Module axum 

Axum HTTP/JSON API handlers

Modules

routes

Structs

ApiJson 🔒

Successful JSON response for v1 handlers, most of which return domain types (from espresso-types, hotshot-query-service, etc.) that don’t implement schemars::JsonSchema; this crate doesn’t add OpenAPI derives to domain types. Wire format is identical to axum::Json<T>; only the OpenAPI operation gets an untyped 200 response instead of a generated schema.

CustomError 🔒

ErrorResponse 🔒

API error response, wire-compatible with the Custom variant of the per-module error enums (node::Error::Custom, merklized_state::Error::Custom, etc.) that all of tide-disco’s Error::catch_all calls produce. Most of our migrated endpoints (catchup, submit, state-signature, light-client, node, status, config, token, database) take that path, so this envelope is byte-identical with tide’s error response for them. Endpoints that use a specific variant directly (e.g. availability::Error::FetchLeaf) emit their own shape on tide; those bytes are not matched here.

OpenApiV1 🔒

Wrapper so the v1 spec is looked up by a distinct type. v2 serves a build-time document rather than an Extension<OpenApi>, so nothing collides today, but the newtype keeps an Extension<OpenApi> added later from silently resolving to v1’s.

RequestLimit 🔒

In-flight request slots for max_connections.

Functions

create_router_v1

Create v1 router with OpenAPI documentation.

declare_path_template_parameters 🔒

decode_body 🔒

Decode a request body based on its Content-Type, matched by media-type essence.

encode_response 🔒

Encode a successful response body based on the request’s Accept header, matching tide-disco’s content negotiation.

finish_v1_docs

Build the OpenAPI spec for the mounted routes and attach the docs routes; every serve mode must route through this.

healthcheck 🔒

limit_requests 🔒

Each request holds a slot while in flight; excess gets 429. A websocket’s slot is released at the 101 upgrade: long-lived streams are deliberately unbounded here, since demo workloads (nasty-client holds hundreds of streams by design) dwarf the request budget of 25.

module_healthcheck 🔒

/v1/{module}/healthcheck, reached by legacy clients via the /{module}/healthcheck rewrite.

path_parameter_schema 🔒

Types read off the handlers’ Path<T> extractors; unknown names are strings.

redirect_to_docs 🔒

v2 is WIP, so / points at the v1 docs; 307 so browsers don’t cache the redirect.

rewrite_legacy_uri 🔒

Tide-disco served every v1 module at both /<module>/... and /v1/<module>/..., and legacy clients (surf-disco, the light-client, tests) still address the unversioned and /v0 forms. Axum only declares the /v1/... and /v2/... route shapes, and Router::layer middleware runs after routing, so it can never redirect a request onto a route it doesn’t already match. This function is instead wrapped around the whole router with tower::util::MapRequestLayer (see serve_axum), which runs before routing, to rewrite the URI so the declared routes match.

router_availability 🔒

router_block_state 🔒

router_catchup 🔒

router_config 🔒

router_database 🔒

router_explorer 🔒

router_fee_state 🔒

router_hotshot_events 🔒

router_light_client 🔒

router_node 🔒

router_reward 🔒

router_state_signature 🔒

router_status 🔒

router_submit 🔒

router_token 🔒

router_v2_docs

Serve the v2 API documentation: the build-time OpenAPI document and the two UIs that render it. Unlike finish_v1_docs, nothing here inspects the router, so a route that is generated but never mounted would still appear in the document; v2_documented_routes_are_mounted asserts that never ships.

serve_openapi_spec_v1 🔒

Serve the v1 OpenAPI spec (extracted from Extension)

swagger_html 🔒

Serve custom Swagger UI with collapsed defaults, pointed at the given OpenAPI spec route.

tag_operations_by_module 🔒

Declare a path parameter for every {name} template segment of every operation.

v2_error_envelope 🔒

Give framework-level rejections on the v2 routes the same error envelope as handler errors.

version 🔒

Tide-disco-compatible version response. Tide emits the binary’s clap version; we emit the crate version so http_client::Client::connect and similar polling helpers succeed.

with_top_level_routes 🔒

Add the routes that every mode serves regardless of which API modules are enabled: /, /healthcheck, /v1/healthcheck, /v2/healthcheck, /v1/{module}/healthcheck, and /version. Callers apply CORS.