ingraph 0.1.0

A declaration-driven indexing framework: records and nodes are written as Rust types, and the storage rows, the dataflow between them and the GraphQL query surface are emitted from the declaration.
Documentation
//! THE RECEIPT a consumer takes: the message itself, or the landed entity's KEY.
//!
//! A store's emission is its COMMIT RECEIPT MADE FLOW — only committed items, after the commit, in
//! commit order — and that law is the driver's, held by
//! [`Resident::reconcile`](super::Resident) for both modes at once: the write lane answers first,
//! and only the positions it committed are fanned out, in the order they were staged. Nothing here
//! re-states it and nothing here can weaken it.
//!
//! What this module adds is the OTHER half of the ⑥ ruling: the receipt is the SUBSCRIBER's choice,
//! per upstream entry, and the author emits `T` ONCE. So the projection `(key, T) → key` happens at
//! the SEND SITE — here — rather than in the operator, which is why one store legally feeds a
//! message-receipt consumer and a notify-receipt one at the same moment, from the same commit, in
//! the same order.
//!
//! ```text
//!                          ┌── message edge ── Vec<Item<T>>
//!   land → commit → fan-out ┤
//!                          └── notify  edge ── Vec<Item<T::Key>>
//! ```
//!
//! # Two ack domains, and they do not meet
//!
//! The upstream settles at the COMMIT; a downstream's ack rides its own edge and can never
//! un-commit anything. That separation is structural rather than a rule written here: the commit
//! already happened before [`Sink::deliver`](super::Sink::deliver) was called at all.

use super::{
  ItemId, Rings,
  downstream::{Downstream, Sink, Wanted},
  message::{AckSender, Item},
};
use crate::transform::Transformer;

/// A node's out-edges when SOME of its consumers took the notify receipt.
///
/// Two lists rather than one enum per edge, and the reason is the type: a message edge carries `T`
/// and a notify edge carries `T::Key`, so no single [`Outbox`](super::Outbox) names both. Each list
/// is an ordinary [`Downstream`], which is what keeps the whole of the existing edge machinery —
/// windows, nudges, backpressure — unchanged on both sides.
///
/// A node NONE of whose consumers asked for a receipt carries a bare [`Downstream<T>`] exactly as it
/// did: this type is what the wiring builds only when a `notify` word was written, so the fence and
/// the projection cost a graph without one nothing at all.
///
/// # The edge INDEX runs messages first, then receipts
///
/// [`Sink::deliver`]'s index is a position in this node's whole edge list, and the order is stated
/// rather than discovered because the wiring and the driver have to agree on it: every message edge,
/// in the order it was attached, then every notify edge in the order it was attached.
#[derive(Debug)]
pub struct Notified<T: Transformer> {
  messages: Downstream<T>,
  receipts: Downstream<T::Key>,
}

impl<T: Transformer> Notified<T> {
  /// No edges yet — neither kind.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self {
      messages: Downstream::new(),
      receipts: Downstream::new(),
    }
  }

  /// The edges whose consumers take the MESSAGE — the default receipt.
  #[inline]
  #[must_use]
  pub const fn messages(&mut self) -> &mut Downstream<T> {
    &mut self.messages
  }

  /// The edges whose consumers take the KEY — the `notify` receipt.
  #[inline]
  #[must_use]
  pub const fn receipts(&mut self) -> &mut Downstream<T::Key> {
    &mut self.receipts
  }

  /// How many edges take the message.
  #[inline]
  #[must_use]
  pub fn messaged(&self) -> usize {
    self.messages.edges().len()
  }

  /// How many edges take the key.
  #[inline]
  #[must_use]
  pub fn notified(&self) -> usize {
    self.receipts.edges().len()
  }
}

impl<T: Transformer> Default for Notified<T> {
  #[inline]
  fn default() -> Self {
    Self::new()
  }
}

/// `T::Key: Send + 'static` for the same reason `T` is — a notify edge is an ordinary edge and its
/// batch crosses threads with the body that sends it.
///
/// `Clone` on both is the two [`Downstream`]s' own — see that type's [`Sink`] impl. It is spent here
/// twice over: every edge of this set carries every output ([`carries`](Sink::carries) is the
/// inherited every-edge answer), so a node with a message edge AND a notify edge is already a
/// fan-out of two, and the key an arm mints is taken from a value that had to survive the arm before
/// it.
impl<T> Sink<T> for Notified<T>
where
  T: Transformer + Clone + Send + 'static,
  T::Key: Clone + Send + 'static,
{
  #[inline]
  fn arity(&self) -> usize {
    self.messaged() + self.notified()
  }

  #[inline]
  fn duplicate(&self, output: &T) -> Option<T> {
    self.messages.duplicate(output)
  }

  #[inline]
  fn connected(&self) -> Wanted {
    Wanted::sole(self.arity() > 0)
  }

  #[inline]
  fn nudges(&self) -> Vec<Box<dyn Rings>> {
    let mut rings = self.messages.nudges();
    rings.extend(self.receipts.nudges());
    rings
  }

  /// THE PROJECTION, at the send site: a message edge takes the batch as it is, and a notify edge
  /// takes each item's KEY under the same transport id.
  ///
  /// The id is carried rather than re-minted, which is what keeps the ack window's arithmetic one
  /// arithmetic: a fan-out joins on all of its arms, and an arm that renamed its items would be an
  /// arm nothing could join.
  #[inline]
  async fn deliver(&mut self, edge: usize, batch: Vec<Item<T>>, ack: AckSender<ItemId>) -> bool {
    let messaged = self.messaged();
    if edge < messaged {
      return self.messages.deliver(edge, batch, ack).await;
    }
    let keys = batch
      .into_iter()
      .map(|item| {
        let (id, value) = item.into_parts();
        Item::new(id, value.key())
      })
      .collect();
    self.receipts.deliver(edge - messaged, keys, ack).await
  }
}

#[cfg(test)]
mod tests;