Module

config

Server configuration.

ServerConfig is the single configuration object for a pounce server instance. Frozen after creation — the server reads config but never mutates it.

1Class

Classes

ServerConfig 94 ▼
Immutable server configuration. All settings for a pounce server instance. Created once at startup…

Immutable server configuration.

All settings for a pounce server instance. Created once at startup, shared across all worker threads (safe because frozen).

Stability tiers: Not every knob carries the same maturity. Treat the following as guidance for production use;pounce config schemastamps the beta tier as anx-stabilityannotation per field.

Stable -- safe for production, behavior is covered by the core
contract: ``host``/``port``/``uds``, ``workers``/``backlog``,
``worker_mode`` values ``auto``/``sync``/``async``/``subinterpreter``,
the timeouts (``*_timeout``), the limits (``max_*``), and logging
(``access_log``/``log_level``/``log_format``).

Beta -- usable but the behavior, surface, or proof is still firming up;
pin versions and validate in staging before relying on them:
the rate-limit knobs (``rate_limit_*``), the request-queue knobs
(``request_queue_*``), introspection (``introspection_*``), HTTP/3
(``http3_*``), and the observability integrations
(``otel_*``/``sentry_*``/``metrics_*``).

See ``docs/design/core-contract.md`` for the per-feature contract and
required proof.

Attributes

Name Type Description
host str —
port int —
workers int —
backlog int —
worker_mode str —
worker_startup_failure str —
cpu_affinity bool —
executor_threads_per_worker int —
keep_alive_timeout float —
request_timeout float —
write_timeout float —
header_timeout float —
startup_timeout float —
shutdown_timeout float —
max_request_size int —
max_header_size int —
max_headers int —
max_connections int —
max_requests_per_connection int —
access_log bool —
log_level str —
log_format str —
display DisplayConfig | None —
app_name str | None —
app_tagline str | None —
app_version str | None —
signage str | None —
access_log_filter Callable[[str, str, int], bool] | None —
http2_enabled bool —
server_header str —
date_header bool —
root_path str —
compression bool —
compression_min_size int —
compression_dictionaries tuple[Any, ...] —
server_timing bool —
debug bool —
reload bool —
reload_include tuple[str, ...] —
reload_dirs tuple[str, ...] —
h11_max_incomplete_event_size int | None —
trusted_hosts frozenset[str] —
trusted_hosts_wildcard bool —
forwarded_for_trusted_hops int —
health_check_path str | None —
introspection_enabled bool —
introspection_bind str —
introspection_path str —
uds str | None —
uds_permissions int —
ssl_certfile str | None —
ssl_keyfile str | None —
static_files dict[str, str] —
static_cache_control str —
static_precompressed bool —
static_follow_symlinks bool —
static_index_file str | None —
middleware list[Middleware] —
websocket_compression bool —
websocket_max_message_size int —
reload_timeout float —
otel_endpoint str | None —
otel_service_name str —
lifecycle_logging bool —
log_slow_requests_threshold float —
metrics_enabled bool —
metrics_path str —
rate_limit_enabled bool —
rate_limit_requests_per_second float —
rate_limit_burst int —
rate_limit_max_tracked_ips int —
request_queue_enabled bool —
request_queue_max_depth int —
http3_enabled bool —
http3_max_connections int —
http3_idle_timeout float —
http3_qpack_max_table_capacity int —
http3_zero_rtt_enabled bool —
sentry_dsn str | None —
sentry_environment str | None —
sentry_release str | None —
sentry_traces_sample_rate float —
sentry_profiles_sample_rate float —
_VALID_LOG_LEVELS frozenset[str] —
_VALID_LOG_FORMATS frozenset[str] —
_VALID_WORKER_MODES frozenset[str] —
_VALID_WORKER_STARTUP_FAILURE frozenset[str] —

Methods

resolve_workers 0 int ▼
Return the effective worker count. If ``workers`` is 0 (auto-detect), returns …
def resolve_workers(self) -> int

Return the effective worker count.

Ifworkers is 0 (auto-detect), returns os.cpu_count() (minimum 1). Otherwise returns the explicit value.

Returns
int
to_iic_dict 0 dict[str, object] ▼
Serialize to a JSON-compatible dict for IIC transfer. Drops non-serializable f…
def to_iic_dict(self) -> dict[str, object]

Serialize to a JSON-compatible dict for IIC transfer.

Drops non-serializable fields (callables, middleware, display). Converts frozenset to sorted list for JSON round-tripping.

Returns
dict[str, object]
to_json 0 str ▼
Serialize to a JSON string for IIC transfer.
def to_json(self) -> str
Returns
str
from_iic_dict 1 ServerConfig ▼
Reconstruct from a dict produced by `to_iic_dict`(). Converts list back to fro…
classmethod
def from_iic_dict(cls, d: dict[str, Any]) -> ServerConfig

Reconstruct from a dict produced by to_iic_dict().

Converts list back to frozenset fortrusted_hosts, and drops any keys that are not valid constructor parameters.

Parameters
Name Type Description
d —
Returns
ServerConfig
from_json 1 ServerConfig ▼
Reconstruct from a JSON string produced by `to_json`().
classmethod
def from_json(cls, s: str) -> ServerConfig
Parameters
Name Type Description
s —
Returns
ServerConfig
from_mapping 1 ServerConfig ▼
Build a ``ServerConfig`` from an untyped key/value mapping. This is the typed …
classmethod
def from_mapping(cls, mapping: Mapping[str, Any]) -> ServerConfig

Build a ServerConfig from an untyped key/value mapping.

This is the typed construction site for merged config dicts (e.g. the output of load_config_with_overrides(), which isdict[str, Any]). It owns the single unavoidable cast from an object-valued mapping to the keyword-only constructor, so callers can splat config without sprinkling per-site type-ignore comments.

Validation is unchanged from direct construction: unknown keys raise TypeError and out-of-range/invalid values raise ValueErrorvia __post_init__().

Parameters
Name Type Description
mapping —
Returns
ServerConfig
Internal Methods 1 ▼
__post_init__ 0 ▼
Validate configuration values.
def __post_init__(self) -> None