1use 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
23pub type PlexusStream = Pin<Box<dyn Stream<Item = PlexusStreamItem> + Send>>;
25
26pub 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
73enum Out<D, P> {
95 Data(D),
96 Progress(P),
97}
98
99struct 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
109pub 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
122pub 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
139pub 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
157pub 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
178pub 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
202fn 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 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
246trait Form<I> {
248 fn frame(item: I, metadata: &Arc<StreamMetadata>, content_type: &'static str) -> PlexusStreamItem;
249}
250
251struct 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
264struct 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 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
305fn 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
328pub 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 let (bidir_tx, bidir_rx) = mpsc::channel::<PlexusStreamItem>(32);
372
373 let bidir_channel = Arc::new(BidirChannel::<Req, Resp>::new(
377 bidir_tx,
378 true, provenance.clone(),
380 plexus_hash.clone(),
381 ));
382
383 let wrap_fn = move |user_stream: Pin<Box<dyn Stream<Item = PlexusStreamItem> + Send>>| -> PlexusStream {
385 let bidir_stream = ReceiverStream::new(bidir_rx);
386
387 let merged = stream::select(user_stream, bidir_stream);
390
391 Box::pin(merged)
392 };
393
394 (bidir_channel, wrap_fn)
395}
396
397pub 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 let wrapped_user_stream = wrap_stream(stream, content_type, provenance);
435
436 let merged = wrap_fn(wrapped_user_stream);
438
439 (ctx, merged)
440}
441
442pub 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
458pub 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
469pub 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 assert_eq!(items.len(), 3);
507
508 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 assert!(matches!(items[2], PlexusStreamItem::Done { .. }));
524 }
525
526 #[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); match &items[0] {
541 PlexusStreamItem::Data { content, .. } => {
542 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 #[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 let _ = (
600 CredentialMinter::issuer, 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 #[derive(Serialize)]
629 struct LoginPayload {
630 user_id: String,
631 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 assert_eq!(
652 content.get("session").unwrap(),
653 &serde_json::json!({ "$credential": "cred_0" })
654 );
655 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 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}