rig-agent 0.43.0

Rig's classic agent runtime.
Documentation
//! Live handler registration and the driver's registration mailbox.
//!
//! ```
//! let (dispatcher, registrar, driver) = rig_agent::bus::Bus::channel();
//! assert!(registrar.keys().is_empty());
//! ```

use std::{
    collections::VecDeque,
    fmt,
    sync::{Arc, PoisonError},
    task::{Context, Waker},
};

use crate::sync::Mutex;

use rig_core::{
    effect::{Family, HandlerDescriptor, HandlerKey},
    error::{ErrorKind, ErrorReport},
};

use rig_core::serve::{ErasedHandler, Serve};

use super::dispatcher::Shared;
use rig_core::effect::Key;

/// The report for a handler registered under a key of another family.
pub(super) fn family_proof_failed(
    key: &HandlerKey,
    wanted: rig_core::effect::EffectFamily,
    descriptor: &HandlerDescriptor,
) -> ErrorReport {
    ErrorReport::new(
        ErrorKind::HandlerUnavailable,
        format!(
            "handler for `{key}` serves the {} family; a `Key<{wanted}>` cannot name it",
            descriptor.family.family()
        ),
    )
    .with_retryable(false)
}

/// A registration on its way to the driver.
pub(super) enum Registration {
    Install {
        key: HandlerKey,
        handler: ErasedHandler,
    },
    Remove {
        key: HandlerKey,
    },
}

struct MailboxInner {
    pending: VecDeque<Registration>,
    /// The driver's waker, refreshed on every driver poll; woken when a
    /// registration is posted.
    driver: Option<Waker>,
    /// Set by the driver's drop, under this lock: a registration posted
    /// after it is dropped on the spot rather than kept for a driver that
    /// will never take it.
    closed: bool,
}

/// Queued registrations consumed on the driver's next poll. Handler ownership
/// makes this thread-safe on native targets but not on browser WASM.
pub(super) struct Mailbox {
    inner: Mutex<MailboxInner>,
}

impl Mailbox {
    pub(super) fn new() -> Self {
        Self {
            inner: Mutex::new(MailboxInner {
                pending: VecDeque::new(),
                driver: None,
                closed: false,
            }),
        }
    }

    pub(super) fn register(
        &self,
        shared: &Shared,
        key: HandlerKey,
        handler: ErasedHandler,
    ) -> Result<(), ErrorReport> {
        // User code runs before the mailbox lock. Publishing and posting
        // must share an order, even when two registrar clones race.
        let descriptor = handler.descriptor();
        let driver = {
            let mut inner = self.inner.lock().unwrap_or_else(PoisonError::into_inner);
            shared.publish_descriptor(key.clone(), descriptor)?;
            if !inner.closed {
                inner
                    .pending
                    .push_back(Registration::Install { key, handler });
            }
            inner.driver.take()
        };
        // Wakers and unposted handlers may reenter the registrar.
        if let Some(driver) = driver {
            driver.wake();
        }
        Ok(())
    }

    pub(super) fn deregister(&self, shared: &Shared, key: &HandlerKey) -> bool {
        let (removed, driver) = {
            let mut inner = self.inner.lock().unwrap_or_else(PoisonError::into_inner);
            let removed = shared.retract_descriptor(key);
            if !inner.closed {
                inner
                    .pending
                    .push_back(Registration::Remove { key: key.clone() });
            }
            (removed, inner.driver.take())
        };
        if let Some(driver) = driver {
            driver.wake();
        }
        removed
    }

    /// Direct driver mutations use the same FIFO without replacing its waker.
    pub(super) fn take_pending(&self) -> VecDeque<Registration> {
        let mut inner = self.inner.lock().unwrap_or_else(PoisonError::into_inner);
        std::mem::take(&mut inner.pending)
    }

    /// Take every posted registration (the driver's side), registering
    /// `cx` as the waker to wake on the next post.
    pub(super) fn drain(&self, cx: &Context<'_>) -> VecDeque<Registration> {
        let mut inner = self.inner.lock().unwrap_or_else(PoisonError::into_inner);
        match &mut inner.driver {
            Some(driver) if driver.will_wake(cx.waker()) => {}
            slot => *slot = Some(cx.waker().clone()),
        }
        std::mem::take(&mut inner.pending)
    }

    /// Drop everything posted and not yet taken, and everything posted
    /// later (the driver is gone).
    pub(super) fn clear(&self) {
        let pending = {
            let mut inner = self.inner.lock().unwrap_or_else(PoisonError::into_inner);
            inner.closed = true;
            std::mem::take(&mut inner.pending)
        };
        drop(pending);
    }
}

/// Install, replace, and remove handlers on a bus. Descriptors update synchronously;
/// the driver installs handlers on its next poll before serving later dispatches.
/// Obtained from the driver or bus constructors, not from dispatchers.
/// Carries handlers, so it is `Send + Sync` natively but neither on browser WASM.
#[derive(Clone)]
pub struct Registrar {
    pub(super) shared: Arc<Shared>,
    pub(super) mailbox: Arc<Mailbox>,
}

impl fmt::Debug for Registrar {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Registrar")
            .field("closed", &self.shared.is_closed())
            .field("handlers", &self.shared.keys())
            .finish_non_exhaustive()
    }
}

impl Registrar {
    /// Register (or replace) the handler serving `key`. The descriptor is
    /// visible at once; the handler serves from the driver's next poll. A
    /// replacement must keep the key's family (a handle bound to the key
    /// checked its family at bind time); a family change is refused with
    /// `HandlerUnavailable` and nothing is posted.
    pub fn register(
        &self,
        key: impl Into<HandlerKey>,
        handler: impl Serve + 'static,
    ) -> Result<(), ErrorReport> {
        self.register_erased(key, ErasedHandler::new(handler))
    }

    /// Register an already-erased handler.
    pub fn register_erased(
        &self,
        key: impl Into<HandlerKey>,
        handler: ErasedHandler,
    ) -> Result<(), ErrorReport> {
        self.mailbox.register(&self.shared, key.into(), handler)
    }

    /// [`register`](Self::register), returning a [`Key`] that carries the
    /// family the handler proved by its descriptor: a handler of another
    /// family is refused before anything is published.
    pub fn register_typed<F: Family>(
        &self,
        key: impl Into<HandlerKey>,
        handler: impl Serve + 'static,
    ) -> Result<Key<F>, ErrorReport> {
        let key = key.into();
        let handler = ErasedHandler::new(handler);
        let descriptor = handler.descriptor();
        if descriptor.family.family() != F::FAMILY {
            return Err(family_proof_failed(&key, F::FAMILY, &descriptor));
        }
        self.register_erased(key.clone(), handler)?;
        Ok(Key::new_unchecked(key))
    }

    /// Remove the handler serving `key`. The descriptor goes at once, so a
    /// later dispatch answers `HandlerUnavailable`; the driver drops the
    /// handler on its next poll. Returns whether a handler was registered.
    pub fn deregister(&self, key: &HandlerKey) -> bool {
        self.mailbox.deregister(&self.shared, key)
    }

    /// The descriptor of the handler serving `key`, from the same snapshot
    /// [`Dispatcher::descriptor`](super::Dispatcher::descriptor) reads.
    pub fn descriptor(&self, key: &HandlerKey) -> Option<HandlerDescriptor> {
        self.shared.descriptor(key)
    }

    /// Every registered key, in key order.
    pub fn keys(&self) -> Vec<HandlerKey> {
        self.shared.keys()
    }

    /// Every registered descriptor, in key order, from the same snapshot
    /// [`Dispatcher::descriptors`](super::Dispatcher::descriptors) reads.
    pub fn descriptors(&self) -> Vec<HandlerDescriptor> {
        self.shared.descriptors()
    }

    /// Whether the driver has been dropped. A registration on a closed bus
    /// still writes its descriptor but its handler is dropped.
    pub fn is_closed(&self) -> bool {
        self.shared.is_closed()
    }
}

// Native registrars must remain shareable across host threads.
#[cfg(not(target_family = "wasm"))]
const _: () = {
    const fn assert_send_sync<T: Clone + Send + Sync + 'static>() {}
    assert_send_sync::<Registrar>();
};

// Browser handlers must accept local state without imposing native thread bounds.
#[cfg(target_family = "wasm")]
const _: fn(&Registrar) = |registrar| {
    struct Local(std::rc::Rc<std::cell::Cell<usize>>);

    impl Serve for Local {
        type Family = rig_core::effect::family::Dynamic;

        fn descriptor(&self) -> HandlerDescriptor {
            HandlerDescriptor {
                key: HandlerKey::from("local"),
                family: rig_core::effect::FamilyDescriptor::Custom {
                    kind: "local".into(),
                },
                layers: Vec::new(),
            }
        }

        async fn serve(
            &self,
            _kind: rig_core::effect::EffectKind,
            _dispatch: rig_core::serve::Dispatch,
        ) -> rig_core::serve::Reply {
            self.0.set(self.0.get() + 1);
            return rig_core::serve::Reply::Outcome(Ok(rig_core::effect::Outcome::Custom {
                payload: serde_json::Value::Null,
            }));
        }
    }

    let _ = registrar.register("local", Local(std::rc::Rc::default()));
};