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};
8use serde::Serialize;
9use serde::de::DeserializeOwned;
10use std::pin::Pin;
11use std::sync::Arc;
12use tokio::sync::mpsc;
13use tokio_stream::wrappers::ReceiverStream;
14
15use super::bidirectional::BidirChannel;
16use super::context::PlexusContext;
17use super::credential_envelope::{
18    assemble_envelope_content, serialize_with_credential_capture, CookieProjector,
19};
20use super::types::{PlexusStreamItem, StreamMetadata};
21
22/// Type alias for boxed stream of PlexusStreamItem
23pub type PlexusStream = Pin<Box<dyn Stream<Item = PlexusStreamItem> + Send>>;
24
25/// Wrap a typed stream into PlexusStream with automatic Done event
26///
27/// This is the core helper for the caller-wraps architecture.
28/// Activations return typed domain events (e.g., HealthEvent),
29/// and the caller wraps them with metadata. A Done event is
30/// automatically appended when the stream completes.
31///
32/// # Dispatch-time credential interception (AUTHZ-CRED-CORE-2)
33///
34/// For every emitted item, this function routes the serialization through
35/// the dispatch-time credential capture machinery: a fresh sidecar is
36/// installed (per the RAII guard documented in
37/// `plexus_auth_core::DispatchCaptureGuard`), serialization runs (and
38/// each `Credential<T>` field emits its sentinel inline while the inner
39/// value is captured into the sidecar), and the resulting `(payload,
40/// captured)` pair is assembled into a wire envelope with an optional
41/// `_credentials` field. Payloads with zero `Credential<T>` fields are
42/// wire-format-identical to today (additive only).
43///
44/// See `crate::plexus::credential_envelope` for the envelope assembly
45/// rules and `plans/AUTHZ/AUTHZ-CRED-CORE-2.md` for the contract.
46///
47/// # Example
48///
49/// ```ignore
50/// let stream = health.check();  // Returns Stream<Item = HealthEvent>
51/// let wrapped = wrap_stream(stream, "health.status", vec!["health".into()]);
52/// // Stream will emit: Data, Data, ..., Done
53/// ```
54pub fn wrap_stream<T: Serialize + Send + 'static>(
55    stream: impl Stream<Item = T> + Send + 'static,
56    content_type: &'static str,
57    provenance: Vec<String>,
58) -> PlexusStream {
59    let plexus_hash = PlexusContext::hash();
60    let metadata = Arc::new(StreamMetadata::new(provenance.clone(), plexus_hash.clone()));
61    let done = StreamMetadata::new(provenance, plexus_hash);
62    Box::pin(Wrapped { inner: stream, metadata, content_type, done: Some(done), ended: false })
63}
64
65pin_project_lite::pin_project! {
66    /// [`wrap_stream`]'s stream. PERF-7: each event is a `Data` item whose
67    /// metadata is the stream's (shared, not cloned), whose content type is
68    /// the method's, and whose content is the event encoded once — straight
69    /// into the WebSocket pipe's buffer when the pipe polls this stream
70    /// ([`super::wire::pipe`]), as a `Value` anywhere else.
71    struct Wrapped<S> {
72        #[pin]
73        inner: S,
74        metadata: Arc<StreamMetadata>,
75        content_type: &'static str,
76        done: Option<StreamMetadata>,
77        ended: bool,
78    }
79}
80
81impl<S, T> Stream for Wrapped<S>
82where
83    S: Stream<Item = T>,
84    T: Serialize,
85{
86    type Item = PlexusStreamItem;
87
88    fn poll_next(self: Pin<&mut Self>, cx: &mut std::task::Context<'_>) -> std::task::Poll<Option<PlexusStreamItem>> {
89        use std::task::Poll;
90        let this = self.project();
91        if !*this.ended {
92            // A stream the method polls inside its own (a call it routes and
93            // reads in process) is not the pipe's: one level deeper.
94            match super::wire::nested(|| this.inner.poll_next(cx)) {
95                Poll::Ready(Some(event)) => {
96                    return Poll::Ready(Some(PlexusStreamItem::Data {
97                        metadata: this.metadata.clone(),
98                        content_type: std::borrow::Cow::Borrowed(*this.content_type),
99                        content: content_of(&event),
100                    }))
101                }
102                Poll::Ready(None) => *this.ended = true,
103                Poll::Pending => return Poll::Pending,
104            }
105        }
106        Poll::Ready(this.done.take().map(|metadata| PlexusStreamItem::Done { metadata }))
107    }
108}
109
110/// An event's content: encoded once into the pipe's buffer when the pipe
111/// polls this stream (PERF-7), else — and for an event carrying a
112/// credential, whose envelope is assembled as before — a `Value`.
113///
114/// # Dispatch-time credential interception (AUTHZ-CRED-CORE-2)
115///
116/// Either way the serialization runs under the credential capture: a
117/// `Credential<T>` writes its sentinel inline and its value is captured.
118/// An event that captured none is today's payload exactly (encoded, the
119/// same JSON); one that captured any takes the `Value` path, where
120/// [`assemble_envelope_content`] adds its `_credentials` envelope.
121///
122/// The cookie projector is `None` because plexus-core does not know what
123/// transport is attached to this stream; the transport may project later.
124fn content_of<T: Serialize>(event: &T) -> super::wire::Content {
125    if let Some(content) = super::wire::encode(event) {
126        return content;
127    }
128    let (payload, captured) = serialize_with_credential_capture(event);
129    let (content, _hints) = assemble_envelope_content(payload, captured, &CookieProjector::None);
130    super::wire::Content::from(content)
131}
132
133/// Create a bidirectional channel and wrap a stream, merging Request items
134///
135/// This function:
136/// 1. Creates a BidirChannel connected to an internal mpsc channel
137/// 2. Wraps the user's typed stream into PlexusStreamItems
138/// 3. Merges in any Request items emitted by the BidirChannel
139/// 4. Returns both the channel (for the activation to use) and the merged stream
140///
141/// # Arguments
142///
143/// * `content_type` - Content type string for data items (e.g., "interactive.wizard")
144/// * `provenance` - Provenance path for metadata
145///
146/// # Returns
147///
148/// Returns a tuple of:
149/// * `Arc<BidirChannel<Req, Resp>>` - The bidirectional channel for the activation
150/// * A closure that takes the user's stream and returns the merged PlexusStream
151///
152/// # Example
153///
154/// ```ignore
155/// let (ctx, wrap_fn) = create_bidir_stream::<StandardRequest, StandardResponse>(
156///     "interactive.wizard",
157///     vec!["interactive".into()],
158/// );
159/// let user_stream = activation.wizard(&ctx).await;
160/// let merged_stream = wrap_fn(user_stream);
161/// ```
162pub fn create_bidir_stream<Req, Resp>(
163    _content_type: &'static str,
164    provenance: Vec<String>,
165) -> (
166    Arc<BidirChannel<Req, Resp>>,
167    impl FnOnce(Pin<Box<dyn Stream<Item = PlexusStreamItem> + Send>>) -> PlexusStream,
168)
169where
170    Req: Serialize + DeserializeOwned + Send + Sync + 'static,
171    Resp: Serialize + DeserializeOwned + Send + Sync + 'static,
172{
173    let plexus_hash = PlexusContext::hash();
174
175    // Create channel for BidirChannel to send Request items
176    let (bidir_tx, bidir_rx) = mpsc::channel::<PlexusStreamItem>(32);
177
178    // Create the BidirChannel with:
179    // - bidirectional_supported = true (we support it)
180    // - use_global_registry = true (responses come via substrate.respond)
181    let bidir_channel = Arc::new(BidirChannel::<Req, Resp>::new(
182        bidir_tx,
183        true,  // bidirectional_supported
184        provenance.clone(),
185        plexus_hash.clone(),
186    ));
187
188    // Create the wrapper closure
189    let wrap_fn = move |user_stream: Pin<Box<dyn Stream<Item = PlexusStreamItem> + Send>>| -> PlexusStream {
190        let bidir_stream = ReceiverStream::new(bidir_rx);
191
192        // Use stream::select to interleave items from both streams
193        // This allows Request items to appear in the stream alongside Data items
194        let merged = stream::select(user_stream, bidir_stream);
195
196        Box::pin(merged)
197    };
198
199    (bidir_channel, wrap_fn)
200}
201
202/// Wrap a typed stream with bidirectional support
203///
204/// Convenience wrapper that creates a BidirChannel and wraps the stream in one call.
205/// The channel is returned for use by the activation.
206///
207/// # Type Parameters
208///
209/// * `T` - The type of items in the user's stream
210/// * `Req` - Request type for bidirectional channel
211/// * `Resp` - Response type for bidirectional channel
212///
213/// # Example
214///
215/// ```ignore
216/// use plexus_core::plexus::{StandardRequest, StandardResponse, wrap_stream_with_bidir};
217///
218/// let (ctx, stream) = wrap_stream_with_bidir::<_, StandardRequest, StandardResponse>(
219///     user_stream,
220///     "interactive.wizard",
221///     vec!["interactive".into()],
222/// );
223/// // ctx can now be used for bidirectional requests
224/// // stream includes both data items and any Request items
225/// ```
226pub fn wrap_stream_with_bidir<T, Req, Resp>(
227    stream: impl Stream<Item = T> + Send + 'static,
228    content_type: &'static str,
229    provenance: Vec<String>,
230) -> (Arc<BidirChannel<Req, Resp>>, PlexusStream)
231where
232    T: Serialize + Send + 'static,
233    Req: Serialize + DeserializeOwned + Send + Sync + 'static,
234    Resp: Serialize + DeserializeOwned + Send + Sync + 'static,
235{
236    let (ctx, wrap_fn) = create_bidir_stream::<Req, Resp>(content_type, provenance.clone());
237
238    // Wrap the user's typed stream into PlexusStreamItems
239    let wrapped_user_stream = wrap_stream(stream, content_type, provenance);
240
241    // Merge with bidir stream
242    let merged = wrap_fn(wrapped_user_stream);
243
244    (ctx, merged)
245}
246
247/// Create an error stream
248///
249/// Returns a single-item stream containing an error event.
250pub fn error_stream(
251    message: String,
252    provenance: Vec<String>,
253    recoverable: bool,
254) -> PlexusStream {
255    let metadata = StreamMetadata::new(provenance, PlexusContext::hash());
256
257    Box::pin(stream::once(async move {
258        PlexusStreamItem::Error {
259            metadata,
260            message,
261            code: None,
262            recoverable,
263            fields: Default::default(),
264        }
265    }))
266}
267
268/// Create an error stream with error code
269///
270/// Returns a single-item stream containing an error event with a code.
271pub fn error_stream_with_code(
272    message: String,
273    code: String,
274    provenance: Vec<String>,
275    recoverable: bool,
276) -> PlexusStream {
277    let metadata = StreamMetadata::new(provenance, PlexusContext::hash());
278
279    Box::pin(stream::once(async move {
280        PlexusStreamItem::Error {
281            metadata,
282            message,
283            code: Some(code),
284            recoverable,
285            fields: Default::default(),
286        }
287    }))
288}
289
290/// Create a done stream
291///
292/// Returns a single-item stream containing a done event.
293pub fn done_stream(provenance: Vec<String>) -> PlexusStream {
294    let metadata = StreamMetadata::new(provenance, PlexusContext::hash());
295
296    Box::pin(stream::once(async move {
297        PlexusStreamItem::Done { metadata }
298    }))
299}
300
301/// Create a progress stream
302///
303/// Returns a single-item stream containing a progress event.
304pub fn progress_stream(
305    message: String,
306    percentage: Option<f32>,
307    provenance: Vec<String>,
308) -> PlexusStream {
309    let metadata = StreamMetadata::new(provenance, PlexusContext::hash());
310
311    Box::pin(stream::once(async move {
312        PlexusStreamItem::Progress {
313            metadata,
314            message,
315            percentage,
316        }
317    }))
318}
319
320#[cfg(test)]
321mod tests {
322    use super::*;
323    use futures::StreamExt;
324    use serde::{Deserialize, Serialize};
325
326    #[derive(Debug, Clone, Serialize, Deserialize)]
327    struct TestEvent {
328        value: i32,
329    }
330
331    #[tokio::test]
332    async fn test_wrap_stream() {
333        let events = vec![TestEvent { value: 1 }, TestEvent { value: 2 }];
334        let input_stream = stream::iter(events);
335
336        let wrapped = wrap_stream(input_stream, "test.event", vec!["test".into()]);
337        let items: Vec<_> = wrapped.collect().await;
338
339        // 2 data items + 1 done
340        assert_eq!(items.len(), 3);
341
342        // Check first item
343        match &items[0] {
344            PlexusStreamItem::Data {
345                content_type,
346                content,
347                metadata,
348            } => {
349                assert_eq!(content_type, "test.event");
350                assert_eq!(content["value"], 1);
351                assert_eq!(metadata.provenance, vec!["test"]);
352            }
353            _ => panic!("Expected Data item"),
354        }
355
356        // Check done at end
357        assert!(matches!(items[2], PlexusStreamItem::Done { .. }));
358    }
359
360    /// AUTHZ-CRED-CORE-2 AC #10 regression: a stream item whose payload
361    /// has no `Credential<T>` fields produces wire content that's
362    /// byte-identical to today (no `_credentials` key added). The path
363    /// goes through the new envelope-assembly machinery — this asserts
364    /// the additive-only property holds.
365    #[tokio::test]
366    async fn wrap_stream_credential_free_payload_is_wire_identical() {
367        let events = vec![TestEvent { value: 7 }];
368        let input_stream = stream::iter(events);
369
370        let wrapped = wrap_stream(input_stream, "test.event", vec!["t".into()]);
371        let items: Vec<_> = wrapped.collect().await;
372
373        assert_eq!(items.len(), 2); // 1 data + 1 done
374        match &items[0] {
375            PlexusStreamItem::Data { content, .. } => {
376                // Same shape as before AUTHZ-CRED-CORE-2: just the
377                // serialized payload as an object.
378                let obj = content.as_object().expect("object");
379                assert_eq!(obj.get("value").unwrap(), &serde_json::json!(7));
380                assert!(
381                    !obj.contains_key("_credentials"),
382                    "_credentials key MUST NOT appear on non-credential payloads"
383                );
384                assert_eq!(obj.len(), 1, "no extra fields");
385            }
386            _ => panic!("Expected Data item"),
387        }
388    }
389
390    /// AUTHZ-CRED-CORE-2 sentinel-emission: a payload containing a
391    /// `Credential<T>` field produces a Data item whose body has the
392    /// sentinel inline. Today the `_credentials` sidecar is absent
393    /// because plexus-auth-core's `DispatchCaptureGuard::install` is
394    /// `pub(crate)` and unreachable from this crate (see
395    /// `plans/AUTHZ/AUTHZ-CRED-CORE-2-RUN-NOTES.md` §Blocker). Once
396    /// the public exposure lands, the sidecar will populate
397    /// automatically — this test will continue passing AND the
398    /// `_credentials` assertion can flip from "absent" to "present
399    /// with the captured value".
400    #[tokio::test]
401    async fn wrap_stream_credential_bearing_payload_emits_sentinel_in_body() {
402        use plexus_auth_core::{
403            AttachmentSite, Credential, CredentialIssuer, CredentialKind, CredentialMetadata,
404            CredentialMinter, CredentialScheme, HeaderName, MethodPath, Origin, Scope,
405        };
406
407        // Construct a credential and embed it in a payload. The minter
408        // is `pub(crate)` to plexus-auth-core; we can't reach its
409        // constructor from here, but we CAN derive a credential indirectly
410        // by using the `Serialize` impl through a stream — which is
411        // exactly what dispatch does in production. For this test we
412        // construct via a workaround: serialize a struct containing a
413        // sentinel-typed value directly to confirm the wrap_stream path
414        // routes it.
415        //
416        // (Once AUTHZ-CRED-CORE-2-a lands and exposes a public minter or
417        // capture API, this test can be tightened to assert the captured
418        // sidecar entry too.)
419
420        // Mint via the test-internal API path. We need a CredentialMinter
421        // for this test; the constructor lives behind the seal so we
422        // cannot construct one. Instead we drive the test through a
423        // typed payload that already contains a sentinel-shaped value
424        // by Serializing a `Credential<T>` via the public API — which
425        // works because plexus-auth-core's Serialize impl emits the
426        // sentinel unconditionally.
427        //
428        // We need access to a Credential<T>. Since
429        // `CredentialMinter::new_sealed` is pub(crate), this test
430        // exercises the wrap_stream serialization path through the
431        // already-public `Credential<T>` Serialize impl by going via a
432        // domain wrapper that serde renders identically:
433        let _ = (
434            CredentialMinter::issuer, // satisfy unused-import for diagnostic
435            Credential::<String>::metadata,
436            CredentialIssuer::new(
437                Origin::new("ws://test"),
438                MethodPath::try_new("auth.login").unwrap(),
439            ),
440            CredentialMetadata::new(
441                CredentialKind::Bearer,
442                AttachmentSite::Header {
443                    name: HeaderName::try_new("authorization").unwrap(),
444                },
445                Some(CredentialScheme::new("Bearer ")),
446                Vec::<Scope>::new(),
447                None,
448                None,
449                None,
450                CredentialIssuer::new(
451                    Origin::new("ws://test"),
452                    MethodPath::try_new("auth.login").unwrap(),
453                ),
454            ),
455        );
456
457        // For this regression test, we send a payload that contains the
458        // raw sentinel shape directly, mimicking what
459        // `Credential<T>::Serialize` would emit. This confirms the
460        // wrap_stream path forwards the sentinel intact and does NOT
461        // strip or transform it.
462        #[derive(Serialize)]
463        struct LoginPayload {
464            user_id: String,
465            // In production this would be `Credential<String>`; here we
466            // hand-write the sentinel JSON the Serialize impl emits so
467            // we can run this test without minter access.
468            session: serde_json::Value,
469        }
470        let payload = LoginPayload {
471            user_id: "alice".into(),
472            session: serde_json::json!({ "$credential": "cred_0" }),
473        };
474        let input_stream = stream::iter(vec![payload]);
475
476        let wrapped = wrap_stream(input_stream, "auth.login.result", vec!["auth".into()]);
477        let items: Vec<_> = wrapped.collect().await;
478
479        let content = match &items[0] {
480            PlexusStreamItem::Data { content, .. } => content,
481            _ => panic!("Expected Data item"),
482        };
483
484        // Sentinel survives intact in the body.
485        assert_eq!(
486            content.get("session").unwrap(),
487            &serde_json::json!({ "$credential": "cred_0" })
488        );
489        // No _credentials sidecar today (see RUN-NOTES §Blocker). When
490        // plexus-auth-core exposes the guard publicly this assertion
491        // flips to checking sidecar presence.
492        let obj = content.as_object().unwrap();
493        assert!(!obj.contains_key("_credentials"),
494            "sidecar absent until plexus-auth-core exposes DispatchCaptureGuard::install");
495    }
496
497
498    #[tokio::test]
499    async fn test_error_stream() {
500        let stream = error_stream("Something failed".into(), vec!["test".into()], false);
501        let items: Vec<_> = stream.collect().await;
502
503        assert_eq!(items.len(), 1);
504        match &items[0] {
505            PlexusStreamItem::Error {
506                message,
507                recoverable,
508                code,
509                ..
510            } => {
511                assert_eq!(message, "Something failed");
512                assert!(!recoverable);
513                assert!(code.is_none());
514            }
515            _ => panic!("Expected Error item"),
516        }
517    }
518
519    #[tokio::test]
520    async fn test_error_stream_with_code() {
521        let stream = error_stream_with_code(
522            "Not found".into(),
523            "NOT_FOUND".into(),
524            vec!["test".into()],
525            true,
526        );
527        let items: Vec<_> = stream.collect().await;
528
529        assert_eq!(items.len(), 1);
530        match &items[0] {
531            PlexusStreamItem::Error {
532                message,
533                code,
534                recoverable,
535                ..
536            } => {
537                assert_eq!(message, "Not found");
538                assert_eq!(code.as_deref(), Some("NOT_FOUND"));
539                assert!(recoverable);
540            }
541            _ => panic!("Expected Error item"),
542        }
543    }
544}