Module

net.listener

Network listener — creates and configures server sockets.

Binds to the configured address, sets socket options (SO_REUSEADDR, SO_REUSEPORT if available), and returns ready-to-accept sockets.

Phase 2 multi-worker strategy:

  • SO_REUSEPORT available (Linux): each worker gets its own independently bound socket — the kernel distributes connections across them.
  • SO_REUSEPORT unavailable (macOS, Windows): one socket is created and shared by all workers — all workers accept from the same fd.

The worker receives a socket and does not know which strategy was used.

9Functions

Functions

create_listener 1 socket.socket ▼
Create and bind a single server socket from configuration. If ``config.uds`` i…
def create_listener(config: ServerConfig) -> socket.socket

Create and bind a single server socket from configuration.

Ifconfig.udsis set, creates a Unix domain socket. Otherwise creates a TCP socket bound toconfig.host:config.port.

Parameters
Name Type Description
config ServerConfig

Server configuration with host, port, and backlog settings.
Returns
socket.socket
create_listeners 3 list[socket.socket] ▼
Create server sockets for *count* workers. When *shared* is True (recommended …
def create_listeners(config: ServerConfig, count: int, *, shared: bool = False) -> list[socket.socket]

Create server sockets for count workers.

When shared is True (recommended for thread workers), a single socket is created and returned for every worker — all threads callaccept() on the same fd and the kernel distributes connections naturally.

When shared is False (required for process workers), each worker gets its own independently boundSO_REUSEPORTsocket on platforms that support it. On platforms withoutSO_REUSEPORTthe shared strategy is used as a fallback regardless of this flag.

Parameters
Name Type Description
config ServerConfig

Server configuration.
count int

Number of worker sockets needed.
shared bool

If True, all workers share a single socket fd. Use this for thread-based workers to avoid macOS SO_REUSEPORT distribution issues.

Default:False
Returns
list[socket.socket]
create_udp_listener 1 socket.socket ▼
Create and bind a single UDP socket for HTTP/3 (QUIC). Binds to config.host:co…
def create_udp_listener(config: ServerConfig) -> socket.socket

Create and bind a single UDP socket for HTTP/3 (QUIC).

Binds to config.host:config.port. When config.port is 0 (ephemeral), the OS assigns a port; callers must pass the resolved TCP port (from the bound TCP socket) so HTTP/3 shares the advertised address.

UDP has no listen() or backlog.

Parameters
Name Type Description
config ServerConfig

Server configuration with host and port.
Returns
socket.socket
create_udp_listeners 2 list[socket.socket] ▼
Create UDP sockets for *count* HTTP/3 workers. Mirrors create_listeners: SO_RE…
def create_udp_listeners(config: ServerConfig, count: int) -> list[socket.socket]

Create UDP sockets for count HTTP/3 workers.

Mirrors create_listeners: SO_REUSEPORT for independent sockets, shared socket when unavailable.

Parameters
Name Type Description
config ServerConfig

Server configuration.
count int

Number of worker sockets needed.
Returns
list[socket.socket]
has_so_reuseport 0 bool ▼
Check if SO_REUSEPORT is available on this platform.
def has_so_reuseport() -> bool
Returns
bool
_bind_unix_socket 1 socket.socket ▼
Create, bind, and listen on a Unix domain socket. Removes any stale socket fil…
def _bind_unix_socket(config: ServerConfig) -> socket.socket

Create, bind, and listen on a Unix domain socket.

Removes any stale socket file before binding. The socket file should be cleaned up on shutdown viacleanup_unix_socket().

Parameters
Name Type Description
config ServerConfig
Returns
socket.socket
cleanup_unix_socket 1 None ▼
Remove the Unix domain socket file on shutdown. Safe to call even if no UDS is…
def cleanup_unix_socket(config: ServerConfig) -> None

Remove the Unix domain socket file on shutdown.

Safe to call even if no UDS is configured (no-op).

Parameters
Name Type Description
config ServerConfig
_bind_socket 3 socket.socket ▼
Create, configure, bind, and listen on a single TCP socket. Uses ``getaddrinfo…
def _bind_socket(config: ServerConfig, *, _log_listen: bool = True, use_reuseport: bool = False) -> socket.socket

Create, configure, bind, and listen on a single TCP socket.

Usesgetaddrinfoto resolve the host, supporting both IPv4 and IPv6 addresses. When binding to an IPv6 address, enables dual-stack (IPV6_V6ONLY=False) where possible so both IPv4 and IPv6 clients can connect.

Whenuse_reuseportis False (default for single-worker dev), a second instance binding to the same address will fail with EADDRINUSE, ensuring single-instance semantics for development.

Parameters
Name Type Description
config ServerConfig
_log_listen bool Default:True
use_reuseport bool Default:False
Returns
socket.socket
_bind_udp_socket 3 socket.socket ▼
Create, configure, and bind a single UDP socket for HTTP/3. UDP has no listen(…
def _bind_udp_socket(config: ServerConfig, *, _log_bind: bool = True, use_reuseport: bool = False) -> socket.socket

Create, configure, and bind a single UDP socket for HTTP/3.

UDP has no listen() or backlog. Uses same address resolution as TCP.

Parameters
Name Type Description
config ServerConfig
_log_bind bool Default:True
use_reuseport bool Default:False
Returns
socket.socket