Crate espresso_api 

Espresso API server with both Axum (HTTP/JSON) and gRPC endpoints

Modules

axum 🔒

Axum HTTP/JSON API handlers

error

Typed API errors for proper HTTP/gRPC status code mapping

proto

The v2 API contract, generated by build.rs from the proto files in proto/: message types, the tonic server traits, and the protoJSON Serialize/Deserialize impls that define the HTTP wire encoding. render builds these messages from consensus types.

render 🔒

Consensus and query service types rendered as v2 proto messages.

rest

Axum REST handlers derived from the google.api.http annotations, transcoding HTTP/JSON onto the tonic service traits.

routes

v1

V1 API module - legacy APIs

Structs

OptionalModules

Which of the optional API modules to serve, for modes that make them conditional (mirroring Options::submit/Options::config/Options::explorer).

Constants

FILE_DESCRIPTOR_SET

The compiled proto descriptor set, for gRPC reflection.

Functions

apply_connection_limit 🔒

Shared budget: a request holds a slot until its handler returns, excess gets 429. A stream (websocket or SSE) releases its slot once the response starts, so open streams are not capped here, see axum::limit_requests.

bind_api 🔒

Add the reserved top-level routes, apply the optional concurrency limit, rewrite legacy URIs, and bind/serve the router. Shared by all serve_axum* entry points. Bind before composing routers: OpenAPI generation takes ~0.5s in debug builds, and clients connecting during it should queue in the accept backlog rather than get refused.

create_router_v1

Create v1 router with OpenAPI documentation.

merge_hotshot_modules 🔒

router_v2 🔒

The v2 REST routes exactly as serve_axum mounts them. Extracted so the test asserting every documented route is mounted exercises the same construction; don’t inline it back.

serve_axum

Start Axum HTTP server with combined v1 and v2 APIs

serve_axum_bare

Serve the bare API (no query or status module): only the HotShot modules are available, since the only app state is the HotShot handle. State-signature is always on; the rest follow Options, matching Options::init_hotshot_modules.

serve_axum_fs

Serve the query API used by the filesystem-backed storage mode: status, availability, node, token, catchup, and state-signature are always on (tide registered them unconditionally); submit and config follow Options. Filesystem storage doesn’t implement the reward/merklized-state/explorer/database traits, so those modules aren’t served (a request to one of their routes 404s, matching tide).

serve_axum_status

Serve the status-only API: no availability/node/token data source is available, so only status and the HotShot modules (submit, catchup, state-signature, config) can be served. State-signature is always on; the rest follow Options.

serve_router 🔒

serve_tonic

Start Tonic gRPC server. The gated services follow their module flag like the REST side; the reflection service still lists them, so a disabled deployment answers them with Unimplemented.

url

Build a full request URL from a server base URL and a path produced by one of the routes::v1::* builders.