Skip to main content

plexus_core/plexus/
streaming.rs

1//! Streaming helpers for the caller-wraps architecture
2//!
3//! These functions are used by the DynamicHub routing layer to wrap activation
4//! responses with metadata. Activations return typed domain events, and
5//! the caller uses these helpers to create PlexusStreamItems.
6
7use futures::stream::{self, Stream, StreamExt};
8use plexus_client::{Progress, RemoteError};
9use serde::{Serialize, Serializer};
10use serde::de::DeserializeOwned;
11use std::pin::Pin;
12use std::sync::Arc;
13use tokio::sync::mpsc;
14use tokio_stream::wrappers::ReceiverStream;
15
16use super::bidirectional::BidirChannel;
17use super::context::PlexusContext;
18use super::credential_envelope::{
19    assemble_envelope_content, serialize_with_credential_capture, CookieProjector,
20};
21use super::types::{PlexusStreamItem, StreamMetadata};
22
23/// Type alias for boxed stream of PlexusStreamItem
24pub type PlexusStream = Pin<Box<dyn Stream<Item = PlexusStreamItem> + Send>>;
25
26/// Wrap a typed stream into PlexusStream with automatic Done event
27///
28/// This is the core helper for the caller-wraps architecture.
29/// Activations return typed domain events (e.g., HealthEvent),
30/// and the caller wraps them with metadata. A Done event is
31/// automatically appended when the stream completes.
32///
33/// # Dispatch-time credential interception (AUTHZ-CRED-CORE-2)
34///
35/// For every emitted item, this function routes the serialization through
36/// the dispatch-time credential capture machinery: a fresh sidecar is
37/// installed (per the RAII guard documented in
38/// `plexus_auth_core::DispatchCaptureGuard`), serialization runs (and
39/// each `Credential<T>` field emits its sentinel inline while the inner
40/// value is captured into the sidecar), and the resulting `(payload,
41/// captured)` pair is assembled into a wire envelope with an optional
42/// `_credentials` field. Payloads with zero `Credential<T>` fields are
43/// wire-format-identical to today (additive only).
44///
45/// See `crate::plexus::credential_envelope` for the envelope assembly
46/// rules and `plans/AUTHZ/AUTHZ-CRED-CORE-2.md` for the contract.
47///
48/// # Example
49///
50/// ```ignore
51/// let stream = health.check();  // Returns Stream<Item = HealthEvent>
52/// let wrapped = wrap_stream(stream, "health.status", vec!["health".into()]);
53/// // Stream will emit: Data, Data, ..., Done
54/// ```
55pub fn wrap_stream<T: Serialize + Send + 'static>(
56    stream: impl Stream<Item = T> + Send + 'static,
57    content_type: &'static str,
58    provenance: Vec<String>,
59) -> PlexusStream {
60    let plexus_hash = PlexusContext::hash();
61    let metadata = Arc::new(StreamMetadata::new(provenance.clone(), plexus_hash.clone()));
62    let done = StreamMetadata::new(provenance, plexus_hash);
63    Box::pin(Wrapped::<_, DataForm> {
64        inner: stream,
65        metadata,
66        content_type,
67        done: Some(done),
68        ended: false,
69        form: std::marker::PhantomData,
70    })
71}
72
73// ============================================================================
74// RETURNS-8: one wrapper per signature form
75// ============================================================================
76//
77// `#[plexus_macros::method]` reads a method's return type and calls the one
78// wrapper that matches it (RETURNS-1 decisions 2, 3, 4, 10):
79//
80// | signature | wrapper | frames per item |
81// |---|---|---|
82// | `-> T` | [`wrap_one`] | data `T`, then done |
83// | `-> Result<T, E>` | [`wrap_one_result`] | data `{"ok": t}` / `{"err": e}`, then done |
84// | `-> impl Stream<Item = T>` | [`wrap_stream`] | data `T` … done |
85// | `-> impl Stream<Item = Result<T, E>>` | [`wrap_result_stream`] | data `{ok}` / `{err}` … done |
86// | `-> impl Stream<Item = Progress<T, P>>` | [`wrap_progress_stream`] | `Update(p)` → progress `P`; `Item(t)` → data `T` |
87// | `-> impl Stream<Item = Result<Progress<T, P>, E>>` | [`wrap_result_progress_stream`] | `Ok(Update(p))` → progress; `Ok(Item(t))` → data `{ok}`; `Err(e)` → data `{err}` |
88//
89// An `Err` item is data: it does not end the stream — the method ends it by
90// returning. Every wrapper appends exactly one `done`.
91
92/// One frame of a method's output before metadata: an item (a data frame) or
93/// a progress update (a progress frame).
94enum Out<D, P> {
95    Data(D),
96    Progress(P),
97}
98
99/// A Result item as the wire carries it: `Ok(t)` → `{"ok": t}`, `Err(e)` →
100/// `{"err": e}` (`plexus_client::wire_result`).
101struct WireResult<T, E>(Result<T, E>);
102
103impl<T: Serialize, E: Serialize> Serialize for WireResult<T, E> {
104    fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error> {
105        plexus_client::wire_result::serialize(&self.0, serializer)
106    }
107}
108
109/// `-> T`: one data frame carrying `item`, then `done`.
110pub fn wrap_one<T: Serialize + Send + 'static>(
111    item: T,
112    content_type: &'static str,
113    provenance: Vec<String>,
114) -> PlexusStream {
115    wrap_frames(
116        stream::once(futures::future::ready(Out::<T, ()>::Data(item))),
117        content_type,
118        provenance,
119    )
120}
121
122/// `-> Result<T, E>`: one data frame, `{"ok": t}` or `{"err": e}`, then `done`.
123pub fn wrap_one_result<T, E>(
124    item: Result<T, E>,
125    content_type: &'static str,
126    provenance: Vec<String>,
127) -> PlexusStream
128where
129    T: Serialize + Send + 'static,
130    E: Serialize + Send + 'static,
131{
132    wrap_frames(
133        stream::once(futures::future::ready(Out::<_, ()>::Data(WireResult(item)))),
134        content_type,
135        provenance,
136    )
137}
138
139/// `-> impl Stream<Item = Result<T, E>>`: one data frame per item, `{"ok": t}`
140/// or `{"err": e}`; an `Err` does not end the stream. Then `done`.
141pub fn wrap_result_stream<T, E>(
142    stream: impl Stream<Item = Result<T, E>> + Send + 'static,
143    content_type: &'static str,
144    provenance: Vec<String>,
145) -> PlexusStream
146where
147    T: Serialize + Send + 'static,
148    E: Serialize + Send + 'static,
149{
150    wrap_frames(
151        stream.map(|r| Out::<_, ()>::Data(WireResult(r))),
152        content_type,
153        provenance,
154    )
155}
156
157/// `-> impl Stream<Item = Progress<T, P>>`: `Update(p)` → a progress frame
158/// carrying `p`; `Item(t)` → a data frame carrying `t`. Then `done`.
159pub fn wrap_progress_stream<T, P>(
160    stream: impl Stream<Item = Progress<T, P>> + Send + 'static,
161    content_type: &'static str,
162    provenance: Vec<String>,
163) -> PlexusStream
164where
165    T: Serialize + Send + 'static,
166    P: Serialize + Send + 'static,
167{
168    wrap_frames(
169        stream.map(|step| match step {
170            Progress::Update(p) => Out::Progress(p),
171            Progress::Item(t) => Out::Data(t),
172        }),
173        content_type,
174        provenance,
175    )
176}
177
178/// `-> impl Stream<Item = Result<Progress<T, P>, E>>`: `Ok(Update(p))` → a
179/// progress frame; `Ok(Item(t))` → a data frame `{"ok": t}`; `Err(e)` → a data
180/// frame `{"err": e}`. Then `done`.
181pub fn wrap_result_progress_stream<T, P, E>(
182    stream: impl Stream<Item = Result<Progress<T, P>, E>> + Send + 'static,
183    content_type: &'static str,
184    provenance: Vec<String>,
185) -> PlexusStream
186where
187    T: Serialize + Send + 'static,
188    P: Serialize + Send + 'static,
189    E: Serialize + Send + 'static,
190{
191    wrap_frames(
192        stream.map(|r| match r {
193            Ok(Progress::Update(p)) => Out::Progress(p),
194            Ok(Progress::Item(t)) => Out::Data(WireResult(Ok(t))),
195            Err(e) => Out::Data(WireResult(Err(e))),
196        }),
197        content_type,
198        provenance,
199    )
200}
201
202/// The one place frames get their metadata: every data item goes through the
203/// credential capture `wrap_stream` has always applied, every progress value
204/// is serialized as-is, and exactly one `done` follows the last item.
205fn wrap_frames<D, P>(
206    stream: impl Stream<Item = Out<D, P>> + Send + 'static,
207    content_type: &'static str,
208    provenance: Vec<String>,
209) -> PlexusStream
210where
211    D: Serialize + Send + 'static,
212    P: Serialize + Send + 'static,
213{
214    let plexus_hash = PlexusContext::hash();
215    let metadata = Arc::new(StreamMetadata::new(provenance.clone(), plexus_hash.clone()));
216    let done = StreamMetadata::new(provenance, plexus_hash);
217    Box::pin(Wrapped::<_, OutForm> {
218        inner: stream,
219        metadata,
220        content_type,
221        done: Some(done),
222        ended: false,
223        form: std::marker::PhantomData,
224    })
225}
226
227pin_project_lite::pin_project! {
228    /// Every wrapper's stream. PERF-7: each event is a `Data` item whose
229    /// metadata is the stream's (shared, not cloned), whose content type is
230    /// the method's, and whose content is the event encoded once — straight
231    /// into the WebSocket pipe's buffer when the pipe polls this stream
232    /// ([`super::wire::pipe`]), as a `Value` anywhere else. RETURNS-8: `K`
233    /// is the signature form's [`Form`] — what one item of the method's
234    /// stream becomes (a data frame, or a progress frame).
235    struct Wrapped<S, K> {
236        #[pin]
237        inner: S,
238        metadata: Arc<StreamMetadata>,
239        content_type: &'static str,
240        done: Option<StreamMetadata>,
241        ended: bool,
242        form: std::marker::PhantomData<fn() -> K>,
243    }
244}
245
246/// RETURNS-8: what one item of a wrapped stream becomes.
247trait Form<I> {
248    fn frame(item: I, metadata: &Arc<StreamMetadata>, content_type: &'static str) -> PlexusStreamItem;
249}
250
251/// `wrap_stream`'s form: every item is data.
252struct DataForm;
253
254impl<T: Serialize> Form<T> for DataForm {
255    fn frame(event: T, metadata: &Arc<StreamMetadata>, content_type: &'static str) -> PlexusStreamItem {
256        PlexusStreamItem::Data {
257            metadata: metadata.clone(),
258            content_type: std::borrow::Cow::Borrowed(content_type),
259            content: content_of(&event),
260        }
261    }
262}
263
264/// The other forms': an [`Out`] — data, or a progress value (RETURNS-6's
265/// progress frame, the method's `P` serialized as-is: progress reports carry
266/// no credentials).
267struct OutForm;
268
269impl<D: Serialize, P: Serialize> Form<Out<D, P>> for OutForm {
270    fn frame(out: Out<D, P>, metadata: &Arc<StreamMetadata>, content_type: &'static str) -> PlexusStreamItem {
271        match out {
272            Out::Data(item) => DataForm::frame(item, metadata, content_type),
273            Out::Progress(p) => PlexusStreamItem::progress(
274                (**metadata).clone(),
275                content_type.to_string(),
276                serde_json::to_value(&p).unwrap_or(serde_json::Value::Null),
277            ),
278        }
279    }
280}
281
282impl<S, K> Stream for Wrapped<S, K>
283where
284    S: Stream,
285    K: Form<S::Item>,
286{
287    type Item = PlexusStreamItem;
288
289    fn poll_next(self: Pin<&mut Self>, cx: &mut std::task::Context<'_>) -> std::task::Poll<Option<PlexusStreamItem>> {
290        use std::task::Poll;
291        let this = self.project();
292        if !*this.ended {
293            // A stream the method polls inside its own (a call it routes and
294            // reads in process) is not the pipe's: one level deeper.
295            match super::wire::nested(|| this.inner.poll_next(cx)) {
296                Poll::Ready(Some(event)) => return Poll::Ready(Some(K::frame(event, this.metadata, this.content_type))),
297                Poll::Ready(None) => *this.ended = true,
298                Poll::Pending => return Poll::Pending,
299            }
300        }
301        Poll::Ready(this.done.take().map(|metadata| PlexusStreamItem::Done { metadata }))
302    }
303}
304
305/// An event's content: encoded once into the pipe's buffer when the pipe
306/// polls this stream (PERF-7), else — and for an event carrying a
307/// credential, whose envelope is assembled as before — a `Value`.
308///
309/// # Dispatch-time credential interception (AUTHZ-CRED-CORE-2)
310///
311/// Either way the serialization runs under the credential capture: a
312/// `Credential<T>` writes its sentinel inline and its value is captured.
313/// An event that captured none is today's payload exactly (encoded, the
314/// same JSON); one that captured any takes the `Value` path, where
315/// [`assemble_envelope_content`] adds its `_credentials` envelope.
316///
317/// The cookie projector is `None` because plexus-core does not know what
318/// transport is attached to this stream; the transport may project later.
319fn content_of<T: Serialize>(event: &T) -> super::wire::Content {
320    if let Some(content) = super::wire::encode(event) {
321        return content;
322    }
323    let (payload, captured) = serialize_with_credential_capture(event);
324    let (content, _hints) = assemble_envelope_content(payload, captured, &CookieProjector::None);
325    super::wire::Content::from(content)
326}
327
328/// Create a bidirectional channel and wrap a stream, merging Request items
329///
330/// This function:
331/// 1. Creates a BidirChannel connected to an internal mpsc channel
332/// 2. Wraps the user's typed stream into PlexusStreamItems
333/// 3. Merges in any Request items emitted by the BidirChannel
334/// 4. Returns both the channel (for the activation to use) and the merged stream
335///
336/// # Arguments
337///
338/// * `content_type` - Content type string for data items (e.g., "interactive.wizard")
339/// * `provenance` - Provenance path for metadata
340///
341/// # Returns
342///
343/// Returns a tuple of:
344/// * `Arc<BidirChannel<Req, Resp>>` - The bidirectional channel for the activation
345/// * A closure that takes the user's stream and returns the merged PlexusStream
346///
347/// # Example
348///
349/// ```ignore
350/// let (ctx, wrap_fn) = create_bidir_stream::<StandardRequest, StandardResponse>(
351///     "interactive.wizard",
352///     vec!["interactive".into()],
353/// );
354/// let user_stream = activation.wizard(&ctx).await;
355/// let merged_stream = wrap_fn(user_stream);
356/// ```
357pub fn create_bidir_stream<Req, Resp>(
358    _content_type: &'static str,
359    provenance: Vec<String>,
360) -> (
361    Arc<BidirChannel<Req, Resp>>,
362    impl FnOnce(Pin<Box<dyn Stream<Item = PlexusStreamItem> + Send>>) -> PlexusStream,
363)
364where
365    Req: Serialize + DeserializeOwned + Send + Sync + 'static,
366    Resp: Serialize + DeserializeOwned + Send + Sync + 'static,
367{
368    let plexus_hash = PlexusContext::hash();
369
370    // Create channel for BidirChannel to send Request items
371    let (bidir_tx, bidir_rx) = mpsc::channel::<PlexusStreamItem>(32);
372
373    // Create the BidirChannel with:
374    // - bidirectional_supported = true (we support it)
375    // - use_global_registry = true (responses come via substrate.respond)
376    let bidir_channel = Arc::new(BidirChannel::<Req, Resp>::new(
377        bidir_tx,
378        true,  // bidirectional_supported
379        provenance.clone(),
380        plexus_hash.clone(),
381    ));
382
383    // Create the wrapper closure
384    let wrap_fn = move |user_stream: Pin<Box<dyn Stream<Item = PlexusStreamItem> + Send>>| -> PlexusStream {
385        let bidir_stream = ReceiverStream::new(bidir_rx);
386
387        // Use stream::select to interleave items from both streams
388        // This allows Request items to appear in the stream alongside Data items
389        let merged = stream::select(user_stream, bidir_stream);
390
391        Box::pin(merged)
392    };
393
394    (bidir_channel, wrap_fn)
395}
396
397/// Wrap a typed stream with bidirectional support
398///
399/// Convenience wrapper that creates a BidirChannel and wraps the stream in one call.
400/// The channel is returned for use by the activation.
401///
402/// # Type Parameters
403///
404/// * `T` - The type of items in the user's stream
405/// * `Req` - Request type for bidirectional channel
406/// * `Resp` - Response type for bidirectional channel
407///
408/// # Example
409///
410/// ```ignore
411/// use plexus_core::plexus::{StandardRequest, StandardResponse, wrap_stream_with_bidir};
412///
413/// let (ctx, stream) = wrap_stream_with_bidir::<_, StandardRequest, StandardResponse>(
414///     user_stream,
415///     "interactive.wizard",
416///     vec!["interactive".into()],
417/// );
418/// // ctx can now be used for bidirectional requests
419/// // stream includes both data items and any Request items
420/// ```
421pub fn wrap_stream_with_bidir<T, Req, Resp>(
422    stream: impl Stream<Item = T> + Send + 'static,
423    content_type: &'static str,
424    provenance: Vec<String>,
425) -> (Arc<BidirChannel<Req, Resp>>, PlexusStream)
426where
427    T: Serialize + Send + 'static,
428    Req: Serialize + DeserializeOwned + Send + Sync + 'static,
429    Resp: Serialize + DeserializeOwned + Send + Sync + 'static,
430{
431    let (ctx, wrap_fn) = create_bidir_stream::<Req, Resp>(content_type, provenance.clone());
432
433    // Wrap the user's typed stream into PlexusStreamItems
434    let wrapped_user_stream = wrap_stream(stream, content_type, provenance);
435
436    // Merge with bidir stream
437    let merged = wrap_fn(wrapped_user_stream);
438
439    (ctx, merged)
440}
441
442/// Create an error stream
443///
444/// Returns a single-item stream containing an error frame carrying `error`.
445/// From a `PlexusError`: `error_stream(RemoteError::from(&e), provenance, false)`.
446pub fn error_stream(
447    error: RemoteError,
448    provenance: Vec<String>,
449    recoverable: bool,
450) -> PlexusStream {
451    let metadata = StreamMetadata::new(provenance, PlexusContext::hash());
452
453    Box::pin(stream::once(async move {
454        PlexusStreamItem::error(metadata, error, recoverable)
455    }))
456}
457
458/// Create a done stream
459///
460/// Returns a single-item stream containing a done event.
461pub fn done_stream(provenance: Vec<String>) -> PlexusStream {
462    let metadata = StreamMetadata::new(provenance, PlexusContext::hash());
463
464    Box::pin(stream::once(async move {
465        PlexusStreamItem::Done { metadata }
466    }))
467}
468
469/// Create a progress stream
470///
471/// Returns a single-item stream containing a progress frame for the call
472/// `content_type` (e.g. "tickets.import"), carrying the method's progress
473/// value `content` — `serde_json::to_value(&p)` of its declared `P`.
474pub fn progress_stream(
475    content_type: String,
476    content: serde_json::Value,
477    provenance: Vec<String>,
478) -> PlexusStream {
479    let metadata = StreamMetadata::new(provenance, PlexusContext::hash());
480
481    Box::pin(stream::once(async move {
482        PlexusStreamItem::progress(metadata, content_type, content)
483    }))
484}
485
486#[cfg(test)]
487mod tests {
488    use super::*;
489    use futures::StreamExt;
490    use serde::{Deserialize, Serialize};
491
492    #[derive(Debug, Clone, Serialize, Deserialize)]
493    struct TestEvent {
494        value: i32,
495    }
496
497    #[tokio::test]
498    async fn test_wrap_stream() {
499        let events = vec![TestEvent { value: 1 }, TestEvent { value: 2 }];
500        let input_stream = stream::iter(events);
501
502        let wrapped = wrap_stream(input_stream, "test.event", vec!["test".into()]);
503        let items: Vec<_> = wrapped.collect().await;
504
505        // 2 data items + 1 done
506        assert_eq!(items.len(), 3);
507
508        // Check first item
509        match &items[0] {
510            PlexusStreamItem::Data {
511                content_type,
512                content,
513                metadata,
514            } => {
515                assert_eq!(content_type, "test.event");
516                assert_eq!(content["value"], 1);
517                assert_eq!(metadata.provenance, vec!["test"]);
518            }
519            _ => panic!("Expected Data item"),
520        }
521
522        // Check done at end
523        assert!(matches!(items[2], PlexusStreamItem::Done { .. }));
524    }
525
526    /// AUTHZ-CRED-CORE-2 AC #10 regression: a stream item whose payload
527    /// has no `Credential<T>` fields produces wire content that's
528    /// byte-identical to today (no `_credentials` key added). The path
529    /// goes through the new envelope-assembly machinery — this asserts
530    /// the additive-only property holds.
531    #[tokio::test]
532    async fn wrap_stream_credential_free_payload_is_wire_identical() {
533        let events = vec![TestEvent { value: 7 }];
534        let input_stream = stream::iter(events);
535
536        let wrapped = wrap_stream(input_stream, "test.event", vec!["t".into()]);
537        let items: Vec<_> = wrapped.collect().await;
538
539        assert_eq!(items.len(), 2); // 1 data + 1 done
540        match &items[0] {
541            PlexusStreamItem::Data { content, .. } => {
542                // Same shape as before AUTHZ-CRED-CORE-2: just the
543                // serialized payload as an object.
544                let obj = content.as_object().expect("object");
545                assert_eq!(obj.get("value").unwrap(), &serde_json::json!(7));
546                assert!(
547                    !obj.contains_key("_credentials"),
548                    "_credentials key MUST NOT appear on non-credential payloads"
549                );
550                assert_eq!(obj.len(), 1, "no extra fields");
551            }
552            _ => panic!("Expected Data item"),
553        }
554    }
555
556    /// AUTHZ-CRED-CORE-2 sentinel-emission: a payload containing a
557    /// `Credential<T>` field produces a Data item whose body has the
558    /// sentinel inline. Today the `_credentials` sidecar is absent
559    /// because plexus-auth-core's `DispatchCaptureGuard::install` is
560    /// `pub(crate)` and unreachable from this crate (see
561    /// `plans/AUTHZ/AUTHZ-CRED-CORE-2-RUN-NOTES.md` §Blocker). Once
562    /// the public exposure lands, the sidecar will populate
563    /// automatically — this test will continue passing AND the
564    /// `_credentials` assertion can flip from "absent" to "present
565    /// with the captured value".
566    #[tokio::test]
567    async fn wrap_stream_credential_bearing_payload_emits_sentinel_in_body() {
568        use plexus_auth_core::{
569            AttachmentSite, Credential, CredentialIssuer, CredentialKind, CredentialMetadata,
570            CredentialMinter, CredentialScheme, HeaderName, MethodPath, Origin, Scope,
571        };
572
573        // Construct a credential and embed it in a payload. The minter
574        // is `pub(crate)` to plexus-auth-core; we can't reach its
575        // constructor from here, but we CAN derive a credential indirectly
576        // by using the `Serialize` impl through a stream — which is
577        // exactly what dispatch does in production. For this test we
578        // construct via a workaround: serialize a struct containing a
579        // sentinel-typed value directly to confirm the wrap_stream path
580        // routes it.
581        //
582        // (Once AUTHZ-CRED-CORE-2-a lands and exposes a public minter or
583        // capture API, this test can be tightened to assert the captured
584        // sidecar entry too.)
585
586        // Mint via the test-internal API path. We need a CredentialMinter
587        // for this test; the constructor lives behind the seal so we
588        // cannot construct one. Instead we drive the test through a
589        // typed payload that already contains a sentinel-shaped value
590        // by Serializing a `Credential<T>` via the public API — which
591        // works because plexus-auth-core's Serialize impl emits the
592        // sentinel unconditionally.
593        //
594        // We need access to a Credential<T>. Since
595        // `CredentialMinter::new_sealed` is pub(crate), this test
596        // exercises the wrap_stream serialization path through the
597        // already-public `Credential<T>` Serialize impl by going via a
598        // domain wrapper that serde renders identically:
599        let _ = (
600            CredentialMinter::issuer, // satisfy unused-import for diagnostic
601            Credential::<String>::metadata,
602            CredentialIssuer::new(
603                Origin::new("ws://test"),
604                MethodPath::try_new("auth.login").unwrap(),
605            ),
606            CredentialMetadata::new(
607                CredentialKind::Bearer,
608                AttachmentSite::Header {
609                    name: HeaderName::try_new("authorization").unwrap(),
610                },
611                Some(CredentialScheme::new("Bearer ")),
612                Vec::<Scope>::new(),
613                None,
614                None,
615                None,
616                CredentialIssuer::new(
617                    Origin::new("ws://test"),
618                    MethodPath::try_new("auth.login").unwrap(),
619                ),
620            ),
621        );
622
623        // For this regression test, we send a payload that contains the
624        // raw sentinel shape directly, mimicking what
625        // `Credential<T>::Serialize` would emit. This confirms the
626        // wrap_stream path forwards the sentinel intact and does NOT
627        // strip or transform it.
628        #[derive(Serialize)]
629        struct LoginPayload {
630            user_id: String,
631            // In production this would be `Credential<String>`; here we
632            // hand-write the sentinel JSON the Serialize impl emits so
633            // we can run this test without minter access.
634            session: serde_json::Value,
635        }
636        let payload = LoginPayload {
637            user_id: "alice".into(),
638            session: serde_json::json!({ "$credential": "cred_0" }),
639        };
640        let input_stream = stream::iter(vec![payload]);
641
642        let wrapped = wrap_stream(input_stream, "auth.login.result", vec!["auth".into()]);
643        let items: Vec<_> = wrapped.collect().await;
644
645        let content = match &items[0] {
646            PlexusStreamItem::Data { content, .. } => content,
647            _ => panic!("Expected Data item"),
648        };
649
650        // Sentinel survives intact in the body.
651        assert_eq!(
652            content.get("session").unwrap(),
653            &serde_json::json!({ "$credential": "cred_0" })
654        );
655        // No _credentials sidecar today (see RUN-NOTES §Blocker). When
656        // plexus-auth-core exposes the guard publicly this assertion
657        // flips to checking sidecar presence.
658        let obj = content.as_object().unwrap();
659        assert!(!obj.contains_key("_credentials"),
660            "sidecar absent until plexus-auth-core exposes DispatchCaptureGuard::install");
661    }
662
663
664    #[tokio::test]
665    async fn test_error_stream() {
666        let stream = error_stream(
667            RemoteError::Execution {
668                message: "Something failed".into(),
669            },
670            vec!["test".into()],
671            false,
672        );
673        let items: Vec<_> = stream.collect().await;
674
675        assert_eq!(items.len(), 1);
676        match &items[0] {
677            PlexusStreamItem::Error {
678                error,
679                recoverable,
680                metadata,
681                ..
682            } => {
683                assert_eq!(
684                    error,
685                    &RemoteError::Execution {
686                        message: "Something failed".into()
687                    }
688                );
689                assert!(!recoverable);
690                assert_eq!(metadata.provenance, vec!["test"]);
691            }
692            _ => panic!("Expected Error item"),
693        }
694    }
695
696    #[tokio::test]
697    async fn test_error_stream_carries_recoverable() {
698        let stream = error_stream(RemoteError::Unauthenticated, vec!["test".into()], true);
699        let items: Vec<_> = stream.collect().await;
700
701        assert_eq!(items.len(), 1);
702        assert!(matches!(
703            &items[0],
704            PlexusStreamItem::Error {
705                error: RemoteError::Unauthenticated,
706                recoverable: true,
707                ..
708            }
709        ));
710    }
711
712    #[tokio::test]
713    async fn test_progress_stream() {
714        let stream = progress_stream(
715            "test.import".into(),
716            serde_json::json!({"message": "indexing", "percentage": 50.0}),
717            vec!["test".into()],
718        );
719        let items: Vec<_> = stream.collect().await;
720
721        assert_eq!(items.len(), 1);
722        match &items[0] {
723            PlexusStreamItem::Progress {
724                content_type,
725                content,
726                ..
727            } => {
728                assert_eq!(content_type, "test.import");
729                let note: plexus_client::Note =
730                    serde_json::from_value(content.clone()).expect("a Note");
731                assert_eq!(note, plexus_client::Note::new("indexing").with_percentage(50.0));
732            }
733            _ => panic!("Expected Progress item"),
734        }
735    }
736
737    // ------------------------------------------------------------------
738    // RETURNS-8: the per-form wrappers
739    // ------------------------------------------------------------------
740
741    /// `(type, content)` of every frame but the last, and asserts the last
742    /// is the stream's one `done`.
743    async fn frames(stream: PlexusStream) -> Vec<(&'static str, serde_json::Value)> {
744        let items: Vec<_> = stream.collect().await;
745        let (last, body) = items.split_last().expect("at least a done");
746        assert!(matches!(last, PlexusStreamItem::Done { .. }), "ends in done");
747        body.iter()
748            .map(|item| match item {
749                PlexusStreamItem::Data { content_type, content, .. } => {
750                    assert_eq!(content_type, "t.m");
751                    ("data", content.clone().into_value())
752                }
753                PlexusStreamItem::Progress { content_type, content, .. } => {
754                    assert_eq!(content_type, "t.m");
755                    ("progress", content.clone())
756                }
757                PlexusStreamItem::Done { .. } => panic!("a second done"),
758                other => panic!("unexpected frame {other:?}"),
759            })
760            .collect()
761    }
762
763    #[tokio::test]
764    async fn wrap_one_is_one_data_frame_then_done() {
765        let got = frames(wrap_one(TestEvent { value: 1 }, "t.m", vec!["t".into()])).await;
766        assert_eq!(got, vec![("data", serde_json::json!({"value": 1}))]);
767    }
768
769    #[tokio::test]
770    async fn wrap_one_result_carries_ok_or_err() {
771        let ok: Result<u32, String> = Ok(7);
772        let err: Result<u32, String> = Err("no".into());
773        assert_eq!(
774            frames(wrap_one_result(ok, "t.m", vec!["t".into()])).await,
775            vec![("data", serde_json::json!({"ok": 7}))]
776        );
777        assert_eq!(
778            frames(wrap_one_result(err, "t.m", vec!["t".into()])).await,
779            vec![("data", serde_json::json!({"err": "no"}))]
780        );
781    }
782
783    #[tokio::test]
784    async fn wrap_result_stream_carries_on_past_an_err() {
785        let items: Vec<Result<u32, String>> = vec![Ok(1), Err("bad".into()), Ok(3)];
786        let got = frames(wrap_result_stream(stream::iter(items), "t.m", vec!["t".into()])).await;
787        assert_eq!(
788            got,
789            vec![
790                ("data", serde_json::json!({"ok": 1})),
791                ("data", serde_json::json!({"err": "bad"})),
792                ("data", serde_json::json!({"ok": 3})),
793            ]
794        );
795    }
796
797    #[tokio::test]
798    async fn wrap_progress_stream_splits_updates_from_items() {
799        let steps: Vec<Progress<u32>> = vec![
800            Progress::Update(plexus_client::Note::new("half").with_percentage(50.0)),
801            Progress::Item(9),
802        ];
803        let got = frames(wrap_progress_stream(stream::iter(steps), "t.m", vec!["t".into()])).await;
804        assert_eq!(
805            got,
806            vec![
807                ("progress", serde_json::json!({"message": "half", "percentage": 50.0})),
808                ("data", serde_json::json!(9)),
809            ]
810        );
811    }
812
813    #[tokio::test]
814    async fn wrap_result_progress_stream_maps_all_three_cases() {
815        let steps: Vec<Result<Progress<u32, String>, String>> = vec![
816            Ok(Progress::Update("step".into())),
817            Ok(Progress::Item(1)),
818            Err("refused".into()),
819        ];
820        let got = frames(wrap_result_progress_stream(
821            stream::iter(steps),
822            "t.m",
823            vec!["t".into()],
824        ))
825        .await;
826        assert_eq!(
827            got,
828            vec![
829                ("progress", serde_json::json!("step")),
830                ("data", serde_json::json!({"ok": 1})),
831                ("data", serde_json::json!({"err": "refused"})),
832            ]
833        );
834    }
835}