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

package/dist-engine-src/src/untracked_state/codec.rs

@@ -0,0 +1,307 @@
+use crate::entity_identity::EntityIdentity;
+use crate::untracked_state::{UntrackedStateRow, UntrackedStateRowRef};
+use crate::LixError;
+
+const UNTRACKED_STATE_FILE_IDENTIFIER: &str = "LXUS";
+
+pub(crate) fn encode_row_ref(row: UntrackedStateRowRef<'_>) -> Result<Vec<u8>, LixError> {
+    let entity_id = row.entity_id.as_json_array_text().map_err(|error| {
+        LixError::unknown(format!(
+            "failed to encode untracked-state entity identity: {error}"
+        ))
+    })?;
+
+    let mut builder = flatbuffers::FlatBufferBuilder::with_capacity(256);
+    let entity_id = builder.create_string(&entity_id);
+    let schema_key = builder.create_string(row.schema_key);
+    let file_id = row.file_id.map(|value| builder.create_string(value));
+    let snapshot_content = row
+        .snapshot_content
+        .map(|value| builder.create_string(value));
+    let metadata = row.metadata.map(|value| builder.create_string(value));
+    let created_at = builder.create_string(row.created_at);
+    let updated_at = builder.create_string(row.updated_at);
+    let version_id = builder.create_string(row.version_id);
+
+    let root = flatbuffer::create_untracked_state_row(
+        &mut builder,
+        &flatbuffer::UntrackedStateRowArgs {
+            entity_id,
+            schema_key,
+            file_id,
+            snapshot_content,
+            metadata,
+            created_at,
+            updated_at,
+            global: row.global,
+            version_id,
+        },
+    );
+    builder.finish(root, Some(UNTRACKED_STATE_FILE_IDENTIFIER));
+    Ok(builder.finished_data().to_vec())
+}
+
+pub(crate) fn decode_row(bytes: &[u8]) -> Result<UntrackedStateRow, LixError> {
+    if bytes.len() < flatbuffers::SIZE_UOFFSET + flatbuffers::FILE_IDENTIFIER_LENGTH
+        || !flatbuffers::buffer_has_identifier(bytes, UNTRACKED_STATE_FILE_IDENTIFIER, false)
+    {
+        return Err(LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            "failed to decode untracked-state row: invalid FlatBuffers file identifier",
+        ));
+    }
+
+    let row = flatbuffer::root_as_untracked_state_row(bytes).map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("failed to decode untracked-state row: {error}"),
+        )
+    })?;
+
+    let entity_id = required_str(row.entity_id(), "entity_id")?;
+    let entity_id = EntityIdentity::from_json_array_text(entity_id).map_err(|error| {
+        LixError::unknown(format!(
+            "failed to decode untracked-state entity identity: {error}"
+        ))
+    })?;
+
+    Ok(UntrackedStateRow {
+        entity_id,
+        schema_key: required_str(row.schema_key(), "schema_key")?.to_string(),
+        file_id: row.file_id().map(ToString::to_string),
+        snapshot_content: row.snapshot_content().map(ToString::to_string),
+        metadata: row.metadata().map(ToString::to_string),
+        created_at: required_str(row.created_at(), "created_at")?.to_string(),
+        updated_at: required_str(row.updated_at(), "updated_at")?.to_string(),
+        global: row.global(),
+        version_id: required_str(row.version_id(), "version_id")?.to_string(),
+    })
+}
+
+fn required_str<'a>(value: Option<&'a str>, field: &str) -> Result<&'a str, LixError> {
+    value.ok_or_else(|| {
+        LixError::new(
+            "LIX_ERROR_UNKNOWN",
+            format!("failed to decode untracked-state row: missing required field `{field}`"),
+        )
+    })
+}
+
+mod flatbuffer {
+    #[derive(Copy, Clone, PartialEq)]
+    pub(super) struct UntrackedStateRow<'a> {
+        table: flatbuffers::Table<'a>,
+    }
+
+    impl<'a> flatbuffers::Follow<'a> for UntrackedStateRow<'a> {
+        type Inner = UntrackedStateRow<'a>;
+
+        #[inline]
+        unsafe fn follow(buf: &'a [u8], loc: usize) -> Self::Inner {
+            Self {
+                table: unsafe { flatbuffers::Table::new(buf, loc) },
+            }
+        }
+    }
+
+    impl<'a> UntrackedStateRow<'a> {
+        const VT_ENTITY_ID: flatbuffers::VOffsetT = 4;
+        const VT_SCHEMA_KEY: flatbuffers::VOffsetT = 6;
+        const VT_FILE_ID: flatbuffers::VOffsetT = 8;
+        const VT_SNAPSHOT_CONTENT: flatbuffers::VOffsetT = 10;
+        const VT_METADATA: flatbuffers::VOffsetT = 12;
+        const VT_CREATED_AT: flatbuffers::VOffsetT = 14;
+        const VT_UPDATED_AT: flatbuffers::VOffsetT = 16;
+        const VT_GLOBAL: flatbuffers::VOffsetT = 18;
+        const VT_VERSION_ID: flatbuffers::VOffsetT = 20;
+
+        #[inline]
+        pub(super) fn entity_id(&self) -> Option<&'a str> {
+            unsafe {
+                self.table
+                    .get::<flatbuffers::ForwardsUOffset<&str>>(Self::VT_ENTITY_ID, None)
+            }
+        }
+
+        #[inline]
+        pub(super) fn schema_key(&self) -> Option<&'a str> {
+            unsafe {
+                self.table
+                    .get::<flatbuffers::ForwardsUOffset<&str>>(Self::VT_SCHEMA_KEY, None)
+            }
+        }
+
+        #[inline]
+        pub(super) fn file_id(&self) -> Option<&'a str> {
+            unsafe {
+                self.table
+                    .get::<flatbuffers::ForwardsUOffset<&str>>(Self::VT_FILE_ID, None)
+            }
+        }
+
+        #[inline]
+        pub(super) fn snapshot_content(&self) -> Option<&'a str> {
+            unsafe {
+                self.table
+                    .get::<flatbuffers::ForwardsUOffset<&str>>(Self::VT_SNAPSHOT_CONTENT, None)
+            }
+        }
+
+        #[inline]
+        pub(super) fn metadata(&self) -> Option<&'a str> {
+            unsafe {
+                self.table
+                    .get::<flatbuffers::ForwardsUOffset<&str>>(Self::VT_METADATA, None)
+            }
+        }
+
+        pub(super) fn created_at(&self) -> Option<&'a str> {
+            unsafe {
+                self.table
+                    .get::<flatbuffers::ForwardsUOffset<&str>>(Self::VT_CREATED_AT, None)
+            }
+        }
+
+        #[inline]
+        pub(super) fn updated_at(&self) -> Option<&'a str> {
+            unsafe {
+                self.table
+                    .get::<flatbuffers::ForwardsUOffset<&str>>(Self::VT_UPDATED_AT, None)
+            }
+        }
+
+        #[inline]
+        pub(super) fn global(&self) -> bool {
+            unsafe { self.table.get::<bool>(Self::VT_GLOBAL, Some(false)) }.unwrap_or(false)
+        }
+
+        #[inline]
+        pub(super) fn version_id(&self) -> Option<&'a str> {
+            unsafe {
+                self.table
+                    .get::<flatbuffers::ForwardsUOffset<&str>>(Self::VT_VERSION_ID, None)
+            }
+        }
+    }
+
+    impl flatbuffers::Verifiable for UntrackedStateRow<'_> {
+        #[inline]
+        fn run_verifier(
+            verifier: &mut flatbuffers::Verifier,
+            position: usize,
+        ) -> Result<(), flatbuffers::InvalidFlatbuffer> {
+            verifier
+                .visit_table(position)?
+                .visit_field::<flatbuffers::ForwardsUOffset<&str>>(
+                    "entity_id",
+                    Self::VT_ENTITY_ID,
+                    true,
+                )?
+                .visit_field::<flatbuffers::ForwardsUOffset<&str>>(
+                    "schema_key",
+                    Self::VT_SCHEMA_KEY,
+                    true,
+                )?
+                .visit_field::<flatbuffers::ForwardsUOffset<&str>>(
+                    "file_id",
+                    Self::VT_FILE_ID,
+                    false,
+                )?
+                .visit_field::<flatbuffers::ForwardsUOffset<&str>>(
+                    "snapshot_content",
+                    Self::VT_SNAPSHOT_CONTENT,
+                    false,
+                )?
+                .visit_field::<flatbuffers::ForwardsUOffset<&str>>(
+                    "metadata",
+                    Self::VT_METADATA,
+                    false,
+                )?
+                .visit_field::<flatbuffers::ForwardsUOffset<&str>>(
+                    "created_at",
+                    Self::VT_CREATED_AT,
+                    true,
+                )?
+                .visit_field::<flatbuffers::ForwardsUOffset<&str>>(
+                    "updated_at",
+                    Self::VT_UPDATED_AT,
+                    true,
+                )?
+                .visit_field::<bool>("global", Self::VT_GLOBAL, false)?
+                .visit_field::<flatbuffers::ForwardsUOffset<&str>>(
+                    "version_id",
+                    Self::VT_VERSION_ID,
+                    true,
+                )?
+                .finish();
+            Ok(())
+        }
+    }
+
+    pub(super) struct UntrackedStateRowArgs<'a> {
+        pub(super) entity_id: flatbuffers::WIPOffset<&'a str>,
+        pub(super) schema_key: flatbuffers::WIPOffset<&'a str>,
+        pub(super) file_id: Option<flatbuffers::WIPOffset<&'a str>>,
+        pub(super) snapshot_content: Option<flatbuffers::WIPOffset<&'a str>>,
+        pub(super) metadata: Option<flatbuffers::WIPOffset<&'a str>>,
+        pub(super) created_at: flatbuffers::WIPOffset<&'a str>,
+        pub(super) updated_at: flatbuffers::WIPOffset<&'a str>,
+        pub(super) global: bool,
+        pub(super) version_id: flatbuffers::WIPOffset<&'a str>,
+    }
+
+    pub(super) fn create_untracked_state_row<'bldr: 'args, 'args: 'mut_bldr, 'mut_bldr>(
+        builder: &'mut_bldr mut flatbuffers::FlatBufferBuilder<'bldr>,
+        args: &'args UntrackedStateRowArgs<'args>,
+    ) -> flatbuffers::WIPOffset<UntrackedStateRow<'bldr>> {
+        let start = builder.start_table();
+        builder.push_slot_always::<flatbuffers::WIPOffset<_>>(
+            UntrackedStateRow::VT_VERSION_ID,
+            args.version_id,
+        );
+        builder.push_slot::<bool>(UntrackedStateRow::VT_GLOBAL, args.global, false);
+        builder.push_slot_always::<flatbuffers::WIPOffset<_>>(
+            UntrackedStateRow::VT_UPDATED_AT,
+            args.updated_at,
+        );
+        builder.push_slot_always::<flatbuffers::WIPOffset<_>>(
+            UntrackedStateRow::VT_CREATED_AT,
+            args.created_at,
+        );
+        if let Some(metadata) = args.metadata {
+            builder.push_slot_always::<flatbuffers::WIPOffset<_>>(
+                UntrackedStateRow::VT_METADATA,
+                metadata,
+            );
+        }
+        if let Some(snapshot_content) = args.snapshot_content {
+            builder.push_slot_always::<flatbuffers::WIPOffset<_>>(
+                UntrackedStateRow::VT_SNAPSHOT_CONTENT,
+                snapshot_content,
+            );
+        }
+        if let Some(file_id) = args.file_id {
+            builder.push_slot_always::<flatbuffers::WIPOffset<_>>(
+                UntrackedStateRow::VT_FILE_ID,
+                file_id,
+            );
+        }
+        builder.push_slot_always::<flatbuffers::WIPOffset<_>>(
+            UntrackedStateRow::VT_SCHEMA_KEY,
+            args.schema_key,
+        );
+        builder.push_slot_always::<flatbuffers::WIPOffset<_>>(
+            UntrackedStateRow::VT_ENTITY_ID,
+            args.entity_id,
+        );
+        let offset = builder.end_table(start);
+        flatbuffers::WIPOffset::new(offset.value())
+    }
+
+    #[inline]
+    pub(super) fn root_as_untracked_state_row(
+        bytes: &[u8],
+    ) -> Result<UntrackedStateRow<'_>, flatbuffers::InvalidFlatbuffer> {
+        flatbuffers::root::<UntrackedStateRow>(bytes)
+    }
+}

package/dist-engine-src/src/untracked_state/context.rs

@@ -0,0 +1,98 @@
+use crate::storage::{StorageReader, StorageWriteSet};
+use crate::untracked_state::{
+    MaterializedUntrackedStateRow, UntrackedStateIdentity, UntrackedStateIdentityRef,
+    UntrackedStateRowRef, UntrackedStateRowRequest, UntrackedStateScanRequest,
+};
+use crate::LixError;
+
+/// Durable local overlay excluded from changelog and commit membership.
+///
+/// Untracked state is not change-controlled, but it is still durable local
+/// state. It is read alongside tracked live state and can override tracked rows
+/// with the same identity.
+#[derive(Clone, Copy)]
+pub(crate) struct UntrackedStateContext;
+
+impl UntrackedStateContext {
+    pub(crate) fn new() -> Self {
+        Self
+    }
+
+    /// Creates a reader over a caller-provided KV store.
+    ///
+    /// The caller decides which KV store supplies visibility for the read.
+    pub(crate) fn reader<S>(&self, store: S) -> UntrackedStateStoreReader<S>
+    where
+        S: StorageReader,
+    {
+        UntrackedStateStoreReader { store }
+    }
+
+    /// Creates a writer over a transaction-local storage write set.
+    ///
+    /// The context never opens its own transaction; the caller applies the
+    /// write set to choose the durable commit or rollback boundary.
+    pub(crate) fn writer<'a>(&self, writes: &'a mut StorageWriteSet) -> UntrackedStateWriter<'a> {
+        UntrackedStateWriter { writes }
+    }
+}
+
+/// Store-backed untracked-state reader created by `UntrackedStateContext`.
+pub(crate) struct UntrackedStateStoreReader<S> {
+    store: S,
+}
+
+impl<S> UntrackedStateStoreReader<S>
+where
+    S: StorageReader,
+{
+    pub(crate) async fn scan_rows(
+        &mut self,
+        request: &UntrackedStateScanRequest,
+    ) -> Result<Vec<MaterializedUntrackedStateRow>, LixError> {
+        crate::untracked_state::storage::scan_rows(&mut self.store, request).await
+    }
+
+    pub(crate) async fn load_row(
+        &mut self,
+        request: &UntrackedStateRowRequest,
+    ) -> Result<Option<MaterializedUntrackedStateRow>, LixError> {
+        crate::untracked_state::storage::load_row(&mut self.store, request).await
+    }
+
+    pub(crate) async fn existing_identities<'a, I>(
+        &mut self,
+        identities: I,
+    ) -> Result<Vec<UntrackedStateIdentity>, LixError>
+    where
+        I: IntoIterator<Item = UntrackedStateIdentityRef<'a>>,
+    {
+        crate::untracked_state::storage::existing_identities(&mut self.store, identities).await
+    }
+}
+
+/// Untracked-state writer over a transaction-local storage write set.
+pub(crate) struct UntrackedStateWriter<'a> {
+    writes: &'a mut StorageWriteSet,
+}
+
+impl UntrackedStateWriter<'_> {
+    /// Stages the latest untracked rows for their identities.
+    ///
+    /// A row with `snapshot_content = None` is treated as removal because
+    /// untracked state keeps only the current local value, not tombstones.
+    pub(crate) fn stage_rows<'a, I>(&mut self, rows: I) -> Result<(), LixError>
+    where
+        I: IntoIterator<Item = UntrackedStateRowRef<'a>>,
+    {
+        crate::untracked_state::storage::stage_rows(self.writes, rows)
+    }
+
+    /// Removes untracked rows by exact identity.
+    pub(crate) fn stage_delete_rows<'a, I>(&mut self, identities: I)
+    where
+        I: IntoIterator<Item = UntrackedStateIdentityRef<'a>>,
+    {
+        crate::untracked_state::storage::stage_delete_rows(self.writes, identities)
+    }
+}

package/dist-engine-src/src/untracked_state/materialization.rs

@@ -0,0 +1,63 @@
+use crate::untracked_state::{MaterializedUntrackedStateRow, UntrackedStateRow};
+use crate::{parse_row_metadata, LixError};
+
+pub(crate) fn materialize_row(
+    row: UntrackedStateRow,
+    projection: &UntrackedMaterializationProjection,
+) -> Result<MaterializedUntrackedStateRow, LixError> {
+    let deleted = row.snapshot_content.is_none();
+    let snapshot_content = if projection.snapshot_content {
+        row.snapshot_content
+    } else {
+        None
+    };
+    let metadata = if projection.metadata {
+        load_optional_metadata(row.metadata)?
+    } else {
+        None
+    };
+    Ok(MaterializedUntrackedStateRow {
+        entity_id: row.entity_id,
+        schema_key: row.schema_key,
+        file_id: row.file_id,
+        snapshot_content,
+        metadata,
+        deleted,
+        created_at: row.created_at,
+        updated_at: row.updated_at,
+        global: row.global,
+        version_id: row.version_id,
+    })
+}
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) struct UntrackedMaterializationProjection {
+    pub(crate) snapshot_content: bool,
+    pub(crate) metadata: bool,
+}
+
+impl UntrackedMaterializationProjection {
+    pub(crate) fn full() -> Self {
+        Self {
+            snapshot_content: true,
+            metadata: true,
+        }
+    }
+
+    pub(crate) fn from_columns(columns: &[String]) -> Self {
+        if columns.is_empty() {
+            return Self::full();
+        }
+        Self {
+            snapshot_content: columns.iter().any(|column| column == "snapshot_content"),
+            metadata: columns.iter().any(|column| column == "metadata"),
+        }
+    }
+}
+
+fn load_optional_metadata(metadata: Option<String>) -> Result<Option<String>, LixError> {
+    let Some(json) = metadata else {
+        return Ok(None);
+    };
+    parse_row_metadata(&json, "untracked_state metadata").map(Some)
+}

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

@@ -0,0 +1,15 @@
+mod codec;
+mod context;
+mod materialization;
+pub(crate) mod storage;
+mod types;
+
+#[allow(unused_imports)]
+pub(crate) use context::{UntrackedStateContext, UntrackedStateStoreReader, UntrackedStateWriter};
+pub(crate) use materialization::{materialize_row, UntrackedMaterializationProjection};
+#[allow(unused_imports)]
+pub(crate) use types::{
+    MaterializedUntrackedStateRow, UntrackedStateFilter, UntrackedStateIdentity,
+    UntrackedStateIdentityRef, UntrackedStateProjection, UntrackedStateRow, UntrackedStateRowRef,
+    UntrackedStateRowRequest, UntrackedStateScanRequest,
+};