timeweb-rs

Async Rust SDK for the Timeweb Cloud API.

The client is generated from the vendor’s own OpenAPI specification, so it covers the whole public API surface — 514 operations across 31 areas: cloud servers, managed databases, Kubernetes, projects, domains, S3 storage, load balancers, firewalls, mail, AI agents, AI Gateway, knowledge bases, floating IPs, VPC, SSH keys, images, dedicated servers, container registry, network drives and more.

Three things make it more than a generated client:

• It is always in sync with the vendor. A scheduled workflow compares the vendored specification with the upstream bundle every week, regenerates the client when the API changes and opens a pull request with the API diff. The SDK never drifts from the API it wraps.
• It parses what the API really sends. The specification and the live API disagree in a few places — nullable fields the API omits, timestamps without a UTC offset, unions the generator renders as empty structs. The generation pipeline repairs those cases, so the documented responses deserialize instead of failing.
• It stays small. Every API area is behind its own Cargo feature, so a consumer that needs one area does not compile the other thousand models.

extern crate tokio;
extern crate timeweb_rs;
use timeweb_rs::apis::servers_api;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = timeweb_rs::authenticated("your-jwt-token");
    let servers = servers_api::get_servers(&config, None, None).await?;
    println!("{servers:#?}");
    Ok(())
}

Where to go next

• Quickstart — install the crate and call the API.
• API reference — every operation, grouped by area.
• Internals — how the generation pipeline works.
• Support — how to support the project.

Quickstart

Install

cargo add timeweb-rs

The crate uses native-tls by default. To use rustls instead:

timeweb-rs = { version = "0.9", default-features = false, features = ["rustls", "full"] }

Every API area is compiled by default. See Feature flags to compile only the areas you need.

Authenticate

The API authenticates with a JWT token issued in the Timeweb Cloud control panel, under the “API и Terraform” section.

extern crate tokio;
extern crate timeweb_rs;
use timeweb_rs::apis::servers_api;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let config = timeweb_rs::authenticated(std::env::var("TIMEWEB_CLOUD_TOKEN")?);

    let servers = servers_api::get_servers(&config, None, None).await?;
    for server in &servers.servers {
        println!("{} ({:?})", server.name, server.status);
    }

    Ok(())
}

authenticated returns a Configuration with a 30 second request timeout. Pass it to any operation — every operation is a free async function in an apis::*_api module and takes the configuration as its first argument.

Call an operation

Path parameters and the request body are ordinary arguments:

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = timeweb_rs::authenticated("your-jwt-token");
use timeweb_rs::{apis::ssh_api, models::AddKeyToServerRequest};

ssh_api::add_key_to_server(
    &config,
    42,
    AddKeyToServerRequest {
        ssh_key_ids: vec![7.0],
    },
)
.await?;
Ok(())
}

Handle the errors

Every operation returns Result<_, apis::Error<T>>, where T is the typed error body of that operation. The uniform envelope of the API is available through ErrorDetails:

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = timeweb_rs::authenticated("your-jwt-token");
use timeweb_rs::{apis::servers_api, ErrorDetails};

match servers_api::get_server(&config, 42).await {
    Ok(server) => println!("{server:#?}"),
    Err(error) => match ErrorDetails::from_api_error(&error) {
        Some(details) => {
            eprintln!("{}: {}", details.status_code, details.messages().join("; "))
        }
        None => eprintln!("{error}"),
    },
}
Ok(())
}

See Error handling for the details.

Use the retries

TimewebClient owns the configuration and re-runs an operation under a RetryPolicy when the API answers 429, 5xx or the transport fails:

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
use timeweb_rs::{apis::servers_api, TimewebClient};

let client = TimewebClient::new(std::env::var("TIMEWEB_CLOUD_TOKEN")?);
let servers = client
    .execute(|| servers_api::get_servers(client.config(), None, None))
    .await?;
println!("{} servers", servers.servers.len());
Ok(())
}

Only wrap idempotent operations: a retried POST that creates a resource may create it twice. See Retries and timeouts.

Feature flags

The crate ships one Cargo feature per API area, named after the area with underscores replaced by dashes:

The full feature turns every area on, and the default features are native-tls and full.

Compile a single area

timeweb-rs = { version = "0.9", default-features = false, features = ["native-tls", "servers"] }

Only the models the servers area uses are compiled — the other thousand models are left out. A model shared by two areas is compiled when either of them is enabled.

Check the names

The list above is generated from the specification. The authoritative list lives in the manifest, and the CI verifies that the manifest and the generated code stay in sync on every pull request.

Error handling

Every operation returns Result<T, apis::Error<E>>, where E is the typed error body of that operation. The four variants of apis::Error say which kind of failure happened:

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = timeweb_rs::authenticated("your-jwt-token");
use timeweb_rs::apis::{servers_api, Error};

match servers_api::get_server(&config, 42).await {
    Ok(server) => println!("{server:#?}"),
    Err(Error::Reqwest(error)) => eprintln!("the request never reached the API: {error}"),
    Err(Error::Serde(error)) => eprintln!("the body was not the expected JSON: {error}"),
    Err(Error::Io(error)) => eprintln!("a local file could not be read: {error}"),
    Err(Error::ResponseError(response)) => {
        eprintln!("the API answered with an error: {}", response.status);
    }
}
Ok(())
}

• Reqwest — the request never reached the API: DNS, TLS, a dropped connection or a timeout.
• Serde — the API answered, but the body is not the expected JSON.
• Io — a local file of a multipart upload could not be read.
• ResponseError — the API answered with a 4xx or 5xx. It carries the status, the raw body, the response headers and the parsed error entity.

The uniform envelope

Timeweb Cloud answers errors with the same envelope: a status code, a machine readable error code, a message that is either a string or a list of strings, and a correlation id. ErrorDetails extracts it from any operation error without naming the per-operation entity:

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = timeweb_rs::authenticated("your-jwt-token");
use timeweb_rs::{apis::servers_api, ErrorDetails};

let error = servers_api::get_server(&config, 42).await.unwrap_err();

if let Some(details) = ErrorDetails::from_api_error(&error) {
    eprintln!("status: {}", details.status_code);
    eprintln!("code:   {}", details.error_code);
    eprintln!("text:   {}", details.messages().join("; "));
    if let Some(id) = &details.response_id {
        eprintln!("id:     {id}"); // quote it in a support ticket
    }
}
Ok(())
}

messages() returns the message of the envelope whatever shape it has — one string or a list.

The typed error

When the operation has a documented error body, it is parsed into the typed entity and reachable through ResponseContent:

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let config = timeweb_rs::authenticated("your-jwt-token");
use timeweb_rs::apis::{servers_api, Error};

let error = servers_api::get_server(&config, 42).await.unwrap_err();

if let Error::ResponseError(response) = error {
    println!("status: {}", response.status);
    if let Some(entity) = &response.entity {
        println!("{entity:#?}");
    }
}
Ok(())
}

The entity is Option: it is None when the body does not match the schema of that operation.

Rate limits and retries

A 429 carries a Retry-After header. The retrying client reads it and waits exactly as long as the API asked. See Retries and timeouts.

Pagination

The list endpoints take a limit and an offset and answer with a meta object that carries the total number of items. paginate turns that into a Stream of items:

extern crate futures_util;
extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
use futures_util::TryStreamExt;
use timeweb_rs::{apis::servers_api, paginate};

let config = timeweb_rs::authenticated("your-jwt-token");

let mut servers = paginate(100, |limit, offset| {
    let config = &config;
    async move {
        let page = servers_api::get_servers(config, Some(limit), Some(offset)).await?;
        Ok(page.servers)
    }
});

while let Some(server) = servers.try_next().await? {
    println!("{}", server.name);
}
Ok(())
}

The closure receives (limit, offset) and returns the items of that page. The stream asks for the next page only when the current one is exhausted, so a large collection never lands in memory at once.

The last request

Offset pagination cannot know that a full page is the last one, so the stream asks for one more page when the total number of items is a multiple of the page size. That last request answers with an empty collection.

Errors

A failed page ends the stream and yields the error:

extern crate futures_util;
extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
use timeweb_rs::{apis::servers_api, paginate};
let config = timeweb_rs::authenticated("your-jwt-token");
use futures_util::TryStreamExt;

let mut servers = paginate(100, |limit, offset| {
    let config = &config;
    async move {
        let page = servers_api::get_servers(config, Some(limit), Some(offset)).await?;
        Ok(page.servers)
    }
});

loop {
    match servers.try_next().await {
        Ok(Some(server)) => println!("{}", server.name),
        Ok(None) => break,
        Err(error) => {
            eprintln!("{error}");
            break;
        }
    }
}
Ok(())
}

The retrying client

paginate does not retry: it is a thin stream over the API. Wrap the fetch closure in the retrying client when the pages should be retried:

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
use timeweb_rs::{apis::servers_api, paginate, TimewebClient};

let client = TimewebClient::new("your-jwt-token");
let retrying = &client;
let mut servers = paginate(100, |limit, offset| {
    async move {
        let page = retrying
            .execute(|| servers_api::get_servers(retrying.config(), Some(limit), Some(offset)))
            .await?;
        Ok(page.servers)
    }
});
let _ = servers;
Ok(())
}

The list operations are idempotent, so retrying them is safe.

Retries and timeouts

The timeout

Every configuration built with authenticated uses an HTTP client with a 30 second timeout, so a stalled connection cannot block a task forever. The timeout is a constant:

#![allow(unused)]
fn main() {
extern crate timeweb_rs;
use std::time::Duration;
use timeweb_rs::DEFAULT_TIMEOUT;

assert_eq!(DEFAULT_TIMEOUT, Duration::from_secs(30));
}

A request that runs into the timeout fails with Error::Reqwest.

Bring your own client when the default does not fit — a proxy, a connection pool or a different timeout:

extern crate reqwest;
extern crate timeweb_rs;
fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = reqwest::Client::builder()
    .timeout(std::time::Duration::from_secs(5))
    .build()?;
let config = timeweb_rs::authenticated_with_client("your-jwt-token", client);
let _ = config;
Ok(())
}

The retry policy

TimewebClient retries an operation when the failure is worth retrying:

• a transport failure — the request never reached the API;
• 429 Too Many Requests;
• any 5xx response.

Every other error is returned immediately. The delay grows exponentially from the base delay, doubles per attempt and is capped by the maximum delay; half of it is random, so the clients of a fleet do not retry in lockstep.

extern crate timeweb_rs;
fn main() {
use std::time::Duration;
use timeweb_rs::{RetryPolicy, TimewebClient};

let policy = RetryPolicy {
    max_retries: 5,
    base_delay:  Duration::from_millis(200),
    max_delay:   Duration::from_secs(10),
};

let client = TimewebClient::new("your-jwt-token").with_policy(policy);
assert_eq!(client.config().base_path, timeweb_rs::DEFAULT_BASE_URL);
}

The default policy retries three times, starting from 500 milliseconds and capping the delay at eight seconds.

Retry-After

A 429 may carry a Retry-After header, either as a number of seconds or as an HTTP date. The client honors it: the delay becomes exactly what the API asked for, capped by the maximum delay of the policy.

Idempotency

Only retry idempotent operations. A POST that creates a resource may reach the API even when the response never arrives, so retrying it can create the resource twice.

execute retries whatever you give it, because the policy is a property of the client, not of the operation. For an operation that is not idempotent, use execute_once:

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
use timeweb_rs::{
    apis::ssh_api,
    models::CreateKeyRequest,
    TimewebClient,
};

let client = TimewebClient::new("your-jwt-token");
let key = client
    .execute_once(|| {
        ssh_api::create_key(
            client.config(),
            CreateKeyRequest {
                name: "deploy".to_owned(),
                body: "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIG…".to_owned(),
                ..CreateKeyRequest::default()
            },
        )
    })
    .await?;
println!("created key {}", key.ssh_key.id);
Ok(())
}

The policy is public

RetryPolicy::delay_for returns the nominal delay of a retry — the delay before the jitter is applied. It is deterministic, which makes it easy to assert on in tests.

AI Gateway

The AI Gateway is a second API surface of Timeweb Cloud with its own host, its own keys and an OpenAI-compatible protocol. It lives at https://api.timeweb.ai, while the rest of the API lives at https://api.timeweb.cloud.

Two areas, two hosts

The management of the keys — listing them, their limits, their usage — is part of the regular Timeweb Cloud API and uses the ordinary configuration. The inference calls talk to the gateway host.

The keys

A gateway key is created in the control panel or with POST /api/v1/cloud-ai/ai-keys, and looks like sk-…. It is not the JWT token of the control panel: the two surfaces have separate credentials.

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
use timeweb_rs::apis::ai_gateway_inference_api;

let config = timeweb_rs::authenticated_ai_gateway("sk-your-key");

let models = ai_gateway_inference_api::get_ai_gateway_models(&config).await?;
println!("{models:#?}");
Ok(())
}

authenticated_ai_gateway builds a configuration for AI_GATEWAY_BASE_URL and sends the key as a bearer token, exactly like the control panel token.

The retrying client

The gateway has its own client, because the base URL differs:

extern crate tokio;
extern crate timeweb_rs;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
use timeweb_rs::{apis::ai_gateway_inference_api, TimewebClient};

let client = TimewebClient::ai_gateway("sk-your-key");
let models = client
    .execute(|| ai_gateway_inference_api::get_ai_gateway_models(client.config()))
    .await?;
println!("{models:#?}");
Ok(())
}

Streaming and multipart

The inference area includes the streaming chat completions and the multipart file uploads of the OpenAI-compatible protocol. The generated operations take the same request and response models as the rest of the SDK, and the file arguments are ordinary paths — the client reads the file and sends it as a part.

API reference

The SDK covers 514 operations across 31 areas of the Timeweb Cloud API. Every area is compiled only when its Cargo feature is enabled, so a consumer that needs one area does not compile the rest. The summaries are quoted from the vendor’s specification.

AI Agent Integrations

Cargo feature: ai-agent-integrations · operations: 18

AI Agent Skills

Cargo feature: ai-agent-skills · operations: 20

AI Agents

Cargo feature: ai-agents · operations: 20

AI Gateway

Cargo feature: ai-gateway · operations: 14

AI Gateway Inference

Cargo feature: ai-gateway-inference · operations: 20

AI Models

Cargo feature: ai-models · operations: 8

AI Solutions

Cargo feature: ai-solutions · operations: 22

Account

Cargo feature: account · operations: 11

Apps

Cargo feature: apps · operations: 22

Balancers

Cargo feature: balancers · operations: 13

CDN

Cargo feature: cdn · operations: 20

Container Registry

Cargo feature: container-registry · operations: 7

Databases

Cargo feature: databases · operations: 40

Dedicated servers

Cargo feature: dedicated-servers · operations: 7

Domains

Cargo feature: domains · operations: 29

Firewall

Cargo feature: firewall · operations: 14

Floating IP

Cargo feature: floating-ip · operations: 7

Images

Cargo feature: images · operations: 10

Knowledge Bases

Cargo feature: knowledge-bases · operations: 19

Kubernetes

Cargo feature: kubernetes · operations: 25

Locations

Cargo feature: locations · operations: 1

MCP

Cargo feature: mcp · operations: 20

Mail

Cargo feature: mail · operations: 14

Network drives

Cargo feature: network-drives · operations: 9

Payments

Cargo feature: payments · operations: 2

Projects

Cargo feature: projects · operations: 25

Routers

Cargo feature: routers · operations: 23

S3

Cargo feature: s3 · operations: 14

SSH

Cargo feature: ssh · operations: 7

Servers

Cargo feature: servers · operations: 46

VPC

Cargo feature: vpc · operations: 7

Architecture

The SDK has three layers. Only the middle one is generated.

The generated layer

src/apis and src/models come out of openapi-generator with the rust generator and the reqwest library. The generator is pinned to a version in openapitools.json, so a regeneration produces the same code.

Every operation is a free async function that takes a Configuration and returns Result<T, Error<E>>. Every model is a serde struct with the constructors the generator emits.

The normalizer

The vendor’s specification is not quite what the generator expects. The normalizer is a set of passes that reconcile it before the generation:

• Path parameters. A parameter declared in: path whose name has no {placeholder} in the route makes the generator emit an unused format argument; a {placeholder} without a declared parameter makes it reference an undefined variable. The passes reconcile the two, and add the missing declarations.
• Tags. Every tag is written in Russian, which the generator cannot turn into Rust module names — all operations would collapse into a single default_api module. The English name of every tag is carried in x-name-i18n, and the passes put it in place.
• Unions. The generator renders a union of a string and a list as an empty struct, and names the variants of a union after the item type, which produces identifiers like ArrayVecstd::collections::HashMap(...). The passes rewrite the shapes the generator cannot render.
• Responses. response_id is a required uuid upstream, while the API returns null on some endpoints; several documented bodies contradict their own schema. The passes relax those schemas.

The normalizer is idempotent: running it twice produces the same document.

The model patcher

The generator follows the specification to the letter, and the live API is more forgiving than the specification. The patcher repairs the difference in the generated models:

• Nullable fields. A nullable property the generator emits as Option<T> with deserialize_with = "Option::deserialize" is still mandatory for serde: a response that omits the field fails with “missing field x”. The patcher adds default, so an absent field deserializes to None while a present null keeps mapping to None.
• Timestamps. The API sends some timestamps without a UTC offset, which the strict chrono::DateTime<FixedOffset> deserializer rejects. The patched fields use the tolerant deserializers of the crate, which accept both shapes.
• The panic. The generated parse_deep_object aborts the process when it is handed a value that is not an object. The patched version returns an empty list.

The hand-written layer

Five small modules carry everything the generator cannot:

A call goes through those modules in a straight line: the client decides whether a failure is worth another attempt, the generated operation builds the request, and reqwest carries it to the API.

The pipeline

The whole generation is reproducible and lives in the xtask crate:

cargo xtask normalize-spec openapi/timeweb-cloud.json /tmp/normalized.json
# … openapi-generator …
cargo xtask layout
cargo xtask feature-gates
cargo xtask patch-models
cargo xtask example-tests
cargo xtask api-index
cargo xtask readme
cargo +nightly fmt --all

The CI checks that the committed code matches the pipeline on every pull request, so a hand edit of the generated code cannot slip through.

The weekly sync

A scheduled workflow compares the vendored specification with the upstream bundle. When the API changes, it regenerates the client, summarizes the API diff with oasdiff, opens a pull request and merges it once CI is green — unless cargo-semver-checks finds breaking changes, in which case the pull request stays open for review.

Support

timeweb-rs is free and open source. If it saved you time, you can say thanks.

Bank transfer

Payment link

Crypto

Double-check the network before sending — funds sent on the wrong network are unrecoverable.

Other ways to help

• Open an issue or a pull request.
• Tell someone about the SDK.