spikard 0.13.0 → 0.15.2

data/vendor/crates/spikard-http/src/jsonrpc/method_registry.rs

@@ -1,648 +0,0 @@
-//! JSON-RPC method registry for handler registration and lookup
-//!
-//! This module provides thread-safe registration and retrieval of JSON-RPC methods
-//! with their associated handlers and metadata.
-
-use crate::handler_trait::Handler;
-use serde::{Deserialize, Serialize};
-use serde_json::Value;
-use std::collections::HashMap;
-use std::fmt;
-use std::sync::{Arc, RwLock};
-
-/// Error type for registry operations that involve lock acquisition
-#[derive(Debug, Clone)]
-pub struct RegistryError {
-    /// Description of the error
-    message: String,
-}
-
-impl RegistryError {
-    /// Create a lock poisoning error
-    fn lock_poisoned() -> Self {
-        Self {
-            message: "Failed to acquire lock on registry: lock was poisoned due to a previous panic".to_string(),
-        }
-    }
-}
-
-impl fmt::Display for RegistryError {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "{}", self.message)
-    }
-}
-
-impl std::error::Error for RegistryError {}
-
-/// Example for a JSON-RPC method
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct MethodExample {
-    /// Name of the example
-    pub name: String,
-    /// Optional description of the example
-    pub description: Option<String>,
-    /// Example parameters
-    pub params: Value,
-    /// Example result
-    pub result: Value,
-}
-
-/// Metadata for a JSON-RPC method
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct MethodMetadata {
-    /// Method name
-    pub name: String,
-    /// Optional description of what the method does
-    pub description: Option<String>,
-    /// JSON Schema for method parameters
-    pub params_schema: Option<Value>,
-    /// JSON Schema for method result
-    pub result_schema: Option<Value>,
-    /// JSON Schema for method errors
-    pub error_schema: Option<Value>,
-    /// Examples for this method
-    pub examples: Vec<MethodExample>,
-    /// Whether this method is deprecated
-    pub deprecated: bool,
-    /// Tags for organizing/categorizing methods
-    pub tags: Vec<String>,
-}
-
-impl MethodMetadata {
-    /// Create a new MethodMetadata with minimal required fields
-    ///
-    /// # Arguments
-    ///
-    /// * `name` - The method name
-    pub fn new(name: impl Into<String>) -> Self {
-        Self {
-            name: name.into(),
-            description: None,
-            params_schema: None,
-            result_schema: None,
-            error_schema: None,
-            examples: Vec::new(),
-            deprecated: false,
-            tags: Vec::new(),
-        }
-    }
-
-    /// Set the description for this method
-    pub fn with_description(mut self, description: impl Into<String>) -> Self {
-        self.description = Some(description.into());
-        self
-    }
-
-    /// Set the parameters schema for this method
-    pub fn with_params_schema(mut self, schema: Value) -> Self {
-        self.params_schema = Some(schema);
-        self
-    }
-
-    /// Set the result schema for this method
-    pub fn with_result_schema(mut self, schema: Value) -> Self {
-        self.result_schema = Some(schema);
-        self
-    }
-
-    /// Set the error schema for this method
-    pub fn with_error_schema(mut self, schema: Value) -> Self {
-        self.error_schema = Some(schema);
-        self
-    }
-
-    /// Add an example to this method's examples
-    pub fn with_example(mut self, example: MethodExample) -> Self {
-        self.examples.push(example);
-        self
-    }
-
-    /// Mark this method as deprecated
-    pub fn mark_deprecated(mut self) -> Self {
-        self.deprecated = true;
-        self
-    }
-
-    /// Add a tag to this method
-    pub fn with_tag(mut self, tag: impl Into<String>) -> Self {
-        self.tags.push(tag.into());
-        self
-    }
-}
-
-/// Type alias for handler and metadata pair
-type MethodEntry = (Arc<dyn Handler>, MethodMetadata);
-
-/// Type alias for the internal storage structure
-type MethodStorage = Arc<RwLock<HashMap<String, MethodEntry>>>;
-
-/// Type alias for list_all return type: (name, handler, metadata)
-type MethodListEntry = (String, Arc<dyn Handler>, MethodMetadata);
-
-/// Thread-safe registry for JSON-RPC methods
-///
-/// Stores handlers along with their metadata. The registry uses `Arc<RwLock>` for
-/// thread-safe concurrent access with low contention for reads.
-///
-/// # Example
-///
-/// ```ignore
-/// use spikard_http::jsonrpc::method_registry::{JsonRpcMethodRegistry, MethodMetadata};
-/// use std::sync::Arc;
-///
-/// let registry = JsonRpcMethodRegistry::new();
-///
-/// // Register a method (handler implementation omitted for brevity)
-/// registry.register(
-///     "add",
-///     Arc::new(add_handler),
-///     MethodMetadata::new("add").with_description("Add two numbers"),
-/// );
-///
-/// // Lookup a method
-/// if let Some(handler) = registry.get("add") {
-///     // Use handler
-/// }
-/// ```
-pub struct JsonRpcMethodRegistry {
-    /// Internal storage: method name -> (handler, metadata)
-    methods: MethodStorage,
-}
-
-impl JsonRpcMethodRegistry {
-    /// Create a new empty method registry
-    pub fn new() -> Self {
-        Self {
-            methods: Arc::new(RwLock::new(HashMap::new())),
-        }
-    }
-
-    /// Register a method with its handler and metadata
-    ///
-    /// If a method with the same name already exists, it will be replaced.
-    ///
-    /// # Arguments
-    ///
-    /// * `name` - The method name (e.g., "add", "multiply")
-    /// * `handler` - The handler that processes this method
-    /// * `metadata` - Metadata describing the method
-    ///
-    /// # Returns
-    ///
-    /// Returns `Ok(())` on success, or `Err(RegistryError)` if the lock cannot be acquired.
-    ///
-    /// # Example
-    ///
-    /// ```ignore
-    /// # use spikard_http::jsonrpc::{JsonRpcMethodRegistry, MethodMetadata};
-    /// # use std::sync::Arc;
-    /// # struct DummyHandler;
-    /// # impl spikard_http::handler_trait::Handler for DummyHandler {
-    /// #     fn call(&self, _: axum::http::Request<axum::body::Body>, _: spikard_http::handler_trait::RequestData) -> std::pin::Pin<Box<dyn std::future::Future<Output = spikard_http::handler_trait::HandlerResult> + Send + '_>> {
-    /// #         Box::pin(async { Err((axum::http::StatusCode::OK, String::new())) })
-    /// #     }
-    /// # }
-    /// let registry = JsonRpcMethodRegistry::new();
-    /// let handler = Arc::new(DummyHandler);
-    /// let metadata = MethodMetadata::new("test");
-    /// registry.register("test", handler, metadata)?;
-    /// # Ok::<(), Box<dyn std::error::Error>>(())
-    /// ```
-    pub fn register(
-        &self,
-        name: impl Into<String>,
-        handler: Arc<dyn Handler>,
-        metadata: MethodMetadata,
-    ) -> Result<(), RegistryError> {
-        let name = name.into();
-        let mut methods = self.methods.write().map_err(|_| RegistryError::lock_poisoned())?;
-        methods.insert(name, (handler, metadata));
-        Ok(())
-    }
-
-    /// Get a handler by method name
-    ///
-    /// Returns `None` if the method is not registered.
-    ///
-    /// # Arguments
-    ///
-    /// * `name` - The method name to look up
-    ///
-    /// # Returns
-    ///
-    /// `Ok(Option<Arc<dyn Handler>>)` containing the handler if found, `Ok(None)` if not found,
-    /// or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn get(&self, name: &str) -> Result<Option<Arc<dyn Handler>>, RegistryError> {
-        let methods = self.methods.read().map_err(|_| RegistryError::lock_poisoned())?;
-        Ok(methods.get(name).map(|(handler, _)| Arc::clone(handler)))
-    }
-
-    /// Get metadata for a method by name
-    ///
-    /// Returns `None` if the method is not registered.
-    ///
-    /// # Arguments
-    ///
-    /// * `name` - The method name to look up
-    ///
-    /// # Returns
-    ///
-    /// `Ok(Option<MethodMetadata>)` containing the metadata if found, `Ok(None)` if not found,
-    /// or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn get_metadata(&self, name: &str) -> Result<Option<MethodMetadata>, RegistryError> {
-        let methods = self.methods.read().map_err(|_| RegistryError::lock_poisoned())?;
-        Ok(methods.get(name).map(|(_, metadata)| metadata.clone()))
-    }
-
-    /// Get both handler and metadata for a method
-    ///
-    /// Returns `None` if the method is not registered.
-    ///
-    /// # Arguments
-    ///
-    /// * `name` - The method name to look up
-    ///
-    /// # Returns
-    ///
-    /// `Ok(Option<MethodEntry>)` if found, `Ok(None)` if not found,
-    /// or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn get_with_metadata(&self, name: &str) -> Result<Option<MethodEntry>, RegistryError> {
-        let methods = self.methods.read().map_err(|_| RegistryError::lock_poisoned())?;
-        Ok(methods
-            .get(name)
-            .map(|(handler, metadata)| (Arc::clone(handler), metadata.clone())))
-    }
-
-    /// List all registered method names
-    ///
-    /// # Returns
-    ///
-    /// `Ok(Vec<String>)` containing all registered method names, sorted lexicographically,
-    /// or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn list_methods(&self) -> Result<Vec<String>, RegistryError> {
-        let methods = self.methods.read().map_err(|_| RegistryError::lock_poisoned())?;
-        let mut names: Vec<String> = methods.keys().cloned().collect();
-        names.sort();
-        Ok(names)
-    }
-
-    /// Check if a method is registered
-    ///
-    /// # Arguments
-    ///
-    /// * `name` - The method name to check
-    ///
-    /// # Returns
-    ///
-    /// `Ok(true)` if the method is registered, `Ok(false)` if not,
-    /// or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn contains(&self, name: &str) -> Result<bool, RegistryError> {
-        let methods = self.methods.read().map_err(|_| RegistryError::lock_poisoned())?;
-        Ok(methods.contains_key(name))
-    }
-
-    /// Get the number of registered methods
-    ///
-    /// # Returns
-    ///
-    /// `Ok(usize)` containing the count of registered methods,
-    /// or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn len(&self) -> Result<usize, RegistryError> {
-        let methods = self.methods.read().map_err(|_| RegistryError::lock_poisoned())?;
-        Ok(methods.len())
-    }
-
-    /// Check if the registry is empty
-    ///
-    /// # Returns
-    ///
-    /// `Ok(true)` if no methods are registered, `Ok(false)` if any methods exist,
-    /// or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn is_empty(&self) -> Result<bool, RegistryError> {
-        let methods = self.methods.read().map_err(|_| RegistryError::lock_poisoned())?;
-        Ok(methods.is_empty())
-    }
-
-    /// Remove a method from the registry
-    ///
-    /// Returns `Ok(true)` if the method was removed, `Ok(false)` if it didn't exist.
-    ///
-    /// # Arguments
-    ///
-    /// * `name` - The method name to remove
-    ///
-    /// # Returns
-    ///
-    /// `Ok(true)` if the method was removed, `Ok(false)` if not found,
-    /// or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn remove(&self, name: &str) -> Result<bool, RegistryError> {
-        let mut methods = self.methods.write().map_err(|_| RegistryError::lock_poisoned())?;
-        Ok(methods.remove(name).is_some())
-    }
-
-    /// Clear all methods from the registry
-    ///
-    /// # Returns
-    ///
-    /// `Ok(())` on success, or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn clear(&self) -> Result<(), RegistryError> {
-        let mut methods = self.methods.write().map_err(|_| RegistryError::lock_poisoned())?;
-        methods.clear();
-        Ok(())
-    }
-
-    /// Get all methods with their metadata
-    ///
-    /// # Returns
-    ///
-    /// `Ok(Vec)` containing tuples of method name, handler, and metadata,
-    /// or `Err(RegistryError)` if the lock cannot be acquired.
-    pub fn list_all(&self) -> Result<Vec<MethodListEntry>, RegistryError> {
-        let methods = self.methods.read().map_err(|_| RegistryError::lock_poisoned())?;
-        Ok(methods
-            .iter()
-            .map(|(name, (handler, metadata))| (name.clone(), Arc::clone(handler), metadata.clone()))
-            .collect())
-    }
-}
-
-impl Default for JsonRpcMethodRegistry {
-    fn default() -> Self {
-        Self::new()
-    }
-}
-
-impl Clone for JsonRpcMethodRegistry {
-    fn clone(&self) -> Self {
-        Self {
-            methods: Arc::clone(&self.methods),
-        }
-    }
-}
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    use crate::handler_trait::{HandlerResult, RequestData};
-    use axum::body::Body;
-    use axum::http::Request;
-    use std::panic;
-
-    /// Mock handler for testing
-    struct MockHandler;
-
-    impl Handler for MockHandler {
-        fn call(
-            &self,
-            _request: Request<Body>,
-            _request_data: RequestData,
-        ) -> std::pin::Pin<Box<dyn std::future::Future<Output = HandlerResult> + Send + '_>> {
-            Box::pin(async { Err((axum::http::StatusCode::OK, "mock".to_string())) })
-        }
-    }
-
-    fn create_test_registry() -> JsonRpcMethodRegistry {
-        JsonRpcMethodRegistry::new()
-    }
-
-    fn create_mock_handler() -> Arc<dyn Handler> {
-        Arc::new(MockHandler)
-    }
-
-    #[test]
-    fn test_new_registry_is_empty() {
-        let registry = create_test_registry();
-        assert!(registry.is_empty().unwrap());
-        assert_eq!(registry.len().unwrap(), 0);
-        assert!(registry.list_methods().unwrap().is_empty());
-    }
-
-    #[test]
-    fn test_register_and_get_method() {
-        let registry = create_test_registry();
-        let handler = create_mock_handler();
-        let metadata = MethodMetadata::new("test_method");
-
-        registry
-            .register("test_method", handler.clone(), metadata.clone())
-            .unwrap();
-
-        assert!(!registry.is_empty().unwrap());
-        assert_eq!(registry.len().unwrap(), 1);
-        assert!(registry.contains("test_method").unwrap());
-        assert!(registry.get("test_method").unwrap().is_some());
-        assert_eq!(
-            registry.get_metadata("test_method").unwrap().unwrap().name,
-            "test_method"
-        );
-    }
-
-    #[test]
-    fn test_get_nonexistent_method() {
-        let registry = create_test_registry();
-        assert!(registry.get("nonexistent").unwrap().is_none());
-        assert!(registry.get_metadata("nonexistent").unwrap().is_none());
-    }
-
-    #[test]
-    fn test_list_methods_returns_sorted() {
-        let registry = create_test_registry();
-        let handler = create_mock_handler();
-
-        registry
-            .register("zebra", handler.clone(), MethodMetadata::new("zebra"))
-            .unwrap();
-        registry
-            .register("apple", handler.clone(), MethodMetadata::new("apple"))
-            .unwrap();
-        registry
-            .register("banana", handler.clone(), MethodMetadata::new("banana"))
-            .unwrap();
-
-        let methods = registry.list_methods().unwrap();
-        assert_eq!(methods, vec!["apple", "banana", "zebra"]);
-    }
-
-    #[test]
-    fn test_register_overwrites_existing() {
-        let registry = create_test_registry();
-        let handler1 = create_mock_handler();
-        let handler2 = create_mock_handler();
-
-        registry
-            .register("method", handler1, MethodMetadata::new("method"))
-            .unwrap();
-        assert_eq!(registry.len().unwrap(), 1);
-
-        registry
-            .register("method", handler2, MethodMetadata::new("method"))
-            .unwrap();
-        assert_eq!(registry.len().unwrap(), 1);
-    }
-
-    #[test]
-    fn test_remove_method() {
-        let registry = create_test_registry();
-        let handler = create_mock_handler();
-
-        registry
-            .register("method", handler, MethodMetadata::new("method"))
-            .unwrap();
-        assert_eq!(registry.len().unwrap(), 1);
-
-        let removed = registry.remove("method").unwrap();
-        assert!(removed);
-        assert_eq!(registry.len().unwrap(), 0);
-        assert!(registry.get("method").unwrap().is_none());
-    }
-
-    #[test]
-    fn test_remove_nonexistent_method() {
-        let registry = create_test_registry();
-        let removed = registry.remove("nonexistent").unwrap();
-        assert!(!removed);
-    }
-
-    #[test]
-    fn test_clear_registry() {
-        let registry = create_test_registry();
-        let handler = create_mock_handler();
-
-        registry
-            .register("method1", handler.clone(), MethodMetadata::new("method1"))
-            .unwrap();
-        registry
-            .register("method2", handler.clone(), MethodMetadata::new("method2"))
-            .unwrap();
-        registry
-            .register("method3", handler.clone(), MethodMetadata::new("method3"))
-            .unwrap();
-
-        assert_eq!(registry.len().unwrap(), 3);
-        registry.clear().unwrap();
-        assert_eq!(registry.len().unwrap(), 0);
-        assert!(registry.is_empty().unwrap());
-    }
-
-    #[test]
-    fn test_get_with_metadata() {
-        let registry = create_test_registry();
-        let handler = create_mock_handler();
-        let metadata = MethodMetadata::new("method").with_description("Test method");
-
-        registry.register("method", handler.clone(), metadata).unwrap();
-
-        let result = registry.get_with_metadata("method").unwrap();
-        assert!(result.is_some());
-
-        let (_retrieved_handler, retrieved_metadata) = result.unwrap();
-        assert_eq!(retrieved_metadata.name, "method");
-        assert_eq!(retrieved_metadata.description, Some("Test method".to_string()));
-    }
-
-    #[test]
-    fn test_list_all() {
-        let registry = create_test_registry();
-        let handler = create_mock_handler();
-
-        registry
-            .register("add", handler.clone(), MethodMetadata::new("add"))
-            .unwrap();
-        registry
-            .register("subtract", handler.clone(), MethodMetadata::new("subtract"))
-            .unwrap();
-
-        let all = registry.list_all().unwrap();
-        assert_eq!(all.len(), 2);
-
-        let names: Vec<String> = all.iter().map(|(name, _, _)| name.clone()).collect();
-        assert!(names.contains(&"add".to_string()));
-        assert!(names.contains(&"subtract".to_string()));
-    }
-
-    #[test]
-    fn test_clone_shares_registry() {
-        let registry1 = create_test_registry();
-        let handler = create_mock_handler();
-
-        registry1
-            .register("method", handler, MethodMetadata::new("method"))
-            .unwrap();
-
-        let registry2 = registry1.clone();
-        assert_eq!(registry2.len().unwrap(), 1);
-        assert!(registry2.contains("method").unwrap());
-    }
-
-    #[test]
-    fn test_metadata_builder_pattern() {
-        let metadata = MethodMetadata::new("test")
-            .with_description("Test description")
-            .with_tag("math")
-            .with_tag("utility")
-            .mark_deprecated();
-
-        assert_eq!(metadata.name, "test");
-        assert_eq!(metadata.description, Some("Test description".to_string()));
-        assert_eq!(metadata.tags, vec!["math", "utility"]);
-        assert!(metadata.deprecated);
-    }
-
-    #[test]
-    fn test_metadata_with_schemas() {
-        let params_schema = serde_json::json!({
-            "type": "object",
-            "properties": {
-                "x": { "type": "number" },
-                "y": { "type": "number" }
-            }
-        });
-
-        let result_schema = serde_json::json!({
-            "type": "number"
-        });
-
-        let metadata = MethodMetadata::new("add")
-            .with_params_schema(params_schema.clone())
-            .with_result_schema(result_schema.clone());
-
-        assert_eq!(metadata.params_schema, Some(params_schema));
-        assert_eq!(metadata.result_schema, Some(result_schema));
-    }
-
-    #[test]
-    fn test_metadata_with_examples() {
-        let example = MethodExample {
-            name: "example1".to_string(),
-            description: Some("Test example".to_string()),
-            params: serde_json::json!({"x": 1, "y": 2}),
-            result: serde_json::json!(3),
-        };
-
-        let metadata = MethodMetadata::new("add").with_example(example.clone());
-
-        assert_eq!(metadata.examples.len(), 1);
-        assert_eq!(metadata.examples[0].name, "example1");
-        assert_eq!(metadata.examples[0].description, Some("Test example".to_string()));
-    }
-
-    #[test]
-    fn test_registry_errors_on_poisoned_lock() {
-        let registry = create_test_registry();
-        let _ = panic::catch_unwind(|| {
-            let _guard = registry.methods.write().expect("lock write");
-            panic!("poison the lock");
-        });
-
-        let handler = create_mock_handler();
-        let err = registry
-            .register("method", handler, MethodMetadata::new("method"))
-            .expect_err("poisoned lock should error");
-        assert!(err.to_string().contains("lock was poisoned"));
-
-        match registry.get("method") {
-            Err(err) => assert!(err.to_string().contains("lock was poisoned")),
-            Ok(_) => panic!("expected poisoned lock error"),
-        }
-    }
-}

data/vendor/crates/spikard-http/src/jsonrpc/mod.rs

@@ -1,60 +0,0 @@
-//! JSON-RPC protocol support for Spikard HTTP
-//!
-//! This module provides JSON-RPC 2.0 protocol support including method registration,
-//! handler lookup, and metadata management.
-
-pub mod http_handler;
-pub mod method_registry;
-pub mod openrpc;
-pub mod protocol;
-pub mod router;
-
-use serde::{Deserialize, Serialize};
-
-pub use http_handler::{JsonRpcState, handle_jsonrpc};
-pub use method_registry::{JsonRpcMethodRegistry, MethodExample, MethodMetadata};
-pub use openrpc::generate_openrpc_spec;
-pub use protocol::{
-    JsonRpcErrorResponse, JsonRpcRequest, JsonRpcResponse, JsonRpcResponseType, error_codes, validate_method_name,
-};
-pub use router::{JsonRpcRequestOrBatch, JsonRpcRouter};
-
-/// JSON-RPC server configuration
-#[derive(Debug, Clone, Serialize, Deserialize)]
-pub struct JsonRpcConfig {
-    /// Enable JSON-RPC endpoint
-    #[serde(default)]
-    pub enabled: bool,
-    /// HTTP endpoint path for JSON-RPC requests (default: "/rpc")
-    #[serde(default = "default_endpoint_path")]
-    pub endpoint_path: String,
-    /// Enable batch request processing (default: true)
-    #[serde(default = "default_true")]
-    pub enable_batch: bool,
-    /// Maximum number of requests in a batch (default: 100)
-    #[serde(default = "default_max_batch_size")]
-    pub max_batch_size: usize,
-}
-
-fn default_endpoint_path() -> String {
-    "/rpc".to_string()
-}
-
-fn default_true() -> bool {
-    true
-}
-
-fn default_max_batch_size() -> usize {
-    100
-}
-
-impl Default for JsonRpcConfig {
-    fn default() -> Self {
-        Self {
-            enabled: true,
-            endpoint_path: default_endpoint_path(),
-            enable_batch: default_true(),
-            max_batch_size: default_max_batch_size(),
-        }
-    }
-}