std.net.socket: Listening Sockets

std.net.socket

std.net.socket is the low-level listening socket layer beneath higher network APIs. It follows the tri-signature pattern:

Profile	Entry point	Contract
:core	listen(address, allocator)	Parse and bind a listening socket.
:service	listen_with_context(address, ctx, allocator)	Honor cancellation and expired deadlines before and during creation.
:sovereign	listen_with_capability(address, cap, allocator)	Require NetBind authority and emit bind audit records.

Address Forms

The parser accepts these bind forms:

Form	Meaning
:8080	IPv4 wildcard bind on port 8080.
127.0.0.1:9000	IPv4 host and port.
[::1]:443	Bracketed IPv6 host and port.
unix:/tmp/janus.sock	Unix socket path.
/tmp/janus.sock	Bare Unix socket path.

Malformed addresses return SocketError.InvalidAddress; malformed ports return SocketError.InvalidPort.

Context Behavior

The context-aware path treats a cancelled context or an expired deadline as SocketError.Timeout. Creation checks the context before socket creation and again between the socket, option, sockaddr, bind, and listen steps.

That means service code can rely on the advertised signature:

let socket = net.listen_with_context(":8080", ctx, allocator) catch |err| do
    match err {
        SocketError.Timeout => return err,
        _ => return err,
    }
end

NetBind Capability

The capability path checks NetBind before any socket syscall is issued. Default NetBind values grant net.bind and allow ports 8080, 3000, and 8000. Add explicit ports with allow_port when a service owns another bind surface.

Denied binds return SocketError.CapabilityDenied.

Audit Records

NetBind can carry an audit sink. The socket layer emits:

Operation	Result
check_bind_address	allowed or denied before socket creation.
bind_socket	allowed after the OS bind succeeds.

The record contains the capability id, operation, optional port, and result. Unix socket paths have no port, so their audit record uses null for the port.

Verification

The closure target for this surface is:

cd janus
./scripts/zb test-net-socket

That target covers address parsing, owned sockaddr layout, a port-zero listen/close smoke, cancelled and expired contexts, capability-denied binds, and bind audit records.