Skip to content

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:

crates/features/src/hello/http/module.rs
use nest_rs::core::module;
use super::controller::HelloController;
use crate::hello::HelloModule;
#[module(
imports = [HelloModule],
providers = [HelloController],
)]
pub struct HelloHttpModule;
apps/hello/.env
NESTRS_HTTP__PORT=3000

Or 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:

apps/api/src/module.rs
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.

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.

FieldEnv variableDefaultPinned form
host<PREFIX>_HTTP__HOST0.0.0.0HttpConfig { host: "127.0.0.1".into(), ..Default::default() }
port<PREFIX>_HTTP__PORT3000HttpConfig { port: 3002, ..Default::default() }
tls.cert<PREFIX>_HTTP__TLS_CERT (inline PEM) or <PREFIX>_HTTP__TLS_CERT_FILE (path)unset ⇒ plain HTTPHttpConfig { tls: Some(HttpTls::new(cert, key)), ..Default::default() }
tls.key<PREFIX>_HTTP__TLS_KEY or <PREFIX>_HTTP__TLS_KEY_FILEunset ⇒ 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 filesin 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 offHttpCors { origins: vec!["https://app.example.com".into()], ..Default::default() }
cors.methods<PREFIX>_HTTP__CORS_METHODSemptymethods: vec!["GET".into(), "POST".into()]
cors.headers<PREFIX>_HTTP__CORS_HEADERSemptyheaders: vec!["Content-Type".into()]
cors.exposed_headers<PREFIX>_HTTP__CORS_EXPOSED_HEADERSempty — Link, Location and Retry-After, which the framework sends, are always exposedexposed_headers: vec!["X-Total-Count".into()]
cors.credentials<PREFIX>_HTTP__CORS_CREDENTIALS (true/false)falsecredentials: 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 secondsmax_age: Some(Duration::from_secs(3600))
versioning<PREFIX>_HTTP__VERSIONING (uri, header, media_type)uriHttpConfig { versioning: ApiVersioning::Header, ..Default::default() } — see Versioning
version_header<PREFIX>_HTTP__VERSION_HEADERX-API-VersionHttpConfig { version_header: "X-Version".into(), ..Default::default() }
default_version<PREFIX>_HTTP__DEFAULT_VERSIONunset ⇒ no defaultHttpConfig { default_version: Some("1".into()), ..Default::default() }
server_header<PREFIX>_HTTP__SERVER_HEADER (true/false)falseHttpConfig { server_header: true, ..Default::default() }
access_log<PREFIX>_HTTP__ACCESS_LOG (true/false)trueHttpConfig { access_log: false, ..Default::default() } — see Access log
trusted_proxies<PREFIX>_HTTP__TRUSTED_PROXIES (comma list of addresses and CIDR ranges)emptyHttpConfig { 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 prefixHttpConfig { global_prefix: Some("/api".into()), ..Default::default() }
max_body_bytes<PREFIX>_HTTP__MAX_BODY_BYTES (bytes)2 MiBHttpConfig { max_body_bytes: 4 * 1024 * 1024, ..Default::default() }
request_timeout<PREFIX>_HTTP__REQUEST_TIMEOUT_SECS (seconds, 0 ⇒ off)20 sHttpConfig { request_timeout: Some(Duration::from_secs(15)), ..Default::default() }
max_concurrent_connections<PREFIX>_HTTP__MAX_CONCURRENT_CONNECTIONS (1–1048576)10 000HttpConfig { max_concurrent_connections: 50_000, ..Default::default() }
header_read_timeout<PREFIX>_HTTP__HEADER_READ_TIMEOUT_SECS (seconds, 1–300)30 sHttpConfig { header_read_timeout: Duration::from_secs(10), ..Default::default() }
body_read_timeout<PREFIX>_HTTP__BODY_READ_TIMEOUT_SECS (seconds, 1–3600)10 sHttpConfig { body_read_timeout: Duration::from_secs(15), ..Default::default() }
idle_timeout<PREFIX>_HTTP__IDLE_TIMEOUT_SECS (seconds, 1–3600)75 sHttpConfig { idle_timeout: Duration::from_secs(620), ..Default::default() }
send_timeout<PREFIX>_HTTP__SEND_TIMEOUT_SECS (seconds, 1–3600)60 sHttpConfig { send_timeout: Duration::from_secs(120), ..Default::default() }
shutdown_timeout<PREFIX>_HTTP__SHUTDOWN_TIMEOUT_SECS (seconds, 1–3600)20 sHttpConfig { shutdown_timeout: Duration::from_secs(55), ..Default::default() }
sse_max_connection<PREFIX>_HTTP__SSE_MAX_CONNECTION_SECS (seconds, 0 ⇒ unlimited)4 hHttpConfig { 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 sHttpConfig { 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_POLICYon (safe values)HttpConfig { security_headers: HttpSecurityHeaders { enabled: false, ..Default::default() }, ..Default::default() }
compression<PREFIX>_HTTP__COMPRESSION (true/false)falseHttpConfig { 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).

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.

Terminal window
# 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 it
NESTRS_HTTP__TLS_CERT_FILE=/etc/letsencrypt/.../fullchain.pem \
NESTRS_HTTP__TLS_KEY_FILE=/etc/letsencrypt/.../privkey.pem \
nestrs run dev api

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 warn on nest_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.

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:

.env.production
NESTRS_HTTP__GLOBAL_PREFIX=/api

or pin it in code:

apps/api/src/module.rs
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.

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:

.env.development
NESTRS_HTTP__SERVER_HEADER=true
apps/api/src/module.rs
HttpModule::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.