Chapters

Guide ยท v0.5

Configuration

One Config holds the server, the limits, the timeouts, the proxy, and the profile. Optional pieces read their own groups: auth for crocket::auth, database for crocket::db. Core crocket never opens a database or fetches a JWKS on its own.

Precedence

Settings stack, and each layer beats the one before it:

  1. The built-in defaults, or the Config you pass to from_env when your program wants different ones.
  2. The dev profile, when CROCKET_PROFILE=dev.
  3. The other CROCKET_* environment variables.
  4. Whatever you assign in code after from_env returns.
  5. The fields you pass to launch({...}).
cpp
Config cfg = Config::from_env({.server = {.port = 50051}});
cfg.timeouts.request = 10s;
return crocket::build(cfg)
    .mount("/", reflect_routes<^^api>())
    .launch({.listen = "0.0.0.0:50051"});

from_env's argument replaces the built-in defaults, and the environment can still override it. That is how a gRPC server defaults to port 50051 without ignoring CROCKET_PORT. launch() with no argument serves on cfg.server. .listen takes "8080", ":8080", "0.0.0.0:8080", or "[::1]:8080".

A value that does not parse throws std::invalid_argument naming the variable, so a typo stops the program at startup. Sizes take K, M, or G (powers of 1024). Durations take ms, s, m, or h, and a bare number is seconds. Booleans are true/false, 1/0, yes/no, or on/off. Lists are comma-separated. Unset or empty leaves the setting alone.

Limits

Every resource a client can make the server hold has a bound. Past it, the request fails or the connection waits, as the table says. The defaults follow h2o for connections and HTTP/2, and Rocket for a JSON body.

LimitDefaultPast it
max_connections1024New connections wait in the accept queue
max_connections_per_ip0 (none)A new connection from that address is closed
http2_max_streams100Advertised in the HTTP/2 SETTINGS
max_header_bytes, max_header_count8 KiB, 100431 headers.too_large
max_body_bytes1 MiB413 body.too_large
max_body_memory256 MiB503 server.busy
etag_max_bytes1 MiBNo automatic ETag
max_in_flight1024503 server.busy
timeouts.request30 s504 deadline.exceeded
timeouts.drain10 sIn-flight requests are dropped after this

max_connections_per_ip is off by default because, behind a load balancer, every connection comes from the balancer. Set it when clients connect directly. h2o also closes a connection that takes more than 10 seconds to send its headers, or that sits idle on HTTP/2 for 10 seconds (GOAWAY).

Dev profile

CROCKET_PROFILE=dev selects Config::dev(). Unset or release uses the release defaults. The dev profile binds 127.0.0.1 when the host is empty, prints every route, turns on GET /__routes, puts error detail in the body, uses a one-hour deadline, and drains in one second. Its logs are readable lines. Release logs are structured. allowed_hosts in the dev profile also accepts localhost, 127.0.0.1, and ::1.

Behind a proxy

Client reports the peer address and whether the connection was https or http. Behind a proxy, list the proxies you run. crocket then takes both from the header they add.

cpp
Config cfg;
cfg.proxy.trusted = {"10.0.0.0/8"};
cfg.proxy.header = ProxyHeader::XForwardedFor;  // the default
cfg.proxy.allowed_hosts = {"api.example.com", "*.example.com"};

Only trusted proxies are believed. Behind a chain, the client is the first address that no trusted proxy is behind, so a value the client wrote into X-Forwarded-For itself is never picked. Only the configured header is read. The other is ignored.

allowed_hosts is the host names the server answers. Any other Host (:authority on HTTP/2) is 400 host.invalid before routing. Ports are not compared. *.example.com matches subdomains and not example.com itself. An empty list allows every host. A malformed entry fails ignite.

CROCKET_TRUSTED_PROXIES, CROCKET_PROXY_HEADER (x-forwarded-for or forwarded), and CROCKET_ALLOWED_HOSTS set the same fields.

Environment variables

The names you set most often:

VariableDefault
CROCKET_PROFILErelease
CROCKET_PORT8000
CROCKET_HOST0.0.0.0 (127.0.0.1 in dev)
CROCKET_LISTENunset. Replaces host and port
CROCKET_TLS_CERT, CROCKET_TLS_KEYunset. TLS needs both
CROCKET_HTTP2true
CROCKET_H2_PRIOR_KNOWLEDGEfalse
CROCKET_WORKERSat least 4, one per core, raised to the largest blocking pool
CROCKET_EVENT_LOOPSone per physical core
CROCKET_LOG_LEVELinfo (debug in dev)
CROCKET_LOG_SAMPLE1 (every successful request)
CROCKET_LOG_SLOW500ms
CROCKET_REQUEST_TIMEOUT30s (an hour in dev)
CROCKET_DRAIN_TIMEOUT10s (1s in dev)
CROCKET_DATABASE_URLunset (libpq's PG* variables)
CROCKET_DATABASE_POOL_SIZE8
CROCKET_AUTH_ISSUER, CROCKET_AUTH_AUDIENCE, CROCKET_AUTH_JWKSunset
CROCKET_AUTH_SECRETunset (HMAC off)

CROCKET_AUTH_* and CROCKET_DATABASE_* do nothing until you link crocket::auth or crocket::pg and construct the verifier or the pool from cfg. The limit variables (CROCKET_MAX_BODY_BYTES and the rest) map onto the table above, one name per field.

Edit this page