Introduction
honig turns an OpenAPI description into typed Rust clients and servers.
It is meant for spec-first workflow and catches drift from the OpenAPI description at compile time.
It supports OpenAPI 3.2 and earlier, focusing on both correctness and runtime performance.
Installing
honig installs as a pre-built binary with cargo-binstall:
cargo binstall cargo-honig
In CI and in a team, install one version everywhere. Two versions of the generator write different code and a different honig dependency:
cargo binstall cargo-honig@x.y.z
Updating
Install the new generator, then generate again:
cargo binstall cargo-honig
cargo honig generate
generate moves the honig dependency to the version of the generator. The two always match: the generated code calls runtime internals that change between versions.
A bot such as Renovate or Dependabot bumps honig alone, without the generator, so the generated code no longer matches. Turn it off for honig. In renovate.json:
{
"packageRules": [{ "matchPackageNames": ["honig"], "enabled": false }]
}
Getting started
Two commands add honig to your crate:
cargo honig init path/to/openapi.yaml
cargo honig generate
init adds the [package.metadata.honig.api] section and the honig dependency to your Cargo.toml.
generate writes the module to src/api and toggles honig features as needed by the generated code.
Then you can declare the module in src/lib.rs or src/main.rs:
pub mod api;
Recipes builds a server and a client from an example description, then whole setups around them.
Update the API
cargo honig generate updates the module after every change to the description.
Every place your code must change becomes a compile error: a new operation is a missing method, a new response is a missing match arm.
Run cargo honig check in CI to assert that the module is up to date with the description or the generator.
Recipes
Each recipe is a whole setup that combines the pieces of the other pages. Each one is a test, so it matches the code.
Web server and CLI client
The examples/shop crate runs a server and a client for a small catalog of products against each other. Every example in this book is a test that runs on each change. So each example matches the code.
Its src/api is what cargo honig generate writes. Its src/supplier is a second module, a client for a book supplier: see Several APIs in one crate.
The description is openapi.yaml:
openapi: 3.2.0
info:
title: Catalog
version: 1.0.0
servers:
- url: https://shop.example.com/v1
security:
- apiKey: []
paths:
/products:
get:
operationId: listProducts
parameters:
- name: limit
in: query
schema: {type: integer, format: int32, maximum: 100}
- name: tags
in: query
style: form
explode: false
schema: {type: array, items: {type: string}}
responses:
'200':
description: A page of products
headers:
X-Next: {schema: {type: string}}
content:
application/json:
schema: {type: array, items: {$ref: '#/components/schemas/Product'}}
default:
description: Error
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
post:
operationId: createProduct
requestBody:
required: true
content:
application/json:
schema: {$ref: '#/components/schemas/Product'}
responses:
'201':
description: Created
content:
application/json:
schema: {$ref: '#/components/schemas/Product'}
default:
description: Error
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
/products/{productId}:
get:
operationId: getProduct
parameters:
- name: productId
in: path
required: true
schema: {type: integer, format: int64}
responses:
'200':
description: A product
content:
application/json:
schema: {$ref: '#/components/schemas/Product'}
'404':
description: Not found
content:
application/json:
schema: {$ref: '#/components/schemas/Error'}
components:
securitySchemes:
apiKey: {type: apiKey, in: header, name: X-API-Key}
schemas:
Product:
oneOf:
- $ref: '#/components/schemas/Physical'
- $ref: '#/components/schemas/Digital'
discriminator:
propertyName: kind
mapping:
physical: '#/components/schemas/Physical'
digital: '#/components/schemas/Digital'
# Each branch fixes its tag, so a value matches exactly one: `oneOf` holds whatever the discriminator says.
Physical:
type: object
required: [kind, name]
properties:
kind: {const: physical}
name: {type: string}
fragile: {type: boolean}
sku: {type: string, pattern: '^[A-Z]{3}-[0-9]{4}$', description: Stock keeping unit}
Digital:
type: object
required: [kind, name]
properties:
kind: {const: digital}
name: {type: string}
downloads: {type: [integer, "null"], format: int32}
Error:
type: object
required: [code, message]
properties:
code: {type: integer, format: int32}
message: {type: string}
Server
The server implements the generated Api trait, which has one method per operation:
/// The catalog in memory. The ID of a product is its index.
#[derive(Default)]
pub struct Catalog(Mutex<Vec<types::Product>>);
impl Catalog {
fn products(&self) -> Result<MutexGuard<'_, Vec<types::Product>>, api::ApiError> {
self.0
.lock()
.map_err(|_| api::ApiError::new(api::http::StatusCode::INTERNAL_SERVER_ERROR, "catalog lock poisoned"))
}
}
impl api::Api for Catalog {
type Principal = ();
async fn list_products(
&self,
params: ops::list_products::Params,
_: &api::Context<'_>,
) -> Result<ops::list_products::Response, api::ApiError> {
let limit = params.limit.and_then(|n| usize::try_from(n).ok()).unwrap_or(usize::MAX);
let body = self.products()?.iter().take(limit).cloned().collect();
Ok(ops::list_products::Response::Ok { body, x_next: None })
}
async fn create_product(
&self,
params: ops::create_product::Params,
_: &api::Context<'_>,
) -> Result<ops::create_product::Response, api::ApiError> {
self.products()?.push(params.body.clone());
Ok(ops::create_product::Response::Created(params.body))
}
async fn get_product(
&self,
params: ops::get_product::Params,
_: &api::Context<'_>,
) -> Result<ops::get_product::Response, api::ApiError> {
let found = usize::try_from(params.product_id).ok().and_then(|i| self.products().ok()?.get(i).cloned());
Ok(match found {
Some(product) => ops::get_product::Response::Ok(product),
None => ops::get_product::Response::NotFound(types::Error::new(404, "no such product".to_owned())),
})
}
}
Serve it with axum in src/main.rs:
async fn serve(addr: &str) -> std::io::Result<()> {
let listener = tokio::net::TcpListener::bind(addr).await?;
println!("serving the catalog on http://{addr}/v1");
let app = api::Server::new(Catalog::default())
// One JSON line per request: the operation, the status, the duration, the body sizes and more.
.on_event(|event: &api::RequestEvent| println!("{}", event.to_json()))
.into_axum();
axum::serve(listener, app).await
}
Client
The client has one method per operation. Each returns one variant per documented response:
async fn create_and_read(base_url: &str, product: types::Product) -> Result<types::Product, api::Error> {
let client = api::Client::new(api::ReqwestTransport::new(base_url)).with_api_key("secret");
client.create_product(ops::create_product::Params::new(product)).await?;
match client.get_product(ops::get_product::Params::new(0)).await? {
ops::get_product::Response::Ok(product) => Ok(product),
ops::get_product::Response::NotFound(error) => panic!("{}", error.message),
}
}
API server and SPA
A single-page app and its API share one port. Unknown paths under the API’s base path still get the API’s 404 in its error schema, so a client never receives the app’s HTML by mistake. rust-embed compiles the app’s folder into the binary, so the server ships as one file:
/// A web app and its API on one port. The API lives under its base path `/v1`, so an unknown `/v1/...` path gets a
/// `404` in the error schema. Every other path serves the app: a file of `dist` or else its `index.html`, so that the
/// app's own router handles the path. `dist` is compiled into the binary, so the server ships as one file.
#[derive(rust_embed::Embed)]
#[folder = "tests/v32_catalog/dist"]
struct Dist;
async fn app(uri: axum::http::Uri) -> axum::response::Response {
use axum::response::IntoResponse;
let path = uri.path().trim_start_matches('/');
match Dist::get(path).or_else(|| Dist::get("index.html")) {
Some(file) => {
([(axum::http::header::CONTENT_TYPE, file.metadata.mimetype().to_owned())], file.data).into_response()
}
None => axum::http::StatusCode::NOT_FOUND.into_response(),
}
}
fn web_app() -> axum::Router {
let api = api::Server::new(Catalog::default()).into_service();
axum::Router::new().nest_service("/v1", api).fallback(app)
}
Claims from an auth layer you already run
A JWT or session layer that you already run puts its claims in the request’s extensions. authenticate maps them to the principal of your Api:
/// What an auth layer that you already run puts in the extensions, such as the claims of a JWT. Its fields are its
/// own, not your principal.
#[derive(Clone)]
struct Claims {
sub: String,
}
/// A stand-in for that layer: it trusts `Authorization: Bearer <sub>`. A real one checks a signature.
fn claims_layer(mut req: axum::extract::Request) -> axum::extract::Request {
let sub = req.headers().get("authorization").and_then(|v| v.to_str().ok()?.strip_prefix("Bearer "));
if let Some(sub) = sub.map(str::to_owned) {
req.extensions_mut().insert(Claims { sub });
}
req
}
/// `authenticate` maps the claims to the principal of the `Api`. A request without claims is anonymous.
fn with_claims() -> axum::Router {
api::Server::new(super::auth::Server)
.authenticate(|req: &api::Request| {
let who = req.extensions().get::<Claims>().map(|claims| claims.sub.clone());
std::future::ready(Ok(who))
})
.into_axum()
.layer(tower::util::MapRequestLayer::new(claims_layer))
}
Errors of layers outside the server
A layer outside the server answers in its own format. Its answers go out in the error schema when they pass through errors(). Layers shows a fallback that does this. A layer that fails with an error, such as a timeout or a full queue, goes through axum’s HandleErrorLayer:
/// Layers outside the server that fail with an error, such as a timeout or a full queue. axum turns such an error
/// into a response with `HandleErrorLayer`. `errors()` renders it in the error schema of the description, so a
/// client decodes it as its typed error.
fn guarded(max_in_flight: usize) -> axum::Router {
let server = api::Server::new(Catalog::default());
let errors = server.errors();
server.into_axum().layer(
tower::ServiceBuilder::new()
.layer(axum::error_handling::HandleErrorLayer::new(move |e: tower::BoxError| {
let status = if e.is::<tower::timeout::error::Elapsed>() {
api::http::StatusCode::GATEWAY_TIMEOUT
} else {
api::http::StatusCode::SERVICE_UNAVAILABLE
};
std::future::ready(errors.response(status, e.to_string()))
}))
.load_shed()
.concurrency_limit(max_in_flight)
.timeout(Duration::from_secs(30)),
)
}
Middlewares
Layers outside the server, authenticate and layers inside it, in the order that a request passes them:
/// Every kind of layer in one server. A request passes them top to bottom.
fn full_stack() -> axum::Router {
api::Server::new(super::auth::Server)
// Inside the server, after routing and the check of the credentials that the description asks for. Their
// errors go out in the error schema.
.operation_layer(tower::timeout::TimeoutLayer::new(Duration::from_secs(10)))
.authenticate(|req: &api::Request| {
std::future::ready(Ok(req.extensions().get::<Claims>().map(|claims| claims.sub.clone())))
})
// After `authenticate`: this layer sees the principal.
.operation_layer(tower::filter::AsyncFilterLayer::new(|req: api::Request| {
let blocked = req.extensions().get::<String>().is_some_and(|who| who == "mallory");
let refusal = api::ApiError::new(api::http::StatusCode::FORBIDDEN, "blocked");
std::future::ready(if blocked { Err(refusal) } else { Ok(req) })
}))
.into_axum()
// Outside the server, on every request before routing. The last one added runs first.
.layer(tower::util::MapRequestLayer::new(claims_layer))
.layer(tower_http::cors::CorsLayer::permissive())
}
WebSockets
OpenAPI cannot describe a WebSocket. So honig generates nothing for one. Serve it as a plain axum route next to the generated routes. Share state through your own Arc:
/// The API of the catalog and a WebSocket route that the description does not declare. It answers each message with
/// how many products the catalog holds.
fn with_live_updates() -> axum::Router {
let catalog = Arc::new(Catalog::default());
let live = {
let catalog = Arc::clone(&catalog);
move |ws: WebSocketUpgrade| async move { ws.on_upgrade(move |socket| count_products(socket, catalog)) }
};
api::Server::new(catalog).into_axum().route("/v1/live", axum::routing::get(live))
}
async fn count_products(mut socket: WebSocket, catalog: Arc<Catalog>) {
while let Some(Ok(Message::Text(_))) = socket.recv().await {
let count = catalog.products().map_or(0, |products| products.len());
if socket.send(Message::Text(count.to_string().into())).await.is_err() {
break;
}
}
}
Command line
The command line has six commands. cargo honig --help lists them:
cargo honig: OpenAPI 3.2 to a Rust client and server
Usage: cargo honig [OPTIONS] <COMMAND>
Commands:
init Add the module `api` to Cargo.toml and the `honig` dependency with your adapters
generate Generate the modules set in Cargo.toml files
check Fail if a module is stale
validate Validate under its own OpenAPI version and print diagnostics
upgrade Print the document upgraded to OpenAPI 3.2 JSON
bundle Print a description split over files as one document, in its own OpenAPI version
help Print this message or the help of the given subcommand(s)
Options:
--manifest-path <PATH> Cargo.toml to use [default: Cargo.toml]
-q, --quiet Only print errors
-h, --help Print help
-V, --version Print version
SETTINGS ([package.metadata.honig.<module>] in Cargo.toml): spec, output, client, server, tests, unknown_fields, overlays, formats, derives
The Settings page of the book explains each one: https://alphajack.github.io/honig/settings.html
Check a description
validate reads a description under its own version and prints what is wrong. It exits with 1 on an error.
$ cargo honig validate openapi.yaml
ok: openapi.yaml
$ cargo honig validate broken.yaml
error: /info: missing field `version`
Each diagnostic starts with a JSON pointer into the document.
See what honig reads
upgrade prints the document as honig generates from it: OpenAPI 3.2 JSON.
Run it to see what a Swagger 2.0 or 3.0 description becomes before you generate.
cargo honig upgrade swagger.yaml > openapi.json
Upgrading lists what changes on the way.
Merge a description split over files
bundle prints one document. Each $ref to another file becomes a component, named after the file.
The version stays the one the description is written in.
cargo honig bundle openapi.yaml > bundled.json
A $ref: order.yaml becomes $ref: '#/components/schemas/order'. Component names and $refs stay, so other tools such as TypeScript generators and API reference pages read the same document. --format yaml prints it as YAML.
Upgrading
honig generates from OpenAPI 3.2 only. A 2.0, 3.0 or 3.1 description is upgraded one version at a time: 2.0 to 3.0, 3.0 to 3.1, then 3.1 to 3.2.
Run cargo honig upgrade to see the result.
Most of a description carries over unchanged. Each change below prints a warning that points at the field.
cargo honig generate prints them unless you pass --quiet.
Swagger 2.0
Swagger 2.0 to OpenAPI 3.0.
| 2.0 | Becomes |
|---|---|
host, basePath, schemes | servers |
definitions, parameters, responses, securityDefinitions | components, with every $ref rewritten |
body and formData parameters | requestBody, one entry per consumes media type |
a response schema | content, one entry per produces media type |
| inline type keywords of other parameters and headers | their schema |
collectionFormat | style and explode |
collectionFormat: tsv | x-collection-format: tsv: 3.x has no tab style, but honig still encodes it |
type: file | type: string with format: binary |
x-nullable | nullable |
What is lost:
- An unknown
collectionFormatis read ascsv. - An unknown
OAuth2flowis read asimplicit. - A security scheme of an unknown
typeis kept as written. Generated code does not use it.
OpenAPI 3.0
OpenAPI 3.0 to 3.1. Schemas move from the 3.0 dialect to JSON Schema 2020-12.
| 3.0 | Becomes |
|---|---|
nullable: true | "null" in type, in enum or in an anyOf branch |
boolean exclusiveMinimum and exclusiveMaximum | their numeric form |
example in a schema | examples: [example] |
x-jsonschema-* extensions | the JSON Schema keywords they carry |
x-oai-license-identifier | the license identifier |
What is lost:
allowEmptyValueandallowReservedon a header. 3.0 allowed them there without effect. 3.1 has neither.- A registered extension whose field is also set. The field wins.
OpenAPI 3.1
OpenAPI 3.1 to 3.2.
| 3.1 | Becomes |
|---|---|
array-form items (JSON Schema 2019-09 and older) | prefixItems |
| an object where an array is required | an array of its values |
xml.attribute and xml.wrapped | xml.nodeType. With both, attribute wins |
x-tagGroups | tags[].parent, only when the mapping is unambiguous |
registered x-oai-* extensions | the 3.2 fields they carry: $self, additionalOperations, itemSchema, itemEncoding, prefixEncoding, encoding, dataValue, serializedValue, the name of a server, the summary of a response and the deprecated and device authorization flow of a security scheme |
What is lost:
allowReservedon a parameter that is not in the query. It was inactive in 3.1 and would change meaning in 3.2.
Settings
cargo honig init openapi.yaml writes the module api with the settings that most crates change. Here the crate depends on reqwest and uuid:
[dependencies]
honig = { version = "=0.0.1", features = ["simd"] }
[package.metadata.honig.api]
spec = "openapi.yaml"
client = { adapters = ["reqwest"] }
server = true
formats = { uuid = true }
Each table [package.metadata.honig.<module>] is one module and sets what is generated into it. These are all its settings:
| Setting | Required | Default | What it does |
|---|---|---|---|
spec | yes | the description relative to Cargo.toml; a list [“a.yaml”, “api/*.yaml”] merges several | |
output | no | "src/<module>" | the module directory |
client | no | true | generate the client; a table sets its adapters = [“reqwest”] and operations = [“getOrder”] |
server | no | true | generate the server; a table sets its adapters = [“axum”] and allow_unimplemented = true |
tests | no | false | generate a test that the description’s examples decode |
unknown_fields | no | "drop" | “keep”: objects without additionalProperties keep unknown keys |
overlays | no | [] | Overlays (1.0 to 1.2) applied in order to the spec |
formats | no | the dependencies | library types of string formats, like { uuid = true, dates = “chrono” } |
derives | no | {} | extra derives on every type or on one type by Rust name, like { “*” = [“Hash”] } |
Client and server
client and server are each true, false or a table that turns the half on with settings of its own:
| Value | What is generated | Runtime features |
|---|---|---|
client = false | no client | none for the client |
client = true | the client; you bring a transport of your own | client |
client = { adapters = ["reqwest"] } | the client and ReqwestTransport | client, reqwest |
client = { adapters = ["reqwest"], operations = ["getOrder"] } | the client with one operation | client, reqwest |
server = { adapters = ["axum", "tracing"] } | the server, into_axum and a span per request | server, axum, tracing |
server = { allow_unimplemented = true } | the server; a method you do not write answers 501 | server |
An adapter serves one half, and tracing-opentelemetry serves both. Each adapter needs its library in [dependencies]. Adapters lists them all.
Several root documents
Some APIs describe themselves in many complete documents. Matrix has one per area. List them, with * for the files of a directory:
[package.metadata.honig.api]
spec = ["matrix/client-server/*.yaml"]
Each file is bundled against its own directory and upgraded to 3.2 alone. Then paths, webhooks, components and tags merge into one module.
- Files whose one server differs only in its path share the host. Each file’s base path moves into its paths (
/loginunder/_matrix/client/v3is/_matrix/client/v3/login). The client’s base URL then serves every operation. - Files on different hosts keep their servers on their path items.
- One method of one path in two files is an error. So is one component name with two different values.
Overlays apply to the merged document.
Overlays
Overlays fix a description that you do not own without editing it. List Overlays here. They apply in order to the description as written. This happens before $refs are bundled.
[package.metadata.honig.api]
spec = "vendor/openapi.yaml"
overlays = ["public.overlay.yaml"]
overlay: 1.2.0
info: {title: Public operations, version: "1"}
actions:
- target: $.paths['/internal']
remove: true
- target: $.paths['/products'].get
update: {operationId: listProducts}
honig reads Overlay 1.0 to 1.2 with every action. That is update, remove, copy and the reusable actions under components.actions. Targets are RFC 9535 JSONPath.
honig reports a broken action with its index and skips it. The others still apply. cargo honig check reads the overlays too. A changed overlay makes the module stale.
Several APIs in one crate
A crate often serves its own API and calls others. Add a table per module:
[package.metadata.honig.api]
spec = "own.yaml"
client = false
[package.metadata.honig.billing]
spec = "vendor/billing.yaml"
server = false
client = { operations = ["createInvoice", "getInvoice"] }
Then declare each module: mod api; and mod billing;.
- The table name is the module name. It must be a Rust identifier and not a keyword.
- The generated code of a module depends only on its description and its table.
- The runtime features are the union of what every module needs. One module with XML bodies turns on
xmlfor the crate. - Each module holds its own types. Identical schemas in two descriptions are two types, so the APIs can change apart. Convert between them with
Fromimpls.
cargo honig generate writes every module. cargo honig generate billing writes one, and Cargo.toml keeps the features of all of them. check and validate take a module name the same way.
Workspaces
Each member keeps its own [package.metadata.honig.<module>]. Run the commands in the member, or at the workspace root:
cargo honig generateat a virtual workspace root runs for every member with module tables.checkdoes too.cargo honig generate -p shopruns for the membershoponly.cargo honig generate billingruns for each member with the modulebilling.- A member with
honig = { workspace = true }lists its features.generatepins the version in the root’s[workspace.dependencies].
Types
Request and response types
A schema with readOnly or writeOnly properties becomes two types:
| Type | Used for | Fields |
|---|---|---|
Login | responses | token (readOnly). No password. |
LoginRequest | request bodies and parameters | password (writeOnly). No token. |
Each is required in Rust where the schema requires it. A missing password is a compile error and not a runtime check. Types that contain one split too. An example is Session and SessionRequest.
Every struct has new. It takes the required properties in document order. A property with a default starts at it. Any other optional property starts empty:
let lamp = types::Physical { fragile: Some(true), ..types::Physical::new(types::PhysicalKind, "Desk lamp".into()) };
A property added to the description as required becomes an argument. Code that builds the type stops compiling until it sets it.
A property that is optional and nullable is api::Nullable<T>. Its variants are Absent, Null and Value(T). This is how a PATCH body tells “leave it” from “clear it”. A property that is only one of required or nullable is Option<T>.
A const is a unit struct that only decodes its value. Arrays with minItems == maxItems are [T; N]. The formats int8 to uint16 are the Rust integers of the same width.
Conditional schemas
if/then blocks that test one property against constants become an enum. It is like a discriminated oneOf:
Notify:
type: object
properties: {type: {type: string}}
allOf:
- {if: {properties: {type: {const: email}}}, then: {required: [email], properties: {email: {type: string}}}}
- {if: {properties: {type: {const: sms}}}, then: {required: [phone], properties: {phone: {type: string}}}}
This gives enum Notify { Email(NotifyEmail), Sms(NotifySms), Otherwise(NotifyOtherwise), Other(Value) }. NotifyEmail has email: String as required.
Otherwiseholds every other value. Its type has the base properties.- A lone
if/then/elsebecomes the same kind of enum.elseis theOtherwisevariant.else: falseleaves none. - An
ifonenum: [email, mail]gives one variant for both values:EmailOrMail. - Conditions that cannot be typed, such as ranges or
not, are still enforced. The server checks them on every request.
$dynamicRef generics are monomorphized. ProductPage: {$ref: Page, $defs: {item: {$dynamicAnchor: item, $ref: Product}}} becomes a struct with items: Vec<Product>. A recursive Tree<T> bound to string becomes StringTree { value: String, children: Vec<StringTree> }.
Your own derives and types
Generated types take extra derives. Use "*" for all types or the Rust name of one type:
[package.metadata.honig.api.derives]
"*" = ["Hash"]
Order = ["sqlx::FromRow"]
Derives the generator already emits are skipped. String enums carry an Other(String) variant for unknown values. So derives that need unit-only enums do not fit them. Examples are sqlx::Type and Copy.
Put x-rust-type on the schema to reuse a type that you already have. honig then generates no type for it:
Money:
x-rust-type: crate::domain::Money
type: object
...
types::Money becomes an alias of your type. It must serialize like the schema. It must implement Debug, Clone, PartialEq and the serde traits. It must also check the constraints of the schema.
A type from another crate takes typify’s object form, which Oxide’s description uses:
SledUuid:
type: string
format: uuid
x-rust-type: {crate: omicron-uuid-kinds, version: "*", path: omicron_uuid_kinds::SledUuid}
honig uses it only when your crate depends on that crate. Otherwise it warns and generates the type.
String formats
The formats table picks the library type of each string format:
[package.metadata.honig.api]
formats = { uuid = true, dates = "chrono", url = true, ipnet = true }
dates is "chrono", "jiff" or "string". Each library named must be a dependency with its serde feature. cargo honig init writes the table from the dependencies the crate has then.
Without the table the dependencies decide: a library with its serde feature gives its type. A dependency added later then changes field types, so generate warns and prints the line that keeps the current types. It also warns when one of these libraries does not have its serde feature, and when both chrono and jiff are there. Dates then use chrono.
| Format | Without its library | With uuid, url, ipnet and chrono | With jiff in place of chrono |
|---|---|---|---|
uuid | String | uuid::Uuid | uuid::Uuid |
date-time | String | chrono::DateTime<chrono::Utc> | jiff::Timestamp |
date | String | chrono::NaiveDate | jiff::civil::Date |
ipv4 | std::net::Ipv4Addr | std::net::Ipv4Addr | std::net::Ipv4Addr |
ipv6 | std::net::Ipv6Addr | std::net::Ipv6Addr | std::net::Ipv6Addr |
time | String | chrono::NaiveTime | jiff::civil::Time |
base64url | api::Base64Url | api::Base64Url | api::Base64Url |
decimal | String | String | String |
char | char | char | char |
date-time-local | String | chrono::NaiveDateTime | jiff::civil::DateTime |
time-local | String | chrono::NaiveTime | jiff::civil::Time |
uri | String | url::Url | url::Url |
ipv4-cidr | String | ipnet::Ipv4Net | ipnet::Ipv4Net |
ipv6-cidr | String | ipnet::Ipv6Net | ipnet::Ipv6Net |
email | api::Email | api::Email | api::Email |
idn-email | api::IdnEmail | api::IdnEmail | api::IdnEmail |
hostname | api::Hostname | api::Hostname | api::Hostname |
idn-hostname | api::IdnHostname | api::IdnHostname | api::IdnHostname |
http-date | String | String | String |
duration | String | String | String |
uri-reference | String | String | String |
iri | String | String | String |
iri-reference | String | String | String |
json-pointer | String | String | String |
relative-json-pointer | String | String | String |
regex | String | String | String |
uri-template | String | String | String |
A format without its library is a String. The server checks its text on every request as the library would on parsing. generate turns on the runtime feature that each check needs. Adapters lists the features.
Mail addresses and host names are types of the runtime. Only a valid value can be one of them. try_from and decoding check the value. They need the idn feature of the runtime. generate turns it on when the description uses them:
let to = e2e::v32_catalog::api::Email::try_from("ann@example.com")?;
assert!(e2e::v32_catalog::api::Email::try_from("ann").is_err());
println!("{}", to.as_str());
| Format | Type | Accepts |
|---|---|---|
email | api::Email | An RFC 5321 mail address (format: email). It is an ASCII dot-atom or quoted local part, then @, then a host name or an address literal. |
idn-email | api::IdnEmail | An RFC 6531 mail address (format: idn-email): an Email that may hold UTF-8. |
hostname | api::Hostname | An RFC 1123 host name (format: hostname) with ASCII labels. A punycode label must decode to a valid name. |
idn-hostname | api::IdnHostname | An IDNA2008 host name (format: idn-hostname): a Hostname whose labels may be Unicode. |
http-date is a String checked as one of the three forms of RFC 9110 section 5.6.7. duration is a String checked as an ISO 8601 duration of RFC 3339 Appendix A. No std type holds P1M: a month has no fixed length. uri-reference, iri, iri-reference, json-pointer, relative-json-pointer, uri-template and regex are Strings checked by their grammars (RFC 3986, 3987, 6901, 6570 and ECMA-262). uuid without its library takes only the hyphenated form of RFC 9562.
contentEncoding: base64url gives api::Base64Url. It holds bytes in the URL-safe alphabet.
{type: number, format: decimal} and decimal128 are api::Decimal. It keeps the digits of the number. 12345678901234567.89 arrives and leaves as written. An f64 would round it.
It reads the exact text wherever the number is. This includes oneOf branches. It rounds only in the Other of a union. That variant holds a value that no branch takes as a serde_json::Value.
For arithmetic parse its digits into a decimal type with d.as_str().parse::<rust_decimal::Decimal>().
{type: string, format: decimal} is a String with every digit. The server checks it as a decimal. Use it past the 28 significant digits that rust_decimal holds.
JSON the description leaves untyped is a serde_json::Value:
- the properties that an object does not declare with
unknown_fields = "keep" - a
{}schema and an untypedadditionalProperties - the
Otherof a union
A number in such a value rounds when it is past u64. It also rounds when it has more significant digits than an f64 holds, which is about 17. RFC 8259 section 6 allows this. A client that reads such an object and writes it back can change that number. To keep a number exact declare it with format: decimal.
A string with a pattern is a type of its own. Only valid values can be that type. The regress feature of the runtime checks it. generate turns the feature on when the description uses pattern:
let sku = types::PhysicalSku::try_from("LMP-0042")?; // checks `^[A-Z]{3}-[0-9]{4}$`
assert!(types::PhysicalSku::try_from("lamp").is_err());
println!("{}", sku.as_str());
Decoding checks in the same way. So a request with a bad value gets 400.
Client
Each operation of the description is a method of the generated Client. It takes a Params with one field per parameter and returns one variant per documented response:
async fn create_and_read(base_url: &str, product: types::Product) -> Result<types::Product, api::Error> {
let client = api::Client::new(api::ReqwestTransport::new(base_url)).with_api_key("secret");
client.create_product(ops::create_product::Params::new(product)).await?;
match client.get_product(ops::get_product::Params::new(0)).await? {
ops::get_product::Response::Ok(product) => Ok(product),
ops::get_product::Response::NotFound(error) => panic!("{}", error.message),
}
}
Params::new takes the path parameters in URL order. Then it takes the other required parameters and then a required body. The URL fixes the argument order. So a reordered description cannot swap two arguments silently. With no arguments Params::default() is the same value.
A method takes its Params or a reference to them. So ¶ms keeps them for a retry. JSON, XML, form and multipart bodies are encoded from the reference with no copy.
Each security scheme gets its own setter with its name, such as with_api_key or with_bearer_auth. A misspelt scheme is a compile error.
Response media type
An operation whose success responses come in several media types has a media in its Params. The client prefers it in Accept and lists the others after it at q=0.9. A server whose answer depends on the resource then sends one the client decodes and not 406:
/// One product as XML from an operation that answers in JSON unless asked otherwise.
async fn product_as_xml(client: &api::Client<impl api::Transport>) -> Result<ops::get_product::Response, api::Error> {
let params = ops::get_product::Params { media: ops::get_product::Media::Xml, ..ops::get_product::Params::new(7) };
client.get_product(params).await
}
Links and callbacks
Response links become typed structs that fill the parameters of the linked operation:
let request = ops::create_product::Params { body: None, ..Default::default() };
let body = serde_json::json!({"id": 7, "name": "Desk lamp"});
let update = ops::create_product::links::UpdateProduct::new(&request, &body);
assert_eq!(update.product_id, Some(7));
The URL of a callback comes from the request that declares it:
/// Where the `productCreated` callback goes: the URL the request's body names.
fn created_callback(request: &api::Request) -> Option<String> {
let exchange = api::Exchange { request: Some(request), method: "POST", ..Default::default() };
ops::create_product::callbacks::product_created_url(&ops::create_product::Params::default(), &exchange)
}
OAuth2
A client credentials flow fetches its token with authorize_<scheme>. A device authorization flow (OpenAPI 3.2) shows a code to the user and then polls:
/// Signs in on another device. The user opens a page and types the code. Meanwhile this polls until they did.
async fn sign_in(client: &mut api::Client<impl api::Transport>) -> Result<(), api::Error> {
let code = client.device_start_o_auth2("shop-cli", &["read:products"]).await?;
println!("Open {} and enter {}", code.verification_uri, code.user_code);
loop {
match client.device_poll_o_auth2("shop-cli", &code).await? {
api::DevicePoll::Ready(_) => return Ok(()), // the token is now the client's credential
api::DevicePoll::Pending | api::DevicePoll::SlowDown => {
tokio::time::sleep(Duration::from_secs(code.interval)).await;
}
}
}
}
Other flows get helpers by what the scheme declares:
| Flow | Methods |
|---|---|
| Authorization code (PKCE) | Client::authorization_url_<s>(..., &pkce) and then exchange_code_<s>(code, ..., &pkce) |
| Password | authorize_password_<s>(user, password, client_id, secret, scopes) |
| Implicit | Client::implicit_url_<s>(...) |
| Refresh | refresh_<s>(refresh_token, client_id, secret) |
| OpenID Connect and RFC 8414 | discover_<s>() returns the token, authorization and device endpoints |
Streams
A response declared as a sequence also gets <op>_stream. The sequence is JSON Lines or JSON text sequences or server-sent events. <op>_stream gives a Stream that yields each item as it arrives. Read it with futures_util::StreamExt::next. A binary response gets the Response with its body still to come: resp.into_body().into_stream() yields its raw chunks. An item that does not decode is an Err. The items after it can still be read:
/// Every product event of the feed read as they arrive. The feed ends with `data: [DONE]`. That is not an event.
async fn product_events(client: &api::Client<impl api::Transport>) -> Result<Vec<types::ProductEvent>, api::Error> {
let params = ops::stream_product_events::Params::default();
let api::Streamed::Ok(mut stream) = client.stream_product_events_stream(params).await? else {
return Ok(vec![]); // another declared status, decoded whole
};
let mut events = vec![];
while let Some(item) = stream.next().await {
match item {
Ok(event) => events.push(event),
Err(api::Error::Decode { body, .. }) if body.ends_with(b"[DONE]") => break,
Err(error) => return Err(error),
}
}
Ok(events)
}
The plain method reads the whole body before it decodes it. On a feed that never ends it waits for ever.
Reconnecting
Reconnects the stream through transport when it ends or breaks off, as the EventSource of a browser
does.
It keeps a clone of transport: wrap a transport that is not Clone in an Arc. It waits
ItemStream::retry (3 seconds until the server sends a retry). Then it sends req again with
Last-Event-ID, so the server can resume after the last event read. An event that the connection broke inside
is dropped. So no event is read twice.
A failed reconnection is an Err and the next poll tries again. Each time it waits twice as long, up to a
minute. A 429 or 5xx counts as failed. The stream ends on a 204 or another status, on a response that is
not text/event-stream and after ItemStream::max_retries failed reconnections in a row.
ItemStream::no_reconnect ends it with the body. Other framings and a req of None end where the body
ends: a streamed request body cannot be sent twice.
/// Follows the feed. When the connection ends or breaks off the stream waits for the `retry` of the server. Then it
/// asks again with `Last-Event-ID`. So no event is lost or read twice. It ends when the server answers `204` or after
/// five failed reconnections in a row.
async fn follow(
client: &api::Client<impl api::Transport>,
mut on_event: impl FnMut(types::ProductEvent),
) -> Result<(), api::Error> {
let params = ops::stream_product_events::Params::default();
let api::Streamed::Ok(stream) = client.stream_product_events_stream(params).await? else {
return Ok(()); // another declared status: the feed is gone
};
let mut stream = stream.max_retries(5);
while let Some(event) = stream.next().await {
on_event(event?);
}
Ok(())
}
Conditional requests
A client sends a conditional request when the operation declares an If-None-Match header parameter. It can then ask for a product only if its copy is stale. When the description declares no 304 for the operation a 304 is Err(api::Error::NotModified). It has the headers of the response:
/// The product or `None` when the copy tagged `etag` is still current.
async fn product_if_changed(
client: &api::Client<impl api::Transport>,
etag: &str,
) -> Result<Option<ops::get_product::Response>, api::Error> {
let params = ops::get_product::Params { if_none_match: Some(etag.to_owned()), ..ops::get_product::Params::new(7) };
match client.get_product(params).await {
Err(api::Error::NotModified { .. }) => Ok(None),
other => other.map(Some),
}
}
Retries and caching
Retries, timeouts and caching come from a reqwest-middleware stack. ReqwestMiddlewareTransport sends through it. This one caches with http-cache-reqwest and retries with reqwest-retry:
/// Retries only methods that RFC 9110 calls idempotent. `RetryTransientMiddleware` alone retries any method. A `POST`
/// sent twice may create twice.
struct IdempotentOnly<M>(M);
#[async_trait::async_trait]
impl<M: reqwest_middleware::Middleware> reqwest_middleware::Middleware for IdempotentOnly<M> {
async fn handle(
&self,
req: reqwest::Request,
extensions: &mut http::Extensions,
next: reqwest_middleware::Next<'_>,
) -> reqwest_middleware::Result<reqwest::Response> {
use reqwest::Method;
let idempotent = [Method::GET, Method::HEAD, Method::OPTIONS, Method::PUT, Method::DELETE];
if idempotent.contains(req.method()) {
self.0.handle(req, extensions, next).await
} else {
next.run(req, extensions).await
}
}
}
/// A client that keeps an in-memory HTTP cache and revalidates with `If-None-Match`. It retries transient failures
/// (a lost connection, 5xx, 429) of idempotent requests with exponential backoff. It is a `reqwest-middleware` stack
/// sent through `ReqwestMiddlewareTransport`.
fn retrying(base_url: &str) -> api::Client<api::ReqwestMiddlewareTransport> {
use http_cache_reqwest::{Cache, CacheMode, HttpCache, HttpCacheOptions, MokaManager};
let policy = reqwest_retry::policies::ExponentialBackoff::builder().build_with_max_retries(3);
let cache =
HttpCache { mode: CacheMode::Default, manager: MokaManager::default(), options: HttpCacheOptions::default() };
let stack = reqwest_middleware::ClientBuilder::new(reqwest::Client::new())
.with(Cache(cache))
.with(IdempotentOnly(reqwest_retry::RetryTransientMiddleware::new_with_policy(policy)))
.build();
api::Client::new(api::ReqwestMiddlewareTransport::with_client(stack, base_url)).with_api_key("secret")
}
Each piece of that stack does one job and has limits:
| Piece | What it does | Limits |
|---|---|---|
RetryTransientMiddleware | It retries a lost connection, a 5xx, a 408 or a 429 with exponential backoff. | It ignores Retry-After: the backoff alone sets the wait. It does not tell methods apart, so on its own it sends a failed POST again. |
IdempotentOnly | It lets only GET, HEAD, OPTIONS, PUT and DELETE through to the retry. | None. |
Cache | It keeps responses as RFC 9111 allows and revalidates a stale one with If-None-Match or If-Modified-Since. A 304 comes back as the cached 200. | Only its 1.0 alpha builds on reqwest 0.13. |
A streamed upload cannot be sent twice. So retry middleware does not retry it.
ureq and the GlooTransport of the browser have no middleware stack. They are tower services, so tower layers wrap them. See your own transport.
Errors
A call returns Err(api::Error) when it gets no response the description declares:
| Variant | Meaning |
|---|---|
Transport | The request could not be sent or the connection broke off (connection or TLS for example). |
Encode | A parameter or the body could not be serialized. |
Decode | A documented response does not fit its schema. pointer says where. |
UnexpectedMedia | The status is declared but the response’s Content-Type is none that the description declares for it. |
NotModified | 304 Not Modified to a request that sent If-None-Match or If-Modified-Since. The operation declares no 304. The representation that the client holds is still current. |
UnexpectedStatus | A status that the operation declares neither as itself nor as a default. |
Invalid | An item of a request body still arriving breaks the description’s constraints. |
TooLarge | A body still arriving went past a limit in bytes: the max_body_bytes of the server. |
Every other variant that read a response carries its raw body.
Browser (WebAssembly)
The client compiles for wasm32-unknown-unknown and sends through the browser’s fetch:
- Depend on
gloo-netwith itshttpfeature under[target.'cfg(target_arch = "wasm32")'.dependencies]. Native builds then skip it, as the adapter compiles on wasm32 only. - Set
client = { adapters = ["gloo-net"] }andserver = false. - Build the client on
api::GlooTransport::new("/api").
Futures on wasm32 are not Send. A transport service of your own writes + api::MaybeSend instead of + Send on its futures, so it compiles for both targets.
Server
A server is your type that implements the generated server::Api. It has one method per operation:
/// The catalog in memory. The ID of a product is its index.
#[derive(Default)]
pub struct Catalog(Mutex<Vec<types::Product>>);
impl Catalog {
fn products(&self) -> Result<MutexGuard<'_, Vec<types::Product>>, api::ApiError> {
self.0
.lock()
.map_err(|_| api::ApiError::new(api::http::StatusCode::INTERNAL_SERVER_ERROR, "catalog lock poisoned"))
}
}
impl api::Api for Catalog {
type Principal = ();
async fn list_products(
&self,
params: ops::list_products::Params,
_: &api::Context<'_>,
) -> Result<ops::list_products::Response, api::ApiError> {
let limit = params.limit.and_then(|n| usize::try_from(n).ok()).unwrap_or(usize::MAX);
let body = self.products()?.iter().take(limit).cloned().collect();
Ok(ops::list_products::Response::Ok { body, x_next: None })
}
async fn create_product(
&self,
params: ops::create_product::Params,
_: &api::Context<'_>,
) -> Result<ops::create_product::Response, api::ApiError> {
self.products()?.push(params.body.clone());
Ok(ops::create_product::Response::Created(params.body))
}
async fn get_product(
&self,
params: ops::get_product::Params,
_: &api::Context<'_>,
) -> Result<ops::get_product::Response, api::ApiError> {
let found = usize::try_from(params.product_id).ok().and_then(|i| self.products().ok()?.get(i).cloned());
Ok(match found {
Some(product) => ops::get_product::Response::Ok(product),
None => ops::get_product::Response::NotFound(types::Error::new(404, "no such product".to_owned())),
})
}
}
api::Server::new(Catalog::default()) builds the server. into_axum() serves it as an axum Router. into_service() serves it as a tower Service for hyper and other servers. See Adapters.
The server keeps your Api in an Arc and shares it across requests without cloning it. To share the same state with code outside the server, such as a websocket route or a background job, pass an Arc you keep a clone of: api::Server::new(Arc::clone(&catalog)).
A request goes through these steps. When a step refuses the request it answers in the error schema of the description:
- Routing: an undeclared path is 404. An undeclared method is 405. A
HEADtakes theGETof its path and gets its headers without the body. - Credentials: the
securityof the operation. If none of its requirements are present then the answer is 401. - Your layers as an
http::Request<Body>in the order that you add them. The first one is the outermost. Its extensions hold the generatedOperation, theRequestEventand the credentials (Secured). The body is not read yet. So a refused request costs no body read.read_bodyreads it for a layer that needs it. - The body: read whole up to
max_body_bytes(413). An operation that streams its body skips this step. - Decoding and validation (400 and 415). Then your handler runs and its response is encoded.
Server::authenticate finds who is calling and puts the principal in the extensions. When your Api names a
Principal the server builds into a service only once it does.
Validation
Requests are checked against every constraint of their schemas. A failing request gets 400 with every violation and its JSON pointer:
{"violations": [{"path": "/body/name", "message": "at least 2 characters required, found 1"}]}
A body whose Content-Type the operation does not declare gets 415.
Content negotiation
An operation may answer in several media types. It answers in the one that the Accept of the request prefers (RFC 9110 section 12.5.1). If Accept takes none of them then it answers 406. When every media type holds the same type the handler returns that type. The server then picks the encoding. When they hold different types Params carries the choice as a typed media.
Streams
Binary responses take api::Blob. Return bytes. Or pass any Stream of chunks to Blob::stream for a large download:
fn get_export(
&self,
p: ops::get_export::Params,
_: &api::Context<'_>,
) -> impl Future<Output = Result<ops::get_export::Response, api::ApiError>> + Send {
let r = match p.id.as_str() {
"big" => {
ops::get_export::Response::Ok(api::Blob::stream(futures_util::stream::iter(CHUNKS.map(<[u8]>::to_vec))))
}
"small" => ops::get_export::Response::Ok(b"zip".to_vec().into()),
// A file read from where the range starts. The bytes before it are never read.
"archive" => ops::get_export::Response::Ok(api::Blob::ranged(ARCHIVE.len() as u64, |first, last| {
let (first, last) = (usize::try_from(first).unwrap_or(0), usize::try_from(last).unwrap_or(0));
futures_util::stream::iter(ARCHIVE.get(first..=last).map(<[u8]>::to_vec))
})),
_ => ops::get_export::Response::NotFound,
};
std::future::ready(Ok(r))
}
A response declared as a range, such as image/* or */*, has no one type to send. Give the blob its type with Blob::with_media. It goes out as that type when it fits the range, else as application/octet-stream. The client reads it back with Blob::media:
fn get_thumbnail(
&self,
p: ops::get_thumbnail::Params,
_: &api::Context<'_>,
) -> impl Future<Output = Result<ops::get_thumbnail::Response, api::ApiError>> + Send {
// `image/*` declares a range: the blob says which image it is.
let preview = api::Blob::from(PNG.to_vec());
let preview = match p.id.as_str() {
"png" => preview.with_media("image/png"),
"zip" => preview.with_media("application/zip"),
_ => preview,
};
std::future::ready(Ok(ops::get_thumbnail::Response::Ok(preview)))
}
Binary request bodies reach the handler as they arrive. A Blob is a Stream of its chunks. So the server never holds a whole upload. A body past max_body_bytes fails its chunk. Then ? answers 413:
let mut body = params.body;
if !body.is_streamed() {
return Err(api::ApiError::new(
api::http::StatusCode::INTERNAL_SERVER_ERROR,
"the body was read before the handler",
));
}
let (mut bytes, mut chunks) = (0, 0);
while let Some(chunk) = body.next().await {
bytes += chunk?.len();
chunks += 1;
}
Sequential responses take api::Items<T> in the same way. These are JSON Lines and JSON text sequences and server-sent events. Return Items::List(vec). Or pass any Stream of items to Items::stream. A sequential request body is a Stream of its items too.
Server-sent events can also take Items::events. Its records carry the id and name of an event. They also carry a retry and comments. A client that reconnects sends the last id back as Last-Event-ID:
/// The feed after the event that a reconnecting client read last. Each event carries its `id`. The client sends it
/// back as `Last-Event-ID`. `retry` tells clients how long to wait before they reconnect. On a quiet minute a
/// comment goes out. So proxies keep the connection open.
fn feed(
events: &[(String, types::ProductEvent)],
last_event_id: Option<&str>,
retry: Duration,
) -> api::Items<types::ProductEvent> {
let after = last_event_id.and_then(|id| events.iter().position(|(e, _)| e == id)).map_or(0, |i| i + 1);
let events = events.iter().skip(after);
let records = std::iter::once(api::Sse::Retry(retry)).chain(events.map(|(id, item)| api::Sse::Event {
id: Some(id.clone()),
event: None,
item: item.clone(),
}));
api::Items::events(futures_util::stream::iter(records.collect::<Vec<_>>())).heartbeat(Duration::from_secs(60))
}
Answer 204 to a client that should stop reconnecting.
Conditional requests
Some GET and HEAD requests get 304 Not Modified (RFC 9110 section 13). This happens when the success response carries an ETag or a Last-Modified. The If-None-Match or If-Modified-Since of the request must also say that the client already holds it. The 304 keeps the validators and caching headers and drops the body. Your handler still runs.
Before a handler changes a resource ctx.preconditions checks If-Match, If-Unmodified-Since and If-None-Match against its current validators. It refuses with 412:
async fn replace_manifest(
&self,
p: ops::replace_manifest::Params,
ctx: &api::Context<'_>,
) -> Result<ops::replace_manifest::Response, api::ApiError> {
let mut manifest = self
.manifest
.lock()
.map_err(|_| api::ApiError::new(api::http::StatusCode::INTERNAL_SERVER_ERROR, "manifest lock poisoned"))?;
let etag = format!("\"v{}\"", manifest.0);
// 412 unless the client changed the version it read.
ctx.preconditions(Some(api::Validators { etag: Some(&etag), last_modified: Some(LAST_MODIFIED) }))?;
*manifest = (manifest.0 + 1, p.body);
Ok(ops::replace_manifest::Response::NoContent)
}
Pass None for a resource that does not exist yet. If-None-Match: * then lets a create through. If-Match: * refuses it.
Range requests
Range requests (RFC 9110 section 14): one byte range of a binary response, for a download that resumes or a player that seeks.
The server answers Range itself on a GET whose success response is binary, such as application/zip or an
image. Your handler returns the whole body as usual:
| Request | Response |
|---|---|
No Range | 200 with Accept-Ranges: bytes |
Range: bytes=1000-, bytes=0-499 or bytes=-500 | 206 Partial Content: those bytes and Content-Range: bytes 1000-4999/5000 |
| A range that starts past the end | 416 Range Not Satisfiable with Content-Range: bytes */5000 |
If-Range next to it with an ETag or date that the body no longer has | 200: the whole new body |
Only a body whose length is known can be cut. That is a body held whole (shared bytes of a crate::Blob are cut
without a copy) or a crate::Blob::ranged. The server calls the open(first, last) of a ranged blob once with
the bytes it sends. So the bytes before the range are never read.
These go out whole with no Accept-Ranges, as RFC 9110 allows: a crate::Blob::stream of unknown length, JSON
and other structured bodies, several ranges in one request and a Range that does not parse. An operation that
declares a 206 (or 2XX) or a Range parameter of its own answers ranges in its handler
(Op::ranges). The server leaves it alone.
Errors
The error of a handler can be the error schema of the description. honig generates From<types::Problem> for api::ApiError for it. Errors that the server raises itself go through error_response:
/// Every error that the server raises itself as plain text. The own typed errors of a handler go out as they are.
fn plain_text_errors() -> axum::Router {
api::Server::new(Catalog::default())
.error_response(|rejection: api::Rejection| {
let reason = &rejection.reason;
if let Some(own) = reason.own() {
return own;
}
let mut response = reason.head();
response
.headers_mut()
.insert(api::http::header::CONTENT_TYPE, api::http::HeaderValue::from_static("text/plain"));
*response.body_mut() = api::Body::from(reason.detail().unwrap_or_default());
response
})
.into_axum()
}
Returns the body that your handler or a layer set (ApiError::with_body). Otherwise the reason in the error
schema of the description (Rejection::schema). Otherwise RFC 9457 problem+json.
The fields of an error schema that the server fills:
| Variant | Meaning |
|---|---|
Status | The HTTP status as a number (code or status). |
StatusText | The HTTP status as text (code declared as a string). |
Title | The reason phrase (title). |
Detail | What went wrong (message, detail or error). |
Type | about:blank (type). |
Violations | Every violation as {path, message} (errors or violations). |
ViolationMessages | Every violation as one string each (errors of strings). |
Const | A required const (object: {const: error}): its one value, as JSON text. |
Empty | A required field nothing maps to: its type’s empty value. |
Server options
The options of honig::Server, from its rustdoc:
A server for the operations O with the tower layers L between routing and each operation. A is whether it
finds who is calling (Authentication).
The generated api::Server::new(api) starts one. Layers run in the order that they are added. The first one is the
outermost as with the ServiceBuilder of tower. Each one is a tower Service of http::Request<Body>. It
answers with a Response or with an error that converts into an ApiError. That error goes out in the error
schema that the description declares. Generic tower layers (Timeout, LoadShed and ConcurrencyLimit) fit
too. Their BoxError becomes a 503.
max_body_bytes
Sets the largest request body in bytes that the server reads. Larger ones get 413. Default: 16 MiB.
The limit is a setting of the server and not a layer outside it, such as RequestBodyLimitLayer of
tower-http:
- The server reads the body itself to decode it. It holds the body in memory. So it needs a limit even with no layer around it.
- A streamed
Blobfails the chunk that goes past the limit. The handler gets that error, and?answers413in the error schema of the description. read_bodyin a layer reads up to the same limit. A layer that checks a signature over the body and the operation that decodes it agree on one number.
A layer outside can only lower the limit. It refuses a request early when its Content-Length is too large.
Its answer then has its own body: map it through Errors::response. A body without Content-Length fails
while the server reads it. The server sees a broken body and answers 400, not 413.
error_response
Sets the response for a request that the server answers without the response of your handler. The cause is no
route, bad input, missing credentials, the Err of a layer, validation, a handler Err or an encoding failure.
Default: Rejection::response.
on_event
Sets the sink that receives the wide event (RequestEvent) of each request once the response is ready. By
default the event is logged with tracing when the server lists the tracing adapter, and dropped otherwise.
errors
Returns the error responses of the description for a layer outside the server. Such a layer is a timeout, a body limit or an IP flood guard. It then answers in the same error schema as the operations.
Authentication
Api::Principal is who is calling. authenticate finds the principal from the credentials that the request presented:
/// The principal that an API key names. Nobody without a key. 401 for a key that nobody holds.
fn caller_of_key(req: &api::Request) -> Result<Option<String>, api::ApiError> {
let key = api::server::credentials(req).into_iter().map(|api::server::Credential::ApiKey(key)| key).next();
match key {
Some("secret") => Ok(Some("ann".to_owned())),
Some(_) => Err(api::ApiError::new(api::http::StatusCode::UNAUTHORIZED, "unknown key")),
None => Ok(None),
}
}
fn authenticated() -> axum::Router {
api::Server::new(Server).authenticate(|req: &api::Request| std::future::ready(caller_of_key(req))).into_axum()
}
find answers None for nobody. When your Api names a Principal, a server without authenticate does not compile. Layers added after authenticate read the principal from the request’s extensions:
Whether the server finds who is calling: Anonymous until Server::authenticate, then Authenticated.
An Api whose Principal is () builds into a service as it is. Any other Principal needs
Server::authenticate: without it into_service does not compile. Each operation then takes what its
security asks for:
The operation’s security | ctx.principal | When authenticate found nobody |
|---|---|---|
none (security: []) | () | the handler runs |
an empty alternative ([{}, {apiKey: []}]) | Option<Principal> | the handler runs with None |
| credentials required | Principal | 401 in the error schema |
Every 401 of an operation carries WWW-Authenticate with a challenge for its http schemes (Bearer, Basic), also one that your handler returns. An apiKey or mutualTLS scheme has no HTTP authentication scheme to name in a challenge (RFC 9110 section 11.6.1), so a 401 for one carries none.
server::credentials(req) gives one Credential variant per security scheme that the operation matched. A scheme added to the description is then a compile error until you handle it.
Request context
Values that outer tower layers attach also reach authenticate. So does the address of the client:
/// Who is calling: the layer in front of the router and the client's address.
fn find_caller(req: &api::Request) -> Result<Option<String>, api::ApiError> {
let principal = req
.extensions()
.get::<Principal>()
.ok_or_else(|| api::ApiError::new(api::http::StatusCode::UNAUTHORIZED, "no principal"))?;
let peer = api::peer(req.extensions())
.ok_or_else(|| api::ApiError::new(api::http::StatusCode::UNAUTHORIZED, "no peer"))?;
Ok(Some(format!("{} from {peer}", principal.0)))
}
Recipes maps the claims of a JWT or session layer that you already run to the principal.
Signatures over the body
Some schemes sign the body: webhooks (X-Hub-Signature-256, Stripe-Signature) and Matrix federation (X-Matrix). The layer that checks the signature reads the body with api::read_body(&mut req).await. The operation decodes the same bytes and reads nothing again:
/// A signature over the body, as webhooks (`X-Hub-Signature-256`) and Matrix (`X-Matrix`) send. Here the signature is
/// the body's length, a stand-in for an HMAC. The filter owns the request, so it reads the body itself. The operation
/// then decodes the same bytes and reads nothing again.
async fn verify(mut req: api::Request) -> Result<api::Request, api::ApiError> {
let len = api::read_body(&mut req).await?.len();
let ok = req.headers().get("x-signature").and_then(|v| v.to_str().ok()) == Some(len.to_string().as_str());
if ok { Ok(req) } else { Err(api::ApiError::new(api::http::StatusCode::UNAUTHORIZED, "bad signature")) }
}
let service = api::Server::new(Catalog::default())
.operation_layer(tower::filter::AsyncFilterLayer::new(verify))
.into_service();
A layer that does not call read_body runs before the body is read. So a refused request costs no body read. A client signs in its transport: the request is final there, body included. reqwest-middleware and tower layers work too.
Scopes and roles
Scopes and roles are typed. There is one server::Scope variant per name in the description. Match them exhaustively. A permission added to the description is then a compile error until you map it:
/// Checks the permissions the operation requires: every request runs through it.
fn permitted(req: &api::Request) -> Result<(), api::ApiError> {
let token = server::credentials(req).into_iter().map(|Credential::Pat(t)| t.to_owned()).next();
let held = |s: Scope| {
let t = token.as_deref().unwrap_or("");
match s {
Scope::IssuesRead => t.split('+').any(|p| p == "read"),
Scope::IssuesWrite => t.split('+').any(|p| p == "write"),
}
};
if server::scopes_held(req, held) {
Ok(())
} else {
Err(api::ApiError::new(api::http::StatusCode::FORBIDDEN, "missing permission"))
}
}
Client certificates
A mutualTLS alternative is never satisfied on its own. A layer that trusts the certificate your TLS terminator verified adds api::ClientCertificateVerified to the request’s extensions.
Layers
Two places take tower layers. The rustdoc of Server::operation_layer compares them:
Adds a tower layer between routing and the operations. It goes inside the layers added before. The first one
added is the outermost as with the ServiceBuilder of tower. Pass one ServiceBuilder to read the order top
to bottom.
A layer here and one on the axum Router that into_axum returns differ:
- An
operation_layerruns once routing found the operation and its credentials passed. Its extensions hold the operation, the credentials and, afterauthenticate, the principal. Its errors go out in the error schema of the description. It fits per-principal limits, permissions, signatures and timeouts. - An axum
Router::layerruns on every request, also to unknown paths. It knows no operation yet, and its errors go out with the body that it writes. It fits CORS, compression and request IDs.
Inside
Layers inside the server answer in the error schema. Timeouts, load shedding and concurrency limits answer 503:
/// Limits that answer in the description's error schema: a `503` once a request takes too long or too many run.
fn limited() -> axum::Router {
api::Server::new(Catalog::default())
.operation_layer(tower::timeout::TimeoutLayer::new(Duration::from_secs(10)))
.operation_layer(tower::load_shed::LoadShedLayer::new())
.operation_layer(tower::limit::ConcurrencyLimitLayer::new(64))
.into_axum()
}
Rate limits
OpenAPI cannot express a rate limit. Enforce one with tower’s AsyncFilterLayer. It runs before the body is read. The request’s extensions hold the operation and, after authenticate, the principal. An ApiError it returns goes out in the error schema:
/// At most `limit` requests. A real limiter keys its count by principal and time window. It keeps it in the same way in
/// an `Arc` because the layer is cloned for every request.
fn rate_limited(limit: u32) -> axum::Router {
let used = Arc::new(AtomicU32::new(0));
api::Server::new(Catalog::default())
.operation_layer(tower::filter::AsyncFilterLayer::new(move |req: api::Request| {
let over = used.fetch_add(1, Ordering::Relaxed) >= limit;
let refusal = api::ApiError::new(api::http::StatusCode::TOO_MANY_REQUESTS, "rate limit exceeded")
.with_header(api::http::header::RETRY_AFTER, api::http::HeaderValue::from_static("60"));
std::future::ready(if over { Err(refusal) } else { Ok(req) })
}))
.into_axum()
}
req.extensions().get::<api::Operation>() is the generated api::Operation: one variant per operation. Match on it to treat operations apart. Rejection::operation of error_response, Context::operation of a handler and the operation of the wide event are the same enum:
/// Writes cost more than reads: only `createProduct` is limited. The match lists every operation, so one added to the
/// description fails to compile here until you decide its limit.
fn writes_limited(limit: u32) -> axum::Router {
let used = Arc::new(AtomicU32::new(0));
api::Server::new(Catalog::default())
.operation_layer(tower::filter::AsyncFilterLayer::new(move |req: api::Request| {
let limited = match req.extensions().get::<api::Operation>() {
Some(api::Operation::CreateProduct) => true,
Some(api::Operation::ListProducts | api::Operation::GetProduct) | None => false,
};
let over = limited && used.fetch_add(1, Ordering::Relaxed) >= limit;
std::future::ready(if over {
Err(api::ApiError::new(api::http::StatusCode::TOO_MANY_REQUESTS, "too many writes"))
} else {
Ok(req)
})
}))
.into_axum()
}
A layer for any API
A plain tower Layer fits any honig server. Its service takes honig::Request and names the operation with the MatchedOperation in the extensions:
/// A tower layer for any honig server: it counts the requests of each operation by its name. It is a plain
/// `tower::Layer` over `http` requests that reads the `MatchedOperation` that the server puts in the extensions.
#[derive(Clone, Default)]
struct CountByOperationLayer(Arc<std::sync::Mutex<std::collections::BTreeMap<&'static str, u32>>>);
impl<S> tower::Layer<S> for CountByOperationLayer {
type Service = CountByOperation<S>;
fn layer(&self, inner: S) -> CountByOperation<S> {
CountByOperation { inner, counts: Arc::clone(&self.0) }
}
}
#[derive(Clone)]
struct CountByOperation<S> {
inner: S,
counts: Arc<std::sync::Mutex<std::collections::BTreeMap<&'static str, u32>>>,
}
impl<S: tower::Service<honig::Request>> tower::Service<honig::Request> for CountByOperation<S> {
type Response = S::Response;
type Error = S::Error;
type Future = S::Future;
fn poll_ready(&mut self, cx: &mut std::task::Context<'_>) -> std::task::Poll<Result<(), S::Error>> {
self.inner.poll_ready(cx)
}
fn call(&mut self, req: honig::Request) -> S::Future {
if let Some(routed) = req.extensions().get::<honig::MatchedOperation>() {
*self.counts.lock().unwrap().entry(routed.name()).or_default() += 1;
}
self.inner.call(req)
}
}
Outside
tower-http layers go outside the server. A layer outside that answers on its own can render the description’s error schema with errors():
/// tower-http layers outside the router. A layer outside that answers on its own renders the error schema of the
/// description with `errors()`. Here it answers for a path that the description does not declare.
fn with_cors() -> axum::Router {
let server = api::Server::new(Catalog::default());
let errors = server.errors();
server
.into_axum()
.fallback(move || {
std::future::ready(errors.response(api::http::StatusCode::NOT_FOUND, "no such page").into_response())
})
.layer(tower_http::cors::CorsLayer::permissive())
}
Recipes puts layers outside and inside the server and authenticate in one stack. It also maps the errors of outside layers that fail with a timeout or a full queue.
AWS Lambda
A honig server runs on AWS Lambda through lambda_http, behind the API Gateway route ANY /{proxy+}. lambda_http::run takes the router in the same way as its adapter does here:
let mut adapter = lambda_http::Adapter::from(api::Server::new(Server).into_axum());
| Topic | What to know |
|---|---|
| Stage | lambda_http puts the stage in front of the path unless AWS_LAMBDA_HTTP_IGNORE_STAGE_IN_PATH is set. A REST API always has a named stage. |
| Caller’s address | There is no socket. API Gateway’s sourceIp is in ctx.extension::<lambda_http::request::RequestContext>(). |
| Binary bodies | A REST API decodes them only for the media types in its binaryMediaTypes. |
| Body size | API Gateway buffers the request up to 6 MB. |
Adapters
The cargo features of the runtime turn on its adapters and codecs. The table lists what turns each one on. generate writes them all but simd, which is yours to list or leave out. cargo honig check reports them when they are out of date.
| Feature | Crate | Adds | On when |
|---|---|---|---|
client | tower-service | The generated client: the Transport bound over tower services and TowerTransport | You generate the client |
server | tower-service | The generated server: a tower Service, routing, conditional requests and the wide event | You generate the server |
reqwest | reqwest | ReqwestTransport: async client with streaming bodies | client = { adapters = ["reqwest"] } |
reqwest-middleware | reqwest-middleware | ReqwestMiddlewareTransport: retries, tracing and caching from your middleware stack | client = { adapters = ["reqwest-middleware"] } |
ureq | ureq | UreqTransport: blocking client | client = { adapters = ["ureq"] } |
gloo-net | gloo-net | GlooTransport: browser fetch on wasm32 only | client = { adapters = ["gloo-net"] } |
axum | axum | Server::into_axum and the address of the client from the ConnectInfo of axum | server = { adapters = ["axum"] } |
tracing | tracing | A span per request and a log line for each wide event | server = { adapters = ["tracing"] } |
tracing-opentelemetry | opentelemetry | W3C Trace Context: traceparent and tracestate | adapters = ["tracing-opentelemetry"] in client or server |
ipnet | ipnet | format: ipv4-cidr and ipv6-cidr checks | The description calls for it |
idn | idna | email, idn-email, hostname and idn-hostname checks | The description calls for it |
regress | regress | pattern and patternProperties checks (ECMA-262) | The description calls for it |
oauth | The OAuth 2.0 flows of the client: token grants, device authorization and discovery | The description calls for it | |
pkce | sha2 | Pkce, authorization_url and exchange_code: the OAuth 2.0 authorization code flow. Outside wasm32 Pkce::new makes a verifier from OS randomness | The description calls for it |
cookie | cookie | Cookie parameters and API keys | The description calls for it |
multipart | multer | multipart/* bodies and parts | The description calls for it |
base64 | base64 | Binary data in JSON (format: byte, contentEncoding, base64url) and http basic credentials | The description calls for it |
xml | quick-xml | XML bodies and parts | The description calls for it |
simd | sonic-rs | SIMD for large bodies: JSON with sonic-rs (x86_64 and aarch64), the UTF-8 check of text with simdutf8 and base64 with base64-simd. Multipart boundaries use memchr with or without it | You or cargo honig init add it |
An adapter is compiled whenever its half lists it, also when its library is an optional dependency that is off. Depend on the major version that the table names. Otherwise cargo builds two copies whose types do not match.
axum
into_axum() returns a Router with a route per path template. It merges next to your own routes or nests under a prefix:
async fn serve(addr: &str) -> std::io::Result<()> {
let listener = tokio::net::TcpListener::bind(addr).await?;
println!("serving the catalog on http://{addr}/v1");
let app = api::Server::new(Catalog::default())
// One JSON line per request: the operation, the status, the duration, the body sizes and more.
.on_event(|event: &api::RequestEvent| println!("{}", event.to_json()))
.into_axum();
axum::serve(listener, app).await
}
A path that the description does not declare falls through to the fallback of the router: a bare 404 with no body and no wide event. To answer it in the error schema with a wide event, give the router a fallback that is the server:
/// An axum router whose undeclared paths reach the server too. They then get its 404 in the error schema and a wide
/// event. Leave the fallback out to give those paths to routes of your own.
fn with_fallback(lines: Arc<Mutex<Vec<String>>>) -> axum::Router {
let server = || {
let lines = Arc::clone(&lines);
api::Server::new(Catalog::default()).on_event(move |event: &api::RequestEvent| {
if let Ok(mut lines) = lines.lock() {
lines.push(event.to_json());
}
})
};
server().into_axum().fallback_service(server().into_service())
}
axum refuses to merge two routers that both have a fallback. Set it once, on the router that you serve.
Recipes serves a web app next to the API and a WebSocket next to the generated routes.
hyper and other servers
into_service() is a tower Service over http requests:
async fn serve_with_hyper(listener: tokio::net::TcpListener) -> std::io::Result<()> {
let service = api::Server::new(Catalog::default()).into_service();
loop {
let (stream, _) = listener.accept().await?;
let service = hyper_util::service::TowerToHyperService::new(service.clone());
let io = hyper_util::rt::TokioIo::new(stream);
tokio::spawn(hyper::server::conn::http1::Builder::new().serve_connection(io, service));
}
}
Blocking client
UreqTransport sends with ureq. block_on runs the call with no async runtime:
/// The blocking client. `block_on` returns once the response is read with no async runtime.
fn list_products(base_url: &str) -> Result<ops::list_products::Response, api::Error> {
let client = api::Client::new(api::UreqTransport::new(base_url)).with_api_key("secret");
api::block_on(client.list_products(ops::list_products::Params::new()))
}
Testing without a socket
A server’s into_service() is a transport too. The client then sends each request straight to the server in memory:
/// A client wired straight to the server with no socket. A test of your server needs this.
fn in_memory_client() -> api::Client<impl api::Transport> {
let service = api::Server::new(Catalog::default()).into_service();
api::Client::new(service).with_api_key("secret")
}
Your own transport
A transport is any tower Service of http requests. Write one to send with any HTTP client. Wrap one with tower’s layers:
/// A transport is any tower `Service`, so tower's layers wrap one: this one adds a request ID to every request.
fn with_request_id(transport: impl api::Transport) -> impl api::Transport {
tower::ServiceBuilder::new()
.map_request(|mut req: api::Request| {
req.headers_mut().insert("x-request-id", api::http::HeaderValue::from_static("req-1"));
req
})
.service(transport)
}
TLS
TLS comes from your own dependency. honig depends on reqwest and ureq without default features. Cargo adds the features that your crate turns on. The default is rustls. If your crate turns them off then add rustls or native-tls. Otherwise every https request fails.
Observability
Every request that reaches the server produces one wide event. Under into_axum a path that the description does not declare gets one only through the fallback in Adapters. The event holds these fields:
- the operation and route
- the status and duration
- the body sizes
- the security schemes and scopes
- the failure kind if there is one
Layers add fields with req.event().set(key, value). Handlers add fields with ctx.event.set(key, value). A key is an EventKey. Declare it as a const such as const TENANT: EventKey = EventKey::new("tenant"). Then a key that has the name of a built-in field fails to compile.
Send the event anywhere with on_event:
/// The wide event of each request as one JSON line to wherever your logs go. Here it is a list that a test reads.
fn logged(lines: Arc<Mutex<Vec<String>>>) -> api::Client<impl api::Transport> {
let service = api::Server::new(Catalog::default())
.on_event(move |event: &api::RequestEvent| {
if let Ok(mut lines) = lines.lock() {
lines.push(event.to_json());
}
})
.into_service();
api::Client::new(service).with_api_key("secret")
}
Tracing
With the tracing adapter each request runs in a span that wraps your layers and handler. The span follows the HTTP server conventions of OpenTelemetry (otel.name, http.route and http.response.status_code). The default on_event logs the wide event inside the span as one structured line. Export the spans with tracing-opentelemetry.
Trace context
The tracing-opentelemetry adapter adds W3C Trace Context. The span of a request then continues the trace that its traceparent header names. The requests of the client carry the traceparent and tracestate of the current span. A request that already has a traceparent keeps it. Spans join only once a tracing-opentelemetry layer exports them:
/// Spans exported through OpenTelemetry. The span of a request continues the trace that its `traceparent` names. The
/// requests of the client carry the ones of the current span.
fn exported() -> impl tracing::Subscriber {
use opentelemetry::trace::TracerProvider as _;
use tracing_subscriber::layer::SubscriberExt as _;
let provider = opentelemetry_sdk::trace::SdkTracerProvider::builder().build();
tracing_subscriber::registry().with(tracing_opentelemetry::layer().with_tracer(provider.tracer("shop")))
}
The runtime is built against opentelemetry 0.33 and tracing-opentelemetry 0.34. Depend on the same versions. A span from another version holds no context that the runtime can read.
Performance
Allocator
Use mimalloc in your binary. Decoding a JSON body allocates every string and Vec it holds. The system allocator is the largest cost after parsing.
Add mimalloc = "0.1" to [dependencies]. Then declare it in main.rs: #[global_allocator] static ALLOC: mimalloc::MiMalloc = mimalloc::MiMalloc;.
SIMD
The simd feature speeds up large bodies. Small ones see no difference. Its row in the feature table names the library of each path and says when it is on.
A body that fails to decode is read again by serde_json. Errors still name the field that is wrong.
Leaving simd out of the features trades runtime performance for a lighter build. JSON goes through serde_json and base64 through the scalar engine of the base64 crate. memchr stays.
sonic-rs has SIMD on x86_64 and aarch64 only. On other targets JSON stays on serde_json. This includes wasm32 clients. The other two libraries still apply. On wasm32 they use SIMD when you build with -C target-feature=+simd128.
simdutf8 and base64-simd pick the instructions of the CPU when the program starts. sonic-rs picks them at compile time. A plain x86_64 build uses SSE2, which every x86_64 CPU has. RUSTFLAGS="-C target-cpu=native" adds AVX2. A binary built that way stops with an illegal instruction on a CPU without AVX2, so name the oldest CPU you deploy to. aarch64 needs no flag.
Logging
The span and log line of the tracing adapter cost a fixed amount per request. It shows on small requests and fades on large ones.
Patterns
pattern checks run on regress. This is the ECMA-262 engine that JSON Schema asks for. One check is cheap. A large array of patterned fields adds up.
Benchmarks
cargo bench -p honig --all-features times the runtime from 256 B to 16 MiB. CI also counts instructions under Valgrind. It fails when a path costs more than n^1.3 (--bench scaling_gate). To see what SIMD gives, compare --bench simd --features multipart with --bench simd --features multipart,simd.
Generated module
| File | Contents |
|---|---|
mod.rs | The root of the module. It declares the other files and re-exports the client, the server and the runtime. |
types.rs | The schemas of the description as Rust types: structs, enums and newtypes. |
operations.rs | One module per operation with its Params, its Response enum and their body types. |
client.rs | The Client with one method per operation, and the WebhookClient when the description has webhooks. |
server.rs | The Api trait with one method per operation, the router and the Server of this API. |
runtime.rs | The runtime items that the generated code calls, re-exported from honig. |
documented_examples.rs | With tests = true: a test that decodes each example of the description into its type. |
Every file starts with // @generated. Do not edit it. Change the description and run cargo honig generate.
The files of the module are declared #[rustfmt::skip]. Your cargo fmt --check leaves them as generated.
honig
The runtime dependency of code generated by cargo-honig: HTTP adapters, routing, authentication and codecs.