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

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

@@ -0,0 +1,82 @@
+use std::any::Any;
+use std::sync::Arc;
+
+use datafusion::arrow::array::StringArray;
+use datafusion::arrow::datatypes::DataType;
+use datafusion::common::{plan_err, Result, ScalarValue};
+use datafusion::logical_expr::{
+    ColumnarValue, ScalarFunctionArgs, ScalarUDFImpl, Signature, Volatility,
+};
+
+use super::common::{decode_utf8_value, scalar_inputs, validate_utf8_encoding_arg};
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub(super) struct LixTextDecode {
+    signature: Signature,
+}
+
+impl LixTextDecode {
+    pub(super) fn new() -> Self {
+        Self {
+            signature: Signature::one_of(
+                vec![Signature::any(1, Volatility::Immutable).type_signature],
+                Volatility::Immutable,
+            ),
+        }
+    }
+}
+
+impl ScalarUDFImpl for LixTextDecode {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_text_decode"
+    }
+
+    fn signature(&self) -> &Signature {
+        &self.signature
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        Ok(DataType::Utf8)
+    }
+
+    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+        if !(1..=2).contains(&args.args.len()) {
+            return plan_err!("lix_text_decode requires 1 or 2 arguments");
+        }
+        validate_utf8_encoding_arg(self.name(), args.args.get(1))?;
+
+        let scalar_inputs = scalar_inputs(&args.args);
+        let arrays = ColumnarValue::values_to_arrays(&args.args)?;
+        let input = &arrays[0];
+        let len = input.len();
+
+        let mut values = Vec::with_capacity(len);
+        for row in 0..len {
+            values.push(decode_utf8_value(input.as_ref(), row)?);
+        }
+        if scalar_inputs {
+            Ok(ColumnarValue::Scalar(ScalarValue::Utf8(
+                values.into_iter().next().flatten(),
+            )))
+        } else {
+            Ok(ColumnarValue::Array(Arc::new(StringArray::from(values))))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_text;
+
+    #[tokio::test]
+    async fn decodes_utf8_binary_to_text() {
+        assert_eq!(
+            single_text("SELECT lix_text_decode(X'416461')").await,
+            Some("Ada".to_string())
+        );
+    }
+}

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

@@ -0,0 +1,85 @@
+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 super::common::{
+    array_ref, binary_array_from_owned, encode_utf8_value, scalar_inputs,
+    validate_utf8_encoding_arg,
+};
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub(super) struct LixTextEncode {
+    signature: Signature,
+}
+
+impl LixTextEncode {
+    pub(super) fn new() -> Self {
+        Self {
+            signature: Signature::one_of(
+                vec![Signature::any(1, Volatility::Immutable).type_signature],
+                Volatility::Immutable,
+            ),
+        }
+    }
+}
+
+impl ScalarUDFImpl for LixTextEncode {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_text_encode"
+    }
+
+    fn signature(&self) -> &Signature {
+        &self.signature
+    }
+
+    fn return_type(&self, _arg_types: &[DataType]) -> Result<DataType> {
+        Ok(DataType::Binary)
+    }
+
+    fn invoke_with_args(&self, args: ScalarFunctionArgs) -> Result<ColumnarValue> {
+        if !(1..=2).contains(&args.args.len()) {
+            return plan_err!("lix_text_encode requires 1 or 2 arguments");
+        }
+        validate_utf8_encoding_arg(self.name(), args.args.get(1))?;
+
+        let scalar_inputs = scalar_inputs(&args.args);
+        let arrays = ColumnarValue::values_to_arrays(&args.args)?;
+        let input = &arrays[0];
+        let len = input.len();
+
+        let mut values = Vec::with_capacity(len);
+        for row in 0..len {
+            values.push(encode_utf8_value(input.as_ref(), row)?);
+        }
+        if scalar_inputs {
+            Ok(ColumnarValue::Scalar(ScalarValue::Binary(
+                values.into_iter().next().flatten(),
+            )))
+        } else {
+            Ok(ColumnarValue::Array(array_ref(binary_array_from_owned(
+                &values,
+            ))))
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_binary;
+
+    #[tokio::test]
+    async fn encodes_utf8_text_to_binary() {
+        assert_eq!(
+            single_binary("SELECT lix_text_encode('Ada')").await,
+            Some(b"Ada".to_vec())
+        );
+    }
+}

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/lix_uuid_v7.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 LixUuidV7 {
+    pub(super) functions: FunctionProviderHandle,
+}
+
+impl PartialEq for LixUuidV7 {
+    fn eq(&self, _other: &Self) -> bool {
+        true
+    }
+}
+
+impl Eq for LixUuidV7 {}
+
+impl std::hash::Hash for LixUuidV7 {
+    fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
+        self.name().hash(state);
+    }
+}
+
+impl std::fmt::Debug for LixUuidV7 {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.debug_struct("LixUuidV7").finish()
+    }
+}
+
+impl ScalarUDFImpl for LixUuidV7 {
+    fn as_any(&self) -> &dyn Any {
+        self
+    }
+
+    fn name(&self) -> &str {
+        "lix_uuid_v7"
+    }
+
+    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_uuid_v7 requires no arguments");
+        }
+        Ok(ColumnarValue::Scalar(ScalarValue::Utf8(Some(
+            self.functions.call_uuid_v7(),
+        ))))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::super::test_support::single_text;
+
+    #[tokio::test]
+    async fn returns_uuid_text() {
+        let value = single_text("SELECT lix_uuid_v7()")
+            .await
+            .expect("uuid should not be null");
+        assert!(!value.is_empty());
+    }
+}

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

@@ -0,0 +1,89 @@
+mod common;
+mod lix_active_version_commit_id;
+mod lix_empty_blob;
+mod lix_json;
+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};
+
+    SharedFunctionProvider::new(Box::new(SystemFunctionProvider) as Box<dyn FunctionProvider + Send>)
+}
+
+pub(crate) fn register_sql2_functions(
+    ctx: &SessionContext,
+    functions: FunctionProviderHandle,
+    active_version_commit_id: Option<String>,
+) {
+    ctx.register_udf(ScalarUDF::from(
+        lix_active_version_commit_id::LixActiveVersionCommitId::new(active_version_commit_id),
+    ));
+    ctx.register_udf(ScalarUDF::from(lix_json_get::LixJsonGet::new()));
+    ctx.register_udf(ScalarUDF::from(lix_json_get_text::LixJsonGetText::new()));
+    ctx.register_udf(ScalarUDF::from(lix_text_decode::LixTextDecode::new()));
+    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: functions.clone(),
+    }));
+    ctx.register_udf(ScalarUDF::from(lix_timestamp::LixTimestamp { functions }));
+}
+
+#[cfg(test)]
+pub(super) mod test_support {
+    use datafusion::arrow::array::{Array, BinaryArray, StringArray};
+    use datafusion::prelude::SessionContext;
+
+    use super::{register_sql2_functions, system_sql2_function_provider};
+
+    pub(super) async fn single_text(sql: &str) -> Option<String> {
+        let ctx = SessionContext::new();
+        register_sql2_functions(&ctx, system_sql2_function_provider(), None);
+        let batches = ctx
+            .sql(sql)
+            .await
+            .expect("query should plan")
+            .collect()
+            .await
+            .expect("query should execute");
+        let array = batches[0]
+            .column(0)
+            .as_any()
+            .downcast_ref::<StringArray>()
+            .expect("first column should be utf8");
+        (!array.is_null(0)).then(|| array.value(0).to_string())
+    }
+
+    pub(super) async fn single_binary(sql: &str) -> Option<Vec<u8>> {
+        let ctx = SessionContext::new();
+        register_sql2_functions(&ctx, system_sql2_function_provider(), None);
+        let batches = ctx
+            .sql(sql)
+            .await
+            .expect("query should plan")
+            .collect()
+            .await
+            .expect("query should execute");
+        let array = batches[0]
+            .column(0)
+            .as_any()
+            .downcast_ref::<BinaryArray>()
+            .expect("first column should be binary");
+        (!array.is_null(0)).then(|| array.value(0).to_vec())
+    }
+}

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");
+    }
+}