Skip to content
NestRS

HTTP

NestRS’s HTTP layer is built on poem — listener, extractors, middleware. NestRS wraps it so a controller is a struct, routes come from #[routes], and the transport activates by importing HttpModule::for_root(...) in AppModule.imports — main never holds a transport.

Other HTTP-shaped surfaces — GraphQL, OpenAPI, MCP, WebSocket gateways — all mount on the same HttpTransport via HttpEndpointMeta, so a single binding (0.0.0.0:3002) serves them all. None of them runs its own port.

This category covers HTTP only — controllers, routes, response shaping, transport configuration. Authentication, authorization, and database queries each have their own category.

Install

Section titled “Install”
Terminal window
cargo add nest-rs-http

In this section

Section titled “In this section”
  • Configuration — HttpConfig, env vars vs pinned struct, TLS, CORS, the framework Server: header.
  • Controllers & routes — #[controller], #[routes], path/query/JSON extractors, typed returns.
  • Responses — Json<T>, status + body tuples, #[http_code], #[response_header], #[redirect].
  • Errors — ResponseError on a feature error enum, RFC 9457 ProblemDetails for one-off problem responses.
  • Extractors — the full extractor surface: RawBody, ClientIp, Scoped<T>, Ctx<T>, Reflector + #[meta(...)].
  • Versioning — #[controller(version = "1")] and multi-version controllers.

Going further

Section titled “Going further”
  • OpenAPI — a self-composing OpenAPI 3.1 spec + Swagger UI from the routes.
  • Guards — the primitive #[use_guards(...)] binds on a controller or route; how the layer chain dedups across transports.
  • Security — bind an AuthGuard and an AbilityGuard to attach the principal and gate actions per row.
  • GraphQL, WebSockets, MCP — each mounts on the same HttpTransport you configured here.