@lix-js/sdk 0.6.0-preview.3 → 0.6.0-preview.5

package/dist-engine-src/src/backend/conformance/factory.rs

@@ -0,0 +1,93 @@
+use crate::backend::{
+    Backend, BackendCapabilities, BackendError, DurableWriteLock, ReadOptions, WriteOptions,
+};
+
+pub trait BackendFactory {
+    type Backend: Backend;
+    type Fixture: BackendFixture<Backend = Self::Backend>;
+
+    fn create_fixture(&self) -> Self::Fixture;
+
+    fn capabilities(&self) -> BackendCapabilities {
+        self.create_fixture().open().capabilities()
+    }
+
+    fn config(&self) -> BackendTestConfig {
+        BackendTestConfig::default()
+    }
+}
+
+pub trait BackendFixture {
+    type Backend: Backend;
+
+    fn open(&self) -> Self::Backend;
+}
+
+pub(crate) struct OpenBackend<F>
+where
+    F: BackendFactory,
+{
+    _fixture: F::Fixture,
+    backend: F::Backend,
+}
+
+pub(crate) fn open_backend<F>(factory: &F) -> OpenBackend<F>
+where
+    F: BackendFactory,
+{
+    let fixture = factory.create_fixture();
+    let backend = fixture.open();
+    OpenBackend {
+        _fixture: fixture,
+        backend,
+    }
+}
+
+impl<F> Backend for OpenBackend<F>
+where
+    F: BackendFactory,
+{
+    type Read<'a>
+        = <F::Backend as Backend>::Read<'a>
+    where
+        Self: 'a;
+    type Write<'a>
+        = <F::Backend as Backend>::Write<'a>
+    where
+        Self: 'a;
+
+    fn capabilities(&self) -> BackendCapabilities {
+        self.backend.capabilities()
+    }
+
+    fn begin_read(&self, opts: ReadOptions) -> Result<Self::Read<'_>, BackendError> {
+        self.backend.begin_read(opts)
+    }
+
+    fn begin_write(&self, opts: WriteOptions) -> Result<Self::Write<'_>, BackendError> {
+        self.backend.begin_write(opts)
+    }
+
+    fn durable_write_lock(&self) -> DurableWriteLock {
+        self.backend.durable_write_lock()
+    }
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct BackendTestConfig {
+    pub max_key_len: usize,
+    pub max_value_len: usize,
+    pub ephemeral: bool,
+    pub supports_concurrent_writers: bool,
+}
+
+impl Default for BackendTestConfig {
+    fn default() -> Self {
+        Self {
+            max_key_len: 256,
+            max_value_len: 4096,
+            ephemeral: false,
+            supports_concurrent_writers: false,
+        }
+    }
+}

package/dist-engine-src/src/backend/conformance/failure_tests.rs

@@ -0,0 +1,608 @@
+use std::collections::{BTreeMap, BTreeSet};
+use std::ops::Bound;
+use std::sync::{Arc, Mutex};
+
+use bytes::Bytes;
+
+use super::{
+    run_backend_conformance, BackendFactory, BackendFixture, BackendTestConfig, ConformanceStatus,
+};
+use crate::backend::{
+    Backend, BackendCapabilities, BackendError, BackendRead, BackendWrite, BufferedRangeScan,
+    CommitResult, CoreProjection, DurableWriteLock, GetOptions, Key, KeyRange, KeyRef,
+    PointVisitor, ProjectedValueRef, ProjectionCapabilities, PutBatch, ReadEntry, ReadOptions,
+    ScanOptions, ScanResult, ScanVisitor, StoredValue, WriteConcurrency, WriteOptions, WriteStats,
+};
+
+type BrokenMap = BTreeMap<Key, Bytes>;
+
+#[derive(Clone, Copy, Debug)]
+enum BrokenMode {
+    GetManyMissesExistingKey,
+    ReadSeesLaterCommits,
+    ReadSeesSecondLaterCommit,
+    ScanReadSeesLaterCommits,
+    DeleteManyIgnoresExistingKeys,
+    DeleteRangeIgnoresUpperBound,
+    KeyOnlyScanReturnsFullValues,
+    AdvertisesPendingCapability,
+    RollbackCommits,
+    BadByteOrdering,
+    KeyResumeRepeatsLastKey,
+    LoseCommittedDataOnReopen,
+    ReopenReturnsFreshDurableWriteLock,
+    CorruptOpaqueBytes,
+}
+
+#[derive(Clone, Debug)]
+struct BrokenBackendFactory {
+    mode: BrokenMode,
+}
+
+#[derive(Clone, Debug)]
+struct BrokenBackendFixture {
+    mode: BrokenMode,
+    entries: Arc<Mutex<BrokenMap>>,
+    commit_count: Arc<Mutex<u64>>,
+    open_count: Arc<Mutex<u64>>,
+    durable_write_lock: DurableWriteLock,
+}
+
+#[derive(Clone, Debug)]
+struct BrokenBackend {
+    mode: BrokenMode,
+    entries: Arc<Mutex<BrokenMap>>,
+    commit_count: Arc<Mutex<u64>>,
+    durable_write_lock: DurableWriteLock,
+}
+
+#[derive(Clone)]
+struct BrokenRead {
+    mode: BrokenMode,
+    parent: Arc<Mutex<BrokenMap>>,
+    commit_count: Arc<Mutex<u64>>,
+    snapshot_commit_count: u64,
+    snapshot: BrokenMap,
+}
+
+struct BrokenWrite {
+    mode: BrokenMode,
+    parent: Arc<Mutex<BrokenMap>>,
+    commit_count: Arc<Mutex<u64>>,
+    staged: BrokenMap,
+}
+
+#[test]
+fn detects_get_many_missing_existing_key_violation() {
+    assert_failed(
+        BrokenMode::GetManyMissesExistingKey,
+        "baseline::get_many_returns_requested_slots",
+    );
+}
+
+#[test]
+fn detects_read_snapshot_violation() {
+    assert_failed(
+        BrokenMode::ReadSeesLaterCommits,
+        "baseline::begin_read_pins_coherent_view",
+    );
+}
+
+#[test]
+fn detects_read_snapshot_second_commit_violation() {
+    assert_failed(
+        BrokenMode::ReadSeesSecondLaterCommit,
+        "baseline::begin_read_pins_coherent_view",
+    );
+}
+
+#[test]
+fn detects_scan_read_snapshot_violation() {
+    assert_failed(
+        BrokenMode::ScanReadSeesLaterCommits,
+        "baseline::begin_read_pins_coherent_view",
+    );
+}
+
+#[test]
+fn detects_delete_many_ignores_existing_keys() {
+    assert_failed(
+        BrokenMode::DeleteManyIgnoresExistingKeys,
+        "baseline::delete_many_removes_existing_keys",
+    );
+}
+
+#[test]
+fn detects_delete_range_ignores_upper_bound() {
+    assert_failed(
+        BrokenMode::DeleteRangeIgnoresUpperBound,
+        "baseline::delete_range_removes_exact_range",
+    );
+}
+
+#[test]
+fn detects_key_only_scan_projection_violation() {
+    assert_failed(
+        BrokenMode::KeyOnlyScanReturnsFullValues,
+        "baseline::full_value_and_key_only_are_core",
+    );
+}
+
+#[test]
+fn detects_advertised_pending_capability() {
+    let report = run_backend_conformance(&BrokenBackendFactory {
+        mode: BrokenMode::AdvertisesPendingCapability,
+    });
+    let pending = report.tests.iter().any(|test| {
+        test.name == "projection::header_returns_header_without_payload"
+            && matches!(test.status, ConformanceStatus::Pending)
+    });
+    assert!(
+        pending,
+        "expected advertised projection capability to create pending test, got {report:#?}"
+    );
+
+    let panic = std::panic::catch_unwind(|| report.assert_no_failures());
+    assert!(
+        panic.is_err(),
+        "assert_no_failures should fail when advertised capabilities are pending"
+    );
+}
+
+#[test]
+fn detects_rollback_commits_violation() {
+    assert_failed(
+        BrokenMode::RollbackCommits,
+        "baseline::rollback_discards_staged_mutations",
+    );
+}
+
+#[test]
+fn detects_rollback_overwrite_delete_violation() {
+    assert_failed(
+        BrokenMode::RollbackCommits,
+        "baseline::rollback_discards_overwrite_and_delete",
+    );
+}
+
+#[test]
+fn detects_bad_byte_ordering_violation() {
+    assert_failed(
+        BrokenMode::BadByteOrdering,
+        "baseline::scan_range_orders_raw_byte_keys",
+    );
+}
+
+#[test]
+fn detects_multi_chunk_drain_repeat_violation() {
+    assert_failed(
+        BrokenMode::KeyResumeRepeatsLastKey,
+        "baseline::scan_range_drains_multi_chunk_limits",
+    );
+}
+
+#[test]
+fn detects_opaque_byte_corruption_violation() {
+    assert_failed(
+        BrokenMode::CorruptOpaqueBytes,
+        "baseline::full_value_preserves_opaque_bytes",
+    );
+}
+
+#[test]
+fn detects_persistent_commit_lost_on_reopen_violation() {
+    assert_failed(
+        BrokenMode::LoseCommittedDataOnReopen,
+        "persistence::committed_data_survives_reopen",
+    );
+}
+
+#[test]
+fn detects_fresh_durable_write_lock_on_reopen_violation() {
+    assert_failed(
+        BrokenMode::ReopenReturnsFreshDurableWriteLock,
+        "persistence::durable_write_lock_is_shared_across_reopen",
+    );
+}
+
+#[test]
+fn detects_persistent_rollback_on_reopen_violation() {
+    assert_failed(
+        BrokenMode::RollbackCommits,
+        "persistence::rolled_back_data_does_not_survive_reopen",
+    );
+}
+
+fn assert_failed(mode: BrokenMode, test_name: &'static str) {
+    let report = run_backend_conformance(&BrokenBackendFactory { mode });
+    let failed = report
+        .tests
+        .iter()
+        .any(|test| test.name == test_name && matches!(test.status, ConformanceStatus::Failed(_)));
+    assert!(
+        failed,
+        "expected {test_name} to fail for {mode:?}, got {:#?}",
+        report
+    );
+}
+
+impl BackendFactory for BrokenBackendFactory {
+    type Backend = BrokenBackend;
+    type Fixture = BrokenBackendFixture;
+
+    fn create_fixture(&self) -> Self::Fixture {
+        BrokenBackendFixture {
+            mode: self.mode,
+            entries: Arc::new(Mutex::new(BrokenMap::new())),
+            commit_count: Arc::new(Mutex::new(0)),
+            open_count: Arc::new(Mutex::new(0)),
+            durable_write_lock: DurableWriteLock::new(),
+        }
+    }
+
+    fn config(&self) -> BackendTestConfig {
+        BackendTestConfig::default()
+    }
+}
+
+impl BackendFixture for BrokenBackendFixture {
+    type Backend = BrokenBackend;
+
+    fn open(&self) -> Self::Backend {
+        let mut open_count = self
+            .open_count
+            .lock()
+            .expect("broken backend open count lock poisoned");
+        if matches!(self.mode, BrokenMode::LoseCommittedDataOnReopen) && *open_count > 0 {
+            self.entries
+                .lock()
+                .expect("broken backend entries lock poisoned")
+                .clear();
+        }
+        *open_count += 1;
+        let durable_write_lock =
+            if matches!(self.mode, BrokenMode::ReopenReturnsFreshDurableWriteLock) {
+                DurableWriteLock::new()
+            } else {
+                self.durable_write_lock.clone()
+            };
+        BrokenBackend {
+            mode: self.mode,
+            entries: Arc::clone(&self.entries),
+            commit_count: Arc::clone(&self.commit_count),
+            durable_write_lock,
+        }
+    }
+}
+
+impl Backend for BrokenBackend {
+    type Read<'a>
+        = BrokenRead
+    where
+        Self: 'a;
+
+    type Write<'a>
+        = BrokenWrite
+    where
+        Self: 'a;
+
+    fn capabilities(&self) -> BackendCapabilities {
+        let mut capabilities = BackendCapabilities::v0(WriteConcurrency::SingleWriter);
+        if matches!(self.mode, BrokenMode::AdvertisesPendingCapability) {
+            capabilities.projection = ProjectionCapabilities {
+                header: true,
+                ..ProjectionCapabilities::default()
+            };
+        }
+        capabilities
+    }
+
+    fn begin_read(&self, _opts: ReadOptions) -> Result<Self::Read<'_>, BackendError> {
+        Ok(BrokenRead {
+            mode: self.mode,
+            parent: Arc::clone(&self.entries),
+            commit_count: Arc::clone(&self.commit_count),
+            snapshot_commit_count: *self
+                .commit_count
+                .lock()
+                .map_err(|_| BackendError::Io("broken backend commit lock poisoned".to_string()))?,
+            snapshot: self.snapshot()?,
+        })
+    }
+
+    fn begin_write(&self, _opts: WriteOptions) -> Result<Self::Write<'_>, BackendError> {
+        Ok(BrokenWrite {
+            mode: self.mode,
+            parent: Arc::clone(&self.entries),
+            commit_count: Arc::clone(&self.commit_count),
+            staged: self.snapshot()?,
+        })
+    }
+
+    fn durable_write_lock(&self) -> DurableWriteLock {
+        self.durable_write_lock.clone()
+    }
+}
+
+impl BackendRead for BrokenRead {
+    type RangeScan<'a> = BufferedRangeScan;
+
+    fn visit_keys<V>(
+        &self,
+        keys: &[Key],
+        opts: GetOptions<'_>,
+        visitor: &mut V,
+    ) -> Result<(), BackendError>
+    where
+        V: PointVisitor + ?Sized,
+    {
+        let live_entries;
+        let current_commit_count = *self
+            .commit_count
+            .lock()
+            .map_err(|_| BackendError::Io("broken backend commit lock poisoned".to_string()))?;
+        let entries = if matches!(self.mode, BrokenMode::ReadSeesLaterCommits)
+            || (matches!(self.mode, BrokenMode::ReadSeesSecondLaterCommit)
+                && current_commit_count >= self.snapshot_commit_count + 2)
+        {
+            live_entries = self
+                .parent
+                .lock()
+                .map_err(|_| BackendError::Io("broken backend lock poisoned".to_string()))?
+                .clone();
+            &live_entries
+        } else {
+            &self.snapshot
+        };
+        visit_keys_from_map(entries, self.mode, keys, opts, visitor)
+    }
+
+    fn with_range_scan<T, F>(
+        &self,
+        range: KeyRange,
+        opts: ScanOptions<'_>,
+        f: F,
+    ) -> Result<T, BackendError>
+    where
+        F: FnOnce(&mut Self::RangeScan<'_>) -> Result<T, BackendError>,
+    {
+        let live_entries;
+        let entries = if matches!(self.mode, BrokenMode::ScanReadSeesLaterCommits) {
+            live_entries = self
+                .parent
+                .lock()
+                .map_err(|_| BackendError::Io("broken backend lock poisoned".to_string()))?
+                .clone();
+            &live_entries
+        } else {
+            &self.snapshot
+        };
+        let mut cursor =
+            BufferedRangeScan::new(scan_rows_from_map(entries, self.mode, range, opts));
+        f(&mut cursor)
+    }
+}
+
+impl BackendWrite for BrokenWrite {
+    fn put_many(&mut self, entries: PutBatch) -> Result<(), BackendError> {
+        for entry in entries.entries {
+            let mut bytes = stored_value_bytes(entry.value);
+            if matches!(self.mode, BrokenMode::CorruptOpaqueBytes) {
+                bytes = Bytes::from(
+                    bytes
+                        .iter()
+                        .copied()
+                        .filter(|byte| *byte != 0)
+                        .collect::<Vec<_>>(),
+                );
+            }
+            self.staged.insert(entry.key, bytes);
+        }
+        Ok(())
+    }
+
+    fn delete_many(&mut self, keys: &[Key]) -> Result<(), BackendError> {
+        for key in keys {
+            if matches!(self.mode, BrokenMode::DeleteManyIgnoresExistingKeys)
+                && self.staged.contains_key(key)
+            {
+                continue;
+            }
+            self.staged.remove(key);
+        }
+        Ok(())
+    }
+
+    fn delete_range(&mut self, range: KeyRange) -> Result<(), BackendError> {
+        if matches!(self.mode, BrokenMode::DeleteRangeIgnoresUpperBound) {
+            self.staged.retain(|key, _value| match &range.lower {
+                Bound::Included(lower) => key < lower,
+                Bound::Excluded(lower) => key <= lower,
+                Bound::Unbounded => false,
+            });
+        } else {
+            self.staged
+                .retain(|key, _value| !range_contains(&range, key));
+        }
+        Ok(())
+    }
+
+    fn commit(self) -> Result<CommitResult, BackendError> {
+        *self
+            .parent
+            .lock()
+            .map_err(|_| BackendError::Io("broken backend lock poisoned".to_string()))? =
+            self.staged;
+        *self
+            .commit_count
+            .lock()
+            .map_err(|_| BackendError::Io("broken backend commit lock poisoned".to_string()))? += 1;
+        Ok(CommitResult {
+            commit_id: None,
+            stats: WriteStats::default(),
+        })
+    }
+
+    fn rollback(self) -> Result<(), BackendError> {
+        if matches!(self.mode, BrokenMode::RollbackCommits) {
+            *self
+                .parent
+                .lock()
+                .map_err(|_| BackendError::Io("broken backend lock poisoned".to_string()))? =
+                self.staged;
+            *self.commit_count.lock().map_err(|_| {
+                BackendError::Io("broken backend commit lock poisoned".to_string())
+            })? += 1;
+        }
+        Ok(())
+    }
+}
+
+impl BrokenBackend {
+    fn snapshot(&self) -> Result<BrokenMap, BackendError> {
+        self.entries
+            .lock()
+            .map_err(|_| BackendError::Io("broken backend lock poisoned".to_string()))
+            .map(|entries| entries.clone())
+    }
+}
+
+fn visit_keys_from_map<V>(
+    entries: &BrokenMap,
+    mode: BrokenMode,
+    keys: &[Key],
+    opts: GetOptions<'_>,
+    visitor: &mut V,
+) -> Result<(), BackendError>
+where
+    V: PointVisitor + ?Sized,
+{
+    let mut seen = BTreeSet::new();
+    for (index, key) in keys.iter().enumerate() {
+        if matches!(mode, BrokenMode::GetManyMissesExistingKey)
+            && key == &Key(Bytes::from_static(b"a"))
+        {
+            visitor.visit(index, key, None)?;
+            continue;
+        }
+        let value = if !seen.insert(key.clone()) {
+            entries
+                .get(key)
+                .map(|value| project_value_ref(value, mode, opts.projection, false))
+        } else {
+            entries
+                .get(key)
+                .map(|value| project_value_ref(value, mode, opts.projection, false))
+        };
+        visitor.visit(index, key, value)?;
+    }
+    Ok(())
+}
+
+fn visit_range_from_map<V>(
+    entries: &BrokenMap,
+    mode: BrokenMode,
+    range: KeyRange,
+    opts: ScanOptions<'_>,
+    visitor: &mut V,
+) -> Result<ScanResult, BackendError>
+where
+    V: ScanVisitor + ?Sized,
+{
+    let mut emitted = 0;
+    let mut has_more = false;
+    let mut candidates = entries
+        .iter()
+        .filter(|(key, _)| range_contains(&range, key))
+        .collect::<Vec<_>>();
+    if matches!(mode, BrokenMode::BadByteOrdering) {
+        candidates.sort_by(|left, right| {
+            left.0
+                 .0
+                .len()
+                .cmp(&right.0 .0.len())
+                .then(left.0.cmp(right.0))
+        });
+    }
+
+    for (key, value) in candidates {
+        if opts.resume_after.is_some_and(|resume_after| {
+            if matches!(mode, BrokenMode::KeyResumeRepeatsLastKey) {
+                key < resume_after
+            } else {
+                key <= resume_after
+            }
+        }) {
+            continue;
+        }
+        if emitted == opts.limit_rows {
+            has_more = true;
+            break;
+        }
+        visitor.visit(
+            key.as_ref(),
+            project_value_ref(value, mode, opts.projection, true),
+        )?;
+        emitted += 1;
+    }
+
+    Ok(ScanResult { emitted, has_more })
+}
+
+fn scan_rows_from_map(
+    entries: &BrokenMap,
+    mode: BrokenMode,
+    range: KeyRange,
+    opts: ScanOptions<'_>,
+) -> Vec<ReadEntry> {
+    let mut rows = Vec::new();
+    let _ = visit_range_from_map(
+        entries,
+        mode,
+        range,
+        opts,
+        &mut |key: KeyRef<'_>, value: ProjectedValueRef<'_>| {
+            rows.push(ReadEntry {
+                key: key.to_owned_key(),
+                value: value.to_owned(),
+            });
+            Ok(())
+        },
+    );
+    rows
+}
+
+fn range_contains(range: &KeyRange, key: &Key) -> bool {
+    let lower_matches = match &range.lower {
+        Bound::Included(lower) => key >= lower,
+        Bound::Excluded(lower) => key > lower,
+        Bound::Unbounded => true,
+    };
+    let upper_matches = match &range.upper {
+        Bound::Included(upper) => key <= upper,
+        Bound::Excluded(upper) => key < upper,
+        Bound::Unbounded => true,
+    };
+    lower_matches && upper_matches
+}
+
+fn project_value_ref(
+    value: &Bytes,
+    mode: BrokenMode,
+    projection: CoreProjection,
+    break_key_only: bool,
+) -> ProjectedValueRef<'_> {
+    match projection {
+        CoreProjection::KeyOnly
+            if break_key_only && matches!(mode, BrokenMode::KeyOnlyScanReturnsFullValues) =>
+        {
+            ProjectedValueRef::FullValue(value.as_ref())
+        }
+        CoreProjection::KeyOnly => ProjectedValueRef::KeyOnly,
+        CoreProjection::FullValue => ProjectedValueRef::FullValue(value.as_ref()),
+    }
+}
+
+fn stored_value_bytes(value: StoredValue) -> Bytes {
+    value.bytes
+}