funapi 0.1.0

data/.claude/25-09-10-OPENAPI_PLAN.md

@@ -0,0 +1,219 @@
+## OpenAPI/Swagger Documentation Generation - Implementation Plan
+
+### Goal
+
+Automatically generate OpenAPI 3.0 specification and serve Swagger UI for FunApi applications, similar
+to FastAPI's /docs endpoint.
+
+### Key Design Decisions
+
+1. Architecture Overview
+
+• Store route metadata during app initialization
+• Generate OpenAPI spec on-demand (or cache at startup)
+• Serve Swagger UI at /docs and /redoc endpoints
+• Provide JSON spec at /openapi.json
+
+2. Information to Extract from Routes
+
+• Path - Route template (e.g., /users/:id)
+• Method - HTTP verb (GET, POST, etc.)
+• Parameters:
+ • Path params (from template: /users/:id → id parameter)
+ • Query params (from query: schema)
+ • Body params (from body: schema)
+• Responses:
+ • Response schema (from response_schema:)
+ • Status code (from handler return value)
+• Tags - Group endpoints logically (future)
+• Description/Summary - Optional metadata (future)
+
+3. Dry-Schema Introspection Strategy From my research:
+
+schema = Dry::Schema.Params { required(:name).filled(:string); required(:age).filled(:integer) }
+# Available introspection:
+# - schema.key_map → list of keys
+# - schema.rules → validation rules (complex nested structure)
+# - schema.types → type information per key
+
+Need to build a schema-to-JSON-schema converter that traverses the dry-schema structure.
+
+4. Route Metadata Storage
+
+# Update Router to store rich route information
+Route = Struct.new(:verb, :pattern, :keys, :handler, :metadata)
+
+# metadata contains:
+{
+  path_template: '/users/:id',
+  query_schema: QuerySchema,
+  body_schema: UserInput,
+  response_schema: UserOutput,
+  summary: "Create user",  # future
+  description: "...",      # future
+  tags: ["users"]          # future
+}
+
+5. Implementation Components
+
+#### Component 1: Route Metadata Collection
+
+# lib/fun_api/openapi/route_metadata.rb
+class RouteMetadata
+  attr_reader :verb, :path, :query_schema, :body_schema, :response_schema
+
+  def initialize(verb:, path:, **schemas)
+    @verb = verb
+    @path = path
+    @query_schema = schemas[:query]
+    @body_schema = schemas[:body]
+    @response_schema = schemas[:response_schema]
+  end
+
+  def to_openapi_operation
+    # Generate OpenAPI Operation Object
+  end
+end
+
+#### Component 2: Schema to JSON Schema Converter
+
+# lib/fun_api/openapi/schema_converter.rb
+class SchemaConverter
+  def self.to_json_schema(dry_schema)
+    # Convert dry-schema to OpenAPI Schema Object
+    # Traverse schema.key_map and schema.types
+    # Build JSON Schema representation
+  end
+
+  def self.extract_field_info(key, types)
+    # Determine: type, required, format, etc.
+  end
+end
+
+#### Component 3: OpenAPI Spec Generator
+
+# lib/fun_api/openapi/spec_generator.rb
+class SpecGenerator
+  def initialize(routes, info: {})
+    @routes = routes
+    @info = info
+  end
+
+  def generate
+    {
+      openapi: "3.0.3",
+      info: build_info,
+      paths: build_paths,
+      components: build_components
+    }
+  end
+end
+
+#### Component 4: Documentation Endpoints
+
+# Auto-register these routes:
+# GET /docs → Swagger UI HTML
+# GET /redoc → ReDoc HTML
+# GET /openapi.json → OpenAPI spec
+
+### Implementation Sequence
+
+1. Phase 1: Route Metadata Storage ✓ Plan
+ • Modify Router.add to store full metadata
+ • Update App.add_route to pass all schema info
+ • Create RouteMetadata class
+2. Phase 2: Schema Introspection ✓ Plan
+ • Create SchemaConverter class
+ • Implement dry-schema → JSON Schema conversion
+ • Handle: string, integer, float, boolean, arrays, nested objects
+ • Handle: required vs optional fields
+3. Phase 3: OpenAPI Spec Generation ✓ Plan
+ • Create SpecGenerator class
+ • Generate paths object from routes
+ • Generate components/schemas from all schemas
+ • Generate parameter objects for path/query params
+4. Phase 4: Swagger UI Integration ✓ Plan
+ • Add /openapi.json endpoint
+ • Add /docs endpoint (Swagger UI)
+ • Use CDN-hosted Swagger UI HTML
+5. Phase 5: Testing & Refinement ✓ Plan
+ • Test with complex schemas
+ • Test with nested objects
+ • Test with arrays
+ • Ensure Swagger UI renders correctly
+
+
+### Example Output
+
+For this route:
+
+api.post '/users', body: UserInput, response_schema: UserOutput do |input, req, task|
+  # ...
+end
+
+Generate:
+
+{
+  "paths": {
+    "/users": {
+      "post": {
+        "requestBody": {
+          "content": {
+            "application/json": {
+              "schema": { "$ref": "#/components/schemas/UserInput" }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful response",
+            "content": {
+              "application/json": {
+                "schema": { "$ref": "#/components/schemas/UserOutput" }
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "components": {
+    "schemas": {
+      "UserInput": {
+        "type": "object",
+        "properties": {
+          "username": { "type": "string" },
+          "email": { "type": "string" },
+          "password": { "type": "string" }
+        },
+        "required": ["username", "email", "password"]
+      },
+      "UserOutput": {
+        "type": "object",
+        "properties": {
+          "id": { "type": "integer" },
+          "username": { "type": "string" },
+          "email": { "type": "string" }
+        },
+        "required": ["id", "username", "email"]
+      }
+    }
+  }
+}
+
+### Questions for You
+
+1. Schema Names: Should we require users to name their schemas explicitly, or auto-generate names from
+constants?
+# Option A: Use constant name
+UserInput = FunApi::Schema.define { ... }  # Name: "UserInput"
+
+# Option B: Explicit naming
+api.post '/users', body: { schema: UserInput, name: "UserCreateRequest" }
+
+2. Default Info: What should the default info object contain? (title, version, description)
+3. Docs Path: Should /docs be configurable or fixed?
+4. Schema Deduplication: If the same schema is used multiple times, should we dedupe in components?
+
+Ready to implement when you give the go-ahead! Should I proceed with the implementation in the next
+session (since we're in READ-ONLY mode now)?

data/.claude/25-10-26-MIDDLEWARE_IMPLEMENTATION.md

@@ -0,0 +1,230 @@
+# Middleware Implementation - Complete ✅
+
+## Summary
+
+FunApi now has a comprehensive middleware system that supports both standard Rack middleware and FastAPI-style convenience methods. The implementation leverages Ruby's battle-tested Rack ecosystem while providing an excellent developer experience.
+
+## What Was Implemented
+
+### 1. Core Middleware System
+**Files Modified:**
+- `lib/fun_api/application.rb` - Added `use` method, `build_middleware_chain`, updated `call`
+- `lib/fun_api/router.rb` - Fixed root route (`/`) matching bug
+
+**Key Features:**
+- Standard Rack middleware support (LIFO execution order)
+- Automatic keyword argument handling for middleware
+- Middleware stack building with proper wrapping
+- Compatible with entire Rack ecosystem
+
+### 2. Built-in Middleware
+
+#### A. CORS Middleware (`lib/fun_api/middleware/cors.rb`)
+- Wraps `rack-cors` gem (battle-tested, 15+ years)
+- FastAPI-style configuration
+- Supports origins, methods, headers, credentials, max_age
+
+```ruby
+api.add_cors(
+  allow_origins: ['http://localhost:3000'],
+  allow_methods: ['GET', 'POST'],
+  allow_headers: ['Content-Type']
+)
+```
+
+#### B. Trusted Host Middleware (`lib/fun_api/middleware/trusted_host.rb`)
+- Validates `Host` header to prevent host header attacks
+- Supports string matching and regex patterns
+- Returns 400 for invalid hosts
+
+```ruby
+api.add_trusted_host(
+  allowed_hosts: ['localhost', '127.0.0.1', /\.example\.com$/]
+)
+```
+
+#### C. Request Logger Middleware (`lib/fun_api/middleware/request_logger.rb`)
+- Logs all requests with timing information
+- Configurable logger and log level
+- Format: `METHOD PATH STATUS DURATIONms`
+
+```ruby
+api.add_request_logger(logger: my_logger, level: :debug)
+```
+
+#### D. Gzip Compression (Convenience Method)
+- Delegates to `Rack::Deflater` (built into Rack)
+- Automatically compresses JSON responses
+
+```ruby
+api.add_gzip
+```
+
+### 3. Dependencies Added
+**File:** `fun_api.gemspec`
+- Added `rack-cors >= 2.0` dependency
+
+### 4. Documentation
+**File:** `README.md`
+- Added comprehensive middleware section
+- Examples for built-in middleware
+- Examples for using standard Rack middleware
+- Examples for custom middleware
+- Updated "Current Status" section
+
+### 5. Examples
+**File:** `examples/middleware_demo.rb`
+- Complete working demo of all middleware features
+- Shows CORS, logging, trusted host in action
+- Demonstrates async operations with middleware
+- Includes validation and OpenAPI integration
+
+### 6. Bug Fixes
+**Router Root Route Fix:**
+- Fixed regex generation for `/` route
+- Previously `/` would generate empty regex `/\A\z/` which never matched
+- Now explicitly handles root route case
+
+## Technical Details
+
+### Middleware Execution Order
+
+FunApi uses standard Rack ordering (LIFO - Last In, First Out for wrapping, FIFO for execution):
+
+```ruby
+app.use Middleware1  # Executes FIRST
+app.use Middleware2  # Executes SECOND
+app.use Middleware3  # Executes THIRD
+# Router executes LAST
+```
+
+Request flow: Middleware1 → Middleware2 → Middleware3 → Router → Middleware3 → Middleware2 → Middleware1
+
+### Keyword Argument Handling
+
+The middleware system automatically detects and converts keyword arguments:
+
+```ruby
+# User writes:
+api.add_cors(allow_origins: ['*'])
+
+# Internally stored as:
+@middleware_stack << [Cors, [{allow_origins: ['*']}], nil]
+
+# build_middleware_chain detects hash and converts back:
+Cors.new(app, **{allow_origins: ['*']})
+```
+
+This allows both positional and keyword arguments to work seamlessly.
+
+## Usage Examples
+
+### Basic Middleware Usage
+
+```ruby
+app = FunApi::App.new do |api|
+  api.add_cors
+  api.add_request_logger
+  
+  api.get '/api/users' do |input, req, task|
+    [{ users: [] }, 200]
+  end
+end
+```
+
+### Using Rack Middleware
+
+```ruby
+app = FunApi::App.new do |api|
+  # Any Rack middleware works!
+  api.use Rack::Attack
+  api.use Rack::ETag
+  api.use Rack::Session::Cookie, secret: ENV['SECRET']
+  
+  # Custom middleware
+  api.use MyCustomMiddleware, option1: 'value'
+end
+```
+
+### Custom Middleware
+
+```ruby
+class TimingMiddleware
+  def initialize(app)
+    @app = app
+  end
+  
+  def call(env)
+    start = Time.now
+    status, headers, body = @app.call(env)
+    duration = Time.now - start
+    headers['X-Response-Time'] = "#{(duration * 1000).round(2)}ms"
+    [status, headers, body]
+  end
+end
+
+app.use TimingMiddleware
+```
+
+## Testing
+
+All middleware has been tested:
+- ✅ CORS headers correctly added
+- ✅ Trusted host blocks invalid hosts
+- ✅ Request logger outputs request info
+- ✅ Middleware chain executes in correct order
+- ✅ Works with async operations
+- ✅ Compatible with validation and response schemas
+- ✅ Integrates with OpenAPI documentation
+
+## Benefits
+
+1. **Rack Ecosystem Access** - All existing Rack middleware (100s of gems) work immediately
+2. **FastAPI-style DX** - Convenience methods for common use cases
+3. **Battle-tested** - Delegates to proven libraries (rack-cors, Rack::Deflater)
+4. **Async Compatible** - Works seamlessly with FunApi's async foundation
+5. **Zero Magic** - Clear, explicit middleware stack
+6. **Production Ready** - CORS, logging, host validation out of the box
+
+## Files Created/Modified
+
+### Created:
+1. `lib/fun_api/middleware.rb` - Main middleware loader
+2. `lib/fun_api/middleware/base.rb` - Base middleware class
+3. `lib/fun_api/middleware/cors.rb` - CORS wrapper
+4. `lib/fun_api/middleware/trusted_host.rb` - Host validation
+5. `lib/fun_api/middleware/request_logger.rb` - Request logging
+6. `examples/middleware_demo.rb` - Complete demo application
+7. `.claude/25-10-26-MIDDLEWARE_IMPLEMENTATION.md` - This document
+
+### Modified:
+1. `lib/fun_api/application.rb` - Added middleware system + convenience methods
+2. `lib/fun_api/router.rb` - Fixed root route bug
+3. `fun_api.gemspec` - Added rack-cors dependency
+4. `README.md` - Added middleware documentation
+
+## What's Next
+
+The middleware system is now production-ready. Future enhancements could include:
+
+1. **More Built-in Middleware:**
+   - Rate limiting wrapper (rack-attack)
+   - Authentication helpers
+   - Request ID tracking
+   - Error reporting hooks
+
+2. **Middleware Configuration:**
+   - Global middleware vs per-route middleware
+   - Middleware groups
+   - Conditional middleware
+
+3. **Documentation:**
+   - Middleware guide (separate doc)
+   - More examples
+   - Best practices
+
+## Conclusion
+
+FunApi now has a robust, Rack-compatible middleware system that matches FastAPI's developer experience while leveraging Ruby's mature ecosystem. The implementation is clean, well-tested, and production-ready.
+
+**Status: ✅ COMPLETE**