Configuration¶

Every server option is exposed in three equivalent ways:

• a CLI flag on the h2corn command
• an H2CORN_* environment variable
• a key in a TOML config file (passed via --config or H2CORN_CONFIG)

When the same option is provided in more than one place, the order of precedence is CLI > environment > TOML > defaults.

Option index¶

Application¶

Where the ASGI app lives and how it is loaded.

root_path¶

ASGI root path (to mount the application at a subpath).

ASGI lifespan handling mode.

Maximum time to wait for ASGI lifespan startup in seconds. Use 0 to disable.

Maximum time to wait for ASGI lifespan shutdown in seconds. Use 0 to disable.

How h2corn accepts connections.

bind¶

Listener addresses to bind. Repeat the flag to add more listeners. Supports HOST:PORT, [IPv6]:PORT, unix:PATH, and fd://N.

Octal mask for Unix Domain Socket permissions.

Maximum number of queued connections on the listening socket.

Set SO_REUSEPORT on the TCP listeners so other server processes can bind the same port — for zero-downtime deploys or independent processes. Workers of one server always share the inherited listener. TCP listeners only.

Direct TLS for TCP listeners. Leave unset when terminating TLS at a proxy.

certfile¶

PEM certificate chain file for direct TLS.

PEM private key file for direct TLS. Encrypted keys are not supported.

PEM CA bundle used to verify client certificates for direct TLS.

Client certificate verification mode for direct TLS.

Process identity, worker pool, and lifecycle on Unix.

pid¶

Write the server process PID to this file.

User name or numeric UID for worker processes and created Unix sockets.

Group name or numeric GID for worker processes and created Unix sockets.

Octal process umask to apply before creating files and sockets. Leave unset to preserve the inherited umask.

Number of worker processes to spawn.

Number of Tokio runtime worker threads per worker process.

Python event-loop implementation: 'auto' uses uvloop when installed (the 'h2corn[uvloop]' extra), otherwise the stdlib asyncio loop. h2corn runs its I/O in Rust, so this only affects how application callbacks are scheduled.

Number of Python event-loop threads per worker, balanced round-robin. Requires a free-threaded (no-GIL) interpreter; ignored on GIL builds. Composes with workers — keep workers x loop_threads at or below the core count.

Maximum number of requests or WebSocket sessions a worker should complete before retiring. Use 0 to disable.

Maximum jitter added to max_requests to stagger worker retirements. Use 0 to disable.

Maximum time between worker healthcheck heartbeats before the supervisor replaces the worker. Use 0 to disable.

Protocol behavior and per-connection bounds.

http1¶

Whether to accept HTTP/1.1 connections. Intended for development; disable in production.

Whether to log requests to stderr.

Maximum active HTTP/2 streams per connection.

Maximum total HTTP/1.1 request head size in bytes. Use 0 for no limit.

Maximum HTTP/1.1 request line size in bytes. Use 0 for no limit.

Maximum number of request header fields; HTTP/2 counts every decoded field, including duplicates. Use 0 for no limit.

Maximum individual HTTP/1.1 header field size in bytes. Use 0 for no limit.

Maximum decoded HTTP/2 header list size in bytes. Use 0 for no limit.

Maximum compressed HTTP/2 header block size in bytes while collecting HEADERS and CONTINUATION frames. Use 0 for no limit.

Maximum inbound HTTP/2 frame payload size to accept and advertise via SETTINGS_MAX_FRAME_SIZE.

HTTP/2 per-stream receive flow-control window in bytes (SETTINGS_INITIAL_WINDOW_SIZE). Bounds worst-case buffered upload bytes per stream; raise for high-bandwidth-delay uploads.

HTTP/2 connection-wide receive flow-control window in bytes. Bounds total buffered upload bytes per connection.

Maximum request body size in bytes. Use 0 for no limit.

Maximum number of concurrent ASGI request or session tasks per worker. Use 0 for no limit.

Maximum number of live client connections per worker. Use 0 for no limit.

Connection-level timeouts. All values are in seconds; 0 disables.

timeout_handshake¶

Maximum time to establish a connection and TLS handshake, in seconds. Use 0 to disable.

Maximum time for workers to finish in-flight requests on shutdown, in seconds.

Idle keep-alive timeout in seconds. Use 0 to disable.

Idle timeout in seconds while reading an HTTP request head or an HTTP/2 header block. Use 0 to disable.

Idle timeout in seconds while reading an HTTP request body. Use 0 to disable.

Timeout in seconds for HTTP/2 response body bytes pinned behind peer flow control. Use 0 to disable.

Limits and keep-alive for RFC 6455 and RFC 8441 WebSockets.

websocket_max_message_size¶

Maximum WebSocket message size in bytes. Defaults to 16 MiB. Use 'inherit' to follow max_request_body_size, or 0 for no limit.

Whether to negotiate permessage-deflate for WebSockets when the client offers it.

Interval in seconds between server WebSocket ping frames. Use 0 to disable.

Time limit in seconds to wait for a pong after a server WebSocket ping. Use 0 to disable.

Trust boundaries with the upstream proxy and default response headers.

proxy_headers¶

Trust proxy headers (e.g., Forwarded, X-Forwarded-*) if the client IP is in forwarded_allow_ips.

Allowed IPs or networks (in CIDR notation) for proxy headers. Use '*' to trust all.

Expect HAProxy's PROXY protocol on inbound connections.

Whether to add a default Server header when the application sets none.

Whether to add a default Date header when the application sets none.

Additional default response headers in name: value form. Repeat the flag to add more headers.

Config is a frozen dataclass; instantiate it directly or use one of the alternative constructors:

from_env(env: Mapping[str, str]) -> Self

from_mapping(data: Mapping[str, Any]) -> Self

from_toml(path: str | PathLike[str]) -> Self

bind = ["127.0.0.1:8000"]
workers = 4
proxy_headers = true
forwarded_allow_ips = ["127.0.0.1", "::1", "unix"]
http1 = false