bookclerk_workerd::socket_table
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. |
pub struct SocketTable {
/* private fields */
}
Open and pending sockets for one plugin instance.
pub fn new(prefix: &str) -> Self
An empty table whose ids start with prefix.
prefix- Id prefix; characters outside[A-Za-z0-9_-]are dropped and it is cut toMAX_ID_PREFIX_BYTES, so every id passescheck_socket_id.
pub fn len(&self) -> usize
Sockets counted against the per-instance limit, pending included.
pub fn is_empty(&self) -> bool
True when the table holds no socket, pending or open.
pub fn reserve(
&mut self,
request: &SocketConnectRequest,
) -> Result<(String, SocketTarget)>
Validates a connect request and reserves a pending socket for it.
The new socket id and the parsed target to dial.
The validate_socket_connect refusal, or limit_exceeded when the
instance already holds MAX_SOCKETS_PER_INSTANCE sockets.
pub fn establish(&mut self, socket: &str, protocol: Option<String>) -> Option<SocketInfo>
Marks a pending socket open once its handshake finished.
socket- Id fromSelf::reserve.protocol- Subprotocol the server chose, if any.
The socket's description for the guest, or None when socket is
not pending (already open, abandoned, or unknown).
pub fn abandon(&mut self, socket: &str) -> bool
Drops a pending socket whose dial or handshake failed.
True when a pending socket was removed; open sockets are left alone
(they end through Self::closed).
pub fn inbound(&self, socket: &str, frame: SocketFrame) -> Inbound
Decides what to do with a data frame the remote side sent.
pub fn outbound(&self, socket: &str, frame: &SocketFrame) -> Result<()>
Checks a frame the guest wants to send.
not_found when the socket is not open, or the frame check's
refusal.
pub fn close_request(&self, socket: &str, code: u16, reason: &str) -> Result<Option<u16>>
Checks a close the guest asked for.
The close code to send (zero becomes 1000), or None when the
socket is not open, which is not an error.
The close code or reason check's refusal.
pub fn set_attachment(&mut self, socket: &str, attachment: Vec<u8>) -> Result<()>
Replaces an open socket's attachment.
The attachment check's refusal, or not_found when the socket is
not open.
pub fn closed(
&mut self,
socket: &str,
code: u16,
reason: &str,
clean: bool,
) -> Option<SocketClosed>
Records that an open socket ended and removes it.
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.
The event for the guest, carrying the last attachment, or None
when the socket was not open, so a socket is reported closed once.
pub fn list(&self) -> Vec<SocketInfo>
The open sockets, oldest first.
Implements: Clone, Debug
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 overMAX_SOCKET_FRAME_BYTES: close the socket withCLOSE_TOO_BIG.Ignore: The socket is not open (closed, or never known): drop the frame.
Implements: Clone, Debug, Eq, PartialEq
pub const CLOSE_TOO_BIG: u16 = 1009;
WebSocket close code for a message larger than the broker accepts (RFC 6455 "Message Too Big").
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