spikard 0.1.0

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.1.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,42 @@
+# 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/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

data/sig/spikard.rbs

@@ -0,0 +1,336 @@
+module Spikard
+  VERSION: String
+
+  module Background
+    def self.run: () { () -> void } -> void
+  end
+
+  class CompressionConfig
+    attr_accessor gzip: bool
+    attr_accessor brotli: bool
+    attr_accessor min_size: Integer
+    attr_accessor quality: Integer
+
+    def initialize: (?gzip: bool, ?brotli: bool, ?min_size: Integer, ?quality: Integer) -> void
+  end
+
+  class RateLimitConfig
+    attr_accessor per_second: Integer
+    attr_accessor burst: Integer
+    attr_accessor ip_based: bool
+
+    def initialize: (per_second: Integer, burst: Integer, ?ip_based: bool) -> void
+  end
+
+  class JwtConfig
+    attr_accessor secret: String
+    attr_accessor algorithm: String
+    attr_accessor audience: Array[String]?
+    attr_accessor issuer: String?
+    attr_accessor leeway: Integer
+
+    def initialize: (secret: String, ?algorithm: String, ?audience: Array[String]?, ?issuer: String?, ?leeway: Integer) -> void
+  end
+
+  class ApiKeyConfig
+    attr_accessor keys: Array[String]
+    attr_accessor header_name: String
+
+    def initialize: (keys: Array[String], ?header_name: String) -> void
+  end
+
+  class StaticFilesConfig
+    attr_accessor directory: String
+    attr_accessor route_prefix: String
+    attr_accessor index_file: bool
+    attr_accessor cache_control: String?
+
+    def initialize: (directory: String, route_prefix: String, ?index_file: bool, ?cache_control: String?) -> void
+  end
+
+  class ContactInfo
+    attr_accessor name: String?
+    attr_accessor email: String?
+    attr_accessor url: String?
+
+    def initialize: (?name: String?, ?email: String?, ?url: String?) -> void
+  end
+
+  class LicenseInfo
+    attr_accessor name: String
+    attr_accessor url: String?
+
+    def initialize: (name: String, ?url: String?) -> void
+  end
+
+  class ServerInfo
+    attr_accessor url: String
+    attr_accessor description: String?
+
+    def initialize: (url: String, ?description: String?) -> void
+  end
+
+  class SecuritySchemeInfo
+    attr_accessor type: String
+    attr_accessor scheme: String?
+    attr_accessor bearer_format: String?
+    attr_accessor location: String?
+    attr_accessor name: String?
+
+    def initialize: (type: String, ?scheme: String?, ?bearer_format: String?, ?location: String?, ?name: String?) -> void
+  end
+
+  class OpenApiConfig
+    attr_accessor enabled: bool
+    attr_accessor title: String
+    attr_accessor version: String
+    attr_accessor description: String?
+    attr_accessor swagger_ui_path: String
+    attr_accessor redoc_path: String
+    attr_accessor openapi_json_path: String
+    attr_accessor contact: ContactInfo?
+    attr_accessor license: LicenseInfo?
+    attr_accessor servers: Array[ServerInfo]
+    attr_accessor security_schemes: Hash[String, SecuritySchemeInfo]
+
+    def initialize: (
+      ?enabled: bool,
+      ?title: String,
+      ?version: String,
+      ?description: String?,
+      ?swagger_ui_path: String,
+      ?redoc_path: String,
+      ?openapi_json_path: String,
+      ?contact: ContactInfo?,
+      ?license: LicenseInfo?,
+      ?servers: Array[ServerInfo],
+      ?security_schemes: Hash[String, SecuritySchemeInfo]
+    ) -> void
+  end
+
+  class ServerConfig
+    attr_accessor host: String
+    attr_accessor port: Integer
+    attr_accessor workers: Integer
+    attr_accessor enable_request_id: bool
+    attr_accessor max_body_size: Integer?
+    attr_accessor request_timeout: Integer?
+    attr_accessor compression: CompressionConfig
+    attr_accessor rate_limit: RateLimitConfig?
+    attr_accessor jwt_auth: JwtConfig?
+    attr_accessor api_key_auth: ApiKeyConfig?
+    attr_accessor static_files: Array[StaticFilesConfig]
+    attr_accessor graceful_shutdown: bool
+    attr_accessor shutdown_timeout: Integer
+    attr_accessor openapi: OpenApiConfig?
+
+    def initialize: (
+      ?host: String,
+      ?port: Integer,
+      ?workers: Integer,
+      ?enable_request_id: bool,
+      ?max_body_size: Integer?,
+      ?request_timeout: Integer?,
+      ?compression: CompressionConfig,
+      ?rate_limit: RateLimitConfig?,
+      ?jwt_auth: JwtConfig?,
+      ?api_key_auth: ApiKeyConfig?,
+      ?static_files: Array[StaticFilesConfig],
+      ?graceful_shutdown: bool,
+      ?shutdown_timeout: Integer,
+      ?openapi: OpenApiConfig?
+    ) -> void
+  end
+
+  class Response
+    attr_accessor content: untyped
+    attr_reader status_code: Integer
+    attr_reader headers: Hash[String, String]
+
+    def initialize: (
+      ?content: untyped,
+      ?body: untyped,
+      ?status_code: Integer,
+      ?headers: Hash[untyped, untyped]?,
+      ?content_type: String?
+    ) -> void
+    def status: () -> Integer
+    def status_code=: (Integer) -> Integer
+    def headers=: (Hash[untyped, untyped]?) -> Hash[String, String]
+    def set_header: (String, String) -> String
+    def set_cookie: (
+      String,
+      String,
+      ?max_age: Integer?,
+      ?domain: String?,
+      ?path: String?,
+      ?secure: bool?,
+      ?httponly: bool?,
+      ?samesite: String?
+    ) -> String
+  end
+
+  class StreamingResponse
+    attr_reader stream: Enumerable[untyped]
+    attr_reader status_code: Integer
+    attr_reader headers: Hash[String, String]
+
+    def initialize: (Enumerable[untyped], ?status_code: Integer, ?headers: Hash[untyped, untyped]?) -> void
+  end
+
+  module LifecycleHooks
+    def on_request: () { (untyped) -> untyped } -> Proc
+    def pre_validation: () { (untyped) -> untyped } -> Proc
+    def pre_handler: () { (untyped) -> untyped } -> Proc
+    def on_response: () { (untyped) -> untyped } -> Proc
+    def on_error: () { (untyped) -> untyped } -> Proc
+    def lifecycle_hooks: () -> Hash[Symbol, Array[Proc]]
+  end
+
+  class App
+    include LifecycleHooks
+
+    attr_reader routes: Array[untyped]
+
+    def initialize: () -> void
+    def register_route: (String, String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def get: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def post: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def put: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def patch: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def delete: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def options: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def head: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def trace: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def websocket: (String, ?handler_name: String?, **untyped) { () -> WebSocketHandler } -> Proc
+    def sse: (String, ?handler_name: String?, **untyped) { () -> SseEventProducer } -> Proc
+    def websocket_handlers: () -> Hash[String, Proc]
+    def sse_producers: () -> Hash[String, Proc]
+    def run: (?config: ServerConfig | Hash[Symbol, untyped]?, ?host: String?, ?port: Integer?) -> void
+  end
+
+  class WebSocketHandler
+    def handle_message: (Hash[untyped, untyped]) -> Hash[untyped, untyped]?
+    def on_connect: () -> void
+    def on_disconnect: () -> void
+  end
+
+  class SseEvent
+    attr_accessor data: Hash[untyped, untyped]
+    attr_accessor event_type: String?
+    attr_accessor id: String?
+    attr_accessor retry_ms: Integer?
+
+    def initialize: (data: Hash[untyped, untyped], ?event_type: String?, ?id: String?, ?retry_ms: Integer?) -> void
+    def to_h: () -> Hash[Symbol, untyped]
+  end
+
+  class SseEventProducer
+    def next_event: () -> SseEvent?
+    def on_connect: () -> void
+    def on_disconnect: () -> void
+  end
+
+  module Schema
+    def self.extract_json_schema: (untyped) -> Hash[untyped, untyped]?
+  end
+
+  module Native
+    def self.run_server: (
+      String,
+      Hash[Symbol, Proc],
+      ServerConfig,
+      Hash[Symbol, Array[Proc]],
+      Hash[String, Proc],
+      Hash[String, Proc]
+    ) -> void
+
+    class TestClient
+      def initialize: (
+        String,
+        Hash[Symbol, Proc],
+        ServerConfig,
+        Hash[String, Proc],
+        Hash[String, Proc]
+      ) -> void
+      def request: (String, String, Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
+      def websocket: (String) -> untyped
+      def sse: (String) -> untyped
+      def close: () -> void
+    end
+  end
+
+  module Testing
+    def self.create_test_client: (App, ?config: ServerConfig?) -> Testing::TestClient
+
+    class Response
+      attr_reader status_code: Integer
+      attr_reader headers: Hash[String, String]
+      attr_reader body: String?
+
+      def initialize: (Hash[Symbol, untyped]) -> void
+      def status: () -> Integer
+      def body_bytes: () -> String
+      def body_text: () -> String?
+      def text: () -> String?
+      def json: () -> untyped
+      def bytes: () -> Array[Integer]
+    end
+
+    class TestClient
+      def initialize: (Spikard::Native::TestClient) -> void
+      def self.new: (App | Spikard::Native::TestClient, ?config: ServerConfig?) -> TestClient
+      def request: (String, String, **Hash[Symbol, untyped]) -> Response
+      def websocket: (String) -> WebSocketTestConnection
+      def sse: (String) -> SseStream
+      def close: () -> void
+      def get: (String, **Hash[Symbol, untyped]) -> Response
+      def post: (String, **Hash[Symbol, untyped]) -> Response
+      def put: (String, **Hash[Symbol, untyped]) -> Response
+      def patch: (String, **Hash[Symbol, untyped]) -> Response
+      def delete: (String, **Hash[Symbol, untyped]) -> Response
+      def head: (String, **Hash[Symbol, untyped]) -> Response
+      def options: (String, **Hash[Symbol, untyped]) -> Response
+      def trace: (String, **Hash[Symbol, untyped]) -> Response
+    end
+
+    class WebSocketTestConnection
+      def initialize: (untyped) -> void
+      def send_text: (untyped) -> void
+      def send_json: (untyped) -> void
+      def receive_text: () -> untyped
+      def receive_json: () -> untyped
+      def receive_bytes: () -> untyped
+      def receive_message: () -> WebSocketMessage
+      def close: () -> void
+    end
+
+    class WebSocketMessage
+      def initialize: (untyped) -> void
+      def as_text: () -> untyped
+      def as_json: () -> untyped
+      def as_binary: () -> untyped
+      def close?: () -> bool
+    end
+
+    class SseStream
+      def initialize: (untyped) -> void
+      def body: () -> String?
+      def events: () -> Array[InlineSseEvent]
+      def events_as_json: () -> Array[untyped]
+    end
+
+    class SseEvent
+      def initialize: (untyped) -> void
+      def data: () -> untyped
+      def as_json: () -> untyped
+    end
+
+    class InlineSseEvent
+      attr_reader data: String
+
+      def initialize: (String) -> void
+      def as_json: () -> untyped
+    end
+  end
+end

metadata

@@ -0,0 +1,84 @@
+--- !ruby/object:Gem::Specification
+name: spikard
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Na'aman Hirschfeld
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-11-23 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+description: |
+  Spikard provides a high-performance HTTP toolkit with a Rust core and thin language bindings.
+  This gem bundles the Ruby bridge implemented with Magnus.
+email:
+- nhirschfeld@gmail.com
+executables: []
+extensions:
+- ext/spikard_rb/extconf.rb
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- ext/spikard_rb/Cargo.toml
+- ext/spikard_rb/extconf.rb
+- ext/spikard_rb/src/lib.rs
+- lib/spikard.rb
+- lib/spikard/app.rb
+- lib/spikard/background.rb
+- lib/spikard/config.rb
+- lib/spikard/converters.rb
+- lib/spikard/handler_wrapper.rb
+- lib/spikard/response.rb
+- lib/spikard/schema.rb
+- lib/spikard/sse.rb
+- lib/spikard/streaming_response.rb
+- lib/spikard/testing.rb
+- lib/spikard/upload_file.rb
+- lib/spikard/version.rb
+- lib/spikard/websocket.rb
+- sig/spikard.rbs
+homepage: https://github.com/Goldziher/spikard
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/Goldziher/spikard
+  source_code_uri: https://github.com/Goldziher/spikard
+  changelog_uri: https://github.com/Goldziher/spikard/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Ruby bindings for the Spikard HTTP toolkit
+test_files: []