funapi 0.1.0

data/docs-site/app.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "funapi"
+require "funapi/templates"
+require "funapi/server/falcon"
+require "kramdown"
+require "kramdown-parser-gfm"
+require "rouge"
+
+class DocsRenderer
+  def initialize(content_dir:)
+    @content_dir = Pathname.new(content_dir)
+    @cache = {}
+  end
+
+  def render(path)
+    file_path = @content_dir.join("#{path}.md")
+    raise FunApi::HTTPException.new(status_code: 404, detail: "Page not found") unless file_path.exist?
+
+    @cache[path] ||= begin
+      content = file_path.read
+      frontmatter, body = parse_frontmatter(content)
+      html = Kramdown::Document.new(
+        body,
+        input: "GFM",
+        syntax_highlighter: "rouge",
+        syntax_highlighter_opts: {default_lang: "ruby"}
+      ).to_html
+
+      {frontmatter: frontmatter, html: html}
+    end
+  end
+
+  def navigation
+    @navigation ||= build_navigation
+  end
+
+  private
+
+  def parse_frontmatter(content)
+    if content.start_with?("---")
+      parts = content.split("---", 3)
+      frontmatter = parse_yaml(parts[1])
+      body = parts[2]
+      [frontmatter, body]
+    else
+      [{}, content]
+    end
+  end
+
+  def parse_yaml(yaml_str)
+    result = {}
+    yaml_str.each_line do |line|
+      result[::Regexp.last_match(1).to_sym] = ::Regexp.last_match(2).strip if line =~ /^(\w+):\s*(.+)$/
+    end
+    result
+  end
+
+  def build_navigation
+    [
+      {
+        title: "Getting Started",
+        items: [
+          {path: "getting-started/at-glance", title: "At Glance"},
+          {path: "getting-started/quick-start", title: "Quick Start"},
+          {path: "getting-started/key-concepts", title: "Key Concepts"}
+        ]
+      },
+      {
+        title: "Essential",
+        items: [
+          {path: "essential/routing", title: "Routing"},
+          {path: "essential/handler", title: "Handler"},
+          {path: "essential/validation", title: "Validation"},
+          {path: "essential/openapi", title: "OpenAPI"},
+          {path: "essential/lifecycle", title: "Lifecycle"},
+          {path: "essential/middleware", title: "Middleware"}
+        ]
+      },
+      {
+        title: "Patterns",
+        items: [
+          {path: "patterns/async-operations", title: "Async Operations"},
+          {path: "patterns/dependencies", title: "Dependencies"},
+          {path: "patterns/background-tasks", title: "Background Tasks"},
+          {path: "patterns/templates", title: "Templates"},
+          {path: "patterns/error-handling", title: "Error Handling"},
+          {path: "patterns/response-schema", title: "Response Schema"},
+          {path: "patterns/database", title: "Database"},
+          {path: "patterns/testing", title: "Testing"},
+          {path: "patterns/deployment", title: "Deployment"}
+        ]
+      }
+    ]
+  end
+end
+
+# Get the docs-site directory path relative to this script
+docs_site_dir = __dir__
+docs = DocsRenderer.new(content_dir: File.join(docs_site_dir, "content"))
+templates = FunApi::Templates.new(
+  directory: File.join(docs_site_dir, "templates"),
+  layout: "layouts/docs.html.erb"
+)
+
+app = FunApi::App.new(
+  title: "FunApi Documentation",
+  version: "0.1.0",
+  description: "Documentation for the FunApi framework"
+) do |api|
+  api.use Rack::Static, urls: ["/css"], root: File.join(docs_site_dir, "public")
+  api.add_request_logger
+
+  api.get "/" do |_input, _req, _task|
+    page = docs.render("index")
+    templates.response(
+      "page.html.erb",
+      title: page[:frontmatter][:title] || "FunApi",
+      content: page[:html],
+      nav: docs.navigation,
+      current_path: "index"
+    )
+  end
+
+  api.get "/docs/:section/:page" do |input, _req, _task|
+    path = "#{input[:path]["section"]}/#{input[:path]["page"]}"
+    page = docs.render(path)
+    templates.response(
+      "page.html.erb",
+      title: page[:frontmatter][:title] || "FunApi",
+      content: page[:html],
+      nav: docs.navigation,
+      current_path: path
+    )
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 3000) if __FILE__ == $0

data/docs-site/content/essential/handler.md

@@ -0,0 +1,156 @@
+---
+title: Handler
+---
+
+# Handler
+
+The handler is the function that processes a request and returns a response.
+
+## Handler Signature
+
+Every handler receives three positional arguments:
+
+```ruby
+api.get '/path' do |input, req, task|
+  [response_data, status_code]
+end
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `input` | Hash | Request data (path, query, body) |
+| `req` | Rack::Request | Full Rack request object |
+| `task` | Async::Task | Current async task for concurrency |
+
+## The Input Hash
+
+The `input` hash normalizes all request data:
+
+```ruby
+api.post '/users/:id' do |input, req, task|
+  input[:path]   # Path parameters: { 'id' => '123' }
+  input[:query]  # Query params: { search: 'ruby' }
+  input[:body]   # Parsed JSON body: { name: 'Alice' }
+end
+```
+
+### Accessing Path Parameters
+
+```ruby
+api.get '/posts/:post_id/comments/:id' do |input, req, task|
+  post_id = input[:path]['post_id']
+  comment_id = input[:path]['id']
+  # ...
+end
+```
+
+### Accessing Query Parameters
+
+```ruby
+# GET /search?q=ruby&page=2
+api.get '/search' do |input, req, task|
+  query = input[:query][:q]
+  page = input[:query][:page]
+  # ...
+end
+```
+
+### Accessing Request Body
+
+```ruby
+api.post '/users' do |input, req, task|
+  name = input[:body][:name]
+  email = input[:body][:email]
+  # ...
+end
+```
+
+## The Rack Request
+
+The `req` object is a standard `Rack::Request`:
+
+```ruby
+api.get '/info' do |input, req, task|
+  {
+    method: req.request_method,
+    path: req.path_info,
+    host: req.host,
+    content_type: req.content_type,
+    user_agent: req.user_agent,
+    ip: req.ip
+  }
+end
+```
+
+### Accessing Headers
+
+```ruby
+api.get '/auth' do |input, req, task|
+  auth_header = req.get_header('HTTP_AUTHORIZATION')
+  # or
+  auth_header = req.env['HTTP_AUTHORIZATION']
+end
+```
+
+## The Async Task
+
+The `task` parameter enables concurrent operations:
+
+```ruby
+api.get '/dashboard' do |input, req, task|
+  # Run operations concurrently
+  user = task.async { UserService.find(id) }
+  posts = task.async { PostService.recent }
+  
+  [{
+    user: user.wait,
+    posts: posts.wait
+  }, 200]
+end
+```
+
+See [Async Operations](/docs/patterns/async-operations) for more.
+
+## Return Value
+
+Handlers must return `[data, status_code]`:
+
+```ruby
+# JSON response
+[{ message: 'Hello' }, 200]
+
+# Array response
+[users, 200]
+
+# Empty response
+[{}, 204]
+
+# Error response
+[{ error: 'Not found' }, 404]
+```
+
+### Returning HTML
+
+Return a `TemplateResponse` for HTML:
+
+```ruby
+api.get '/' do |input, req, task|
+  templates.response('home.html.erb', title: 'Home')
+end
+```
+
+See [Templates](/docs/patterns/templates) for more.
+
+## Keyword Arguments (Dependencies)
+
+When using dependency injection, dependencies come as keyword arguments:
+
+```ruby
+api.get '/users', depends: [:db, :logger] do |input, req, task, db:, logger:|
+  logger.info("Fetching users")
+  users = db.query("SELECT * FROM users")
+  [{ users: users }, 200]
+end
+```
+
+See [Dependencies](/docs/patterns/dependencies) for more.

data/docs-site/content/essential/lifecycle.md

@@ -0,0 +1,161 @@
+---
+title: Lifecycle
+---
+
+# Lifecycle
+
+Lifecycle hooks let you run code when your application starts up or shuts down.
+
+## Startup Hooks
+
+Run code before the server accepts requests:
+
+```ruby
+app = FunApi::App.new do |api|
+  api.on_startup do
+    puts "Connecting to database..."
+    DB.connect
+  end
+
+  api.on_startup do
+    puts "Warming cache..."
+    Cache.warm
+  end
+end
+```
+
+### Use Cases
+
+- Database connection pool initialization
+- Cache warming
+- Loading configuration
+- Starting background workers
+- Metrics/logging initialization
+
+## Shutdown Hooks
+
+Run code when the server stops:
+
+```ruby
+app = FunApi::App.new do |api|
+  api.on_shutdown do
+    puts "Closing database connections..."
+    DB.disconnect
+  end
+
+  api.on_shutdown do
+    puts "Flushing metrics..."
+    Metrics.flush
+  end
+end
+```
+
+### Use Cases
+
+- Graceful database disconnection
+- Flushing buffers/queues
+- Stopping background workers
+- Cleanup of temporary files
+
+## Multiple Hooks
+
+You can register multiple hooks of each type. They run in registration order:
+
+```ruby
+app = FunApi::App.new do |api|
+  api.on_startup do
+    puts "1. First startup hook"
+  end
+
+  api.on_startup do
+    puts "2. Second startup hook"
+  end
+
+  api.on_shutdown do
+    puts "1. First shutdown hook"
+  end
+
+  api.on_shutdown do
+    puts "2. Second shutdown hook"
+  end
+end
+```
+
+## Error Handling
+
+### Startup Errors
+
+If a startup hook raises an error, the server won't start:
+
+```ruby
+api.on_startup do
+  raise "Database unavailable"
+  # Server fails to start
+end
+```
+
+### Shutdown Errors
+
+Shutdown hook errors are logged but don't stop other hooks:
+
+```ruby
+api.on_shutdown do
+  raise "Cleanup failed"
+  # Error logged, but next hook still runs
+end
+
+api.on_shutdown do
+  puts "This still runs"
+end
+```
+
+## Complete Example
+
+```ruby
+require 'funapi'
+require 'funapi/server/falcon'
+
+app = FunApi::App.new(title: "My API") do |api|
+  api.on_startup do
+    puts "Starting up..."
+    $db = Database.connect(ENV['DATABASE_URL'])
+    $cache = Cache.new
+    $cache.warm
+    puts "Ready!"
+  end
+
+  api.on_shutdown do
+    puts "Shutting down..."
+    $cache.flush
+    $db.disconnect
+    puts "Goodbye!"
+  end
+
+  api.get '/health' do |input, req, task|
+    [{ status: 'ok', db: $db.connected? }, 200]
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 3000)
+```
+
+## With Dependencies
+
+Combine lifecycle hooks with dependency injection:
+
+```ruby
+app = FunApi::App.new do |api|
+  api.on_startup do
+    db_pool = ConnectionPool.new(size: 10) { Database.connect }
+    api.register(:db) { db_pool.checkout }
+  end
+
+  api.on_shutdown do
+    api.resolve(:db).close_all
+  end
+
+  api.get '/users', depends: [:db] do |input, req, task, db:|
+    [{ users: db.query("SELECT * FROM users") }, 200]
+  end
+end
+```

data/docs-site/content/essential/middleware.md

@@ -0,0 +1,201 @@
+---
+title: Middleware
+---
+
+# Middleware
+
+Middleware wraps your application, processing requests before handlers and responses after.
+
+## Built-in Middleware
+
+FunApi provides convenience methods for common middleware:
+
+### CORS
+
+Handle Cross-Origin Resource Sharing:
+
+```ruby
+api.add_cors(
+  allow_origins: ['http://localhost:3000', 'https://myapp.com'],
+  allow_methods: ['GET', 'POST', 'PUT', 'DELETE'],
+  allow_headers: ['Content-Type', 'Authorization'],
+  expose_headers: ['X-Request-Id'],
+  max_age: 600,
+  allow_credentials: true
+)
+```
+
+For development, allow all origins:
+
+```ruby
+api.add_cors(allow_origins: ['*'])
+```
+
+### Request Logger
+
+Log incoming requests:
+
+```ruby
+api.add_request_logger
+```
+
+With custom logger:
+
+```ruby
+api.add_request_logger(
+  logger: Logger.new('logs/requests.log'),
+  level: :info
+)
+```
+
+### Trusted Host
+
+Validate the Host header (security):
+
+```ruby
+api.add_trusted_host(
+  allowed_hosts: ['myapp.com', 'api.myapp.com']
+)
+```
+
+With regex patterns:
+
+```ruby
+api.add_trusted_host(
+  allowed_hosts: ['localhost', /\.myapp\.com$/]
+)
+```
+
+### Gzip Compression
+
+Compress JSON responses:
+
+```ruby
+api.add_gzip
+```
+
+## Using Rack Middleware
+
+Any Rack middleware works with FunApi:
+
+```ruby
+app = FunApi::App.new do |api|
+  api.use Rack::Session::Cookie, secret: ENV['SESSION_SECRET']
+  api.use Rack::Attack
+  api.use Rack::ETag
+end
+```
+
+## Custom Middleware
+
+Create middleware following the Rack pattern:
+
+```ruby
+class TimingMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    start = Time.now
+    status, headers, body = @app.call(env)
+    duration = Time.now - start
+    
+    headers['X-Response-Time'] = "#{(duration * 1000).round}ms"
+    [status, headers, body]
+  end
+end
+
+app = FunApi::App.new do |api|
+  api.use TimingMiddleware
+end
+```
+
+### With Options
+
+```ruby
+class AuthMiddleware
+  def initialize(app, secret:, exclude: [])
+    @app = app
+    @secret = secret
+    @exclude = exclude
+  end
+
+  def call(env)
+    path = env['PATH_INFO']
+    
+    if @exclude.include?(path)
+      return @app.call(env)
+    end
+
+    token = env['HTTP_AUTHORIZATION']&.delete_prefix('Bearer ')
+    
+    unless valid_token?(token)
+      return [401, {'content-type' => 'application/json'}, ['{"error":"Unauthorized"}']]
+    end
+
+    @app.call(env)
+  end
+
+  private
+
+  def valid_token?(token)
+    # Verify token with @secret
+  end
+end
+
+app = FunApi::App.new do |api|
+  api.use AuthMiddleware, 
+    secret: ENV['JWT_SECRET'],
+    exclude: ['/health', '/docs', '/openapi.json']
+end
+```
+
+## Middleware Order
+
+Middleware runs in the order registered (first in, first out):
+
+```ruby
+app = FunApi::App.new do |api|
+  api.use LoggingMiddleware    # 1. Runs first
+  api.use AuthMiddleware       # 2. Runs second
+  api.use TimingMiddleware     # 3. Runs third
+  
+  # Then your routes handle the request
+  # Response goes back through in reverse order
+end
+```
+
+Request flow:
+```
+Request → Logging → Auth → Timing → Handler
+Response ← Logging ← Auth ← Timing ← Handler
+```
+
+## Complete Example
+
+```ruby
+require 'funapi'
+require 'funapi/server/falcon'
+
+app = FunApi::App.new(title: "My API") do |api|
+  # Security
+  api.add_trusted_host(allowed_hosts: ['localhost', 'myapi.com'])
+  api.add_cors(allow_origins: ['https://myapp.com'])
+  
+  # Logging
+  api.add_request_logger
+  
+  # Compression
+  api.add_gzip
+  
+  # Custom
+  api.use Rack::Session::Cookie, secret: 'secret'
+  
+  api.get '/hello' do |input, req, task|
+    [{ message: 'Hello!' }, 200]
+  end
+end
+
+FunApi::Server::Falcon.start(app, port: 3000)
+```