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

package/dist-engine-src/src/common/identity.rs

@@ -0,0 +1,145 @@
+use std::borrow::Borrow;
+use std::fmt;
+use std::ops::Deref;
+
+use crate::LixError;
+use serde::{Deserialize, Deserializer, Serialize, Serializer};
+
+macro_rules! canonical_identity_type {
+    ($name:ident, $label:literal) => {
+        #[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
+        pub struct $name(String);
+
+        impl $name {
+            pub fn new(value: impl Into<String>) -> Result<Self, LixError> {
+                let value = value.into();
+                validate_non_empty_identity_value($label, value).map(Self)
+            }
+
+            pub fn as_str(&self) -> &str {
+                &self.0
+            }
+
+            pub fn into_inner(self) -> String {
+                self.0
+            }
+        }
+
+        impl TryFrom<String> for $name {
+            type Error = LixError;
+
+            fn try_from(value: String) -> Result<Self, Self::Error> {
+                Self::new(value)
+            }
+        }
+
+        impl TryFrom<&str> for $name {
+            type Error = LixError;
+
+            fn try_from(value: &str) -> Result<Self, Self::Error> {
+                Self::new(value)
+            }
+        }
+
+        impl From<$name> for String {
+            fn from(value: $name) -> Self {
+                value.0
+            }
+        }
+
+        impl Deref for $name {
+            type Target = str;
+
+            fn deref(&self) -> &Self::Target {
+                self.0.as_str()
+            }
+        }
+
+        impl AsRef<str> for $name {
+            fn as_ref(&self) -> &str {
+                self.0.as_str()
+            }
+        }
+
+        impl Borrow<str> for $name {
+            fn borrow(&self) -> &str {
+                self.0.as_str()
+            }
+        }
+
+        impl fmt::Display for $name {
+            fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+                self.0.fmt(f)
+            }
+        }
+
+        impl PartialEq<&str> for $name {
+            fn eq(&self, other: &&str) -> bool {
+                self.0 == *other
+            }
+        }
+
+        impl PartialEq<$name> for &str {
+            fn eq(&self, other: &$name) -> bool {
+                *self == other.0
+            }
+        }
+
+        impl Serialize for $name {
+            fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
+            where
+                S: Serializer,
+            {
+                serializer.serialize_str(&self.0)
+            }
+        }
+
+        impl<'de> Deserialize<'de> for $name {
+            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+            where
+                D: Deserializer<'de>,
+            {
+                let value = String::deserialize(deserializer)?;
+                Self::new(value).map_err(serde::de::Error::custom)
+            }
+        }
+    };
+}
+
+canonical_identity_type!(EntityId, "entity_id");
+canonical_identity_type!(FileId, "file_id");
+canonical_identity_type!(VersionId, "version_id");
+canonical_identity_type!(CanonicalSchemaKey, "schema_key");
+canonical_identity_type!(CanonicalPluginKey, "plugin_key");
+
+pub(crate) fn validate_non_empty_identity_value(
+    label: &str,
+    value: impl Into<String>,
+) -> Result<String, LixError> {
+    let value = value.into();
+    if value.is_empty() {
+        return Err(LixError::new(
+            LixError::CODE_INVALID_PARAM,
+            format!("{label} must be non-empty"),
+        ));
+    }
+    Ok(value)
+}
+
+pub(crate) fn json_pointer_get<'a>(
+    value: &'a serde_json::Value,
+    pointer: &[String],
+) -> Option<&'a serde_json::Value> {
+    let mut current = value;
+    for segment in pointer {
+        match current {
+            serde_json::Value::Object(object) => current = object.get(segment)?,
+            serde_json::Value::Array(array) => {
+                let index = segment.parse::<usize>().ok()?;
+                current = array.get(index)?;
+            }
+            _ => return None,
+        }
+    }
+    Some(current)
+}

package/dist-engine-src/src/common/json_pointer.rs

@@ -0,0 +1,67 @@
+use crate::LixError;
+
+pub(crate) fn parse_json_pointer(pointer: &str) -> Result<Vec<String>, LixError> {
+    if pointer.is_empty() {
+        return Ok(Vec::new());
+    }
+    if !pointer.starts_with('/') {
+        return Err(LixError::new(
+            LixError::CODE_SCHEMA_DEFINITION,
+            format!("invalid JSON pointer '{pointer}'"),
+        ));
+    }
+    pointer[1..]
+        .split('/')
+        .map(decode_json_pointer_segment)
+        .collect()
+}
+
+pub(crate) fn format_json_pointer(segments: &[String]) -> String {
+    if segments.is_empty() {
+        return String::new();
+    }
+    format!(
+        "/{}",
+        segments
+            .iter()
+            .map(|segment| segment.replace('~', "~0").replace('/', "~1"))
+            .collect::<Vec<_>>()
+            .join("/")
+    )
+}
+
+pub(crate) fn top_level_property_name(pointer: &str) -> Result<Option<String>, LixError> {
+    if pointer.is_empty() {
+        return Ok(None);
+    }
+    if !pointer.starts_with('/') {
+        return Err(LixError::new(
+            LixError::CODE_SCHEMA_DEFINITION,
+            format!("invalid JSON pointer '{pointer}'"),
+        ));
+    }
+    let segment = pointer[1..].split('/').next().unwrap_or_default();
+    Ok(Some(decode_json_pointer_segment(segment)?))
+}
+
+fn decode_json_pointer_segment(segment: &str) -> Result<String, LixError> {
+    let mut out = String::new();
+    let mut chars = segment.chars();
+    while let Some(ch) = chars.next() {
+        if ch != '~' {
+            out.push(ch);
+            continue;
+        }
+        match chars.next() {
+            Some('0') => out.push('~'),
+            Some('1') => out.push('/'),
+            _ => {
+                return Err(LixError::new(
+                    LixError::CODE_SCHEMA_DEFINITION,
+                    "invalid JSON pointer escape",
+                ))
+            }
+        }
+    }
+    Ok(out)
+}

package/dist-engine-src/src/common/metadata.rs

@@ -0,0 +1,40 @@
+use crate::LixError;
+
+pub(crate) fn parse_row_metadata(
+    value: &str,
+    context: impl AsRef<str>,
+) -> Result<String, LixError> {
+    let metadata = parse_row_metadata_value(value, context)?;
+    Ok(serde_json::to_string(&metadata).expect("serde_json::Value metadata serializes"))
+}
+
+pub(crate) fn parse_row_metadata_value(
+    value: &str,
+    context: impl AsRef<str>,
+) -> Result<serde_json::Value, LixError> {
+    let metadata = serde_json::from_str::<serde_json::Value>(value).map_err(|error| {
+        LixError::new(
+            "LIX_ERROR_INVALID_JSON",
+            format!("{} metadata is invalid JSON: {error}", context.as_ref()),
+        )
+    })?;
+    validate_row_metadata(&metadata, context)?;
+    Ok(metadata)
+}
+
+pub(crate) fn validate_row_metadata(
+    metadata: &serde_json::Value,
+    context: impl AsRef<str>,
+) -> Result<(), LixError> {
+    if metadata.is_object() {
+        return Ok(());
+    }
+    Err(LixError::new(
+        LixError::CODE_SCHEMA_VALIDATION,
+        format!("{} metadata must be a JSON object", context.as_ref()),
+    ))
+}
+
+pub(crate) fn serialize_row_metadata(metadata: &String) -> String {
+    metadata.clone()
+}

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

@@ -0,0 +1,23 @@
+pub(crate) mod error;
+pub(crate) mod fingerprint;
+pub(crate) mod fs_path;
+pub(crate) mod identity;
+pub(crate) mod json_pointer;
+pub(crate) mod metadata;
+pub(crate) mod types;
+pub(crate) mod wire;
+
+pub use error::LixError;
+pub(crate) use fingerprint::stable_content_fingerprint_hex;
+pub(crate) use fs_path::{
+    directory_ancestor_paths, directory_name_from_path, normalize_directory_path,
+    normalize_path_segment, parent_directory_path, ParsedFilePath,
+};
+pub(crate) use identity::{json_pointer_get, validate_non_empty_identity_value};
+pub use identity::{CanonicalPluginKey, CanonicalSchemaKey, EntityId, FileId, VersionId};
+pub(crate) use json_pointer::{format_json_pointer, parse_json_pointer, top_level_property_name};
+pub(crate) use metadata::{
+    parse_row_metadata, parse_row_metadata_value, serialize_row_metadata, validate_row_metadata,
+};
+pub use types::{LixNotice, NullableKeyFilter, SqlQueryResult, Value, WriteReceipt};
+pub use wire::{WireQueryResult, WireValue};

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

@@ -0,0 +1,105 @@
+use std::ops::Deref;
+
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub enum Value {
+    Null,
+    Boolean(bool),
+    Integer(i64),
+    Real(f64),
+    Text(String),
+    Json(serde_json::Value),
+    Blob(Vec<u8>),
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub enum NullableKeyFilter<T> {
+    Any,
+    Null,
+    Value(T),
+}
+
+impl<T> Default for NullableKeyFilter<T> {
+    fn default() -> Self {
+        Self::Any
+    }
+}
+
+impl<T> NullableKeyFilter<T> {
+    pub fn is_any(&self) -> bool {
+        matches!(self, Self::Any)
+    }
+
+    pub fn as_value(&self) -> Option<&T> {
+        match self {
+            Self::Value(value) => Some(value),
+            Self::Any | Self::Null => None,
+        }
+    }
+
+    pub fn as_ref(&self) -> NullableKeyFilter<&T> {
+        match self {
+            Self::Any => NullableKeyFilter::Any,
+            Self::Null => NullableKeyFilter::Null,
+            Self::Value(value) => NullableKeyFilter::Value(value),
+        }
+    }
+
+    pub fn from_nullable(value: Option<T>) -> Self {
+        match value {
+            Some(value) => Self::Value(value),
+            None => Self::Null,
+        }
+    }
+}
+
+impl<T> NullableKeyFilter<T>
+where
+    T: Deref,
+{
+    pub fn as_deref(&self) -> NullableKeyFilter<&T::Target> {
+        match self {
+            Self::Any => NullableKeyFilter::Any,
+            Self::Null => NullableKeyFilter::Null,
+            Self::Value(value) => NullableKeyFilter::Value(value.deref()),
+        }
+    }
+}
+
+impl<T: PartialEq> NullableKeyFilter<T> {
+    pub fn matches(&self, candidate: Option<&T>) -> bool {
+        match self {
+            Self::Any => true,
+            Self::Null => candidate.is_none(),
+            Self::Value(expected) => candidate == Some(expected),
+        }
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct SqlQueryResult {
+    pub rows: Vec<Vec<Value>>,
+    #[serde(default)]
+    pub columns: Vec<String>,
+    #[serde(default)]
+    pub notices: Vec<LixNotice>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+pub struct LixNotice {
+    pub code: String,
+    pub message: String,
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub hint: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, Default)]
+pub struct WriteReceipt {
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub state_commit_sequence: Option<u64>,
+}
+
+impl WriteReceipt {
+    pub fn is_empty(&self) -> bool {
+        self.state_commit_sequence.is_none()
+    }
+}

package/dist-engine-src/src/common/wire.rs

@@ -0,0 +1,222 @@
+use crate::{LixError, LixNotice, SqlQueryResult, Value};
+use base64::Engine as _;
+use serde::{Deserialize, Serialize};
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+#[serde(tag = "kind", rename_all = "lowercase")]
+pub enum WireValue {
+    Null { value: () },
+    Bool { value: bool },
+    Int { value: i64 },
+    Float { value: f64 },
+    Text { value: String },
+    Json { value: serde_json::Value },
+    Blob { base64: String },
+}
+
+#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
+pub struct WireQueryResult {
+    pub rows: Vec<Vec<WireValue>>,
+    #[serde(default)]
+    pub columns: Vec<String>,
+    #[serde(default)]
+    pub notices: Vec<LixNotice>,
+}
+
+impl WireValue {
+    pub fn try_from_engine(value: &Value) -> Result<Self, LixError> {
+        match value {
+            Value::Null => Ok(Self::Null { value: () }),
+            Value::Boolean(value) => Ok(Self::Bool { value: *value }),
+            Value::Integer(value) => Ok(Self::Int { value: *value }),
+            Value::Real(value) => {
+                if !value.is_finite() {
+                    return Err(LixError {
+                        code: "LIX_ERROR_UNKNOWN".to_string(),
+                        message: "cannot encode non-finite float value to wire format".to_string(),
+                        hint: None,
+                        details: None,
+                    });
+                }
+                Ok(Self::Float { value: *value })
+            }
+            Value::Text(value) => Ok(Self::Text {
+                value: value.clone(),
+            }),
+            Value::Json(value) => Ok(Self::Json {
+                value: value.clone(),
+            }),
+            Value::Blob(value) => Ok(Self::Blob {
+                base64: base64::engine::general_purpose::STANDARD.encode(value),
+            }),
+        }
+    }
+
+    pub fn try_into_engine(self) -> Result<Value, LixError> {
+        match self {
+            Self::Null { .. } => Ok(Value::Null),
+            Self::Bool { value } => Ok(Value::Boolean(value)),
+            Self::Int { value } => Ok(Value::Integer(value)),
+            Self::Float { value } => {
+                if !value.is_finite() {
+                    return Err(LixError {
+                        code: "LIX_ERROR_UNKNOWN".to_string(),
+                        message: "cannot decode non-finite float value from wire format"
+                            .to_string(),
+                        hint: None,
+                        details: None,
+                    });
+                }
+                Ok(Value::Real(value))
+            }
+            Self::Text { value } => Ok(Value::Text(value)),
+            Self::Json { value } => Ok(Value::Json(value)),
+            Self::Blob { base64 } => {
+                let decoded = base64::engine::general_purpose::STANDARD
+                    .decode(base64.as_bytes())
+                    .map_err(|error| LixError {
+                        code: "LIX_ERROR_UNKNOWN".to_string(),
+                        message: format!("failed to decode wire blob base64: {error}"),
+                        hint: None,
+                        details: None,
+                    })?;
+                Ok(Value::Blob(decoded))
+            }
+        }
+    }
+}
+
+impl WireQueryResult {
+    pub fn try_from_engine(result: &SqlQueryResult) -> Result<Self, LixError> {
+        let mut rows = Vec::with_capacity(result.rows.len());
+        for row in &result.rows {
+            let mut wire_row = Vec::with_capacity(row.len());
+            for value in row {
+                wire_row.push(WireValue::try_from_engine(value)?);
+            }
+            rows.push(wire_row);
+        }
+        Ok(Self {
+            rows,
+            columns: result.columns.clone(),
+            notices: result.notices.clone(),
+        })
+    }
+
+    pub fn try_into_engine(self) -> Result<SqlQueryResult, LixError> {
+        let mut rows = Vec::with_capacity(self.rows.len());
+        for row in self.rows {
+            let mut engine_row = Vec::with_capacity(row.len());
+            for value in row {
+                engine_row.push(value.try_into_engine()?);
+            }
+            rows.push(engine_row);
+        }
+        Ok(SqlQueryResult {
+            rows,
+            columns: self.columns,
+            notices: self.notices,
+        })
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::{WireQueryResult, WireValue};
+    use crate::{LixNotice, SqlQueryResult, Value};
+    use serde_json::json;
+
+    #[test]
+    fn value_roundtrip_preserves_all_variants() {
+        let original = vec![
+            Value::Null,
+            Value::Boolean(true),
+            Value::Integer(42),
+            Value::Real(1.5),
+            Value::Text("hello".to_string()),
+            Value::Json(json!({"hello": "world"})),
+            Value::Blob(vec![1, 2, 3]),
+        ];
+
+        for value in original {
+            let wire = WireValue::try_from_engine(&value).expect("to wire should succeed");
+            let roundtrip = wire
+                .try_into_engine()
+                .expect("from wire to engine should succeed");
+            assert_eq!(roundtrip, value);
+        }
+    }
+
+    #[test]
+    fn query_result_roundtrip_preserves_rows_and_columns() {
+        let original = SqlQueryResult {
+            rows: vec![
+                vec![
+                    Value::Integer(1),
+                    Value::Text("a".to_string()),
+                    Value::Blob(vec![0x41, 0x42]),
+                ],
+                vec![Value::Null, Value::Boolean(false), Value::Real(2.5)],
+            ],
+            columns: vec!["i".to_string(), "t".to_string(), "b".to_string()],
+            notices: vec![LixNotice {
+                code: "LIX_TEST_NOTICE".to_string(),
+                message: "test notice".to_string(),
+                hint: Some("test hint".to_string()),
+            }],
+        };
+
+        let wire = WireQueryResult::try_from_engine(&original).expect("to wire should succeed");
+        let roundtrip = wire
+            .try_into_engine()
+            .expect("from wire to engine should succeed");
+        assert_eq!(roundtrip, original);
+    }
+
+    #[test]
+    fn canonical_json_uses_lowercase_kinds_only() {
+        let wire = WireQueryResult {
+            rows: vec![vec![
+                WireValue::Null { value: () },
+                WireValue::Bool { value: true },
+                WireValue::Int { value: 1 },
+                WireValue::Float { value: 1.5 },
+                WireValue::Text {
+                    value: "hello".to_string(),
+                },
+                WireValue::Json {
+                    value: json!({"hello": "world"}),
+                },
+                WireValue::Blob {
+                    base64: "AQI=".to_string(),
+                },
+            ]],
+            columns: vec!["a".to_string()],
+            notices: Vec::new(),
+        };
+
+        let serialized =
+            serde_json::to_string(&wire).expect("wire query result should serialize to json");
+        assert!(serialized.contains("\"kind\":\"null\""));
+        assert!(serialized.contains("\"kind\":\"bool\""));
+        assert!(serialized.contains("\"kind\":\"int\""));
+        assert!(serialized.contains("\"kind\":\"float\""));
+        assert!(serialized.contains("\"kind\":\"text\""));
+        assert!(serialized.contains("\"kind\":\"json\""));
+        assert!(serialized.contains("\"kind\":\"blob\""));
+        assert!(!serialized.contains("\"kind\":\"Null\""));
+        assert!(!serialized.contains("\"kind\":\"Bool\""));
+        assert!(!serialized.contains("\"kind\":\"Integer\""));
+        assert!(!serialized.contains("\"kind\":\"Real\""));
+        assert!(!serialized.contains("\"kind\":\"Text\""));
+        assert!(!serialized.contains("\"kind\":\"Json\""));
+        assert!(!serialized.contains("\"kind\":\"Blob\""));
+    }
+
+    #[test]
+    fn null_shape_is_explicitly_canonical() {
+        let value = WireValue::Null { value: () };
+        let json = serde_json::to_value(value).expect("wire value should serialize");
+        assert_eq!(json, json!({ "kind": "null", "value": null }));
+    }
+}