funapi 0.1.0

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

@@ -0,0 +1,353 @@
+# Middleware Implementation Plan
+
+## Goal
+
+Implement a comprehensive middleware system for FunApi that leverages the battle-tested Rack middleware ecosystem while providing FastAPI-like convenience methods.
+
+## Architecture Decision: Hybrid Approach
+
+Support both standard Rack middleware AND FunApi-specific convenience wrappers:
+
+```ruby
+# 1. Standard Rack middleware (existing ecosystem)
+app = FunApi::App.new do |api|
+  api.use Rack::Cors do |config|
+    config.allow do |allow|
+      allow.origins '*'
+      allow.resource '*', headers: :any, methods: [:get, :post]
+    end
+  end
+end
+
+# 2. FunApi-specific middleware (FastAPI-style convenience)
+app = FunApi::App.new do |api|
+  api.add_cors(
+    allow_origins: ['*'],
+    allow_methods: ['*'],
+    allow_headers: ['*']
+  )
+  
+  # Or custom FunApi middleware with async support
+  api.use FunApi::Middleware::RateLimit, max_requests: 100, window: 60
+end
+```
+
+## Implementation Phases
+
+### Phase 1: Core Middleware System ⭐⭐⭐⭐⭐
+
+**File**: `lib/fun_api/application.rb`
+
+**Changes**:
+1. Uncomment and fix `build_middleware_chain` method (lines 144-152)
+2. Add `use(middleware, *args, &block)` method
+3. Update `call(env)` to use middleware chain instead of router directly
+4. Ensure middleware is applied in correct order (LIFO - Last In, First Out)
+
+**Why First**: This unblocks everything else and enables the entire Rack ecosystem.
+
+**Implementation**:
+```ruby
+class App
+  def use(middleware, *args, &block)
+    @middleware_stack << [middleware, args, block]
+    self
+  end
+  
+  def call(env)
+    app = build_middleware_chain
+    app.call(env)
+  end
+  
+  private
+  
+  def build_middleware_chain
+    # Start with router as the innermost app
+    app = @router
+    
+    # Wrap with middleware in reverse order (LIFO)
+    @middleware_stack.reverse_each do |middleware, args, block|
+      app = middleware.new(app, *args, &block)
+    end
+    
+    app
+  end
+end
+```
+
+### Phase 2: Built-in Middleware ⭐⭐⭐⭐
+
+Create FunApi-specific middleware with async awareness and FastAPI-style convenience.
+
+#### A. Base Middleware Class
+**File**: `lib/fun_api/middleware/base.rb`
+
+```ruby
+module FunApi
+  module Middleware
+    class Base
+      def initialize(app)
+        @app = app
+      end
+      
+      def call(env)
+        @app.call(env)
+      end
+    end
+  end
+end
+```
+
+#### B. CORS Middleware (Delegate to rack-cors)
+**File**: `lib/fun_api/middleware/cors.rb`
+
+Wrapper around the battle-tested `rack-cors` gem.
+
+```ruby
+module FunApi
+  module Middleware
+    class Cors
+      def self.new(app, allow_origins: ['*'], allow_methods: ['*'], 
+                   allow_headers: ['*'], expose_headers: [], 
+                   max_age: 600, allow_credentials: false)
+        require 'rack/cors'
+        
+        Rack::Cors.new(app) do |config|
+          config.allow do |allow|
+            allow.origins(*allow_origins)
+            allow.resource '*',
+              methods: allow_methods,
+              headers: allow_headers,
+              expose: expose_headers,
+              max_age: max_age,
+              credentials: allow_credentials
+          end
+        end
+      end
+    end
+  end
+  
+  class App
+    def add_cors(**options)
+      use FunApi::Middleware::Cors, **options
+    end
+  end
+end
+```
+
+**Dependencies**: Add `rack-cors` to gemspec
+
+#### C. Trusted Host Middleware
+**File**: `lib/fun_api/middleware/trusted_host.rb`
+
+Validates the `Host` header to prevent host header attacks.
+
+```ruby
+module FunApi
+  module Middleware
+    class TrustedHost < Base
+      def initialize(app, allowed_hosts: [])
+        super(app)
+        @allowed_hosts = Array(allowed_hosts)
+      end
+      
+      def call(env)
+        host = env['HTTP_HOST']&.split(':')&.first
+        
+        unless host_allowed?(host)
+          return [
+            400,
+            {'content-type' => 'application/json'},
+            [JSON.dump(detail: 'Invalid host header')]
+          ]
+        end
+        
+        @app.call(env)
+      end
+      
+      private
+      
+      def host_allowed?(host)
+        return true if @allowed_hosts.empty?
+        @allowed_hosts.any? { |pattern|
+          pattern.is_a?(Regexp) ? pattern.match?(host) : pattern == host
+        }
+      end
+    end
+  end
+  
+  class App
+    def add_trusted_host(allowed_hosts:)
+      use FunApi::Middleware::TrustedHost, allowed_hosts: allowed_hosts
+    end
+  end
+end
+```
+
+#### D. Request Logger Middleware
+**File**: `lib/fun_api/middleware/request_logger.rb`
+
+Logs incoming requests with timing information.
+
+```ruby
+module FunApi
+  module Middleware
+    class RequestLogger < Base
+      def initialize(app, logger: nil, level: :info)
+        super(app)
+        @logger = logger || Logger.new($stdout)
+        @level = level
+      end
+      
+      def call(env)
+        start = Time.now
+        status, headers, body = @app.call(env)
+        duration = Time.now - start
+        
+        log_request(env, status, duration)
+        
+        [status, headers, body]
+      end
+      
+      private
+      
+      def log_request(env, status, duration)
+        request = Rack::Request.new(env)
+        @logger.send(@level,
+          "#{request.request_method} #{request.path} " \
+          "#{status} #{(duration * 1000).round(2)}ms"
+        )
+      end
+    end
+  end
+  
+  class App
+    def add_request_logger(logger: nil, level: :info)
+      use FunApi::Middleware::RequestLogger, logger: logger, level: level
+    end
+  end
+end
+```
+
+#### E. Gzip Compression (Delegate to Rack::Deflater)
+**File**: Convenience method only
+
+```ruby
+class App
+  def add_gzip
+    use Rack::Deflater, if: ->(env, status, headers, body) {
+      headers['content-type']&.start_with?('application/json')
+    }
+  end
+end
+```
+
+### Phase 3: Documentation & Examples ⭐⭐⭐
+
+#### Update README.md
+Add middleware section with examples:
+- Basic middleware usage
+- Built-in middleware
+- Compatible Rack middleware ecosystem
+- Custom middleware creation
+
+#### Create Example App
+**File**: `examples/middleware_demo.rb`
+
+Demonstrate all middleware features.
+
+### Phase 4: Testing ⭐⭐⭐⭐
+
+**File**: `test/test_middleware.rb`
+
+Test:
+- Middleware ordering (LIFO)
+- Built-in middleware functionality
+- Async compatibility
+- Integration with Rack middleware
+- Edge cases (no middleware, single middleware, multiple middleware)
+
+## Benefits
+
+1. ✅ **Leverage Ruby ecosystem** - All existing Rack middleware works out of the box
+2. ✅ **Battle-tested** - Rack middleware pattern is 15+ years proven
+3. ✅ **FastAPI-like DX** - Convenience methods (`add_cors`, `add_gzip`) for common needs
+4. ✅ **Flexibility** - Support both Rack standard and custom middleware
+5. ✅ **Async-compatible** - Rack 3.0+ supports async natively
+6. ✅ **Zero reinvention** - Delegate to proven gems (rack-cors, rack-deflater)
+
+## Compatible Rack Middleware (to document)
+
+Popular Rack middleware that works immediately:
+
+```ruby
+# Rate limiting
+gem 'rack-attack'
+app.use Rack::Attack
+
+# Authentication
+gem 'warden'
+app.use Warden::Manager
+
+# Caching
+app.use Rack::Cache
+
+# ETags
+app.use Rack::ETag
+
+# Conditional GET
+app.use Rack::ConditionalGet
+
+# Static files
+app.use Rack::Static, urls: ['/public']
+
+# Session
+app.use Rack::Session::Cookie, secret: 'your_secret'
+```
+
+## Implementation Checklist
+
+### Phase 1: Core System
+- [ ] Add `use` method to `App` class
+- [ ] Implement `build_middleware_chain` method
+- [ ] Update `call` method to use middleware chain
+- [ ] Test with existing Rack middleware (Rack::Cors)
+- [ ] Ensure middleware ordering is correct (LIFO)
+
+### Phase 2: Built-in Middleware
+- [ ] Create `lib/fun_api/middleware/base.rb`
+- [ ] Create `lib/fun_api/middleware/cors.rb` (wrapper)
+- [ ] Create `lib/fun_api/middleware/trusted_host.rb`
+- [ ] Create `lib/fun_api/middleware/request_logger.rb`
+- [ ] Add convenience methods: `add_cors`, `add_gzip`, etc.
+- [ ] Add `rack-cors` to gemspec dependencies
+
+### Phase 3: Documentation
+- [ ] Update README with middleware section
+- [ ] Document built-in middleware
+- [ ] List compatible Rack middleware
+- [ ] Create middleware guide
+- [ ] Add examples for common use cases (auth, CORS, logging)
+- [ ] Create `examples/middleware_demo.rb`
+
+### Phase 4: Testing
+- [ ] Create `test/test_middleware.rb`
+- [ ] Test middleware ordering
+- [ ] Test async compatibility
+- [ ] Test with popular Rack middleware
+- [ ] Integration tests for built-in middleware
+- [ ] Edge case testing
+
+## Questions Resolved
+
+**Q: Should we leverage Rack for middleware?**
+A: YES! Rack middleware is battle-tested and gives us access to the entire Ruby ecosystem. We should support standard Rack middleware while providing FastAPI-style convenience wrappers.
+
+**Q: Which middleware should be built-in vs ecosystem?**
+A: 
+- **Built-in**: CORS (wrapped), TrustedHost, RequestLogger (most common needs)
+- **Ecosystem**: Rate limiting (rack-attack), Auth (warden), Caching (rack-cache)
+- **Delegate to Rack**: Gzip (Rack::Deflater), ETag (Rack::ETag)
+
+**Q: How to maintain async compatibility?**
+A: Rack 3.0+ already supports async via Fiber/Async. Our middleware just needs to follow standard Rack interface (`call(env)` returns `[status, headers, body]`).

data/.claude/25-10-27-BACKGROUND_TASKS_ANALYSIS.md

@@ -0,0 +1,325 @@
+# Background Tasks Analysis for FunAPI
+
+## Executive Summary
+
+After extensive testing of Ruby's Async gem, **we can implement background tasks with ZERO abstraction** - users can simply use `Async(task) do ... end` to spawn fire-and-forget tasks. However, there's a critical **dependency cleanup issue** that makes a lightweight `BackgroundTasks` abstraction valuable.
+
+## Key Findings
+
+### Python vs Ruby: Task Lifecycle
+
+**Python (asyncio):**
+- `asyncio.create_task()` returns immediately without waiting
+- Tasks can be "orphaned" if not explicitly awaited
+- This is WHY FastAPI needs `BackgroundTasks` - to ensure tasks complete before process exits
+
+**Ruby (Async gem):**
+- `task.async { }` creates a child task that IS tracked by parent
+- Parent waits for children when block ends (via `Async do ... end.wait`)
+- `Async(parent) { }` creates a DETACHED task (truly fire-and-forget)
+
+### The Critical Problem: Dependency Cleanup
+
+```ruby
+Async do |task|
+  begin
+    db = Database.connect
+    
+    # User spawns background task
+    Async(task) do
+      sleep 0.1
+      send_email(db)  # DB is captured in closure
+    end
+    
+    [response, 200]
+    
+  ensure
+    db.close  # RUNS BEFORE background task!
+  end
+end
+```
+
+**Timeline:**
+1. Request handler starts
+2. Response returned
+3. **ensure block runs → DB closed**
+4. Background task tries to use DB (might work due to closure, but semantically wrong)
+
+### Solution Options
+
+#### Option 1: No Abstraction (Pure Async)
+
+```ruby
+api.post '/notify' do |input, req, task|
+  email = input[:body][:email]
+  
+  # Detached background task
+  Async(task) do
+    send_welcome_email(email)
+  end
+  
+  [{ message: "Sent" }, 200]
+end
+```
+
+**Pros:**
+- Zero magic, pure Ruby Async
+- No new API to learn
+- Explicit and clear
+
+**Cons:**
+- ❌ Runs AFTER dependency cleanup
+- ❌ Dependencies might be closed when task runs
+- ❌ No FastAPI parity
+- ❌ No task collection/management
+
+#### Option 2: BackgroundTasks Object (Recommended)
+
+```ruby
+api.post '/notify' do |input, req, task, background:|
+  email = input[:body][:email]
+  
+  background.add_task(:send_welcome_email, email)
+  
+  [{ message: "Sent" }, 200]
+end
+```
+
+**Implementation ensures correct execution order:**
+1. Handler returns response tuple
+2. **Background tasks execute** (with dependencies still available)
+3. Dependency cleanup in ensure block
+4. Response sent to client
+
+**Pros:**
+- ✅ Tasks run BEFORE dependency cleanup
+- ✅ FastAPI API parity
+- ✅ Dependencies guaranteed available
+- ✅ Can inject dependencies into background tasks
+- ✅ Error handling for task failures
+- ✅ Testing/introspection support
+
+**Cons:**
+- Small abstraction needed (~50 lines)
+
+## Recommended Implementation
+
+### BackgroundTasks Class
+
+```ruby
+module FunApi
+  class BackgroundTasks
+    def initialize(task, context)
+      @task = task
+      @context = context
+      @tasks = []
+    end
+    
+    def add_task(callable, *args, **kwargs)
+      @tasks << { callable: callable, args: args, kwargs: kwargs }
+    end
+    
+    def execute
+      @tasks.each do |task_def|
+        callable = task_def[:callable]
+        args = task_def[:args]
+        kwargs = task_def[:kwargs]
+        
+        # Spawn as child task (not detached)
+        @task.async do
+          if callable.respond_to?(:call)
+            callable.call(*args, **kwargs)
+          elsif callable.is_a?(Symbol) && @context.respond_to?(callable)
+            @context.public_send(callable, *args, **kwargs)
+          end
+        rescue => e
+          warn "Background task failed: #{e.message}"
+        end
+      end
+      
+      # Wait for all background tasks to complete
+      @task.children.each(&:wait)
+    end
+  end
+end
+```
+
+### Modified Request Flow
+
+```ruby
+def handle_async_route(req, path_params, body_schema, query_schema, response_schema, dependencies, &blk)
+  current_task = Async::Task.current
+  cleanup_objects = []
+  background_tasks = BackgroundTasks.new(current_task, self)
+
+  begin
+    # ... input validation ...
+    # ... dependency resolution ...
+    
+    resolved_deps[:background] = background_tasks
+    
+    payload, status = blk.call(input, req, current_task, **resolved_deps)
+    
+    # Execute background tasks BEFORE ensure
+    background_tasks.execute
+    
+    # ... response building ...
+    
+  ensure
+    cleanup_objects.each(&:cleanup)
+  end
+end
+```
+
+### Execution Order
+
+```
+1. Request arrives
+2. Dependencies resolved (DB connect, etc.)
+3. Route handler executes
+4. Handler returns [payload, status]
+5. ⭐ Background tasks execute (deps still available)
+6. Background tasks complete
+7. Dependencies cleaned up (DB close, etc.)
+8. Response tuple returned
+9. HTTP layer sends response to client
+```
+
+## Use Cases
+
+### Perfect For:
+- Email notifications after signup
+- Logging/analytics after request
+- Cache warming
+- Simple webhook calls
+- Audit trail recording
+
+### NOT For:
+- Long-running jobs (> 30 seconds)
+- Jobs requiring persistence/retries
+- Jobs that must survive server restart
+- Distributed job processing
+→ Use Sidekiq, GoodJob, or Que instead
+
+## API Design
+
+### As Dependency (Recommended)
+
+```ruby
+api.post '/signup', body: UserSchema do |input, req, task, background:|
+  user = create_user(input[:body])
+  
+  background.add_task(:send_welcome_email, user[:email])
+  background.add_task(:notify_admin, user)
+  
+  [user, 201]
+end
+```
+
+### With Callable Objects
+
+```ruby
+background.add_task(method(:send_email), to: user[:email])
+background.add_task(lambda { |id| log_event(id) }, user[:id])
+```
+
+### With Dependencies
+
+```ruby
+api.register(:mailer) { Mailer.new }
+
+api.post '/signup', depends: [:mailer] do |input, req, task, mailer:, background:|
+  user = create_user(input[:body])
+  
+  # Background task can use mailer (captured in closure)
+  background.add_task(lambda { mailer.send_welcome(user[:email]) })
+  
+  [user, 201]
+end
+```
+
+## Comparison to FastAPI
+
+### FastAPI
+```python
+from fastapi import BackgroundTasks
+
+@app.post("/send-notification/{email}")
+async def notify(email: str, background_tasks: BackgroundTasks):
+    background_tasks.add_task(send_email, email, message="Hi")
+    return {"message": "Sent"}
+```
+
+### FunAPI
+```ruby
+api.post '/send-notification/:email' do |input, req, task, background:|
+  email = input[:path]['email']
+  background.add_task(:send_email, email, message: "Hi")
+  [{ message: "Sent" }, 200]
+end
+```
+
+**Nearly identical!** ✨
+
+## Testing Strategy
+
+```ruby
+class TestBackgroundTasks < Minitest::Test
+  def test_background_tasks_execute_after_response
+    execution_order = []
+    
+    app = FunApi::App.new do |api|
+      api.post '/test' do |input, req, task, background:|
+        execution_order << :handler
+        
+        background.add_task(lambda { execution_order << :background })
+        
+        [{ ok: true }, 200]
+      end
+    end
+    
+    res = async_request(app, :post, '/test')
+    
+    assert_equal [:handler, :background], execution_order
+    assert_equal 200, res.status
+  end
+  
+  def test_background_tasks_can_access_dependencies
+    # Test that DB is still available in background task
+  end
+  
+  def test_background_task_errors_are_handled
+    # Test that task errors don't crash app
+  end
+end
+```
+
+## Recommendation: Implement BackgroundTasks
+
+**Why:**
+1. ✅ Correct execution order (before dependency cleanup)
+2. ✅ FastAPI API parity
+3. ✅ Safe dependency access
+4. ✅ Better error handling
+5. ✅ Testable and introspectable
+6. ✅ Small implementation (~50-80 lines)
+
+**Why not "no API":**
+1. ❌ `Async(task) { }` runs AFTER cleanup
+2. ❌ Dependencies might be closed
+3. ❌ No error handling
+4. ❌ Harder to test
+5. ❌ Less discoverable
+
+## Next Steps
+
+1. Implement `BackgroundTasks` class
+2. Modify `handle_async_route` to inject and execute
+3. Write comprehensive tests
+4. Create examples (email, logging, webhooks)
+5. Update docs (README, AGENTS.md)
+6. Consider dependency injection into background tasks
+
+**Estimated effort:** 2-3 hours
+**Impact:** High - production-critical feature
+**Complexity:** Low - leverages existing Async infrastructure