turnloop-websocket 0.1.0-beta.2

Sans-I/O WebSocket protocol and HTTP upgrade helpers
Documentation

turnloop-websocket

Runtime-independent WebSocket state and HTTP upgrade helpers over tungstenite. The host supplies transport bytes, upgrade nonce and deadlines, drains events, and acknowledges completed writes. Shared HTTP types and buffers come from turnloop-http.

Supports masking, fragmentation, control frames, message/frame limits, subprotocols and close handshakes. permessage-deflate is not negotiated. This is a protocol building block, not a complete npm ws or JavaScript object-model replacement.

Native Node interop runs through the shared scripts/test-servers.py runner; no Node package installation is required. Browser wasm uses host entropy for upstream masking and the same sans-I/O protocol implementation.

Getting started on turnloop

Enable the turnloop feature. WebSocketStream::connect performs and validates an HTTP upgrade on a connected TCP, pipe or TLS stream; supply a fresh random nonce, subprotocol list, executor handle and absolute deadline. accept performs the server upgrade. Both preserve coalesced first-frame bytes. Await send and receive; ping/pong and close replies flush before received messages are returned. close waits for the peer under a deadline, then closes the transport with a lingering close under the same deadline (half-close, discard until the peer's EOF), so a late peer frame cannot turn the close into a reset. Dropping a pending frame operation closes the stream. The host keeps turning its LocalExecutor.

cargo run -p turnloop-websocket --features turnloop --example echo_server -- 127.0.0.1:8080
cargo run -p turnloop-websocket --features turnloop --example echo_client -- 127.0.0.1:8080

The same framed adapter works on native and WASI streams. Browsers use the web backend's host WebSocket capability instead of raw HTTP upgrades; browser APIs control TLS, headers, masking and extension negotiation. permessage-deflate remains unsupported by the sans-I/O core. See turnloop-io for shared transport glue.

For browser-hosted payload I/O, adopt a host WebSocket directly (its handshake and framing belong to the browser), then await the same shared stream helpers:

let socket = handle.driver().websocket(url, turnloop_io::turnloop::Token(0))?;
let mut payloads = handle.io(socket);
turnloop_io::write_all(&mut payloads, b"hello").await?;
let count = turnloop_io::read(&mut payloads, &mut buffer).await?;

Do not wrap that payload stream in WebSocketStream, which expects raw framed wire bytes. Host payload I/O does not expose raw ping/pong frames, custom upgrade headers, application-controlled masking, or a server listener. Wrap operations in turnloop_io::deadline for abortable waits; the web executor contract tests exercise this host path with real WebSocket traffic.