bookclerk_workerd::socket_table

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

The socket broker's bookkeeping, without I/O.

SocketTable holds every socket one plugin instance has open through the broker: its id, URL, negotiated subprotocol, attachment and declared heartbeat pairs. The broker's network code (socket_broker) asks it what to do with each frame the remote side sends and each request the guest makes, so the decisions the fuzz target checks are the ones the broker acts on.

A socket is pending from SocketTable::reserve until the handshake finishes (SocketTable::establish) or fails (SocketTable::abandon). Pending sockets count against MAX_SOCKETS_PER_INSTANCE but are invisible to the guest. Ids are never reused within one table.

Item Kind Summary
SocketTable struct Open and pending sockets for one plugin instance.
Inbound enum What the broker does with one data frame the remote side sent.
CLOSE_TOO_BIG constant WebSocket close code for a message larger than the broker accepts (RFC 6455 "Message Too Big").
MAX_ID_PREFIX_BYTES constant Longest id prefix SocketTable::new keeps, so ids stay within the 64-byte id limit with any counter value.

Structs

SocketTable

pub struct SocketTable {
    /* private fields */
}

Open and pending sockets for one plugin instance.

SocketTable::new

pub fn new(prefix: &str) -> Self

An empty table whose ids start with prefix.

Arguments
  • prefix - Id prefix; characters outside [A-Za-z0-9_-] are dropped and it is cut to MAX_ID_PREFIX_BYTES, so every id passes check_socket_id.

SocketTable::len

pub fn len(&self) -> usize

Sockets counted against the per-instance limit, pending included.

SocketTable::is_empty

pub fn is_empty(&self) -> bool

True when the table holds no socket, pending or open.

SocketTable::reserve

pub fn reserve(
    &mut self,
    request: &SocketConnectRequest,
) -> Result<(String, SocketTarget)>

Validates a connect request and reserves a pending socket for it.

Returns

The new socket id and the parsed target to dial.

Errors

The validate_socket_connect refusal, or limit_exceeded when the instance already holds MAX_SOCKETS_PER_INSTANCE sockets.

SocketTable::establish

pub fn establish(&mut self, socket: &str, protocol: Option<String>) -> Option<SocketInfo>

Marks a pending socket open once its handshake finished.

Arguments
  • socket - Id from Self::reserve.
  • protocol - Subprotocol the server chose, if any.
Returns

The socket's description for the guest, or None when socket is not pending (already open, abandoned, or unknown).

SocketTable::abandon

pub fn abandon(&mut self, socket: &str) -> bool

Drops a pending socket whose dial or handshake failed.

Returns

True when a pending socket was removed; open sockets are left alone (they end through Self::closed).

SocketTable::inbound

pub fn inbound(&self, socket: &str, frame: SocketFrame) -> Inbound

Decides what to do with a data frame the remote side sent.

SocketTable::outbound

pub fn outbound(&self, socket: &str, frame: &SocketFrame) -> Result<()>

Checks a frame the guest wants to send.

Errors

not_found when the socket is not open, or the frame check's refusal.

SocketTable::close_request

pub fn close_request(&self, socket: &str, code: u16, reason: &str) -> Result<Option<u16>>

Checks a close the guest asked for.

Returns

The close code to send (zero becomes 1000), or None when the socket is not open, which is not an error.

Errors

The close code or reason check's refusal.

SocketTable::set_attachment

pub fn set_attachment(&mut self, socket: &str, attachment: Vec<u8>) -> Result<()>

Replaces an open socket's attachment.

Errors

The attachment check's refusal, or not_found when the socket is not open.

SocketTable::closed

pub fn closed(
    &mut self,
    socket: &str,
    code: u16,
    reason: &str,
    clean: bool,
) -> Option<SocketClosed>

Records that an open socket ended and removes it.

Arguments
  • socket - The socket that ended.
  • code - Close code; 1006 when the connection dropped without one.
  • reason - Close reason the peer sent; empty for none.
  • clean - True when the close handshake completed.
Returns

The event for the guest, carrying the last attachment, or None when the socket was not open, so a socket is reported closed once.

SocketTable::list

pub fn list(&self) -> Vec<SocketInfo>

The open sockets, oldest first.

Implements: Clone, Debug

Enums

Inbound

pub enum Inbound {
    Reply(SocketFrame),
    Deliver(SocketMessage),
    TooBig,
    Ignore,
}

What the broker does with one data frame the remote side sent.

Variants

  • Reply: A declared heartbeat: send this frame back and do not wake the guest.
  • Deliver: Wake the guest and hand it this message.
  • TooBig: The frame is over MAX_SOCKET_FRAME_BYTES: close the socket with CLOSE_TOO_BIG.
  • Ignore: The socket is not open (closed, or never known): drop the frame.

Implements: Clone, Debug, Eq, PartialEq

Constants

CLOSE_TOO_BIG

pub const CLOSE_TOO_BIG: u16 = 1009;

WebSocket close code for a message larger than the broker accepts (RFC 6455 "Message Too Big").

MAX_ID_PREFIX_BYTES

pub const MAX_ID_PREFIX_BYTES: usize = 32;

Longest id prefix SocketTable::new keeps, so ids stay within the 64-byte id limit with any counter value.

Generated from crates/bookclerk-workerd at main · View as Markdown