spikard 0.1.2 → 0.2.1

data/lib/spikard/converters.rb

@@ -1,85 +1,85 @@
-# frozen_string_literal: true
-
-require_relative 'upload_file'
-
-module Spikard
-  # Type conversion utilities for handler parameters
-  #
-  # This module handles converting validated JSON data from Rust into Ruby types,
-  # particularly for UploadFile instances.
-  module Converters
-    module_function
-
-    # Check if a value looks like file metadata from Rust
-    #
-    # @param value [Object] Value to check
-    # @return [Boolean]
-    def file_metadata?(value)
-      value.is_a?(Hash) && value.key?('filename') && value.key?('content')
-    end
-
-    # Convert file metadata hash to UploadFile instance
-    #
-    # @param file_data [Hash] File metadata from Rust (filename, content, size, content_type)
-    # @return [UploadFile] UploadFile instance
-    def convert_file_metadata_to_upload_file(file_data)
-      UploadFile.new(
-        file_data['filename'],
-        file_data['content'],
-        content_type: file_data['content_type'],
-        size: file_data['size'],
-        headers: file_data['headers'],
-        content_encoding: file_data['content_encoding']
-      )
-    end
-
-    # Process handler parameters, converting file metadata to UploadFile instances
-    #
-    # This method recursively processes the body parameter, looking for file metadata
-    # structures and converting them to UploadFile instances.
-    #
-    # @param value [Object] The value to process (can be Hash, Array, or primitive)
-    # @return [Object] Processed value with UploadFile instances
-    def process_upload_file_fields(value)
-      # Handle nil
-      return value if value.nil?
-
-      # Handle primitives (String, Numeric, Boolean)
-      return value unless value.is_a?(Hash) || value.is_a?(Array)
-
-      # Handle arrays - recursively process each element
-      if value.is_a?(Array)
-        return value.map do |item|
-          # Check if this array item is file metadata
-          if file_metadata?(item)
-            convert_file_metadata_to_upload_file(item)
-          else
-            # Recursively process nested arrays/hashes
-            process_upload_file_fields(item)
-          end
-        end
-      end
-
-      # Handle hashes - check if it's file metadata first
-      return convert_file_metadata_to_upload_file(value) if file_metadata?(value)
-
-      # Otherwise, recursively process hash values
-      value.transform_values { |v| process_upload_file_fields(v) }
-    end
-
-    # Process handler body parameter, handling UploadFile conversion
-    #
-    # This is the main entry point for converting Rust-provided request data
-    # into Ruby types. It handles:
-    # - Single UploadFile
-    # - Arrays of UploadFile
-    # - Hashes with UploadFile fields
-    # - Nested structures
-    #
-    # @param body [Object] The body parameter from Rust (already JSON-parsed)
-    # @return [Object] Processed body with UploadFile instances
-    def convert_handler_body(body)
-      process_upload_file_fields(body)
-    end
-  end
-end
+# frozen_string_literal: true
+
+require_relative 'upload_file'
+
+module Spikard
+  # Type conversion utilities for handler parameters
+  #
+  # This module handles converting validated JSON data from Rust into Ruby types,
+  # particularly for UploadFile instances.
+  module Converters
+    module_function
+
+    # Check if a value looks like file metadata from Rust
+    #
+    # @param value [Object] Value to check
+    # @return [Boolean]
+    def file_metadata?(value)
+      value.is_a?(Hash) && value.key?('filename') && value.key?('content')
+    end
+
+    # Convert file metadata hash to UploadFile instance
+    #
+    # @param file_data [Hash] File metadata from Rust (filename, content, size, content_type)
+    # @return [UploadFile] UploadFile instance
+    def convert_file_metadata_to_upload_file(file_data)
+      UploadFile.new(
+        file_data['filename'],
+        file_data['content'],
+        content_type: file_data['content_type'],
+        size: file_data['size'],
+        headers: file_data['headers'],
+        content_encoding: file_data['content_encoding']
+      )
+    end
+
+    # Process handler parameters, converting file metadata to UploadFile instances
+    #
+    # This method recursively processes the body parameter, looking for file metadata
+    # structures and converting them to UploadFile instances.
+    #
+    # @param value [Object] The value to process (can be Hash, Array, or primitive)
+    # @return [Object] Processed value with UploadFile instances
+    def process_upload_file_fields(value)
+      # Handle nil
+      return value if value.nil?
+
+      # Handle primitives (String, Numeric, Boolean)
+      return value unless value.is_a?(Hash) || value.is_a?(Array)
+
+      # Handle arrays - recursively process each element
+      if value.is_a?(Array)
+        return value.map do |item|
+          # Check if this array item is file metadata
+          if file_metadata?(item)
+            convert_file_metadata_to_upload_file(item)
+          else
+            # Recursively process nested arrays/hashes
+            process_upload_file_fields(item)
+          end
+        end
+      end
+
+      # Handle hashes - check if it's file metadata first
+      return convert_file_metadata_to_upload_file(value) if file_metadata?(value)
+
+      # Otherwise, recursively process hash values
+      value.transform_values { |v| process_upload_file_fields(v) }
+    end
+
+    # Process handler body parameter, handling UploadFile conversion
+    #
+    # This is the main entry point for converting Rust-provided request data
+    # into Ruby types. It handles:
+    # - Single UploadFile
+    # - Arrays of UploadFile
+    # - Hashes with UploadFile fields
+    # - Nested structures
+    #
+    # @param body [Object] The body parameter from Rust (already JSON-parsed)
+    # @return [Object] Processed body with UploadFile instances
+    def convert_handler_body(body)
+      process_upload_file_fields(body)
+    end
+  end
+end

data/lib/spikard/handler_wrapper.rb

@@ -1,116 +1,116 @@
-# frozen_string_literal: true
-
-require_relative 'converters'
-
-module Spikard
-  # Handler wrapper utilities for automatic file metadata conversion
-  #
-  # Provides ergonomic handler patterns that automatically convert
-  # file metadata to UploadFile instances, eliminating boilerplate.
-  #
-  # @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|
-        converted_body = Converters.convert_handler_body(body)
-        handler.call(converted_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|
-        converted_body = Converters.convert_handler_body(body)
-        handler.call(params, query, converted_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|
-        converted_body = Converters.convert_handler_body(body)
-        context = {
-          params: params,
-          query: query,
-          body: converted_body
-        }
-        handler.call(context)
-      end
-    end
-  end
-end
+# frozen_string_literal: true
+
+require_relative 'converters'
+
+module Spikard
+  # Handler wrapper utilities for automatic file metadata conversion
+  #
+  # Provides ergonomic handler patterns that automatically convert
+  # file metadata to UploadFile instances, eliminating boilerplate.
+  #
+  # @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|
+        converted_body = Converters.convert_handler_body(body)
+        handler.call(converted_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|
+        converted_body = Converters.convert_handler_body(body)
+        handler.call(params, query, converted_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|
+        converted_body = Converters.convert_handler_body(body)
+        context = {
+          params: params,
+          query: query,
+          body: converted_body
+        }
+        handler.call(context)
+      end
+    end
+  end
+end

data/lib/spikard/provide.rb

@@ -0,0 +1,228 @@
+# 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))
+    # rubocop:disable Metrics/MethodLength
+    def provide(key, value = nil, depends_on: [], singleton: false, cacheable: true, &block)
+      key_str = key.to_s
+      @dependencies ||= {}
+
+      # Handle Provide wrapper instances
+      if value.is_a?(Provide)
+        provider = value
+        @dependencies[key_str] = {
+          type: :factory,
+          factory: provider.factory,
+          depends_on: provider.depends_on,
+          singleton: provider.singleton,
+          cacheable: provider.cacheable
+        }
+      elsif block
+        # Factory dependency (block form)
+        @dependencies[key_str] = {
+          type: :factory,
+          factory: block,
+          depends_on: Array(depends_on).map(&:to_s),
+          singleton: singleton,
+          cacheable: cacheable
+        }
+      else
+        # Value dependency
+        raise ArgumentError, 'Either provide a value or a block, not both' if value.nil?
+
+        @dependencies[key_str] = {
+          type: :value,
+          value: value,
+          singleton: true, # Values are always singleton
+          cacheable: true
+        }
+      end
+
+      self
+    end
+    # rubocop:enable Metrics/MethodLength
+
+    # Get all registered dependencies
+    #
+    # @return [Hash] Dictionary mapping dependency keys to their definitions
+    # @api private
+    def dependencies
+      @dependencies ||= {}
+      @dependencies.dup
+    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 }
+
+      # 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 = {}
+
+        injectable_params.each do |param_name|
+          dep_def = dependencies[param_name]
+          kwargs[param_name.to_sym] = resolve_dependency(dep_def, request)
+        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)
+      case dep_def[:type]
+      when :value
+        dep_def[:value]
+      when :factory
+        factory = dep_def[:factory]
+        dep_def[:depends_on]
+        # TODO: Implement nested dependency resolution when dependencies are provided
+        factory.call
+      end
+    end
+  end
+end