funapi 0.1.0

data/AGENTS.md

@@ -0,0 +1,416 @@
+# FunApi - Agent Instructions
+
+FunApi is a minimal, async-first Ruby web framework inspired by FastAPI. This file contains essential context for AI coding agents working on this project.
+
+## Project Overview
+
+**Goal**: Bring FastAPI's excellent developer experience to Ruby with async-first architecture.
+
+**Core Philosophy**:
+- Async-first using Ruby's `Async` library and Falcon server
+- Simple validation with dry-schema
+- Minimal magic, clear explicit APIs
+- Automatic OpenAPI/Swagger documentation
+- Rack-compatible middleware system
+
+**Target Ruby Version**: >= 3.2.0
+
+## Setup Commands
+
+```bash
+# Install dependencies
+./bin/bundle install
+
+# Run tests
+./bin/bundle exec rake test
+
+# Run linter (Standard Ruby)
+./bin/bundle exec rake standard
+
+# Run linter with auto-fix
+./bin/bundle exec standardrb --fix
+
+# Run both tests and linting
+./bin/bundle exec rake
+```
+
+## Development Workflow
+
+### Running Examples
+
+```bash
+# Middleware demo (port 3000)
+ruby examples/middleware_demo.rb
+
+# OpenAPI demo (port 9292)
+ruby test/demo_openapi.rb
+
+# Middleware test demo
+ruby test/demo_middleware.rb
+```
+
+### Testing Changes
+
+1. Run examples to verify functionality manually
+2. Run `bundle exec rake test` to ensure tests pass
+3. Run `bundle exec rake standard` to check code style
+4. Check OpenAPI docs at `http://localhost:PORT/docs` when running examples
+
+## Code Style Guidelines
+
+**Linter**: Standard Ruby (standardrb)
+- Ruby version: 3.2 (configured in `.standard.yml`)
+- **IMPORTANT**: DO NOT add comments unless explicitly requested
+- Follow Standard Ruby formatting automatically
+
+**Conventions**:
+- Use frozen string literals: `# frozen_string_literal: true`
+- Prefer keyword arguments for options
+- Use Ruby 3+ pattern matching where appropriate
+- Keep methods focused and single-purpose
+- Use descriptive variable names (no abbreviations)
+
+**File Organization**:
+- Core framework: `lib/funapi/`
+- Middleware: `lib/funapi/middleware/`
+- OpenAPI: `lib/funapi/openapi/`
+- Server adapters: `lib/funapi/server/`
+- Examples: `examples/`
+- Tests/Demos: `test/`
+
+## Architecture Patterns
+
+### Route Handlers
+
+All route handlers receive three parameters:
+```ruby
+api.get '/path' do |input, req, task|
+  # input: { path: {...}, query: {...}, body: {...} }
+  # req: Rack::Request object
+  # task: Async::Task for concurrent operations
+
+  [response_data, status_code]
+end
+```
+
+### Async Operations
+
+Use the `task` parameter for concurrent operations:
+```ruby
+api.get '/dashboard/:id' do |input, req, task|
+  user_task = task.async { fetch_user(id) }
+  posts_task = task.async { fetch_posts(id) }
+
+  data = {
+    user: user_task.wait,
+    posts: posts_task.wait
+  }
+
+  [data, 200]
+end
+```
+
+### Validation Schemas
+
+Use dry-schema for request validation:
+```ruby
+MySchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  optional(:age).filled(:integer)
+end
+
+# Apply to routes
+api.post '/users', body: MySchema do |input, req, task|
+  user = input[:body]  # Already validated
+  [user, 201]
+end
+```
+
+### Middleware
+
+Follow standard Rack middleware pattern:
+```ruby
+class MyMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    # Before request
+    status, headers, body = @app.call(env)
+    # After request
+    [status, headers, body]
+  end
+end
+
+# Use keyword arguments for options
+class ConfigurableMiddleware
+  def initialize(app, **options)
+    @app = app
+    @option = options[:option]
+  end
+end
+```
+
+### Lifecycle Hooks
+
+Run code at startup/shutdown:
+```ruby
+api.on_startup do
+  DB.connect
+  Cache.warm
+end
+
+api.on_shutdown do
+  DB.disconnect
+end
+```
+
+- Multiple hooks allowed (run in registration order)
+- Startup hooks run before server accepts requests
+- Shutdown hooks run after server stops
+- Shutdown errors logged but don't stop other hooks
+
+### Template Rendering
+
+Return `TemplateResponse` for HTML instead of JSON:
+```ruby
+require 'funapi/templates'
+
+templates = FunApi::Templates.new(
+  directory: 'templates',
+  layout: 'layouts/application.html.erb'  # optional default layout
+)
+
+api.get '/' do |input, req, task|
+  templates.response('home.html.erb', title: 'Home', user: current_user)
+end
+
+# Disable layout for HTMX partials
+api.post '/items' do |input, req, task|
+  templates.response('_item.html.erb', layout: false, item: item, status: 201)
+end
+
+# Use with_layout for route groups
+admin = templates.with_layout('layouts/admin.html.erb')
+api.get '/admin' do |input, req, task|
+  admin.response('dashboard.html.erb', title: 'Admin')
+end
+```
+
+**Layout templates** use `yield_content`:
+```erb
+<!DOCTYPE html>
+<html>
+<head><title><%= title %></title></head>
+<body><%= yield_content %></body>
+</html>
+```
+
+**Partials** via `render_partial`:
+```erb
+<% items.each do |item| %>
+  <%= render_partial('_item.html.erb', item: item) %>
+<% end %>
+```
+
+## Key Files and Their Purpose
+
+- `lib/funapi/application.rb` - Main App class, route registration, middleware system
+- `lib/funapi/router.rb` - Route matching and path parameter extraction
+- `lib/funapi/schema.rb` - Validation wrapper around dry-schema
+- `lib/funapi/exceptions.rb` - HTTPException, ValidationError, TemplateNotFoundError
+- `lib/funapi/templates.rb` - ERB template rendering with layouts/partials
+- `lib/funapi/template_response.rb` - HTML response wrapper
+- `lib/funapi/middleware/` - Built-in middleware (CORS, TrustedHost, RequestLogger)
+- `lib/funapi/openapi/` - OpenAPI spec generation from routes and schemas
+- `lib/funapi/server/falcon.rb` - Falcon server integration
+
+## Common Tasks
+
+### Adding a New Built-in Middleware
+
+1. Create file in `lib/funapi/middleware/my_middleware.rb`
+2. Follow pattern:
+   ```ruby
+   module FunApi
+     module Middleware
+       class MyMiddleware
+         def initialize(app, **options)
+           @app = app
+           # Store options
+         end
+
+         def call(env)
+           # Middleware logic
+           @app.call(env)
+         end
+       end
+     end
+   end
+   ```
+3. Add convenience method to `lib/funapi/application.rb`:
+   ```ruby
+   def add_my_middleware(**options)
+     require_relative 'middleware/my_middleware'
+     use FunApi::Middleware::MyMiddleware, **options
+   end
+   ```
+4. Require in `lib/funapi/middleware.rb`
+5. Add example to `examples/middleware_demo.rb`
+6. Update README.md middleware section
+
+### Adding a New Route Helper
+
+1. Add method to `lib/funapi/application.rb`
+2. Follow existing pattern (get, post, put, patch, delete)
+3. Use `add_route` internally with proper verb
+
+### Extending OpenAPI Generation
+
+1. Schema conversion: `lib/funapi/openapi/schema_converter.rb`
+2. Spec generation: `lib/funapi/openapi/spec_generator.rb`
+3. Test with `ruby test/demo_openapi.rb` and check `/docs`
+
+## Testing Instructions
+
+**Test Framework**: Minitest
+**Test Structure**: Flat (following Sidekiq pattern)
+**Current Status**: 174 tests, 487 assertions, all passing (~220ms)
+
+### Running Tests
+
+```bash
+# All tests
+bundle exec rake test
+
+# Single test file
+bundle exec ruby -Itest test/test_router.rb
+
+# Single test
+bundle exec ruby -Itest test/test_router.rb -n test_root_route_matches
+
+# Tests + linting
+bundle exec rake
+```
+
+### Test Files
+
+All tests live in `test/` (flat structure):
+- `test_fun_api.rb` - Basic smoke tests (10 tests)
+- `test_router.rb` - Router functionality (11 tests)
+- `test_schema.rb` - Schema validation (14 tests)
+- `test_middleware.rb` - Middleware chain (12 tests)
+- `test_validation.rb` - Request validation (14 tests)
+- `test_response_schema.rb` - Response filtering (9 tests)
+- `test_async.rb` - Async operations (10 tests)
+- `test_exceptions.rb` - Error handling (10 tests)
+- `test_templates.rb` - Template rendering (37 tests)
+- `test_lifecycle.rb` - Lifecycle hooks (14 tests)
+
+### Writing Tests
+
+Follow existing patterns:
+```ruby
+class TestMyFeature < Minitest::Test
+  def async_request(app, method, path, **options)
+    Async do
+      Rack::MockRequest.new(app).send(method, path, **options)
+    end.wait
+  end
+
+  def test_something
+    app = FunApi::App.new do |api|
+      api.get '/test' do |input, req, task|
+        [{ message: 'test' }, 200]
+      end
+    end
+
+    res = async_request(app, :get, '/test')
+    assert_equal 200, res.status
+  end
+end
+```
+
+### Test Coverage
+
+✅ Router (path matching, parameters, 404s)
+✅ Schema validation (success, failure, errors, arrays)
+✅ Middleware (chain building, ordering, built-ins)
+✅ Request validation (query/body, error format)
+✅ Response schemas (filtering, arrays, nested)
+✅ Async operations (concurrency, timeouts, dependencies)
+✅ Exceptions (HTTPException, custom errors)
+✅ Templates (rendering, layouts, partials, with_layout)
+✅ Lifecycle hooks (startup/shutdown, error handling)
+
+### Manual Testing
+
+1. Run example apps in `examples/`
+2. Test with curl:
+   ```bash
+   curl http://localhost:3000/
+   curl -X POST http://localhost:3000/users \
+     -H 'Content-Type: application/json' \
+     -d '{"name":"Test","email":"test@example.com"}'
+   ```
+3. Check OpenAPI docs at `/docs`
+4. Verify middleware behavior (CORS headers, logging, etc.)
+
+### Before Committing
+
+- Run `bundle exec rake` (tests + linting)
+- Ensure all tests pass
+- Check no temporary files in project root
+- Update tests if adding new features
+
+## Security Considerations
+
+- **Sensitive Data**: Never log passwords, tokens, or API keys
+- **Response Schemas**: Use response_schema to filter sensitive fields from responses
+- **Trusted Host**: Always use `add_trusted_host` in production
+- **CORS**: Configure `add_cors` with specific origins, not `['*']` in production
+- **Validation**: Always validate user input with schemas
+
+## Common Pitfalls
+
+1. **Root Route Bug**: The router has special handling for `/` - don't change it
+2. **Keyword Arguments**: Middleware must accept `**options`, not positional args
+3. **Async Context**: Route handlers must be called within Async::Task context
+4. **Path Params**: Always strings in `input[:path]`, convert types manually
+5. **Response Format**: Must return `[data, status_code]` from handlers
+6. **Middleware Order**: First registered runs first (FIFO execution, LIFO wrapping)
+
+## Dependencies
+
+**Core**:
+- `async` (>= 2.8) - Async/concurrency primitives
+- `falcon` (>= 0.44) - Async HTTP server
+- `rack` (>= 3.0.0) - Web server interface
+- `dry-schema` (>= 1.13) - Validation
+
+**Middleware**:
+- `rack-cors` (>= 2.0) - CORS support
+
+**Development**:
+- `standard` - Ruby style guide and linter
+- `minitest` - Testing framework
+
+
+## Future Enhancements Roadmap
+
+See `README.md` for full list. Key priorities:
+1. ~~Dependency injection system~~ ✅ Done
+2. ~~Background tasks~~ ✅ Done
+3. ~~Template rendering~~ ✅ Done
+4. ~~Lifecycle hooks (startup/shutdown)~~ ✅ Done
+5. Path parameter type validation
+6. WebSocket support
+
+## Questions?
+
+Check these resources:
+- `/examples` - Working demo applications
+- `/test` - Demo scripts showing features
+- `/.claude` - Implementation plans and notes
+- `README.md` - User-facing documentation

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-10-12
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Felipe
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.