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 `retired` SEAT: the engine word a declaration wrote, and the connection a deployment writes
//! beside it.
//!
//! ```ignore
//! #[ingraph::graph(retired(sqlite))]      // the ENGINE — an application's decision
//! pub struct Media { … }
//! ```
//!
//! ```ignore
//! [retired]                               # WHERE — a deployment's decision
//! dsn = "sqlite://var/findit/retired.db"
//! ```
//!
//! # WHY THE WORD AND THE STRING ARE ON DIFFERENT SIDES
//!
//! An engine decides what the framework has to COMPILE — a feature, a driver, a dialect — and that
//! is a fact about the program rather than about the machine it runs on, so it is written where the
//! program is: in the declaration, as a word. A DSN is a path on somebody's disk or a host in
//! somebody's network, which changes per deployment and is exactly what a configuration file is for.
//! An engine in the document would be a build that has to carry all four drivers in case; a DSN in
//! the declaration would be a source tree that has to be edited to move a file.
//!
//! It is [`crate::NodeSection`]'s division one grain up, and the same division the record tier
//! already makes: `persist(sqlite)` is a word, and the pool it runs on is a parameter.

use smol_bytes::Utf8Bytes;

/// **WHICH ENGINE A ROOT'S RETIRED LEDGER RUNS ON** — the `retired(<engine>)` word, as a value.
///
/// # A CLOSED vocabulary over an OPEN seam, and the two are not in tension
///
/// [`RetiredStore`](super::RetiredStore) is a trait anybody may implement; this is the list of
/// engines the framework can build UNAIDED, from a word and a DSN, with no type from the deployment.
/// Each arm is a driver this crate ships behind its own feature and a dialect it knows how to
/// render — which is precisely the framework-owned half, and precisely what an enum is for.
///
/// A KV store — `redb`, `rocksdb`, an in-memory one — and a `store = "path::To::Store"` word naming
/// a deployment's own type are FUTURE spellings on this same seat. They are not arms here yet, and
/// the seam they will arrive on is already the one the four below occupy, so nothing about adding
/// them is a change to [`RetiredStore`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub enum RetiredEngine {
  /// SQLite — `retired(sqlite)`, under `feature = "sqlite"`.
  Sqlite,
  /// PostgreSQL — `retired(postgres)`, under `feature = "postgres"`.
  Postgres,
  /// MySQL — `retired(mysql)`, under `feature = "mysql"`.
  Mysql,
  /// MongoDB — `retired(mongo)`, under `feature = "mongo"`.
  Mongo,
}

impl RetiredEngine {
  /// Every engine, in the order a refusal lists them.
  pub const ALL: [Self; 4] = [Self::Sqlite, Self::Postgres, Self::Mysql, Self::Mongo];

  /// The word a declaration writes: `sqlite`, `postgres`, `mysql`, `mongo`.
  ///
  /// The SAME four spellings a record's `persist(…)` takes, and that is a requirement rather than a
  /// convenience: a deployment writing `retired(postgres)` beside `persist(postgres)` has written
  /// one word twice about one database, and two vocabularies for one set of engines is how the two
  /// come to disagree.
  #[inline]
  #[must_use]
  pub const fn as_str(self) -> &'static str {
    match self {
      Self::Sqlite => "sqlite",
      Self::Postgres => "postgres",
      Self::Mysql => "mysql",
      Self::Mongo => "mongo",
    }
  }

  /// The feature a build needs for this engine's store to exist.
  #[inline]
  #[must_use]
  pub const fn feature(self) -> &'static str {
    match self {
      Self::Sqlite => "sqlite",
      Self::Postgres => "postgres",
      Self::Mysql => "mysql",
      Self::Mongo => "mongo",
    }
  }
}

impl core::str::FromStr for RetiredEngine {
  type Err = UnknownRetiredEngine;

  fn from_str(word: &str) -> Result<Self, Self::Err> {
    Self::ALL
      .into_iter()
      .find(|engine| engine.as_str() == word)
      .ok_or_else(|| UnknownRetiredEngine {
        word: Utf8Bytes::from(word),
      })
  }
}

impl core::fmt::Display for RetiredEngine {
  #[inline]
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.write_str(self.as_str())
  }
}

/// A word that is not one of the four engines the framework builds.
///
/// It names the four, because a closed vocabulary owes a reader its whole content at the point of
/// refusal — the same posture every other word-shaped refusal in this crate takes.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct UnknownRetiredEngine {
  /// What was written.
  word: Utf8Bytes,
}

impl UnknownRetiredEngine {
  /// What was written.
  #[inline]
  #[must_use]
  pub fn word(&self) -> &str {
    self.word.as_str()
  }
}

impl core::fmt::Display for UnknownRetiredEngine {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    write!(
      f,
      "`{word}` is not an engine the retired ledger builds — it takes `sqlite`, `postgres`, \
       `mysql` or `mongo`. A store of your own is not a word here at all: implement \
       `RetiredStore` and hand it to `Keeper::new`",
      word = self.word,
    )
  }
}

impl core::error::Error for UnknownRetiredEngine {}

/// **WHERE THIS DEPLOYMENT KEEPS ITS RETIRED LEDGER** — the `[retired]` section.
///
/// One knob, and the shape of the section is what makes it one: the ENGINE is the declaration's
/// (see [`RetiredEngine`]), the TABLE NAME is the family's (`__ig_retired_<family>`, minted rather
/// than configured), and what is left for a document to say is the connection.
///
/// # THE FRAMEWORK OPENS NOTHING, and this field is a deployment's own statement of WHERE
///
/// `<Root>::init` takes the connection it runs on; a blob store is opened by its author; the options
/// spine's own note says the framework does no file I/O. The ledger keeps that law: a store is
/// handed a pool or a database handle it did not open, and this field is what a deployment READS —
/// through [`dsn`](Self::dsn), off its own options — to decide which pool to open and hand over.
///
/// So [`None`] is not a refusal waiting to happen. A deployment whose records already live in the
/// same database has the handle already and writes no section at all; one that wants the ledger
/// somewhere else writes the connection down here, in the file where a connection belongs, rather
/// than in the source tree.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
#[cfg_attr(feature = "serde", derive(serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(deny_unknown_fields))]
pub struct RetiredOptions {
  /// The connection the ledger is opened on — a SQLite path (`sqlite://var/x.db`), a PostgreSQL or
  /// MySQL URL, a MongoDB URI.
  ///
  /// One word for all four, because one word is what the engines' own drivers take: every one of
  /// them opens from a string, and a second field per engine would be four ways to say the thing
  /// the declaration already decided.
  #[cfg_attr(feature = "serde", serde(default))]
  dsn: Option<Utf8Bytes>,
}

impl RetiredOptions {
  /// No connection named — the deployment wires its store in code.
  #[inline]
  #[must_use]
  pub const fn new() -> Self {
    Self { dsn: None }
  }

  /// The connection this deployment named, or [`None`] where it named none.
  #[inline]
  #[must_use]
  pub fn dsn(&self) -> Option<&str> {
    self.dsn.as_ref().map(Utf8Bytes::as_str)
  }

  /// Keep the ledger at `dsn` — a statement, not an act; see the type note.
  #[inline]
  #[must_use]
  pub fn with_dsn(mut self, dsn: impl Into<Utf8Bytes>) -> Self {
    self.set_dsn(Some(dsn.into()));
    self
  }

  /// [`with_dsn`](Self::with_dsn), in place — INCLUDING back to [`None`], which is what lets a
  /// holder narrowing a value parsed off a document say so.
  #[inline]
  pub fn set_dsn(&mut self, dsn: Option<Utf8Bytes>) -> &mut Self {
    self.dsn = dsn;
    self
  }
}