spikard 0.7.5 → 0.8.0

data/ext/spikard_rb/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spikard-rb-ext"
-version = "0.7.5"
+version = "0.8.0"
 edition = "2024"
 license = "MIT"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]

data/lib/spikard/grpc.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Spikard
+  # gRPC support for Spikard
+  #
+  # This module provides Ruby bindings for handling gRPC requests through
+  # Spikard's Rust-based gRPC runtime. Handlers receive protobuf messages
+  # as binary strings and use the google-protobuf gem for serialization.
+  #
+  # @example Basic gRPC handler
+  #   require 'spikard/grpc'
+  #   require 'user_pb'  # Generated protobuf
+  #
+  #   class UserServiceHandler < Spikard::Grpc::Handler
+  #     def handle_request(request)
+  #       case request.method_name
+  #       when 'GetUser'
+  #         # Deserialize request
+  #         req = Example::GetUserRequest.decode(request.payload)
+  #
+  #         # Process request
+  #         user = Example::User.new(id: req.id, name: 'John Doe')
+  #
+  #         # Serialize response
+  #         Spikard::Grpc::Response.new(payload: Example::User.encode(user))
+  #       else
+  #         raise "Unknown method: #{request.method_name}"
+  #       end
+  #     end
+  #   end
+  module Grpc
+    # gRPC request object
+    #
+    # Represents an incoming gRPC request with service/method information
+    # and a binary protobuf payload.
+    #
+    # @!attribute [r] service_name
+    #   @return [String] Fully qualified service name (e.g., "mypackage.MyService")
+    # @!attribute [r] method_name
+    #   @return [String] Method name (e.g., "GetUser")
+    # @!attribute [r] payload
+    #   @return [String] Binary string containing serialized protobuf message
+    # @!attribute [r] metadata
+    #   @return [Hash<String, String>] gRPC metadata (headers)
+    class Request
+      # These methods are implemented in Rust via Magnus FFI
+      # See: crates/spikard-rb/src/grpc/handler.rs
+    end
+
+    # gRPC response object
+    #
+    # Used to return gRPC responses from handlers. The payload should be
+    # a binary string containing a serialized protobuf message.
+    #
+    # @example Creating a response
+    #   user = Example::User.new(id: 1, name: 'Alice')
+    #   response = Spikard::Grpc::Response.new(payload: Example::User.encode(user))
+    #
+    # @example Adding metadata
+    #   response = Spikard::Grpc::Response.new(payload: encoded_message)
+    #   response.metadata = { 'x-custom-header' => 'value' }
+    class Response
+      # @!attribute [w] metadata
+      #   @return [Hash<String, String>] gRPC metadata to include in response
+
+      # Create a new gRPC response
+      #
+      # @param payload [String] Binary string containing serialized protobuf message
+      # @raise [ArgumentError] if payload is not a String
+      #
+      # Note: Implementation in Rust (Magnus FFI)
+      # See: crates/spikard-rb/src/grpc/handler.rs
+
+      # Create an error response
+      #
+      # @param message [String] Error message
+      # @param metadata [Hash<String, String>] Optional gRPC metadata
+      # @return [Response] A response with error status
+      #
+      # @example
+      #   response = Spikard::Grpc::Response.error('Method not implemented')
+      def self.error(message, metadata = {})
+        error_metadata = metadata.merge(
+          'grpc-status' => 'INTERNAL',
+          'grpc-message' => message
+        )
+        response = new(payload: '')
+        response.metadata = error_metadata
+        response
+      end
+    end
+
+    # Base class for gRPC handlers
+    #
+    # Subclass this to implement gRPC service handlers. Override
+    # {#handle_request} to process incoming requests.
+    #
+    # @example Implementing a handler
+    #   class MyServiceHandler < Spikard::Grpc::Handler
+    #     def handle_request(request)
+    #       case request.method_name
+    #       when 'MethodOne'
+    #         # Handle MethodOne
+    #         req = MyPackage::MethodOneRequest.decode(request.payload)
+    #         resp = MyPackage::MethodOneResponse.new(...)
+    #         Spikard::Grpc::Response.new(payload: MyPackage::MethodOneResponse.encode(resp))
+    #       when 'MethodTwo'
+    #         # Handle MethodTwo
+    #         # ...
+    #       else
+    #         raise "Unknown method: #{request.method_name}"
+    #       end
+    #     end
+    #   end
+    class Handler
+      # Handle a gRPC request
+      #
+      # This method must be overridden by subclasses to implement the
+      # actual request handling logic.
+      #
+      # @param request [Spikard::Grpc::Request] The incoming gRPC request
+      # @return [Spikard::Grpc::Response] The gRPC response
+      # @raise [NotImplementedError] if not overridden by subclass
+      def handle_request(request)
+        raise NotImplementedError, "#{self.class}#handle_request must be implemented"
+      end
+    end
+
+    # Service registry for gRPC handlers
+    #
+    # Manages registration and lookup of gRPC service handlers.
+    # Handlers are registered by service name and method.
+    #
+    # @example Registering a handler
+    #   service = Spikard::Grpc::Service.new
+    #   handler = UserServiceHandler.new
+    #   service.register_handler('mypackage.UserService', handler)
+    class Service
+      def initialize
+        @handlers = {}
+      end
+
+      # Register a gRPC handler for a service
+      #
+      # @param service_name [String] Fully qualified service name
+      # @param handler [Spikard::Grpc::Handler] Handler instance
+      # @raise [ArgumentError] if service_name is invalid or handler doesn't respond to handle_request
+      def register_handler(service_name, handler)
+        raise ArgumentError, 'Service name cannot be empty' if service_name.nil? || service_name.empty?
+
+        unless handler.respond_to?(:handle_request)
+          raise ArgumentError, "Handler must respond to :handle_request"
+        end
+
+        @handlers[service_name] = handler
+      end
+
+      # Get a handler by service name
+      #
+      # @param service_name [String] Fully qualified service name
+      # @return [Spikard::Grpc::Handler, nil] The handler or nil if not found
+      def get_handler(service_name)
+        @handlers[service_name]
+      end
+
+      # Get all registered service names
+      #
+      # @return [Array<String>] List of registered service names
+      def service_names
+        @handlers.keys
+      end
+
+      # Check if a service is registered
+      #
+      # @param service_name [String] Fully qualified service name
+      # @return [Boolean] true if the service is registered
+      def registered?(service_name)
+        @handlers.key?(service_name)
+      end
+    end
+  end
+end

data/lib/spikard/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Spikard
-  VERSION = '0.7.5'
+  VERSION = '0.8.0'
 end

data/lib/spikard.rb

@@ -17,6 +17,7 @@ require_relative 'spikard/background'
 require_relative 'spikard/schema'
 require_relative 'spikard/websocket'
 require_relative 'spikard/sse'
+require_relative 'spikard/grpc'
 require_relative 'spikard/upload_file'
 require_relative 'spikard/converters'
 require_relative 'spikard/provide'

data/vendor/crates/spikard-bindings-shared/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spikard-bindings-shared"
-version = "0.7.5"
+version = "0.8.0"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 license = "MIT"
@@ -18,6 +18,7 @@ spikard-http = { path = "../spikard-http" }
 tracing = "0.1"
 http = "1.4"
 http-body-util = "0.1"
+tonic = "0.14"
 
 [features]
 default = []

data/vendor/crates/spikard-bindings-shared/src/grpc_metadata.rs

@@ -0,0 +1,197 @@
+//! Shared gRPC metadata utilities
+//!
+//! This module provides common metadata conversion functions used across all
+//! language bindings (Python, Node.js, Ruby, PHP) to avoid code duplication.
+
+use std::collections::HashMap;
+use tonic::metadata::{MetadataMap, MetadataKey, MetadataValue};
+
+/// Extract metadata from gRPC MetadataMap to a simple HashMap.
+///
+/// This function converts gRPC metadata to a language-agnostic HashMap format
+/// that can be easily passed to language bindings. Only ASCII metadata is
+/// included; binary metadata is skipped with optional logging.
+///
+/// # Arguments
+///
+/// * `metadata` - The gRPC MetadataMap to extract from
+/// * `log_binary_skip` - Whether to log when binary metadata is skipped
+///
+/// # Returns
+///
+/// A HashMap containing all ASCII metadata key-value pairs
+///
+/// # Examples
+///
+/// ```
+/// use tonic::metadata::MetadataMap;
+/// use spikard_bindings_shared::grpc_metadata::extract_metadata_to_hashmap;
+///
+/// let mut metadata = MetadataMap::new();
+/// metadata.insert("authorization", "Bearer token123".parse().unwrap());
+///
+/// let map = extract_metadata_to_hashmap(&metadata, false);
+/// assert_eq!(map.get("authorization"), Some(&"Bearer token123".to_string()));
+/// ```
+pub fn extract_metadata_to_hashmap(metadata: &MetadataMap, log_binary_skip: bool) -> HashMap<String, String> {
+    let mut map = HashMap::new();
+
+    for key_value in metadata.iter() {
+        match key_value {
+            tonic::metadata::KeyAndValueRef::Ascii(key, value) => {
+                let key_str = key.as_str().to_string();
+                let value_str = value.to_str().unwrap_or("").to_string();
+                map.insert(key_str, value_str);
+            }
+            tonic::metadata::KeyAndValueRef::Binary(key, _value) => {
+                // Binary metadata is skipped as we only support string values
+                if log_binary_skip {
+                    tracing::debug!("Skipping binary metadata key: {}", key.as_str());
+                }
+            }
+        }
+    }
+
+    map
+}
+
+/// Convert a HashMap to gRPC MetadataMap.
+///
+/// This function converts a language-agnostic HashMap into a gRPC MetadataMap
+/// that can be used in responses. All keys and values are validated and errors
+/// are returned if any are invalid.
+///
+/// # Arguments
+///
+/// * `map` - The HashMap to convert
+///
+/// # Returns
+///
+/// A Result containing the MetadataMap or an error message
+///
+/// # Errors
+///
+/// Returns an error if:
+/// - A metadata key is invalid (contains invalid characters)
+/// - A metadata value is invalid (contains invalid characters)
+///
+/// # Examples
+///
+/// ```
+/// use std::collections::HashMap;
+/// use spikard_bindings_shared::grpc_metadata::hashmap_to_metadata;
+///
+/// let mut map = HashMap::new();
+/// map.insert("content-type".to_string(), "application/grpc".to_string());
+///
+/// let metadata = hashmap_to_metadata(&map).unwrap();
+/// assert!(metadata.contains_key("content-type"));
+/// ```
+pub fn hashmap_to_metadata(map: &HashMap<String, String>) -> Result<MetadataMap, String> {
+    let mut metadata = MetadataMap::new();
+
+    for (key, value) in map {
+        let metadata_key = MetadataKey::from_bytes(key.as_bytes())
+            .map_err(|err| format!("Invalid metadata key '{}': {}", key, err))?;
+
+        let metadata_value = MetadataValue::try_from(value)
+            .map_err(|err| format!("Invalid metadata value for '{}': {}", key, err))?;
+
+        metadata.insert(metadata_key, metadata_value);
+    }
+
+    Ok(metadata)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn test_extract_empty_metadata() {
+        let metadata = MetadataMap::new();
+        let map = extract_metadata_to_hashmap(&metadata, false);
+        assert!(map.is_empty());
+    }
+
+    #[test]
+    fn test_extract_single_metadata() {
+        let mut metadata = MetadataMap::new();
+        metadata.insert("content-type", "application/grpc".parse().unwrap());
+
+        let map = extract_metadata_to_hashmap(&metadata, false);
+        assert_eq!(map.len(), 1);
+        assert_eq!(map.get("content-type"), Some(&"application/grpc".to_string()));
+    }
+
+    #[test]
+    fn test_extract_multiple_metadata() {
+        let mut metadata = MetadataMap::new();
+        metadata.insert("content-type", "application/grpc".parse().unwrap());
+        metadata.insert("authorization", "Bearer token123".parse().unwrap());
+        metadata.insert("x-custom-header", "custom-value".parse().unwrap());
+
+        let map = extract_metadata_to_hashmap(&metadata, false);
+        assert_eq!(map.len(), 3);
+        assert_eq!(map.get("content-type"), Some(&"application/grpc".to_string()));
+        assert_eq!(map.get("authorization"), Some(&"Bearer token123".to_string()));
+        assert_eq!(map.get("x-custom-header"), Some(&"custom-value".to_string()));
+    }
+
+    #[test]
+    fn test_hashmap_to_metadata_empty() {
+        let map = HashMap::new();
+        let metadata = hashmap_to_metadata(&map).unwrap();
+        assert_eq!(metadata.len(), 0);
+    }
+
+    #[test]
+    fn test_hashmap_to_metadata_single() {
+        let mut map = HashMap::new();
+        map.insert("content-type".to_string(), "application/grpc".to_string());
+
+        let metadata = hashmap_to_metadata(&map).unwrap();
+        assert_eq!(metadata.len(), 1);
+        assert!(metadata.contains_key("content-type"));
+    }
+
+    #[test]
+    fn test_hashmap_to_metadata_multiple() {
+        let mut map = HashMap::new();
+        map.insert("content-type".to_string(), "application/grpc".to_string());
+        map.insert("authorization".to_string(), "Bearer token".to_string());
+
+        let metadata = hashmap_to_metadata(&map).unwrap();
+        assert_eq!(metadata.len(), 2);
+        assert!(metadata.contains_key("content-type"));
+        assert!(metadata.contains_key("authorization"));
+    }
+
+    #[test]
+    fn test_hashmap_to_metadata_invalid_key() {
+        let mut map = HashMap::new();
+        map.insert("invalid\nkey".to_string(), "value".to_string());
+
+        let result = hashmap_to_metadata(&map);
+        assert!(result.is_err());
+        assert!(result.unwrap_err().contains("Invalid metadata key"));
+    }
+
+    #[test]
+    fn test_roundtrip_metadata() {
+        let mut original_metadata = MetadataMap::new();
+        original_metadata.insert("content-type", "application/grpc".parse().unwrap());
+        original_metadata.insert("x-custom", "value".parse().unwrap());
+
+        // Extract to HashMap
+        let map = extract_metadata_to_hashmap(&original_metadata, false);
+
+        // Convert back to MetadataMap
+        let new_metadata = hashmap_to_metadata(&map).unwrap();
+
+        // Verify both have the same entries
+        assert_eq!(new_metadata.len(), original_metadata.len());
+        assert!(new_metadata.contains_key("content-type"));
+        assert!(new_metadata.contains_key("x-custom"));
+    }
+}

data/vendor/crates/spikard-bindings-shared/src/lib.rs

@@ -8,6 +8,7 @@ pub mod config_extractor;
 pub mod conversion_traits;
 pub mod di_traits;
 pub mod error_response;
+pub mod grpc_metadata;
 pub mod handler_base;
 pub mod lifecycle_base;
 pub mod lifecycle_executor;
@@ -18,6 +19,7 @@ pub mod validation_helpers;
 pub use config_extractor::{ConfigExtractor, ConfigSource};
 pub use di_traits::{FactoryDependencyAdapter, ValueDependencyAdapter};
 pub use error_response::ErrorResponseBuilder;
+pub use grpc_metadata::{extract_metadata_to_hashmap, hashmap_to_metadata};
 pub use handler_base::{HandlerError, HandlerExecutor, LanguageHandler};
 pub use lifecycle_executor::{
     HookResultData, LanguageLifecycleHook, LifecycleExecutor, RequestModifications, extract_body,

data/vendor/crates/spikard-core/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spikard-core"
-version = "0.7.5"
+version = "0.8.0"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 license = "MIT"

data/vendor/crates/spikard-http/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "spikard-http"
-version = "0.7.5"
+version = "0.8.0"
 edition = "2024"
 authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
 license = "MIT"
@@ -50,6 +50,10 @@ cookie = "0.18"
 base64 = "0.22.1"
 flate2 = { version = "=1.1.5", default-features = false, features = ["rust_backend"] }
 brotli = "8.0"
+tonic = { version = "0.14", features = ["transport", "codegen", "gzip"] }
+prost = "0.14"
+prost-types = "0.14"
+h2 = "0.4"
 
 
 [features]