Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/oxidecomputer/oxide.rs
The Oxide Rust SDK and CLI
https://github.com/oxidecomputer/oxide.rs
Last synced: about 2 months ago
JSON representation
The Oxide Rust SDK and CLI
- Host: GitHub
- URL: https://github.com/oxidecomputer/oxide.rs
- Owner: oxidecomputer
- License: mpl-2.0
- Created: 2023-03-04T00:29:44.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2024-05-22T21:26:45.000Z (4 months ago)
- Last Synced: 2024-05-22T22:28:11.010Z (4 months ago)
- Language: Rust
- Homepage:
- Size: 2.22 MB
- Stars: 30
- Watchers: 22
- Forks: 7
- Open Issues: 59
-
Metadata Files:
- Readme: README.adoc
- License: LICENSE
Awesome Lists containing this project
README
# 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 use
https://github.com/oxidecomputer/progenitor[`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
https://github.com/matklad/cargo-xtask['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.