bookclerk_plugin_sdk::sockets
Host-brokered WebSockets ([sockets]) for native guests.
A plugin that declares [sockets] (with capabilities.network.mode = "outbound") receives [Sockets] on Bindings::sockets
and exports a SocketHandler on
Entrypoints::socket_handler. The host's broker holds
each connection, answers declared heartbeats itself and wakes the handler
once per message, so the plugin process may sleep between messages: the
model of hibernatable Workers WebSockets.
HostWebSocket wraps one socket id with the same surface the
TypeScript and Python SDKs give their handlers (send, close,
serialize_attachment, deserialize_attachment). Attachments are stored
as UTF-8 JSON so a socket opened by one SDK reads the same in another.
| Item | Kind | Summary |
|---|---|---|
HostWebSocket |
struct | One host-held socket, named by its id, over the plugin's Sockets grant. |
text_heartbeat |
function | A text heartbeat pair: when request arrives the broker sends response without waking the guest (for example Socket.io's "2" ping and "3" pong). |
encode_attachment |
function | Encodes an attachment value as the host stores it: UTF-8 JSON. |
decode_attachment |
function | Decodes stored attachment bytes. |
bookclerk_plugin_abi::SocketAutoResponsebookclerk_plugin_abi::SocketClosedbookclerk_plugin_abi::SocketConnectRequestbookclerk_plugin_abi::SocketFramebookclerk_plugin_abi::SocketHandlerbookclerk_plugin_abi::SocketHeaderbookclerk_plugin_abi::SocketInfobookclerk_plugin_abi::SocketMessagebookclerk_plugin_abi::SocketMessageOkbookclerk_plugin_abi::Socketsbookclerk_plugin_abi::MAX_SOCKETS_PER_INSTANCEbookclerk_plugin_abi::MAX_SOCKET_ATTACHMENT_BYTESbookclerk_plugin_abi::MAX_SOCKET_AUTO_RESPONSESbookclerk_plugin_abi::MAX_SOCKET_AUTO_RESPONSE_BYTESbookclerk_plugin_abi::MAX_SOCKET_FRAME_BYTESbookclerk_plugin_abi::MAX_SOCKET_HEADERSbookclerk_plugin_abi::MAX_SOCKET_URL_BYTES
pub struct HostWebSocket<'a> {
/* private fields */
}
One host-held socket, named by its id, over the plugin's Sockets grant.
The handle holds no connection: it is cheap to build from a
SocketMessage or SocketClosed in the handler, and stays valid
across invocations while the socket is open.
pub async fn connect(
sockets: &'a dyn Sockets,
request: SocketConnectRequest,
) -> Result<(Self, SocketInfo), PluginError>
Opens a socket and wraps it.
sockets- The plugin'sSOCKETSbinding.request- URL, subprotocols, headers, heartbeats and attachment.
The handle and the host's SocketInfo for it.
Returns the host's error: invalid_params for a request outside the
ABI rules, forbidden for a URL off the network grant,
limit_exceeded past MAX_SOCKETS_PER_INSTANCE.
pub fn from_info(sockets: &'a dyn Sockets, info: &SocketInfo) -> Self
Wraps a socket connect or list returned.
sockets- The plugin'sSOCKETSbinding.info- The socket.
The handle.
pub fn from_message(sockets: &'a dyn Sockets, event: &SocketMessage) -> Self
Wraps the socket a message arrived on.
sockets- The plugin'sSOCKETSbinding.event- The message.
The handle, carrying the attachment the message arrived with.
pub fn new(sockets: &'a dyn Sockets, id: String, attachment: Vec<u8>) -> Self
Wraps a socket by id.
sockets- The plugin'sSOCKETSbinding.id- Host-minted socket id.attachment- Attachment last seen for it.
The handle.
pub fn id(&self) -> &str
Host-minted socket id.
pub async fn send(&self, frame: SocketFrame) -> Result<(), PluginError>
Sends one frame.
Returns payload_too_large past MAX_SOCKET_FRAME_BYTES and
not_found when the socket is closed.
pub async fn send_text(&self, text: impl Into<String>) -> Result<(), PluginError>
Sends one text frame.
pub async fn close(&self, code: u16, reason: impl Into<String>) -> Result<(), PluginError>
Closes the socket.
code- Close code;0sends 1000.reason- Close reason, at most 123 UTF-8 bytes.
Returns invalid_params for a code a peer may not send.
pub async fn serialize_attachment<T: Serialize + ?Sized>(
&mut self,
value: &T,
) -> Result<(), PluginError>
Stores a JSON value with the socket; every later message carries it.
As encode_attachment, plus the host's not_found for a closed
socket.
pub fn deserialize_attachment<T: DeserializeOwned>(
&self,
) -> Result<Option<T>, PluginError>
The stored attachment, decoded.
pub fn text_heartbeat(
request: impl Into<String>,
response: impl Into<String>,
) -> SocketAutoResponse
A text heartbeat pair: when request arrives the broker sends response
without waking the guest (for example Socket.io's "2" ping and "3" pong).
request- Text frame to match byte for byte.response- Text frame to send back.
The pair for SocketConnectRequest::auto_responses.
pub fn encode_attachment<T: Serialize + ?Sized>(value: &T) -> Result<Vec<u8>, PluginError>
Encodes an attachment value as the host stores it: UTF-8 JSON.
value- Value to keep with the socket.
At most MAX_SOCKET_ATTACHMENT_BYTES bytes.
Returns invalid_params when the value does not serialize as JSON and
payload_too_large when it does not fit.
pub fn decode_attachment<T: DeserializeOwned>(
bytes: &[u8],
) -> Result<Option<T>, PluginError>
Decodes stored attachment bytes.
bytes- Attachment the host kept.
None when no attachment is set.
Returns invalid_params when the bytes are not JSON of type T.
Generated from crates/bookclerk-plugin-sdk at main · View as Markdown