spikard 0.4.0-arm64-darwin-23

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,44 @@
+# frozen_string_literal: true
+
+module Spikard
+  # Represents a streaming HTTP response made of chunks produced lazily.
+  class StreamingResponse
+    attr_reader :stream, :status_code, :headers, :native_response
+
+    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
+
+      rebuild_native!
+    end
+
+    def to_native_response
+      @native_response
+    end
+
+    private
+
+    def rebuild_native!
+      ensure_native!
+      @native_response = Spikard::Native.build_streaming_response(@stream, @status_code, @headers)
+      return unless @native_response
+
+      @status_code = @native_response.status_code
+      @headers = @native_response.headers
+    end
+
+    def ensure_native!
+      return if defined?(Spikard::Native) && Spikard::Native.respond_to?(:build_streaming_response)
+
+      raise 'Spikard native extension is not loaded'
+    end
+  end
+end

data/lib/spikard/testing.rb

@@ -0,0 +1,221 @@
+# 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 = app.normalized_routes_json
+      handlers = app.handler_map.transform_keys(&:to_sym)
+      ws_handlers = app.websocket_handlers || {}
+      sse_producers = app.sse_producers || {}
+      dependencies = app.dependencies || {}
+      native = Spikard::Native::TestClient.new(routes_json, handlers, config, ws_handlers, sse_producers, dependencies)
+      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

data/lib/spikard/upload_file.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+require 'stringio'
+require 'base64'
+
+module Spikard
+  # File upload handling for multipart/form-data requests
+  #
+  # This class provides an interface for handling file uploads,
+  # designed to be compatible with Rails patterns while optimized
+  # for Spikard's Rust-backed request processing.
+  #
+  # @example
+  #   app.post('/upload') do |body|
+  #     file = body[:file]  # UploadFile instance
+  #     content = file.read
+  #     {
+  #       filename: file.filename,
+  #       size: file.size,
+  #       content_type: file.content_type,
+  #       description: body[:description]
+  #     }
+  #   end
+  class UploadFile
+    # @return [String] Original filename from the client
+    attr_reader :filename
+
+    # @return [String] MIME type of the uploaded file
+    attr_reader :content_type
+
+    # @return [Integer] Size of the file in bytes
+    attr_reader :size
+
+    # @return [Hash<String, String>] Additional headers associated with this file field
+    attr_reader :headers
+
+    # Create a new UploadFile instance
+    #
+    # @param filename [String] Original filename from the client
+    # @param content [String] File contents (may be base64 encoded)
+    # @param content_type [String, nil] MIME type (defaults to "application/octet-stream")
+    # @param size [Integer, nil] File size in bytes (computed from content if not provided)
+    # @param headers [Hash<String, String>, nil] Additional headers from the multipart field
+    # @param content_encoding [String, nil] Encoding type (e.g., "base64")
+    def initialize(filename, content, content_type: nil, size: nil, headers: nil, content_encoding: nil)
+      @filename = filename
+      @content_type = content_type || 'application/octet-stream'
+      @headers = headers || {}
+
+      # Decode content if base64 encoded
+      @content = if content_encoding == 'base64' || base64_encoded?(content)
+                   Base64.decode64(content)
+                 else
+                   content
+                 end
+
+      @size = size || @content.bytesize
+      @io = StringIO.new(@content)
+    end
+
+    # Read file contents
+    #
+    # @param size [Integer, nil] Number of bytes to read (nil for all remaining)
+    # @return [String] File contents
+    def read(size = nil)
+      @io.read(size)
+    end
+
+    # Read file contents as text
+    #
+    # @param encoding [String] Character encoding (defaults to UTF-8)
+    # @return [String] File contents as text
+    def text(encoding: 'UTF-8')
+      @content.force_encoding(encoding)
+    end
+
+    # Seek to a specific position in the file
+    #
+    # @param offset [Integer] Byte offset
+    # @param whence [Integer] Position reference (IO::SEEK_SET, IO::SEEK_CUR, IO::SEEK_END)
+    # @return [Integer] New position
+    def seek(offset, whence = IO::SEEK_SET)
+      @io.seek(offset, whence)
+    end
+
+    # Get current position in the file
+    #
+    # @return [Integer] Current byte offset
+    def tell
+      @io.tell
+    end
+    alias pos tell
+
+    # Rewind to the beginning of the file
+    #
+    # @return [Integer] Always returns 0
+    def rewind
+      @io.rewind
+    end
+
+    # Close the file (no-op for StringIO-based implementation)
+    #
+    # @return [nil]
+    def close
+      @io.close
+    end
+
+    # Check if file is closed
+    #
+    # @return [Boolean]
+    def closed?
+      @io.closed?
+    end
+
+    # Get the raw content as a string
+    #
+    # @return [String] Raw file content
+    attr_reader :content
+
+    private
+
+    # Check if a string appears to be base64 encoded
+    #
+    # @param str [String] String to check
+    # @return [Boolean]
+    def base64_encoded?(str)
+      # Simple heuristic: check if string matches base64 pattern
+      str.is_a?(String) && str.match?(%r{\A[A-Za-z0-9+/]*={0,2}\z})
+    end
+  end
+end

data/lib/spikard/version.rb

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

data/lib/spikard/websocket.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Spikard
+  # Base class for WebSocket message handlers.
+  #
+  # Implement this class to handle WebSocket connections and messages.
+  #
+  # @example
+  #   class ChatHandler < Spikard::WebSocketHandler
+  #     def handle_message(message)
+  #       # Echo message back
+  #       message
+  #     end
+  #
+  #     def on_connect
+  #       puts "Client connected"
+  #     end
+  #
+  #     def on_disconnect
+  #       puts "Client disconnected"
+  #     end
+  #   end
+  #
+  #   app = Spikard::App.new
+  #
+  #   app.websocket('/chat') do
+  #     ChatHandler.new
+  #   end
+  #
+  #   app.run
+  class WebSocketHandler
+    # Handle an incoming WebSocket message.
+    #
+    # @param message [Hash] Parsed JSON message from the client
+    # @return [Hash, nil] Optional response message to send back to the client.
+    #   Return nil to not send a response.
+    def handle_message(message)
+      raise NotImplementedError, "#{self.class.name} must implement #handle_message"
+    end
+
+    # Called when a client connects.
+    #
+    # 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.
+    #
+    # 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.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+# Main Ruby namespace for the Spikard bindings.
+module Spikard
+end
+
+begin
+  require 'json'
+rescue LoadError
+  # Fallback to pure-Ruby implementation when native JSON extension is unavailable
+  require 'json/pure'
+end
+require_relative 'spikard/version'
+require_relative 'spikard/config'
+require_relative 'spikard/response'
+require_relative 'spikard/streaming_response'
+require_relative 'spikard/background'
+require_relative 'spikard/schema'
+require_relative 'spikard/websocket'
+require_relative 'spikard/sse'
+require_relative 'spikard/upload_file'
+require_relative 'spikard/converters'
+require_relative 'spikard/provide'
+require_relative 'spikard/handler_wrapper'
+require_relative 'spikard/app'
+require_relative 'spikard/testing'
+
+begin
+  require 'spikard_rb'
+rescue LoadError => e
+  raise LoadError, <<~MSG, e.backtrace
+    Failed to load the Spikard native extension (spikard_rb). Run `bundle exec rake ext:build` to compile it before executing tests.
+    Original error: #{e.message}
+  MSG
+end
+
+# Convenience aliases and methods at top level
+module Spikard
+  TestClient = Testing::TestClient
+
+  # Handler wrapper utilities
+  extend HandlerWrapper
+end