spikard 0.13.0 → 0.15.2

data/lib/spikard/grpc.rb

@@ -1,232 +0,0 @@
-# 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
-    STATUS_CODES = {
-      'OK' => '0',
-      'CANCELLED' => '1',
-      'UNKNOWN' => '2',
-      'INVALID_ARGUMENT' => '3',
-      'DEADLINE_EXCEEDED' => '4',
-      'NOT_FOUND' => '5',
-      'ALREADY_EXISTS' => '6',
-      'PERMISSION_DENIED' => '7',
-      'RESOURCE_EXHAUSTED' => '8',
-      'FAILED_PRECONDITION' => '9',
-      'ABORTED' => '10',
-      'OUT_OF_RANGE' => '11',
-      'UNIMPLEMENTED' => '12',
-      'INTERNAL' => '13',
-      'UNAVAILABLE' => '14',
-      'DATA_LOSS' => '15',
-      'UNAUTHENTICATED' => '16'
-    }.freeze
-
-    # 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)
-    # rubocop:disable Lint/EmptyClass -- Implementation in Rust via FFI
-    class Request
-      # These methods are implemented in Rust via Magnus FFI.
-      # See: crates/spikard-rb/src/grpc/handler.rs for implementation details.
-    end
-    # rubocop:enable Lint/EmptyClass
-
-    # 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 status_or_metadata [String, Integer, Hash<String, String>] Optional gRPC
-      #   status alias/code or metadata hash
-      # @param metadata [Hash<String, String>] Optional gRPC metadata when a status is provided
-      # @return [Response] A response with error status
-      #
-      # @example
-      #   response = Spikard::Grpc::Response.error('Method not implemented')
-      def self.error(message, status_or_metadata = {}, metadata = {})
-        status = nil
-
-        if status_or_metadata.is_a?(Hash)
-          metadata = status_or_metadata.merge(metadata)
-        else
-          status = status_or_metadata
-        end
-
-        error_metadata = metadata.transform_keys(&:to_s)
-        error_metadata['grpc-status'] =
-          normalize_status(status || error_metadata['grpc-status'] || 'INTERNAL')
-        error_metadata['grpc-message'] = message
-
-        response = new(payload: '')
-        response.metadata = error_metadata
-        response
-      end
-
-      def self.normalize_status(status)
-        case status
-        when Integer
-          status.to_s
-        when Symbol
-          normalize_status(status.to_s)
-        when String
-          normalized = status.strip
-          return normalized if /\A\d+\z/.match?(normalized)
-
-          STATUS_CODES.fetch(normalized.upcase) do
-            raise ArgumentError, "Unknown gRPC status: #{status}"
-          end
-        else
-          raise ArgumentError, "gRPC status must be a String, Symbol, or Integer (got #{status.class})"
-        end
-      end
-      private_class_method :normalize_status
-    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?
-
-        raise ArgumentError, 'Handler must respond to :handle_request' unless handler.respond_to?(:handle_request)
-
-        @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/handler_wrapper.rb

@@ -1,113 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'converters'
-
-module Spikard
-  # Handler wrapper utilities.
-  #
-  # UploadFile conversion now happens in the Rust binding, so these wrappers
-  # simply forward the already-converted body/params.
-  #
-  # @example Basic usage with body only
-  #   app.post('/upload', &wrap_body_handler do |body|
-  #     {
-  #       filename: body[:file].filename,
-  #       content: body[:file].read
-  #     }
-  #   end)
-  #
-  # @example With all parameters
-  #   app.post('/upload', &wrap_handler do |params, query, body|
-  #     {
-  #       id: params[:id],
-  #       search: query[:q],
-  #       file: body[:file].filename
-  #     }
-  #   end)
-  module HandlerWrapper
-    module_function
-
-    # Wrap a handler that receives only the request body
-    #
-    # Automatically converts file metadata in the body to UploadFile instances.
-    #
-    # @yield [body] Handler block that receives converted body
-    # @yieldparam body [Hash] Request body with file metadata converted to UploadFile
-    # @yieldreturn [Hash, Spikard::Response] Response data or Response object
-    # @return [Proc] Wrapped handler proc
-    #
-    # @example
-    #   app.post('/upload', &wrap_body_handler do |body|
-    #     { filename: body[:file].filename }
-    #   end)
-    def wrap_body_handler(&handler)
-      raise ArgumentError, 'block required for wrap_body_handler' unless handler
-
-      # Return a proc that matches the signature expected by Spikard::App
-      # The actual handler receives path params, query params, and body from Rust
-      lambda do |_params, _query, body|
-        handler.call(body)
-      end
-    end
-
-    # Wrap a handler that receives path params, query params, and body
-    #
-    # Automatically converts file metadata in the body to UploadFile instances.
-    #
-    # @yield [params, query, body] Handler block that receives all request data
-    # @yieldparam params [Hash] Path parameters
-    # @yieldparam query [Hash] Query parameters
-    # @yieldparam body [Hash] Request body with file metadata converted to UploadFile
-    # @yieldreturn [Hash, Spikard::Response] Response data or Response object
-    # @return [Proc] Wrapped handler proc
-    #
-    # @example
-    #   app.post('/users/{id}/upload', &wrap_handler do |params, query, body|
-    #     {
-    #       user_id: params[:id],
-    #       description: query[:desc],
-    #       file: body[:file].filename
-    #     }
-    #   end)
-    def wrap_handler(&handler)
-      raise ArgumentError, 'block required for wrap_handler' unless handler
-
-      lambda do |params, query, body|
-        handler.call(params, query, body)
-      end
-    end
-
-    # Wrap a handler that receives a context hash with all request data
-    #
-    # Automatically converts file metadata in the body to UploadFile instances.
-    # Useful when you want all request data in a single hash.
-    #
-    # @yield [context] Handler block that receives context hash
-    # @yieldparam context [Hash] Request context with:
-    #   - :params [Hash] Path parameters
-    #   - :query [Hash] Query parameters
-    #   - :body [Hash] Request body with file metadata converted to UploadFile
-    # @yieldreturn [Hash, Spikard::Response] Response data or Response object
-    # @return [Proc] Wrapped handler proc
-    #
-    # @example
-    #   app.post('/upload', &wrap_handler_with_context do |ctx|
-    #     {
-    #       file: ctx[:body][:file].filename,
-    #       query_params: ctx[:query]
-    #     }
-    #   end)
-    def wrap_handler_with_context(&handler)
-      raise ArgumentError, 'block required for wrap_handler_with_context' unless handler
-
-      lambda do |params, query, body|
-        context = {
-          params: params,
-          query: query,
-          body: body
-        }
-        handler.call(context)
-      end
-    end
-  end
-end

data/lib/spikard/provide.rb

@@ -1,315 +0,0 @@
-# frozen_string_literal: true
-
-module Spikard
-  # Wrapper class for dependency providers
-  #
-  # This class wraps factory functions and configuration for dependency injection.
-  # It provides a consistent API across Python, Node.js, and Ruby bindings.
-  #
-  # @example Factory with caching
-  #   app.provide("db", Spikard::Provide.new(method("create_db"), cacheable: true))
-  #
-  # @example Factory with dependencies
-  #   app.provide("auth", Spikard::Provide.new(
-  #     method("create_auth_service"),
-  #     depends_on: ["db", "cache"],
-  #     singleton: true
-  #   ))
-  class Provide
-    attr_reader :factory, :depends_on, :singleton, :cacheable
-
-    # Create a new dependency provider
-    #
-    # @param factory [Proc, Method] The factory function that creates the dependency value
-    # @param depends_on [Array<String, Symbol>] List of dependency keys this factory depends on
-    # @param singleton [Boolean] Whether to cache the value globally (default: false)
-    # @param cacheable [Boolean] Whether to cache the value per-request (default: true)
-    def initialize(factory, depends_on: [], singleton: false, cacheable: true)
-      @factory = factory
-      @depends_on = Array(depends_on).map(&:to_s)
-      @singleton = singleton
-      @cacheable = cacheable
-    end
-
-    # Check if the factory is async (based on method arity or other heuristics)
-    #
-    # @return [Boolean] True if the factory appears to be async
-    def async?
-      # Ruby doesn't have explicit async/await like Python/JS
-      # We could check if it returns a Thread or uses Fiber
-      false
-    end
-
-    # Check if the factory is an async generator
-    #
-    # @return [Boolean] True if the factory is an async generator
-    def async_generator?
-      false
-    end
-  end
-
-  # Dependency Injection support for Spikard applications
-  #
-  # Provides methods for registering and managing dependencies that can be
-  # automatically injected into route handlers.
-  #
-  # @example Registering a value dependency
-  #   app.provide("database_url", "postgresql://localhost/mydb")
-  #
-  # @example Registering a factory dependency
-  #   app.provide("db_pool", depends_on: ["database_url"]) do |database_url:|
-  #     ConnectionPool.new(database_url)
-  #   end
-  #
-  # @example Singleton dependency (shared across all requests)
-  #   app.provide("config", singleton: true) do
-  #     Config.load_from_file("config.yml")
-  #   end
-  #
-  # @example Using Provide wrapper
-  #   app.provide("db", Spikard::Provide.new(method("create_db"), cacheable: true))
-  module ProvideSupport
-    # Register a dependency in the DI container
-    #
-    # This method supports three patterns:
-    # 1. **Value dependency**: Pass a value directly (e.g., string, number, object)
-    # 2. **Factory dependency**: Pass a block that computes the value
-    # 3. **Provide wrapper**: Pass a Spikard::Provide instance
-    #
-    # @param key [String, Symbol] Unique identifier for the dependency
-    # @param value [Object, Provide, nil] Static value, Provide instance, or nil
-    # @param depends_on [Array<String, Symbol>] List of dependency keys this factory depends on
-    # @param singleton [Boolean] Whether to cache the value globally (default: false)
-    # @param cacheable [Boolean] Whether to cache the value per-request (default: true)
-    # @yield Optional factory block that receives dependencies as keyword arguments
-    # @yieldparam **deps [Hash] Resolved dependencies as keyword arguments
-    # @yieldreturn [Object] The computed dependency value
-    # @return [self] Returns self for method chaining
-    #
-    # @example Value dependency
-    #   app.provide("app_name", "MyApp")
-    #   app.provide("port", 8080)
-    #
-    # @example Factory with dependencies
-    #   app.provide("database", depends_on: ["config"]) do |config:|
-    #     Database.connect(config["db_url"])
-    #   end
-    #
-    # @example Singleton factory
-    #   app.provide("thread_pool", singleton: true) do
-    #     ThreadPool.new(size: 10)
-    #   end
-    #
-    # @example Non-cacheable factory (resolves every time)
-    #   app.provide("request_id", cacheable: false) do
-    #     SecureRandom.uuid
-    #   end
-    #
-    # @example Using Provide wrapper
-    #   app.provide("db", Spikard::Provide.new(method("create_db"), cacheable: true))
-    def provide(key, value = nil, depends_on: [], singleton: false, cacheable: true, &block)
-      key_str = key.to_s
-      registry = ensure_native_dependencies!
-
-      # Handle Provide wrapper instances
-      if value.is_a?(Provide)
-        registry.register_factory(key_str, value.factory, value.depends_on, value.singleton, value.cacheable)
-      elsif block
-        registry.register_factory(key_str, block, Array(depends_on).map(&:to_s), singleton, cacheable)
-      else
-        raise ArgumentError, 'Either provide a value or a block, not both' if value.nil?
-
-        registry.register_value(key_str, value)
-      end
-
-      self
-    end
-
-    # Get all registered dependencies
-    #
-    # @return [Hash] Dictionary mapping dependency keys to their definitions
-    # @api private
-    def dependencies
-      ensure_native_dependencies!
-    end
-
-    private
-
-    def ensure_native_dependencies!
-      registry = (@native_dependencies if instance_variable_defined?(:@native_dependencies) && @native_dependencies)
-      raise 'Spikard native dependency registry unavailable' unless registry
-
-      registry
-    end
-  end
-
-  # Internal helpers for resolving and caching DI dependencies.
-  module DependencyResolutionHelpers
-    UNRESOLVED_DEPENDENCY = Object.new.freeze
-
-    module_function
-
-    def build_resolution_context(*resolution_args)
-      dependencies, request_cache, singleton_cache, stack = resolution_args
-      {
-        dependencies:,
-        request_cache: request_cache || {},
-        singleton_cache: singleton_cache || {},
-        stack: stack || []
-      }
-    end
-
-    def resolve_factory_dependency(dep_def, request, context, resolver)
-      factory = dep_def[:factory]
-      depends_on = Array(dep_def[:depends_on]).map(&:to_s)
-      resolved_kwargs = resolver.call(
-        depends_on,
-        context[:dependencies],
-        request,
-        context[:request_cache],
-        context[:singleton_cache],
-        context[:stack]
-      )
-      invoke_factory(factory, depends_on, resolved_kwargs)
-    end
-
-    def fetch_dependency_definition(key, dependencies, stack)
-      dep_def = dependencies[key]
-      raise KeyError, "Missing dependency: #{key}" unless dep_def
-      raise ArgumentError, "Circular dependency detected: #{(stack + [key]).join(' -> ')}" if stack.include?(key)
-
-      dep_def
-    end
-
-    def lookup_cached_dependency(key, dep_def, request_cache, singleton_cache)
-      return singleton_cache[key] if dep_def[:singleton] && singleton_cache.key?(key)
-      return request_cache[key] if dep_def.fetch(:cacheable, true) && request_cache.key?(key)
-
-      UNRESOLVED_DEPENDENCY
-    end
-
-    def cache_dependency_value(key, dep_def, value, request_cache, singleton_cache)
-      singleton_cache[key] = value if dep_def[:singleton]
-      request_cache[key] = value if dep_def.fetch(:cacheable, true)
-    end
-
-    def invoke_factory(factory, depends_on, resolved_kwargs)
-      return factory.call if depends_on.empty?
-
-      parameters = factory.parameters
-      ordered_values = depends_on.map { |dependency_key| resolved_kwargs.fetch(dependency_key.to_sym) }
-
-      if parameters.any? { |type, _name| %i[key keyreq keyrest].include?(type) }
-        factory.call(**resolved_kwargs)
-      else
-        factory.call(*ordered_values)
-      end
-    end
-  end
-
-  # Dependency injection handler wrapper
-  #
-  # Wraps a route handler to inject dependencies based on parameter names.
-  # Dependencies are resolved from the DI container and passed as keyword arguments.
-  #
-  # @api private
-  module DIHandlerWrapper
-    # Wrap a handler to inject dependencies
-    #
-    # @param handler [Proc] The original route handler
-    # @param dependencies [Hash] Available dependencies from the app
-    # @return [Proc] Wrapped handler with DI support
-    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-    def self.wrap_handler(handler, dependencies)
-      # Extract parameter names from the handler
-      params = handler.parameters.map { |_type, name| name.to_s }
-      singleton_cache = {}
-
-      # Find which parameters match registered dependencies
-      injectable_params = params & dependencies.keys
-
-      if injectable_params.empty?
-        # No DI needed, return original handler
-        return handler
-      end
-
-      # Create wrapped handler that injects dependencies
-      lambda do |request|
-        # Build kwargs with injected dependencies
-        kwargs = {}
-        request_cache = {}
-
-        injectable_params.each do |param_name|
-          kwargs[param_name.to_sym] = resolve_dependency_by_key(
-            param_name,
-            dependencies,
-            request,
-            request_cache,
-            singleton_cache,
-            []
-          )
-        end
-
-        # Call original handler with injected dependencies
-        if handler.arity.zero?
-          # Handler takes no arguments (dependencies injected via closure or instance vars)
-          handler.call
-        elsif injectable_params.length == params.length
-          # All parameters are dependencies
-          handler.call(**kwargs)
-        else
-          # Mix of request data and dependencies
-          handler.call(request, **kwargs)
-        end
-      end
-    end
-    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
-
-    # Resolve a dependency definition
-    #
-    # @param dep_def [Hash] Dependency definition
-    # @param request [Hash] Request context (unused for now, future: per-request deps)
-    # @return [Object] Resolved dependency value
-    # @api private
-    def self.resolve_dependency(dep_def, request, *resolution_args)
-      context = DependencyResolutionHelpers.build_resolution_context(*resolution_args)
-      return dep_def[:value] if dep_def[:type] == :value
-      raise ArgumentError, "Unknown dependency type: #{dep_def[:type].inspect}" unless dep_def[:type] == :factory
-
-      DependencyResolutionHelpers.resolve_factory_dependency(
-        dep_def,
-        request,
-        context,
-        method(:resolve_factory_dependencies)
-      )
-    end
-
-    def self.resolve_dependency_by_key(key, dependencies, request, request_cache, singleton_cache, stack)
-      key = key.to_s
-      dep_def = DependencyResolutionHelpers.fetch_dependency_definition(key, dependencies, stack)
-      cached_value = DependencyResolutionHelpers.lookup_cached_dependency(key, dep_def, request_cache, singleton_cache)
-      return cached_value unless cached_value.equal?(DependencyResolutionHelpers::UNRESOLVED_DEPENDENCY)
-
-      value = resolve_dependency(dep_def, request, dependencies, request_cache, singleton_cache, stack + [key])
-      DependencyResolutionHelpers.cache_dependency_value(key, dep_def, value, request_cache, singleton_cache)
-      value
-    end
-
-    def self.resolve_factory_dependencies(depends_on, dependencies, request, request_cache, singleton_cache, stack)
-      return {} if depends_on.empty?
-
-      raise ArgumentError, 'Dependency registry is required for nested dependency resolution' unless dependencies
-
-      depends_on.to_h do |dependency_key|
-        [dependency_key.to_sym, resolve_dependency_by_key(
-          dependency_key,
-          dependencies,
-          request,
-          request_cache,
-          singleton_cache,
-          stack
-        )]
-      end
-    end
-  end
-end