Skip to main content

rig_agent/bus/
driver.rs

1//! Bus serving future, handler ownership, and dispatch recording.
2//!
3//! ```
4//! let (dispatcher, registrar, driver) = rig_agent::bus::Bus::channel();
5//! assert_eq!(driver.in_flight(), 0);
6//! ```
7
8use std::{
9    collections::{BTreeMap, BTreeSet, VecDeque},
10    fmt,
11    pin::Pin,
12    sync::Arc,
13    task::{Context, Poll},
14};
15
16use futures::{
17    Sink, SinkExt, StreamExt,
18    stream::{FusedStream, FuturesUnordered},
19};
20use tracing::Instrument;
21
22use rig_core::{
23    effect::{EffectId, EffectKind, HandlerDescriptor, HandlerKey, Outcome},
24    error::ErrorReport,
25    serve::{Dispatch, Observe, Origin, Recorder},
26    streaming::{Item, StreamEvent},
27    wasm_compat::WasmBoxedFuture,
28};
29
30use rig_core::serve::{ErasedHandler, Serve};
31
32use super::{
33    dispatcher::{Command, Dispatcher, Shared, handler_unavailable},
34    registrar::{Mailbox, Registrar, Registration},
35};
36
37use rig_core::serve::ServingPolicy;
38
39type InFlight = WasmBoxedFuture<'static, (HandlerKey, EffectId)>;
40type InFlightServing = Pin<Box<Serving>>;
41
42/// Shared observer state: the driver and each outstanding dispatch retain the
43/// same recorder, independently of the agent value that installed it.
44pub(crate) struct Recording(Arc<dyn Recorder + Send + Sync>);
45
46/// The record's view of one dispatch: the recorder, told by id.
47struct Recorded {
48    published: Option<Arc<rig_core::tool::PublishedContext>>,
49    recorder: Arc<dyn Recorder + Send + Sync>,
50    id: EffectId,
51}
52
53impl Observe for Recorded {
54    fn adapter_context(&self) -> Option<rig_core::observe::AdapterContext> {
55        self.recorder.adapter_context(self.id)
56    }
57
58    fn outcome(&mut self, outcome: &Result<Outcome, ErrorReport>) {
59        if let Some(output) = self
60            .published
61            .as_ref()
62            .and_then(|published| published.result_context())
63        {
64            self.recorder.tool_output(self.id, output);
65        }
66        self.recorder.resolve(self.id, outcome.clone());
67    }
68
69    fn keep_events(&self) -> bool {
70        self.recorder.keep_events()
71    }
72
73    fn event(&mut self, item: &Item<StreamEvent>) {
74        self.recorder.event(self.id, item);
75    }
76
77    fn origin(&mut self, origin: &rig_core::message::Origin) {
78        self.recorder.origin(self.id, origin);
79    }
80    fn stream_error(&mut self, error: &ErrorReport) {
81        self.recorder.stream_error(self.id, error);
82    }
83
84    fn discard(&mut self, _: &str) {
85        self.recorder.discard(self.id);
86    }
87
88    fn patch(&mut self, kind: &EffectKind) {
89        self.recorder.patch(self.id, kind.clone());
90    }
91}
92
93impl Recording {
94    pub(crate) fn new(recorder: impl Recorder + Send + Sync) -> Self {
95        Self(Arc::new(recorder))
96    }
97
98    fn observe(&self, dispatch: Dispatch, id: EffectId) -> Dispatch {
99        let published = dispatch.scope::<rig_core::tool::PublishedContext>();
100        dispatch.with_observer(Box::new(Recorded {
101            published,
102            recorder: Arc::clone(&self.0),
103            id,
104        }))
105    }
106}
107
108/// Serving future owning the bus's handler table. Shared dispatchers retain
109/// descriptors, not handlers. The owner must poll or spawn this future for
110/// dispatches to progress; it is `Send` on native targets and may be `!Send` on WASM.
111/// Completes after command-owning dispatchers are dropped and in-flight work drains.
112/// Dropping it fails unfinished and subsequent dispatches with `BusClosed`.
113pub struct BusDriver {
114    shared: Arc<Shared>,
115    mailbox: Arc<Mailbox>,
116    handlers: BTreeMap<HandlerKey, ErasedHandler>,
117    config: ServingPolicy,
118    in_flight: FuturesUnordered<InFlightServing>,
119    queued: BTreeMap<HandlerKey, VecDeque<Command>>,
120    busy: BTreeSet<HandlerKey>,
121    recorder: Option<Recording>,
122    commands_closed: bool,
123}
124
125impl fmt::Debug for BusDriver {
126    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
127        f.debug_struct("BusDriver")
128            .field("config", &self.config)
129            .field("in_flight", &self.in_flight.len())
130            .field(
131                "queued",
132                &self.queued.values().map(VecDeque::len).sum::<usize>(),
133            )
134            .field("handlers", &self.handlers.keys().collect::<Vec<_>>())
135            .finish_non_exhaustive()
136    }
137}
138
139impl BusDriver {
140    pub(super) fn new(shared: Arc<Shared>, mailbox: Arc<Mailbox>, config: ServingPolicy) -> Self {
141        Self {
142            shared,
143            mailbox,
144            handlers: BTreeMap::new(),
145            config,
146            in_flight: FuturesUnordered::new(),
147            queued: BTreeMap::new(),
148            busy: BTreeSet::new(),
149            recorder: None,
150            commands_closed: false,
151        }
152    }
153
154    /// Register or replace `key` immediately, publishing its descriptor.
155    /// Returns an error if registration is refused by [`Registrar::register`].
156    pub fn register(
157        &mut self,
158        key: impl Into<HandlerKey>,
159        handler: impl Serve + 'static,
160    ) -> Result<(), ErrorReport> {
161        self.register_erased(key, ErasedHandler::new(handler))
162    }
163
164    /// Register an already-erased handler.
165    pub fn register_erased(
166        &mut self,
167        key: impl Into<HandlerKey>,
168        handler: ErasedHandler,
169    ) -> Result<(), ErrorReport> {
170        self.registrar().register_erased(key, handler)?;
171        self.apply(self.mailbox.take_pending());
172        Ok(())
173    }
174
175    /// [`register`](Self::register), returning a [`Key`](rig_core::effect::Key) that carries the
176    /// family the handler proved by its descriptor.
177    pub fn register_typed<F: rig_core::effect::Family>(
178        &mut self,
179        key: impl Into<HandlerKey>,
180        handler: impl Serve + 'static,
181    ) -> Result<rig_core::effect::Key<F>, ErrorReport> {
182        let key = key.into();
183        let handler = ErasedHandler::new(handler);
184        let descriptor = handler.descriptor();
185        if descriptor.family.family() != F::FAMILY {
186            return Err(super::registrar::family_proof_failed(
187                &key,
188                F::FAMILY,
189                &descriptor,
190            ));
191        }
192        self.register_erased(key.clone(), handler)?;
193        Ok(rig_core::effect::Key::new_unchecked(key))
194    }
195
196    /// Remove the handler serving `key`. Returns whether one was registered.
197    pub fn deregister(&mut self, key: &HandlerKey) -> bool {
198        let removed = self.registrar().deregister(key);
199        self.apply(self.mailbox.take_pending());
200        removed
201    }
202
203    /// A handle for registering on this bus once the driver is out of hand
204    /// (spawned): see [`Registrar`].
205    pub fn registrar(&self) -> Registrar {
206        Registrar {
207            shared: Arc::clone(&self.shared),
208            mailbox: Arc::clone(&self.mailbox),
209        }
210    }
211
212    /// Install a handler and drop its predecessor without holding a lock.
213    /// Handler destructors may reenter the bus.
214    fn install(&mut self, key: HandlerKey, handler: ErasedHandler) {
215        if let Some(recording) = &self.recorder {
216            let described = handler.descriptor();
217            recording.0.handlers(vec![HandlerDescriptor {
218                key: key.clone(),
219                family: described.family,
220                layers: described.layers,
221            }]);
222        }
223        let displaced = self.handlers.insert(key, handler);
224        drop(displaced);
225    }
226
227    /// Apply what the registrars posted since the last poll.
228    fn apply_registrations(&mut self, cx: &Context<'_>) {
229        self.apply(self.mailbox.drain(cx));
230    }
231
232    fn apply(&mut self, registrations: VecDeque<Registration>) {
233        for registration in registrations {
234            match registration {
235                Registration::Install { key, handler } => self.install(key, handler),
236                Registration::Remove { key } => {
237                    let removed = self.handlers.remove(&key);
238                    drop(removed);
239                }
240            }
241        }
242    }
243
244    /// Record every served dispatch into `recorder` (a
245    /// [`rig_core::serve::Recorder`]); the handlers registered now are
246    /// handed to it first ([`Recorder::handlers`]), and each one installed
247    /// later as it is installed.
248    pub fn record_to(&mut self, recorder: impl Recorder + Send + Sync) {
249        self.record_with(Recording::new(recorder));
250    }
251
252    pub(crate) fn record_with(&mut self, recorder: Recording) {
253        recorder.0.handlers(
254            self.handlers
255                .iter()
256                .map(|(key, handler)| {
257                    let described = handler.descriptor();
258                    HandlerDescriptor {
259                        key: key.clone(),
260                        family: described.family,
261                        layers: described.layers,
262                    }
263                })
264                .collect(),
265        );
266        self.recorder = Some(recorder);
267    }
268
269    /// The serving policy.
270    pub const fn config(&self) -> &ServingPolicy {
271        &self.config
272    }
273
274    /// Dispatches currently being served.
275    pub fn in_flight(&self) -> usize {
276        self.in_flight.len()
277    }
278
279    /// Dispatches accepted but waiting for their key under serial serving.
280    pub fn queued(&self) -> usize {
281        self.queued.values().map(VecDeque::len).sum()
282    }
283
284    /// Start a command, returning whether it entered flight. Missing handlers fail
285    /// immediately; cancelled consumers are dropped without handler polls or records.
286    fn serve(&mut self, command: Command) -> bool {
287        let Command {
288            lineage,
289            id,
290            key,
291            kind,
292            parent,
293            scope,
294            context,
295            adapter_context,
296            published,
297            reply,
298            span,
299            mut cancel,
300        } = command;
301        if cancel.try_recv().is_err() {
302            drop(reply);
303            return false;
304        }
305        let Some(handler) = self.handlers.get(&key).cloned() else {
306            reply.fail(handler_unavailable(&key));
307            return false;
308        };
309        // A dispatch whose ancestor was cancelled while it was queued is
310        // dropped unserved: no handler poll, no record.
311        let Ok(flag) = self.shared.begin_lineage(lineage.clone(), key.clone()) else {
312            reply.fail(rig_core::serve::cancelled());
313            return false;
314        };
315        if self.config.serial_per_handler {
316            self.busy.insert(key.clone());
317        }
318        // Nested dispatches need this lineage for cancellation and reentrancy checks.
319        let scoped = Dispatcher::parented(
320            Arc::clone(&self.shared),
321            self.config.stream_capacity,
322            lineage,
323            scope.clone(),
324        );
325        let mut dispatch = Dispatch::new(id, matches!(&reply, super::dispatcher::Reply::Stream(_)))
326            .with_scope(Arc::new(scoped));
327        if let Some(context) = adapter_context {
328            dispatch = dispatch.with_adapter_context(context);
329        }
330        // Context stays outside the serializable effect payload.
331        if let Some(context) = context {
332            dispatch = dispatch.with_scope(Arc::new(context));
333        }
334        if let Some(published) = published {
335            dispatch = dispatch.with_scope(published);
336        }
337        let dispatch = match &self.recorder {
338            Some(recorder) => {
339                recorder
340                    .0
341                    .begin(id, key.clone(), kind.clone(), Origin { parent, scope });
342                recorder.observe(dispatch, id)
343            }
344            None => dispatch,
345        };
346        let task_key = key.clone();
347        let shared = Arc::clone(&self.shared);
348        let task = Box::pin(
349            async move {
350                use futures::future::{Either, select};
351                let mut reply = Some(reply);
352                let serving = Box::pin(async {
353                    let answer = handler.handle(kind, dispatch).await;
354                    match reply.as_mut() {
355                        Some(super::dispatcher::Reply::Stream(sender)) => {
356                            let mut stream = answer.into_stream();
357                            while !flag.is_set() {
358                                let Some(item) = stream.next().await else {
359                                    break;
360                                };
361                                // Retain at most this item beyond the consumer queue.
362                                // Recheck cancellation after readiness, before transfer.
363                                let mut item = Some(item);
364                                let sent = std::future::poll_fn(|cx| {
365                                    if flag.is_set() {
366                                        return Poll::Ready(Err(()));
367                                    }
368                                    match Pin::new(&mut *sender).poll_ready(cx) {
369                                        Poll::Pending => return Poll::Pending,
370                                        Poll::Ready(Err(_)) => return Poll::Ready(Err(())),
371                                        Poll::Ready(Ok(())) => {}
372                                    }
373                                    if flag.is_set() {
374                                        return Poll::Ready(Err(()));
375                                    }
376                                    let Some(item) = item.take() else {
377                                        return Poll::Ready(Ok(()));
378                                    };
379                                    Poll::Ready(
380                                        Pin::new(&mut *sender).start_send(item).map_err(|_| ()),
381                                    )
382                                })
383                                .await;
384                                if sent.is_err() || sender.flush().await.is_err() {
385                                    return true;
386                                }
387                            }
388                        }
389                        Some(super::dispatcher::Reply::Unary(_)) => {
390                            let answer = answer.into_outcome().await;
391                            if flag.is_set() {
392                                return false;
393                            }
394                            if let Some(super::dispatcher::Reply::Unary(sender)) = reply.take() {
395                                return sender.send(answer).is_err();
396                            }
397                        }
398                        None => {}
399                    }
400                    false
401                });
402                // Cancellation wins when both sides are ready on this poll.
403                // Drop execution before notifying the remaining consumer.
404                let cancels = select(cancel, flag.wait());
405                let cancelled = match select(cancels, serving).await {
406                    Either::Right((consumer_gone, _)) => {
407                        if consumer_gone {
408                            shared.cancel_descendants(id);
409                        }
410                        consumer_gone || flag.is_set()
411                    }
412                    Either::Left((reason, serving)) => {
413                        if matches!(reason, Either::Left(_)) {
414                            shared.cancel_descendants(id);
415                        }
416                        drop(serving);
417                        true
418                    }
419                };
420                if cancelled && let Some(reply) = reply.take() {
421                    reply.fail(rig_core::serve::cancelled());
422                }
423                (task_key, id)
424            }
425            .instrument(span),
426        );
427        self.in_flight.push(Box::pin(Serving { task }));
428        true
429    }
430
431    fn accept(&mut self, command: Command) {
432        if command.lineage.is_cancelled() {
433            command.reply.fail(rig_core::serve::cancelled());
434            return;
435        }
436        if self.config.serial_per_handler && self.busy.contains(&command.key) {
437            self.queued
438                .entry(command.key.clone())
439                .or_default()
440                .push_back(command);
441        } else {
442            self.serve(command);
443        }
444    }
445
446    /// Release a completed dispatch and start the next eligible command for its key.
447    /// Refuse cancelled descendants and skip commands with missing handlers.
448    fn release(&mut self, key: HandlerKey, id: EffectId) {
449        if self.shared.end_in_flight(id) {
450            // Queued descendants must not execute or produce records after cancellation.
451            for queue in self.queued.values_mut() {
452                let (orphans, kept): (Vec<_>, Vec<_>) = std::mem::take(queue)
453                    .into_iter()
454                    .partition(|command| command.lineage.is_cancelled());
455                *queue = kept.into();
456                for orphan in orphans {
457                    orphan.reply.fail(rig_core::serve::cancelled());
458                }
459            }
460            self.shared.fail_cancelled_buffered();
461        }
462        if !self.config.serial_per_handler {
463            return;
464        }
465        self.busy.remove(&key);
466        loop {
467            let next = self.queued.get_mut(&key).and_then(VecDeque::pop_front);
468            let Some(command) = next else {
469                self.queued.remove(&key);
470                return;
471            };
472            if self.serve(command) {
473                return;
474            }
475        }
476    }
477
478    fn drain_cancelled_queues(&mut self) {
479        for queue in self.queued.values_mut() {
480            let (cancelled, kept): (Vec<_>, Vec<_>) = std::mem::take(queue)
481                .into_iter()
482                .partition(|command| command.lineage.is_cancelled());
483            *queue = kept.into();
484            for command in cancelled {
485                command.reply.fail(rig_core::serve::cancelled());
486            }
487        }
488    }
489
490    /// Answer every command queued for a key that no longer has a handler.
491    /// Deregistration wakes the driver so this runs promptly.
492    fn drain_orphaned_queues(&mut self) {
493        if !self.config.serial_per_handler || self.queued.is_empty() {
494            return;
495        }
496        let orphaned: Vec<HandlerKey> = self
497            .queued
498            .keys()
499            .filter(|key| !self.handlers.contains_key(*key))
500            .cloned()
501            .collect();
502        for key in orphaned {
503            if let Some(queue) = self.queued.remove(&key) {
504                for command in queue {
505                    command.reply.fail(handler_unavailable(&key));
506                }
507            }
508        }
509    }
510}
511
512/// An in-flight task: the handler's future, the cancels it races and the
513/// dispatch's answer, ending as the key it occupied and the dispatch's id so
514/// the driver can release the one and end the other.
515struct Serving {
516    task: InFlight,
517}
518
519impl Future for Serving {
520    type Output = (HandlerKey, EffectId);
521
522    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<(HandlerKey, EffectId)> {
523        self.get_mut().task.as_mut().poll(cx)
524    }
525}
526
527impl Future for BusDriver {
528    type Output = ();
529
530    fn poll(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
531        let this = self.get_mut();
532        loop {
533            if !this.commands_closed {
534                // Drain commands before registrations so each command sees registrations
535                // posted before it, including those arriving between the drains.
536                let commands = this.shared.drain(cx);
537                this.apply_registrations(cx);
538                for command in commands {
539                    this.accept(command);
540                }
541                this.drain_cancelled_queues();
542                this.drain_orphaned_queues();
543                // Closing under the queue lock excludes late sends, including pending
544                // values that outlive their dispatcher while streams are still draining.
545                if this.shared.try_close_commands() {
546                    this.commands_closed = true;
547                }
548            }
549            // Drive the tasks. A completion may release a queued command,
550            // which is why the outer loop re-enters.
551            let mut progressed = false;
552            loop {
553                if this.in_flight.is_terminated() || this.in_flight.is_empty() {
554                    break;
555                }
556                match this.in_flight.poll_next_unpin(cx) {
557                    Poll::Ready(Some((key, id))) => {
558                        progressed = true;
559                        this.release(key, id);
560                    }
561                    Poll::Ready(None) | Poll::Pending => break,
562                }
563            }
564            // Refuse queued descendants on this pass even if no task completed.
565            this.drain_cancelled_queues();
566            if progressed {
567                continue;
568            }
569            if this.commands_closed && this.in_flight.is_empty() {
570                return Poll::Ready(());
571            }
572            return Poll::Pending;
573        }
574    }
575}
576
577impl Drop for BusDriver {
578    fn drop(&mut self) {
579        // Mark closure before dropping handlers so lost replies report BusClosed
580        // and reentrant destructors cannot submit new work.
581        self.shared.mark_closed();
582        self.mailbox.clear();
583        self.shared.driver_died();
584    }
585}
586
587#[cfg(not(target_family = "wasm"))]
588const _: () = {
589    const fn assert_send<T: Send + 'static>() {}
590    assert_send::<BusDriver>();
591};