happenstance-postgres 0.8.0

PostgreSQL event store and projection store adapters for happenstance.
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
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
//! The conformance suite, run against a live pinned Postgres.
//!
//! # How this target is gated, and why it is gated *this* way
//!
//! Every test here needs a Docker daemon. The default gate must not, because
//! `.redkiln/config.yaml` wires `cargo xtask affected` and `cargo xtask ci
//! --fast` as the verify grains for **every other project in this initiative**,
//! and a step that needs a container breaks all of them.
//!
//! Three gating mechanisms were on the table and only one works.
//!
//! **`required-features` does not.** The default gate runs `cargo test --locked
//! --workspace --all-features` and `cargo clippy --workspace --all-targets
//! --all-features`, and `--all-features` *enables* the required feature — so the
//! target would build **and run**, against a server that is not there. It is
//! listed as admissible in this project's architecture brief; it is not, and
//! saying so here is cheaper than the next reader rediscovering it.
//!
//! **An environment-variable read that returns early does not, on its own.** A
//! "no server, pass quietly" path is indistinguishable in CI output from a rule
//! that passed, which is CF-18's argument about omitted skips applied one layer
//! out.
//!
//! **`#[ignore]` does.** It composes with `--all-features`, it keeps the target
//! compiled and linted by the default gate — which is what stops this mount from
//! rotting — and it makes the gated tests appear in the default run as
//! `ignored` rather than vanishing from the count. An absent target and a
//! skipped one are different observations and only one of them is acceptable.
//!
//! The macro cannot be told to add `#[ignore]`, but it does not have to be: the
//! emitter is a **parameter**, and [`emit_ignored_tokio`] below is
//! `emit_tokio` with one attribute added. That is a whole-invocation gate — it
//! marks every generated test — and is emphatically **not** a `#[cfg]` hiding a
//! rule out of a macro's expansion, which DR-5 forbids for CF-18's reason: a
//! rule silently omitted is indistinguishable from a rule that passed.
//!
//! # Running it
//!
//! ```console
//! cargo test -p happenstance-postgres --all-features -- --ignored --list
//! cargo test -p happenstance-postgres --all-features -- --ignored --show-output
//! ```
//!
//! `--list` first, so "no rule is absent from the run" is proven rather than
//! assumed. `--show-output` because a declined capability's reason is printed
//! only under it, and an unread reason is a trade nobody recorded.

#![cfg(not(target_arch = "wasm32"))]
#![allow(clippy::unwrap_used)]

mod support;

use happenstance_postgres::event_store::PostgresEventStore;
use happenstance_postgres::sqlx::{Row, query};
use happenstance_testkit::concurrency::CONTENDERS;
use happenstance_testkit::{Capability, Fixture};
use support::PostgresFixture;

/// `emit_tokio`, plus `#[ignore]`.
///
/// The reason string is not decoration: `cargo test -- --ignored --list` prints
/// it, so the one command an adapter author runs to find out what is gated also
/// tells them how to ungate it.
macro_rules! emit_ignored_tokio {
    ($($name:ident),* $(,)?) => {
        $(
            #[tokio::test]
            #[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
            async fn $name() {
                happenstance_testkit::rules::$name(__conformance_fixture)
                    .await
                    .report(::core::stringify!($name));
            }
        )*
    };
}
pub(crate) use emit_ignored_tokio;

/// The concurrency family's emitter, plus `#[ignore]`.
///
/// A separate macro rather than a parameter on the one above, because the
/// families differ in two ways that matter: the rules live under
/// `concurrency::rules`, and each test needs
/// `#[tokio::test(flavor = "multi_thread")]`. A current-thread runtime turns
/// `CONTENDERS` contenders from a race into a queue, and a queue passes every
/// rule in this family for the wrong reason.
macro_rules! emit_ignored_concurrency_tokio {
    ($($name:ident),* $(,)?) => {
        $(
            #[tokio::test(flavor = "multi_thread")]
            #[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
            async fn $name() {
                happenstance_testkit::concurrency::rules::$name(__conformance_fixture)
                    .await
                    .report(::core::stringify!($name));
            }
        )*
    };
}
pub(crate) use emit_ignored_concurrency_tokio;

/// The model family's emitter, plus `#[ignore]`.
macro_rules! emit_ignored_model_tokio {
    ($($name:ident),* $(,)?) => {
        $(
            #[tokio::test]
            #[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
            async fn $name() {
                happenstance_testkit::model::rules::$name(__conformance_fixture)
                    .await
                    .report(::core::stringify!($name));
            }
        )*
    };
}
pub(crate) use emit_ignored_model_tokio;

happenstance_testkit::event_store_conformance!(
    mod_name = dcb_conformance,
    emit = crate::emit_ignored_tokio,
    fixture = PostgresFixture::new()
);

// The concurrency family. This is the bar the whole crate exists to clear: the
// first adapter in the portfolio to run it against a store whose writers are
// **not** serialised. A mechanism that passed by funnelling every write through
// one lock would pass these rules too, and would have deleted the axis rather
// than filled it.
//
// `PostgresFixture` is named at the call site rather than returned as an opaque
// `impl Fixture`, because an opaque type carries only the bounds written on it
// and `F::Store: Send` would be unprovable — which is the one line
// `ConcurrentFixture` exists for. No second impl is owed: the trait is
// blanket-implemented for any `Fixture` whose `Store` is `Send`, and a `PgPool`
// is `Send + Sync`.
happenstance_testkit::event_store_concurrency_conformance!(
    mod_name = dcb_concurrency_conformance,
    emit = crate::emit_ignored_concurrency_tokio,
    fixture = PostgresFixture::new()
);

// The model family: the suite's rules checked against a reference model under
// `proptest`, which is why the testkit dev-dependency names that feature.
happenstance_testkit::event_store_model_conformance!(
    mod_name = dcb_model_conformance,
    emit = crate::emit_ignored_model_tokio,
    fixture = PostgresFixture::new()
);

// ---------------------------------------------------------------------------
// This story's own tests.
//
// `append`, `head` and `contains_event_id` are still `todo!()`, so every rule in
// the expansion above would panic if run. What is provable now is the schema,
// the isolation and the fixture's own shape — and those are proved through the
// public `PostgresEventStore::pool()` accessor and raw SQL, which is the one
// channel available before the adapter has a body.
// ---------------------------------------------------------------------------

/// The columns migrations 1 and 3 are allowed to give `event`, and their shapes.
///
/// Held as data so the check below, which keeps its name but covers migration 3
/// since #420, is a set comparison: a column added in passing must fail a test.
const SETTLED_COLUMNS: &[(&str, &str, bool)] = &[
    // (name, data_type, is_nullable)
    ("position", "bigint", false),
    ("event_type", "text", false),
    ("data", "bytea", false),
    ("metadata", "bytea", true),
    ("tags", "ARRAY", false),
    ("origin_store", "bytea", true),
    ("origin_position", "bigint", true),
    ("recorded_at", "bigint", false),
    // The visibility mechanism, on ADR-0013's measurement: absent while the
    // schema story owned this file, deliberately present since ADR-0024.
    ("xact_id", "xid8", false),
    // Write groups (#420, ADR-0105), added by migration 3, nullable with no
    // default so a row from before it reads as a group of one.
    ("write_group", "bigint", true),
    ("group_guard", "bytea", true),
];

#[tokio::test]
#[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
async fn migration_1_creates_the_settled_column_set() {
    let fixture = PostgresFixture::new();
    let store = fixture.connect().await;

    let rows = query(
        "SELECT column_name, data_type, is_nullable \
         FROM information_schema.columns \
         WHERE table_schema = $1 AND table_name = 'event' \
         ORDER BY ordinal_position",
    )
    .bind(fixture.schema())
    .fetch_all(store.pool())
    .await
    .expect("the event table should exist after migrations 1 and 3");

    let found: Vec<(String, String, bool)> = rows
        .iter()
        .map(|row| {
            (
                row.get::<String, _>("column_name"),
                row.get::<String, _>("data_type"),
                row.get::<String, _>("is_nullable") == "YES",
            )
        })
        .collect();

    let expected: Vec<(String, String, bool)> = SETTLED_COLUMNS
        .iter()
        .map(|(name, ty, nullable)| ((*name).to_owned(), (*ty).to_owned(), *nullable))
        .collect();

    assert_eq!(
        found, expected,
        "the event table's column set drifted: a new column is a decision, not a formality"
    );

    let indexes =
        query("SELECT indexname FROM pg_indexes WHERE schemaname = $1 AND tablename = 'event'")
            .bind(fixture.schema())
            .fetch_all(store.pool())
            .await
            .expect("pg_indexes should answer");

    let names: Vec<String> = indexes
        .iter()
        .map(|row| row.get::<String, _>("indexname"))
        .collect();

    let promised = ["event_tags_idx", "event_type_idx", "event_origin_idx"];
    for expected in promised.into_iter().chain(["event_write_group_idx"]) {
        assert!(
            names.iter().any(|name| name == expected),
            "index `{expected}` is missing; found {names:?}"
        );
    }
}

/// The guard that keeps this story from settling a later story's question.
///
/// The no-server half of this lives in `src/migration.rs` as a text scan. This
/// is the half a real server can disagree with: a `bigserial` and a `bigint`
/// with a sequence default are the same thing to Postgres and different things
/// to a reader of the SQL.
#[tokio::test]
#[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
async fn migration_1_does_not_preempt_adr_0024() {
    let fixture = PostgresFixture::new();
    let store = fixture.connect().await;

    let row = query(
        "SELECT column_default, is_identity \
         FROM information_schema.columns \
         WHERE table_schema = $1 AND table_name = 'event' AND column_name = 'position'",
    )
    .bind(fixture.schema())
    .fetch_one(store.pool())
    .await
    .expect("the position column should exist");

    assert!(
        row.get::<Option<String>, _>("column_default").is_none(),
        "`position` has acquired a column default. A default is `nextval()`, and \
         `nextval()` allocating outside the transaction is where ES-10 is lost — \
         which is the question ADR-0024 exists to answer deliberately."
    );
    assert_eq!(
        row.get::<String, _>("is_identity"),
        "NO",
        "`position` has become an identity column, which is a sequence by another name"
    );
}

/// One fixture instance is one isolated backing store.
///
/// The story-local stand-in for
/// `rules::two_fixture_instances_observe_none_of_each_others_appends`, which the
/// slice-mate turns green through a real `append`. `MemoryFixture::sharing` is
/// the in-tree implementation that deliberately fails this, and it is what this
/// test exists to reject.
#[tokio::test]
#[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
async fn two_fixture_instances_are_two_backing_stores() {
    let left = PostgresFixture::new();
    let right = PostgresFixture::new();
    assert_ne!(
        left.schema(),
        right.schema(),
        "two instances share a schema, so they are one backing store wearing two names"
    );

    let left_store = left.connect().await;
    let right_store = right.connect().await;

    insert_bare_row(&left_store, 1).await;

    assert_eq!(count_events(&left_store).await, 1);
    assert_eq!(
        count_events(&right_store).await,
        0,
        "the second instance can see the first's row, so the isolation scheme is a lie"
    );
}

/// Two handles from one instance address one backing store.
///
/// `SECOND_HANDLE` is the only MUST among the capabilities. This is its runtime
/// half; the compile-time half is the constant assertion below.
#[tokio::test]
#[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
async fn two_handles_from_one_instance_share_a_backing_store() {
    let fixture = PostgresFixture::new();
    let first = fixture.connect().await;
    let second = fixture.connect().await;

    insert_bare_row(&first, 1).await;

    assert_eq!(
        count_events(&second).await,
        1,
        "the second handle cannot see the first's write, so they are not one store"
    );
}

/// `REOPEN` is claimed supported, so it is exercised rather than asserted.
///
/// A capability claimed and never run is a claim, not a fact.
#[tokio::test]
#[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
async fn a_row_survives_a_reopen() {
    let fixture = PostgresFixture::new();
    {
        let store = fixture.connect().await;
        insert_bare_row(&store, 1).await;
    }

    fixture.reopen().await;

    let reopened = fixture.connect().await;
    assert_eq!(
        count_events(&reopened).await,
        1,
        "the row did not survive a reopen, so `REOPEN: SUPPORTED` is not true"
    );
}

/// The fixture's raw `DELETE` removes the rows, from the same store, and
/// leaves the sequence where it was (#147).
///
/// The guard rule in the suite checks the removal itself. This adds what only
/// this adapter's schema decides: the `StoreId` survives, and the next append
/// lands above the removed tail because `event_position_seq` never rewinds on
/// `DELETE`. That last assertion is ES-38's content for this adapter, recorded
/// here as evidence; the rule is `positions_are_not_reused_after_removal`'s
/// (#151). Every read follows a settle, because this fixture declines
/// `READ_YOUR_OWN_WRITES`.
#[tokio::test]
#[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
async fn removal_outside_the_port_deletes_the_row_and_keeps_the_allocator() {
    use happenstance_core::{EventStore, Query, ReadOptions, collect};
    use happenstance_testkit::fixtures::{query_tagged, tagged_event};
    use happenstance_testkit::{Removed, Settled};

    let fixture = PostgresFixture::new();
    let store = fixture.connect().await;
    let mut appended = Vec::new();
    for (event_type, tag) in [("Kept", "kept"), ("Middle", "middle"), ("Tail", "tail")] {
        let position = store
            .append(&[tagged_event(event_type, &[("removal", tag)])], None)
            .await
            .unwrap();
        appended.push(position);
    }
    let [kept, middle, tail] = appended[..] else {
        unreachable!("three appends returned three positions")
    };

    assert_eq!(
        fixture.remove_outside_port(&[middle, tail]).await,
        Removed::Deleted
    );

    assert_eq!(fixture.settle_frontier().await, Settled::Visible);
    let held = collect(store.read(&Query::all(), ReadOptions::new()))
        .await
        .unwrap();
    assert_eq!(
        held.iter().map(|event| event.position).collect::<Vec<_>>(),
        [kept],
        "only the event that was not named is left"
    );
    let survivor = held.first().unwrap();
    let by_tag = collect(store.read(&query_tagged(&[("removal", "tail")]), ReadOptions::new()))
        .await
        .unwrap();
    assert!(
        by_tag.is_empty(),
        "a tag query for a removed event finds nothing"
    );

    let next = store
        .append(&[tagged_event("Next", &[("removal", "next")])], None)
        .await
        .unwrap();
    assert_eq!(fixture.settle_frontier().await, Settled::Visible);
    let after = collect(store.read(&Query::all(), ReadOptions::new()))
        .await
        .unwrap();
    let appended_next = after.iter().find(|event| event.position == next).unwrap();
    assert_eq!(
        appended_next.id.store(),
        survivor.id.store(),
        "the same incarnation: a removal does not re-mint the StoreId"
    );
    assert!(
        next > tail,
        "the next append took {next}, at or below the removed tail at {tail}: \
         the sequence rewound"
    );
}

/// One instance hands out `CONTENDERS` simultaneous live handles.
///
/// The failure this rejects is not a red test, it is a **hang**: a pool sized
/// below `CONTENDERS` deadlocks rather than failing and CF-33 says there is no
/// watchdog to tell the two apart. Every handle is held open at once and each
/// executes a statement, so a pool that cannot supply them all times out here
/// rather than inside the concurrency family, where the cause would be much
/// further from the symptom.
#[tokio::test(flavor = "multi_thread")]
#[ignore = "needs a live Postgres; run with `-- --ignored` (starts a container)"]
async fn contenders_handles_open_concurrently_without_deadlock() {
    let fixture = PostgresFixture::new();

    let mut stores = Vec::with_capacity(CONTENDERS);
    for _ in 0..CONTENDERS {
        stores.push(fixture.connect().await);
    }

    // Held simultaneously, and all made to do work simultaneously. Opening then
    // dropping each in turn would pass with a pool of one.
    let mut handles = Vec::with_capacity(CONTENDERS);
    for store in &stores {
        let pool = store.pool().clone();
        handles.push(tokio::spawn(async move {
            query("SELECT 1")
                .execute(&pool)
                .await
                .expect("a live handle should answer a trivial query");
        }));
    }
    for handle in handles {
        handle.await.expect("no contender task should panic");
    }

    assert_eq!(stores.len(), CONTENDERS);
}

/// A fixture that answers only the two required capabilities.
///
/// Its only purpose is to *name* the trait's provided defaults so a test can
/// compare against them. There is no other way to tell "declined deliberately"
/// from "never considered": both are the same three tokens of Rust at the impl
/// site, which is the whole hazard `MID_BATCH_FAULT` carries.
struct Defaulted;

impl Fixture for Defaulted {
    type Store = PostgresEventStore;
    const SECOND_HANDLE: Capability = Capability::SUPPORTED;
    const REOPEN: Capability = Capability::SUPPORTED;
    async fn connect(&self) -> Self::Store {
        unreachable!("`Defaulted` exists to be read, never constructed")
    }
}

/// Every capability constant is an answer, and none is the trait's default.
///
/// This runs with no server, deliberately: it is the belt to
/// `Capability::declined("")`'s suspender, which fires at **codegen** for an
/// associated const — so `cargo build` and `cargo test` catch an empty reason
/// and `cargo clippy` does not. A green clippy proves nothing about these.
#[test]
fn capability_constants_are_answered_not_defaulted() {
    assert!(PostgresFixture::SECOND_HANDLE.is_supported());
    assert!(PostgresFixture::REOPEN.is_supported());
    // A frontier store, so the default sentence (no frontier here) is false.
    assert!(PostgresFixture::HELD_ABOVE_FRONTIER.is_supported());
    // A raw `DELETE` reaches this store's own table, and the sequence survives
    // it, so the removal capability is this store's to grant (#147).
    assert!(PostgresFixture::REMOVAL.is_supported());

    // `MID_BATCH_FAULT` was declined while `append` was `todo!()` and is
    // supported now that it is not. Both are answers; the failure mode this test
    // exists for is the third possibility, which is the trait's silent default
    // on a store that could have co-operated.
    assert!(
        PostgresFixture::MID_BATCH_FAULT.is_supported(),
        "Postgres can fail between two rows of one batch -- an AFTER INSERT trigger          raising on the nth row does it -- so declining is not an honest answer          once `append` exists to fault"
    );

    // Not left at the trait's provided default. Comparing against the default
    // explicitly is the only way to tell an answer from an omission, because the
    // two are the same three tokens of Rust at the impl site.
    assert_ne!(
        PostgresFixture::MID_BATCH_FAULT.reason(),
        Defaulted::MID_BATCH_FAULT.reason(),
        "MID_BATCH_FAULT is the trait's silent default on a store that could co-operate"
    );

    // The ceilings are facts mirrored from the adapter, not literals restated.
    assert_eq!(
        PostgresFixture::MAX_EVENT_DATA_LEN,
        Some(PostgresEventStore::MAX_EVENT_DATA_LEN)
    );
    assert_eq!(
        PostgresFixture::MAX_TAGS_PER_EVENT,
        Some(PostgresEventStore::MAX_TAGS_PER_EVENT)
    );
    assert_eq!(
        PostgresFixture::MAX_EVENTS_PER_BATCH,
        Some(PostgresEventStore::MAX_EVENTS_PER_BATCH)
    );
}

/// The stated ceilings clear the floors every store must clear.
///
/// VT-21, VT-22 and VT-24 make 65,536 bytes, 64 tags and 128 events per batch
/// floors rather than suggestions. A ceiling below one of them is legal and
/// fails `store_accepts_the_guaranteed_minimum_*` — correctly. Catching it here
/// costs nothing and does not need a server.
///
/// Written as `const` blocks rather than runtime assertions, which clippy asked
/// for and which is the stronger form: every operand is a constant, so a ceiling
/// dropped below a floor stops the crate **compiling** rather than reddening a
/// test somebody has to run. That is atom 61's preference and it costs nothing
/// here.
#[test]
fn the_stated_ceilings_clear_the_specification_floors() {
    const {
        assert!(
            PostgresEventStore::MAX_EVENT_DATA_LEN
                >= happenstance_core::MIN_SUPPORTED_EVENT_DATA_LEN
        );
        assert!(
            PostgresEventStore::MAX_TAGS_PER_EVENT
                >= happenstance_core::MIN_SUPPORTED_TAGS_PER_EVENT
        );
        assert!(
            PostgresEventStore::MAX_EVENTS_PER_BATCH
                >= happenstance_core::MIN_SUPPORTED_EVENTS_PER_BATCH
        );
    }
}

// --- helpers ---------------------------------------------------------------

/// Writes one row directly, bypassing `append`, which is still `todo!()`.
///
/// Positions are supplied by the caller because the schema deliberately has no
/// default and the mechanism that will supply them is a later story's. This is
/// not a literal position value in the sense CF-6 forbids — nothing here asserts
/// *on* a position, it only needs the primary key to differ.
async fn insert_bare_row(store: &PostgresEventStore, position: i64) {
    query(
        "INSERT INTO event (position, event_type, data, metadata, tags, recorded_at) \
         VALUES ($1, 'probe', '\\x00'::bytea, NULL, ARRAY[]::text[], 0)",
    )
    .bind(position)
    .execute(store.pool())
    .await
    .expect("a bare insert should succeed against migration 1's table");
}

/// How many rows the `event` table holds, through this handle.
async fn count_events(store: &PostgresEventStore) -> i64 {
    query("SELECT count(*) AS n FROM event")
        .fetch_one(store.pool())
        .await
        .expect("counting rows should succeed")
        .get::<i64, _>("n")
}