funapi 0.1.0

data/.claude/DECISIONS.md

@@ -0,0 +1,397 @@
+# FunApi - Architectural Decisions
+
+This document records key architectural and design decisions made during the development of FunApi.
+
+## Testing Strategy (2024-10-26)
+
+### Decision: Flat Test Structure
+
+**Context**: Needed to organize tests for the framework. Options were nested directories (unit/, integration/) vs flat structure.
+
+**Decision**: Use flat test structure following Sidekiq's pattern.
+
+**Rationale**:
+- Simplicity - easier to find tests
+- Flexibility - tests can be unit or integration as needed
+- No artificial boundaries - test what matters, not how
+- Proven pattern - Sidekiq has excellent test organization
+- Library-friendly - FunApi is a library, not an application
+
+**Implementation**:
+```
+test/
+├── test_helper.rb
+├── test_fun_api.rb       # Basic smoke tests
+├── test_router.rb        # Router functionality
+├── test_schema.rb        # Validation
+├── test_middleware.rb    # Middleware chain
+├── test_validation.rb    # Request validation
+├── test_response_schema.rb
+├── test_async.rb
+└── test_exceptions.rb
+```
+
+**Result**: 90 tests, 217 assertions, all passing in ~220ms
+
+---
+
+## Middleware System (2024-10-26)
+
+### Decision: Rack-Compatible Middleware with FastAPI-Style Convenience
+
+**Context**: Needed middleware support. Options: Build custom system vs leverage Rack ecosystem.
+
+**Decision**: Support standard Rack middleware PLUS provide FastAPI-style convenience methods.
+
+**Rationale**:
+- Leverage battle-tested Rack ecosystem (15+ years, 100+ middleware)
+- No reinvention - delegate to proven libraries (rack-cors, Rack::Deflater)
+- FastAPI-like DX - convenience methods for common use cases
+- Zero lock-in - users can use any Rack middleware
+- Async compatible - Rack 3.0+ supports async natively
+
+**Implementation**:
+```ruby
+# Standard Rack middleware
+app.use Rack::Attack
+app.use Rack::Session::Cookie, secret: 'key'
+
+# FunApi convenience methods
+app.add_cors(allow_origins: ['*'])
+app.add_trusted_host(allowed_hosts: ['example.com'])
+app.add_request_logger
+```
+
+**Built-in Middleware**:
+- CORS (wraps rack-cors)
+- TrustedHost (custom implementation)
+- RequestLogger (custom with async awareness)
+- Gzip (delegates to Rack::Deflater)
+
+**Result**: Full Rack compatibility + excellent developer experience
+
+---
+
+## Middleware Execution Order (2024-10-26)
+
+### Decision: Standard Rack Ordering (LIFO wrapping, FIFO execution)
+
+**Context**: How should middleware execute when multiple are registered?
+
+**Decision**: First registered middleware runs first (outermost layer).
+
+**Rationale**:
+- Standard Ruby/Rack convention
+- Expected by Rack developers
+- Well-documented behavior
+- Works with all existing Rack middleware
+
+**Example**:
+```ruby
+app.use Middleware1  # Executes FIRST
+app.use Middleware2  # Executes SECOND
+# Router executes LAST
+```
+
+Request flow: MW1 → MW2 → Router → MW2 → MW1
+
+---
+
+## OpenAPI Implementation (2024-09)
+
+### Decision: Automatic Schema Extraction
+
+**Context**: How to generate OpenAPI specs from dry-schema definitions?
+
+**Decision**: Introspect dry-schema at runtime and convert to JSON Schema.
+
+**Rationale**:
+- No manual duplication
+- Single source of truth (the schema)
+- Automatic documentation updates
+- FastAPI-like experience
+
+**Implementation**:
+- SchemaConverter: dry-schema → JSON Schema
+- SpecGenerator: routes + schemas → OpenAPI 3.0.3 spec
+- Auto-register /openapi.json and /docs endpoints
+
+---
+
+## Response Schema Filtering (2024-09)
+
+### Decision: Security-First Response Filtering
+
+**Context**: How to handle sensitive data in responses (passwords, tokens)?
+
+**Decision**: Response schemas filter output to only include specified fields.
+
+**Rationale**:
+- Security by default
+- Prevent accidental data leaks
+- FastAPI's response_model pattern
+- Explicit is better than implicit
+
+**Example**:
+```ruby
+UserOutputSchema = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:name).filled(:string)
+  # password NOT included
+end
+
+api.get '/user', response_schema: UserOutputSchema do
+  user = { id: 1, name: 'Alice', password: 'secret' }
+  [user, 200]  # Password automatically filtered
+end
+```
+
+---
+
+## Async-First Design (2024-09)
+
+### Decision: Async::Task as Third Handler Parameter
+
+**Context**: How to expose async capabilities to route handlers?
+
+**Decision**: Pass `Async::Task` as third parameter to all handlers.
+
+**Rationale**:
+- Explicit async access
+- No magic globals
+- True concurrent execution
+- Ruby's Async library is mature
+
+**Example**:
+```ruby
+api.get '/dashboard' do |input, req, task|
+  user_task = task.async { fetch_user }
+  posts_task = task.async { fetch_posts }
+  
+  [{ user: user_task.wait, posts: posts_task.wait }, 200]
+end
+```
+
+**Trade-off**: Three parameters instead of two, but explicitness wins.
+
+---
+
+## Router Root Route Fix (2024-10-26)
+
+### Decision: Special-Case Root Route `/`
+
+**Context**: Regex generation failed for `/` route (empty regex).
+
+**Decision**: Explicitly handle `/` as special case before regex generation.
+
+**Rationale**:
+- `/` is common and important
+- Regex `/\A\z/` doesn't match `/`
+- Simple fix with no overhead
+- Prevents future bugs
+
+**Implementation**:
+```ruby
+if path == '/'
+  regex = '/'
+else
+  # normal regex generation
+end
+```
+
+---
+
+## Validation Error Format (2024-09)
+
+### Decision: FastAPI-Compatible Error Format
+
+**Context**: How to structure validation errors?
+
+**Decision**: Use FastAPI's error format with `detail` array.
+
+**Rationale**:
+- Familiar to FastAPI users
+- Structured and parseable
+- Clear error location information
+- Industry standard
+
+**Format**:
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "email"],
+      "msg": "is missing",
+      "type": "value_error"
+    }
+  ]
+}
+```
+
+---
+
+## Schema Validation (2024-09)
+
+### Decision: dry-schema Over ActiveModel
+
+**Context**: Which validation library to use?
+
+**Decision**: Use dry-schema for validation.
+
+**Rationale**:
+- Lightweight (no Rails dependency)
+- Functional approach (no mutations)
+- Better API error messages
+- Type coercion built-in
+- Fast and battle-tested
+
+**Trade-off**: Less familiar to Rails developers, but better fit for APIs.
+
+---
+
+## Server Choice (2024-09)
+
+### Decision: Falcon as Default Server
+
+**Context**: Which Rack server to recommend?
+
+**Decision**: Falcon for development and production.
+
+**Rationale**:
+- Native async support
+- Built for Async library
+- Better concurrency for I/O-bound work
+- Aligns with async-first philosophy
+
+**Note**: Any Rack 3+ server will work (Puma, Unicorn, etc.)
+
+---
+
+## Documentation Strategy (2024-10-26)
+
+### Decision: Dual Documentation (README + AGENTS.md)
+
+**Context**: How to document for both humans and AI agents?
+
+**Decision**: 
+- README.md for human users (features, examples)
+- AGENTS.md for AI coding agents (architecture, testing, conventions)
+
+**Rationale**:
+- Following agents.md standard
+- Different audiences need different info
+- Keeps README concise
+- Provides deep context for agents
+
+---
+
+## Examples as Documentation (2024-10-26)
+
+### Decision: Executable Examples > Test Assertions
+
+**Context**: Should examples be automated tests?
+
+**Decision**: Keep examples simple and executable, separate from test suite.
+
+**Rationale**:
+- Examples show real usage
+- Can be run manually for smoke testing
+- Don't clutter with assertions
+- Living documentation
+- Test suite covers thorough testing
+
+**Organization**:
+- `examples/` - Runnable demos
+- `test/` - Automated tests
+- `test/demo_*.rb` - Reference demos (not automated)
+
+---
+
+## Dependency Injection (2024-10-27)
+
+### Decision: Block-Based Dependencies with Cleanup
+
+**Context**: Need DI with automatic resource cleanup. Evaluated: dry-system, tuples, context managers, blocks.
+
+**Decision**: Ruby blocks with `ensure` for lifecycle management.
+
+**Rationale**:
+- Most idiomatic Ruby (matches `File.open`, `Mutex.synchronize`)
+- `ensure` guarantees cleanup, even on errors
+- FastAPI parity (context managers)
+- Lightweight (uses Fiber, no heavy deps)
+
+**Pattern**:
+```ruby
+api.register(:db) do |provide|
+  conn = Database.connect
+  provide.call(conn)
+ensure
+  conn.close
+end
+
+api.get '/users', depends: [:db] do |input, req, task, db:|
+  [db.all_users, 200]
+end
+```
+
+**Features**:
+- Request-scoped caching
+- Nested dependencies with `FunApi::Depends()`
+- Three patterns: simple, tuple (compat), block (preferred)
+- Cleanup in `ensure` after response sent
+
+**Result**: 121 tests passing, FastAPI-aligned.
+
+---
+
+## Dependency Injection: Not dry-system (2024-10-27)
+
+### Decision: Custom Lightweight DI
+
+**Context**: dry-system exists but designed for different use case.
+
+**Decision**: Build custom DI using only dry-container.
+
+**Rationale**:
+- dry-system = constructor injection, we need parameter injection
+- FunApi is minimal, dry-system is comprehensive
+- Custom solution maps 1:1 to FastAPI's `Depends()`
+
+**Used**: dry-container (registry only)
+**Skipped**: dry-system, dry-auto_inject, dry-effects
+
+---
+
+## Future Decisions Pending
+
+1. ~~**Dependency Injection**~~ ✅ Done
+2. **Background Tasks**: Post-response execution
+3. **Path Parameter Types**: Type coercion/validation
+4. **WebSocket Support**: Async integration
+5. **Content Negotiation**: JSON + others
+6. **Global Dependencies**: Apply to all routes
+
+---
+
+## Non-Decisions (Explicitly Rejected)
+
+### Rails Integration
+**Decision**: FunApi remains independent of Rails.
+**Reason**: Keep it minimal, different use case.
+
+### Magic DSLs
+**Decision**: No heavy DSLs or metaprogramming.
+**Reason**: Explicit is better than implicit.
+
+### Database Integration
+**Decision**: No built-in ORM or database layer.
+**Reason**: Users choose their own (Sequel, ROM, ActiveRecord).
+
+---
+
+## Change Log
+
+- 2024-10-27: Added dependency injection decisions
+- 2024-10-26: Testing, middleware, documentation strategies
+- 2024-09: Initial core framework decisions

data/.claude/PROJECT_PLAN.md

@@ -0,0 +1,80 @@
+# Project Overview
+
+A minimal, async-first Ruby web framework inspired by FastAPI. Built on top of Falcon and dry-schema, FunApi provides a simple, performant way to build web APIs in Ruby with a focus on developer experience.
+
+## Philosophy
+
+FunApi aims to bring FastAPI's excellent developer experience to Ruby by providing:
+
+- **Async-first**: Built on Ruby's Async library and Falcon server for high-performance concurrent operations
+- **Simple validation**: Using dry-schema for straightforward request validation
+- **Minimal magic**: Clear, explicit APIs without heavy DSLs
+- **Easy to start**: Get an API up and running in minutes
+- **Auto-documentation**: Automatic OpenAPI/Swagger documentation generation
+
+## Current Status (Updated 2024-10-27)
+
+### ✅ Production-Ready Features Implemented:
+
+**Core Framework**
+- ✅ Async-first request handling with Async::Task
+- ✅ Route definition with path params
+- ✅ Request validation (body/query) with array support
+- ✅ Response schema validation and filtering
+- ✅ FastAPI-style error responses
+- ✅ Falcon server integration
+
+**Dependency Injection** ⭐ NEW
+- ✅ Block-based dependencies with `ensure` cleanup
+- ✅ Request-scoped caching
+- ✅ Nested dependencies with `FunApi::Depends()`
+- ✅ Three patterns: simple, tuple, block (Ruby-idiomatic)
+- ✅ Automatic resource lifecycle (setup → use → cleanup)
+- ✅ FastAPI `Depends()` parity
+
+**Documentation**
+- ✅ OpenAPI/Swagger documentation generation
+- ✅ Automatic /docs and /openapi.json endpoints
+- ✅ Schema introspection and conversion
+
+**Middleware**
+- ✅ Rack-compatible middleware system
+- ✅ Built-in middleware (CORS, TrustedHost, RequestLogger, Gzip)
+- ✅ FastAPI-style convenience methods
+- ✅ Full ecosystem support (rack-attack, rack-cache, etc.)
+
+**Testing**
+- ✅ Comprehensive test suite (121 tests, 281 assertions)
+- ✅ Router, schema, middleware, async, exceptions
+- ✅ Dependency injection (31 new tests)
+- ✅ Fast execution (~200ms)
+
+### 📋 What to Tackle Next
+
+### Immediate Priority
+
+1. **Background Tasks** - Post-response execution
+   - Fire-and-forget after response sent
+   - Email, logging, cleanup tasks
+   - Leverages async foundation
+   - Why: Common production pattern, natural async fit
+
+2. **Lifecycle Hooks** - Startup/shutdown
+   - App initialization/cleanup
+   - Exception handlers
+   - Why: Production deployment needs
+
+### Secondary Priority
+
+3. **Path Parameter Types** - Type coercion/validation
+4. **File Uploads** - Multipart handling  
+5. **WebSocket Support** - Real-time connections
+6. **Global Dependencies** - Apply to all routes
+7. **Dependency Overrides** - Testing utilities
+
+### Nice to Have
+
+- Content negotiation (JSON, XML, MessagePack)
+- TestClient utilities
+- Security schemes (OAuth2, JWT helpers)
+- Response streaming