1use std::{
11 sync::{
12 Arc, Mutex,
13 atomic::{AtomicUsize, Ordering},
14 },
15 task::Poll,
16};
17
18use futures::StreamExt;
19
20use crate::lock;
21use crate::{
22 completion::UnsupportedOption,
23 effect::{Answered, EffectId, EffectKind, HandlerDescriptor, HandlerKey},
24 error::{ErrorKind, ErrorReport},
25 streaming::{Relayed, StreamEvents},
26 tool::Touches,
27 wasm_compat::{WasmBoxedFuture, WasmCompatSend, WasmCompatSync},
28};
29
30#[cfg(test)]
31mod tests;
32
33pub type HandlerFuture<'a> = WasmBoxedFuture<'a, Reply>;
35
36pub trait Serve: WasmCompatSend + WasmCompatSync {
80 type Family: crate::effect::Served;
82
83 fn descriptor(&self) -> HandlerDescriptor;
86
87 fn key(&self) -> HandlerKey {
91 self.descriptor().key
92 }
93
94 fn serve(
96 &self,
97 kind: EffectKind,
98 dispatch: Dispatch,
99 ) -> impl Future<Output = Reply> + WasmCompatSend + use<'_, Self>;
100
101 fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
105 let _ = kind;
106 None
107 }
108
109 fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
114 let _ = kind;
115 Vec::new()
116 }
117}
118
119pub(crate) trait Handler: WasmCompatSend + WasmCompatSync {
121 fn descriptor(&self) -> HandlerDescriptor;
122 fn handle(&self, kind: EffectKind, dispatch: Dispatch) -> HandlerFuture<'_>;
123 fn footprint(&self, kind: &EffectKind) -> Option<Touches>;
124 fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption>;
125}
126
127#[diagnostic::do_not_recommend]
130impl<T: Serve> Handler for T {
131 fn descriptor(&self) -> HandlerDescriptor {
132 Serve::descriptor(self)
133 }
134
135 fn handle(&self, kind: EffectKind, dispatch: Dispatch) -> HandlerFuture<'_> {
136 let observer = dispatch.observer.clone();
137 let folded = dispatch.folded.clone();
138 let streaming = dispatch.is_stream();
139 let level = Level::enter(&dispatch.serving);
140 Box::pin(async move {
141 let reply = self.serve(kind, dispatch).await;
142 if !level.outermost() {
147 return reply.observed(streaming, None, None);
148 }
149 let seen = observer.and_then(|slot| lock(&slot).take());
150 reply.observed(streaming, seen, folded)
151 })
152 }
153
154 fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
155 Serve::footprint(self, kind)
156 }
157
158 fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
159 Serve::check(self, kind)
160 }
161}
162
163impl<H: Serve + ?Sized> Serve for Arc<H> {
166 type Family = H::Family;
167
168 fn descriptor(&self) -> HandlerDescriptor {
169 (**self).descriptor()
170 }
171
172 fn key(&self) -> HandlerKey {
173 (**self).key()
174 }
175
176 async fn serve(&self, kind: EffectKind, dispatch: Dispatch) -> Reply {
177 (**self).serve(kind, dispatch).await
178 }
179
180 fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
181 (**self).footprint(kind)
182 }
183
184 fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
185 (**self).check(kind)
186 }
187}
188
189struct Level(Arc<AtomicUsize>);
192
193impl Level {
194 fn enter(serving: &Arc<AtomicUsize>) -> Self {
195 serving.fetch_add(1, Ordering::AcqRel);
196 Self(serving.clone())
197 }
198
199 fn outermost(&self) -> bool {
202 self.0.load(Ordering::Acquire) == 1
203 }
204}
205
206impl Drop for Level {
207 fn drop(&mut self) {
208 self.0.fetch_sub(1, Ordering::AcqRel);
209 }
210}
211
212#[derive(Clone)]
215pub struct ErasedHandler {
216 inner: ErasedInner,
217 key: HandlerKey,
219}
220
221#[cfg(not(target_family = "wasm"))]
222type ErasedInner = Arc<dyn Handler + Send + Sync>;
223#[cfg(target_family = "wasm")]
224type ErasedInner = Arc<dyn Handler>;
225
226impl ErasedHandler {
227 pub fn new(handler: impl Serve + 'static) -> Self {
229 Self {
230 key: handler.key(),
231 inner: Arc::new(handler),
232 }
233 }
234
235 pub fn unavailable(descriptor: HandlerDescriptor, why: impl Into<String>) -> Self {
258 Self::new(Unavailable {
259 descriptor,
260 why: why.into(),
261 })
262 }
263
264 pub fn layered(self, intercept: impl super::Intercept) -> Self {
268 Self::new(super::Layer::new(self, intercept))
269 }
270
271 pub fn map_stream<M, F>(self, name: impl Into<String>, make: M) -> Self
289 where
290 M: Fn(Arc<crate::tool::PublishedContext>) -> F + WasmCompatSend + WasmCompatSync + 'static,
291 F: FnMut(Relayed) -> Vec<Relayed> + WasmCompatSend + 'static,
292 {
293 Self::new(super::map::MapStream::new(self, name.into(), make))
294 }
295
296 pub fn descriptor(&self) -> HandlerDescriptor {
298 self.inner.descriptor()
299 }
300
301 pub fn key(&self) -> &HandlerKey {
303 &self.key
304 }
305
306 pub fn handle(&self, kind: EffectKind, dispatch: Dispatch) -> HandlerFuture<'_> {
308 self.inner.handle(kind, dispatch)
309 }
310
311 pub fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
314 self.inner.footprint(kind)
315 }
316
317 pub fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
319 self.inner.check(kind)
320 }
321
322 pub fn ptr_eq(&self, other: &Self) -> bool {
324 Arc::ptr_eq(&self.inner, &other.inner)
325 }
326}
327
328impl std::fmt::Debug for ErasedHandler {
329 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
330 f.debug_struct("ErasedHandler")
331 .field("key", &self.key)
332 .finish_non_exhaustive()
333 }
334}
335
336struct Unavailable {
339 descriptor: HandlerDescriptor,
340 why: String,
341}
342
343impl Serve for Unavailable {
344 type Family = crate::effect::family::Dynamic;
345
346 fn descriptor(&self) -> HandlerDescriptor {
347 self.descriptor.clone()
348 }
349
350 async fn serve(&self, _kind: EffectKind, _dispatch: Dispatch) -> Reply {
351 Reply::Outcome(Err(ErrorReport::new(
352 ErrorKind::HandlerUnavailable,
353 self.why.clone(),
354 )))
355 }
356}
357
358impl Serve for ErasedHandler {
360 type Family = crate::effect::family::Dynamic;
361
362 fn descriptor(&self) -> HandlerDescriptor {
363 self.inner.descriptor()
364 }
365
366 fn key(&self) -> HandlerKey {
367 self.key.clone()
368 }
369
370 async fn serve(&self, kind: EffectKind, dispatch: Dispatch) -> Reply {
371 self.handle(kind, dispatch).await
372 }
373
374 fn footprint(&self, kind: &EffectKind) -> Option<Touches> {
375 self.inner.footprint(kind)
376 }
377
378 fn check(&self, kind: &EffectKind) -> Vec<UnsupportedOption> {
379 self.inner.check(kind)
380 }
381}
382
383#[derive(Default)]
387pub struct StreamTap {
388 finished: bool,
390}
391
392impl StreamTap {
393 pub fn new() -> Self {
395 Self::default()
396 }
397
398 pub fn observe(
401 &mut self,
402 item: &Result<Relayed, ErrorReport>,
403 ) -> Option<Result<Answered, ErrorReport>> {
404 if self.finished {
405 return None;
406 }
407 let outcome = match item {
408 Ok(Relayed::Origin(_) | Relayed::Item(_) | Relayed::Usage(_)) => None,
409 Ok(Relayed::Done(response)) => Some(Ok(Answered::Completion(Arc::clone(response)))),
410 Err(report) => Some(Err(report.clone())),
411 };
412 self.finished = outcome.is_some();
413 outcome
414 }
415}
416
417pub fn stream_truncated() -> ErrorReport {
421 ErrorReport::from(&crate::error::ProviderError::Truncated)
422}
423
424pub enum Reply {
426 Outcome(Result<Answered, ErrorReport>),
428 Stream(StreamEvents),
430}
431
432impl Reply {
433 pub async fn into_outcome(self) -> Result<Answered, ErrorReport> {
435 self.folded_outcome(None).await
436 }
437
438 pub(crate) async fn folded_outcome(
439 self,
440 folded: Option<Folded>,
441 ) -> Result<Answered, ErrorReport> {
442 match self {
443 Self::Outcome(outcome) => outcome,
444 Self::Stream(mut stream) => {
445 let mut fold = StreamTap::new();
446 while let Some(item) = stream.next().await {
447 let outcome = match &folded {
448 Some(folded) => lock(folded).take(),
449 None => fold.observe(&item),
450 };
451 if let Some(outcome) = outcome {
452 return outcome;
453 }
454 }
455 Err(stream_truncated())
456 }
457 }
458 }
459
460 pub fn into_stream(self) -> StreamEvents {
463 match self {
464 Self::Stream(stream) => stream,
465 Self::Outcome(outcome) => Box::pin(futures::stream::iter(match outcome {
466 Ok(Answered::Completion(response)) => {
467 let items = crate::operation::completion::events_of(&response);
468 std::iter::once(Ok(Relayed::Origin(response.origin.clone())))
469 .chain(items.into_iter().map(|item| Ok(Relayed::Item(item))))
470 .chain(std::iter::once(Ok(Relayed::Done(response))))
471 .collect()
472 }
473 Ok(other) => vec![Err(wrong_stream_answer(&other))],
474 Err(report) => vec![Err(report)],
475 })),
476 }
477 }
478
479 fn observed(self, streaming: bool, mut seen: Option<Observed>, folded: Option<Folded>) -> Self {
480 if !streaming && let Self::Outcome(outcome) = self {
481 if let Some(seen) = &mut seen {
482 seen.outcome(outcome.clone());
483 }
484 return Self::Outcome(outcome);
485 }
486 if seen.is_none() && folded.is_none() {
487 return if streaming {
488 Self::Stream(self.into_stream())
489 } else {
490 self
491 };
492 }
493 let mut original = match &self {
494 Self::Outcome(Ok(Answered::Completion(response))) => {
495 Some(Ok(Answered::Completion(response.clone())))
496 }
497 _ => None,
498 };
499 let mut stream = self.into_stream();
500 let mut fold = StreamTap::new();
501 let mut finished = false;
502 Self::Stream(Box::pin(futures::stream::poll_fn(move |cx| {
503 let item = match stream.as_mut().poll_next(cx) {
504 Poll::Pending => return Poll::Pending,
505 Poll::Ready(item) => item,
506 };
507 if let Some(item) = &item {
508 let mut outcome = if finished { None } else { fold.observe(item) };
509 finished |= outcome.is_some();
510 if let Some(seen) = &mut seen {
511 let recorded = match &outcome {
514 None => None,
515 Some(_) if matches!(item, Ok(Relayed::Done(_))) && original.is_some() => {
516 original.take()
517 }
518 Some(_) if folded.is_none() => outcome.take(),
519 Some(outcome) => Some(outcome.clone()),
520 };
521 if streaming {
522 seen.item(item, recorded);
523 } else if let Some(recorded) = recorded {
524 seen.outcome(recorded);
525 }
526 }
527 if let (Some(outcome), Some(folded)) = (outcome, &folded) {
528 *lock(folded) = Some(outcome);
529 }
530 } else if !finished {
531 finished = true;
532 let outcome = Err(stream_truncated());
533 if let Some(seen) = &mut seen {
534 seen.outcome(outcome.clone());
535 }
536 if let Some(folded) = &folded {
537 *lock(folded) = Some(outcome);
538 }
539 }
540 Poll::Ready(item)
541 })))
542 }
543}
544
545pub(crate) type Folded = Arc<Mutex<Option<Result<Answered, ErrorReport>>>>;
548
549pub struct Dispatch {
552 id: EffectId,
553 streaming: bool,
554 scopes: Vec<Arc<dyn std::any::Any + Send + Sync>>,
555 observer: Option<Arc<Mutex<Option<Observed>>>>,
556 serving: Arc<AtomicUsize>,
559 folded: Option<Folded>,
560}
561
562impl Dispatch {
563 pub fn new(id: EffectId, streaming: bool) -> Self {
565 Self {
566 id,
567 streaming,
568 scopes: Vec::new(),
569 observer: None,
570 serving: Arc::default(),
571 folded: None,
572 }
573 }
574
575 pub const fn id(&self) -> EffectId {
577 self.id
578 }
579
580 pub const fn is_stream(&self) -> bool {
582 self.streaming
583 }
584
585 pub fn with_scope(mut self, scope: Arc<dyn std::any::Any + Send + Sync>) -> Self {
587 self.scopes.push(scope);
588 self
589 }
590
591 pub fn scope<T: std::any::Any + Send + Sync>(&self) -> Option<Arc<T>> {
593 self.scopes
594 .iter()
595 .find_map(|scope| Arc::downcast::<T>(scope.clone()).ok())
596 }
597
598 pub fn scopes(&self) -> Vec<Arc<dyn std::any::Any + Send + Sync>> {
600 self.scopes.clone()
601 }
602
603 pub fn recorded_by(mut self, recorder: Arc<dyn super::Recorder + Send + Sync>) -> Self {
612 let published = self.scope::<crate::tool::PublishedContext>();
613 self.observer = Some(Arc::new(Mutex::new(Some(Observed {
614 recorder,
615 id: self.id,
616 published,
617 streamed: false,
618 told: false,
619 }))));
620 self
621 }
622
623 pub(crate) fn patched(&mut self, kind: &EffectKind) {
624 if let Some(slot) = &self.observer
625 && let Some(seen) = lock(slot).as_mut()
626 {
627 seen.recorder.patch(seen.id, kind.clone());
628 }
629 }
630
631 pub(crate) fn discard(&mut self) {
634 if let Some(slot) = &self.observer
635 && let Some(mut seen) = lock(slot).take()
636 {
637 seen.told = true;
638 seen.recorder.discard(seen.id);
639 }
640 }
641
642 pub(crate) fn inner(&mut self, folded: Option<Folded>) -> Self {
643 let observer = self.observer.as_ref().and_then(|slot| lock(slot).take());
644 Self {
645 id: self.id,
646 streaming: self.streaming,
647 scopes: self.scopes.clone(),
648 observer: observer.map(|seen| Arc::new(Mutex::new(Some(seen)))),
649 serving: Arc::default(),
650 folded,
651 }
652 }
653}
654
655struct Observed {
657 recorder: Arc<dyn super::Recorder + Send + Sync>,
658 id: EffectId,
659 published: Option<Arc<crate::tool::PublishedContext>>,
660 streamed: bool,
662 told: bool,
663}
664
665impl Observed {
666 fn outcome(&mut self, outcome: Result<Answered, ErrorReport>) {
668 if std::mem::replace(&mut self.told, true) {
669 return;
670 }
671 if let Some(output) = self
672 .published
673 .as_ref()
674 .and_then(|published| published.result_context())
675 {
676 self.recorder.tool_output(self.id, output);
677 }
678 self.recorder.resolve(self.id, outcome);
679 }
680
681 fn item(
682 &mut self,
683 item: &Result<Relayed, ErrorReport>,
684 outcome: Option<Result<Answered, ErrorReport>>,
685 ) {
686 match item {
687 Ok(Relayed::Item(item)) => {
689 if !std::mem::replace(&mut self.streamed, true) || self.recorder.keep_events() {
690 self.recorder.event(self.id, item);
691 }
692 }
693 Ok(Relayed::Origin(origin)) if self.recorder.keep_events() => {
694 self.recorder.origin(self.id, origin);
695 }
696 Err(error) if self.recorder.keep_events() => self.recorder.stream_error(self.id, error),
697 _ => {}
698 }
699 if let Some(outcome) = outcome {
700 self.outcome(outcome);
701 }
702 }
703}
704
705impl Drop for Observed {
706 fn drop(&mut self) {
707 self.outcome(Err(cancelled()));
708 }
709}
710
711fn wrong_stream_answer(other: &Answered) -> ErrorReport {
712 ErrorReport::new(
713 ErrorKind::Internal,
714 format!(
715 "a streaming dispatch was answered with a {} outcome",
716 other.family()
717 ),
718 )
719}
720
721pub fn cancelled() -> ErrorReport {
723 ErrorReport::new(
724 ErrorKind::Cancelled,
725 "the consumer cancelled the dispatch before it was answered",
726 )
727 .with_retryable(false)
728}
729
730#[derive(Debug, Clone, Copy, PartialEq, Eq, thiserror::Error)]
732#[error("the dispatch's consumer is gone")]
733pub struct SinkClosed;
734
735pub async fn serve_inline(
737 handler: &ErasedHandler,
738 kind: EffectKind,
739) -> Result<Answered, ErrorReport> {
740 serve_inline_with(handler, kind, Vec::new()).await
741}
742
743pub async fn serve_inline_with(
745 handler: &ErasedHandler,
746 kind: EffectKind,
747 scopes: Vec<Arc<dyn std::any::Any + Send + Sync>>,
748) -> Result<Answered, ErrorReport> {
749 let mut dispatch = Dispatch::new(EffectId::from_raw(0), false);
750 for scope in scopes {
751 dispatch = dispatch.with_scope(scope);
752 }
753 handler.handle(kind, dispatch).await.into_outcome().await
754}