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

package/dist-engine-src/src/sql2/public_bind/table.rs

@@ -0,0 +1,168 @@
+use std::collections::{BTreeMap, BTreeSet};
+
+use serde_json::Value as JsonValue;
+
+use crate::schema::schema_key_from_definition;
+use crate::LixError;
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub(crate) enum Capability {
+    Allowed,
+    ReadOnly(&'static str),
+    Unsupported(&'static str),
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct ColumnContract {
+    pub(crate) writable: bool,
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct TableContract {
+    pub(crate) insert: Capability,
+    pub(crate) update: Capability,
+    pub(crate) delete: Capability,
+    pub(crate) columns: BTreeMap<String, ColumnContract>,
+}
+
+impl TableContract {
+    pub(crate) fn operation(&self, operation: super::DmlOperation) -> Capability {
+        match operation {
+            super::DmlOperation::Insert => self.insert,
+            super::DmlOperation::Update => self.update,
+            super::DmlOperation::Delete => self.delete,
+        }
+    }
+
+    pub(crate) fn column(&self, column: &str) -> Option<&ColumnContract> {
+        self.columns.get(column)
+    }
+}
+
+#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)]
+pub(crate) struct PublicSurface {
+    name: String,
+}
+
+impl PublicSurface {
+    pub(crate) fn named(name: impl Into<String>) -> Self {
+        Self {
+            name: name.into().to_ascii_lowercase(),
+        }
+    }
+
+    pub(crate) fn name(&self) -> &str {
+        &self.name
+    }
+}
+
+#[derive(Clone, Debug)]
+pub(crate) struct PublicTableContracts {
+    contracts: BTreeMap<String, TableContract>,
+}
+
+impl PublicTableContracts {
+    pub(crate) fn new(visible_schemas: &[JsonValue]) -> Result<Self, LixError> {
+        let mut contracts = builtin_contracts();
+        for schema in visible_schemas {
+            let schema_key = schema_key_from_definition(schema)?.schema_key;
+            contracts.insert(
+                format!("{}_history", schema_key.to_ascii_lowercase()),
+                history_contract(),
+            );
+        }
+        Ok(Self { contracts })
+    }
+
+    pub(crate) fn get(&self, surface: &PublicSurface) -> Option<&TableContract> {
+        self.contracts.get(surface.name())
+    }
+}
+
+fn builtin_contracts() -> BTreeMap<String, TableContract> {
+    let mut contracts = BTreeMap::new();
+
+    for table in [
+        "lix_change",
+        "lix_commit",
+        "lix_commit_by_version",
+        "lix_commit_edge",
+        "lix_commit_edge_by_version",
+        "lix_change_set",
+        "lix_change_set_by_version",
+        "lix_change_set_element",
+        "lix_change_set_element_by_version",
+    ] {
+        contracts.insert(table.to_string(), commit_graph_contract());
+    }
+
+    for table in [
+        "lix_state_history",
+        "lix_file_history",
+        "lix_directory_history",
+    ] {
+        contracts.insert(table.to_string(), history_contract());
+    }
+
+    contracts.insert(
+        "lix_registered_schema".to_string(),
+        TableContract {
+            insert: Capability::Allowed,
+            update: Capability::Allowed,
+            delete: Capability::Unsupported(
+                "lix_registered_schema deletion is not supported; register an amended schema instead",
+            ),
+            columns: columns(&["value", "lixcol_metadata", "lixcol_global", "lixcol_untracked"]),
+        },
+    );
+
+    contracts.insert(
+        "lix_key_value".to_string(),
+        TableContract {
+            insert: Capability::Allowed,
+            update: Capability::Allowed,
+            delete: Capability::Allowed,
+            columns: columns(&["key", "value", "lixcol_metadata"]),
+        },
+    );
+
+    contracts
+}
+
+fn commit_graph_contract() -> TableContract {
+    TableContract {
+        insert: Capability::ReadOnly(
+            "Commit graph and changelog surfaces are read-only; Lix creates them when transactions commit.",
+        ),
+        update: Capability::ReadOnly(
+            "Commit graph and changelog surfaces are read-only; Lix creates them when transactions commit.",
+        ),
+        delete: Capability::ReadOnly(
+            "Commit graph and changelog surfaces are read-only; Lix creates them when transactions commit.",
+        ),
+        columns: BTreeMap::new(),
+    }
+}
+
+fn history_contract() -> TableContract {
+    TableContract {
+        insert: Capability::ReadOnly(
+            "History views are query-only; write to the live surface such as lix_state, lix_file, lix_directory, or the typed entity table.",
+        ),
+        update: Capability::ReadOnly(
+            "History views are query-only; write to the live surface such as lix_state, lix_file, lix_directory, or the typed entity table.",
+        ),
+        delete: Capability::ReadOnly(
+            "History views are query-only; write to the live surface such as lix_state, lix_file, lix_directory, or the typed entity table.",
+        ),
+        columns: BTreeMap::new(),
+    }
+}
+
+fn columns(writable: &[&str]) -> BTreeMap<String, ColumnContract> {
+    let writable = writable.iter().copied().collect::<BTreeSet<_>>();
+    writable
+        .into_iter()
+        .map(|column| (column.to_string(), ColumnContract { writable: true }))
+        .collect()
+}

package/dist-engine-src/src/sql2/read_only.rs

@@ -1,42 +1,42 @@
 use datafusion::error::DataFusionError;
 
-use crate::transaction::types::StageRow;
+use crate::transaction::types::TransactionWriteRow;
 use crate::LixError;
 
 pub(crate) fn reject_read_only_entity_surface(
     schema_key: &str,
-    operation: &str,
+    action: &str,
 ) -> Result<(), DataFusionError> {
     if schema_key == "lix_directory_descriptor" {
         return Err(read_only_error(
-            operation,
+            action,
             schema_key,
             "Use the writable lix_directory surface to create, update, or delete directories.",
         ));
     }
     if let Some(message) = read_only_schema_message(schema_key) {
-        return Err(read_only_error(operation, schema_key, message));
+        return Err(read_only_error(action, schema_key, message));
     }
     Ok(())
 }
 
 pub(crate) fn reject_read_only_stage_rows(
-    rows: &[StageRow],
-    operation: &str,
+    rows: &[TransactionWriteRow],
+    action: &str,
 ) -> Result<(), DataFusionError> {
     for row in rows {
         if let Some(message) = read_only_schema_message(&row.schema_key) {
-            return Err(read_only_error(operation, &row.schema_key, message));
+            return Err(read_only_error(action, &row.schema_key, message));
         }
     }
     Ok(())
 }
 
-fn read_only_error(operation: &str, schema_key: &str, message: &'static str) -> DataFusionError {
+fn read_only_error(action: &str, schema_key: &str, message: &'static str) -> DataFusionError {
     super::error::lix_error_to_datafusion_error(
         LixError::new(
             LixError::CODE_READ_ONLY,
-            format!("{operation} cannot write read-only surface '{schema_key}'"),
+            format!("{action} cannot write read-only surface '{schema_key}'"),
         )
         .with_hint(message),
     )
@@ -55,9 +55,7 @@ fn read_only_schema_message(schema_key: &str) -> Option<&'static str> {
         }
         "lix_commit"
         | "lix_commit_edge"
-        | "lix_change"
-        | "lix_change_set"
-        | "lix_change_set_element" => Some(
+        | "lix_change" => Some(
             "Commit graph and changelog surfaces are read-only; Lix creates them when transactions commit.",
         ),
         _ => None,

package/dist-engine-src/src/sql2/session.rs

@@ -5,7 +5,6 @@ use datafusion::prelude::{SessionConfig, SessionContext};
 use crate::LixError;
 
 use super::change_provider::register_lix_change_provider;
-use super::commit_derived_provider::register_commit_derived_providers;
 use super::directory_history_provider::register_lix_directory_history_provider;
 use super::directory_provider::{
     register_lix_directory_providers, register_lix_directory_write_providers,
@@ -37,22 +36,20 @@ pub(crate) async fn build_read_session(
     )
     .await?;
     register_lix_version_provider(&session, ctx.live_state(), Arc::clone(&version_ref)).await?;
-    let changelog_query_source = ctx.changelog_query_source();
-    register_lix_change_provider(&session, changelog_query_source.clone()).await?;
-    let commit_graph = ctx.commit_graph();
-    register_commit_derived_providers(&session, commit_graph, Arc::clone(&version_ref)).await?;
+    let commit_store_query_source = ctx.commit_store_query_source();
+    register_lix_change_provider(&session, commit_store_query_source.clone()).await?;
     let state_history_commit_graph = ctx.commit_graph();
     register_history_providers(
         &session,
         state_history_commit_graph,
-        changelog_query_source.clone(),
+        commit_store_query_source.clone(),
     )
     .await?;
     let file_history_commit_graph = ctx.commit_graph();
     register_lix_file_history_provider(
         &session,
         file_history_commit_graph,
-        changelog_query_source.clone(),
+        commit_store_query_source.clone(),
         ctx.blob_reader(),
     )
     .await?;
@@ -60,7 +57,7 @@ pub(crate) async fn build_read_session(
     register_lix_directory_history_provider(
         &session,
         directory_history_commit_graph,
-        changelog_query_source.clone(),
+        commit_store_query_source.clone(),
     )
     .await?;
     let entity_commit_graph = Arc::new(tokio::sync::Mutex::new(ctx.commit_graph()));
@@ -87,7 +84,7 @@ pub(crate) async fn build_read_session(
         ctx.live_state(),
         Arc::clone(&version_ref),
         entity_commit_graph,
-        changelog_query_source,
+        commit_store_query_source,
         &ctx.list_visible_schemas()?,
     )
     .await?;
@@ -120,7 +117,7 @@ pub(crate) async fn build_write_session(
     Ok(session)
 }
 
-fn new_sql_session_context() -> SessionContext {
+pub(crate) fn new_sql_session_context() -> SessionContext {
     SessionContext::new_with_config(
         SessionConfig::new()
             .with_information_schema(true)

package/dist-engine-src/src/sql2/udfs/lix_timestamp.rs

@@ -0,0 +1,76 @@
+use std::any::Any;
+
+use datafusion::arrow::datatypes::DataType;
+use datafusion::common::{plan_err, Result, ScalarValue};
+use datafusion::logical_expr::{
+    ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility,
+};
+
+use crate::functions::FunctionProviderHandle;
+
+#[derive(Clone)]
+pub(super) struct LixTimestamp {
+    pub(super) functions: FunctionProviderHandle,
+}
+
+impl PartialEq for LixTimestamp {
+    fn eq(&self, _other: &Self) -> bool {
+        true
+    }
+}
+
+impl Eq for LixTimestamp {}
+
+impl std::hash::Hash for LixTimestamp {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.name().hash(state);
+    }
+}
+
+impl std::fmt::Debug for LixTimestamp {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LixTimestamp").finish()
+    }
+}
+
+impl ScalarUDFImpl for LixTimestamp {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_timestamp"
+    }
+
+    fn signature(&self) -> &Signature {
+        static SIGNATURE: std::sync::LazyLock<Signature> =
+            std::sync::LazyLock::new(|| Signature::nullary(Volatility::Volatile));
+        &SIGNATURE
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        Ok(DataType::Utf8)
+    }
+
+    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+        if !args.args.is_empty() {
+            return plan_err!("lix_timestamp requires no arguments");
+        }
+        Ok(ColumnarValue::Scalar(ScalarValue::Utf8(Some(
+            self.functions.call_timestamp(),
+        ))))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_text;
+
+    #[tokio::test]
+    async fn returns_timestamp_text() {
+        let value = single_text("SELECT lix_timestamp()")
+            .await
+            .expect("timestamp should not be null");
+        assert!(!value.is_empty());
+    }
+}

package/dist-engine-src/src/sql2/udfs/mod.rs

@@ -6,13 +6,17 @@ mod lix_json_get;
 mod lix_json_get_text;
 mod lix_text_decode;
 mod lix_text_encode;
+mod lix_timestamp;
 mod lix_uuid_v7;
+mod public_call;
 
 use datafusion::execution::context::SessionContext;
 use datafusion::logical_expr::ScalarUDF;
 
 use crate::functions::FunctionProviderHandle;
 
+pub(crate) use public_call::validate_public_udf_calls;
+
 #[cfg(test)]
 pub(crate) fn system_sql2_function_provider() -> FunctionProviderHandle {
     use crate::functions::{FunctionProvider, SharedFunctionProvider, SystemFunctionProvider};
@@ -34,7 +38,10 @@ pub(crate) fn register_sql2_functions(
     ctx.register_udf(ScalarUDF::from(lix_text_encode::LixTextEncode::new()));
     ctx.register_udf(ScalarUDF::from(lix_json::LixJson));
     ctx.register_udf(ScalarUDF::from(lix_empty_blob::LixEmptyBlob));
-    ctx.register_udf(ScalarUDF::from(lix_uuid_v7::LixUuidV7 { functions }));
+    ctx.register_udf(ScalarUDF::from(lix_uuid_v7::LixUuidV7 {
+        functions: functions.clone(),
+    }));
+    ctx.register_udf(ScalarUDF::from(lix_timestamp::LixTimestamp { functions }));
 }
 
 #[cfg(test)]

package/dist-engine-src/src/sql2/udfs/public_call.rs

@@ -0,0 +1,211 @@
+use std::ops::ControlFlow;
+
+use datafusion::sql::sqlparser::ast::{
+    Expr, Function, FunctionArg, FunctionArgExpr, FunctionArguments, ObjectNamePart, Statement,
+    Value, Visit, Visitor,
+};
+use datafusion::sql::sqlparser::dialect::GenericDialect;
+use datafusion::sql::sqlparser::parser::Parser;
+
+use crate::LixError;
+
+pub(crate) fn validate_public_udf_calls(sql: &str) -> Result<(), LixError> {
+    let statements = Parser::parse_sql(&GenericDialect {}, sql).map_err(|error| {
+        LixError::new(
+            LixError::CODE_PARSE_ERROR,
+            format!("sql2 SQL parse error: {error}"),
+        )
+    })?;
+
+    let mut visitor = PublicUdfCallVisitor;
+    match statements.visit(&mut visitor) {
+        ControlFlow::Continue(()) => Ok(()),
+        ControlFlow::Break(error) => Err(*error),
+    }
+}
+
+struct PublicUdfCallVisitor;
+
+impl Visitor for PublicUdfCallVisitor {
+    type Break = Box<LixError>;
+
+    fn pre_visit_expr(&mut self, expr: &Expr) -> ControlFlow<Self::Break> {
+        let Expr::Function(function) = expr else {
+            return ControlFlow::Continue(());
+        };
+
+        match validate_public_function_call(function) {
+            Ok(()) => ControlFlow::Continue(()),
+            Err(error) => ControlFlow::Break(Box::new(error)),
+        }
+    }
+
+    fn pre_visit_statement(&mut self, statement: &Statement) -> ControlFlow<Self::Break> {
+        match statement {
+            Statement::CreateFunction(_) | Statement::DropFunction(_) => ControlFlow::Continue(()),
+            _ => ControlFlow::Continue(()),
+        }
+    }
+}
+
+fn validate_public_function_call(function: &Function) -> Result<(), LixError> {
+    let Some(name) = public_lix_function_name(function) else {
+        return Ok(());
+    };
+    let arity = function_arity(&function.args);
+
+    match name {
+        "lix_json" => expect_exact_arity(name, arity, 1),
+        "lix_empty_blob" => expect_exact_arity(name, arity, 0),
+        "lix_timestamp" => expect_exact_arity(name, arity, 0),
+        "lix_uuid_v7" => expect_exact_arity(name, arity, 0),
+        "lix_active_version_commit_id" => expect_exact_arity(name, arity, 0),
+        "lix_text_encode" | "lix_text_decode" => {
+            expect_arity_range(name, arity, 1, 2)?;
+            validate_literal_utf8_encoding(name, &function.args)
+        }
+        _ => Ok(()),
+    }
+}
+
+fn public_lix_function_name(function: &Function) -> Option<&'static str> {
+    let part = function.name.0.last()?;
+    let ident = match part {
+        ObjectNamePart::Identifier(ident) => ident.value.as_str(),
+        ObjectNamePart::Function(_) => return None,
+    };
+    match ident.to_ascii_lowercase().as_str() {
+        "lix_json" => Some("lix_json"),
+        "lix_empty_blob" => Some("lix_empty_blob"),
+        "lix_timestamp" => Some("lix_timestamp"),
+        "lix_uuid_v7" => Some("lix_uuid_v7"),
+        "lix_active_version_commit_id" => Some("lix_active_version_commit_id"),
+        "lix_text_encode" => Some("lix_text_encode"),
+        "lix_text_decode" => Some("lix_text_decode"),
+        _ => None,
+    }
+}
+
+fn function_arity(args: &FunctionArguments) -> usize {
+    match args {
+        FunctionArguments::None => 0,
+        FunctionArguments::Subquery(_) => 1,
+        FunctionArguments::List(list) => list.args.len(),
+    }
+}
+
+fn expect_exact_arity(name: &str, actual: usize, expected: usize) -> Result<(), LixError> {
+    if actual == expected {
+        return Ok(());
+    }
+
+    let expectation = if expected == 0 {
+        "no arguments".to_string()
+    } else if expected == 1 {
+        "exactly 1 argument".to_string()
+    } else {
+        format!("exactly {expected} arguments")
+    };
+    Err(invalid_param(format!("{name} requires {expectation}")))
+}
+
+fn expect_arity_range(name: &str, actual: usize, min: usize, max: usize) -> Result<(), LixError> {
+    if (min..=max).contains(&actual) {
+        return Ok(());
+    }
+    Err(invalid_param(format!(
+        "{name} requires {min} or {max} arguments"
+    )))
+}
+
+fn validate_literal_utf8_encoding(name: &str, args: &FunctionArguments) -> Result<(), LixError> {
+    let Some(encoding) = function_arg(args, 1) else {
+        return Ok(());
+    };
+    let Some(value) = string_literal_arg(encoding) else {
+        return Ok(());
+    };
+    let normalized = value.trim().to_ascii_uppercase().replace('-', "");
+    if normalized == "UTF8" {
+        Ok(())
+    } else {
+        Err(invalid_param(format!(
+            "{name}() only supports UTF8 encoding, got '{value}'"
+        )))
+    }
+}
+
+fn function_arg(args: &FunctionArguments, index: usize) -> Option<&FunctionArg> {
+    match args {
+        FunctionArguments::List(list) => list.args.get(index),
+        _ => None,
+    }
+}
+
+fn string_literal_arg(arg: &FunctionArg) -> Option<&str> {
+    let expr = match arg {
+        FunctionArg::Unnamed(FunctionArgExpr::Expr(expr))
+        | FunctionArg::Named {
+            arg: FunctionArgExpr::Expr(expr),
+            ..
+        }
+        | FunctionArg::ExprNamed {
+            arg: FunctionArgExpr::Expr(expr),
+            ..
+        } => expr,
+        _ => return None,
+    };
+    let Expr::Value(value) = expr else {
+        return None;
+    };
+    match &value.value {
+        Value::SingleQuotedString(value)
+        | Value::DoubleQuotedString(value)
+        | Value::TripleSingleQuotedString(value)
+        | Value::TripleDoubleQuotedString(value)
+        | Value::EscapedStringLiteral(value)
+        | Value::UnicodeStringLiteral(value)
+        | Value::NationalStringLiteral(value)
+        | Value::SingleQuotedRawStringLiteral(value)
+        | Value::DoubleQuotedRawStringLiteral(value)
+        | Value::TripleSingleQuotedRawStringLiteral(value)
+        | Value::TripleDoubleQuotedRawStringLiteral(value) => Some(value.as_str()),
+        Value::DollarQuotedString(value) => Some(value.value.as_str()),
+        _ => None,
+    }
+}
+
+fn invalid_param(message: impl Into<String>) -> LixError {
+    LixError::new(LixError::CODE_INVALID_PARAM, message)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::validate_public_udf_calls;
+
+    #[test]
+    fn rejects_lix_udf_wrong_arity_as_public_invalid_param() {
+        let error = validate_public_udf_calls("SELECT lix_uuid_v7('extra')")
+            .expect_err("wrong arity should be rejected");
+        assert_eq!(error.code, "LIX_INVALID_PARAM");
+        assert!(error.message.contains("lix_uuid_v7 requires no arguments"));
+    }
+
+    #[test]
+    fn rejects_unsupported_literal_encoding_as_public_invalid_param() {
+        let error = validate_public_udf_calls("SELECT lix_text_encode('Ada', 'base64')")
+            .expect_err("unsupported encoding should be rejected");
+        assert_eq!(error.code, "LIX_INVALID_PARAM");
+        assert!(error
+            .message
+            .contains("lix_text_encode() only supports UTF8 encoding"));
+    }
+
+    #[test]
+    fn accepts_valid_public_lix_udf_calls() {
+        validate_public_udf_calls(
+            "SELECT lix_json('{\"x\":1}'), lix_text_decode(X'416461', 'utf-8')",
+        )
+        .expect("valid calls should pass public validation");
+    }
+}