Crate actus_controller 

Public API types and utilities for the Actus controller system — the Controller trait, the typed Params / ExtractedParams, the route metadata (Verb, ParamDef, RouteDef), and the route-resolution routing helpers. This is what user code and the #[controller] / routes! / app_routes! macros’ generated code interact with.

Modules

reply

Contains the user-facing API for creating replies.

routing

Route resolution helpers — matching a request path + verb against a controller’s &[RouteDef] and extracting the path/query/body parameters. Used by the #[controller] macro’s generated dispatch; exposed for tools and tests that need to resolve routes directly.

Macros

app_routes

Declares the application’s URL blueprint and generates its init().

reply

Creates a Reply (a Result<ReplyData, WebError>) for a success case.

routes

A marker macro to define routes within a #[controller] impl block. The #[controller] procedural macro is responsible for parsing this.

Structs

ExtractedParams

Parameters extracted after route resolution — path captures plus the declared query and body values. The #[controller] macro reads typed handler arguments out of this; application code rarely touches it directly.

ParamDef

The compile-time description of one route parameter, recorded by the routes! macro and used to extract and parse it at request time.

Params

Raw parameters from the HTTP request, plus headers, the parsed body, and a typed extensions slot for per-request data that prepare hooks (or middleware) want to attach for handlers to read.

ProblemDetails

Structured error response shaped like an RFC 7807 Problem Details document, plus arbitrary extension members that get serialized into the JSON body.

ReplySpec

A builder for a reply with an explicit status and/or headers wrapped around a payload. Start one with build_reply, chain the setters, and finish with ReplySpec::done (which yields a ReplyData::Rich).

RouteDef

The compile-time description of one route in a controller, recorded by the routes! macro. The framework matches and dispatches against these, and tools can introspect them (e.g. the OpenAPI generator).

SseEvent

One frame in a Server-Sent Events stream. A frame may carry data (the common case), a comment (heartbeats and debug pings), and the optional event / id / retry fields. The wire encoding is handled by SseEvent::to_bytes — embedded newlines in data become multiple data: lines, the way the spec requires.

StatusCode

An HTTP status code (status-code in RFC 9110 et al.).

Enums

ControllerMode

How a controller treats request parameters it didn’t declare.

ParamDefault

A parameter’s default value, applied when the request omits it. Declared in routes! as name: Type = default.

ParamSource

Where a parameter’s value is read from.

ParamType

The declared type of a route parameter — governs how its raw string value is parsed before reaching the handler.

ReplyData

The concrete payload of a successful reply. The Finalizer turns it into an HTTP response. Build one with the reply! macro or the reply::* constructor functions rather than by hand.

Verb

An HTTP method. Used in routes! verb prefixes and for the Allow header the framework stamps on 405 responses.

WebError

An error returned from a handler, a prepare hook, or middleware. Each variant maps to an HTTP status the framework renders as the response (WebError::Problem as an application/problem+json body).

Constants

DEFAULT_VERBS

Verbs accepted by a route declared without a verb prefix. Reflects the “verbs are constraints, not identities” stance: an unmarked route imposes no semantic restriction beyond what HTML forms emit natively. Restrictive verbs (PUT/DELETE/PATCH) and protocol verbs (HEAD/OPTIONS) must be opted into explicitly.

Traits

Controller

The runtime interface every controller implements. Hand-writing this is possible but unusual — the #[controller] macro generates the implementation (dispatch table, parameter extraction, the metadata methods) from a controller’s impl block and its routes! declaration.

DeclaresExpectation

Implemented by the #[controller] macro for every controller that declares expects = "…"; absent on a controller that declares nothing, which is the whole point. The families { … } block in app_routes! requires this trait of every controller mounted under a listed prefix, so a silently undeclared controller on a covered lane is a compile error — the on_unimplemented message below is the one the developer reads.

Family

A route family’s accepted floors, as a type — generated by app_routes! for each "prefix" => ["floor", …] entry in its families block, and handed to declares_expectation_in so the acceptance check can run in a const.

Functions

build_reply

Start a ReplySpec builder for a reply that needs an explicit status and/or headers on top of its body.

bytes

Build a ReplyData::Bytes with an explicit Content-Type. The content-type is required: there is no honest default for arbitrary bytes, and application/octet-stream masquerading as one tends to cause more bugs than it fixes (browsers guess; downstream HTTP caches mis-cache). Pass the right media type at the call site.

declares_expectation

Identity pass-through that only compiles for a controller implementing DeclaresExpectation. app_routes! wraps a mount’s construction expression in this when the mount falls under a families prefix declared without an accepted set — so presence of a declaration is checked at compile time, and any construction form (Foo { db }, Foo::new(db), make_foo()) works without the macro naming the type.

declares_expectation_in

declares_expectation, plus the value check: the controller’s DeclaresExpectation::EXPECTS must be one of F::ACCEPTS. The check is a const assertion evaluated when this instantiation is compiled — i.e. when the generated init() is reachable from something that runs, which in an application it always is. A failure reads as an E0080 naming the controller type in its “while instantiating” note. (The boot-time coverage check over Router::mounts() remains the backstop that needs no reachability.)

empty

An empty-body reply (204 No Content unless a status is set via build_reply).

floor_accepted

const-evaluable “is floor one of accepts”.

json

Build a JSON ReplyData from any Serialize value.

sse

Build a streaming Server-Sent Events response from a stream of SseEvents. Sets Content-Type: text/event-stream and Cache-Control: no-cache (without which an intermediate cache might hold the live stream, defeating the point).

str_eq

const-evaluable string equality (== on str is not const).

stream

Build a streaming-body reply from a stream of byte chunks. The body is written out as the stream yields, not buffered.

try_json

Fallible counterpart of json. Returns the raw serde_json::Error on failure so callers (notably the reply! macro) can map it to a structured response instead of panicking.

Type Aliases

BodyStream

A boxed, Send + Sync stream of body chunks, used by ReplyData::Stream and SSE responses.

Reply

A handler’s return type: Ok(ReplyData) for a success payload, or Err(WebError) for an error the framework renders as an HTTP error response. The reply! macro produces the Ok side.

Routes

A list of (mount, controller-factory) pairs — the route-registration shape the app_routes! macro builds when wiring controllers into a router.

Attribute Macros

async_trait

controller

Attribute macro for a controller’s impl block.