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 BY-KEY JOIN: where a keyed group's members wait for each other, and what a complete one
//! carries with it.
//!
//! # Complete or not at all
//!
//! A `subscribe(…)` container's keyed group is delivered as ONE input — the emitted `Paired(A, B)`
//! variant — and it is delivered only when every member has arrived for that key. A message whose
//! counterparts are not there yet waits HERE; the straights beside it never touch this buffer,
//! because an independent flow has nothing to wait for.
//!
//! # There is no deadline, and that is the ruling rather than an omission
//!
//! A half-arrived group waits indefinitely. No timeout, no policy: the member that did arrive is
//! still in its sender's ack window — its [`Owing`](super::Owing) stays open while a
//! [`Share`] of it sits here — so the sender's watermark sticks, and the upstream's own lag sweep
//! re-pulls the flow that stopped. That is the safety net the design names, and a knob here would
//! be one before there was a case for one. Dropping the buffer is the other end of it: the shares
//! go, the tokens disconnect, and every sender reads that as held.
//!
//! # What the framework holds and what the declaration writes
//!
//! The members carry DIFFERENT message types, so the slots a partial group keeps are a struct only
//! that node's own expansion can spell. This module holds the part that is the same for every
//! group — the keyed table, the shares that accumulate against a key, and the completion — and
//! [`Group`] is the seam the spelled part meets it at.

use core::hash::Hash;

use std::collections::HashMap;

use super::{ItemId, message::Share};

/// How a member of a keyed group states the key it JOINS ON.
///
/// # Why it is a value and not a trait on the message
///
/// The obvious seat is the message type — `impl Joins for Frame` — and it is the wrong one for
/// [`Sink`](super::Sink)'s reason: two nodes joining the same upstream on different fields would be
/// two impls for one app-owned type, which is `E0119` and unfixable. A projection INSTALLED at the
/// wiring has no such question, and it is the shape
/// [`Attributes`](super::Attributes) already takes for the same kind of read.
///
/// One value answers for every member — `impl Joins<Frame>` and `impl Joins<Segment>` on one
/// projection, with one `Key` — which is what "joined by key" means: the members meet at a type
/// they all produce.
pub trait Joins<T> {
  /// The key the group is joined by.
  type Key;

  /// The key `message` joins under.
  fn key(&self, message: &T) -> Self::Key;
}

/// A keyed group's PARTIAL state: one slot per member, and what a full set becomes.
///
/// Written by the node's own expansion, because the slots are one `Option` per member and the
/// members are different types. The framework only ever asks the one question below.
///
/// # `complete` gives the group BACK
///
/// `Result<Complete, Self>` rather than `Option<Complete>` on `&mut self`, so that a group which is
/// not ready cannot be half-emptied by the asking: an implementation that takes a member out and
/// then finds another missing has already lost the first. Taking the whole value and handing it
/// back is the shape where that mistake is not expressible.
pub trait Group: Default {
  /// The complete group — the payload the emitted `Paired` variant carries.
  type Complete;

  /// The complete group, or this partial one back unchanged.
  fn complete(self) -> Result<Self::Complete, Self>;
}

/// One key's half-arrived group: the members that came, and what they are owed on.
#[derive(Debug)]
struct Waiting<G> {
  slots: G,
  // One per member MESSAGE and not per member slot: a second message for a slot that is already
  // filled replaces the value and keeps both shares, so the pair's outcome answers every delivery
  // that carried the key. See `Pairing::arrive`.
  shares: Vec<Share<ItemId>>,
}

impl<G: Default> Default for Waiting<G> {
  fn default() -> Self {
    Self {
      slots: G::default(),
      shares: Vec::new(),
    }
  }
}

/// The by-key join buffer of ONE keyed group.
///
/// One per node, because a container has one group: `key` on a `upstream(…)` entry JOINS the group
/// rather than opening one, so there is nothing here to tell two of them apart.
#[derive(Debug)]
pub struct Pairing<K, G> {
  waiting: HashMap<K, Waiting<G>>,
}

impl<K, G> Pairing<K, G> {
  /// An empty buffer.
  #[inline]
  #[must_use]
  pub fn new() -> Self {
    Self {
      waiting: HashMap::new(),
    }
  }

  /// How many keys have a group waiting for a member.
  #[inline]
  #[must_use]
  pub fn waiting(&self) -> usize {
    self.waiting.len()
  }

  /// Whether nothing is waiting.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.waiting.is_empty()
  }
}

impl<K, G> Pairing<K, G>
where
  K: Eq + Hash,
  G: Group,
{
  /// Put a member's message into the group under `key`, and answer the group if that COMPLETED it.
  ///
  /// `fill` is the member's own slot — the one line only the node's expansion can write — and
  /// `share` is what that message's delivery is owed. The answer carries every share the key
  /// collected, which is what a joined delivery's [`Custody`](super::Custody) is built from.
  ///
  /// # A second message for a filled slot REPLACES it, and both shares are kept
  ///
  /// Two frames for one key before the segment arrives is not an error and not a queue: keyed
  /// replace is this layer's law — a re-delivery is harmless because the last state wins — so the
  /// slot takes the newer value. What must not happen is the older message being forgotten: its
  /// sender is still waiting, so its share stays, and the pair's outcome answers both deliveries
  /// alike. Nothing is dropped and nothing is answered for work that did not happen.
  pub fn arrive(
    &mut self,
    key: K,
    share: Share<ItemId>,
    fill: impl FnOnce(&mut G),
  ) -> Option<(G::Complete, Vec<Share<ItemId>>)> {
    // Taken OUT and put back rather than filled in place: [`Group::complete`] consumes the group,
    // which is what makes a half-emptied one unspellable, and an entry cannot hand its value over.
    let mut waiting = self.waiting.remove(&key).unwrap_or_default();
    fill(&mut waiting.slots);
    waiting.shares.push(share);
    let Waiting { slots, shares } = waiting;
    match slots.complete() {
      Ok(complete) => Some((complete, shares)),
      Err(slots) => {
        self.waiting.insert(key, Waiting { slots, shares });
        None
      }
    }
  }
}

impl<K, G> Default for Pairing<K, G> {
  #[inline]
  fn default() -> Self {
    Self::new()
  }
}

#[cfg(test)]
mod tests;