Streams

Carriage for the transports that move bytes.

A stream is the byte-level carriage beneath a stream-based transport — TCP, TLS, WebSocket, and the rest. It is a separate concern that direct transports never touch: they may still serialise a call, but they pass the buffer through in-memory marshaller calls instead. Only a call between two objects in the same zone skips serialisation entirely.

When a stream is involved — and when it isn't

A stream-based transport serialises the call and moves the bytes over a carriage — a pipe, an SPSC queue, or a TCP socket. That carriage is the stream, and it is composable: a TCP stream wrapped in TLS, then framed for WebSocket, all without changing the interface or the service above. The abstract stream, TCP stream, acceptor, listener, and WebSocket stream are dual-mode, compiling from the same source in blocking and coroutine builds.

A direct transport uses no stream. It may still serialise the call — it is crossing a zone boundary — but it passes the serialised buffer through i_marshaller function calls in memory rather than over any carriage. The narrowest case, a call between two objects in the same zone, skips serialisation altogether: the proxy resolves to a plain function call, no buffer and no copy. Streams enter only when bytes have to travel over a carriage.

Usable without the RPC layer

The streaming stack does not depend on the RPC machinery above it. If all you want is a byte pipe — a TLS socket, a WebSocket feed, an HTTP endpoint — you can use the streaming classes directly, with no proxies, stubs, or marshalling in the picture. The transport_streaming and transport_websocket classes are simply the optional glue that hands a stream to the RPC logic; leave them out and what remains is a standalone, dual-mode networking library you can build on directly.

Stream layers

TCP The base host-to-host byte stream most network links build on.
SPSC A lock-free single-producer/single-consumer buffer for the lowest-latency same-machine carriage.
TLS Encryption wrapped around a stream. OpenSSL is dual-mode; mbedtls is coroutine-only.
Compression Smaller payloads where bandwidth costs more than CPU — for constrained or metered links.
WebSocket Browser-friendly framed messaging, the carriage behind generated JavaScript clients.
HTTP REST endpoints, static serving, and operational routes alongside the RPC stack.
io_uring TCP Linux kernel async I/O for the highest-throughput networked paths. Coroutine build only.
Custom streams Additional byte-carriage layers can be added where a deployment needs a link Canopy does not ship.

Streamed delivery pairs naturally with one-way [post] methods for high-rate feeds — video, audio, telemetry, and LLM tokens. Under saturation, documented backpressure guidelines govern how a stream-backed transport behaves rather than leaving it to chance.