funapi 0.1.0

data/examples/background_tasks_demo.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+require_relative "../lib/funapi"
+require_relative "../lib/funapi/server/falcon"
+require "logger"
+
+FAKE_EMAILS = []
+FAKE_LOGS = []
+FAKE_WEBHOOKS = []
+
+def send_welcome_email(email, name)
+  sleep 0.05
+  message = "Welcome email sent to #{email} for #{name}"
+  FAKE_EMAILS << message
+  puts "  📧 #{message}"
+end
+
+def log_signup_event(user_id, email)
+  sleep 0.02
+  log_entry = "[#{Time.now}] User #{user_id} signed up: #{email}"
+  FAKE_LOGS << log_entry
+  puts "  📝 #{log_entry}"
+end
+
+def notify_admin(user_count)
+  sleep 0.03
+  notification = "Admin notified: Total users now #{user_count}"
+  FAKE_WEBHOOKS << notification
+  puts "  🔔 #{notification}"
+end
+
+def send_webhook(url, data)
+  sleep 0.04
+  webhook = "Webhook sent to #{url}: #{data}"
+  FAKE_WEBHOOKS << webhook
+  puts "  🌐 #{webhook}"
+end
+
+USERS_DB = []
+
+UserSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+  optional(:notifications).filled(:bool)
+end
+
+app = FunApi::App.new(
+  title: "Background Tasks Demo API",
+  version: "1.0.0",
+  description: "Demonstrating background tasks in FunApi"
+) do |api|
+  api.register(:logger) do
+    logger = Logger.new($stdout)
+    logger.level = Logger::INFO
+    logger
+  end
+
+  api.get "/" do |_input, _req, _task|
+    [{
+      message: "Background Tasks Demo API",
+      endpoints: {
+        home: "GET /",
+        signup: "POST /signup (body: {name, email, notifications?})",
+        users: "GET /users",
+        send_batch: "POST /send-batch-emails",
+        stats: "GET /stats"
+      },
+      info: "Background tasks run after response is sent but before dependencies close"
+    }, 200]
+  end
+
+  api.post "/signup", body: UserSchema do |input, _req, _task, background:|
+    user_data = input[:body]
+
+    user_id = USERS_DB.size + 1
+    user = user_data.merge(id: user_id, created_at: Time.now.to_s)
+    USERS_DB << user
+
+    puts "\n🚀 Handler: Creating user #{user[:name]}"
+
+    background.add_task(method(:send_welcome_email), user[:email], user[:name])
+    background.add_task(method(:log_signup_event), user_id, user[:email])
+
+    background.add_task(method(:notify_admin), USERS_DB.size) if user[:notifications]
+
+    background.add_task(
+      method(:send_webhook),
+      "https://api.example.com/hooks/user-created",
+      user.to_json
+    )
+
+    puts "✅ Handler: Response ready (user created)\n"
+
+    [{user: user, message: "Signup successful! Check your email."}, 201]
+  end
+
+  api.get "/users" do |_input, _req, _task|
+    [{users: USERS_DB, count: USERS_DB.size}, 200]
+  end
+
+  api.post "/send-batch-emails", depends: [:logger] do |_input, _req, _task, logger:, background:|
+    user_count = USERS_DB.size
+
+    return [{error: "No users to email"}, 400] if user_count.zero?
+
+    puts "\n🚀 Handler: Queueing #{user_count} email tasks"
+
+    USERS_DB.each do |user|
+      background.add_task(lambda { |email, name|
+        logger.info("Sending batch email to #{email}")
+        send_welcome_email(email, name)
+      }, user[:email], user[:name])
+    end
+
+    puts "✅ Handler: Response ready (#{user_count} emails queued)\n"
+
+    [{message: "#{user_count} emails queued for sending", count: user_count}, 200]
+  end
+
+  api.get "/stats" do |_input, _req, _task|
+    [{
+      users: USERS_DB.size,
+      emails_sent: FAKE_EMAILS.size,
+      logs_created: FAKE_LOGS.size,
+      webhooks_sent: FAKE_WEBHOOKS.size
+    }, 200]
+  end
+end
+
+puts "\n🚀 FunApi Background Tasks Demo"
+puts "=" * 60
+puts "\nServer starting on http://localhost:3000"
+puts "\n📚 API Docs: http://localhost:3000/docs"
+puts "\n✨ Try these examples:\n"
+puts "\n# Check available endpoints"
+puts "curl http://localhost:3000/"
+puts "\n# Sign up a user (watch background tasks execute)"
+puts "curl -X POST http://localhost:3000/signup \\"
+puts "  -H 'Content-Type: application/json' \\"
+puts "  -d '{\"name\":\"Alice\",\"email\":\"alice@example.com\",\"notifications\":true}'"
+puts "\n# Sign up another user"
+puts "curl -X POST http://localhost:3000/signup \\"
+puts "  -H 'Content-Type: application/json' \\"
+puts "  -d '{\"name\":\"Bob\",\"email\":\"bob@example.com\",\"notifications\":false}'"
+puts "\n# Send batch emails to all users"
+puts "curl -X POST http://localhost:3000/send-batch-emails"
+puts "\n# Check stats"
+puts "curl http://localhost:3000/stats"
+puts "\n# List all users"
+puts "curl http://localhost:3000/users"
+puts "\n" + ("=" * 60)
+puts "\n💡 Notice how:"
+puts "  - Response is sent IMMEDIATELY"
+puts "  - Background tasks run AFTER handler completes"
+puts "  - Background tasks run BEFORE dependencies close"
+puts "  - Multiple tasks execute in order"
+puts "  - Tasks can access dependencies (logger, db, etc.)\n\n"
+
+FunApi::Server::Falcon.start(app, port: 3000)

data/examples/demo_middleware.rb

@@ -0,0 +1,55 @@
+require_relative "lib/funapi"
+require_relative "lib/funapi/server/falcon"
+
+class SimpleMiddleware
+  def initialize(app)
+    @app = app
+  end
+
+  def call(env)
+    puts "[SimpleMiddleware] Before request"
+    status, headers, body = @app.call(env)
+    puts "[SimpleMiddleware] After request - Status: #{status}"
+    headers["X-Simple-Middleware"] = "true"
+    [status, headers, body]
+  end
+end
+
+class LoggingMiddleware
+  def initialize(app, prefix = "LOG")
+    @app = app
+    @prefix = prefix
+  end
+
+  def call(env)
+    request = Rack::Request.new(env)
+    puts "[#{@prefix}] #{request.request_method} #{request.path}"
+    @app.call(env)
+  end
+end
+
+app = FunApi::App.new(
+  title: "Middleware Test API",
+  version: "1.0.0"
+) do |api|
+  api.use SimpleMiddleware
+  api.use LoggingMiddleware, "ACCESS"
+
+  api.get "/test" do |_input, _req, _task|
+    [{message: "Middleware test successful!"}, 200]
+  end
+
+  api.get "/hello/:name" do |input, _req, _task|
+    name = input[:path]["name"]
+    [{greeting: "Hello, #{name}!"}, 200]
+  end
+end
+
+puts "Starting FunApi with middleware..."
+puts "Test endpoints:"
+puts "  http://localhost:3000/test"
+puts "  http://localhost:3000/hello/World"
+puts "  http://localhost:3000/docs"
+puts ""
+
+FunApi::Server::Falcon.start(app, port: 3000)

data/examples/demo_openapi.rb

@@ -0,0 +1,63 @@
+require_relative "lib/funapi"
+require_relative "lib/funapi/server/falcon"
+
+UserCreateSchema = FunApi::Schema.define do
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+  required(:password).filled(:string)
+  optional(:age).filled(:integer)
+end
+
+UserOutputSchema = FunApi::Schema.define do
+  required(:id).filled(:integer)
+  required(:name).filled(:string)
+  required(:email).filled(:string)
+  optional(:age).filled(:integer)
+end
+
+QuerySchema = FunApi::Schema.define do
+  optional(:limit).filled(:integer)
+  optional(:offset).filled(:integer)
+end
+
+app = FunApi::App.new(
+  title: "User Management API",
+  version: "1.0.0",
+  description: "A simple user management API demonstrating OpenAPI generation"
+) do |api|
+  api.get "/users", query: QuerySchema, response_schema: [UserOutputSchema] do |_input, _req, _task|
+    users = [
+      {id: 1, name: "John Doe", email: "john@example.com", age: 30},
+      {id: 2, name: "Jane Smith", email: "jane@example.com"}
+    ]
+    [users, 200]
+  end
+
+  api.get "/users/:id", response_schema: UserOutputSchema do |input, _req, _task|
+    user_id = input[:path]["id"]
+    user = {id: user_id.to_i, name: "John Doe", email: "john@example.com", age: 30}
+    [user, 200]
+  end
+
+  api.post "/users", body: UserCreateSchema, response_schema: UserOutputSchema do |input, _req, _task|
+    user = input[:body].merge(id: rand(1000))
+    [user, 201]
+  end
+
+  api.put "/users/:id", body: UserCreateSchema, response_schema: UserOutputSchema do |input, _req, _task|
+    user_id = input[:path]["id"]
+    user = input[:body].merge(id: user_id.to_i)
+    [user, 200]
+  end
+
+  api.delete "/users/:id" do |_input, _req, _task|
+    [{message: "User deleted"}, 200]
+  end
+end
+
+puts "Starting server on http://localhost:9292"
+puts "OpenAPI spec: http://localhost:9292/openapi.json"
+puts "Swagger UI: http://localhost:9292/docs"
+puts
+
+FunApi::Server::Falcon.start(app, port: 9292)

data/examples/dependency_block_demo.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+# standard:disable Style/GlobalVars
+
+require_relative '../lib/funapi'
+require_relative '../lib/funapi/server/falcon'
+
+class DatabaseConnection
+  attr_reader :id, :queries_run
+
+  def initialize(id)
+    @id = id
+    @open = true
+    @queries_run = []
+    puts "  ✅ Database connection #{id} OPENED"
+  end
+
+  def query(sql)
+    raise "Connection #{@id} is closed!" unless @open
+
+    @queries_run << sql
+    puts "  📊 Running query on connection #{@id}: #{sql}"
+    { result: "data for #{sql}" }
+  end
+
+  def close
+    return unless @open
+
+    @open = false
+    puts "  ❌ Database connection #{@id} CLOSED (ran #{@queries_run.length} queries)"
+  end
+
+  def open?
+    @open
+  end
+end
+
+$connection_counter = 0
+$all_connections = []
+
+app = FunApi::App.new(
+  title: 'Block-Based Dependency Demo',
+  version: '1.0.0'
+) do |api|
+  api.register(:db) do |provide|
+    $connection_counter += 1
+    conn = DatabaseConnection.new($connection_counter)
+    $all_connections << conn
+
+    provide.call(conn)
+  ensure
+    conn&.close
+  end
+
+  api.get '/' do |_input, _req, _task|
+    [{
+      message: 'Block-Based Dependency Demo',
+      info: 'Dependencies use Ruby blocks with ensure for cleanup',
+      pattern: 'register(:key) { |provide| resource = setup(); provide.call(resource); ensure cleanup() }',
+      endpoints: {
+        users: 'GET /users (opens db, runs query, closes db)',
+        error: 'GET /error (opens db, errors, still closes db)',
+        multiple: 'GET /multiple (opens db once, uses multiple times)'
+      },
+      stats: 'GET /stats'
+    }, 200]
+  end
+
+  api.get '/users',
+          depends: [:db] do |_input, _req, _task, db:|
+    puts "\n🔹 Handler executing..."
+    users = db.query('SELECT * FROM users')
+
+    puts '🔹 Handler returning response...'
+    [users, 200]
+  end
+
+  api.get '/error',
+          depends: [:db] do |_input, _req, _task, db:|
+    puts "\n🔹 Handler executing..."
+    db.query('SELECT * FROM users')
+
+    puts '🔹 Handler raising error...'
+    raise FunApi::HTTPException.new(status_code: 500, detail: 'Something went wrong!')
+  end
+
+  api.get '/multiple',
+          depends: {
+            db1: :db,
+            db2: :db
+          } do |_input, _req, _task, db1:, db2:|
+    puts "\n🔹 Handler executing with multiple deps..."
+    puts "  db1 object_id: #{db1.object_id}"
+    puts "  db2 object_id: #{db2.object_id}"
+    puts "  Same instance? #{db1.equal?(db2)}"
+
+    db1.query('SELECT * FROM users')
+    db2.query('SELECT * FROM posts')
+
+    [{
+      note: 'Both db1 and db2 are the same connection (request-scoped cache)',
+      db1_id: db1.id,
+      db2_id: db2.id,
+      same_instance: db1.equal?(db2)
+    }, 200]
+  end
+
+  api.get '/stats' do |_input, _req, _task|
+    open_count = $all_connections.count(&:open?)
+    closed_count = $all_connections.count { |c| !c.open? }
+
+    [{
+      total_connections_created: $connection_counter,
+      currently_open: open_count,
+      closed: closed_count,
+      all_connections: $all_connections.map do |c|
+        {
+          id: c.id,
+          open: c.open?,
+          queries_run: c.queries_run.length
+        }
+      end
+    }, 200]
+  end
+end
+
+puts "\n🚀 FunApi Block-Based Dependency Demo"
+puts '=' * 50
+puts "\nThis demo shows the new Ruby-idiomatic dependency pattern:"
+puts "\n  api.register(:key) do |provide|"
+puts '    resource = setup_resource()'
+puts '    provide.call(resource)  # Yield resource to framework'
+puts '  ensure'
+puts '    cleanup_resource()      # Always runs, even on errors'
+puts '  end'
+puts "\nServer starting on http://localhost:3002"
+puts "\n✨ Try these commands:\n"
+puts '# Open connection, run query, close connection'
+puts 'curl http://localhost:3002/users'
+puts "\n# Open connection, error, still close connection"
+puts 'curl http://localhost:3002/error'
+puts "\n# Open connection once, use multiple times (cached)"
+puts 'curl http://localhost:3002/multiple'
+puts "\n# Check connection stats"
+puts 'curl http://localhost:3002/stats'
+puts "\n" + ('=' * 50) + "\n\n"
+
+FunApi::Server::Falcon.start(app, port: 3002)
+
+# standard:enable Style/GlobalVars

data/examples/dependency_cleanup_demo.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+# standard:disable Style/GlobalVars
+
+require_relative '../lib/funapi'
+require_relative '../lib/funapi/server/falcon'
+
+class DatabaseConnection
+  attr_reader :id, :queries_run
+
+  def initialize(id)
+    @id = id
+    @open = true
+    @queries_run = []
+    puts "  ✅ Database connection #{id} OPENED"
+  end
+
+  def query(sql)
+    raise "Connection #{@id} is closed!" unless @open
+
+    @queries_run << sql
+    puts "  📊 Running query on connection #{@id}: #{sql}"
+    { result: "data for #{sql}" }
+  end
+
+  def close
+    return unless @open
+
+    @open = false
+    puts "  ❌ Database connection #{@id} CLOSED (ran #{@queries_run.length} queries)"
+  end
+
+  def open?
+    @open
+  end
+end
+
+$connection_counter = 0
+$all_connections = []
+
+app = FunApi::App.new(
+  title: 'Dependency Cleanup Demo',
+  version: '1.0.0'
+) do |api|
+  api.register(:db) do
+    $connection_counter += 1
+    conn = DatabaseConnection.new($connection_counter)
+    $all_connections << conn
+
+    cleanup = -> { conn.close }
+
+    [conn, cleanup]
+  end
+
+  api.get '/' do |_input, _req, _task|
+    [{
+      message: 'Dependency Cleanup Demo',
+      endpoints: {
+        users: 'GET /users (opens db, runs query, closes db)',
+        error: 'GET /error (opens db, errors, still closes db)',
+        multiple: 'GET /multiple (opens db once, uses multiple times)'
+      },
+      stats: 'GET /stats'
+    }, 200]
+  end
+
+  api.get '/users',
+          depends: [:db] do |_input, _req, _task, db:|
+    puts "\n🔹 Handler executing..."
+    users = db.query('SELECT * FROM users')
+
+    puts '🔹 Handler returning response...'
+    [users, 200]
+  end
+
+  api.get '/error',
+          depends: [:db] do |_input, _req, _task, db:|
+    puts "\n🔹 Handler executing..."
+    db.query('SELECT * FROM users')
+
+    puts '🔹 Handler raising error...'
+    raise FunApi::HTTPException.new(status_code: 500, detail: 'Something went wrong!')
+  end
+
+  api.get '/multiple',
+          depends: {
+            db1: :db,
+            db2: :db
+          } do |_input, _req, _task, db1:, db2:|
+    puts "\n🔹 Handler executing with multiple deps..."
+    puts "  db1 object_id: #{db1.object_id}"
+    puts "  db2 object_id: #{db2.object_id}"
+    puts "  Same instance? #{db1.equal?(db2)}"
+
+    db1.query('SELECT * FROM users')
+    db2.query('SELECT * FROM posts')
+
+    [{
+      note: 'Both db1 and db2 are the same connection (request-scoped cache)',
+      db1_id: db1.id,
+      db2_id: db2.id,
+      same_instance: db1.equal?(db2)
+    }, 200]
+  end
+
+  api.get '/stats' do |_input, _req, _task|
+    open_count = $all_connections.count(&:open?)
+    closed_count = $all_connections.count { |c| !c.open? }
+
+    [{
+      total_connections_created: $connection_counter,
+      currently_open: open_count,
+      closed: closed_count,
+      all_connections: $all_connections.map do |c|
+        {
+          id: c.id,
+          open: c.open?,
+          queries_run: c.queries_run.length
+        }
+      end
+    }, 200]
+  end
+end
+
+puts "\n🚀 FunApi Dependency Cleanup Demo"
+puts '=' * 50
+puts "\nThis demo shows how dependency cleanup works:"
+puts '- Dependencies can return [resource, cleanup_proc]'
+puts '- Cleanup runs AFTER response is sent (in ensure block)'
+puts '- Cleanup runs even if handler raises an error'
+puts '- Multiple references to same dependency = single instance'
+puts "\nServer starting on http://localhost:3001"
+puts "\n✨ Try these commands:\n"
+puts '# Open connection, run query, close connection'
+puts 'curl http://localhost:3001/users'
+puts "\n# Open connection, error, still close connection"
+puts 'curl http://localhost:3001/error'
+puts "\n# Open connection once, use multiple times (cached)"
+puts 'curl http://localhost:3001/multiple'
+puts "\n# Check connection stats"
+puts 'curl http://localhost:3001/stats'
+puts "\n" + ('=' * 50) + "\n\n"
+
+FunApi::Server::Falcon.start(app, port: 3001)
+
+# standard:enable Style/GlobalVars