funapi 0.1.0

data/docs-site/content/patterns/dependencies.md

@@ -0,0 +1,141 @@
+---
+title: Dependencies
+---
+
+# Dependencies
+
+Dependency injection lets you provide services to your handlers without global state.
+
+## Registering Dependencies
+
+Register dependencies in the app container:
+
+```ruby
+app = FunApi::App.new do |api|
+  api.register(:db) { Database.connect }
+  api.register(:logger) { Logger.new(STDOUT) }
+  api.register(:mailer) { Mailer.new }
+end
+```
+
+## Using Dependencies
+
+Request dependencies with the `depends:` parameter:
+
+```ruby
+api.get '/users', depends: [:db] do |input, req, task, db:|
+  users = db.query("SELECT * FROM users")
+  [{ users: users }, 200]
+end
+
+api.post '/contact', depends: [:mailer, :logger] do |input, req, task, mailer:, logger:|
+  logger.info("Sending contact email")
+  mailer.send(input[:body])
+  [{ sent: true }, 200]
+end
+```
+
+## Dependency Cleanup
+
+For resources that need cleanup (database connections, file handles), return a tuple:
+
+```ruby
+api.register(:db) do
+  conn = Database.connect
+  cleanup = -> { conn.close }
+  [conn, cleanup]
+end
+```
+
+The cleanup proc runs after the request completes.
+
+## Block-Style Dependencies
+
+For context-manager style cleanup (like Python's `with`):
+
+```ruby
+api.register(:transaction) do |yielder|
+  db = Database.connect
+  db.begin_transaction
+  
+  yielder.call(db)  # Yield the resource
+  
+  db.commit
+rescue
+  db.rollback
+  raise
+ensure
+  db.close
+end
+```
+
+## Per-Request Dependencies
+
+Dependencies can access request context:
+
+```ruby
+api.register(:current_user) do
+  # This runs fresh for each request
+  User.find_by_token(request.headers['Authorization'])
+end
+```
+
+## Depends Class
+
+For complex dependency graphs, use `FunApi::Depends`:
+
+```ruby
+get_db = -> { Database.connect }
+get_user = ->(db:) { db.find_user(current_token) }
+
+api.get '/profile', depends: { 
+  db: get_db, 
+  user: FunApi.Depends(get_user, db: :db) 
+} do |input, req, task, db:, user:|
+  [{ user: user }, 200]
+end
+```
+
+## Complete Example
+
+```ruby
+require 'funapi'
+require 'funapi/server/falcon'
+
+app = FunApi::App.new(title: "My API") do |api|
+  # Simple dependency
+  api.register(:logger) { Logger.new(STDOUT) }
+  
+  # Dependency with cleanup
+  api.register(:db) do
+    conn = PG.connect(ENV['DATABASE_URL'])
+    [conn, -> { conn.close }]
+  end
+  
+  # Block-style dependency
+  api.register(:transaction) do |yielder|
+    conn = PG.connect(ENV['DATABASE_URL'])
+    conn.exec("BEGIN")
+    yielder.call(conn)
+    conn.exec("COMMIT")
+  rescue
+    conn.exec("ROLLBACK")
+    raise
+  ensure
+    conn.close
+  end
+
+  api.get '/users', depends: [:db, :logger] do |input, req, task, db:, logger:|
+    logger.info("Fetching users")
+    result = db.exec("SELECT * FROM users")
+    [{ users: result.to_a }, 200]
+  end
+
+  api.post '/users', depends: [:transaction] do |input, req, task, transaction:|
+    transaction.exec("INSERT INTO users (name) VALUES ($1)", [input[:body][:name]])
+    [{ created: true }, 201]
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 3000)
+```

data/docs-site/content/patterns/deployment.md

@@ -0,0 +1,212 @@
+---
+title: Deployment
+---
+
+# Deployment
+
+Deploy FunApi applications to production.
+
+## Running with Falcon
+
+FunApi uses Falcon as its server:
+
+```ruby
+# app.rb
+require 'funapi'
+require 'funapi/server/falcon'
+
+app = FunApi::App.new do |api|
+  # routes...
+end
+
+FunApi::Server::Falcon.start(app, 
+  host: '0.0.0.0',
+  port: ENV.fetch('PORT', 3000).to_i
+)
+```
+
+```bash
+ruby app.rb
+```
+
+## Environment Variables
+
+Configure your app with environment variables:
+
+```ruby
+app = FunApi::App.new do |api|
+  api.on_startup do
+    DB.connect(ENV.fetch('DATABASE_URL'))
+  end
+
+  if ENV['RACK_ENV'] == 'production'
+    api.add_trusted_host(allowed_hosts: [ENV['HOST']])
+  end
+end
+```
+
+## Docker
+
+### Dockerfile
+
+```dockerfile
+FROM ruby:3.2-alpine
+
+RUN apk add --no-cache build-base
+
+WORKDIR /app
+
+COPY Gemfile Gemfile.lock ./
+RUN bundle install --without development test
+
+COPY . .
+
+EXPOSE 3000
+
+CMD ["ruby", "app.rb"]
+```
+
+### docker-compose.yml
+
+```yaml
+version: '3.8'
+
+services:
+  web:
+    build: .
+    ports:
+      - "3000:3000"
+    environment:
+      - DATABASE_URL=postgres://postgres:password@db/myapp
+      - RACK_ENV=production
+    depends_on:
+      - db
+
+  db:
+    image: postgres:15
+    environment:
+      - POSTGRES_PASSWORD=password
+      - POSTGRES_DB=myapp
+    volumes:
+      - postgres_data:/var/lib/postgresql/data
+
+volumes:
+  postgres_data:
+```
+
+## Fly.io
+
+### fly.toml
+
+```toml
+app = "my-funapi-app"
+primary_region = "iad"
+
+[build]
+  builder = "heroku/buildpacks:22"
+
+[env]
+  RACK_ENV = "production"
+
+[http_service]
+  internal_port = 3000
+  force_https = true
+  auto_stop_machines = true
+  auto_start_machines = true
+```
+
+Deploy:
+
+```bash
+fly launch
+fly deploy
+```
+
+## Render
+
+Create a `render.yaml`:
+
+```yaml
+services:
+  - type: web
+    name: my-funapi-app
+    env: ruby
+    buildCommand: bundle install
+    startCommand: ruby app.rb
+    envVars:
+      - key: RACK_ENV
+        value: production
+      - key: DATABASE_URL
+        fromDatabase:
+          name: mydb
+          property: connectionString
+```
+
+## Production Checklist
+
+### Security
+
+```ruby
+app = FunApi::App.new do |api|
+  # Validate host header
+  api.add_trusted_host(allowed_hosts: ['myapp.com', 'api.myapp.com'])
+  
+  # CORS with specific origins
+  api.add_cors(allow_origins: ['https://myapp.com'])
+end
+```
+
+### Logging
+
+```ruby
+api.add_request_logger(
+  logger: Logger.new(STDOUT),
+  level: :info
+)
+```
+
+### Error Handling
+
+Don't expose internal errors in production:
+
+```ruby
+class ProductionErrorHandler
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    @app.call(env)
+  rescue => e
+    # Log the real error
+    Logger.new(STDOUT).error("#{e.class}: #{e.message}")
+    
+    # Return generic message
+    [500, {'content-type' => 'application/json'}, 
+     ['{"detail":"Internal server error"}']]
+  end
+end
+
+app = FunApi::App.new do |api|
+  api.use ProductionErrorHandler if ENV['RACK_ENV'] == 'production'
+end
+```
+
+### Health Check
+
+```ruby
+api.get '/health' do |input, req, task|
+  [{ status: 'ok', time: Time.now.iso8601 }, 200]
+end
+```
+
+### Graceful Shutdown
+
+FunApi handles SIGINT and SIGTERM automatically, running shutdown hooks before exiting.
+
+```ruby
+api.on_shutdown do
+  puts "Draining connections..."
+  ConnectionPool.shutdown
+end
+```

data/docs-site/content/patterns/error-handling.md

@@ -0,0 +1,184 @@
+---
+title: Error Handling
+---
+
+# Error Handling
+
+FunApi provides FastAPI-style error responses.
+
+## HTTPException
+
+Raise `HTTPException` to return an error response:
+
+```ruby
+api.get '/users/:id' do |input, req, task|
+  user = find_user(input[:path]['id'])
+  
+  unless user
+    raise FunApi::HTTPException.new(
+      status_code: 404,
+      detail: "User not found"
+    )
+  end
+  
+  [{ user: user }, 200]
+end
+```
+
+Response:
+
+```json
+{
+  "detail": "User not found"
+}
+```
+
+## Common Status Codes
+
+```ruby
+# 400 Bad Request
+raise FunApi::HTTPException.new(status_code: 400, detail: "Invalid input")
+
+# 401 Unauthorized
+raise FunApi::HTTPException.new(status_code: 401, detail: "Authentication required")
+
+# 403 Forbidden
+raise FunApi::HTTPException.new(status_code: 403, detail: "Permission denied")
+
+# 404 Not Found
+raise FunApi::HTTPException.new(status_code: 404, detail: "Resource not found")
+
+# 409 Conflict
+raise FunApi::HTTPException.new(status_code: 409, detail: "Already exists")
+
+# 422 Unprocessable Entity
+raise FunApi::HTTPException.new(status_code: 422, detail: "Validation failed")
+
+# 500 Internal Server Error
+raise FunApi::HTTPException.new(status_code: 500, detail: "Something went wrong")
+```
+
+## Custom Headers
+
+Add headers to error responses:
+
+```ruby
+raise FunApi::HTTPException.new(
+  status_code: 401,
+  detail: "Token expired",
+  headers: { 'WWW-Authenticate' => 'Bearer' }
+)
+```
+
+## ValidationError
+
+`ValidationError` is raised automatically by schema validation, but you can raise it manually:
+
+```ruby
+raise FunApi::ValidationError.new(
+  errors: [
+    { path: [:email], text: "is invalid" }
+  ]
+)
+```
+
+Response (422):
+
+```json
+{
+  "detail": [
+    {
+      "loc": ["email"],
+      "msg": "is invalid",
+      "type": "value_error"
+    }
+  ]
+}
+```
+
+## Handling Exceptions in Handlers
+
+Use standard Ruby exception handling:
+
+```ruby
+api.get '/external' do |input, req, task|
+  begin
+    data = ExternalAPI.fetch
+    [{ data: data }, 200]
+  rescue ExternalAPI::Timeout
+    raise FunApi::HTTPException.new(
+      status_code: 504,
+      detail: "External service timeout"
+    )
+  rescue ExternalAPI::Error => e
+    raise FunApi::HTTPException.new(
+      status_code: 502,
+      detail: "External service error: #{e.message}"
+    )
+  end
+end
+```
+
+## Custom Error Classes
+
+Create domain-specific errors:
+
+```ruby
+class NotFoundError < FunApi::HTTPException
+  def initialize(resource, id)
+    super(
+      status_code: 404,
+      detail: "#{resource} with id #{id} not found"
+    )
+  end
+end
+
+class UnauthorizedError < FunApi::HTTPException
+  def initialize(message = "Authentication required")
+    super(
+      status_code: 401,
+      detail: message,
+      headers: { 'WWW-Authenticate' => 'Bearer' }
+    )
+  end
+end
+
+# Usage
+api.get '/users/:id' do |input, req, task|
+  user = find_user(input[:path]['id'])
+  raise NotFoundError.new('User', input[:path]['id']) unless user
+  [{ user: user }, 200]
+end
+```
+
+## Error Middleware
+
+Handle errors globally with middleware:
+
+```ruby
+class ErrorHandlerMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    @app.call(env)
+  rescue StandardError => e
+    # Log the error
+    puts "Error: #{e.message}"
+    puts e.backtrace.first(5).join("\n")
+    
+    # Return generic error in production
+    [
+      500,
+      { 'content-type' => 'application/json' },
+      [JSON.dump(detail: 'Internal server error')]
+    ]
+  end
+end
+
+app = FunApi::App.new do |api|
+  api.use ErrorHandlerMiddleware
+  # routes...
+end
+```

data/docs-site/content/patterns/response-schema.md

@@ -0,0 +1,159 @@
+---
+title: Response Schema
+---
+
+# Response Schema
+
+Filter and validate response data before sending to clients.
+
+## Why Response Schemas?
+
+Response schemas help you:
+
+1. **Filter sensitive data** - Remove passwords, tokens, internal IDs
+2. **Validate output** - Catch bugs before they reach clients
+3. **Document responses** - Auto-generate OpenAPI response schemas
+
+## Basic Usage
+
+Define a schema for the response:
+
+```ruby
+UserOutputSchema = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+end
+
+api.get '/users/:id', response_schema: UserOutputSchema do |input, req, task|
+  user = find_user(input[:path]['id'])
+  # Even if user has :password, :api_key, etc., they're filtered out
+  [user, 200]
+end
+```
+
+## Filtering Sensitive Data
+
+```ruby
+# Internal user record
+user = {
+  id: 1,
+  name: "Alice",
+  email: "alice@example.com",
+  password_hash: "abc123...",
+  api_key: "secret...",
+  internal_notes: "VIP customer"
+}
+
+# With response_schema: UserOutputSchema
+# Client receives only:
+{
+  "id": 1,
+  "name": "Alice",
+  "email": "alice@example.com"
+}
+```
+
+## Array Responses
+
+For array responses, wrap the schema in brackets:
+
+```ruby
+api.get '/users', response_schema: [UserOutputSchema] do |input, req, task|
+  users = fetch_all_users
+  [users, 200]
+end
+```
+
+## Different Input/Output Schemas
+
+Common pattern: accept more fields than you return.
+
+```ruby
+UserCreateSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+  required(:password).filled(:string)
+end
+
+UserOutputSchema = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+  required(:created_at).filled(:string)
+end
+
+api.post '/users', 
+  body: UserCreateSchema, 
+  response_schema: UserOutputSchema do |input, req, task|
+  
+  user = create_user(input[:body])
+  # password is filtered out of response
+  [user, 201]
+end
+```
+
+## Nested Objects
+
+```ruby
+AddressSchema = FunApi::Schema.define do
+  required(:city).filled(:string)
+  required(:country).filled(:string)
+end
+
+UserWithAddressSchema = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:name).filled(:string)
+  required(:address).hash do
+    required(:city).filled(:string)
+    required(:country).filled(:string)
+  end
+end
+
+api.get '/users/:id', response_schema: UserWithAddressSchema do |input, req, task|
+  user = find_user_with_address(input[:path]['id'])
+  [user, 200]
+end
+```
+
+## Validation Errors
+
+If your response doesn't match the schema, FunApi returns a 500 error:
+
+```ruby
+api.get '/broken', response_schema: UserOutputSchema do |input, req, task|
+  # Missing required :email field
+  [{ id: 1, name: "Alice" }, 200]
+end
+
+# Response: 500
+# {"detail":"Response validation failed: {:email=>[\"is missing\"]}"}
+```
+
+This helps catch bugs in development before they reach production.
+
+## OpenAPI Integration
+
+Response schemas appear in your OpenAPI documentation:
+
+```json
+{
+  "paths": {
+    "/users/{id}": {
+      "get": {
+        "responses": {
+          "200": {
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/UserOutputSchema"
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```