[server]

The listener, connection limits and timeouts, request body limit, reverse proxies, request ids, render workers and skew protection of the Rust server.

[server]
host = "0.0.0.0"
port = 3000
trusted_proxies = ["10.0.0.0/8"]   # your load balancer
workers = "auto"

Every key is optional and a partial table keeps the defaults for the rest. TLS has its own table, [server.tls].

Reference

Behavior

• Refusals before any handler runs. A body over max_body_bytes gets 413 Payload Too Large with x-gio-refused: unread, which tells <GioForm> the submission never reached the app. A body that arrives too slowly gets 408 Request Timeout.
• Keep-alive hint. HTTP/1.1 responses carry Keep-Alive: timeout=N, where N is the smaller of header_read_timeout_secs and idle_timeout_secs, so clients stop reusing a connection before the server closes it.
• Long responses are never cut by the connection deadlines. Streaming SSR, SSE streams, streamed route handler bodies and WebSockets stay open as long as they run. Only render_timeout_secs applies to a stream, between its chunks.
• Skew protection only looks at requests that carry x-deployment-id, which only the GioJS client runtime sends (soft navigations and prefetches). A full page load never gets a 409.
• The client resolved through trusted_proxies is what rate limits, prefetch budgets, the metrics allowlist, req.ip / ctx.ip and the logs use.

Startup warnings

Loosening one of these keys logs one warn line at startup, and giojs-server --check-config (and gio doctor) report the same text under warnings:

The other timeouts can be set to 0 without a warning. Each one you lift gives slow or idle clients a way to hold connections open: keep them on when GioJS faces the internet directly.

Examples

Listen on this machine only

Behind a reverse proxy on the same host, bind the loopback address so nothing else can reach the port:

[server]
host = "127.0.0.1"
port = 3000
trusted_proxies = ["127.0.0.1", "::1"]

Accept larger uploads

Raise the body limit and give slow uploads more time. Bodies are buffered in memory, so keep the limit near the largest upload you expect:

[server]
max_body_bytes = 26214400        # 25 MiB
request_body_timeout_secs = 120

Behind a load balancer

Trust the balancer's address range, keep its idle timeout below the server's, and let it set request ids only if it always sets its own:

[server]
trusted_proxies = ["10.0.0.0/8"]
accept_request_id = false          # the balancer passes a client's X-Request-Id through
header_read_timeout_secs = 75      # above the balancer's 60 s upstream idle timeout
idle_timeout_secs = 75

Render on every core

[server]
workers = "auto"                   # one Node worker per core, at most 8

Good to know

• The environment wins over the file for the address: GIO_HOST over host, GIO_PORT then PORT over port. A plain HOST variable is not read. A malformed value stops startup.
• workers = 0, a negative count or more than 64 stops startup (workers = 0: expected 1 to 64, or "auto").
• With max_body_bytes = 0 a body is still refused with 413 once it cannot fit in one 64 MiB worker message. A binary body is base64-encoded on the way, so about 48 MiB is the real ceiling.
• Proxies that pool upstream connections longer than header_read_timeout_secs (nginx keepalive, ingress-nginx and AWS ALB default to 60 seconds) can reuse a connection as GioJS closes it and answer 502. Keep the proxy's idle timeout below it, or raise both timeouts as in the example above.

Not configurable

• Path canonicalization. Repeated and trailing slashes collapse and escapes of unreserved characters are decoded before any rule, rate limit or route sees the path; a path with a . or .. segment or a malformed % escape gets 400. Every matcher then agrees on one spelling.
• The /_gio namespace is closed. A path under it that is not a built-in endpoint answers 404 from Rust and never reaches the app.
• Request id validation. An incoming X-Request-Id is only kept when it matches ^[A-Za-z0-9._:-]{1,128}$, so it is always safe to log and echo.
• The worker message cap (64 MiB per request) is fixed: it bounds what one request can cost the Node worker whatever max_body_bytes says.

Related

• [server.tls] - terminate TLS in GioJS
• [[rate_limits]] - per-client request budgets
• Connection limits, Reverse proxies and Render workers on the overview
• Proxies, Sizing & Scaling - per-proxy settings
• Turning Protections On and Off
• Environment variables

Version history