timeweb-rs 0.1.2

Async Rust SDK for the Timeweb Cloud API
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109

# timeweb-rs

[![crates.io](https://img.shields.io/crates/v/timeweb-rs.svg)](https://crates.io/crates/timeweb-rs)
[![docs.rs](https://img.shields.io/docsrs/timeweb-rs)](https://docs.rs/timeweb-rs)
[![CI](https://github.com/RAprogramm/timeweb-rs/actions/workflows/ci.yml/badge.svg)](https://github.com/RAprogramm/timeweb-rs/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/RAprogramm/timeweb-rs/graph/badge.svg?token=iKNwLuK8au)](https://codecov.io/gh/RAprogramm/timeweb-rs)
[![MSRV](https://img.shields.io/badge/MSRV-1.95-blue.svg)](https://www.rust-lang.org)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

Async Rust SDK for the [Timeweb Cloud](https://timeweb.cloud/?i=137383) API.

## Overview

`timeweb-rs` covers the full Timeweb Cloud public API — **313 operations across
22 areas**: cloud servers, managed databases, Kubernetes, projects, domains,
S3 storage, load balancers, firewalls, mail, AI agents, knowledge bases,
floating IPs, VPC, SSH keys, images, dedicated servers, container registry,
network drives and more.

The `apis` and `models` modules are generated from the official Timeweb Cloud
OpenAPI specification with [`openapi-generator`](https://openapi-generator.tech)
(the same tool behind the official Go, Python, PHP and Java SDKs). A thin
hand-written layer adds an idiomatic authenticated-client constructor. The
generated code is committed to the repository, so building the crate needs no
code generation step and no extra build dependencies.

## Installation

```sh
cargo add timeweb-rs
```

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

```toml
timeweb-rs = { version = "0.1", default-features = false, features = ["rustls"] }
```

## Usage

Authentication uses a JWT token issued in the Timeweb Cloud control panel under
the "API и Terraform" section.

```rust
use timeweb_rs::apis::servers_api;

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

    let servers = servers_api::get_servers(&config, None, None).await?;
    println!("{servers:#?}");

    Ok(())
}
```

Every operation is a free async function in an `apis::*_api` module and takes a
reference to [`apis::configuration::Configuration`] as its first argument.
Build that configuration with `timeweb_rs::authenticated`.

## API coverage

One module per API area: `account_api`, `ai_agents_api`, `apps_api`,
`balancers_api`, `container_registry_api`, `databases_api`,
`dedicated_servers_api`, `domains_api`, `firewall_api`, `floating_ip_api`,
`images_api`, `knowledge_bases_api`, `kubernetes_api`, `locations_api`,
`mail_api`, `network_drives_api`, `payments_api`, `projects_api`, `s3_api`,
`servers_api`, `ssh_api`, `vpc_api`.

## Regenerating from the spec

The generated code is committed. To refresh it after an upstream API update:

1. Download the latest spec:
   ```sh
   curl -o openapi/timeweb-cloud.json https://timeweb.cloud/api-docs-data/bundle.json
   ```
2. Normalize it:
   ```sh
   python3 openapi/normalize_spec.py openapi/timeweb-cloud.json /tmp/normalized.json
   ```
3. Generate the client:
   ```sh
   npx @openapitools/openapi-generator-cli generate \
       -i /tmp/normalized.json -g rust -o /tmp/twgen \
       -p packageName=timeweb_client,library=reqwest
   ```
4. Replace `src/apis` and `src/models` with the freshly generated directories.

`openapi/normalize_spec.py` is a small, documented pre-processor: it reconciles
path parameters with their route templates (the upstream spec has a few
mismatches that produce non-compiling code) and swaps the Russian API tags for
the English names the spec already carries in `x-name-i18n`. Request and
response schemas are left untouched.

## Releases

This project follows [Semantic Versioning](https://semver.org); changes are
recorded in [CHANGELOG.md](CHANGELOG.md). To cut a release: move the
`Unreleased` changelog section under a new version heading, bump `version` in
`Cargo.toml`, commit, and push a `vX.Y.Z` tag. CI publishes the crate to
crates.io once the version is ahead of the registry, and the release workflow
creates the matching GitHub release from the changelog entry.

## License

[MIT](LICENSE)