Skip to main content

Module envelope

Module envelope 

Source
Expand description

The Plexus wire envelope, as a client sees it.

§Why this is not plexus_core::plexus::types::PlexusStreamItem

The server-side envelope requires metadata on every variant, and the WebSocket JSON-RPC transport does deliver it. The REST bridge does not: stream_sse_response re-frames each item and emits only

event: data
data: {"content": <event JSON>}

— dropping metadata and content_type entirely (and a REST unary body carries an error’s RemoteError with no recoverable). A client type that made those fields mandatory could therefore not represent what the REST transport actually receives.

So StreamItem is deliberately the looser type: every field the REST bridge drops is Option / #[serde(default)]. It deserializes the full WebSocket envelope losslessly, and an SSE transport can construct the same type from an (event-name, data-payload) pair — which is what makes one typed client work over both transports.

(An SSE data: payload is not itself a StreamItem: the discriminant lives in the frame’s event: field, not in the JSON. Reassembling the two is the SSE transport’s job; this type is the target shape it reassembles into.)

Wire compatibility with the server envelope is a regression gate, not an assumption — see tests/client_envelope_compat.rs in plexus-core, which round-trips every PlexusStreamItem 0.7 frame produced by plexus-core through this type, byte for byte.

§0.7 (RETURNS-6)

The progress frame carries the method’s typed progress value as content (beside the call’s content_type, as a data frame does); the error frame carries a typed RemoteError — beside spec/05’s message, code and flattened error_kind fields, which main’s typed refusals (AUTH-2, POLYGLOT-5) put there and RETURNS-36 kept.

Structs§

Content
An item’s content as a typed client reads it (PERF.115-36): the JSON text the wire carried, decoded straight into the method’s event when it is read, never into a Value first. A transport that has no text (one in process, a script) hands over the Value it holds.
StreamMetadata
Provenance metadata the calling layer stamps onto each item.

Enums§

RawItem
One item of a response stream as a typed client reads it (PERF.115-36): a StreamItem whose content is still the wire’s JSON (Content), and nothing read that a typed decode does not use: no metadata. Transport::call_raw yields these and decode_raw turns them into events; a consumer that wants the metadata reads StreamItems.
StreamItem
One item of a Plexus response stream, as delivered by a Transport.