HTTP configuration
HttpConfig — host, port, TLS, the mount prefix, the framework header — each field set by `<PREFIX>_HTTP__*` or pinned in code.
HttpModule attaches the HTTP transport at boot. Every controller and gateway
brings it bare, and the framework’s own mounts (GraphqlModule, McpModule,
HealthModule, OpenApiModule, …) import it — so the app imports what it serves
and the transport attaches once. A bare import reads every option from the
environment — what nestrs new scaffolds, the port in the app’s own .env:
use nest_rs::core::module;
use super::controller::HelloController;use crate::hello::HelloModule;
#[module( imports = [HelloModule], providers = [HelloController],)]pub struct HelloHttpModule;NESTRS_HTTP__PORT=3000Or pin HttpConfig in code at the app’s root, for what the code means
whatever the machine — the one reason a root names the transport:
use nest_rs::core::module;use nest_rs::http::{HttpConfig, HttpModule};
#[module(imports = [ HttpModule::for_root(HttpConfig { compression: true, ..Default::default() }),])]pub struct ApiModule;A pin takes the whole <PREFIX>_HTTP__* namespace off the .env cascade —
every field, the ones ..Default::default() filled included. The real
environment still overrides any field, but a key in a .env file no longer
reaches this config, and the boot names each such key at warn
(the dual-path rule). So the .env
examples on this page reach an app that pins nothing — the scaffold’s —
and a pinning app reads them from the real environment alone.
The app configures HTTP once. A feature crate that serves over HTTP — one
another app may compose — gets a bare HttpModule from its controllers, or, in
a module listing none, from its own imports: it reads the same
<PREFIX>_HTTP__*, and the app still runs one server, configured by its
for_root.
Default values: host 0.0.0.0, port 3000, no TLS (plain HTTP), no CORS,
no framework Server header, a 2 MiB request-body cap, a 20-second
request timeout, at most 10 000 open connections, a 20-second shutdown
window, the access log and the default security headers on.
HttpConfig fields
Section titled “HttpConfig fields”Every field of HttpConfig is settable both by env var and in the pinned
struct — the same dual-path rule every config in the framework follows.
Real env always wins over the .env cascade, and a pinned struct over every
.env file.
| Field | Env variable | Default | Pinned form |
|---|---|---|---|
host | <PREFIX>_HTTP__HOST | 0.0.0.0 | HttpConfig { host: "127.0.0.1".into(), ..Default::default() } |
port | <PREFIX>_HTTP__PORT | 3000 | HttpConfig { port: 3002, ..Default::default() } |
tls.cert | <PREFIX>_HTTP__TLS_CERT (inline PEM) or <PREFIX>_HTTP__TLS_CERT_FILE (path) | unset ⇒ plain HTTP | HttpConfig { tls: Some(HttpTls::new(cert, key)), ..Default::default() } |
tls.key | <PREFIX>_HTTP__TLS_KEY or <PREFIX>_HTTP__TLS_KEY_FILE | unset ⇒ plain HTTP | (set together with tls.cert) |
tls reload interval | <PREFIX>_HTTP__TLS_RELOAD_SECS (1–86400, 0 ⇒ unwatched) | 60 for a pair read from files | in a test: HttpTls::from_files(cert_path, key_path)?.with_reload(Some(Duration::from_secs(300))), None ⇒ unwatched — see Renewal without a restart |
cors.origins | <PREFIX>_HTTP__CORS_ORIGINS (comma list of scheme://host[:port], or *; see CORS) | unset or empty ⇒ CORS off | HttpCors { origins: vec!["https://app.example.com".into()], ..Default::default() } |
cors.methods | <PREFIX>_HTTP__CORS_METHODS | empty | methods: vec!["GET".into(), "POST".into()] |
cors.headers | <PREFIX>_HTTP__CORS_HEADERS | empty | headers: vec!["Content-Type".into()] |
cors.exposed_headers | <PREFIX>_HTTP__CORS_EXPOSED_HEADERS | empty — Link, Location and Retry-After, which the framework sends, are always exposed | exposed_headers: vec!["X-Total-Count".into()] |
cors.credentials | <PREFIX>_HTTP__CORS_CREDENTIALS (true/false) | false | credentials: true |
cors.max_age | <PREFIX>_HTTP__CORS_MAX_AGE_SECS (seconds, 1–86400, 0 ⇒ none) | unset ⇒ no Access-Control-Max-Age, the browser’s own few seconds | max_age: Some(Duration::from_secs(3600)) |
versioning | <PREFIX>_HTTP__VERSIONING (uri, header, media_type) | uri | HttpConfig { versioning: ApiVersioning::Header, ..Default::default() } — see Versioning |
version_header | <PREFIX>_HTTP__VERSION_HEADER | X-API-Version | HttpConfig { version_header: "X-Version".into(), ..Default::default() } |
default_version | <PREFIX>_HTTP__DEFAULT_VERSION | unset ⇒ no default | HttpConfig { default_version: Some("1".into()), ..Default::default() } |
server_header | <PREFIX>_HTTP__SERVER_HEADER (true/false) | false | HttpConfig { server_header: true, ..Default::default() } |
access_log | <PREFIX>_HTTP__ACCESS_LOG (true/false) | true | HttpConfig { access_log: false, ..Default::default() } — see Access log |
trusted_proxies | <PREFIX>_HTTP__TRUSTED_PROXIES (comma list of addresses and CIDR ranges) | empty | HttpConfig { trusted_proxies: vec![trusted_proxy!("10.0.0.1"), trusted_proxy!("10.0.0.0/8")], ..Default::default() }, each literal checked as the program compiles — see ClientIp |
global_prefix | <PREFIX>_HTTP__GLOBAL_PREFIX (one literal path: { } or : * < fail the boot) | unset ⇒ no prefix | HttpConfig { global_prefix: Some("/api".into()), ..Default::default() } |
max_body_bytes | <PREFIX>_HTTP__MAX_BODY_BYTES (bytes) | 2 MiB | HttpConfig { max_body_bytes: 4 * 1024 * 1024, ..Default::default() } |
request_timeout | <PREFIX>_HTTP__REQUEST_TIMEOUT_SECS (seconds, 0 ⇒ off) | 20 s | HttpConfig { request_timeout: Some(Duration::from_secs(15)), ..Default::default() } |
max_concurrent_connections | <PREFIX>_HTTP__MAX_CONCURRENT_CONNECTIONS (1–1048576) | 10 000 | HttpConfig { max_concurrent_connections: 50_000, ..Default::default() } |
header_read_timeout | <PREFIX>_HTTP__HEADER_READ_TIMEOUT_SECS (seconds, 1–300) | 30 s | HttpConfig { header_read_timeout: Duration::from_secs(10), ..Default::default() } |
body_read_timeout | <PREFIX>_HTTP__BODY_READ_TIMEOUT_SECS (seconds, 1–3600) | 10 s | HttpConfig { body_read_timeout: Duration::from_secs(15), ..Default::default() } |
idle_timeout | <PREFIX>_HTTP__IDLE_TIMEOUT_SECS (seconds, 1–3600) | 75 s | HttpConfig { idle_timeout: Duration::from_secs(620), ..Default::default() } |
send_timeout | <PREFIX>_HTTP__SEND_TIMEOUT_SECS (seconds, 1–3600) | 60 s | HttpConfig { send_timeout: Duration::from_secs(120), ..Default::default() } |
shutdown_timeout | <PREFIX>_HTTP__SHUTDOWN_TIMEOUT_SECS (seconds, 1–3600) | 20 s | HttpConfig { shutdown_timeout: Duration::from_secs(55), ..Default::default() } |
sse_max_connection | <PREFIX>_HTTP__SSE_MAX_CONNECTION_SECS (seconds, 0 ⇒ unlimited) | 4 h | HttpConfig { sse_max_connection: Some(Duration::from_secs(3600)), ..Default::default() } — see Streaming |
sse_keep_alive | <PREFIX>_HTTP__SSE_KEEP_ALIVE_SECS (seconds, 1–3600, 0 ⇒ none) | 15 s | HttpConfig { sse_keep_alive: Some(Duration::from_secs(30)), ..Default::default() } |
security_headers | <PREFIX>_HTTP__SECURITY_HEADERS_ENABLED (the switch), then each field’s name after SECURITY_HEADERS_: _CONTENT_TYPE_OPTIONS, _FRAME_OPTIONS, _HSTS, _REFERRER_POLICY, _CROSS_ORIGIN_OPENER_POLICY, _CROSS_ORIGIN_RESOURCE_POLICY, _CROSS_ORIGIN_EMBEDDER_POLICY, _PERMISSIONS_POLICY, _CONTENT_SECURITY_POLICY | on (safe values) | HttpConfig { security_headers: HttpSecurityHeaders { enabled: false, ..Default::default() }, ..Default::default() } |
compression | <PREFIX>_HTTP__COMPRESSION (true/false) | false | HttpConfig { compression: true, ..Default::default() } |
See Compression for what the flag negotiates and when to leave it off.
A long-lived connection’s ceiling is set per edge. An #[sse] stream, a
WebSocket and a GraphQL subscription
socket each authenticate once and keep those privileges until they end, and
each edge runs its own loop, so each reads its own variable —
<PREFIX>_HTTP__SSE_MAX_CONNECTION_SECS, <PREFIX>_WS__MAX_CONNECTION_SECS,
<PREFIX>_GRAPHQL__MAX_CONNECTION_SECS — from one default, four hours
(nest_rs::http::DEFAULT_MAX_CONNECTION). A deployment shortening how long a
revoked credential keeps a live socket sets the three. The same holds for a
server-sent stream’s keep-alive (SSE_KEEP_ALIVE_SECS, here and on
MCP, DEFAULT_SSE_KEEP_ALIVE) and a unit’s deadline
(REQUEST_TIMEOUT_SECS here, a WebSocket message’s and an MCP operation’s on
theirs, DEFAULT_UNIT_TIMEOUT).
Serve HTTPS
Section titled “Serve HTTPS”Setting both <PREFIX>_HTTP__TLS_CERT[_FILE] and <PREFIX>_HTTP__TLS_KEY[_FILE]
makes the transport serve over rustls instead of plain
HTTP, offering HTTP/2 then HTTP/1.1 to each client. Setting only one of the pair fails
the boot — a half-configured TLS is a deployment mistake, not a silent
fall back to plaintext. Setting both spellings of one half — TLS_CERT and
TLS_CERT_FILE — in the same tier fails the boot too, naming both, since
nothing says which was meant. Across tiers the process environment chooses,
as it does for every variable.
# Inline (suits k8s secrets, systemd EnvironmentFile, …)NESTRS_HTTP__TLS_CERT="$(cat fullchain.pem)" \NESTRS_HTTP__TLS_KEY="$(cat privkey.pem)" \nestrs run dev api
# Or by path — the transport reads the pair and keeps watching itNESTRS_HTTP__TLS_CERT_FILE=/etc/letsencrypt/.../fullchain.pem \NESTRS_HTTP__TLS_KEY_FILE=/etc/letsencrypt/.../privkey.pem \nestrs run dev apiRenewal without a restart
Section titled “Renewal without a restart”The two forms differ in one way that matters in production: material read
from files is watched. Every <PREFIX>_HTTP__TLS_RELOAD_SECS seconds (60 by
default, 0 to turn it off) the pair is re-read, and a renewed pair is swapped
into the running rustls config. The listener is not rebuilt — the port stays
bound, in-flight connections finish, and certbot’s --deploy-hook needs no
systemctl restart.
Two things it deliberately will not do:
- A pair it cannot read leaves the current certificate serving, with a
warnonnest_rs::http. A renewal tool that unlinks before it writes would otherwise take the listener down between two syscalls. - A pair is installed only once it reads back identical twice, so a file caught mid-flush is never the one that gets served.
That second rule has a limit worth knowing, because polling cannot see past it:
a renewal that writes the certificate and its key more than one interval
apart looks settled in between, and that pair is installed. Certbot and
cert-manager both swap atomically (a new lineage directory plus a symlink, a
remounted Secret), so this does not arise with either — but a hand-rolled hook
that writes the two files in sequence should write them together, or set
<PREFIX>_HTTP__TLS_RELOAD_SECS longer than the gap.
Inline PEM has no source to watch, so it is loaded once. In code the two forms
are two constructors: HttpTls::from_files(cert_path, key_path)? reads the pair
and watches it (.with_reload(Some(interval)) sets the interval, None stops
the watch), and
HttpTls::new(cert, key) takes inline PEM bytes. Production carries its
material in the environment, so the pinned form is a test’s: a suite hands
HttpTls::new the pair nest_rs::testing::TestAuthority issues in process.
Mounting under a shared prefix
Section titled “Mounting under a shared prefix”Behind a reverse proxy that hands off a sub-path (/api/*), every
controller can be mounted under one prefix without touching path = "…"
on each. Like every other field it follows the dual path — set it in the
environment:
NESTRS_HTTP__GLOBAL_PREFIX=/apior pin it in code:
use nest_rs::core::module;use nest_rs::http::{HttpConfig, HttpModule};
#[module(imports = [ HttpModule::for_root(HttpConfig { global_prefix: Some("/api".into()), ..Default::default() }),])]pub struct ApiModule;The prefix is normalized ("api", "/api", "/api/" all yield
Some("/api"); empty / "/" collapse to no-op), then applied as the route
table is built, to every route and every surface that mounts beside them —
#[get("/users")] is registered at GET /api/users, /graphql at
/api/graphql. What answers sees the path the client sent, prefix included:
a handler’s uri(), the template the span and the access line name
(/api/users/{id}), and the boot log. The OpenAPI document keeps its paths
prefix-free and states the prefix once, as its servers base URL. It is one literal
path: a route template’s braces, or a
:, * or < the router would read as a parameter, fail the boot naming
the variable.
Framework Server: header
Section titled “Framework Server: header”Off by default — a production-safe choice: no fingerprint of the
framework or its version is exposed. Flip on for local development to see
Server: nestrs/<crate version> on every response (the same shape Apache
and nginx use) — from a file when the app pins no HttpConfig:
NESTRS_HTTP__SERVER_HEADER=trueHttpModule::for_root(HttpConfig { server_header: true, ..Default::default()})The value is sourced from the nest-rs-http crate’s CARGO_PKG_VERSION at
build time — it tracks the framework, not your app version.
Going further
Section titled “Going further”- CORS and security headers — which origins a browser page may call from, and the headers every response carries.
- Limits and deadlines — the body cap, the request budget, the connection cap and deadlines, and the shutdown window.
- Controllers & routes — write the handlers this transport serves.
- Configuration — the framework-wide
<PREFIX>_<NS>__*scheme and the.envcascade.