bookclerk_workerd::granted_sockets
POST /sockets/<op> on the granted reverse channel: a workerd isolate's
env.SOCKETS calls, parsed and answered over plain byte slices.
The isolate holds a sockets-only grant token minted at open; each call
names its operation in the path (connect, send, close,
attachment, list) and carries that operation's fields as JSON. Binary
frames and attachments travel as base64. Every request is checked with the
same bookclerk_plugin_abi::sockets rules the host applies again when it
serves Sockets, so a malformed call fails here with a typed error and
never reaches the host. Keeping parsing sans-IO lets the socket_request
fuzz target drive the code the bridge runs.
| Item | Kind | Summary |
|---|---|---|
RouteAutoResponse |
struct | One heartbeat pair as the route carries it. |
RouteConnect |
struct | POST /sockets/connect body. |
RouteSend |
struct | POST /sockets/send body. |
RouteClose |
struct | POST /sockets/close body. |
RouteAttachment |
struct | POST /sockets/attachment body. |
RouteList |
struct | POST /sockets/list body: an empty object. |
RouteFrame |
enum | One message as the route carries it: {"text": "..."} or {"binary": "<base64>"}. |
SocketCall |
enum | One checked env.SOCKETS call, ready for the host's Sockets stub. |
SocketReply |
enum | What the host answered one SocketCall with. |
parse_socket_call |
function | Parses and checks one POST /sockets/<op> call. |
socket_reply_json |
function | Encodes a host answer as the route's JSON reply body. |
MAX_SOCKET_ROUTE_BODY_BYTES |
constant | Largest /sockets/* request body: one frame at maxSocketFrameBytes in its worst JSON form, plus room for a connect request's URL, headers and heartbeat pairs. A text frame of control characters escapes to six bytes per byte (\u0000), which outgrows base64's four per three. The ABI checks bound each field once decoded; this only bounds the read. |
SOCKET_ROUTE_OPS |
constant | Operations the route serves, in path spelling. |
pub struct RouteAutoResponse {
pub request: RouteFrame,
pub response: RouteFrame,
}
One heartbeat pair as the route carries it.
Fields
request: Frame to match.response: Frame to send back.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct RouteConnect {
pub url: String,
pub protocols: Vec<String>,
pub headers: Vec<SocketHeader>,
pub auto_responses: Vec<RouteAutoResponse>,
pub attachment: Vec<u8>,
}
POST /sockets/connect body.
Fields
url:wss://orws://URL on the plugin's network grant.protocols: Requested subprotocols.headers: Extra request headers. Values may be credentials.auto_responses: Heartbeats the broker answers without waking the guest.attachment: Initial attachment, base64.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct RouteSend {
pub socket: String,
pub frame: RouteFrame,
}
POST /sockets/send body.
Fields
socket: Socket id fromconnectorlist.frame: The message.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct RouteClose {
pub socket: String,
pub code: u16,
pub reason: String,
}
POST /sockets/close body.
Fields
socket: Socket id.code: WebSocket close code; zero or absent sends 1000.reason: Close reason, at most 123 UTF-8 bytes.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct RouteAttachment {
pub socket: String,
pub attachment: Vec<u8>,
}
POST /sockets/attachment body.
Fields
socket: Socket id.attachment: New attachment, base64.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub struct RouteList {}
POST /sockets/list body: an empty object.
Implements: Clone, Debug, Deserialize<'de>, Eq, PartialEq, Serialize
pub enum RouteFrame {
Text(String),
Binary(Vec<u8>),
}
One message as the route carries it: {"text": "..."} or
{"binary": "<base64>"}.
Variants
Text: Text message, UTF-8.Binary: Binary message, base64 on the wire.
Implements: Clone, Debug, Deserialize<'de>, Eq, From<RouteFrame>, From<SocketFrame>, PartialEq, Serialize
pub enum SocketCall {
Connect(SocketConnectRequest),
Send { socket: String, frame: SocketFrame },
Close { socket: String, code: u16, reason: String },
SetAttachment { socket: String, attachment: Vec<u8> },
List,
}
One checked env.SOCKETS call, ready for the host's Sockets stub.
Variants
Connect:Sockets.connect.Send:Sockets.send.socket: Socket id.frame: The message.
Close:Sockets.close.socket: Socket id.code: Close code to send (zero already mapped to 1000).reason: Close reason.
SetAttachment:Sockets.setAttachment.socket: Socket id.attachment: New attachment.
List:Sockets.list.
Implements: Clone, Debug, Eq, PartialEq
pub enum SocketReply {
Connected(SocketInfo),
Done,
Listed(Vec<SocketInfo>),
}
What the host answered one SocketCall with.
Variants
Connected:connectopened this socket.Done:send,closeorattachmentfinished.Listed:listfound these open sockets, oldest first.
Implements: Clone, Debug, Eq, PartialEq
pub fn parse_socket_call(op: &str, body: &[u8]) -> Result<SocketCall, PluginError>
Parses and checks one POST /sockets/<op> call.
op- Path segment after/sockets/.body- Request body bytes, already bounded byMAX_SOCKET_ROUTE_BODY_BYTES.
The call, with every field within the ABI limits.
Returns not_found for an operation the route does not serve,
invalid_params for malformed JSON, an unknown field, a malformed socket
id, URL, header, subprotocol, heartbeat or close code, and
payload_too_large for an oversized frame or attachment.
pub fn socket_reply_json(reply: &SocketReply) -> Result<Vec<u8>>
Encodes a host answer as the route's JSON reply body.
connect answers the SocketInfo (attachment as base64), list
answers {"sockets": [...]}, and the rest answer {}.
Returns the serializer's error, which a well-formed SocketInfo never
produces.
pub const MAX_SOCKET_ROUTE_BODY_BYTES: u32 = _;
Largest /sockets/* request body: one frame at maxSocketFrameBytes in
its worst JSON form, plus room for a connect request's URL, headers and
heartbeat pairs. A text frame of control characters escapes to six bytes
per byte (\u0000), which outgrows base64's four per three. The ABI checks
bound each field once decoded; this only bounds the read.
pub const SOCKET_ROUTE_OPS: [&str; 5] = _;
Operations the route serves, in path spelling.
Generated from crates/bookclerk-workerd at main · View as Markdown