spikard 0.1.0

data/lib/spikard/schema.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ModuleLength
+module Spikard
+  # Schema extraction helpers for Ruby type systems
+  #
+  # Supports:
+  # - Plain JSON Schema (Hash)
+  # - Dry::Schema with :json_schema extension
+  # - Dry::Struct (Dry-Types)
+  #
+  # @example With Dry::Schema
+  #   require 'dry-schema'
+  #   Dry::Schema.load_extensions(:json_schema)
+  #
+  #   UserSchema = Dry::Schema.JSON do
+  #     required(:email).filled(:str?)
+  #     required(:age).filled(:int?)
+  #   end
+  #
+  #   schema = Spikard::Schema.extract_json_schema(UserSchema)
+  #
+  # @example With Dry::Struct
+  #   require 'dry-struct'
+  #
+  #   class User < Dry::Struct
+  #     attribute :email, Types::String
+  #     attribute :age, Types::Integer
+  #   end
+  #
+  #   schema = Spikard::Schema.extract_json_schema(User)
+  #
+  # @example With plain JSON Schema
+  #   schema_hash = {
+  #     "type" => "object",
+  #     "properties" => {
+  #       "email" => { "type" => "string" },
+  #       "age" => { "type" => "integer" }
+  #     },
+  #     "required" => ["email", "age"]
+  #   }
+  #
+  #   schema = Spikard::Schema.extract_json_schema(schema_hash)
+  module Schema
+    # rubocop:disable Metrics/ClassLength
+    class << self
+      # Extract JSON Schema from various Ruby schema sources
+      #
+      # @param schema_source [Object] The schema source (Hash, Dry::Schema, Dry::Struct class)
+      # @return [Hash, nil] JSON Schema hash or nil if extraction fails
+      def extract_json_schema(schema_source)
+        return nil if schema_source.nil?
+
+        # 1. Check if plain JSON Schema hash
+        return schema_source if schema_source.is_a?(Hash) && json_schema_hash?(schema_source)
+
+        # 2. Check for Dry::Schema with json_schema extension
+        return extract_from_dry_schema(schema_source) if dry_schema?(schema_source)
+
+        # 3. Check for Dry::Struct (Dry-Types)
+        return extract_from_dry_struct(schema_source) if dry_struct_class?(schema_source)
+
+        # 4. Unknown type
+        warn "Spikard: Unable to extract JSON Schema from #{schema_source.class}. " \
+             'Supported types: Hash, Dry::Schema, Dry::Struct'
+        nil
+      end
+
+      private
+
+      # Check if object is a plain JSON Schema hash
+      def json_schema_hash?(obj)
+        return false unless obj.is_a?(Hash)
+
+        # Must have 'type' key or '$schema' key
+        obj.key?('type') || obj.key?('$schema') || obj.key?(:type) || obj.key?(:$schema)
+      end
+
+      # Check if object is a Dry::Schema
+      def dry_schema?(obj)
+        defined?(Dry::Schema::Processor) && obj.is_a?(Dry::Schema::Processor)
+      end
+
+      # Check if object is a Dry::Struct class
+      def dry_struct_class?(obj)
+        return false unless obj.is_a?(Class)
+
+        defined?(Dry::Struct) && obj < Dry::Struct
+      end
+
+      # Extract JSON Schema from Dry::Schema
+      def extract_from_dry_schema(schema)
+        unless schema.respond_to?(:json_schema)
+          warn 'Spikard: Dry::Schema instance does not have json_schema method. ' \
+               'Did you load the :json_schema extension? ' \
+               'Add: Dry::Schema.load_extensions(:json_schema)'
+          return nil
+        end
+
+        begin
+          schema.json_schema
+        rescue StandardError => e
+          warn "Spikard: Failed to extract JSON Schema from Dry::Schema: #{e.message}"
+          nil
+        end
+      end
+
+      # Extract JSON Schema from Dry::Struct class
+      # rubocop:disable Metrics/MethodLength
+      def extract_from_dry_struct(struct_class)
+        # Dry::Struct doesn't have built-in JSON Schema export
+        # We need to manually build it from the attribute schema
+
+        properties = {}
+        required = []
+
+        struct_class.schema.each do |key, type_definition|
+          # Extract attribute name
+          attr_name = key.to_s
+
+          # Determine if required (non-optional)
+          is_required = !type_definition.optional?
+          required << attr_name if is_required
+
+          # Convert Dry::Types to JSON Schema type
+          json_type = dry_type_to_json_schema(type_definition)
+          properties[attr_name] = json_type if json_type
+        end
+
+        {
+          'type' => 'object',
+          'properties' => properties,
+          'required' => required
+        }
+      rescue StandardError => e
+        warn "Spikard: Failed to extract JSON Schema from Dry::Struct: #{e.message}"
+        nil
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Convert Dry::Types type to JSON Schema type
+      def dry_type_to_json_schema(type_def)
+        schema = base_schema_for(type_def)
+        apply_metadata_constraints(schema, type_def)
+      rescue StandardError
+        { 'type' => 'object' }
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def base_schema_for(type_def)
+        type_class = type_def.primitive.to_s
+        case type_class
+        when 'String' then { 'type' => 'string' }
+        when 'Integer' then { 'type' => 'integer' }
+        when 'Float', 'BigDecimal' then { 'type' => 'number' }
+        when 'TrueClass', 'FalseClass' then { 'type' => 'boolean' }
+        when 'Array'
+          {
+            'type' => 'array',
+            'items' => infer_array_items_schema(type_def)
+          }
+        when 'Hash'
+          { 'type' => 'object', 'additionalProperties' => true }
+        when 'NilClass' then { 'type' => 'null' }
+        else
+          { 'type' => 'object' }
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def infer_array_items_schema(type_def)
+        if type_def.respond_to?(:member) && type_def.member
+          dry_type_to_json_schema(type_def.member)
+        else
+          {}
+        end
+      rescue StandardError
+        {}
+      end
+
+      def apply_metadata_constraints(schema, type_def)
+        metadata = extract_metadata(type_def)
+        return schema if metadata.empty?
+
+        schema = apply_enum_and_format(schema, metadata)
+        apply_numeric_constraints(schema, metadata)
+      end
+
+      def apply_enum_and_format(schema, metadata)
+        enum_values = metadata[:enum] || metadata['enum']
+        schema['enum'] = Array(enum_values) if enum_values
+
+        format_value = metadata[:format] || metadata['format']
+        schema['format'] = format_value.to_s if format_value
+
+        description = metadata[:description] || metadata['description']
+        schema['description'] = description.to_s if description
+        schema
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def apply_numeric_constraints(schema, metadata)
+        mapping = {
+          min_size: 'minLength',
+          max_size: 'maxLength',
+          min_items: 'minItems',
+          max_items: 'maxItems',
+          min: 'minimum',
+          max: 'maximum',
+          gte: 'minimum',
+          lte: 'maximum',
+          gt: 'exclusiveMinimum',
+          lt: 'exclusiveMaximum'
+        }
+
+        mapping.each do |meta_key, json_key|
+          value = metadata[meta_key] || metadata[meta_key.to_s]
+          next unless value
+
+          schema[json_key] = value
+        end
+        schema
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      def extract_metadata(type_def)
+        return {} unless type_def.respond_to?(:meta) || type_def.respond_to?(:options)
+
+        if type_def.respond_to?(:meta) && type_def.meta
+          type_def.meta
+        elsif type_def.respond_to?(:options) && type_def.options.is_a?(Hash)
+          type_def.options
+        else
+          {}
+        end
+      rescue StandardError
+        {}
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end
+# rubocop:enable Metrics/ModuleLength

data/lib/spikard/sse.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+module Spikard
+  # Represents a Server-Sent Event.
+  #
+  # @!attribute [rw] data
+  #   @return [Hash] Event data (will be JSON serialized)
+  # @!attribute [rw] event_type
+  #   @return [String, nil] Optional event type
+  # @!attribute [rw] id
+  #   @return [String, nil] Optional event ID for client reconnection support
+  # @!attribute [rw] retry_ms
+  #   @return [Integer, nil] Optional retry timeout in milliseconds
+  class SseEvent
+    attr_accessor :data, :event_type, :id, :retry_ms
+
+    # Create a new SSE event.
+    #
+    # @param data [Hash] Event data (will be JSON serialized)
+    # @param event_type [String, nil] Optional event type
+    # @param id [String, nil] Optional event ID for client reconnection support
+    # @param retry_ms [Integer, nil] Optional retry timeout in milliseconds
+    def initialize(data:, event_type: nil, id: nil, retry_ms: nil)
+      @data = data
+      @event_type = event_type
+      @id = id
+      @retry_ms = retry_ms
+    end
+
+    # Convert to hash for JSON serialization.
+    #
+    # @return [Hash] Hash representation of the event
+    def to_h
+      {
+        data: @data,
+        event_type: @event_type,
+        id: @id,
+        retry: @retry_ms
+      }.compact
+    end
+  end
+
+  # Base class for SSE event producers.
+  #
+  # Implement this class to generate Server-Sent Events.
+  #
+  # @example
+  #   class NotificationProducer < Spikard::SseEventProducer
+  #     def initialize
+  #       @count = 0
+  #     end
+  #
+  #     def next_event
+  #       sleep 1  # Wait 1 second between events
+  #
+  #       return nil if @count >= 10  # End stream after 10 events
+  #
+  #       event = Spikard::SseEvent.new(
+  #         data: { message: "Notification #{@count}" },
+  #         event_type: 'notification',
+  #         id: @count.to_s
+  #       )
+  #       @count += 1
+  #       event
+  #     end
+  #
+  #     def on_connect
+  #       puts "Client connected to SSE stream"
+  #     end
+  #
+  #     def on_disconnect
+  #       puts "Client disconnected from SSE stream"
+  #     end
+  #   end
+  #
+  #   app = Spikard::App.new
+  #
+  #   app.sse('/notifications') do
+  #     NotificationProducer.new
+  #   end
+  #
+  #   app.run
+  class SseEventProducer
+    # Generate the next event.
+    #
+    # This method is called repeatedly to produce the event stream.
+    #
+    # @return [SseEvent, nil] SseEvent when an event is ready, or nil to end the stream.
+    def next_event
+      raise NotImplementedError, "#{self.class.name} must implement #next_event"
+    end
+
+    # Called when a client connects to the SSE endpoint.
+    #
+    # Override this method to perform initialization when a client connects.
+    #
+    # @return [void]
+    def on_connect
+      # Optional hook - default implementation does nothing
+    end
+
+    # Called when a client disconnects from the SSE endpoint.
+    #
+    # Override this method to perform cleanup when a client disconnects.
+    #
+    # @return [void]
+    def on_disconnect
+      # Optional hook - default implementation does nothing
+    end
+  end
+end

data/lib/spikard/streaming_response.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Spikard
+  # Represents a streaming HTTP response made of chunks produced lazily.
+  class StreamingResponse
+    attr_reader :stream, :status_code, :headers
+
+    def initialize(stream, status_code: 200, headers: nil)
+      unless stream.respond_to?(:next) || stream.respond_to?(:each)
+        raise ArgumentError, 'StreamingResponse requires an object responding to #next or #each'
+      end
+
+      @stream = stream.respond_to?(:to_enum) ? stream.to_enum : stream
+      @status_code = Integer(status_code || 200)
+      header_hash = headers || {}
+      @headers = header_hash.each_with_object({}) do |(key, value), memo|
+        memo[String(key)] = String(value)
+      end
+    end
+  end
+end

data/lib/spikard/testing.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Spikard
+  # Testing helpers that wrap the native Ruby extension.
+  module Testing
+    module_function
+
+    def create_test_client(app, config: nil)
+      unless defined?(Spikard::Native::TestClient)
+        raise LoadError, 'Spikard native test client is not available. Build the native extension before running tests.'
+      end
+
+      # Allow generated apps to stash a test config
+      if config.nil? && app.instance_variable_defined?(:@__spikard_test_config)
+        config = app.instance_variable_get(:@__spikard_test_config)
+      end
+
+      # Use default config if none provided
+      config ||= Spikard::ServerConfig.new
+
+      routes_json = JSON.generate(app.route_metadata)
+      handlers = app.handler_map.transform_keys(&:to_sym)
+      ws_handlers = app.websocket_handlers || {}
+      sse_producers = app.sse_producers || {}
+      native = Spikard::Native::TestClient.new(routes_json, handlers, config, ws_handlers, sse_producers)
+      TestClient.new(native)
+    end
+
+    # High level wrapper around the native test client.
+    class TestClient
+      def initialize(native)
+        @native = native
+      end
+
+      # Factory method for creating test client from an app
+      def self.new(app_or_native, config: nil)
+        # If passed a native client directly, use it
+        return super(app_or_native) if app_or_native.is_a?(Spikard::Native::TestClient)
+
+        # Otherwise, create test client from app
+        Spikard::Testing.create_test_client(app_or_native, config: config)
+      end
+
+      def request(method, path, **options)
+        payload = @native.request(method.to_s.upcase, path, options)
+        Response.new(payload)
+      end
+
+      def websocket(path)
+        native_ws = @native.websocket(path)
+        WebSocketTestConnection.new(native_ws)
+      end
+
+      def sse(path)
+        native_sse = @native.sse(path)
+        SseStream.new(native_sse)
+      end
+
+      def close
+        @native.close
+      end
+
+      %w[get post put patch delete head options trace].each do |verb|
+        define_method(verb) do |path, **options|
+          request(verb.upcase, path, **options)
+        end
+      end
+    end
+
+    # WebSocket test connection wrapper
+    class WebSocketTestConnection
+      def initialize(native_ws)
+        @native_ws = native_ws
+      end
+
+      def send_text(text)
+        @native_ws.send_text(JSON.generate(text))
+      end
+
+      def send_json(obj)
+        @native_ws.send_json(obj)
+      end
+
+      def receive_text
+        raw = @native_ws.receive_text
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        raw
+      end
+
+      def receive_json
+        @native_ws.receive_json
+      end
+
+      def receive_bytes
+        receive_text
+      end
+
+      def receive_message
+        native_msg = @native_ws.receive_message
+        WebSocketMessage.new(native_msg)
+      end
+
+      def close
+        @native_ws.close
+      end
+    end
+
+    # WebSocket message wrapper
+    class WebSocketMessage
+      def initialize(native_msg)
+        @native_msg = native_msg
+      end
+
+      def as_text
+        raw = @native_msg.as_text
+        return unless raw
+
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        raw
+      end
+
+      def as_json
+        @native_msg.as_json
+      end
+
+      def as_binary
+        @native_msg.as_binary
+      end
+
+      def close?
+        @native_msg.is_close
+      end
+    end
+
+    # SSE stream wrapper
+    class SseStream
+      def initialize(native_sse)
+        @native_sse = native_sse
+      end
+
+      def body
+        @native_sse.body
+      end
+
+      def events
+        parsed_chunks.map { |chunk| InlineSseEvent.new(chunk) }
+      end
+
+      def events_as_json
+        parsed_chunks.filter_map do |chunk|
+          JSON.parse(chunk)
+        rescue JSON::ParserError
+          nil
+        end
+      end
+
+      private
+
+      # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+      def parsed_chunks
+        raw = body.to_s.gsub("\r\n", "\n")
+        events = []
+        current = []
+
+        raw.each_line do |line|
+          stripped = line.chomp
+          if stripped.start_with?('data:')
+            current << stripped[5..].strip
+          elsif stripped.empty?
+            unless current.empty?
+              data = current.join("\n").strip
+              events << data unless data.empty?
+              current = []
+            end
+          end
+        end
+
+        unless current.empty?
+          data = current.join("\n").strip
+          events << data unless data.empty?
+        end
+
+        events
+      end
+      # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+    end
+
+    # SSE event wrapper
+    class SseEvent
+      def initialize(native_event)
+        @native_event = native_event
+      end
+
+      def data
+        @native_event.data
+      end
+
+      def as_json
+        @native_event.as_json
+      end
+    end
+
+    # Lightweight wrapper for parsed SSE events backed by strings.
+    class InlineSseEvent
+      attr_reader :data
+
+      def initialize(data)
+        @data = data
+      end
+
+      def as_json
+        JSON.parse(@data)
+      end
+    end
+  end
+end