funapi 0.1.0

data/docs-site/content/getting-started/quick-start.md

@@ -0,0 +1,127 @@
+---
+title: Quick Start
+---
+
+# Quick Start
+
+Get a FunApi application running in under 5 minutes.
+
+## Installation
+
+Add FunApi to your Gemfile:
+
+```ruby
+gem 'funapi'
+```
+
+Then install:
+
+```bash
+bundle install
+```
+
+## Create Your First App
+
+Create a file called `app.rb`:
+
+```ruby
+require 'funapi'
+require 'funapi/server/falcon'
+
+app = FunApi::App.new(
+  title: "My First API",
+  version: "1.0.0"
+) do |api|
+  api.get '/hello' do |input, req, task|
+    [{ message: 'Hello, World!' }, 200]
+  end
+
+  api.get '/hello/:name' do |input, req, task|
+    name = input[:path]['name']
+    [{ message: "Hello, #{name}!" }, 200]
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 3000)
+```
+
+## Run It
+
+```bash
+ruby app.rb
+```
+
+You should see:
+
+```
+Falcon listening on 0.0.0.0:3000
+Try: curl http://0.0.0.0:3000/hello
+Press Ctrl+C to stop
+```
+
+## Test It
+
+```bash
+$ curl http://localhost:3000/hello
+{"message":"Hello, World!"}
+
+$ curl http://localhost:3000/hello/Ruby
+{"message":"Hello, Ruby!"}
+```
+
+## Check the Docs
+
+Open your browser to `http://localhost:3000/docs`
+
+You'll see interactive Swagger UI documentation automatically generated from your routes.
+
+## Add Validation
+
+Let's add a POST endpoint with request validation:
+
+```ruby
+require 'funapi'
+require 'funapi/server/falcon'
+
+UserSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+  optional(:age).filled(:integer)
+end
+
+app = FunApi::App.new(title: "My API") do |api|
+  api.get '/hello' do |input, req, task|
+    [{ message: 'Hello, World!' }, 200]
+  end
+
+  api.post '/users', body: UserSchema do |input, req, task|
+    user = input[:body]
+    # user is already validated!
+    [{ created: user }, 201]
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 3000)
+```
+
+Test the validation:
+
+```bash
+# Valid request
+$ curl -X POST http://localhost:3000/users \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Alice","email":"alice@example.com"}'
+{"created":{"name":"Alice","email":"alice@example.com"}}
+
+# Invalid request (missing email)
+$ curl -X POST http://localhost:3000/users \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Alice"}'
+{"detail":[{"loc":["body","email"],"msg":"is missing","type":"value_error"}]}
+```
+
+## Next Steps
+
+- [Key Concepts](/docs/getting-started/key-concepts) - Understand the core ideas
+- [Routing](/docs/essential/routing) - Learn about path parameters and HTTP methods
+- [Validation](/docs/essential/validation) - Deep dive into dry-schema

data/docs-site/content/index.md

@@ -0,0 +1,81 @@
+---
+title: FunApi
+---
+
+# FunApi
+
+A minimal, async-first Ruby web framework inspired by FastAPI.
+
+```ruby
+require 'funapi'
+require 'funapi/server/falcon'
+
+UserSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+end
+
+app = FunApi::App.new(title: "My API", version: "1.0.0") do |api|
+  api.get '/hello' do |input, req, task|
+    [{ message: 'Hello, World!' }, 200]
+  end
+
+  api.post '/users', body: UserSchema do |input, req, task|
+    [{ created: input[:body] }, 201]
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 3000)
+```
+
+Visit `http://localhost:3000/docs` to see your interactive API documentation.
+
+## Key Features
+
+- **Async-first** - Built on Falcon and Ruby's Async library for high-performance concurrent operations
+- **Simple validation** - Using dry-schema for straightforward request/response validation
+- **Auto-documentation** - Automatic OpenAPI/Swagger docs generated from your code
+- **Minimal magic** - Clear, explicit APIs without heavy DSLs
+- **Rack-compatible** - Works with any Rack middleware
+
+## Standing on Giants
+
+FunApi brings together proven Ruby libraries:
+
+- **[Falcon](https://github.com/socketry/falcon)** - High-performance async HTTP server
+- **[dry-schema](https://dry-rb.org/gems/dry-schema/)** - Powerful, composable validation
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'funapi'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Example
+
+```ruby
+require 'funapi'
+require 'funapi/server/falcon'
+
+app = FunApi::App.new do |api|
+  api.get '/hello/:name' do |input, req, task|
+    name = input[:path]['name']
+    [{ message: "Hello, #{name}!" }, 200]
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 3000)
+```
+
+```bash
+$ curl http://localhost:3000/hello/world
+{"message":"Hello, world!"}
+```

data/docs-site/content/patterns/async-operations.md

@@ -0,0 +1,137 @@
+---
+title: Async Operations
+---
+
+# Async Operations
+
+FunApi is async-first. Every handler receives an `Async::Task` for concurrent operations.
+
+## The Task Parameter
+
+The third handler parameter is an `Async::Task`:
+
+```ruby
+api.get '/dashboard' do |input, req, task|
+  # task is Async::Task.current
+end
+```
+
+## Concurrent Fetches
+
+Run multiple operations in parallel:
+
+```ruby
+api.get '/dashboard/:id' do |input, req, task|
+  id = input[:path]['id']
+
+  # These run concurrently
+  user_task = task.async { fetch_user(id) }
+  posts_task = task.async { fetch_posts(id) }
+  stats_task = task.async { fetch_stats(id) }
+
+  # Wait for all to complete
+  [{
+    user: user_task.wait,
+    posts: posts_task.wait,
+    stats: stats_task.wait
+  }, 200]
+end
+```
+
+Without async, this would take `time(user) + time(posts) + time(stats)`.
+With async, it takes `max(time(user), time(posts), time(stats))`.
+
+## Error Handling
+
+Handle errors from async operations:
+
+```ruby
+api.get '/data' do |input, req, task|
+  primary = task.async { fetch_from_primary }
+  fallback = task.async { fetch_from_fallback }
+
+  begin
+    [{ data: primary.wait }, 200]
+  rescue => e
+    # Primary failed, use fallback
+    [{ data: fallback.wait, source: 'fallback' }, 200]
+  end
+end
+```
+
+## Timeouts
+
+Add timeouts to operations:
+
+```ruby
+api.get '/external' do |input, req, task|
+  result = task.with_timeout(5) do
+    fetch_from_slow_api
+  end
+  
+  [{ data: result }, 200]
+rescue Async::TimeoutError
+  raise FunApi::HTTPException.new(
+    status_code: 504,
+    detail: "External API timeout"
+  )
+end
+```
+
+## Sleep
+
+Use `Kernel#sleep` (not `task.sleep`):
+
+```ruby
+api.get '/delayed' do |input, req, task|
+  sleep(1)  # Non-blocking in async context
+  [{ message: 'Done' }, 200]
+end
+```
+
+## Real-World Example
+
+```ruby
+api.get '/user/:id/feed' do |input, req, task|
+  user_id = input[:path]['id']
+
+  # Fetch user and check permissions first
+  user = fetch_user(user_id)
+  raise FunApi::HTTPException.new(status_code: 404) unless user
+
+  # Then fetch feed data concurrently
+  posts = task.async { Post.where(user_id: user_id).limit(20) }
+  notifications = task.async { Notification.unread(user_id) }
+  suggestions = task.async { RecommendationService.for(user_id) }
+
+  [{
+    user: user,
+    posts: posts.wait,
+    notifications: notifications.wait,
+    suggestions: suggestions.wait
+  }, 200]
+end
+```
+
+## When to Use Async
+
+**Good candidates:**
+- Multiple independent database queries
+- External API calls
+- File I/O operations
+- Any I/O-bound work
+
+**Not needed for:**
+- CPU-bound calculations
+- Single database query
+- Simple transformations
+
+## Technical Details
+
+FunApi uses Ruby's [Async](https://github.com/socketry/async) library and [Falcon](https://github.com/socketry/falcon) server. The task parameter is the current `Async::Task`, giving you access to the full Async API.
+
+```ruby
+# These are equivalent
+task.async { work }
+Async::Task.current.async { work }
+```

data/docs-site/content/patterns/background-tasks.md

@@ -0,0 +1,143 @@
+---
+title: Background Tasks
+---
+
+# Background Tasks
+
+Execute tasks after the response is sent to the client.
+
+## Basic Usage
+
+Request the `background:` parameter in your handler:
+
+```ruby
+api.post '/signup', body: UserSchema do |input, req, task, background:|
+  user = create_user(input[:body])
+  
+  # These run AFTER the response is sent
+  background.add_task(method(:send_welcome_email), user[:email])
+  background.add_task(method(:log_signup), user[:id])
+  
+  [{ user: user }, 201]
+end
+```
+
+The client receives the response immediately. The tasks execute afterward.
+
+## Adding Tasks
+
+### With Method References
+
+```ruby
+def send_email(to, subject)
+  # send email
+end
+
+background.add_task(method(:send_email), "user@example.com", "Welcome!")
+```
+
+### With Lambdas
+
+```ruby
+background.add_task(->(email) { Mailer.send(email) }, user[:email])
+```
+
+### With Keyword Arguments
+
+```ruby
+background.add_task(
+  ->(to:, subject:) { send_email(to: to, subject: subject) },
+  to: "user@example.com",
+  subject: "Welcome!"
+)
+```
+
+## With Dependencies
+
+Dependencies are available to background tasks:
+
+```ruby
+api.register(:mailer) { Mailer.new }
+api.register(:analytics) { Analytics.new }
+
+api.post '/signup', depends: [:mailer, :analytics] do |input, req, task, mailer:, analytics:, background:|
+  user = create_user(input[:body])
+  
+  # Dependencies captured in closure
+  background.add_task(lambda {
+    mailer.send_welcome(user[:email])
+    analytics.track('signup', user[:id])
+  })
+  
+  [{ user: user }, 201]
+end
+```
+
+## Error Handling
+
+Background task errors are logged but don't affect the response:
+
+```ruby
+background.add_task(lambda {
+  raise "Task failed!"
+  # Logged as warning, doesn't crash the server
+})
+```
+
+## When to Use
+
+**Good for:**
+- Email notifications
+- Logging and analytics
+- Cache warming
+- Simple webhook calls
+- Audit trail recording
+
+**Not for:**
+- Long-running jobs (> 30 seconds)
+- Jobs requiring persistence
+- Jobs that must survive restarts
+- Jobs needing retries
+
+For complex jobs, use a proper job queue like Sidekiq or GoodJob.
+
+## Complete Example
+
+```ruby
+require 'funapi'
+require 'funapi/server/falcon'
+
+def send_welcome_email(email)
+  puts "Sending welcome email to #{email}"
+  # Actually send email
+end
+
+def log_signup(user_id)
+  puts "Logging signup for user #{user_id}"
+  # Log to analytics
+end
+
+def notify_admin(user)
+  puts "Notifying admin about new user: #{user[:name]}"
+  # Send Slack notification
+end
+
+app = FunApi::App.new do |api|
+  UserSchema = FunApi::Schema.define do
+    required(:name).filled(:string)
+    required(:email).filled(:string)
+  end
+
+  api.post '/signup', body: UserSchema do |input, req, task, background:|
+    user = { id: rand(1000), **input[:body] }
+    
+    background.add_task(method(:send_welcome_email), user[:email])
+    background.add_task(method(:log_signup), user[:id])
+    background.add_task(method(:notify_admin), user)
+    
+    [{ user: user, message: 'Check your email!' }, 201]
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 3000)
+```

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

@@ -0,0 +1,175 @@
+---
+title: Database
+---
+
+# Database
+
+FunApi works with any database library. Here's how to integrate common options.
+
+## With db-postgres
+
+[db-postgres](https://github.com/socketry/db-postgres) is async-native and works great with FunApi:
+
+```ruby
+require 'funapi'
+require 'db/postgres'
+require 'funapi/server/falcon'
+
+app = FunApi::App.new do |api|
+  api.on_startup do
+    $db = DB::Postgres::Connection.new(
+      host: 'localhost',
+      database: 'myapp',
+      user: 'postgres'
+    )
+  end
+
+  api.on_shutdown do
+    $db&.close
+  end
+
+  api.get '/users' do |input, req, task|
+    result = $db.query("SELECT id, name, email FROM users")
+    [{ users: result.to_a }, 200]
+  end
+end
+```
+
+## With Sequel
+
+[Sequel](https://sequel.jeremyevans.net/) is a powerful database toolkit:
+
+```ruby
+require 'funapi'
+require 'sequel'
+require 'funapi/server/falcon'
+
+DB = Sequel.connect(ENV['DATABASE_URL'])
+
+app = FunApi::App.new do |api|
+  api.get '/users' do |input, req, task|
+    users = DB[:users].all
+    [{ users: users }, 200]
+  end
+
+  api.get '/users/:id' do |input, req, task|
+    user = DB[:users].where(id: input[:path]['id']).first
+    raise FunApi::HTTPException.new(status_code: 404) unless user
+    [{ user: user }, 200]
+  end
+
+  api.post '/users', body: UserSchema do |input, req, task|
+    id = DB[:users].insert(input[:body])
+    user = DB[:users].where(id: id).first
+    [{ user: user }, 201]
+  end
+end
+```
+
+## With ActiveRecord
+
+You can use ActiveRecord standalone (without Rails):
+
+```ruby
+require 'funapi'
+require 'active_record'
+require 'funapi/server/falcon'
+
+ActiveRecord::Base.establish_connection(ENV['DATABASE_URL'])
+
+class User < ActiveRecord::Base
+end
+
+app = FunApi::App.new do |api|
+  api.get '/users' do |input, req, task|
+    users = User.all.map(&:attributes)
+    [{ users: users }, 200]
+  end
+
+  api.post '/users', body: UserSchema do |input, req, task|
+    user = User.create!(input[:body])
+    [{ user: user.attributes }, 201]
+  end
+end
+```
+
+## Connection Pooling with Dependencies
+
+Use dependency injection for connection management:
+
+```ruby
+require 'connection_pool'
+
+app = FunApi::App.new do |api|
+  pool = ConnectionPool.new(size: 10) do
+    PG.connect(ENV['DATABASE_URL'])
+  end
+
+  api.register(:db) do
+    conn = pool.checkout
+    [conn, -> { pool.checkin(conn) }]
+  end
+
+  api.get '/users', depends: [:db] do |input, req, task, db:|
+    result = db.exec("SELECT * FROM users")
+    [{ users: result.to_a }, 200]
+  end
+end
+```
+
+## Transactions
+
+### With Block Dependencies
+
+```ruby
+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.post '/transfer', depends: [:transaction] do |input, req, task, transaction:|
+  transaction.exec("UPDATE accounts SET balance = balance - $1 WHERE id = $2", 
+    [input[:body][:amount], input[:body][:from_id]])
+  transaction.exec("UPDATE accounts SET balance = balance + $1 WHERE id = $2", 
+    [input[:body][:amount], input[:body][:to_id]])
+  
+  [{ success: true }, 200]
+end
+```
+
+## Async Queries
+
+With async-compatible drivers, run queries concurrently:
+
+```ruby
+api.get '/dashboard/:id' do |input, req, task|
+  id = input[:path]['id']
+
+  user = task.async { DB[:users].where(id: id).first }
+  posts = task.async { DB[:posts].where(user_id: id).limit(10).all }
+  stats = task.async { DB[:stats].where(user_id: id).first }
+
+  [{
+    user: user.wait,
+    posts: posts.wait,
+    stats: stats.wait
+  }, 200]
+end
+```
+
+## Migrations
+
+FunApi doesn't include migrations. Use your database library's migration tool:
+
+- Sequel: `sequel -m migrations/ postgres://...`
+- ActiveRecord: `rake db:migrate`
+- Raw SQL files with a migration runner