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
//! Where a re-readable source got to, and where that is kept.
//!
//! The seam is here because the drive loop needs it, and it is deliberately SMALL: a position is
//! read at start-up and written when a watermark advances, and nothing else in this layer asks it
//! anything. R4 formalises the durable shape — the record's own key is per node and per content
//! root, which this one is written to grow into — so what ships here is the two calls the loop
//! makes and two implementations of them.
//!
//! # Which senders have a position at all
//!
//! Only the ones that can READ THEMSELVES AGAIN. A change feed can: its position is a key in the
//! store's own order, and resuming means `WHERE key > p`. A mid-graph node cannot — its outputs came
//! from inputs it no longer holds — so its [`Outbound`](super::Outbound) watermark is the same
//! computation kept in memory, and the thing that heals a gap there is the upstream re-delivering,
//! not a cursor. The watermark is one idea; making it durable is a property of the source.

use core::{future::Future, hash::Hash};

use smol_bytes::Utf8Bytes;

use super::journal::Ledger;

/// WHOSE position: the node that is reading, and the source it is reading.
///
/// Both halves are needed because a node may listen to several sources and a source may be listened
/// to by several nodes, and the two cursors are independent — a re-enabled node resumes from ITS
/// own position, which is exactly why enabling a node again costs nothing.
#[derive(Debug, Clone, PartialEq, Eq, Hash, derive_more::Display)]
#[display("{node}/{source}")]
pub struct Track {
  node: Utf8Bytes,
  source: Utf8Bytes,
}

impl Track {
  /// The track `node` keeps over `source`.
  #[inline]
  pub fn new(node: impl Into<Utf8Bytes>, source: impl Into<Utf8Bytes>) -> Self {
    Self {
      node: node.into(),
      source: source.into(),
    }
  }

  /// The reading node.
  #[inline]
  #[must_use]
  pub fn node(&self) -> &str {
    &self.node
  }

  /// The source being read.
  #[inline]
  #[must_use]
  pub fn source(&self) -> &str {
    &self.source
  }
}

/// The CONTROL STORE: where a node got to, and the journal rows that must land with it.
///
/// # Why the journal is here and not beside it
///
/// The journal is CO-LOCATED with the progress cursor by default, and co-location is not a thing
/// two calls can promise: a row written in one transaction and a position advanced in another leave
/// a crash window in which the two disagree, and *how far did this node get* would then have two
/// answers. So [`advance`](Self::advance) takes both, and an implementation writes them in ONE
/// transaction. One durability domain, torn observability impossible.
///
/// [`Row`](Ledger::Row) is `()` for a deployment keeping no journal, which is free: the row type
/// is zero-sized, so a caller builds rows unconditionally instead of branching on whether anybody
/// wanted them.
///
/// # `&mut self`
///
/// Load-bearing rather than incidental. An advance is a read-modify-write against one row, and the
/// implementation that matters holds a database CONNECTION — a resource that is exclusive whether
/// or not the borrow says so. Taking the exclusive borrow is what makes the serialisation the
/// compiler's rather than a comment, and it costs nothing, because a track belongs to exactly one
/// resident.
///
/// The futures are `Send` because a position is advanced from inside a resident, and residents are
/// tasks on somebody's runtime. Spelled as `impl Future + Send` rather than `async fn`, so the bound
/// is part of the contract instead of something each caller has to hope for.
///
/// # TWO SPELLINGS per verb, inherited from [`Ledger`] and carried through
///
/// [`Ledger`] gives a control store a blocking `record` beside an awaited `record_async`, and this
/// trait's own two verbs take the same knife: a store that answers where it stands is written once
/// in that shape and is coherent across both traits, rather than blocking on one seam and awaiting
/// on the sibling seam it is a supertrait of.
pub trait Positions<K>: Ledger {
  /// Where `track` got to, or `None` if it has never advanced — the BLOCKING spelling.
  fn position(&mut self, track: &Track) -> Result<Option<K>, Self::Error>;

  /// [`position`](Self::position) as a future — what an awaited caller reads.
  fn position_async(
    &mut self,
    track: &Track,
  ) -> impl Future<Output = Result<Option<K>, Self::Error>> + Send;

  /// Record that `track` has reached `to` and upsert `journal` — in ONE transaction, blocking.
  ///
  /// The caller's obligation, and the one this layer is built around: this is called only after the
  /// effect covering everything up to `to` is durable. Called earlier, a crash would skip work; the
  /// storage layer cannot repair that, because it never saw the skipped rows.
  ///
  /// ONE transaction is the whole of the co-location, and it is why this takes the rows rather than
  /// leaving them to a second call: two writes leave a window in which a crash makes the position
  /// and the record disagree, and *how far did this node get* would have two answers.
  ///
  /// The rows are REPLACED by their own `(root, node)` key rather than appended, which is what makes
  /// a replayed advance rewrite what it wrote instead of growing the table. That is the same law the
  /// position itself is written under.
  fn advance(&mut self, track: &Track, to: K, journal: &[Self::Row]) -> Result<(), Self::Error>;

  /// [`advance`](Self::advance) as a future — the same one transaction, awaited.
  fn advance_async(
    &mut self,
    track: &Track,
    to: K,
    journal: &[Self::Row],
  ) -> impl Future<Output = Result<(), Self::Error>> + Send;
}

/// Positions kept in memory.
///
/// It is not a stub: a process that re-reads its whole source on every start is a legitimate
/// deployment — the pull is idempotent and the storage layer replaces by key — and it is the right
/// implementation for a source whose backlog is small. It is also what every walk in this layer
/// measures against, since it makes the loop's ordering visible without a database in the way.
#[derive(Debug)]
pub struct RecordedPositions<K> {
  rows: std::collections::HashMap<Track, K>,
}

impl<K> RecordedPositions<K> {
  /// No positions recorded.
  #[inline]
  #[must_use]
  pub fn new() -> Self {
    Self {
      rows: std::collections::HashMap::new(),
    }
  }

  /// How many tracks have advanced.
  #[inline]
  #[must_use]
  pub fn len(&self) -> usize {
    self.rows.len()
  }

  /// Whether none has.
  #[inline]
  #[must_use]
  pub fn is_empty(&self) -> bool {
    self.rows.is_empty()
  }
}

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

impl<K> Ledger for RecordedPositions<K>
where
  K: Send,
{
  type Error = core::convert::Infallible;
  type Row = ();

  #[inline]
  fn record(&mut self, _rows: &[()]) -> Result<(), Self::Error> {
    Ok(())
  }

  #[inline]
  async fn record_async(&mut self, _rows: &[()]) -> Result<(), Self::Error> {
    Ok(())
  }
}

/// A map in memory answers where it stands, so the blocking spelling is the real body here and the
/// awaited one is that body handed back ready. There is no round trip for the two to differ in.
impl<K> Positions<K> for RecordedPositions<K>
where
  K: Clone + Send + Sync,
{
  #[inline]
  fn position(&mut self, track: &Track) -> Result<Option<K>, Self::Error> {
    Ok(self.rows.get(track).cloned())
  }

  #[inline]
  async fn position_async(&mut self, track: &Track) -> Result<Option<K>, Self::Error> {
    self.position(track)
  }

  #[inline]
  fn advance(&mut self, track: &Track, to: K, _journal: &[()]) -> Result<(), Self::Error> {
    self.rows.insert(track.clone(), to);
    Ok(())
  }

  #[inline]
  async fn advance_async(
    &mut self,
    track: &Track,
    to: K,
    journal: &[()],
  ) -> Result<(), Self::Error> {
    self.advance(track, to, journal)
  }
}

/// The SQLite-backed positions table — the floor's durable half.
///
/// One table, one row per track, written by KEYED REPLACE: an advance is an upsert on
/// `(unit, source)`, so a replayed advance writes the same row rather than a second one. That is the
/// same law the storage layer runs on, applied to the cursor itself.
///
/// `i64` and not a generic key. The floor's own pull orders by an INTEGER column — see
/// [`SqliteFeed`](super::SqliteFeed) — so the position it produces is an integer, and widening this
/// to the whole id vocabulary is R4's, where the durable shape is settled. A narrower type here is
/// what keeps the two from disagreeing in the meantime.
#[cfg(feature = "sqlite")]
#[derive(Debug)]
pub struct SqlitePositions {
  conn: sqlx::SqliteConnection,
}

#[cfg(feature = "sqlite")]
impl SqlitePositions {
  /// The table this type owns. Fixed rather than configurable: it is the FRAMEWORK's own bookkeeping
  /// and not a declared entity, so a name a deployment could vary would be a name two deployments
  /// could disagree about.
  pub const TABLE: &'static str = "ingraph_position";

  /// Open the positions table on `conn`, creating it if it is not there.
  ///
  /// # Errors
  ///
  /// [`SqlitePositionsError`] when the create statement fails.
  pub async fn open(mut conn: sqlx::SqliteConnection) -> Result<Self, SqlitePositionsError> {
    use sqlx::Executor as _;

    // `WITHOUT ROWID`, because the primary key IS the whole address and a shadow rowid would be a
    // second index over data that is already unique.
    //
    // The first column is spelled `unit` and this layer's word for what it holds is `node`. That is
    // deliberate, not a leftover: the column is ON DISK, so changing it is a migration and not a
    // rename — `CREATE TABLE IF NOT EXISTS` would leave an existing table alone and the statements
    // below would then ask it for a column it does not have. It converges when a migration carries
    // it.
    conn
      .execute(
        "CREATE TABLE IF NOT EXISTS ingraph_position (\
           unit TEXT NOT NULL, \
           source TEXT NOT NULL, \
           position INTEGER NOT NULL, \
           PRIMARY KEY (unit, source)\
         ) WITHOUT ROWID",
      )
      .await
      .map_err(SqlitePositionsError)?;
    Ok(Self { conn })
  }

  /// The connection back, for a caller that opened it.
  #[inline]
  #[must_use]
  pub fn into_connection(self) -> sqlx::SqliteConnection {
    self.conn
  }
}

/// A [`SqlitePositions`] statement failed.
#[cfg(feature = "sqlite")]
#[derive(Debug, derive_more::Display)]
#[display("the positions table refused a statement: {_0}")]
pub struct SqlitePositionsError(sqlx::Error);

#[cfg(feature = "sqlite")]
impl core::error::Error for SqlitePositionsError {
  #[inline]
  fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
    Some(&self.0)
  }
}

/// The floor keeps positions and nothing else. A control store that also keeps a JOURNAL is a
/// second table on this same connection, and its row type is the deployment's own declared record —
/// see [`JournalRow`](super::JournalRow), which is what a control store's `Row` has to be buildable through.
#[cfg(feature = "sqlite")]
impl Ledger for SqlitePositions {
  type Error = SqlitePositionsError;
  type Row = ();

  /// The floor keeps no journal, so both spellings write nothing and neither needs the other's
  /// posture — there is no statement here to be blocking or awaited about.
  #[inline]
  fn record(&mut self, _rows: &[()]) -> Result<(), Self::Error> {
    Ok(())
  }

  #[inline]
  async fn record_async(&mut self, _rows: &[()]) -> Result<(), Self::Error> {
    Ok(())
  }
}

/// **THE ONE BACKEND HERE WHOSE ONLY FACE IS A FUTURE**, and the two blocking spellings say so.
///
/// `sqlx` answers in futures and has no blocking face to call instead, so
/// [`position`](Positions::position) and [`advance`](Positions::advance) are the awaited bodies
/// driven by the drive layer's own [`block_on`](super::lane::block_on) — the same driver the thread
/// engine already spends on a write, and a driver rather than a runtime: one future, no timer, no
/// spawn, no reactor. A caller already inside a runtime's task should reach for the `_async`
/// spellings, which are the real bodies; these two are for the thread engine, which owns the thread
/// it blocks.
#[cfg(feature = "sqlite")]
impl Positions<i64> for SqlitePositions {
  #[inline]
  fn position(&mut self, track: &Track) -> Result<Option<i64>, Self::Error> {
    super::lane::block_on(self.position_async(track))
  }

  async fn position_async(&mut self, track: &Track) -> Result<Option<i64>, Self::Error> {
    use sqlx::Row as _;

    let row = sqlx::query("SELECT position FROM ingraph_position WHERE unit = ? AND source = ?")
      .bind(track.node())
      .bind(track.source())
      .fetch_optional(&mut self.conn)
      .await
      .map_err(SqlitePositionsError)?;
    row
      .map(|row| row.try_get::<i64, _>(0))
      .transpose()
      .map_err(SqlitePositionsError)
  }

  #[inline]
  fn advance(&mut self, track: &Track, to: i64, journal: &[()]) -> Result<(), Self::Error> {
    super::lane::block_on(self.advance_async(track, to, journal))
  }

  async fn advance_async(
    &mut self,
    track: &Track,
    to: i64,
    _journal: &[()],
  ) -> Result<(), Self::Error> {
    sqlx::query(
      "INSERT INTO ingraph_position (unit, source, position) VALUES (?, ?, ?) \
       ON CONFLICT (unit, source) DO UPDATE SET position = excluded.position",
    )
    .bind(track.node())
    .bind(track.source())
    .bind(to)
    .execute(&mut self.conn)
    .await
    .map_err(SqlitePositionsError)?;
    Ok(())
  }
}

/// A key a position map can hold — stated once, so the loop's bound reads as one word.
///
/// It is the intersection of what the two implementations here need and nothing wider: hashed and
/// compared because a position is looked up by track, cloned because reading one hands out a copy,
/// and `Send + Sync` because a resident is a task.
pub trait PositionKey: Clone + Eq + Hash + Send + Sync {}

impl<K> PositionKey for K where K: Clone + Eq + Hash + Send + Sync {}

#[cfg(test)]
mod tests;