This repo contains two published crates: the Oxide Rust SDK and the Oxide CLI. The SDK and CLI are derived from the Oxide API OpenAPI spec and provide interfaces for interacting with the Oxide Rack.
Both the SDK and CLI rely on
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.
|
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.