Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.0Becomes
host, basePath, schemesservers
definitions, parameters, responses, securityDefinitionscomponents, with every $ref rewritten
body and formData parametersrequestBody, one entry per consumes media type
a response schemacontent, one entry per produces media type
inline type keywords of other parameters and headerstheir schema
collectionFormatstyle and explode
collectionFormat: tsvx-collection-format: tsv: 3.x has no tab style, but honig still encodes it
type: filetype: string with format: binary
x-nullablenullable

What is lost:

  • An unknown collectionFormat is read as csv.
  • An unknown OAuth2 flow is read as implicit.
  • A security scheme of an unknown type is 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.0Becomes
nullable: true"null" in type, in enum or in an anyOf branch
boolean exclusiveMinimum and exclusiveMaximumtheir numeric form
example in a schemaexamples: [example]
x-jsonschema-* extensionsthe JSON Schema keywords they carry
x-oai-license-identifierthe license identifier

What is lost:

  • allowEmptyValue and allowReserved on 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.1Becomes
array-form items (JSON Schema 2019-09 and older)prefixItems
an object where an array is requiredan array of its values
xml.attribute and xml.wrappedxml.nodeType. With both, attribute wins
x-tagGroupstags[].parent, only when the mapping is unambiguous
registered x-oai-* extensionsthe 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:

  • allowReserved on 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:

SettingRequiredDefaultWhat it does
specyesthe description relative to Cargo.toml; a list [“a.yaml”, “api/*.yaml”] merges several
outputno"src/<module>"the module directory
clientnotruegenerate the client; a table sets its adapters = [“reqwest”] and operations = [“getOrder”]
servernotruegenerate the server; a table sets its adapters = [“axum”] and allow_unimplemented = true
testsnofalsegenerate a test that the description’s examples decode
unknown_fieldsno"drop"“keep”: objects without additionalProperties keep unknown keys
overlaysno[]Overlays (1.0 to 1.2) applied in order to the spec
formatsnothe dependencieslibrary types of string formats, like { uuid = true, dates = “chrono” }
derivesno{}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:

ValueWhat is generatedRuntime features
client = falseno clientnone for the client
client = truethe client; you bring a transport of your ownclient
client = { adapters = ["reqwest"] }the client and ReqwestTransportclient, reqwest
client = { adapters = ["reqwest"], operations = ["getOrder"] }the client with one operationclient, reqwest
server = { adapters = ["axum", "tracing"] }the server, into_axum and a span per requestserver, axum, tracing
server = { allow_unimplemented = true }the server; a method you do not write answers 501server

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 (/login under /_matrix/client/v3 is /_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 xml for 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 From impls.

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 generate at a virtual workspace root runs for every member with module tables. check does too.
  • cargo honig generate -p shop runs for the member shop only. cargo honig generate billing runs for each member with the module billing.
  • A member with honig = { workspace = true } lists its features. generate pins the version in the root’s [workspace.dependencies].

Types

Request and response types

A schema with readOnly or writeOnly properties becomes two types:

TypeUsed forFields
Loginresponsestoken (readOnly). No password.
LoginRequestrequest bodies and parameterspassword (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.

  • Otherwise holds every other value. Its type has the base properties.
  • A lone if/then/else becomes the same kind of enum. else is the Otherwise variant. else: false leaves none.
  • An if on enum: [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.

FormatWithout its libraryWith uuid, url, ipnet and chronoWith jiff in place of chrono
uuidStringuuid::Uuiduuid::Uuid
date-timeStringchrono::DateTime<chrono::Utc>jiff::Timestamp
dateStringchrono::NaiveDatejiff::civil::Date
ipv4std::net::Ipv4Addrstd::net::Ipv4Addrstd::net::Ipv4Addr
ipv6std::net::Ipv6Addrstd::net::Ipv6Addrstd::net::Ipv6Addr
timeStringchrono::NaiveTimejiff::civil::Time
base64urlapi::Base64Urlapi::Base64Urlapi::Base64Url
decimalStringStringString
charcharcharchar
date-time-localStringchrono::NaiveDateTimejiff::civil::DateTime
time-localStringchrono::NaiveTimejiff::civil::Time
uriStringurl::Urlurl::Url
ipv4-cidrStringipnet::Ipv4Netipnet::Ipv4Net
ipv6-cidrStringipnet::Ipv6Netipnet::Ipv6Net
emailapi::Emailapi::Emailapi::Email
idn-emailapi::IdnEmailapi::IdnEmailapi::IdnEmail
hostnameapi::Hostnameapi::Hostnameapi::Hostname
idn-hostnameapi::IdnHostnameapi::IdnHostnameapi::IdnHostname
http-dateStringStringString
durationStringStringString
uri-referenceStringStringString
iriStringStringString
iri-referenceStringStringString
json-pointerStringStringString
relative-json-pointerStringStringString
regexStringStringString
uri-templateStringStringString

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());
FormatTypeAccepts
emailapi::EmailAn 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-emailapi::IdnEmailAn RFC 6531 mail address (format: idn-email): an Email that may hold UTF-8.
hostnameapi::HostnameAn RFC 1123 host name (format: hostname) with ASCII labels. A punycode label must decode to a valid name.
idn-hostnameapi::IdnHostnameAn 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 untyped additionalProperties
  • the Other of 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 &params 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
}

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:

FlowMethods
Authorization code (PKCE)Client::authorization_url_<s>(..., &pkce) and then exchange_code_<s>(code, ..., &pkce)
Passwordauthorize_password_<s>(user, password, client_id, secret, scopes)
ImplicitClient::implicit_url_<s>(...)
Refreshrefresh_<s>(refresh_token, client_id, secret)
OpenID Connect and RFC 8414discover_<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:

PieceWhat it doesLimits
RetryTransientMiddlewareIt 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.
IdempotentOnlyIt lets only GET, HEAD, OPTIONS, PUT and DELETE through to the retry.None.
CacheIt 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:

VariantMeaning
TransportThe request could not be sent or the connection broke off (connection or TLS for example).
EncodeA parameter or the body could not be serialized.
DecodeA documented response does not fit its schema. pointer says where.
UnexpectedMediaThe status is declared but the response’s Content-Type is none that the description declares for it.
NotModified304 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.
UnexpectedStatusA status that the operation declares neither as itself nor as a default.
InvalidAn item of a request body still arriving breaks the description’s constraints.
TooLargeA 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:

  1. Depend on gloo-net with its http feature under [target.'cfg(target_arch = "wasm32")'.dependencies]. Native builds then skip it, as the adapter compiles on wasm32 only.
  2. Set client = { adapters = ["gloo-net"] } and server = false.
  3. 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:

  1. Routing: an undeclared path is 404. An undeclared method is 405. A HEAD takes the GET of its path and gets its headers without the body.
  2. Credentials: the security of the operation. If none of its requirements are present then the answer is 401.
  3. Your layers as an http::Request<Body> in the order that you add them. The first one is the outermost. Its extensions hold the generated Operation, the RequestEvent and the credentials (Secured). The body is not read yet. So a refused request costs no body read. read_body reads it for a layer that needs it.
  4. The body: read whole up to max_body_bytes (413). An operation that streams its body skips this step.
  5. 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:

RequestResponse
No Range200 with Accept-Ranges: bytes
Range: bytes=1000-, bytes=0-499 or bytes=-500206 Partial Content: those bytes and Content-Range: bytes 1000-4999/5000
A range that starts past the end416 Range Not Satisfiable with Content-Range: bytes */5000
If-Range next to it with an ETag or date that the body no longer has200: 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:

VariantMeaning
StatusThe HTTP status as a number (code or status).
StatusTextThe HTTP status as text (code declared as a string).
TitleThe reason phrase (title).
DetailWhat went wrong (message, detail or error).
Typeabout:blank (type).
ViolationsEvery violation as {path, message} (errors or violations).
ViolationMessagesEvery violation as one string each (errors of strings).
ConstA required const (object: {const: error}): its one value, as JSON text.
EmptyA 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 Blob fails the chunk that goes past the limit. The handler gets that error, and ? answers 413 in the error schema of the description.
  • read_body in 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 securityctx.principalWhen authenticate found nobody
none (security: [])()the handler runs
an empty alternative ([{}, {apiKey: []}])Option<Principal>the handler runs with None
credentials requiredPrincipal401 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_layer runs once routing found the operation and its credentials passed. Its extensions hold the operation, the credentials and, after authenticate, 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::layer runs 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());
TopicWhat to know
Stagelambda_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 addressThere is no socket. API Gateway’s sourceIp is in ctx.extension::<lambda_http::request::RequestContext>().
Binary bodiesA REST API decodes them only for the media types in its binaryMediaTypes.
Body sizeAPI 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.

FeatureCrateAddsOn when
clienttower-serviceThe generated client: the Transport bound over tower services and TowerTransportYou generate the client
servertower-serviceThe generated server: a tower Service, routing, conditional requests and the wide eventYou generate the server
reqwestreqwestReqwestTransport: async client with streaming bodiesclient = { adapters = ["reqwest"] }
reqwest-middlewarereqwest-middlewareReqwestMiddlewareTransport: retries, tracing and caching from your middleware stackclient = { adapters = ["reqwest-middleware"] }
urequreqUreqTransport: blocking clientclient = { adapters = ["ureq"] }
gloo-netgloo-netGlooTransport: browser fetch on wasm32 onlyclient = { adapters = ["gloo-net"] }
axumaxumServer::into_axum and the address of the client from the ConnectInfo of axumserver = { adapters = ["axum"] }
tracingtracingA span per request and a log line for each wide eventserver = { adapters = ["tracing"] }
tracing-opentelemetryopentelemetryW3C Trace Context: traceparent and tracestateadapters = ["tracing-opentelemetry"] in client or server
ipnetipnetformat: ipv4-cidr and ipv6-cidr checksThe description calls for it
idnidnaemail, idn-email, hostname and idn-hostname checksThe description calls for it
regressregresspattern and patternProperties checks (ECMA-262)The description calls for it
oauthThe OAuth 2.0 flows of the client: token grants, device authorization and discoveryThe description calls for it
pkcesha2Pkce, authorization_url and exchange_code: the OAuth 2.0 authorization code flow. Outside wasm32 Pkce::new makes a verifier from OS randomnessThe description calls for it
cookiecookieCookie parameters and API keysThe description calls for it
multipartmultermultipart/* bodies and partsThe description calls for it
base64base64Binary data in JSON (format: byte, contentEncoding, base64url) and http basic credentialsThe description calls for it
xmlquick-xmlXML bodies and partsThe description calls for it
simdsonic-rsSIMD 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 itYou 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

FileContents
mod.rsThe root of the module. It declares the other files and re-exports the client, the server and the runtime.
types.rsThe schemas of the description as Rust types: structs, enums and newtypes.
operations.rsOne module per operation with its Params, its Response enum and their body types.
client.rsThe Client with one method per operation, and the WebhookClient when the description has webhooks.
server.rsThe Api trait with one method per operation, the router and the Server of this API.
runtime.rsThe runtime items that the generated code calls, re-exported from honig.
documented_examples.rsWith 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.