Configuration

Process-level HTTP settings live in ServerConfig and nested RequestPolicy. The stario serve and stario watch commands read STARIO_* environment variables through server_config_from_env(); Stario does not load dotenv files — set variables in the shell, process manager, or your own bootstrap.

For embedding, pass a ServerConfig to Server. Request handlers do not read these objects directly; limits apply at the protocol layer on each connection.

ServerConfig

ServerConfig groups listen address, Unix socket options, graceful shutdown window, socket backlog, TCP SO_REUSEADDR, event loop choice, nested request policy, and live-response compression defaults.

When unix_socket is set, host, port, and reuse_addr are ignored; backlog and unix_socket_mode apply to the Unix listener.

graceful_shutdown_timeout is the phase-one drain window: in-flight handlers and connections from app.create_task may finish before force-close. Shutdown may continue up to about one additional second in a force-close loop before orphaned tasks are cancelled (see Server in the framework source).

class ServerConfig(*, host='127.0.0.1', port=8000, unix_socket=None, unix_socket_mode=432, requests=None, compression=None, graceful_shutdown_timeout=5.0, backlog=2048, reuse_addr=True, event_loop='asyncio')

Listen address, transport policy, request policy, compression, and shutdown.

When unix_socket is set, host, port, and reuse_addr are ignored; only backlog and unix_socket_mode apply to the Unix listener.

Nested requests and compression objects are stored by reference; treat as immutable after construction.

graceful_shutdown_timeout is the phase-1 drain window (handlers finish, idle connections close). Shutdown may continue up to one additional second in a force-close loop before orphaned tasks are cancelled (see Server._drain_listener).

server_config_from_env()

Read STARIO_* listen, limit, compression, and shutdown settings.

RequestPolicy

RequestPolicy caps header and body sizes, limits HTTP pipelining depth, and sets read timeouts for headers, body chunks, and keep-alive idle time. Defaults for header/body sizes and body read timeout come from stario.http.request (64 KiB headers, 10 MiB body, 30 s idle between body chunks). Header read timeout, keep-alive idle timeout, and pipelining depth default in stario.http.config (5 s, 5 s, 8).

Per-route handlers can pass a smaller max_size to await c.req.body(max_size=…) without changing the global policy.

class RequestPolicy(*, max_header_bytes=65536, max_body_bytes=10485760, header_timeout=5.0, body_timeout=30.0, keep_alive_timeout=5.0, max_pipelined_requests=8)

Header/body size caps, pipelining limit, and timeouts for a connection.

request_policy_from_env()

Read STARIO_REQUESTS_* size caps, read timeouts, and keep-alive idle timeout.

Compression (live responses)

ServerConfig.compression is a CompressionConfig used by Writer on dynamic responses. Negotiation honors Accept-Encoding quality values; among ties Stario prefers brotli, then zstd, then gzip. Bodies below min_size or incompressible content types may skip compression on whole-body (respond) paths; chunked streams negotiate without a minimum body size.

Static asset pre-compression uses a separate default profile inside StaticAssets (see Static assets).

class CompressionConfig(*, min_size=512, zstd_level=3, zstd_window_log=None, brotli_level=4, brotli_window_log=None, gzip_level=6, gzip_window_bits=None)

Policy for picking br / zstd / gzip from Accept-Encoding and for streaming vs whole-body responses.

Configure only via the constructor; fields are not meant for post-init mutation.

CompressionConfig.enabled_encodings()

Supported encodings in framework preference order.

CompressionConfig.make_compressor(encoding)

Build a compressor for an encoding already selected by negotiation.

CompressionConfig.may_compress(accept_encoding, *, data=None, content_type=None, streaming=False)

Return True when negotiation could pick a compressor (shared by select and Writer fast paths).

CompressionConfig.select(accept_encoding, *, data=None, content_type=None, streaming=False)

Choose one compressor from the client header and this config, or return None (identity).

Environment variables

Stario does not auto-load .env files. Export variables in the environment before starting the CLI, or construct ServerConfig / RequestPolicy in library code.

Listen and shutdown

Variable	Default	Purpose
`STARIO_HOST`	`127.0.0.1`	TCP bind address (ignored when a Unix socket is set).
`STARIO_PORT`	`8000`	TCP port.
`STARIO_LOOP`	`asyncio`	Event loop: `asyncio` or `uvloop`.
`STARIO_UNIX_SOCKET`	(empty)	Unix socket path; empty means TCP.
`STARIO_UNIX_SOCKET_MODE`	`660` (octal)	File mode applied after bind on a Unix socket.
`STARIO_BACKLOG`	`2048`	Socket listen backlog.
`STARIO_REUSE_ADDR`	`1`	TCP `SO_REUSEADDR` (`0` disables).
`STARIO_GRACEFUL_SHUTDOWN_TIMEOUT`	`5`	Graceful drain window in seconds.

Request limits

Variable	Default	Purpose
`STARIO_REQUESTS_MAX_HEADER_BYTES`	`65536`	Total request-line and header bytes before `431`.
`STARIO_REQUESTS_MAX_BODY_BYTES`	`10485760`	Maximum request body size (`413` when exceeded).
`STARIO_REQUESTS_HEADER_TIMEOUT`	`5`	Seconds to receive the request line and headers.
`STARIO_REQUESTS_BODY_TIMEOUT`	`30`	Seconds of idle time between body chunks.
`STARIO_REQUESTS_KEEP_ALIVE_TIMEOUT`	`5`	Idle time before closing a keep-alive connection.
`STARIO_REQUESTS_MAX_PIPELINED_REQUESTS`	`8`	Maximum queued pipelined requests per connection (excludes the in-flight handler; default allows 1 active + 8 queued).

HTTP/1.1 connections

RequestPolicy applies per TCP or Unix connection. The protocol may queue multiple requests on one socket (pipelining) but runs one handler at a time until the current response finishes (after writer.respond(), writer.end(), or equivalent completion).

While a response is in progress, additional pipelined requests wait in a queue on that connection.
When the queue exceeds max_pipelined_requests, the server responds with 503 and closes the connection.
keep_alive_timeout closes idle connections with no in-flight work.
header_timeout and body_timeout bound slow clients during read phases.

Each connection shares one client-disconnect future across pipelined exchanges — c.alive() and c.disconnect reflect the peer, not a single request in isolation. See Handlers and the writer for how this interacts with long-lived streams.

Compression (live responses)

Variable	Default	Purpose
`STARIO_COMPRESS_MIN_SIZE`	`512`	Minimum body size to attempt compression.
`STARIO_COMPRESS_ZSTD_LEVEL`	`3`	zstd level (`-1` disables zstd).
`STARIO_COMPRESS_ZSTD_WINDOW_LOG`	(unset)	Optional zstd window log.
`STARIO_COMPRESS_BROTLI_LEVEL`	`4`	Brotli level (`-1` disables brotli).
`STARIO_COMPRESS_BROTLI_WINDOW_LOG`	(unset)	Optional Brotli window log.
`STARIO_COMPRESS_GZIP_LEVEL`	`6`	gzip level (`-1` disables gzip).
`STARIO_COMPRESS_GZIP_WINDOW_BITS`	(unset)	Optional gzip window bits.

Telemetry

Tracer selection and sink tuning use STARIO_TRACER and STARIO_TRACERS_* variables. See Telemetry and stario serve --help.

Examples

bash

STARIO_PORT=9000 STARIO_TRACER=json stario serve main:bootstrap

STARIO_LOOP=uvloop stario watch main:bootstrap --watch app/