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

package/dist-engine-src/src/backend/predicate.rs

@@ -0,0 +1,80 @@
+use std::ops::Bound;
+
+use bytes::Bytes;
+
+use crate::backend::{Key, KeyRange, Prefix};
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct BackendPredicate {
+    pub id: PredicateId,
+    pub expr: PredicateExpr,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub struct PredicateId(pub u32);
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum PredicateExpr {
+    Key(KeyPredicate),
+    Header(HeaderPredicate),
+    Refs(RefsPredicate),
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum KeyPredicate {
+    Eq(Key),
+    StartsWith(Prefix),
+    Range(KeyRange),
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum HeaderPredicate {
+    FieldEq {
+        field: HeaderFieldId,
+        value: ScalarValue,
+    },
+    FieldIn {
+        field: HeaderFieldId,
+        values: Vec<ScalarValue>,
+    },
+    FieldRange {
+        field: HeaderFieldId,
+        lower: Bound<ScalarValue>,
+        upper: Bound<ScalarValue>,
+    },
+    IsDeleted(bool),
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum RefsPredicate {
+    HasRef { kind: RefKind, value: Bytes },
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub struct HeaderFieldId(pub u16);
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub struct RefKind(pub u16);
+
+#[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord)]
+pub enum ScalarValue {
+    Bool(bool),
+    U64(u64),
+    I64(i64),
+    Bytes(Bytes),
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum Support {
+    Exact,
+    Inexact,
+    Unsupported,
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum PredicateSupportLevel {
+    #[default]
+    None,
+    Inexact,
+    Exact,
+}

package/dist-engine-src/src/backend/traits.rs

@@ -0,0 +1,260 @@
+use crate::backend::{
+    BackendCapabilities, BackendError, CommitResult, GetManyResult, GetOptions, Key, KeyRange,
+    KeyRef, ProjectedValue, ProjectedValueRef, PutBatch, ReadEntry, ReadOptions, ScanOptions,
+    ScanResult, WriteOptions,
+};
+use std::sync::Arc;
+
+/// Process-local write lane for one backend durable target.
+///
+/// This type intentionally hides the async mutex implementation from the
+/// public `Backend` contract while preserving a cloneable handle that backend
+/// implementations can share across cloned or reopened handles.
+#[derive(Clone)]
+pub struct DurableWriteLock {
+    inner: Arc<tokio::sync::Mutex<()>>,
+}
+
+impl std::fmt::Debug for DurableWriteLock {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("DurableWriteLock").finish_non_exhaustive()
+    }
+}
+
+impl DurableWriteLock {
+    pub fn new() -> Self {
+        Self {
+            inner: Arc::new(tokio::sync::Mutex::new(())),
+        }
+    }
+
+    pub async fn lock_owned(&self) -> DurableWriteGuard {
+        DurableWriteGuard {
+            _guard: Arc::clone(&self.inner).lock_owned().await,
+        }
+    }
+
+    pub fn ptr_eq(&self, other: &Self) -> bool {
+        Arc::ptr_eq(&self.inner, &other.inner)
+    }
+}
+
+impl Default for DurableWriteLock {
+    fn default() -> Self {
+        Self::new()
+    }
+}
+
+pub struct DurableWriteGuard {
+    _guard: tokio::sync::OwnedMutexGuard<()>,
+}
+
+pub trait Backend {
+    type Read<'a>: BackendRead + 'a
+    where
+        Self: 'a;
+
+    type Write<'a>: BackendWrite + 'a
+    where
+        Self: 'a;
+
+    fn capabilities(&self) -> BackendCapabilities;
+
+    fn begin_read(&self, opts: ReadOptions) -> Result<Self::Read<'_>, BackendError>;
+
+    fn begin_write(&self, opts: WriteOptions) -> Result<Self::Write<'_>, BackendError>;
+
+    /// Serializes engine-level durable writes for this backend's durable target.
+    ///
+    /// Clones or independently opened handles for the same durable target must
+    /// return the same lock. Handles for independent targets may return
+    /// independent locks.
+    ///
+    /// This lock is a process-local write lane, not a durability mechanism.
+    /// Crash recovery, fsync policy, and cross-process serialization are backend
+    /// responsibilities in the MVP.
+    fn durable_write_lock(&self) -> DurableWriteLock;
+}
+
+pub trait BackendRead {
+    type RangeScan<'cursor>: BackendRangeScan;
+
+    fn visit_keys<V>(
+        &self,
+        keys: &[Key],
+        opts: GetOptions<'_>,
+        visitor: &mut V,
+    ) -> Result<(), BackendError>
+    where
+        V: PointVisitor + ?Sized;
+
+    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>;
+
+    fn close(self) -> Result<(), BackendError>
+    where
+        Self: Sized,
+    {
+        Ok(())
+    }
+}
+
+pub trait ScanVisitor {
+    fn visit(&mut self, key: KeyRef<'_>, value: ProjectedValueRef<'_>) -> Result<(), BackendError>;
+}
+
+pub trait BackendRangeScan {
+    fn visit_next<V>(
+        &mut self,
+        limit_rows: usize,
+        visitor: &mut V,
+    ) -> Result<ScanResult, BackendError>
+    where
+        V: ScanVisitor + ?Sized;
+}
+
+#[derive(Clone, Debug, Default)]
+pub struct BufferedRangeScan {
+    rows: Vec<ReadEntry>,
+    position: usize,
+}
+
+impl BufferedRangeScan {
+    pub fn new(rows: Vec<ReadEntry>) -> Self {
+        Self { rows, position: 0 }
+    }
+}
+
+impl BackendRangeScan for BufferedRangeScan {
+    fn visit_next<V>(
+        &mut self,
+        limit_rows: usize,
+        visitor: &mut V,
+    ) -> Result<ScanResult, BackendError>
+    where
+        V: ScanVisitor + ?Sized,
+    {
+        if limit_rows == 0 {
+            return Ok(ScanResult::default());
+        }
+
+        let mut emitted = 0usize;
+        while emitted < limit_rows {
+            let Some(entry) = self.rows.get(self.position) else {
+                break;
+            };
+            visitor.visit(entry.key.as_ref(), entry.value.as_ref())?;
+            self.position += 1;
+            emitted += 1;
+        }
+
+        Ok(ScanResult {
+            emitted,
+            has_more: self.position < self.rows.len(),
+        })
+    }
+}
+
+pub trait PointVisitor {
+    fn visit(
+        &mut self,
+        index: usize,
+        key: &Key,
+        value: Option<ProjectedValueRef<'_>>,
+    ) -> Result<(), BackendError>;
+}
+
+pub fn get_many<R>(
+    read: &R,
+    keys: &[Key],
+    opts: GetOptions<'_>,
+) -> Result<GetManyResult, BackendError>
+where
+    R: BackendRead + ?Sized,
+{
+    struct MaterializingPointVisitor<'a> {
+        values: &'a mut [Option<ProjectedValue>],
+    }
+
+    impl PointVisitor for MaterializingPointVisitor<'_> {
+        fn visit(
+            &mut self,
+            index: usize,
+            _key: &Key,
+            value: Option<ProjectedValueRef<'_>>,
+        ) -> Result<(), BackendError> {
+            if let Some(slot) = self.values.get_mut(index) {
+                *slot = value.map(|value| value.to_owned());
+            }
+            Ok(())
+        }
+    }
+
+    let mut values = vec![None::<ProjectedValue>; keys.len()];
+    read.visit_keys(
+        keys,
+        opts,
+        &mut MaterializingPointVisitor {
+            values: values.as_mut_slice(),
+        },
+    )?;
+    Ok(GetManyResult::new(values))
+}
+
+pub fn visit_range<R>(
+    read: &R,
+    range: KeyRange,
+    opts: ScanOptions<'_>,
+    visitor: &mut dyn ScanVisitor,
+) -> Result<ScanResult, BackendError>
+where
+    R: BackendRead,
+{
+    let limit_rows = opts.limit_rows;
+    read.with_range_scan(range, opts, |cursor| cursor.visit_next(limit_rows, visitor))
+}
+
+impl<F> ScanVisitor for F
+where
+    F: for<'a> FnMut(KeyRef<'a>, ProjectedValueRef<'a>) -> Result<(), BackendError>,
+{
+    fn visit(&mut self, key: KeyRef<'_>, value: ProjectedValueRef<'_>) -> Result<(), BackendError> {
+        self(key, value)
+    }
+}
+
+impl<F> PointVisitor for F
+where
+    F: for<'a> FnMut(usize, &Key, Option<ProjectedValueRef<'a>>) -> Result<(), BackendError>,
+{
+    fn visit(
+        &mut self,
+        index: usize,
+        key: &Key,
+        value: Option<ProjectedValueRef<'_>>,
+    ) -> Result<(), BackendError> {
+        self(index, key, value)
+    }
+}
+
+pub trait BackendWrite {
+    fn put_many(&mut self, entries: PutBatch) -> Result<(), BackendError>;
+
+    fn delete_many(&mut self, keys: &[Key]) -> Result<(), BackendError>;
+
+    fn delete_range(&mut self, range: KeyRange) -> Result<(), BackendError>;
+
+    fn commit(self) -> Result<CommitResult, BackendError>
+    where
+        Self: Sized;
+
+    fn rollback(self) -> Result<(), BackendError>
+    where
+        Self: Sized;
+}

package/dist-engine-src/src/backend/types.rs

@@ -1,96 +1,239 @@
-use async_trait::async_trait;
-
-use crate::backend::{
-    BackendKvEntryPage, BackendKvExistsBatch, BackendKvGetRequest, BackendKvKeyPage,
-    BackendKvScanRequest, BackendKvValueBatch, BackendKvValuePage, BackendKvWriteBatch,
-    BackendKvWriteStats,
-};
-use crate::LixError;
-
-#[async_trait]
-pub trait Backend: Send + Sync {
-    async fn begin_read_transaction(
-        &self,
-    ) -> Result<Box<dyn BackendReadTransaction + Send + Sync + 'static>, LixError>;
-
-    async fn begin_write_transaction(
-        &self,
-    ) -> Result<Box<dyn BackendWriteTransaction + Send + Sync + 'static>, LixError>;
-
-    /// Releases physical resources held by this backend handle.
+use std::ops::Bound;
+
+use bytes::Bytes;
+
+use crate::backend::BackendError;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct SpaceId(pub u32);
+
+#[derive(Clone, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct Key(pub Bytes);
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
+pub struct KeyRef<'a>(pub &'a [u8]);
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Value(pub Bytes);
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ReadEntry {
+    pub key: Key,
+    pub value: ProjectedValue,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct PutEntry {
+    pub key: Key,
+    pub value: StoredValue,
+}
+
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct PutBatch {
+    pub entries: Vec<PutEntry>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct StoredValue {
+    pub bytes: Bytes,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct KeyRange {
+    pub lower: Bound<Key>,
+    pub upper: Bound<Key>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Prefix {
+    pub bytes: Bytes,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct GetOptions<'a> {
+    pub projection: CoreProjection,
+    pub _reserved: std::marker::PhantomData<&'a ()>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub struct ScanOptions<'a> {
+    pub projection: CoreProjection,
+    pub limit_rows: usize,
+    pub resume_after: Option<&'a Key>,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct ScanChunk {
+    pub entries: Vec<ReadEntry>,
+    pub has_more: bool,
+}
+
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub struct ScanResult {
+    pub emitted: usize,
+    pub has_more: bool,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct GetManyResult {
+    /// One slot per key passed to `get_many`, in caller order.
     ///
-    /// This is a resource lifecycle operation, not a durability boundary and
-    /// not a destructive operation. Successful write transactions are durable
-    /// when their commit returns; callers should not rely on `close` to save
-    /// data. Implementations that do not own external resources may keep the
-    /// default no-op behavior.
-    async fn close(&self) -> Result<(), LixError> {
-        Ok(())
+    /// Duplicates are preserved. `None` means the requested key was missing.
+    pub values: Vec<Option<ProjectedValue>>,
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum CoreProjection {
+    KeyOnly,
+    FullValue,
+}
+
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum ProjectedValue {
+    KeyOnly,
+    FullValue(Bytes),
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum ProjectedValueRef<'a> {
+    KeyOnly,
+    FullValue(&'a [u8]),
+}
+
+impl ProjectedValueRef<'_> {
+    pub fn to_owned(self) -> ProjectedValue {
+        match self {
+            ProjectedValueRef::KeyOnly => ProjectedValue::KeyOnly,
+            ProjectedValueRef::FullValue(value) => {
+                ProjectedValue::FullValue(Bytes::copy_from_slice(value))
+            }
+        }
     }
+}
 
-    /// Destroys the physical storage target represented by this backend.
-    ///
-    /// This is a persistence lifecycle operation, not a logical SQL operation.
-    ///
-    /// Callers should treat the backend as the authority for what constitutes
-    /// the full storage target. For example:
-    ///
-    /// - native SQLite may delete the main database file plus WAL/SHM sidecars
-    /// - wasm/opfs SQLite may clear the persisted OPFS target
-    /// - Postgres may drop or clear the configured schema/database target
-    ///
-    /// Callers must not attempt to infer or delete backend-owned physical
-    /// artifacts themselves.
-    ///
-    /// Implementations may choose not to support destroy if the backend
-    /// instance does not have enough information or authority to remove its
-    /// target.
-    async fn destroy(&self) -> Result<(), LixError> {
-        Err(LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: "destroy is not supported by this backend".to_string(),
-            hint: None,
-            details: None,
-        })
+impl ProjectedValue {
+    pub fn as_ref(&self) -> ProjectedValueRef<'_> {
+        match self {
+            ProjectedValue::KeyOnly => ProjectedValueRef::KeyOnly,
+            ProjectedValue::FullValue(value) => ProjectedValueRef::FullValue(value.as_ref()),
+        }
+    }
+}
+
+impl<'a> KeyRef<'a> {
+    pub fn as_bytes(self) -> &'a [u8] {
+        self.0
+    }
+
+    pub fn to_owned_key(self) -> Key {
+        Key(Bytes::copy_from_slice(self.0))
     }
 }
 
-#[async_trait]
-pub trait BackendReadTransaction: Send + Sync {
-    async fn get_values(
-        &mut self,
-        request: BackendKvGetRequest,
-    ) -> Result<BackendKvValueBatch, LixError>;
+impl Key {
+    pub fn as_ref(&self) -> KeyRef<'_> {
+        KeyRef(self.0.as_ref())
+    }
+}
 
-    async fn exists_many(
-        &mut self,
-        request: BackendKvGetRequest,
-    ) -> Result<BackendKvExistsBatch, LixError>;
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct ReadOptions {
+    pub snapshot: Option<SnapshotRef>,
+    pub consistency: ReadConsistency,
+}
 
-    async fn scan_keys(
-        &mut self,
-        request: BackendKvScanRequest,
-    ) -> Result<BackendKvKeyPage, LixError>;
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum ReadConsistency {
+    #[default]
+    Snapshot,
+    StaleOk,
+    Latest,
+}
 
-    async fn scan_values(
-        &mut self,
-        request: BackendKvScanRequest,
-    ) -> Result<BackendKvValuePage, LixError>;
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct WriteOptions {
+    pub base_snapshot: Option<SnapshotRef>,
+    pub durability: Durability,
+    pub idempotency_key: Option<Bytes>,
+}
 
-    async fn scan_entries(
-        &mut self,
-        request: BackendKvScanRequest,
-    ) -> Result<BackendKvEntryPage, LixError>;
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct SnapshotRef(pub Bytes);
 
-    async fn rollback(self: Box<Self>) -> Result<(), LixError>;
+#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
+pub enum Durability {
+    #[default]
+    Durable,
 }
 
-#[async_trait]
-pub trait BackendWriteTransaction: BackendReadTransaction {
-    async fn write_kv_batch(
-        &mut self,
-        batch: BackendKvWriteBatch,
-    ) -> Result<BackendKvWriteStats, LixError>;
+#[derive(Clone, Debug, Default, PartialEq, Eq)]
+pub struct WriteStats {
+    pub put_entries: u64,
+    pub deleted_entries: u64,
+    pub deleted_ranges: u64,
+    pub written_bytes: u64,
+    pub backend_calls: u64,
+}
 
-    async fn commit(self: Box<Self>) -> Result<(), LixError>;
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct CommitResult {
+    pub commit_id: Option<Bytes>,
+    pub stats: WriteStats,
+}
+
+impl Prefix {
+    pub fn to_range(&self) -> Result<KeyRange, BackendError> {
+        let lower = Key(self.bytes.clone());
+        let mut upper = self.bytes.to_vec();
+
+        while let Some(last) = upper.last_mut() {
+            if *last == u8::MAX {
+                upper.pop();
+            } else {
+                *last += 1;
+                return Ok(KeyRange {
+                    lower: Bound::Included(lower),
+                    upper: Bound::Excluded(Key(Bytes::from(upper))),
+                });
+            }
+        }
+
+        Ok(KeyRange {
+            lower: Bound::Included(lower),
+            upper: Bound::Unbounded,
+        })
+    }
+}
+
+impl Default for GetOptions<'_> {
+    fn default() -> Self {
+        Self {
+            projection: CoreProjection::FullValue,
+            _reserved: std::marker::PhantomData,
+        }
+    }
+}
+
+impl GetManyResult {
+    pub fn new(values: Vec<Option<ProjectedValue>>) -> Self {
+        Self { values }
+    }
+
+    pub fn entries_for_requested_keys(&self, keys: &[Key]) -> Vec<ReadEntry> {
+        keys.iter()
+            .cloned()
+            .zip(self.values.iter().cloned())
+            .filter_map(|(key, value)| value.map(|value| ReadEntry { key, value }))
+            .collect()
+    }
+}
+
+impl Default for ScanOptions<'_> {
+    fn default() -> Self {
+        Self {
+            projection: CoreProjection::FullValue,
+            limit_rows: 1024,
+            resume_after: None,
+        }
+    }
 }