Crate nest_rs_http 

HTTP transport for nestrs — a nest_rs_core::Transport backed by poem.

HttpTransport mounts every #[routes] controller, every self-mounting endpoint another surface declares (a GraphQL schema, an MCP service — each via HttpEndpointMeta), and any extra endpoint registered with HttpTransport::mount.

Re-exports

pub use poem;

pub use schemars;

Modules

endpoint_wrap_priority

Canonical priority bands for transport-edge wraps, mirroring the documented HTTP wrap order (outermost → innermost):

Structs

ClientIp

Best-effort client IP for the current request. Always present (see the module doc for the resolution order and the security caveat).

CorsConfig

Cross-Origin Resource Sharing policy. origins empty ⇒ no CORS layer installed (the default). Lists are comma-separated in env vars.

Ctx

Extracts a request-scoped value of type T an upstream guard or interceptor attached.

GlobalGuardsActive

Marker provided by use_guards_global when at least one global guard is registered. The transport reads it (it cannot see the Guard trait or GuardSpecs) to decide whether an unguardable endpoint — an imperative mount(...) the transport can neither shape nor introspect — is a fail-secure violation.

HttpBootCheck

A boot-time check the HTTP transport runs at the start of configure. Returning Err(message) aborts boot with that message.

HttpConfig

HTTP transport options resolved at boot. Every field is settable both via NESTRS_HTTP__* env vars (read by Config::from_env) and via the pinned struct (passed to HttpModule::for_root).

HttpControllerMeta

Discovery metadata attached to every #[controller] + #[routes] type. crate::HttpTransport iterates these at boot via nest_rs_core::DiscoveryService::meta; apps can read the same metadata to drive secondary concerns (OpenAPI rendering, route listings).

HttpEndpointMeta

Discovery metadata for a self-mounting HTTP endpoint owned by another surface (a GraphQL schema, an MCP streamable-HTTP service). The closure nests one opaque sub-endpoint at its own path; path and label exist only so the transport can list the mount in its boot-time route log.

HttpEndpointWrap

Discovery metadata attached at boot. The HTTP transport collects every HttpEndpointWrap at configure time, sorts by priority(), and folds them around the assembled route (after per-route layers, before CORS / server header).

HttpModule

HttpRouteMeta

Declarative description of a handler in a controller — verb/path/name plus the OpenAPI facets #[routes] extracts, so a doc generator (nestrs-openapi) builds a spec from discovery alone.

HttpSetup

HttpTransport

HTTP Transport backed by poem. At Transport::configure time, runs every discovered HttpBootCheck, mounts every #[module(providers = [...])]-declared HttpControllerMeta and HttpEndpointMeta, then any imperative HttpTransport::mount, then folds every discovered HttpEndpointWrap wrap around the assembled endpoint. Transport-edge wraps (the global interceptor / filter pools, infra #[interceptor]s like DbContext) attach themselves through HttpEndpointWrap from their own crates — this transport stays free of the cross-transport trait crates and only knows about poem. Guards and pipes never wrap here: they execute in the per-route shaper (post-routing) or at a Guarded self-mount’s edge.

Piped

Applies pipe P to the value extractor E produces, handing the handler the transformed P::Out.

ProblemDetails

Body of an application/problem+json response. Stable URIs for the well-known constructors live at https://www.rfc-editor.org/rfc/rfc9457 — type is the only field a client may key on, so the URIs are stable across releases (and overridable via with_type when an app wants to publish its own type registry).

RawBody

Whole request body as Bytes, bounded by RawBody::DEFAULT_LIMIT (or by the RawBodyLimit in the request extensions, when installed).

RawBodyLimit

Per-request byte cap for RawBody, read from the request extensions. HttpModule installs this from HttpConfig.max_body_bytes; absent ⇒ the extractor falls back to RawBody::DEFAULT_LIMIT. Public so middleware can pin a per-route cap by inserting it into req.extensions_mut().

Reflector

RequestScopeEndpoint

Installs a fresh RequestScope (over the singleton container) into each request’s extensions before delegating inward, so guards and handlers can resolve request-scoped providers via Scoped<T>. Applied outermost by HttpTransport.

Scoped

Resolves a provider of type T from the current request’s RequestScope. Rejects with 500 if the scope is absent (a transport wiring bug) or if no provider is registered for T.

SelfMountGuardWrap

Discovery metadata that wraps a single EdgePosture::Guarded self-mount with the global guard chain. Provided by nest-rs-guards’ use_guards_global (which can see the Guard trait); applied by the HTTP transport, which cannot — the closure keeps this crate free of any guard dependency, the same inversion HttpEndpointWrap uses. Absent when no global guard is registered, in which case guarded self-mounts mount unwrapped.

ShapedEndpoint

TlsConfig

TLS material for the HTTP transport: a PEM certificate chain and private key, handed to HttpTransport::tls.

Valid

Validation pipe: extract E, validate with validator::Validate, reject invalid input with a field-level JSON 400. Valid<Json<T>> is the ergonomic form of Piped<ValidationPipe<T>, Json<T>>.

Enums

EdgePosture

How a self-mounted endpoint relates to the global guard pool.

HttpVerb

Traits

Controller

Implemented automatically by the #[routes] macro. Each controller mounts its routes (prefixed with the controller’s PATH) onto a parent Route.

IntoInner

Owned-unwrap for poem extractors, so a pipe can take the value they carry without cloning.

RouteResponseShaper

A handler wrapper keyed by a marker type. #[routes] applies it when a handler declares a parameter of an implementing type.

Functions

join_path

Join a controller prefix with a route path the way poem’s nesting does: ("/health", "/live") -> "/health/live". Public so nestrs-openapi composes paths identically to how this transport mounts them — the served path and the documented path must not drift.

schema_of

Kept here so #[routes] emits ::nest_rs_http::schema_of::<T> and never names schemars’ generator API itself.

shaped

version_path

Apply URI API versioning: Some("1"), "/users" → "/v1/users". The single place the URI strategy lives — #[routes], the boot route log, and the OpenAPI document all route through it so the served/logged/documented paths can never drift.

Type Aliases

SchemaFn

Builds the schema for a Json<T> request body or response, recording named component schemas in the shared generator. #[routes] emits one per JSON payload it finds; a non-Json<…> body/return carries None and imposes no JsonSchema bound.

Attribute Macros

async_trait

controller

#[controller(path = "/health")] — paired with #[routes] on the impl block. Generates from_container(&Container) -> Self and a pub const PATH.

crud

Generate standard REST operations (list/get/create/update/delete) on a #[controller] impl block, re-emitting under #[routes]. Grammar: #[crud(entity = …::Entity, output = Dto, create = CreateDto, update = UpdateDto, readonly, paginate = cursor|page)].

http_code

#[http_code(N)] — override the response status (100..=999). Passthrough marker consumed by #[routes]. Mutually exclusive with #[redirect].

input

#[input] — shorthand for input DTOs. Appends #[derive(::serde::Deserialize, ::validator::Validate)] and #[serde(deny_unknown_fields)] so an unknown field on the wire (e.g. is_admin: true) is rejected at parse time instead of silently dropped.

interceptor

Mark a struct as a global HTTP interceptor. Behaves like #[injectable] for construction and additionally emits a Discoverable impl attaching an HttpEndpointWrap; the HTTP transport reads those metas at boot. The struct must implement nest_rs_interceptors::Interceptor.

redirect

#[redirect("url"[, code])] — discard the handler’s payload and return a redirect. Status defaults to 307 and must be in 300..=399. Mutually exclusive with #[http_code]. The decorated method’s body must be empty — #[routes] does not call it. Passthrough marker consumed by #[routes].

response_header

#[response_header("name", "value")] — append a header to the response. Stacks with #[http_code] and #[redirect]; repeatable. Passthrough marker consumed by #[routes].

routes

Bind controller methods to HTTP routes. Applied to an impl block belonging to a #[controller]-marked struct. Each method tagged with #[get("/path")], #[post], #[put], #[delete], or #[patch] is wired as a poem handler.