kreuzberg 4.0.0.rc1

data/vendor/kreuzberg/src/plugins/traits.rs

@@ -0,0 +1,258 @@
+//! Base plugin trait definition.
+//!
+//! All plugins must implement the `Plugin` trait, which provides basic lifecycle
+//! management and metadata methods.
+
+use crate::Result;
+
+/// Base trait that all plugins must implement.
+///
+/// This trait provides common functionality for plugin lifecycle management,
+/// identification, and metadata.
+///
+/// # Thread Safety
+///
+/// All plugins must be `Send + Sync` to support concurrent usage across threads.
+///
+/// # Example
+///
+/// ```rust
+/// use kreuzberg::plugins::Plugin;
+/// use kreuzberg::Result;
+/// use std::sync::atomic::{AtomicBool, Ordering};
+///
+/// struct MyPlugin {
+///     initialized: AtomicBool,
+/// }
+///
+/// impl Plugin for MyPlugin {
+///     fn name(&self) -> &str {
+///         "my-plugin"
+///     }
+///
+///     fn version(&self) -> String {
+///         "1.0.0".to_string()
+///     }
+///
+///     fn initialize(&self) -> Result<()> {
+///         self.initialized.store(true, Ordering::Release);
+///         println!("Plugin initialized!");
+///         Ok(())
+///     }
+///
+///     fn shutdown(&self) -> Result<()> {
+///         self.initialized.store(false, Ordering::Release);
+///         println!("Plugin shutdown!");
+///         Ok(())
+///     }
+/// }
+/// ```
+pub trait Plugin: Send + Sync {
+    /// Returns the unique name/identifier for this plugin.
+    ///
+    /// The name should be:
+    /// - Unique across all plugins
+    /// - Lowercase with hyphens (e.g., "my-custom-plugin")
+    /// - URL-safe characters only
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use kreuzberg::plugins::Plugin;
+    /// # use kreuzberg::Result;
+    /// # struct MyPlugin;
+    /// # impl Plugin for MyPlugin {
+    /// #     fn version(&self) -> String { "1.0.0".to_string() }
+    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
+    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
+    /// fn name(&self) -> &str {
+    ///     "pdf-extractor"
+    /// }
+    /// # }
+    /// ```
+    fn name(&self) -> &str;
+
+    /// Returns the semantic version of this plugin.
+    ///
+    /// Should follow semver format: `MAJOR.MINOR.PATCH`
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use kreuzberg::plugins::Plugin;
+    /// # use kreuzberg::Result;
+    /// # struct MyPlugin;
+    /// # impl Plugin for MyPlugin {
+    /// #     fn name(&self) -> &str { "my-plugin" }
+    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
+    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
+    /// fn version(&self) -> String {
+    ///     "1.2.3".to_string()
+    /// }
+    /// # }
+    /// ```
+    fn version(&self) -> String;
+
+    /// Initialize the plugin.
+    ///
+    /// Called once when the plugin is registered. Use this to:
+    /// - Load configuration
+    /// - Initialize resources (connections, caches, etc.)
+    /// - Validate dependencies
+    ///
+    /// # Thread Safety
+    ///
+    /// This method takes `&self` instead of `&mut self` to work with `Arc<dyn Plugin>`.
+    /// Plugins needing mutable state during initialization should use interior mutability
+    /// patterns (Mutex, RwLock, OnceCell, etc.).
+    ///
+    /// # Errors
+    ///
+    /// Should return an error if initialization fails. The plugin will not be
+    /// registered if this method returns an error.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use kreuzberg::plugins::Plugin;
+    /// # use kreuzberg::Result;
+    /// # use std::sync::Mutex;
+    /// # struct MyPlugin { config: Mutex<Option<String>> }
+    /// # impl Plugin for MyPlugin {
+    /// #     fn name(&self) -> &str { "my-plugin" }
+    /// #     fn version(&self) -> String { "1.0.0".to_string() }
+    /// #     fn shutdown(&self) -> Result<()> { Ok(()) }
+    /// fn initialize(&self) -> Result<()> {
+    ///     // Load configuration using interior mutability
+    ///     let mut config = self.config.lock().unwrap();
+    ///     *config = Some("loaded".to_string());
+    ///
+    ///     // Perform any initialization work
+    ///     println!("Plugin initialized successfully");
+    ///
+    ///     Ok(())
+    /// }
+    /// # }
+    /// ```
+    fn initialize(&self) -> Result<()>;
+
+    /// Shutdown the plugin.
+    ///
+    /// Called when the plugin is being unregistered or the application is shutting down.
+    /// Use this to:
+    /// - Close connections
+    /// - Flush caches
+    /// - Release resources
+    ///
+    /// # Thread Safety
+    ///
+    /// This method takes `&self` instead of `&mut self` to work with `Arc<dyn Plugin>`.
+    /// Plugins needing mutable state during shutdown should use interior mutability
+    /// patterns (Mutex, RwLock, etc.).
+    ///
+    /// # Errors
+    ///
+    /// Errors during shutdown are logged but don't prevent the shutdown process.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// # use kreuzberg::plugins::Plugin;
+    /// # use kreuzberg::Result;
+    /// # use std::sync::Mutex;
+    /// # struct MyPlugin { cache: Mutex<Option<Vec<String>>> }
+    /// # impl Plugin for MyPlugin {
+    /// #     fn name(&self) -> &str { "my-plugin" }
+    /// #     fn version(&self) -> String { "1.0.0".to_string() }
+    /// #     fn initialize(&self) -> Result<()> { Ok(()) }
+    /// fn shutdown(&self) -> Result<()> {
+    ///     // Flush caches using interior mutability
+    ///     let mut cache = self.cache.lock().unwrap();
+    ///     if let Some(data) = cache.take() {
+    ///         // Persist cache to disk
+    ///     }
+    ///
+    ///     Ok(())
+    /// }
+    /// # }
+    /// ```
+    fn shutdown(&self) -> Result<()>;
+
+    /// Optional plugin description for debugging and logging.
+    ///
+    /// Defaults to empty string if not overridden.
+    fn description(&self) -> &str {
+        ""
+    }
+
+    /// Optional plugin author information.
+    ///
+    /// Defaults to empty string if not overridden.
+    fn author(&self) -> &str {
+        ""
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::sync::atomic::{AtomicBool, Ordering};
+
+    struct TestPlugin {
+        initialized: AtomicBool,
+    }
+
+    impl Plugin for TestPlugin {
+        fn name(&self) -> &str {
+            "test-plugin"
+        }
+
+        fn version(&self) -> String {
+            "1.0.0".to_string()
+        }
+
+        fn initialize(&self) -> Result<()> {
+            self.initialized.store(true, Ordering::Release);
+            Ok(())
+        }
+
+        fn shutdown(&self) -> Result<()> {
+            self.initialized.store(false, Ordering::Release);
+            Ok(())
+        }
+
+        fn description(&self) -> &str {
+            "A test plugin"
+        }
+
+        fn author(&self) -> &str {
+            "Test Author"
+        }
+    }
+
+    #[test]
+    fn test_plugin_metadata() {
+        let plugin = TestPlugin {
+            initialized: AtomicBool::new(false),
+        };
+        assert_eq!(plugin.name(), "test-plugin");
+        assert_eq!(plugin.version(), "1.0.0");
+        assert_eq!(plugin.description(), "A test plugin");
+        assert_eq!(plugin.author(), "Test Author");
+    }
+
+    #[test]
+    fn test_plugin_lifecycle() {
+        let plugin = TestPlugin {
+            initialized: AtomicBool::new(false),
+        };
+
+        assert!(!plugin.initialized.load(Ordering::Acquire));
+
+        plugin.initialize().unwrap();
+        assert!(plugin.initialized.load(Ordering::Acquire));
+
+        plugin.shutdown().unwrap();
+        assert!(!plugin.initialized.load(Ordering::Acquire));
+    }
+}