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
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
//! **THE THREE SQL LEDGERS**: SQLite, PostgreSQL and MySQL, over one table shape and four
//! statements each.
//!
//! ```sql
//! CREATE TABLE IF NOT EXISTS "__ig_retired_media" (
//!   "root"               BLOB    NOT NULL,   -- the root's own IdColumn word
//!   "retired_second"     INTEGER NOT NULL,   -- Timestamp's own two-column shape
//!   "retired_nanosecond" INTEGER NOT NULL,
//!   "origin"             TEXT    NOT NULL,
//!   "late_tails"         INTEGER NOT NULL,
//!   PRIMARY KEY ("root")
//! )
//! ```
//!
//! # THE STATEMENTS ARE RENDERED ONCE, at construction
//!
//! Four strings per store, built when the store is opened and never again. A retirement is not a hot
//! path, but a statement rebuilt per act would be a statement that could differ per act — and what
//! the ledger owes above everything is that the row it wrote is the row it reads back.
//!
//! # THE ROOT'S COLUMN IS THE ROOT'S OWN
//!
//! The word is `<<Root as IdColumn<Db>>::Stored as StoredAs<Db>>::WORDS[0]`, which is exactly the
//! word a record's own key column takes in this dialect. That is not a convenience: it is what makes
//! a ledger row's key comparable with the record tables it is a ledger FOR, which the read side's
//! own anti-join will need and which a hand-picked `TEXT` would have quietly forfeited.
//!
//! An id spans ONE column — the vocabulary's own shape — so the first word is the whole word, and
//! [`spans`](crate::spans) is what already holds a stored form to that claim everywhere else.
//!
//! # THE UPSERT IS ORIGIN-ONLY, and the dialects spell one rule three ways
//!
//! `ON CONFLICT DO UPDATE` (SQLite, PostgreSQL) and `ON DUPLICATE KEY UPDATE` (MySQL) are the same
//! clause: set `origin`, touch nothing else. See the [module note](super) for the state machine's
//! own arm that decides it.

use core::marker::PhantomData;

use smol_bytes::Utf8Bytes;

use crate::{
  IdColumn, StoredAs, Timestamp,
  drive::registry::{RetireOrigin, RootKey},
};

use super::{Landing, RetiredRow, RetiredStore, RetiredStoreError, RetiredTable, UnnameableFamily};

/// **THE DIALECT FACTS A LEDGER NEEDS** — four, and no more, because four statements is all there is.
///
/// It is a seam over `sqlx`'s own database marker types rather than a reuse of the query layer's
/// dialect trait, and the reason is what each is FOR: the query layer's dialect renders a filter
/// tree with operands, aliases, casts and a `LIMIT` grammar, and none of that has any bearing on
/// four statements over five columns. What a ledger needs is how to quote a name, how to spell a
/// parameter, how to say *on conflict*, and the two words a timestamp and a flag take.
pub trait RetiredSql: sqlx::Database {
  /// The word a whole-seconds column takes.
  const SECOND: &'static str;
  /// The word a sub-second nanoseconds column takes.
  const NANOSECOND: &'static str;
  /// The word the origin's text takes.
  const ORIGIN: &'static str;
  /// The word the `late_tails` flag takes.
  const FLAG: &'static str;

  /// `identifier`, bracketed as this dialect brackets one.
  #[must_use]
  fn quote(identifier: &str) -> String;

  /// The `at`-th parameter marker, ONE-BASED — `?` where the dialect counts nothing, `$1` where it
  /// does.
  #[must_use]
  fn placeholder(at: usize) -> String;

  /// The clause that turns the INSERT into the origin-only upsert, given the already-quoted `root`
  /// and `origin` identifiers.
  #[must_use]
  fn upsert(root: &str, origin: &str) -> String;
}

/// The four statements, rendered once — see the [module note](self).
#[derive(Debug, Clone, PartialEq, Eq)]
struct Statements {
  /// `CREATE TABLE IF NOT EXISTS …`
  create: String,
  /// `INSERT INTO … ON CONFLICT … DO UPDATE SET origin = …`
  record: String,
  /// `DELETE FROM … WHERE root = …`
  erase: String,
  /// `SELECT … FROM …`
  roll: String,
}

impl Statements {
  /// The four, for `table`, with `root` as the root column's own dialect word.
  fn render<Db: RetiredSql>(table: &RetiredTable, root_word: &str) -> Self {
    let name = Db::quote(table.name());
    let root = Db::quote(RetiredTable::ROOT);
    let second = Db::quote(RetiredTable::RETIRED_SECOND);
    let nanosecond = Db::quote(RetiredTable::RETIRED_NANOSECOND);
    let origin = Db::quote(RetiredTable::ORIGIN);
    let late_tails = Db::quote(RetiredTable::LATE_TAILS);
    let columns = format!("{root}, {second}, {nanosecond}, {origin}, {late_tails}");
    let binds = (1..=5).map(Db::placeholder).collect::<Vec<_>>().join(", ");
    Self {
      create: format!(
        "CREATE TABLE IF NOT EXISTS {name} ({root} {root_word} NOT NULL, {second} {second_word} \
         NOT NULL, {nanosecond} {nanosecond_word} NOT NULL, {origin} {origin_word} NOT NULL, \
         {late_tails} {flag_word} NOT NULL, PRIMARY KEY ({root}))",
        second_word = Db::SECOND,
        nanosecond_word = Db::NANOSECOND,
        origin_word = Db::ORIGIN,
        flag_word = Db::FLAG,
      ),
      record: format!(
        "INSERT INTO {name} ({columns}) VALUES ({binds}) {upsert}",
        upsert = Db::upsert(&root, &origin),
      ),
      erase: format!(
        "DELETE FROM {name} WHERE {root} = {one}",
        one = Db::placeholder(1),
      ),
      roll: format!("SELECT {columns} FROM {name}"),
    }
  }
}

/// **ONE ROOT FAMILY'S LEDGER, ON ONE SQL DATABASE.**
///
/// It holds a POOL rather than opening one, which is the framework's own posture at every other
/// storage seam: a deployment whose records already live in this database hands over the pool it
/// has, and a deployment that wants a ledger of its own opens one and hands that over. Nothing here
/// reads a DSN — see [`RetiredOptions`](super::RetiredOptions), which is the document a deployment
/// reads one OFF, and whose own note carries why the framework opens nothing.
pub struct SqlRetired<Db: sqlx::Database, Root> {
  /// Where the rows go.
  pool: sqlx::Pool<Db>,
  /// Which table they go in.
  table: RetiredTable,
  /// The four, rendered once.
  statements: Statements,
  /// The family's key type. `fn() -> Root` rather than `Root`, so the store is `Send + Sync`
  /// whatever the key is — the store never holds one.
  root: PhantomData<fn() -> Root>,
}

impl<Db: sqlx::Database, Root> core::fmt::Debug for SqlRetired<Db, Root> {
  fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
    f.debug_struct("SqlRetired")
      .field("table", &self.table.name())
      .finish_non_exhaustive()
  }
}

impl<Db: sqlx::Database, Root> Clone for SqlRetired<Db, Root> {
  fn clone(&self) -> Self {
    Self {
      pool: self.pool.clone(),
      table: self.table.clone(),
      statements: self.statements.clone(),
      root: PhantomData,
    }
  }
}

impl<Db, Root> SqlRetired<Db, Root>
where
  Db: RetiredSql,
  Root: IdColumn<Db>,
  <Root as IdColumn<Db>>::Stored: StoredAs<Db>,
{
  /// `family`'s ledger, on `pool`.
  ///
  /// The table name is minted from the family and is not a knob: `__ig_retired_<family>`. See
  /// [`RetiredTable::new`], which is also where the name is REFUSED if it could not be spliced
  /// safely — the four statements are rendered here, once, so that is the last moment a caller's
  /// string can be stopped.
  ///
  /// # Errors
  ///
  /// [`UnnameableFamily`], where `family` is not a bare identifier.
  ///
  /// # Panics
  ///
  /// Where the root's stored form declares NO column word for this dialect — a `WORDS` of length
  /// zero. That is not reachable through the id vocabulary, whose every member spans exactly one
  /// column, and it is spelled rather than defaulted so that a downstream `IdColumn` row which got
  /// it wrong is loud here rather than silent in a `CREATE TABLE` with a missing type.
  pub fn new(pool: sqlx::Pool<Db>, family: impl Into<Utf8Bytes>) -> Result<Self, UnnameableFamily> {
    let table = RetiredTable::new(family)?;
    let root_word = <<Root as IdColumn<Db>>::Stored as StoredAs<Db>>::WORDS
      .first()
      .expect("an id spans exactly one column, so its stored form has exactly one word");
    let statements = Statements::render::<Db>(&table, root_word);
    Ok(Self {
      pool,
      table,
      statements,
      root: PhantomData,
    })
  }

  /// The table this ledger writes.
  #[inline]
  #[must_use]
  pub const fn table(&self) -> &RetiredTable {
    &self.table
  }

  /// The `CREATE TABLE IF NOT EXISTS` this store runs — what a schema review reads.
  #[inline]
  #[must_use]
  pub fn create_statement(&self) -> &str {
    &self.statements.create
  }

  /// The upserting `INSERT` this store runs.
  #[inline]
  #[must_use]
  pub fn record_statement(&self) -> &str {
    &self.statements.record
  }

  /// The `DELETE` this store runs.
  #[inline]
  #[must_use]
  pub fn erase_statement(&self) -> &str {
    &self.statements.erase
  }

  /// The `SELECT` this store runs.
  #[inline]
  #[must_use]
  pub fn roll_statement(&self) -> &str {
    &self.statements.roll
  }
}

/// **ONE DIALECT'S WHOLE PARTICIPATION**: its four words, its three renderings and its
/// [`RetiredStore`] row.
///
/// A macro rather than one generic impl, and the reason is `sqlx`'s own shape: `Executor` is
/// implemented for `&Pool<Db>` per concrete database, and a body written over an abstract `Db`
/// would have to carry that as a `for<'c>` bound at every call. Three expansions of one body cost
/// nothing a reader has to keep in step — the body is written ONCE, here — and buy a signature per
/// dialect that says exactly what it needs.
macro_rules! sql_ledger {
  (
    $db:ty, $feature:literal, {
      second: $second:literal,
      nanosecond: $nanosecond:literal,
      origin: $origin:literal,
      flag: $flag:literal,
      quote: $quote:expr,
      placeholder: $placeholder:expr,
      upsert: $upsert:expr,
    }
  ) => {
    #[cfg(feature = $feature)]
    #[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
    impl RetiredSql for $db {
      const SECOND: &'static str = $second;
      const NANOSECOND: &'static str = $nanosecond;
      const ORIGIN: &'static str = $origin;
      const FLAG: &'static str = $flag;

      fn quote(identifier: &str) -> String {
        #[allow(clippy::redundant_closure_call)]
        ($quote)(identifier)
      }

      fn placeholder(at: usize) -> String {
        #[allow(clippy::redundant_closure_call)]
        ($placeholder)(at)
      }

      fn upsert(root: &str, origin: &str) -> String {
        #[allow(clippy::redundant_closure_call)]
        ($upsert)(root, origin)
      }
    }

    #[cfg(feature = $feature)]
    #[cfg_attr(docsrs, doc(cfg(feature = $feature)))]
    impl<Root> RetiredStore<Root> for SqlRetired<$db, Root>
    where
      Root: RootKey + IdColumn<$db>,
      <Root as IdColumn<$db>>::Stored: StoredAs<$db>
        + sqlx::Type<$db>
        + for<'q> sqlx::Encode<'q, $db>
        + for<'r> sqlx::Decode<'r, $db>
        + Send
        + Unpin
        + 'static,
    {
      // AUDIT (`AssertSqlSafe`, sqlx 0.9's dynamic-SQL gate) for all four verbs below: every
      // statement is rendered ONCE by `Statements::render`, out of three kinds of part and no
      // others — this dialect's own `const` words, five column names that are `const`s on
      // `RetiredTable`, and the TABLE NAME, which `RetiredTable::new` refuses unless
      // `slot::is_identifier` accepts the family. That charset is ASCII alphanumerics and `_`, not
      // digit-leading, so no accepted name can carry a quote, a comment, a semicolon or whitespace.
      // Every VALUE — the key, both halves of the stamp, the origin's word and the flag — is BOUND.
      fn ready(&self) -> Landing<'_, ()> {
        Box::pin(async move {
          sqlx::query(sqlx::AssertSqlSafe(self.statements.create.clone()))
            .execute(&self.pool)
            .await
            .map(|_created| ())
            .map_err(|source| RetiredStoreError::new("ready", self.table.named(), source))
        })
      }

      fn record<'a>(&'a self, row: &'a RetiredRow<Root>) -> Landing<'a, ()> {
        Box::pin(async move {
          sqlx::query(sqlx::AssertSqlSafe(self.statements.record.clone()))
            .bind(row.key().to_stored())
            .bind(row.at().as_second())
            .bind(row.at().subsec_nanosecond())
            .bind(row.origin().as_str().to_owned())
            .bind(row.late_tails())
            .execute(&self.pool)
            .await
            .map(|_written| ())
            .map_err(|source| RetiredStoreError::new("record", self.table.named(), source))
        })
      }

      fn erase<'a>(&'a self, key: &'a Root) -> Landing<'a, ()> {
        Box::pin(async move {
          sqlx::query(sqlx::AssertSqlSafe(self.statements.erase.clone()))
            .bind(key.to_stored())
            .execute(&self.pool)
            .await
            .map(|_gone| ())
            .map_err(|source| RetiredStoreError::new("erase", self.table.named(), source))
        })
      }

      fn roll(&self) -> Landing<'_, Vec<RetiredRow<Root>>> {
        Box::pin(async move {
          let rows = sqlx::query(sqlx::AssertSqlSafe(self.statements.roll.clone()))
            .fetch_all(&self.pool)
            .await
            .map_err(|source| RetiredStoreError::new("roll", self.table.named(), source))?;
          rows.into_iter().map(|row| self.read_row(&row)).collect()
        })
      }
    }

    /// ONE ROW, READ BACK — the inverse of the five binds, at THIS dialect.
    ///
    /// It lives inside the expansion rather than beside it because `sqlx::Row::try_get` asks for
    /// `Type<Db>` and `Decode<'_, Db>` at the CONCRETE database: `i64`, `i32` and `String` have
    /// those rows per driver, and a body written over an abstract `Db` would have to re-state every
    /// one of them as a bound its callers could not discharge.
    #[cfg(feature = $feature)]
    impl<Root> SqlRetired<$db, Root>
    where
      Root: RootKey + IdColumn<$db>,
      <Root as IdColumn<$db>>::Stored:
        sqlx::Type<$db> + for<'r> sqlx::Decode<'r, $db> + Send + Unpin + 'static,
    {
      /// The row, or the refusal that stopped it.
      fn read_row(
        &self,
        row: &<$db as sqlx::Database>::Row,
      ) -> Result<RetiredRow<Root>, RetiredStoreError> {
        use sqlx::Row as _;

        let refuse =
          |source: sqlx::Error| RetiredStoreError::new("roll", self.table.named(), source);
        let stored: <Root as IdColumn<$db>>::Stored =
          row.try_get(RetiredTable::ROOT).map_err(refuse)?;
        // A row this ledger did not write — a hand-edited key, a column repurposed — is a DECODE
        // refusal and is reported as one, carrying the id vocabulary's own sentence about what it
        // would not admit.
        let key = Root::from_stored(stored)
          .map_err(|refusal| refuse(sqlx::Error::Decode(Box::new(refusal))))?;
        let second: i64 = row.try_get(RetiredTable::RETIRED_SECOND).map_err(refuse)?;
        let nanosecond: i32 = row
          .try_get(RetiredTable::RETIRED_NANOSECOND)
          .map_err(refuse)?;
        let at = Timestamp::from_parts(second, nanosecond)
          .map_err(|refusal| refuse(sqlx::Error::Decode(Box::new(refusal))))?;
        let origin: String = row.try_get(RetiredTable::ORIGIN).map_err(refuse)?;
        let late_tails: bool = row.try_get(RetiredTable::LATE_TAILS).map_err(refuse)?;
        Ok(RetiredRow::new(
          key,
          at,
          RetireOrigin::from(origin),
          late_tails,
        ))
      }
    }
  };
}

sql_ledger!(sqlx::Sqlite, "sqlite", {
  second: "INTEGER",
  nanosecond: "INTEGER",
  origin: "TEXT",
  // SQLite has no boolean storage class — `Type<Sqlite> for bool` is `DataType::Bool`, which the
  // engine stores as an integer 0 or 1. The word is the class, exactly as the stored-word table one
  // module over spells `bool => "INTEGER"`.
  flag: "INTEGER",
  quote: |identifier: &str| format!("\"{identifier}\""),
  placeholder: |_at: usize| "?".to_owned(),
  upsert: |root: &str, origin: &str| {
    format!("ON CONFLICT ({root}) DO UPDATE SET {origin} = excluded.{origin}")
  },
});

sql_ledger!(sqlx::Postgres, "postgres", {
  second: "bigint",
  nanosecond: "integer",
  origin: "text",
  flag: "boolean",
  quote: |identifier: &str| format!("\"{identifier}\""),
  // THE ONE DIALECT THAT COUNTS ITS PARAMETERS, which is the whole reason `placeholder` takes an
  // ordinal at all.
  placeholder: |at: usize| format!("${at}"),
  upsert: |root: &str, origin: &str| {
    format!("ON CONFLICT ({root}) DO UPDATE SET {origin} = EXCLUDED.{origin}")
  },
});

sql_ledger!(sqlx::MySql, "mysql", {
  second: "bigint",
  nanosecond: "int",
  // `varchar(255)`, which is the house's own text word one module over — a ceiling inherited rather
  // than chosen, and an origin longer than it is refused by MySQL on the way in exactly as a longer
  // `String` column's value is.
  origin: "varchar(255)",
  flag: "tinyint(1)",
  quote: |identifier: &str| format!("`{identifier}`"),
  placeholder: |_at: usize| "?".to_owned(),
  // MySQL names no conflict TARGET: the clause fires on whichever unique key collided, and this
  // table has exactly one. `VALUES(col)` is the row that was refused, which is what `excluded` is
  // called on the other two.
  upsert: |_root: &str, origin: &str| format!("ON DUPLICATE KEY UPDATE {origin} = VALUES({origin})"),
});