@lix-js/sdk 0.6.0-preview.5 → 0.6.0

package/dist-engine-src/src/plugin/manifest.rs

@@ -1,516 +0,0 @@
-use std::sync::OnceLock;
-
-use globset::{Glob, GlobBuilder};
-use jsonschema::{Draft, JSONSchema};
-use serde::{Deserialize, Serialize};
-use serde_json::Value as JsonValue;
-
-use crate::LixError;
-
-static PLUGIN_MANIFEST_SCHEMA: OnceLock<JsonValue> = OnceLock::new();
-static PLUGIN_MANIFEST_VALIDATOR: OnceLock<Result<JSONSchema, LixError>> = OnceLock::new();
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "kebab-case")]
-pub enum PluginRuntime {
-    WasmComponentV1,
-}
-
-#[allow(dead_code)]
-impl PluginRuntime {
-    pub fn as_str(self) -> &'static str {
-        match self {
-            Self::WasmComponentV1 => "wasm-component-v1",
-        }
-    }
-
-    pub fn from_str(value: &str) -> Option<Self> {
-        match value {
-            "wasm-component-v1" => Some(Self::WasmComponentV1),
-            _ => None,
-        }
-    }
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct PluginManifest {
-    pub key: String,
-    pub runtime: PluginRuntime,
-    pub api_version: String,
-    #[serde(rename = "match")]
-    pub file_match: PluginMatch,
-    #[serde(default)]
-    pub detect_changes: Option<DetectChangesConfig>,
-    pub entry: String,
-    pub schemas: Vec<String>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct PluginMatch {
-    pub path_glob: String,
-    #[serde(default)]
-    pub content_type: Option<PluginContentType>,
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum PluginContentType {
-    Text,
-    Binary,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct ValidatedPluginManifest {
-    pub manifest: PluginManifest,
-    pub normalized_json: String,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct DetectChangesConfig {
-    #[serde(default)]
-    pub state_context: Option<DetectStateContextConfig>,
-}
-
-#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
-pub struct DetectStateContextConfig {
-    #[serde(default)]
-    pub include_active_state: Option<bool>,
-    #[serde(default)]
-    pub columns: Option<Vec<StateContextColumn>>,
-}
-
-#[allow(dead_code)]
-impl DetectStateContextConfig {
-    pub fn includes_active_state(&self) -> bool {
-        self.include_active_state.unwrap_or(false)
-    }
-
-    pub fn resolved_columns_or_default(&self) -> Option<Vec<StateContextColumn>> {
-        if !self.includes_active_state() {
-            return None;
-        }
-        Some(
-            self.columns
-                .clone()
-                .unwrap_or_else(|| StateContextColumn::default_active_state_columns().to_vec()),
-        )
-    }
-}
-
-#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
-#[serde(rename_all = "snake_case")]
-pub enum StateContextColumn {
-    EntityPk,
-    SchemaKey,
-    SchemaVersion,
-    SnapshotContent,
-    FileId,
-    PluginKey,
-    BranchId,
-    ChangeId,
-    Metadata,
-    CreatedAt,
-    UpdatedAt,
-}
-
-#[allow(dead_code)]
-impl StateContextColumn {
-    pub const fn default_active_state_columns() -> &'static [StateContextColumn] {
-        &[
-            StateContextColumn::EntityPk,
-            StateContextColumn::SchemaKey,
-            StateContextColumn::SchemaVersion,
-            StateContextColumn::SnapshotContent,
-        ]
-    }
-}
-
-pub fn parse_plugin_manifest_json(raw: &str) -> Result<ValidatedPluginManifest, LixError> {
-    let manifest_json: JsonValue = serde_json::from_str(raw).map_err(|error| LixError {
-        code: "LIX_ERROR_UNKNOWN".to_string(),
-        message: format!("Plugin manifest must be valid JSON: {error}"),
-        hint: None,
-            details: None,
-    })?;
-
-    validate_plugin_manifest_json(&manifest_json)?;
-
-    let manifest: PluginManifest =
-        serde_json::from_value(manifest_json.clone()).map_err(|error| LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: format!("Plugin manifest does not match expected shape: {error}"),
-            hint: None,
-            details: None,
-        })?;
-    validate_path_glob(&manifest.file_match.path_glob)?;
-
-    let normalized_json = serde_json::to_string(&manifest_json).map_err(|error| LixError {
-        code: "LIX_ERROR_UNKNOWN".to_string(),
-        message: format!("Failed to normalize plugin manifest JSON: {error}"),
-        hint: None,
-            details: None,
-    })?;
-
-    Ok(ValidatedPluginManifest {
-        manifest,
-        normalized_json,
-    })
-}
-
-pub fn select_best_glob_match<'a, T, C: Copy + PartialEq>(
-    path: &str,
-    file_content_type: Option<C>,
-    candidates: &'a [T],
-    glob: impl Fn(&T) -> &str,
-    required_content_type: impl Fn(&T) -> Option<C>,
-) -> Option<&'a T> {
-    let mut selected: Option<&T> = None;
-    let mut selected_rank: Option<(u8, i32)> = None;
-
-    for candidate in candidates {
-        let pattern = glob(candidate);
-        if !glob_matches_path(pattern, path) {
-            continue;
-        }
-        if let (Some(actual_type), Some(required_type)) =
-            (file_content_type, required_content_type(candidate))
-        {
-            if actual_type != required_type {
-                continue;
-            }
-        }
-
-        let rank = glob_specificity_rank(pattern);
-        match selected_rank {
-            None => {
-                selected = Some(candidate);
-                selected_rank = Some(rank);
-            }
-            Some(existing_rank) if rank > existing_rank => {
-                selected = Some(candidate);
-                selected_rank = Some(rank);
-            }
-            _ => {}
-        }
-    }
-
-    selected
-}
-
-pub fn glob_matches_path(glob: &str, path: &str) -> bool {
-    let normalized_glob = glob.trim();
-    let normalized_path = path.trim();
-    if normalized_glob.is_empty() || normalized_path.is_empty() {
-        return false;
-    }
-    if is_catch_all_glob(normalized_glob) {
-        return true;
-    }
-
-    GlobBuilder::new(normalized_glob)
-        .literal_separator(false)
-        .case_insensitive(true)
-        .build()
-        .map(|compiled| compiled.compile_matcher().is_match(normalized_path))
-        .unwrap_or(false)
-}
-
-fn validate_path_glob(glob: &str) -> Result<(), LixError> {
-    Glob::new(glob).map_err(|error| LixError {
-        code: "LIX_ERROR_UNKNOWN".to_string(),
-        message: format!("Invalid plugin manifest: match.path_glob is invalid: {error}"),
-        hint: None,
-            details: None,
-    })?;
-    Ok(())
-}
-
-fn validate_plugin_manifest_json(manifest: &JsonValue) -> Result<(), LixError> {
-    let validator = plugin_manifest_validator()?;
-    if let Err(errors) = validator.validate(manifest) {
-        let details = format_validation_errors(errors);
-        return Err(LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: format!("Invalid plugin manifest: {details}"),
-            hint: None,
-            details: None,
-        });
-    }
-    Ok(())
-}
-
-fn glob_specificity_rank(glob: &str) -> (u8, i32) {
-    let normalized = glob.trim();
-    if is_catch_all_glob(normalized) {
-        return (0, i32::MIN);
-    }
-    (1, glob_specificity_score(normalized))
-}
-
-fn glob_specificity_score(glob: &str) -> i32 {
-    let mut literal_chars = 0i32;
-    let mut wildcard_chars = 0i32;
-    for ch in glob.chars() {
-        match ch {
-            '*' | '?' | '[' | ']' | '{' | '}' => wildcard_chars += 1,
-            _ => literal_chars += 1,
-        }
-    }
-    literal_chars - wildcard_chars
-}
-
-fn is_catch_all_glob(glob: &str) -> bool {
-    glob == "*" || glob == "**/*" || glob == "**"
-}
-
-fn plugin_manifest_validator() -> Result<&'static JSONSchema, LixError> {
-    let result = PLUGIN_MANIFEST_VALIDATOR.get_or_init(|| {
-        let mut options = JSONSchema::options();
-        options.with_meta_schemas();
-        if plugin_manifest_schema()
-            .get("$schema")
-            .and_then(JsonValue::as_str)
-            .is_some_and(|url| url == "https://json-schema.org/draft/2020-12/schema")
-        {
-            options.with_draft(Draft::Draft202012);
-        }
-
-        options
-            .compile(plugin_manifest_schema())
-            .map_err(|error| LixError {
-                code: "LIX_ERROR_UNKNOWN".to_string(),
-                message: format!("Failed to compile plugin manifest schema: {error}"),
-                hint: None,
-            details: None,
-            })
-    });
-
-    match result {
-        Ok(schema) => Ok(schema),
-        Err(error) => Err(LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: error.message.clone(),
-            hint: None,
-            details: None,
-        }),
-    }
-}
-
-fn plugin_manifest_schema() -> &'static JsonValue {
-    PLUGIN_MANIFEST_SCHEMA.get_or_init(|| {
-        let raw = include_str!("./plugin_manifest.schema.json");
-        serde_json::from_str(raw).expect("plugin_manifest.schema.json must be valid JSON")
-    })
-}
-
-fn format_validation_errors<'a>(
-    errors: impl Iterator<Item = jsonschema::ValidationError<'a>>,
-) -> String {
-    let mut parts = Vec::new();
-    for error in errors {
-        let path = error.instance_path.to_string();
-        let message = error.to_string();
-        if path.is_empty() {
-            parts.push(message);
-        } else {
-            parts.push(format!("{path} {message}"));
-        }
-    }
-    if parts.is_empty() {
-        "Unknown validation error".to_string()
-    } else {
-        parts.join("; ")
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::{
-        parse_plugin_manifest_json, DetectStateContextConfig, PluginContentType, StateContextColumn,
-    };
-
-    #[test]
-    fn resolved_columns_returns_none_when_active_state_is_not_enabled() {
-        let config = DetectStateContextConfig {
-            include_active_state: None,
-            columns: None,
-        };
-
-        assert_eq!(config.resolved_columns_or_default(), None);
-    }
-
-    #[test]
-    fn resolved_columns_uses_defaults_when_columns_are_omitted() {
-        let config = DetectStateContextConfig {
-            include_active_state: Some(true),
-            columns: None,
-        };
-
-        assert_eq!(
-            config.resolved_columns_or_default(),
-            Some(StateContextColumn::default_active_state_columns().to_vec())
-        );
-    }
-
-    #[test]
-    fn resolved_columns_uses_explicit_column_selection() {
-        let config = DetectStateContextConfig {
-            include_active_state: Some(true),
-            columns: Some(vec![
-                StateContextColumn::EntityPk,
-                StateContextColumn::SchemaKey,
-            ]),
-        };
-
-        assert_eq!(
-            config.resolved_columns_or_default(),
-            Some(vec![
-                StateContextColumn::EntityPk,
-                StateContextColumn::SchemaKey
-            ])
-        );
-    }
-
-    #[test]
-    fn parses_valid_manifest() {
-        let validated = parse_plugin_manifest_json(
-            r#"{
-                "key":"plugin_json",
-                "runtime":"wasm-component-v1",
-                "api_version":"0.1.0",
-                "match":{"path_glob":"*.json"},
-                "entry":"plugin.wasm",
-                "schemas":["schema/default.json"]
-            }"#,
-        )
-        .expect("manifest should parse");
-
-        assert_eq!(validated.manifest.key, "plugin_json");
-        assert_eq!(validated.manifest.runtime.as_str(), "wasm-component-v1");
-        assert_eq!(validated.manifest.entry, "plugin.wasm");
-    }
-
-    #[test]
-    fn rejects_invalid_manifest() {
-        let err = parse_plugin_manifest_json(
-            r#"{
-                "runtime":"wasm-component-v1",
-                "api_version":"0.1.0",
-                "match":{"path_glob":"*.json"},
-                "entry":"plugin.wasm",
-                "schemas":["schema/default.json"]
-            }"#,
-        )
-        .expect_err("manifest should be invalid");
-
-        assert!(err.message.contains("Invalid plugin manifest"));
-        assert!(err.message.contains("key"));
-    }
-
-    #[test]
-    fn rejects_invalid_path_glob() {
-        let err = parse_plugin_manifest_json(
-            r#"{
-                "key":"plugin_markdown",
-                "runtime":"wasm-component-v1",
-                "api_version":"0.1.0",
-                "match":{"path_glob":"*.{md,mdx"},
-                "entry":"plugin.wasm",
-                "schemas":["schema/default.json"]
-            }"#,
-        )
-        .expect_err("invalid glob should fail");
-
-        assert!(err.message.contains("match.path_glob"));
-    }
-
-    #[test]
-    fn parses_manifest_with_content_type_match_filter() {
-        let validated = parse_plugin_manifest_json(
-            r#"{
-                "key":"plugin_text",
-                "runtime":"wasm-component-v1",
-                "api_version":"0.1.0",
-                "match":{"path_glob":"**/*", "content_type":"text"},
-                "entry":"plugin.wasm",
-                "schemas":["schema/default.json"]
-            }"#,
-        )
-        .expect("manifest should parse");
-
-        assert_eq!(
-            validated.manifest.file_match.content_type,
-            Some(PluginContentType::Text)
-        );
-    }
-
-    #[test]
-    fn parses_manifest_with_active_state_columns() {
-        let validated = parse_plugin_manifest_json(
-            r#"{
-                "key":"plugin_markdown",
-                "runtime":"wasm-component-v1",
-                "api_version":"0.1.0",
-                "match":{"path_glob":"*.{md,mdx}"},
-                "entry":"plugin.wasm",
-                "schemas":["schema/default.json"],
-                "detect_changes": {
-                    "state_context": {
-                        "include_active_state": true,
-                        "columns": ["entity_pk", "schema_key", "snapshot_content"]
-                    }
-                }
-            }"#,
-        )
-        .expect("manifest should parse");
-
-        let state_context = validated
-            .manifest
-            .detect_changes
-            .expect("detect_changes should be present")
-            .state_context
-            .expect("state_context should be present");
-
-        assert_eq!(state_context.include_active_state, Some(true));
-        assert_eq!(
-            state_context.columns,
-            Some(vec![
-                StateContextColumn::EntityPk,
-                StateContextColumn::SchemaKey,
-                StateContextColumn::SnapshotContent
-            ])
-        );
-    }
-
-    #[test]
-    fn parses_manifest_with_active_state_and_default_columns() {
-        let validated = parse_plugin_manifest_json(
-            r#"{
-                "key":"plugin_markdown",
-                "runtime":"wasm-component-v1",
-                "api_version":"0.1.0",
-                "match":{"path_glob":"*.md"},
-                "entry":"plugin.wasm",
-                "schemas":["schema/default.json"],
-                "detect_changes": {
-                    "state_context": {
-                        "include_active_state": true
-                    }
-                }
-            }"#,
-        )
-        .expect("manifest should parse");
-
-        let state_context = validated
-            .manifest
-            .detect_changes
-            .expect("detect_changes should be present")
-            .state_context
-            .expect("state_context should be present");
-
-        assert_eq!(
-            state_context.resolved_columns_or_default(),
-            Some(StateContextColumn::default_active_state_columns().to_vec())
-        );
-    }
-}

package/dist-engine-src/src/plugin/materializer.rs

@@ -1,202 +0,0 @@
-use std::collections::BTreeSet;
-use std::sync::{Arc, RwLock};
-
-use async_trait::async_trait;
-
-use crate::common::LixError;
-use crate::live_state::{list_installed_plugin_archive_refs, PluginArchiveRef};
-use crate::Backend;
-
-use super::component::{apply_changes_with_plugin, PluginComponentHost};
-use super::{
-    load_installed_plugin_from_archive_bytes, plugin_key_from_archive_path, PluginContentType,
-    PluginRuntime,
-};
-
-#[derive(Debug, Clone, PartialEq, Eq)]
-pub struct InstalledPlugin {
-    pub key: String,
-    pub runtime: PluginRuntime,
-    pub api_version: String,
-    pub path_glob: String,
-    pub content_type: Option<PluginContentType>,
-    pub entry: String,
-    pub manifest_json: String,
-    pub wasm: Vec<u8>,
-}
-
-#[async_trait(?Send)]
-pub trait FilesystemPluginMaterializer {
-    async fn load_installed_plugins(&self) -> Result<Vec<InstalledPlugin>, LixError>;
-
-    async fn apply_plugin_changes(
-        &self,
-        plugin: &InstalledPlugin,
-        payload: &[u8],
-    ) -> Result<Vec<u8>, LixError>;
-}
-
-pub(crate) trait PluginMaterializationHost: PluginComponentHost {
-    fn plugin_backend(&self) -> &Arc<dyn Backend + Send + Sync>;
-
-    fn installed_plugins_cache(&self) -> &RwLock<Option<Vec<InstalledPlugin>>>;
-}
-
-pub(crate) async fn load_installed_plugins_with_runtime_cache(
-    host: &impl PluginMaterializationHost,
-) -> Result<Vec<InstalledPlugin>, LixError> {
-    if let Some(cached) = host
-        .installed_plugins_cache()
-        .read()
-        .map_err(|_| LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: "installed plugin cache lock poisoned".to_string(),
-            hint: None,
-            details: None,
-        })?
-        .clone()
-    {
-        return Ok(cached);
-    }
-
-    let plugins = load_installed_plugins_from_backend(host).await?;
-    let mut guard = host
-        .installed_plugins_cache()
-        .write()
-        .map_err(|_| LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: "installed plugin cache lock poisoned".to_string(),
-            hint: None,
-            details: None,
-        })?;
-    *guard = Some(plugins.clone());
-    Ok(plugins)
-}
-
-pub(crate) async fn load_installed_plugins_from_backend(
-    host: &impl PluginMaterializationHost,
-) -> Result<Vec<InstalledPlugin>, LixError> {
-    load_installed_plugins_from_backend_state(host.plugin_backend().as_ref()).await
-}
-
-pub(crate) async fn load_installed_plugins_from_backend_state(
-    backend: &dyn Backend,
-) -> Result<Vec<InstalledPlugin>, LixError> {
-    let archive_refs = list_installed_plugin_archive_refs(backend).await?;
-    let mut plugins = Vec::with_capacity(archive_refs.len());
-    for archive_ref in archive_refs {
-        plugins.push(
-            load_installed_plugin_from_archive_ref_with_backend(backend, &archive_ref).await?,
-        );
-    }
-    Ok(plugins)
-}
-
-pub(crate) async fn load_installed_plugin_from_archive_ref_with_backend(
-    backend: &dyn Backend,
-    archive_ref: &PluginArchiveRef,
-) -> Result<InstalledPlugin, LixError> {
-    let Some(plugin_key) = plugin_key_from_archive_path(&archive_ref.path) else {
-        return Err(LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: format!(
-                "plugin materialization: unsupported plugin archive path '{}'",
-                archive_ref.path
-            ),
-            hint: None,
-            details: None,
-        });
-    };
-    let binary_cas = crate::binary_cas::BinaryCasContext::new();
-    let mut reader = binary_cas.reader(backend);
-    let archive_hash = crate::binary_cas::BlobHash::from_hex(&archive_ref.blob_hash)?;
-    let archive_bytes = reader
-        .load_bytes_many(&[archive_hash])
-        .await?
-        .into_vec()
-        .into_iter()
-        .next()
-        .flatten()
-        .ok_or_else(|| LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: format!(
-                "plugin materialization: missing plugin archive blob '{}' for file '{}' ({})",
-                archive_ref.blob_hash, archive_ref.path, archive_ref.file_id
-            ),
-            hint: None,
-            details: None,
-        })?;
-    if archive_bytes.is_empty() {
-        return Err(LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: format!(
-                "plugin materialization: archive '{}' is empty",
-                archive_ref.path
-            ),
-            hint: None,
-            details: None,
-        });
-    }
-    load_installed_plugin_from_archive_bytes(&plugin_key, &archive_ref.path, &archive_bytes)
-}
-
-pub(crate) async fn list_installed_plugin_manifest_keys(
-    backend: &dyn Backend,
-) -> Result<BTreeSet<String>, LixError> {
-    Ok(load_installed_plugins_from_backend_state(backend)
-        .await?
-        .into_iter()
-        .map(|plugin| plugin.key)
-        .collect())
-}
-
-#[allow(dead_code)]
-pub(crate) async fn installed_plugin_manifest_key_exists(
-    backend: &dyn Backend,
-    plugin_key: &str,
-) -> Result<bool, LixError> {
-    Ok(list_installed_plugin_manifest_keys(backend)
-        .await?
-        .contains(plugin_key))
-}
-
-pub(crate) fn invalidate_installed_plugins_cache(
-    host: &impl PluginMaterializationHost,
-) -> Result<(), LixError> {
-    let mut guard = host
-        .installed_plugins_cache()
-        .write()
-        .map_err(|_| LixError {
-            code: "LIX_ERROR_UNKNOWN".to_string(),
-            message: "installed plugin cache lock poisoned".to_string(),
-            hint: None,
-            details: None,
-        })?;
-    *guard = None;
-    let mut component_guard = host.plugin_component_cache().lock().map_err(|_| LixError {
-        code: "LIX_ERROR_UNKNOWN".to_string(),
-        message: "plugin component cache lock poisoned".to_string(),
-        hint: None,
-            details: None,
-    })?;
-    component_guard.clear();
-    Ok(())
-}
-
-#[async_trait(?Send)]
-impl<T> FilesystemPluginMaterializer for T
-where
-    T: PluginMaterializationHost,
-{
-    async fn load_installed_plugins(&self) -> Result<Vec<InstalledPlugin>, LixError> {
-        load_installed_plugins_with_runtime_cache(self).await
-    }
-
-    async fn apply_plugin_changes(
-        &self,
-        plugin: &InstalledPlugin,
-        payload: &[u8],
-    ) -> Result<Vec<u8>, LixError> {
-        apply_changes_with_plugin(self, plugin, payload).await
-    }
-}