bookclerk_workerd::socket_broker
The socket broker: holds a plugin instance's WebSockets while its guest sleeps.
The host starts bookclerk-workerd in broker mode
(SOCKET_BROKER_ENV) inside the plugin's jail, under the plugin's
network grant. The broker serves the plugin ABI's Sockets interface to
the host on stdio and delivers what arrives through the host's
SocketHandler (see bookclerk_plugin_abi::serve_socket_broker), in the
manner of hibernatable Workers WebSockets:
- every dial passes the egress policy: the URL's host must be on a
fetchdomain grant or a TCP grant for that host and port (target_granted), and the broker connects only to resolved addresses the policy allows, with no redirects; wss://uses rustls on the hosts' one provider with Mozilla's roots;- heartbeat frames the guest declared at connect are answered here and
never wake the guest (
SocketTable::inbound); - other messages queue per socket and reach the host one at a time; the broker stops reading a socket whose queue is full, and keeps answering heartbeats otherwise while a delivery waits for the guest to wake;
- a socket's close reaches the host after its last message, once.
The decisions live in crate::socket_table, which the fuzz target
drives without I/O.
| Item | Kind | Summary |
|---|---|---|
SocketBroker |
struct | The broker's Sockets for one plugin instance. |
default_tls |
function | TLS settings with Mozilla's roots on the hosts' one rustls provider. |
target_granted |
function | True when the grant covers the socket's target. |
serve_stdio |
function | Serves the broker on stdio until the host hangs up. |
SOCKET_BROKER_ENV |
constant | Environment variable that starts bookclerk-workerd as the plugin's socket broker (value 1) instead of its front door. |
pub struct SocketBroker {
/* private fields */
}
The broker's Sockets for one plugin instance.
pub fn new(
policy: EgressPolicy,
tls: Arc<ClientConfig>,
handler: Rc<dyn SocketHandler>,
id_prefix: &str,
) -> Self
A broker with no sockets.
Must be used inside a tokio::task::LocalSet: each socket runs on
local tasks because the host's handler is a Cap'n Proto capability.
policy- The plugin's effective egress policy.tls- TLS settings forwss://(default_tlsin production).handler- The host's handler for messages and closes.id_prefix- Prefix for socket ids, unique per broker start so ids are not reused across restarts.
pub fn with_tunnels(self, tunnels: Arc<Mux>) -> Self
Sends every dial through the host's proxy link as a tunnel.
tunnels- The host proxy link.
Updated Self for chaining.
Never: the shared state has no other owner until the broker serves.
Implements: Sockets
pub fn default_tls() -> Result<Arc<ClientConfig>>
TLS settings with Mozilla's roots on the hosts' one rustls provider.
Returns an internal error when the provider offers no safe protocol version (it always does).
pub fn target_granted(policy: &EgressPolicy, target: &SocketTarget) -> bool
True when the grant covers the socket's target.
A WebSocket starts as an HTTP request, so a fetch domain grant that
grants the target's port covers it (an entry with no port grants 80 and
443, as for fetch); a TCP grant for the host and port covers it too, since that grant
already lets the plugin open the same connection and speak the protocol
itself. Either way the addresses are checked afterwards.
pub async fn serve_stdio(policy: EgressPolicy, tunnels: Option<Arc<Mux>>) -> Result<()>
Serves the broker on stdio until the host hangs up.
policy- The plugin's effective egress policy.tunnels- The host's CONNECT link. When set, every socket is dialed through it, so the broker's own jail needs no network;Nonedials directly (diagnostic spawns only).
Returns the TLS setup or link failure.
pub const SOCKET_BROKER_ENV: &str = "BOOKCLERK_SOCKET_BROKER";
Environment variable that starts bookclerk-workerd as the plugin's
socket broker (value 1) instead of its front door.
Generated from crates/bookclerk-workerd at main · View as Markdown