blackbull.protocol.rsock

blackbull.protocol.rsock

Bound and listening sockets.

Check for None or absent results after bind failure. Adopted sockets are already listening and must not be bound again; see docs/deployment/unix-and-fd.md.

adopt_inherited_sockets()

Adopt owned listening descriptors advertised by BB_INHERIT_FDS, or return None.

Do not bind/listen again. Clear the variable so forked workers cannot adopt twice.

adopt_listening_fd(fd)

Build a socket.socket from an already-bound listening fd.

Used for systemd socket-activation (--bind fd://N) and any other out-of-process socket hand-off where the supervisor binds and listens on the user's behalf.

Validates the sd_listen_fds(3) contract when $LISTEN_PID and $LISTEN_FDS are present:

• LISTEN_PID MUST equal our pid — if it points at someone else we raise rather than steal another process's fds.
• LISTEN_FDS defines the inclusive window [SD_LISTEN_FDS_START, SD_LISTEN_FDS_START + LISTEN_FDS) — we reject fds outside that window.

When neither env var is set we trust the caller and build the socket object anyway (useful for non-systemd handoff and for tests).

The fd is not unset CLOEXEC — workers inherit it via fork, the multiworker path already handles set_inheritable as needed.

close_sockets(sockets)

Close each live descriptor once and return any close failures.

create_configured_sockets(port, cfg, *, reuseport, host=None)

create_dual_stack_sockets with every option cfg carries.

create_dual_stack_sockets(port, backlog=_DEFAULT_BACKLOG, reuseport=False, sndbuf=0, rcvbuf=0, keepalive=True, user_timeout_ms=0, host=None)

Bind wildcard IPv4/IPv6 listeners, or only the named host's interface.

port=0 shares the assigned port across families. Return successfully bound sockets; IPv6 may be unavailable.

create_socket(address, backlog=_DEFAULT_BACKLOG)

Create a single socket.

The host in address determines the address family: an IPv6 literal (e.g. '::') opens an AF_INET6 socket; anything else opens an AF_INET socket.

Prefer create_dual_stack_sockets for new code.

create_unix_socket(path, backlog=_DEFAULT_BACKLOG, sndbuf=0, rcvbuf=0, mode=432)

Bind and listen on an AF_UNIX socket at path.

Returns the bound socket on success, None on any bind/listen failure.

path is taken verbatim — no expanduser, no normalisation; the caller is responsible for placing the socket where their reverse proxy expects it.

mode sets the socket-file permissions after bind (chmod on the inode). Defaults to 0o660 so a reverse proxy (nginx) running in the same group can connect; pass None to skip the chmod and inherit umask behaviour.

A stale leftover socket file at path is unlinked before bind (matching the systemd / hypercorn / nginx behaviour). We refuse to unlink if path is a regular file or directory — the user almost certainly didn't mean to point us at one.

TCP-only socket options (SO_REUSEPORT, TCP_USER_TIMEOUT, IPV6_V6ONLY) are deliberately skipped — AF_UNIX doesn't carry them. SO_SNDBUF / SO_RCVBUF are honoured when supplied.

somaxconn()

net.core.somaxconn in this process's network namespace, or None.

unix_accept_queue(sock)

(waiting, backlog) of a listening AF_UNIX socket, from the kernel.

Read by inode, so an adopted or duplicated fd reports its creator's backlog. The queue is full when waiting > backlog. None off Linux, for a socket that is not listening or is in another network namespace, or on any failure.