sudomateo/oxidecomputer-oxide.rs

The Oxide Rust SDK and CLI

Oxide SDK and CLI

This repo contains the CLI, Rust SDK, and SDK mocking library. The CLI is released as binaries for various operating systens. The SDK and mocking library published to crates.io. All are derived from the Oxide API OpenAPI spec.

Generation

Generation of the CLI, SDK, and mocking library progenitor for code generation from the OpenAPI description of the Oxide API. Typically progenitor is used via a macro or build.rs, here we use an 'xtask`. Not only is the source OpenAPI document checked in, we also check-in the generated code 1. so that changes in generated output (in addition to input) may be easily tracked and 2. so that navigating from rustdoc to source shows the full code rather than, say, an opaque macro invocation (that yields literally tens of thousands of lines of code).

The Oxide OpenAPI description is in oxide.json. To re-generate the CLI and SDK from an updated API document, run cargo xtask generate. CI ensures that the API description and generated code are in sync.

Note	generation requires that a nightly version of rustfmt is installed.

Hand-written code

While both the SDK and CLI are mostly generated, both include some hand- written code as well.

The SDK includes hand-written code to simplify the use of some aspects of the API and to support the CLI. For example, it includes a clap-related impl block so that the ByteCount type can be specified with a binary suffix (e.g. 64gb).

The CLI includes hand-written code for some of the blocking and tackling. It also has hand-written code to add additional subcommands (e.g. auth) and to augment commands that cannot be fully or optimally generated.

Releasing a new version

There are several steps to releasing a new version.

Determine the version number

The CLI, SDK, and mocking library all carry the same version number which follows this pattern:

MAJOR.MINOR.PATCH+API_VERSION

The version number is incremented according to semver. This means that both API incompatibilities and generation incompatibilities need to be taken into account. The version of the API appears as, effectively, a comment suffix. This allows users to reasonably recognize the proper version for the version of the Oxide API currently deployed in their environment.

Update Cargo.toml files

Update Cargo.toml for the workspace, CLI, SDK, and mocking library. Commit changes.

Publish crates

Use cargo publish -p oxide and cargo publish -p oxide-httpmock.

Release the CLI

Tag the repo with the version number (vMAJOR.MINOR.PATCH+API_VERSION) and push change and tags. This will kick off the cargo-dist workflow to generate a release with binaries.