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}