@lix-js/sdk 0.6.0-preview.1 → 0.6.0-preview.2

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

@@ -0,0 +1,358 @@
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct BytePage {
+    bytes: Vec<u8>,
+    offsets: Vec<u32>,
+}
+
+impl BytePage {
+    pub fn new() -> Self {
+        Self {
+            bytes: Vec::new(),
+            offsets: vec![0],
+        }
+    }
+
+    pub fn len(&self) -> usize {
+        self.offsets.len().saturating_sub(1)
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    pub fn get(&self, index: usize) -> Option<&[u8]> {
+        let start = usize::try_from(*self.offsets.get(index)?).ok()?;
+        let end = usize::try_from(*self.offsets.get(index + 1)?).ok()?;
+        self.bytes.get(start..end)
+    }
+
+    pub fn iter(&self) -> BytePageIter<'_> {
+        BytePageIter {
+            page: self,
+            index: 0,
+        }
+    }
+}
+
+pub struct BytePageIter<'a> {
+    page: &'a BytePage,
+    index: usize,
+}
+
+impl<'a> Iterator for BytePageIter<'a> {
+    type Item = &'a [u8];
+
+    fn next(&mut self) -> Option<Self::Item> {
+        let value = self.page.get(self.index)?;
+        self.index += 1;
+        Some(value)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct BytePageBuilder {
+    bytes: Vec<u8>,
+    offsets: Vec<u32>,
+}
+
+impl BytePageBuilder {
+    pub fn new() -> Self {
+        Self {
+            bytes: Vec::new(),
+            offsets: vec![0],
+        }
+    }
+
+    pub fn with_capacity(items: usize, bytes: usize) -> Self {
+        let mut offsets = Vec::with_capacity(items.saturating_add(1));
+        offsets.push(0);
+        Self {
+            bytes: Vec::with_capacity(bytes),
+            offsets,
+        }
+    }
+
+    pub fn from_page(page: BytePage) -> Self {
+        Self {
+            bytes: page.bytes,
+            offsets: page.offsets,
+        }
+    }
+
+    pub fn len(&self) -> usize {
+        self.offsets.len().saturating_sub(1)
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.len() == 0
+    }
+
+    pub fn get(&self, index: usize) -> Option<&[u8]> {
+        let start = usize::try_from(*self.offsets.get(index)?).ok()?;
+        let end = usize::try_from(*self.offsets.get(index + 1)?).ok()?;
+        self.bytes.get(start..end)
+    }
+
+    pub fn push(&mut self, value: impl AsRef<[u8]>) {
+        let value = value.as_ref();
+        self.bytes.extend_from_slice(value);
+        let end = u32::try_from(self.bytes.len()).expect("byte page exceeds u32 offset capacity");
+        self.offsets.push(end);
+    }
+
+    pub fn finish(self) -> BytePage {
+        BytePage {
+            bytes: self.bytes,
+            offsets: self.offsets,
+        }
+    }
+}
+
+/// Ordered byte range for backend KV scans.
+///
+/// Ranges are half-open: `start <= key < end`. `Prefix` is explicit because it
+/// is a common access pattern and lets each backend choose the safest
+/// implementation for its storage engine.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum BackendKvScanRange {
+    Prefix(Vec<u8>),
+    Range { start: Vec<u8>, end: Vec<u8> },
+}
+
+impl BackendKvScanRange {
+    pub fn prefix(prefix: impl Into<Vec<u8>>) -> Self {
+        Self::Prefix(prefix.into())
+    }
+
+    pub fn range(start: impl Into<Vec<u8>>, end: impl Into<Vec<u8>>) -> Self {
+        Self::Range {
+            start: start.into(),
+            end: end.into(),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvGetRequest {
+    pub groups: Vec<BackendKvGetGroup>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvGetGroup {
+    pub namespace: String,
+    pub keys: Vec<Vec<u8>>,
+}
+
+impl BackendKvGetGroup {
+    pub fn namespace(&self) -> &str {
+        &self.namespace
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvValueBatch {
+    pub groups: Vec<BackendKvValueGroup>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvValueGroup {
+    namespace: String,
+    values: BytePage,
+    present: Vec<bool>,
+}
+
+impl BackendKvValueGroup {
+    pub fn new(namespace: impl Into<String>, values: BytePage, present: Vec<bool>) -> Self {
+        assert_eq!(
+            values.len(),
+            present.len(),
+            "backend value batch must have one value slot per presence bit"
+        );
+        Self {
+            namespace: namespace.into(),
+            values,
+            present,
+        }
+    }
+
+    pub fn namespace(&self) -> &str {
+        &self.namespace
+    }
+
+    pub fn len(&self) -> usize {
+        self.present.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.present.is_empty()
+    }
+
+    pub fn value(&self, index: usize) -> Option<Option<&[u8]>> {
+        let present = *self.present.get(index)?;
+        if present {
+            Some(Some(
+                self.values
+                    .get(index)
+                    .expect("backend value batch invariant violated"),
+            ))
+        } else {
+            Some(None)
+        }
+    }
+
+    pub fn values_iter(&self) -> impl Iterator<Item = Option<&[u8]>> {
+        (0..self.len()).filter_map(|index| self.value(index))
+    }
+
+    pub fn into_parts(self) -> (String, BytePage, Vec<bool>) {
+        (self.namespace, self.values, self.present)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvExistsBatch {
+    pub groups: Vec<BackendKvExistsGroup>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvExistsGroup {
+    pub namespace: String,
+    pub exists: Vec<bool>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvScanRequest {
+    pub namespace: String,
+    pub range: BackendKvScanRange,
+    pub after: Option<Vec<u8>>,
+    pub limit: usize,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvKeyPage {
+    pub keys: BytePage,
+    pub resume_after: Option<Vec<u8>>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvValuePage {
+    pub values: BytePage,
+    pub resume_after: Option<Vec<u8>>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvEntryPage {
+    pub keys: BytePage,
+    pub values: BytePage,
+    pub resume_after: Option<Vec<u8>>,
+}
+
+impl BackendKvEntryPage {
+    pub fn len(&self) -> usize {
+        self.keys.len()
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.keys.is_empty()
+    }
+
+    pub fn key(&self, index: usize) -> Option<&[u8]> {
+        self.keys.get(index)
+    }
+
+    pub fn value(&self, index: usize) -> Option<&[u8]> {
+        self.values.get(index)
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, Default)]
+pub struct BackendKvWriteBatch {
+    pub groups: Vec<BackendKvWriteGroup>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct BackendKvWriteGroup {
+    namespace: String,
+    put_keys: BytePageBuilder,
+    put_values: BytePageBuilder,
+    deletes: BytePageBuilder,
+}
+
+impl BackendKvWriteGroup {
+    pub fn new(namespace: impl Into<String>) -> Self {
+        Self {
+            namespace: namespace.into(),
+            put_keys: BytePageBuilder::new(),
+            put_values: BytePageBuilder::new(),
+            deletes: BytePageBuilder::new(),
+        }
+    }
+
+    pub fn from_pages(
+        namespace: impl Into<String>,
+        put_keys: BytePage,
+        put_values: BytePage,
+        deletes: BytePage,
+    ) -> Self {
+        assert_eq!(
+            put_keys.len(),
+            put_values.len(),
+            "backend write batch must have one value per put key"
+        );
+        Self {
+            namespace: namespace.into(),
+            put_keys: BytePageBuilder::from_page(put_keys),
+            put_values: BytePageBuilder::from_page(put_values),
+            deletes: BytePageBuilder::from_page(deletes),
+        }
+    }
+
+    pub fn put(&mut self, key: impl AsRef<[u8]>, value: impl AsRef<[u8]>) {
+        self.put_keys.push(key);
+        self.put_values.push(value);
+    }
+
+    pub fn delete(&mut self, key: impl AsRef<[u8]>) {
+        self.deletes.push(key);
+    }
+
+    pub fn namespace(&self) -> &str {
+        &self.namespace
+    }
+
+    pub fn put_count(&self) -> usize {
+        self.put_keys.len()
+    }
+
+    pub fn delete_count(&self) -> usize {
+        self.deletes.len()
+    }
+
+    pub fn put_key(&self, index: usize) -> Option<&[u8]> {
+        self.put_keys.get(index)
+    }
+
+    pub fn put_value(&self, index: usize) -> Option<&[u8]> {
+        self.put_values.get(index)
+    }
+
+    pub fn delete_key(&self, index: usize) -> Option<&[u8]> {
+        self.deletes.get(index)
+    }
+
+    pub fn into_parts(self) -> (String, BytePage, BytePage, BytePage) {
+        (
+            self.namespace,
+            self.put_keys.finish(),
+            self.put_values.finish(),
+            self.deletes.finish(),
+        )
+    }
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct BackendKvWriteStats {
+    pub puts: usize,
+    pub deletes: usize,
+    pub bytes_written: usize,
+}

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

@@ -0,0 +1,12 @@
+mod kv;
+#[cfg(test)]
+pub(crate) mod testing;
+mod types;
+
+pub use kv::{
+    BackendKvEntryPage, BackendKvExistsBatch, BackendKvExistsGroup, BackendKvGetGroup,
+    BackendKvGetRequest, BackendKvKeyPage, BackendKvScanRange, BackendKvScanRequest,
+    BackendKvValueBatch, BackendKvValueGroup, BackendKvValuePage, BackendKvWriteBatch,
+    BackendKvWriteGroup, BackendKvWriteStats, BytePage, BytePageBuilder,
+};
+pub use types::{Backend, BackendReadTransaction, BackendWriteTransaction};