Configuration Options Reference

Complete parameter reference for config.yaml and routes.yaml.

Section: server

Server Connection Timeouts & Adaptive Amortization (REQ-126)

Toron enforces strict socket connection timeouts to guarantee immunity against Slowloris socket exhaustion and Slow-Read Denial of Service attacks (REQ-005 §2, TASK-004 §3, ADR-083, ADR-126).

Parameter Specifications

• read_timeout (time.Duration): Defines the maximum time Toron will wait to read the entire HTTP request headers and body. Under steady-state keep-alive traffic bursts, client connections are wrapped in an adaptive tracker (connDeadlineTracker). If an active kernel read deadline was already established and more than half the timeout window remains ($R > \tau/2$), redundant operating system calls to SetReadDeadline are safely bypassed, achieving $>99\%$ syscall reduction at high request rates.
• write_timeout (time.Duration): Defines the maximum duration allowed to serialize response headers and write body bytes to the client socket.
  • Discrete Responses: Amortized identically to read deadlines during rapid keep-alive transactions.
  • Streaming Responses (res.StreamBody): For long-lived streaming connections (such as Server-Sent Events text/event-stream, live feeds, or unbuffered proxy streams), Toron refreshes the socket write deadline on every transmitted chunk (ForceSetWriteDeadline(now + write_timeout)). This allows active, healthy streams to remain connected indefinitely (hours or days) while ensuring that stalled or slow-reading clients (advertising a zero TCP window or reading below rate) are terminated within write_timeout after socket buffers saturate (CWE-400 Slow-Read defense).
• idle_timeout (time.Duration): Defines the maximum duration an idle keep-alive connection can wait for the arrival of the next request. The moment an HTTP transaction completes and the socket reader buffer is empty (br.Buffered() == 0), Toron immediately invalidates the read amortization cache (ResetReadAmortization()) and forces an explicit kernel deadline (ForceSetReadDeadline(now + idle_timeout)). This prevents long active request read deadlines (e.g. 5s or 10s) from lingering into idle periods, guaranteeing that idle connections disconnect promptly after idle_timeout.
• upgrade_idle_timeout (time.Duration): Defines the maximum inactivity timeout for upgraded full-duplex protocols (WebSockets, RFC 8441 HTTP/2 CONNECT tunnels, L4 transparent TCP relays). In bidirectional relay loops (relayStreams), deadlines are amortized during active frame transfers, while silence across both directions terminates the connection after upgrade_idle_timeout. If set to 0 or omitted, Toron defaults to idle_timeout (or 60s if idle_timeout is also 0) as a critical security fail-safe (SEC-27, ADR-083).

Non-Negative Validation Rules

All server timeout parameters are strictly validated by ValidateConfig during startup and configuration dry-run (toron -t):

• Any negative duration (e.g. read_timeout: -5s, write_timeout: -1s, idle_timeout: -200ms, upgrade_idle_timeout: -10s) is strictly rejected with an explicit error:

  server.read_timeout must be non-negative, got -5s
  

• Startup halts immediately, preventing misconfigured services from deploying with invalid or negative timeout calculations.

Zero-Timeout Mode (Benchmark & Isolated Environments)

For performance engineers conducting raw benchmark evaluations or deploying in isolated, trusted private enclaves where maximum throughput is paramount:

• Setting read_timeout: 0 (or 0s) or write_timeout: 0 (or 0s) explicitly disables socket deadline enforcement.
• When configured to 0, connDeadlineTracker clears any existing deadline via conn.SetDeadline(time.Time{}) and executes exactly zero socket deadline system calls during steady-state request processing.
• The configuration loader preserves explicit 0 values and does not overwrite them with default values (validateConfigDefaults).

[!WARNING] Disabling connection deadlines (read_timeout: 0, write_timeout: 0) removes Slowloris and Slow-Read DoS protections. Only utilize zero-timeout mode in trusted networks, closed benchmark clusters, or behind upstream edge load balancers with their own deadline enforcement.

Section: server.http2

Section: server.http3

Section: server.tls

Section: server.acme

Section: server.compression

Section: server.cache

Section: server.cors / routes[].cors

Section: server.security_headers / routes[].security_headers

Section: server.waf / routes[].waf

Section: discovery (OCI Container Auto-Discovery)

Section: ingress (Kubernetes Ingress Controller)

Section: sidecar (Service Mesh Sidecar Mode)

Section: transcoder (REST-to-gRPC Transcoding)

Section: server.auth / routes[].auth

Section: routes[] (routes.yaml Schema)

Section: proxy.transport / routes[].transport (REQ-123, REQ-124, REQ-129)

Section: logging

Related Pages

• Configuration Guide
• Layer 4 TCP & UDP Transport Proxies
• CLI Reference