spikard 0.4.0-x86_64-linux

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 456c14e0b98d776f632e10f5c154cacd4dc6e886ede14eb68e8a7f06e49d80b9
+  data.tar.gz: f0d630b5bd83b1bc653da774b4fdfb950fad568dae7b07a90b4bcf8772dde81f
+SHA512:
+  metadata.gz: 52fef672b90dea8986266e474a40558fa8c38b92c4aa4a79fdb3806bf279d07fc5ae5b170bdf57800a5c3f0d6330273c1ea66f6003213ef6799258b7dcdf6c84
+  data.tar.gz: 6a9479972f513edc4ec0d7ad990cff9f0a1044f1b4716fee86aa6b98845d4cd264d969766b9611610182ebe4d8324c197a171f1908052f5c06e91f74c5128b43

data/LICENSE

@@ -0,0 +1 @@
+See ../../LICENSE

data/README.md

@@ -0,0 +1,659 @@
+# Spikard Ruby
+
+[![Documentation](https://img.shields.io/badge/docs-spikard.dev-58FBDA)](https://spikard.dev)
+[![Gem Version](https://img.shields.io/gem/v/spikard.svg)](https://rubygems.org/gems/spikard)
+[![Gem Downloads](https://img.shields.io/gem/dt/spikard.svg)](https://rubygems.org/gems/spikard)
+[![Ruby Version](https://img.shields.io/badge/ruby-%3E%3D%203.2-red.svg)](https://www.ruby-lang.org/)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![codecov](https://codecov.io/gh/Goldziher/spikard/graph/badge.svg?token=H4ZXDZ4A69)](https://codecov.io/gh/Goldziher/spikard)
+[![PyPI](https://img.shields.io/pypi/v/spikard.svg)](https://pypi.org/project/spikard/)
+[![npm](https://img.shields.io/npm/v/spikard.svg)](https://www.npmjs.com/package/spikard)
+[![Crates.io](https://img.shields.io/crates/v/spikard.svg)](https://crates.io/crates/spikard)
+[![Packagist](https://img.shields.io/packagist/v/spikard/spikard.svg)](https://packagist.org/packages/spikard/spikard)
+
+High-performance Ruby web framework with a Rust core. Build REST APIs with Sinatra-style routing and zero-overhead async handlers backed by Axum and Tower-HTTP.
+
+## Features
+
+- **Rust-powered performance**: High-throughput HTTP server backed by Tokio and Axum
+- **Sinatra-style routing**: Familiar `get`, `post`, `put`, `patch`, `delete` DSL
+- **Type-safe with RBS**: Full RBS type definitions for Steep type checking
+- **Zero-copy serialization**: Direct Rust-to-Ruby object conversion via Magnus
+- **Async-first**: Non-blocking handlers with full async/await support
+- **Middleware stack**: Compression, rate limiting, request IDs, authentication
+- **WebSockets & SSE**: Native real-time communication primitives
+- **Request validation**: JSON Schema and dry-schema support
+- **Lifecycle hooks**: onRequest, preValidation, preHandler, onResponse, onError
+- **Dependency injection**: Built-in container for services and factories
+
+## Installation
+
+**Via RubyGems (recommended):**
+
+```bash
+gem install spikard
+```
+
+**From source (development):**
+
+```bash
+cd packages/ruby
+bundle install
+bundle exec rake ext:build
+```
+
+**Requirements:**
+- Ruby 3.2 or later
+- Bundler
+- Rust toolchain (for building from source)
+
+## Windows Development
+
+On Windows, Spikard uses the GNU toolchain (not MSVC) to match Ruby's official RubyInstaller distribution.
+
+### Prerequisites
+
+1. **Install RubyInstaller with DevKit:**
+   - Download from [RubyInstaller.org](https://rubyinstaller.org/downloads/)
+   - Choose Ruby+Devkit 3.2.x (x64)
+   - During installation, select "MSYS2 development toolchain"
+
+2. **Install Rust with GNU target:**
+   ```powershell
+   rustup toolchain install stable-x86_64-pc-windows-gnu
+   rustup default stable-x86_64-pc-windows-gnu
+   ```
+
+3. **Verify setup:**
+   ```powershell
+   ruby --version  # Should show 3.2.x
+   rustup show     # Should show *-pc-windows-gnu
+   ```
+
+### Building on Windows
+
+```bash
+cd packages/ruby
+bundle install
+bundle exec rake compile
+```
+
+The build uses the GNU toolchain automatically via RubyInstaller's MSYS2 DevKit. No MSVC configuration needed.
+
+## Quick Start
+
+```ruby
+require "spikard"
+require "dry-schema"
+
+UserSchema = Dry::Schema.JSON do
+  required(:name).filled(:str?)
+  required(:email).filled(:str?)
+end
+
+app = Spikard::App.new
+
+app.get "/users/:id" do |request|
+  user_id = request[:path_params]["id"].to_i
+  { id: user_id, name: "Alice" }
+end
+
+app.post "/users", request_schema: UserSchema do |request|
+  body = request[:body]
+  { id: 1, name: body["name"], email: body["email"] }
+end
+
+app.run(port: 8000)
+```
+
+## Request Hash Structure
+
+Handlers receive a single `request` hash argument with the following keys:
+
+- `:method` - HTTP method (String): `"GET"`, `"POST"`, etc.
+- `:path` - URL path (String): `"/users/123"`
+- `:path_params` - Path parameters (Hash): `{"id" => "123"}`
+- `:query` - Query parameters (Hash): `{"search" => "ruby"}`
+- `:raw_query` - Raw query multimap (Hash of Arrays)
+- `:headers` - Request headers (Hash): `{"Authorization" => "Bearer..."}`
+- `:cookies` - Request cookies (Hash): `{"session_id" => "..."}`
+- `:body` - Parsed request body (Hash or nil)
+- `:params` - Merged params from path, query, headers, and cookies
+
+**Example:**
+
+```ruby
+app.get "/users/:id" do |request|
+  user_id = request[:path_params]["id"]
+  search = request[:query]["search"]
+  auth = request[:headers]["Authorization"]
+
+  { id: user_id, search: search }
+end
+```
+
+## Route Registration
+
+### HTTP Methods
+
+```ruby
+app.get "/path" do |request|
+  # Handler code
+  { method: request[:method] }
+end
+
+app.post "/path" do |request|
+  { created: true }
+end
+
+app.put "/path" do |request|
+  { updated: true }
+end
+
+app.patch "/path" do |request|
+  { patched: true }
+end
+
+app.delete "/path" do |request|
+  { deleted: true }
+end
+
+app.options "/path" do |request|
+  { options: [] }
+end
+
+app.head "/path" do |request|
+  # HEAD request
+end
+
+app.trace "/path" do |request|
+  # TRACE request
+end
+```
+
+### Path Parameters
+
+```ruby
+app.get "/users/:user_id" do |request|
+  { user_id: request[:path_params]["user_id"].to_i }
+end
+
+app.get "/posts/:post_id/comments/:comment_id" do |request|
+  {
+    post_id: request[:path_params]["post_id"].to_i,
+    comment_id: request[:path_params]["comment_id"].to_i
+  }
+end
+```
+
+### Query Parameters
+
+```ruby
+app.get "/search" do |request|
+  q = request[:query]["q"]
+  limit = (request[:query]["limit"] || "10").to_i
+  { query: q, limit: limit }
+end
+```
+
+## Validation
+
+Spikard supports **dry-schema** and **raw JSON Schema objects**.
+
+### With dry-schema
+
+```ruby
+require "dry-schema"
+Dry::Schema.load_extensions(:json_schema)
+
+UserSchema = Dry::Schema.JSON do
+  required(:name).filled(:str?)
+  required(:email).filled(:str?)
+  required(:age).filled(:int?)
+end
+
+app.post "/users", request_schema: UserSchema do |request|
+  # request[:body] is validated against schema
+  { id: 1, name: request[:body]["name"] }
+end
+```
+
+### With raw JSON Schema
+
+```ruby
+user_schema = {
+  "type" => "object",
+  "properties" => {
+    "name" => { "type" => "string" },
+    "email" => { "type" => "string", "format" => "email" }
+  },
+  "required" => ["name", "email"]
+}
+
+app.post "/users", request_schema: user_schema do |request|
+  { id: 1, name: request[:body]["name"], email: request[:body]["email"] }
+end
+```
+
+## Dependency Injection
+
+Register values or factories and inject them as keyword parameters:
+
+```ruby
+app.provide("config", { "db_url" => "postgresql://localhost/app" })
+app.provide("db_pool", depends_on: ["config"], singleton: true) do |config:|
+  { url: config["db_url"], driver: "pool" }
+end
+
+app.get "/stats" do |request, config:, db_pool:|
+  { db: db_pool[:url], env: config["db_url"] }
+end
+```
+
+### With dry-struct
+
+```ruby
+require "dry-struct"
+require "dry-types"
+
+module Types
+  include Dry.Types()
+end
+
+class User < Dry::Struct
+  attribute :name, Types::String
+  attribute :email, Types::String
+  attribute :age, Types::Integer
+end
+
+app.post "/users", request_schema: User do |request|
+  # request[:body] validated as User
+  { id: 1, name: request[:body]["name"] }
+end
+```
+
+## Response Types
+
+### Simple Hash Response
+
+```ruby
+app.get "/hello" do
+  { message: "Hello, World!" }
+end
+```
+
+### String Response
+
+```ruby
+app.get "/text" do
+  "Plain text response"
+end
+```
+
+### Full Response Object
+
+```ruby
+app.post "/users" do |request|
+  Spikard::Response.new(
+    content: { id: 1, name: request[:body]["name"] },
+    status_code: 201,
+    headers: { "X-Custom" => "value" }
+  )
+end
+```
+
+### Streaming Response
+
+```ruby
+app.get "/stream" do
+  stream = Enumerator.new do |yielder|
+    10.times do |i|
+      yielder << "Chunk #{i}\n"
+      sleep 0.1
+    end
+  end
+
+  Spikard::StreamingResponse.new(
+    stream,
+    status_code: 200,
+    headers: { "Content-Type" => "text/plain" }
+  )
+end
+```
+
+## File Uploads
+
+```ruby
+app.post "/upload", file_params: true do |request|
+  file = request[:body]["file"]  # UploadFile instance
+
+  {
+    filename: file.filename,
+    size: file.size,
+    content_type: file.content_type,
+    content: file.read
+  }
+end
+```
+
+## Configuration
+
+```ruby
+config = Spikard::ServerConfig.new(
+  host: "0.0.0.0",
+  port: 8080,
+  workers: 4,
+  enable_request_id: true,
+  max_body_size: 10 * 1024 * 1024,  # 10 MB
+  request_timeout: 30,
+  compression: Spikard::CompressionConfig.new(
+    gzip: true,
+    brotli: true,
+    quality: 6
+  ),
+  rate_limit: Spikard::RateLimitConfig.new(
+    per_second: 100,
+    burst: 200
+  )
+)
+
+app.run(config: config)
+```
+
+### Middleware Configuration
+
+**Compression:**
+
+```ruby
+compression = Spikard::CompressionConfig.new(
+  gzip: true,
+  brotli: true,
+  min_size: 1024,
+  quality: 6
+)
+```
+
+**Rate Limiting:**
+
+```ruby
+rate_limit = Spikard::RateLimitConfig.new(
+  per_second: 100,
+  burst: 200,
+  ip_based: true
+)
+```
+
+**JWT Authentication:**
+
+```ruby
+jwt = Spikard::JwtConfig.new(
+  secret: "your-secret-key",
+  algorithm: "HS256",
+  audience: ["api.example.com"],
+  issuer: "auth.example.com",
+  leeway: 30
+)
+```
+
+**Static Files:**
+
+```ruby
+static = Spikard::StaticFilesConfig.new(
+  directory: "./public",
+  route_prefix: "/static",
+  index_file: true,
+  cache_control: "public, max-age=3600"
+)
+```
+
+**OpenAPI Documentation:**
+
+```ruby
+openapi = Spikard::OpenApiConfig.new(
+  enabled: true,
+  title: "My API",
+  version: "1.0.0",
+  description: "API docs",
+  swagger_ui_path: "/docs",
+  redoc_path: "/redoc"
+)
+```
+
+## Lifecycle Hooks
+
+```ruby
+app.on_request do |request|
+  puts "#{request[:method]} #{request[:path]}"
+  request
+end
+
+app.pre_validation do |request|
+  if too_many_requests?
+    Spikard::Response.new(
+      content: { error: "Rate limit exceeded" },
+      status_code: 429
+    )
+  else
+    request
+  end
+end
+
+app.pre_handler do |request|
+  if invalid_token?(request[:headers]["Authorization"])
+    Spikard::Response.new(
+      content: { error: "Unauthorized" },
+      status_code: 401
+    )
+  else
+    request
+  end
+end
+
+app.on_response do |response|
+  response.headers["X-Frame-Options"] = "DENY"
+  response
+end
+
+app.on_error do |response|
+  puts "Error: #{response.status_code}"
+  response
+end
+```
+
+## WebSockets
+
+```ruby
+class ChatHandler < Spikard::WebSocketHandler
+  def on_connect
+    puts "Client connected"
+  end
+
+  def handle_message(message)
+    # message is a Hash (parsed JSON)
+    { echo: message, timestamp: Time.now.to_i }
+  end
+
+  def on_disconnect
+    puts "Client disconnected"
+  end
+end
+
+app.websocket("/chat") { ChatHandler.new }
+```
+
+## Server-Sent Events (SSE)
+
+```ruby
+class NotificationProducer < Spikard::SseEventProducer
+  def initialize
+    @count = 0
+  end
+
+  def on_connect
+    puts "Client connected to SSE stream"
+  end
+
+  def next_event
+    sleep 1
+
+    return nil if @count >= 10  # End stream
+
+    event = Spikard::SseEvent.new(
+      data: { message: "Notification #{@count}" },
+      event_type: "notification",
+      id: @count.to_s,
+      retry_ms: 3000
+    )
+    @count += 1
+    event
+  end
+
+  def on_disconnect
+    puts "Client disconnected from SSE"
+  end
+end
+
+app.sse("/notifications") { NotificationProducer.new }
+```
+
+## Background Tasks
+
+```ruby
+app.post "/process" do |request|
+  Spikard::Background.run do
+    # Heavy processing after response
+    ProcessData.perform(request[:path_params]["id"])
+  end
+
+  { status: "processing" }
+end
+```
+
+## Testing
+
+```ruby
+require "spikard"
+
+app = Spikard::App.new
+app.get "/hello" do
+  { message: "Hello, World!" }
+end
+
+client = Spikard::TestClient.new(app)
+
+# HTTP requests
+response = client.get("/hello", query: { name: "Alice" })
+puts response.status_code  # => 200
+puts response.json         # => { "message" => "Hello, World!" }
+
+# POST with JSON
+response = client.post("/users", json: { name: "Bob" })
+
+# File upload
+response = client.post("/upload", files: {
+  file: ["test.txt", "content", "text/plain"]
+})
+
+# WebSocket
+ws = client.websocket("/chat")
+ws.send_json({ message: "hello" })
+message = ws.receive_json
+ws.close
+
+# SSE
+sse = client.sse("/events")
+events = sse.events_as_json
+puts events.length
+
+# Cleanup
+client.close
+```
+
+## Running the Server
+
+```ruby
+# Development
+app.run(port: 8000)
+
+# Production
+config = Spikard::ServerConfig.new(
+  host: "0.0.0.0",
+  port: 8080,
+  workers: 4
+)
+app.run(config: config)
+```
+
+## Type Safety with RBS
+
+RBS type signatures are provided in `sig/spikard.rbs`:
+
+```ruby
+module Spikard
+  class App
+    def initialize: () -> void
+    def get: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def post: (String, ?handler_name: String?, **untyped) { (untyped) -> untyped } -> Proc
+    def run: (?config: ServerConfig | Hash[Symbol, untyped]?) -> void
+  end
+
+  class ServerConfig
+    def initialize: (?host: String, ?port: Integer, **untyped) -> void
+  end
+end
+```
+
+Use with Steep for type checking:
+
+```bash
+bundle exec steep check
+```
+
+## Performance
+
+Ruby bindings use:
+- **Magnus** for zero-overhead FFI
+- **rb-sys** for modern Ruby 3.2+ integration
+- Idiomatic Ruby blocks and procs
+- GC-safe handler storage
+
+## Examples
+
+The [examples directory](../../examples/) contains comprehensive demonstrations:
+
+**Ruby-specific examples:**
+- [Basic Ruby Example](../../examples/di/ruby_basic.rb) - Simple server with DI
+- [Database Integration](../../examples/di/ruby_database.rb) - DI with database pools
+- Additional examples in [examples/](../../examples/)
+
+**API Schemas** (language-agnostic, can be used with code generation):
+- [Todo API](../../examples/schemas/todo-api.openapi.yaml) - REST CRUD with validation
+- [File Service](../../examples/schemas/file-service.openapi.yaml) - File uploads/downloads
+- [Auth Service](../../examples/schemas/auth-service.openapi.yaml) - JWT, API keys, OAuth
+- [Chat Service](../../examples/schemas/chat-service.asyncapi.yaml) - WebSocket messaging
+- [Event Streams](../../examples/schemas/events-stream.asyncapi.yaml) - SSE streaming
+
+See [examples/README.md](../../examples/README.md) for code generation instructions.
+
+## Documentation
+
+**API Reference & Guides:**
+- [Type Definitions (RBS)](sig/spikard.rbs) - Full type signatures for Steep
+- [Configuration Reference](lib/spikard/config.rb) - ServerConfig and middleware options
+- [Handler Documentation](lib/spikard/handler_wrapper.rb) - Request/response handling
+
+**Project Resources:**
+- [Main Project README](../../README.md) - Spikard overview and multi-language ecosystem
+- [Contributing Guide](../../CONTRIBUTING.md) - Development guidelines
+- [Architecture Decisions](../../docs/adr/) - ADRs on design choices
+- [Examples](../../examples/ruby/) - Runnable example applications
+
+**Cross-Language:**
+- [Python (PyPI)](https://pypi.org/project/spikard/)
+- [Node.js (npm)](https://www.npmjs.com/package/spikard)
+- [Rust (Crates.io)](https://crates.io/crates/spikard)
+- [PHP (Packagist)](https://packagist.org/packages/spikard/spikard)
+
+## License
+
+MIT - See [LICENSE](../../LICENSE) for details

data/ext/spikard_rb/Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "spikard-rb-ext"
+version = "0.4.0"
+edition = "2024"
+license = "MIT"
+authors = ["Na'aman Hirschfeld <nhirschfeld@gmail.com>"]
+
+[lib]
+name = "spikard_rb"
+crate-type = ["cdylib"]
+
+[workspace]
+
+[dependencies]
+magnus = { version = "0.8.2", features = ["rb-sys"] }
+# Use vendored crates for packaged gem distribution
+spikard_rb_core = { package = "spikard-rb", path = "../../vendor/crates/spikard-rb" }

data/ext/spikard_rb/extconf.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'mkmf'
+require 'rb_sys/mkmf'
+
+default_profile = ENV.fetch('CARGO_PROFILE', 'release')
+
+create_rust_makefile('spikard_rb') do |config|
+  config.profile = default_profile.to_sym
+end

data/ext/spikard_rb/src/lib.rs

@@ -0,0 +1,6 @@
+use magnus::Ruby;
+
+#[magnus::init]
+fn init(ruby: &Ruby) -> Result<(), magnus::Error> {
+    spikard_rb_core::init(ruby)
+}