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 KEEPER**: the party that occupies the registry's durable-act seat, and the one place the
//! sealed ordering is performed.
//!
//! [`RetiredLedger`](crate::RetiredLedger)'s contract is *queue the write and return* — it is called
//! from inside a resident's own loop, with a transition just made, and an implementation that
//! blocked there would stop the worker whose dispatch earned the act. So the seat is a CHANNEL and
//! the work is a BODY: [`Keeper`] is what the registry holds, [`KeeperBody`] is what a runtime
//! spends, and everything durable happens in the second.
//!
//! # THE ORDERING, and it is the whole reason this type exists
//!
//! ```text
//!   registry says RETIRED ──► Keeper::owed  ──►  store.record(row).await  ──►  mirror.mark(key)
//!                             (queue, return)     THE DURABLE WRITE            THE PUBLISH
//! ```
//!
//! **Durable write FIRST, publish AFTER.** Both halves are asserted by the shape rather than by
//! discipline: the publish is written after an `await` whose value is checked, so a refused write
//! cannot fall through to a `mark`, and a crash anywhere between them leaves the LEDGER ahead of the
//! MIRROR.
//!
//! That direction is chosen and not incidental. The mirror is a cache and the ledger is the truth,
//! so an interruption that leaves the truth ahead is repaired by the next boot for free — the
//! rebuild reads the row and marks the key. An interruption that left the MIRROR ahead would have
//! hidden a key nothing durable agrees is retired, and no restart repairs that: the read path was
//! lying and the ledger has no row to correct it with.
//!
//! # A RESTORE HAS A THIRD STEP, and it is what `Restoring` is waiting for
//!
//! ```text
//!   registry says RESTORING ─► Keeper::owed ──► store.erase(key).await ──► mirror.unmark(key)
//!                                                                     └──► registry.restored(key)
//! ```
//!
//! [`RootState::Restoring`](crate::RootState) is the one state that cannot end itself: its own note
//! says it *waits on a durable write it does not hold and must be TOLD*. This is the party that
//! holds the write, so this is the party that tells it — and it tells it LAST, after the erase and
//! after the publish, so that a key which has been declared back is a key nothing anywhere still
//! calls retired.
//!
//! # A REFUSED WRITE PUBLISHES NOTHING, and says so
//!
//! An engine that would not take the row leaves the registry saying *retired* over a ledger that
//! does not — a cache ahead of its truth, which the next boot silently un-says. Nothing here
//! pretends otherwise: the mirror is untouched, a `Restoring` key is not told, and the refusal is
//! counted into [`KeeperReport`] where a deployment can see that its cache and its truth have parted
//! company.

use std::sync::{
  Arc, Weak,
  atomic::{AtomicU64, Ordering},
};

use crate::{
  Timestamp,
  drive::registry::{Registry, RetireOrigin, RetiredLedger, Retirement, RootKey, Stamp},
};

use super::{RetiredMirror, RetiredRow, RetiredStore, RetiredStoreError};

/// **HOW THE LEDGER HAS BEEN GETTING ON** — three counts, read at any moment.
///
/// [`refused`](Self::refused) is the one that matters. Zero is a deployment whose mirror and whose
/// ledger agree; anything else is the number of times they have not, and each one is a key whose
/// in-memory state a restart will contradict.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct KeeperReport {
  /// Rows written — retirements that reached the ledger and were then published.
  pub recorded: u64,
  /// Rows erased — restores that reached the ledger and were then published.
  pub erased: u64,
  /// Acts the engine refused. The mirror was NOT moved for any of them.
  pub refused: u64,
}

/// The counters behind [`KeeperReport`], shared between the seat and its body.
#[derive(Debug, Default)]
struct Counters {
  recorded: AtomicU64,
  erased: AtomicU64,
  refused: AtomicU64,
}

impl Counters {
  /// The three, read together.
  ///
  /// `Relaxed` throughout, and it is the honest ordering: these are a REPORT, published by nothing
  /// and ordering nothing. A reader that catches one count a moment before another has read a
  /// deployment mid-act, which is what reading a live counter means.
  fn report(&self) -> KeeperReport {
    KeeperReport {
      recorded: self.recorded.load(Ordering::Relaxed),
      erased: self.erased.load(Ordering::Relaxed),
      refused: self.refused.load(Ordering::Relaxed),
    }
  }
}

/// **THE SEAT**: what [`Registry::installing`](crate::Registry::installing) is handed, and all it
/// ever does is queue.
///
/// Cheap to hold and cheap to call — a `send` on an unbounded line and a clone of a root key, which
/// is an id. The body on the other end is where a database is touched.
///
/// # The line is UNBOUNDED, and the grain is why
///
/// Backpressure exists to stop a producer outrunning a consumer, and the producer here is
/// retirement: one act per root key a person stood down or a volume that went away. A deployment
/// that retires a million roots in a burst has done something a bounded queue would turn into a
/// stalled resident rather than a slow ledger — and stalling the resident is exactly what this
/// seat's contract forbids.
///
/// # NOT [`Clone`], and the omission is what makes the body's ending certain
///
/// [`KeeperBody::run`] ends when every sender on its line is gone, and the one seat that exists
/// lives in the family's own [`Registry`]. A clone would be a second sender somewhere else, holding
/// a body open over a table that had already been dropped — so the seat is minted once, handed to
/// [`Registry::installing`](crate::Registry::installing), and never copied.
pub struct Keeper<Root> {
  /// Where an owed act goes. See the type note for why it is unbounded.
  owed: flume::Sender<(Root, Retirement)>,
  /// The counts, shared with the body that moves them.
  counters: Arc<Counters>,
}

impl<Root> core::fmt::Debug for Keeper<Root> {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.debug_struct("Keeper")
      .field("queued", &self.owed.len())
      .field("report", &self.counters.report())
      .finish()
  }
}

impl<Root> Keeper<Root>
where
  Root: RootKey,
{
  /// **THE PAIR**: the seat a registry holds, and the body a runtime spends.
  ///
  /// `registry` is WEAK, and that is not an optimisation: the registry holds the seat
  /// ([`Registry::installing`](crate::Registry::installing) stores an `Arc<dyn RetiredLedger<Root>>`),
  /// so a strong pointer back would be a cycle that never drops. What the body needs it for is the
  /// third step of a restore — telling a `Restoring` key that its erase landed — and a registry that
  /// has gone away has no key left to tell.
  #[must_use]
  pub fn new(
    store: Arc<dyn RetiredStore<Root>>,
    mirror: Arc<RetiredMirror<Root>>,
    registry: Weak<Registry<Root>>,
  ) -> (Self, KeeperBody<Root>) {
    let (owed, taken) = flume::unbounded();
    let counters = Arc::new(Counters::default());
    let seat = Self {
      owed,
      counters: Arc::clone(&counters),
    };
    let body = KeeperBody {
      taken,
      store,
      mirror,
      registry,
      counters,
    };
    (seat, body)
  }

  /// **SEAT A KEEPER ON `registry`**, handing back the body to spend — or [`None`] where a ledger is
  /// already seated there.
  ///
  /// [`Registry::installing`](crate::Registry::installing)'s refusal, forwarded whole: a second
  /// writer for one family's rows is two parties disagreeing about what a retirement means, and the
  /// honest answer to the second is *no*. A caller that gets `None` back has a body it never built
  /// rather than one it must remember not to run.
  #[must_use = "the body is what performs the writes; a dropped one leaves the ledger untouched"]
  pub fn seated(
    registry: &Arc<Registry<Root>>,
    store: Arc<dyn RetiredStore<Root>>,
    mirror: Arc<RetiredMirror<Root>>,
  ) -> Option<KeeperBody<Root>> {
    let (seat, body) = Self::new(store, mirror, Arc::downgrade(registry));
    registry
      .installing(Arc::new(seat) as Arc<dyn RetiredLedger<Root>>)
      .then_some(body)
  }

  /// How the ledger has been getting on — see [`KeeperReport`].
  #[inline]
  #[must_use]
  pub fn report(&self) -> KeeperReport {
    self.counters.report()
  }

  /// How many acts are waiting for the body.
  #[inline]
  #[must_use]
  pub fn queued(&self) -> usize {
    self.owed.len()
  }
}

/// **QUEUE AND RETURN** — the whole of what the seat does on the transition's own thread.
///
/// A send onto an unbounded line cannot block and cannot fail except by the body being gone, which
/// is a deployment already shutting down: an act with nowhere to go is dropped, and the registry it
/// came from is a cache that is about to be dropped too.
impl<Root> RetiredLedger<Root> for Keeper<Root>
where
  Root: RootKey,
{
  #[inline]
  fn owed(&self, key: &Root, act: Retirement) {
    let _gone = self.owed.send((key.clone(), act));
  }
}

/// **THE BODY**: what actually writes, and the only party that publishes.
///
/// Spend it on a runtime — `R::spawn_detach(body.run())`, or an ignition's own `spawn` where the
/// join is wanted. It ENDS when every [`Keeper`] onto its line is gone, which is the same
/// punctuation the registry driver honours one module over: *shutdown is the receive failing
/// because every sender has been dropped.*
pub struct KeeperBody<Root: RootKey> {
  /// The far end of the seat's line.
  taken: flume::Receiver<(Root, Retirement)>,
  /// Where the rows go.
  store: Arc<dyn RetiredStore<Root>>,
  /// What is published, after they have gone.
  mirror: Arc<RetiredMirror<Root>>,
  /// Who is told that a restore's erase landed — weak, see [`Keeper::new`].
  registry: Weak<Registry<Root>>,
  /// The counts, shared with the seat that reports them.
  counters: Arc<Counters>,
}

impl<Root: RootKey> core::fmt::Debug for KeeperBody<Root> {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.debug_struct("KeeperBody")
      .field("queued", &self.taken.len())
      .field("report", &self.counters.report())
      .finish()
  }
}

impl<Root: RootKey> KeeperBody<Root> {
  /// **THE LOOP**: one act at a time, until the line ends.
  ///
  /// Serial by construction, and that is the correct shape rather than a limitation. Two acts for
  /// ONE key must not race — a retire overtaking its own restore would leave the ledger saying the
  /// opposite of the last thing anybody asked — and the registry has already serialised them into
  /// the order they were decided in. Running them concurrently would be discarding that order at
  /// the one point it becomes durable.
  pub async fn run(self) {
    while let Ok((key, act)) = self.taken.recv_async().await {
      self.perform(&key, act).await;
    }
  }

  /// **ONE ACT**: the durable half, then the publish, then — for a restore — the telling.
  ///
  /// Public because it is the unit the ordering is stated in, and therefore the unit a test asserts
  /// the ordering over. A caller driving it by hand is driving the same body [`run`](Self::run)
  /// does, one act at a time.
  pub async fn perform(&self, key: &Root, act: Retirement) {
    match act {
      Retirement::Recorded {
        at,
        origin,
        late_tails,
      } => self.recorded(key, at, origin, late_tails).await,
      Retirement::Erased => self.erased(key).await,
    }
  }

  /// The row lands, and only then is the key marked.
  async fn recorded(&self, key: &Root, at: Timestamp, origin: RetireOrigin, late_tails: bool) {
    let row = RetiredRow::new(key.clone(), at, origin, late_tails);
    if self.refused(self.store.record(&row).await) {
      return;
    }
    self.mirror.mark(key.clone());
    self.counters.recorded.fetch_add(1, Ordering::Relaxed);
  }

  /// The row goes, the key is unmarked, and the waiting state is told — in that order.
  async fn erased(&self, key: &Root) {
    if self.refused(self.store.erase(key).await) {
      return;
    }
    self.mirror.unmark(key.clone());
    self.counters.erased.fetch_add(1, Ordering::Relaxed);
    // THE THIRD STEP, and it is last for its own reason: `Restored` moves the key out of
    // `Restoring`, and a key declared back before the mirror had let go of it would be reachable
    // and invisible at the same time.
    if let Some(registry) = self.registry.upgrade() {
      let _told = registry.restored(key, Stamp::now());
    }
  }

  /// Whether the act was refused — counted here so that both verbs report it the same way, and
  /// `true` meaning *stop, publish nothing*.
  fn refused(&self, outcome: Result<(), RetiredStoreError>) -> bool {
    let Err(refusal) = outcome else {
      return false;
    };
    self.counters.refused.fetch_add(1, Ordering::Relaxed);
    // The refusal is COUNTED and dropped rather than propagated, and that is what the seat's own
    // contract leaves available: `owed` returns nothing, so there is nobody up the stack to hand a
    // `Result` to. What a deployment reads instead is `KeeperReport`, and what it reads under
    // `tracing` is this line.
    #[cfg(feature = "tracing")]
    {
      // The SOURCE is logged beside the refusal, not instead of it: `Display` on this error names
      // the verb and the table by convention and leaves the chain to the reader, and a log line is
      // the one reader that cannot walk one.
      let engine = core::error::Error::source(&refusal).map(ToString::to_string);
      tracing::error!(
        verb = refusal.verb(),
        table = refusal.table(),
        error = %refusal,
        engine = engine.as_deref().unwrap_or("—"),
        "the retired ledger refused an act; the mirror was not moved"
      );
    }
    #[cfg(not(feature = "tracing"))]
    let _unreported = refusal;
    true
  }

  /// How the ledger has been getting on — see [`KeeperReport`].
  #[inline]
  #[must_use]
  pub fn report(&self) -> KeeperReport {
    self.counters.report()
  }
}

/// **THE BOOT ROAD**: the ledger is the truth, so a starting deployment reads it and states what it
/// says.
///
/// Three acts, in order:
///
/// 1. [`ready`](RetiredStore::ready) — the table exists, because a `roll` over a table that was
///    never created is not an empty ledger, it is an error.
/// 2. [`roll`](RetiredStore::roll) — every row.
/// 3. Each row is stated into the registry and marked in the mirror, with NO durable act earned:
///    [`Registry::rebuilt`](crate::Registry::rebuilt) is the door for exactly that, because a
///    rebuild that went through `retire` would re-write every row it had just read, stamped with
///    the boot's own clock instead of the retirement's.
///
/// What is NOT rebuilt is everything else. Inflight counts start at zero, no debounce window
/// survives, and a key that was `Retiring` or `Restoring` when the process died is simply not in
/// the ledger — the first is a key nothing durable ever said was out, and the second is a key whose
/// row is already gone. Both are `Idle`, which is the honest reading of a cache that was never the
/// truth.
///
/// # Errors
///
/// [`RetiredStoreError`] from either read. A deployment that cannot read its ledger has no honest
/// state to start in, so the refusal is handed back rather than absorbed — unlike a refusal DURING
/// a run, where there is no caller left to hand one to.
pub async fn rebuild<Root>(
  store: &dyn RetiredStore<Root>,
  registry: &Registry<Root>,
  mirror: &RetiredMirror<Root>,
) -> Result<usize, RetiredStoreError>
where
  Root: RootKey,
{
  store.ready().await?;
  let rows = store.roll().await?;
  let read = rows.len();
  for row in rows {
    registry.rebuilt(row.key(), row.at(), row.origin().clone(), row.late_tails());
    mirror.mark(row.into_key());
  }
  Ok(read)
}