#![cfg(feature = "event-store")]
#![allow(clippy::unwrap_used)]
use std::future::Future;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicU64, Ordering};
use happenstance_core::{
AppendCondition, AppendError, Event, Query, QueryItem, SendEventStore, StoreLimit, Tags,
};
use happenstance_sqlite::event_store::{SqliteEventStore, SqliteEventStoreError};
use happenstance_testkit::{Capability, Fixture};
use rusqlite::Connection;
#[derive(Debug)]
struct TempDb(PathBuf);
impl TempDb {
fn new(label: &str) -> Self {
static NEXT: AtomicU64 = AtomicU64::new(1);
let ordinal = NEXT.fetch_add(1, Ordering::Relaxed);
let mut path = std::env::temp_dir();
path.push(format!(
"happenstance-sqlite-append-{label}-{}-{ordinal}.db",
std::process::id()
));
let _ = std::fs::remove_file(&path);
Self(path)
}
fn path(&self) -> &Path {
&self.0
}
fn open(&self) -> SqliteEventStore {
SqliteEventStore::open(self.path()).unwrap()
}
fn raw(&self) -> Connection {
Connection::open(self.path()).unwrap()
}
}
impl Drop for TempDb {
fn drop(&mut self) {
for suffix in ["", "-wal", "-shm"] {
let mut path = self.0.clone().into_os_string();
path.push(suffix);
let _ = std::fs::remove_file(PathBuf::from(path));
}
}
}
#[derive(Debug)]
struct AppendOnlyFixture(TempDb);
impl AppendOnlyFixture {
fn new() -> Self {
Self(TempDb::new("rules"))
}
}
impl Fixture for AppendOnlyFixture {
type Store = SqliteEventStore;
const SECOND_HANDLE: Capability = Capability::SUPPORTED;
const REOPEN: Capability = Capability::declined(
"this minimal fixture exists only to drive the two append rules that do \
not read their result back; the reopen rules belong to SqliteFixture in \
tests/conformance.rs, which is the fixture this adapter is measured by",
);
fn connect(&self) -> impl Future<Output = Self::Store> {
core::future::ready(self.0.open())
}
}
fn event(event_type: &str) -> Event {
Event::new(event_type, &b"{}"[..]).unwrap()
}
fn tags(pairs: &[(&str, &str)]) -> Tags {
Tags::from_pairs(pairs.iter().copied()).unwrap()
}
fn tagged(event_type: &str, pairs: &[(&str, &str)]) -> Event {
event(event_type).with_tags(tags(pairs))
}
fn query_of_types(types: &[&str]) -> Query {
Query::from_item(QueryItem::of_types(types.iter().copied()).unwrap())
}
fn query_tagged(pairs: &[(&str, &str)]) -> Query {
Query::from_item(QueryItem::tagged(tags(pairs)).unwrap())
}
fn row_counts(connection: &Connection) -> (i64, i64, i64) {
let count = |table: &str| -> i64 {
connection
.query_row(&format!("SELECT count(*) FROM {table}"), [], |row| {
row.get(0)
})
.unwrap()
};
(count("event"), count("event_tag"), count("tag_cardinality"))
}
fn assigned_positions(connection: &Connection) -> Vec<i64> {
let mut statement = connection
.prepare("SELECT position FROM event ORDER BY position")
.unwrap();
let rows = statement.query_map([], |row| row.get(0)).unwrap();
rows.map(Result::unwrap).collect()
}
fn query_plan(connection: &Connection, sql: &str) -> Vec<String> {
let mut statement = connection
.prepare(&format!("EXPLAIN QUERY PLAN {sql}"))
.unwrap();
let rows = statement
.query_map([], |row| row.get::<_, String>(3))
.unwrap();
rows.map(Result::unwrap).collect()
}
#[tokio::test]
async fn empty_batch_is_refused_before_any_condition_is_looked_at() {
let db = TempDb::new("empty-batch");
let store = db.open();
store.append(&[event("Blocker")], None).await.unwrap();
let refused = store
.append(
&[],
Some(&AppendCondition::new(query_of_types(&["Blocker"]))),
)
.await;
assert!(
matches!(refused, Err(AppendError::NoEvents)),
"an empty batch is the caller's own bug and the emptiness check MUST \
precede the condition check; got {refused:?}"
);
}
#[tokio::test]
async fn the_two_borrowed_empty_batch_rules_pass() {
happenstance_testkit::rules::append_rejects_empty_batch(async || AppendOnlyFixture::new())
.await
.report("append_rejects_empty_batch");
happenstance_testkit::rules::empty_batch_is_refused_before_the_condition_is_evaluated(
async || AppendOnlyFixture::new(),
)
.await
.report("empty_batch_is_refused_before_the_condition_is_evaluated");
}
#[tokio::test]
async fn each_ceiling_is_exact_at_both_ends() {
let db = TempDb::new("ceilings");
let store = db.open();
let at_limit = Event::new("Sized", vec![b'x'; SqliteEventStore::MAX_EVENT_DATA_LEN]).unwrap();
store.append(&[at_limit], None).await.unwrap();
let over = Event::new(
"Sized",
vec![b'x'; SqliteEventStore::MAX_EVENT_DATA_LEN + 1],
)
.unwrap();
assert!(
matches!(
store.append(&[over], None).await,
Err(AppendError::ExceedsStoreLimit {
limit: StoreLimit::EventDataLen,
len
}) if len == SqliteEventStore::MAX_EVENT_DATA_LEN + 1
),
"an oversized payload must be ExceedsStoreLimit {{ EventDataLen }}, \
never AppendError::Store and never a truncation"
);
let at_limit = event("Tagged").with_tags(distinct_tags(SqliteEventStore::MAX_TAGS_PER_EVENT));
store.append(&[at_limit], None).await.unwrap();
let over = event("Tagged").with_tags(distinct_tags(SqliteEventStore::MAX_TAGS_PER_EVENT + 1));
assert!(
matches!(
store.append(&[over], None).await,
Err(AppendError::ExceedsStoreLimit {
limit: StoreLimit::TagsPerEvent,
len
}) if len == SqliteEventStore::MAX_TAGS_PER_EVENT + 1
),
"too many tags must be ExceedsStoreLimit {{ TagsPerEvent }}"
);
let at_limit: Vec<Event> = (0..SqliteEventStore::MAX_EVENTS_PER_BATCH)
.map(|_| event("Batched"))
.collect();
store.append(&at_limit, None).await.unwrap();
let over: Vec<Event> = (0..=SqliteEventStore::MAX_EVENTS_PER_BATCH)
.map(|_| event("Batched"))
.collect();
assert!(
matches!(
store.append(&over, None).await,
Err(AppendError::ExceedsStoreLimit {
limit: StoreLimit::EventsPerBatch,
len
}) if len == SqliteEventStore::MAX_EVENTS_PER_BATCH + 1
),
"too many events must be ExceedsStoreLimit {{ EventsPerBatch }}"
);
}
fn distinct_tags(n: usize) -> Tags {
let pairs: Vec<(String, String)> = (0..n)
.map(|index| ("k".to_owned(), format!("v{index}")))
.collect();
Tags::from_pairs(
pairs
.iter()
.map(|(key, value)| (key.as_str(), value.as_str())),
)
.unwrap()
}
#[tokio::test]
async fn a_refused_append_leaves_the_file_unchanged() {
let db = TempDb::new("refusal");
let store = db.open();
store
.append(&[tagged("Seed", &[("course", "c1")])], None)
.await
.unwrap();
let inspector = db.raw();
let before = row_counts(&inspector);
let positions_before = assigned_positions(&inspector);
assert!(store.append(&[], None).await.is_err());
let over = Event::new(
"TooBig",
vec![b'x'; SqliteEventStore::MAX_EVENT_DATA_LEN + 1],
)
.unwrap();
assert!(store.append(&[over], None).await.is_err());
let batch: Vec<Event> = (0..8)
.map(|_| tagged("Rejected", &[("course", "c1")]))
.collect();
let refused = store
.append(
&batch,
Some(&AppendCondition::new(query_tagged(&[("course", "c1")]))),
)
.await;
assert!(
matches!(refused, Err(AppendError::ConditionViolated(_))),
"a violated guard is ConditionViolated, never Store — the Store answer \
is what a BEGIN DEFERRED probe-then-insert produces; got {refused:?}"
);
let after = row_counts(&inspector);
assert_eq!(before, after, "a refusal wrote rows into the file");
assert_eq!(positions_before, assigned_positions(&inspector));
}
#[tokio::test]
async fn two_handles_racing_one_condition_yield_one_winner_and_one_rejection() {
let db = TempDb::new("race");
let first = db.open();
let second = db.open();
let condition = AppendCondition::new(query_tagged(&[("course", "c1")]));
let winner = first
.append(&[tagged("Enrolled", &[("course", "c1")])], Some(&condition))
.await;
assert!(winner.is_ok(), "the first decision must land: {winner:?}");
let loser = second
.append(&[tagged("Enrolled", &[("course", "c1")])], Some(&condition))
.await;
assert!(
matches!(loser, Err(AppendError::ConditionViolated(_))),
"the loser must be told to rebuild and retry, not handed a driver \
error; got {loser:?}"
);
let events: i64 = db
.raw()
.query_row("SELECT count(*) FROM event", [], |row| row.get(0))
.unwrap();
assert_eq!(events, 1, "exactly one of the two decisions landed");
}
#[tokio::test]
async fn guard_after_is_exclusive_at_the_boundary() {
let db = TempDb::new("after-boundary");
let store = db.open();
let boundary = store
.append(&[tagged("Enrolled", &[("course", "c1")])], None)
.await
.unwrap();
let admitted = store
.append(
&[tagged("Enrolled", &[("course", "c1")])],
Some(
&AppendCondition::new(query_tagged(&[("course", "c1")]))
.after_every_guard(boundary),
),
)
.await;
assert!(
admitted.is_ok(),
"`after` is exclusive: an event AT the boundary does not violate the \
guard; got {admitted:?}"
);
let refused = store
.append(
&[tagged("Enrolled", &[("course", "c1")])],
Some(
&AppendCondition::new(query_tagged(&[("course", "c1")]))
.after_every_guard(boundary),
),
)
.await;
assert!(matches!(refused, Err(AppendError::ConditionViolated(_))));
}
#[tokio::test]
async fn a_guard_without_after_sees_the_whole_log() {
let db = TempDb::new("unbounded-guard");
let store = db.open();
store
.append(&[tagged("Enrolled", &[("course", "c1")])], None)
.await
.unwrap();
for _ in 0..3 {
store.append(&[event("Noise")], None).await.unwrap();
}
let refused = store
.append(
&[event("Enrolled")],
Some(&AppendCondition::new(query_tagged(&[("course", "c1")]))),
)
.await;
assert!(
matches!(refused, Err(AppendError::ConditionViolated(_))),
"an unbounded guard is violated by a match anywhere in the log, however \
old; got {refused:?}"
);
}
#[tokio::test]
async fn any_violated_guard_refuses_the_whole_batch() {
let db = TempDb::new("many-guards");
let store = db.open();
store.append(&[event("Second")], None).await.unwrap();
let condition = AppendCondition::new(query_of_types(&["First"]))
.and_guard(query_of_types(&["Second"]), None)
.and_guard(query_of_types(&["Third"]), None);
let refused = store.append(&[event("Anything")], Some(&condition)).await;
assert!(
matches!(refused, Err(AppendError::ConditionViolated(_))),
"the middle guard matched, so the whole append is refused; got {refused:?}"
);
}
#[tokio::test]
async fn a_batch_never_conflicts_with_itself() {
let db = TempDb::new("self-conflict");
let store = db.open();
let batch = vec![
tagged("Enrolled", &[("course", "c1")]),
tagged("Enrolled", &[("course", "c1")]),
];
let landed = store
.append(
&batch,
Some(&AppendCondition::new(query_tagged(&[("course", "c1")]))),
)
.await;
assert!(
landed.is_ok(),
"the condition is evaluated against what the store already held, and it \
held nothing; got {landed:?}"
);
assert_eq!(assigned_positions(&db.raw()).len(), 2);
}
#[tokio::test]
async fn append_returns_the_callers_own_last_position() {
let db = TempDb::new("returned-position");
let first = db.open();
let second = db.open();
let mine = first
.append(&[event("Mine"), event("MineToo")], None)
.await
.unwrap();
second.append(&[event("Theirs")], None).await.unwrap();
let inspector = db.raw();
let mut statement = inspector
.prepare("SELECT position FROM event WHERE event_type = 'MineToo'")
.unwrap();
let my_last: i64 = statement.query_row([], |row| row.get(0)).unwrap();
assert_eq!(
i64::try_from(mine.get()).unwrap(),
my_last,
"append returns the position it assigned to the caller's own last \
event, compared against what the store actually stored — never a \
literal, and never the head another connection has since moved"
);
}
#[tokio::test]
async fn batch_positions_follow_slice_order() {
let db = TempDb::new("slice-order");
let store = db.open();
let types = ["A", "B", "C", "D"];
let batch: Vec<Event> = types.iter().map(|name| event(name)).collect();
let last = store.append(&batch, None).await.unwrap();
let inspector = db.raw();
let mut statement = inspector
.prepare("SELECT event_type, position FROM event ORDER BY position")
.unwrap();
let rows: Vec<(String, i64)> = statement
.query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
.unwrap()
.map(Result::unwrap)
.collect();
let observed: Vec<&str> = rows.iter().map(|(name, _)| name.as_str()).collect();
assert_eq!(observed, types, "position order must follow slice order");
assert!(
rows.windows(2).all(|pair| pair[0].1 < pair[1].1),
"positions ascend strictly; nothing here assumes they ascend by one"
);
assert_eq!(i64::try_from(last.get()).unwrap(), rows[rows.len() - 1].1);
}
#[tokio::test]
async fn every_appended_row_carries_its_identity_and_stamp() {
let db = TempDb::new("identity");
let store = db.open();
let store_id = store.store_id();
let before = now_millis();
store
.append(
&[tagged("Enrolled", &[("course", "c1"), ("student", "s1")])],
None,
)
.await
.unwrap();
let after = now_millis();
let inspector = db.raw();
let (origin_store, origin_position, position, recorded_at): (Vec<u8>, i64, i64, i64) =
inspector
.query_row(
"SELECT origin_store, origin_position, position, recorded_at FROM event",
[],
|row| Ok((row.get(0)?, row.get(1)?, row.get(2)?, row.get(3)?)),
)
.unwrap();
assert_eq!(origin_store, store_id.to_bytes().to_vec());
assert_eq!(
origin_position, position,
"a locally appended event's origin position is the position it was just \
given"
);
assert!(
(before..=after).contains(&recorded_at),
"recorded_at is stamped once, at append: {recorded_at} outside \
[{before}, {after}]"
);
let mut statement = inspector
.prepare("SELECT tag, position, event_type FROM event_tag ORDER BY tag")
.unwrap();
let rows: Vec<(String, i64, String)> = statement
.query_map([], |row| Ok((row.get(0)?, row.get(1)?, row.get(2)?)))
.unwrap()
.map(Result::unwrap)
.collect();
assert_eq!(rows.len(), 2);
for (_, tag_position, event_type) in &rows {
assert_eq!(*tag_position, position);
assert_eq!(event_type, "Enrolled");
}
}
#[tokio::test]
async fn tag_cardinality_is_maintained_by_append() {
let db = TempDb::new("cardinality");
let store = db.open();
store
.append(
&[
tagged("Enrolled", &[("course", "c1"), ("student", "s1")]),
tagged("Enrolled", &[("course", "c1"), ("student", "s2")]),
tagged("Enrolled", &[("course", "c1"), ("student", "s3")]),
],
None,
)
.await
.unwrap();
let inspector = db.raw();
let mut statement = inspector
.prepare("SELECT tag, events FROM tag_cardinality ORDER BY tag")
.unwrap();
let counts: Vec<(String, i64)> = statement
.query_map([], |row| Ok((row.get(0)?, row.get(1)?)))
.unwrap()
.map(Result::unwrap)
.collect();
assert_eq!(
counts,
vec![
("course:c1".to_owned(), 3),
("student:s1".to_owned(), 1),
("student:s2".to_owned(), 1),
("student:s3".to_owned(), 1),
],
"every tag written is counted; a zero here is the most-selective-tag \
probe with nothing to order by"
);
}
#[tokio::test]
async fn the_identity_stamp_touches_only_the_batch_it_wrote() {
let db = TempDb::new("stamp-bounds");
let store = db.open();
let planted = {
let inspector = db.raw();
inspector
.execute(
"INSERT INTO event (event_type, data, metadata, tags, recorded_at) \
VALUES ('Planted', X'7b7d', NULL, X'1f', 0)",
[],
)
.unwrap();
inspector.last_insert_rowid()
};
store.append(&[event("Enrolled")], None).await.unwrap();
let inspector = db.raw();
let planted_origin: Option<i64> = inspector
.query_row(
"SELECT origin_position FROM event WHERE position = ?",
[planted],
|row| row.get(0),
)
.unwrap();
assert_eq!(
planted_origin, None,
"the stamp rewrote a row outside its own batch. An unbounded \
`WHERE origin_position IS NULL` scans the whole log under BEGIN \
IMMEDIATE and claims another origin's events as this store's own"
);
let appended_origin: Option<i64> = inspector
.query_row(
"SELECT origin_position FROM event WHERE event_type = 'Enrolled'",
[],
|row| row.get(0),
)
.unwrap();
assert_eq!(
appended_origin,
Some(planted + 1),
"the batch's own row must still be stamped with the position it was \
just given"
);
}
#[test]
fn the_identity_stamp_seeks_by_position_rather_than_scanning() {
let db = TempDb::new("stamp-plan");
drop(db.open());
let connection = db.raw();
let bounded = query_plan(
&connection,
"UPDATE event SET origin_store = X'00', origin_position = position \
WHERE position >= 1 AND origin_position IS NULL",
);
assert!(!bounded.is_empty(), "EXPLAIN QUERY PLAN returned no rows");
for detail in &bounded {
assert!(
!detail.contains("SCAN"),
"the identity stamp scans `event` instead of seeking to its own \
batch, under the BEGIN IMMEDIATE write lock. Plan: {bounded:?}"
);
}
let unbounded = query_plan(
&connection,
"UPDATE event SET origin_store = X'00', origin_position = position \
WHERE origin_position IS NULL",
);
assert!(
unbounded.iter().any(|detail| detail.contains("SCAN")),
"the negative control no longer scans, so the assertion above proves \
nothing about the bound. Plan: {unbounded:?}"
);
}
#[tokio::test]
async fn a_batch_at_the_declared_ceiling_lands_whole() {
let db = TempDb::new("full-ceiling");
let store = db.open();
let batch: Vec<Event> = (0..SqliteEventStore::MAX_EVENTS_PER_BATCH)
.map(|index| {
let pairs: Vec<(String, String)> = (0..SqliteEventStore::MAX_TAGS_PER_EVENT)
.map(|tag| (format!("k{tag}"), format!("v{index}")))
.collect();
let tags = Tags::from_pairs(
pairs
.iter()
.map(|(key, value)| (key.as_str(), value.as_str())),
)
.unwrap();
event("Bulk").with_tags(tags)
})
.collect();
let last = store.append(&batch, None).await.unwrap();
let inspector = db.raw();
let (events, tag_rows, _) = row_counts(&inspector);
assert_eq!(
events,
i64::try_from(SqliteEventStore::MAX_EVENTS_PER_BATCH).unwrap()
);
assert_eq!(
tag_rows,
i64::try_from(
SqliteEventStore::MAX_EVENTS_PER_BATCH * SqliteEventStore::MAX_TAGS_PER_EVENT
)
.unwrap(),
"every tag row of every event landed; a chunk lost here would be \
invisible to a port-level read-back of the events alone"
);
let positions = assigned_positions(&inspector);
assert_eq!(
i64::try_from(last.get()).unwrap(),
*positions.last().unwrap()
);
assert!(positions.windows(2).all(|pair| pair[0] < pair[1]));
}
#[tokio::test]
async fn a_failure_mid_batch_leaves_nothing() {
let db = TempDb::new("mid-batch-fault");
let store = db.open();
let inspector = db.raw();
inspector
.execute_batch(
"CREATE TRIGGER fail_mid_batch AFTER INSERT ON event
WHEN (SELECT count(*) FROM event) > 3
BEGIN SELECT RAISE(ABORT, 'injected mid-batch fault'); END;",
)
.unwrap();
let batch: Vec<Event> = (0..16).map(|_| tagged("Bulk", &[("k", "v")])).collect();
let failed = store.append(&batch, None).await;
assert!(
matches!(failed, Err(AppendError::Store(_))),
"an injected driver fault is honestly AppendError::Store; got {failed:?}"
);
let (events, tag_rows, cardinality) = row_counts(&inspector);
assert_eq!(
(events, tag_rows, cardinality),
(0, 0, 0),
"committing between chunks would leave a partially applied batch that a \
single-threaded read-back would happily confirm"
);
inspector
.execute_batch("DROP TRIGGER fail_mid_batch;")
.unwrap();
}
#[tokio::test(flavor = "multi_thread", worker_threads = 4)]
async fn contention_waits_rather_than_erroring() {
let db = TempDb::new("contention");
let path = db.path().to_path_buf();
let handles: Vec<_> = (0..4)
.map(|worker| {
let path = path.clone();
tokio::spawn(async move {
let store = SqliteEventStore::open(&path).unwrap();
let mut outcomes = Vec::new();
for round in 0..8 {
outcomes.push(
store
.append(&[tagged("Contended", &[("worker", "w")])], None)
.await
.map(|position| (worker, round, position)),
);
}
outcomes
})
})
.collect();
let mut committed = 0;
for handle in handles {
for outcome in handle.await.unwrap() {
match outcome {
Ok(_) => committed += 1,
Err(err) => panic!(
"contention must be absorbed by the busy timeout, not \
reported as a store failure: {err:?}"
),
}
}
}
assert_eq!(committed, 32);
let (events, _, _) = row_counts(&db.raw());
assert_eq!(events, 32);
}
fn now_millis() -> i64 {
use std::time::{SystemTime, UNIX_EPOCH};
SystemTime::now()
.duration_since(UNIX_EPOCH)
.ok()
.and_then(|since| i64::try_from(since.as_millis()).ok())
.unwrap_or(0)
}
#[test]
fn the_store_error_is_still_the_named_type() {
fn assert_error<T: core::error::Error + Send + Sync + 'static>() {}
assert_error::<SqliteEventStoreError>();
}
fn corrupt(db: &TempDb, sql: &str) {
db.raw()
.execute(sql, [])
.expect("the corruption is the test environment's, not the adapter's");
}
#[tokio::test]
async fn a_guard_whose_only_match_is_negative_is_reported_rather_than_satisfied() {
let db = TempDb::new("negative-guard");
let store = db.open();
store.append(&[event("Marker")], None).await.unwrap();
corrupt(&db, "UPDATE event SET position = -1 WHERE position = 1");
let outcome = store
.append(
&[event("Next")],
Some(&AppendCondition::new(query_of_types(&["Marker"]))),
)
.await;
match outcome {
Err(AppendError::Store(SqliteEventStoreError::InvalidPosition(-1))) => {}
outcome => panic!(
"a guard whose highest match is stored at `-1` must surface as \
`AppendError::Store(InvalidPosition(-1))`, and this store answered \
{outcome:?}. Comparing the raw `i64` against the boundary first \
means `-1 > 0` is false, so the guard reports *no violation* about \
a row that matches it — and the append it waves through is the one \
the condition existed to refuse"
),
}
}
#[tokio::test]
async fn a_negative_assigned_position_is_reported_rather_than_returned_absolutised() {
let db = TempDb::new("negative-assigned");
let store = db.open();
store.append(&[event("Seed")], None).await.unwrap();
corrupt(&db, "UPDATE event SET position = -5 WHERE position = 1");
corrupt(
&db,
"UPDATE sqlite_sequence SET seq = -5 WHERE name = 'event'",
);
let outcome = store.append(&[event("Next")], None).await;
match outcome {
Err(AppendError::Store(SqliteEventStoreError::InvalidPosition(-4))) => {}
outcome => panic!(
"an assigned position of `-4` must surface as \
`AppendError::Store(InvalidPosition(-4))`, and this store answered \
{outcome:?}. `SequencePosition::new((-4i64).unsigned_abs())` is \
`Some(4)`, a position the file does not contain and the next honest \
append will — so the acknowledgement the caller stores is a \
forgery, and VT-11's uniqueness is broken by the store's own \
write path"
),
}
assert_eq!(
assigned_positions(&db.raw()),
vec![-5],
"a refused append must leave the file exactly as it found it"
);
}