blackbull.server.listener

blackbull.server.listener

The sockets a deployment wants, said once each.

A :class:Listener is one listening socket: where it is, what speaks there, whether TLS terminates there, and how many workers own it. Server binds a list of them, so no port is privileged over another and HTTP is a value rather than the absence of a raw handler.

The four ports a cleartext-plus-TLS deployment needs are four listeners that differ in address and TLS and in nothing else — HTTP/1.1 versus h2c is preface detection, and TLS h1 versus h2 is ALPN, both already handled downstream.

HTTP = 'http' module-attribute

What :attr:Listener.speaks names for the detecting HTTP stack.

InheritedFd dataclass

A socket already bound and listening, handed over by a supervisor.

Covers systemd-style activation and the re-exec handoff that keeps the listener continuous across an auto-reload.

Listener dataclass

One listening socket and what happens on it.

speaks is always a positive name: 'http' selects the stack that detects HTTP/1.1, h2c and WebSocket upgrades, and a raw protocol names itself.

tls is the listener's own context, so a second certificate — or mTLS on one port and not another — is sayable.

workers is where ownership is decided, and the only place. Left unset it follows speaks: the HTTP stack is stateless and runs on every worker, while a raw protocol holds state that scattering across workers would scatter with it. Pass it explicitly to override.

Tcp dataclass

A TCP port, on host or on every interface when it is None.

port=0 asks the OS for a free one; the bound port is read back after binding.

Unix dataclass

An AF_UNIX path.