takagi 0.1.0 → 1.1.0

data/examples/cloud_gateway_app.rb

@@ -0,0 +1,217 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Cloud Gateway Application (Modular Pattern)
+#
+# This example demonstrates the modular pattern using Takagi::Controller
+# and Takagi::Application for high-scale cloud/gateway servers.
+#
+# Use case: Cloud server handling thousands of devices with uneven load
+#
+# Run with: ruby examples/cloud_gateway_app.rb
+
+require_relative '../lib/takagi'
+
+# High-throughput telemetry ingestion
+class TelemetryController < Takagi::Controller
+  configure do
+    mount '/telemetry'
+    profile :high_throughput  # 8 processes × 4 threads = 32 workers
+  end
+
+  # POST /telemetry/data - High-volume sensor data ingestion
+  post '/data' do |request|
+    data = request.data
+
+    # Simulate data processing
+    {
+      received: true,
+      device_id: data['device_id'],
+      timestamp: Time.now.to_i,
+      points: data['points']&.length || 0
+    }
+  end
+
+  # GET /telemetry/stats - Telemetry statistics
+  get '/stats' do
+    {
+      total_devices: 1523,
+      points_per_second: 15_234,
+      avg_latency_ms: 12
+    }
+  end
+end
+
+# Observable streams for real-time monitoring
+class ObservableController < Takagi::Controller
+  configure do
+    mount '/observe'
+    profile :long_lived  # 2 processes × 8 threads = 16 workers (for long connections)
+  end
+
+  # OBSERVE /observe/devices/:id - Stream device data
+  observable '/devices/:id' do |_request, params|
+    device_id = params[:id]
+
+    {
+      device_id: device_id,
+      status: 'online',
+      last_seen: Time.now.to_i,
+      temperature: rand(20..30),
+      battery: rand(50..100)
+    }
+  end
+
+  # OBSERVE /observe/alerts - Stream system alerts
+  observable '/alerts' do
+    {
+      timestamp: Time.now.to_i,
+      severity: %w[info warning error].sample,
+      message: 'Sample alert message'
+    }
+  end
+end
+
+# Device management API
+class DeviceManagementController < Takagi::Controller
+  configure do
+    mount '/devices'
+    profile :low_traffic  # 1 process × 2 threads = 2 workers
+  end
+
+  # GET /devices - List all devices
+  get '/' do
+    {
+      devices: [
+        { id: 'device-001', name: 'Sensor 1', status: 'online' },
+        { id: 'device-002', name: 'Sensor 2', status: 'online' },
+        { id: 'device-003', name: 'Sensor 3', status: 'offline' }
+      ],
+      total: 3
+    }
+  end
+
+  # GET /devices/:id - Get device details
+  get '/:id' do |_request, params|
+    {
+      id: params[:id],
+      name: "Device #{params[:id]}",
+      status: 'online',
+      firmware: '2.1.0',
+      last_seen: Time.now.to_i
+    }
+  end
+
+  # POST /devices/:id/command - Send command to device
+  post '/:id/command' do |request, params|
+    command = request.data
+
+    {
+      device_id: params[:id],
+      command: command['action'],
+      status: 'queued'
+    }
+  end
+end
+
+# Configuration API
+class ConfigController < Takagi::Controller
+  configure do
+    mount '/config'
+    profile :low_traffic
+  end
+
+  # GET /config/global - Get global configuration
+  get '/global' do
+    {
+      telemetry_interval: 60,
+      max_devices: 10_000,
+      retention_days: 30
+    }
+  end
+
+  # PUT /config/global - Update global configuration
+  put '/global' do |request|
+    config = request.data
+
+    {
+      updated: true,
+      config: config
+    }
+  end
+end
+
+# Firmware update API (large payloads)
+class FirmwareController < Takagi::Controller
+  configure do
+    mount '/firmware'
+    profile :large_payloads  # 2 processes × 2 threads, 10MB buffer
+  end
+
+  # GET /firmware/latest - Get latest firmware info
+  get '/latest' do
+    {
+      version: '2.1.0',
+      size_bytes: 5_242_880,
+      checksum: 'abc123...',
+      release_date: '2025-01-15'
+    }
+  end
+
+  # POST /firmware/upload - Upload new firmware
+  post '/upload' do |request|
+    # Simulate firmware processing
+    {
+      uploaded: true,
+      size: request.payload&.bytesize || 0,
+      checksum: 'processing...'
+    }
+  end
+end
+
+# Main application
+class CloudGatewayApp < Takagi::Application
+  configure do
+    load_controllers(
+      TelemetryController,
+      ObservableController,
+      DeviceManagementController,
+      ConfigController,
+      FirmwareController
+    )
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  puts "Starting Cloud Gateway App..."
+  puts "CoAP server running on port 5683"
+  puts ""
+  puts "Architecture:"
+  puts "  /telemetry  - High throughput (32 workers) - Sensor data ingestion"
+  puts "  /observe    - Long-lived (16 workers)    - Real-time streams"
+  puts "  /devices    - Low traffic (2 workers)    - Device management"
+  puts "  /config     - Low traffic (2 workers)    - Configuration API"
+  puts "  /firmware   - Large payloads (4 workers) - Firmware updates"
+  puts ""
+  puts "Example commands:"
+  puts "  # High-volume telemetry"
+  puts "  coap-client -m post coap://localhost/telemetry/data -e '{\"device_id\":\"dev-001\",\"points\":[{\"temp\":25}]}'"
+  puts ""
+  puts "  # Observable streams"
+  puts "  coap-client -m get -s 10 coap://localhost/observe/devices/dev-001"
+  puts "  coap-client -m get -s 10 coap://localhost/observe/alerts"
+  puts ""
+  puts "  # Device management"
+  puts "  coap-client -m get coap://localhost/devices"
+  puts "  coap-client -m get coap://localhost/devices/dev-001"
+  puts "  coap-client -m post coap://localhost/devices/dev-001/command -e '{\"action\":\"reboot\"}'"
+  puts ""
+  puts "  # Configuration"
+  puts "  coap-client -m get coap://localhost/config/global"
+  puts ""
+  puts "  # Firmware"
+  puts "  coap-client -m get coap://localhost/firmware/latest"
+  puts ""
+
+  CloudGatewayApp.run!(port: 5683, protocols: [:udp, :tcp])
+end

data/examples/nested_api_app.rb

@@ -0,0 +1,258 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Nested API Application
+#
+# This example demonstrates nested controller mounting for
+# organizing complex APIs with versioning and resource hierarchy.
+#
+# Use case: RESTful API with nested resources
+#
+# Run with: ruby examples/nested_api_app.rb
+
+require_relative '../lib/takagi'
+
+# --- API v1 ---
+
+# Sensors controller under API v1
+class V1SensorsController < Takagi::Controller
+  configure do
+    mount '/sensors'
+    profile :high_throughput
+  end
+
+  # GET /api/v1/sensors
+  get '/' do
+    {
+      sensors: [
+        { id: 'temp-001', type: 'temperature', location: 'room-1' },
+        { id: 'hum-001', type: 'humidity', location: 'room-1' }
+      ]
+    }
+  end
+
+  # GET /api/v1/sensors/:id
+  get '/:id' do |_request, params|
+    {
+      id: params[:id],
+      type: 'temperature',
+      value: rand(20..30),
+      unit: 'celsius',
+      timestamp: Time.now.to_i
+    }
+  end
+
+  # POST /api/v1/sensors/:id/readings
+  post '/:id/readings' do |request, params|
+    data = request.data
+
+    {
+      sensor_id: params[:id],
+      reading_id: SecureRandom.uuid,
+      value: data['value'],
+      stored: true
+    }
+  end
+end
+
+# Users controller under API v1
+class V1UsersController < Takagi::Controller
+  configure do
+    mount '/users'
+    profile :low_traffic
+  end
+
+  # GET /api/v1/users
+  get '/' do
+    {
+      users: [
+        { id: 'user-001', name: 'Alice', role: 'admin' },
+        { id: 'user-002', name: 'Bob', role: 'user' }
+      ]
+    }
+  end
+
+  # GET /api/v1/users/:id
+  get '/:id' do |_request, params|
+    {
+      id: params[:id],
+      name: "User #{params[:id]}",
+      role: 'user',
+      created_at: Time.now.to_i
+    }
+  end
+end
+
+# API v1 parent controller
+class ApiV1Controller < Takagi::Controller
+  configure do
+    mount '/api/v1'
+
+    # Nest resource controllers
+    nest V1SensorsController, V1UsersController
+  end
+
+  # GET /api/v1 - API info
+  get '/' do
+    {
+      version: '1.0',
+      endpoints: {
+        sensors: '/api/v1/sensors',
+        users: '/api/v1/users'
+      },
+      status: 'stable'
+    }
+  end
+end
+
+# --- API v2 (Improved version) ---
+
+class V2SensorsController < Takagi::Controller
+  configure do
+    mount '/sensors'
+    profile :high_throughput
+  end
+
+  # GET /api/v2/sensors
+  get '/' do
+    {
+      sensors: [
+        {
+          id: 'temp-001',
+          type: 'temperature',
+          location: { building: 'A', floor: 1, room: 'room-1' },
+          metadata: { calibrated: true, accuracy: 0.1 }
+        }
+      ],
+      pagination: { page: 1, total: 1 }
+    }
+  end
+
+  # GET /api/v2/sensors/:id
+  get '/:id' do |_request, params|
+    {
+      id: params[:id],
+      type: 'temperature',
+      readings: {
+        current: rand(20..30),
+        min_24h: 18,
+        max_24h: 32,
+        avg_24h: 25
+      },
+      unit: 'celsius',
+      timestamp: Time.now.to_i
+    }
+  end
+end
+
+class ApiV2Controller < Takagi::Controller
+  configure do
+    mount '/api/v2'
+    nest V2SensorsController
+  end
+
+  # GET /api/v2 - API info
+  get '/' do
+    {
+      version: '2.0',
+      endpoints: {
+        sensors: '/api/v2/sensors'
+      },
+      status: 'beta',
+      improvements: [
+        'Enhanced sensor metadata',
+        'Improved response structure',
+        'Better pagination'
+      ]
+    }
+  end
+end
+
+# --- Admin API (separate hierarchy) ---
+
+class AdminDevicesController < Takagi::Controller
+  configure do
+    mount '/devices'
+  end
+
+  # DELETE /admin/devices/:id
+  delete '/:id' do |_request, params|
+    {
+      deleted: true,
+      device_id: params[:id],
+      timestamp: Time.now.to_i
+    }
+  end
+end
+
+class AdminController < Takagi::Controller
+  configure do
+    mount '/admin'
+    profile :low_traffic
+    nest AdminDevicesController
+  end
+
+  # GET /admin/stats
+  get '/stats' do
+    {
+      total_devices: 523,
+      active_users: 42,
+      api_requests_24h: 15_234,
+      storage_used_gb: 125
+    }
+  end
+end
+
+# Main application
+class NestedApiApp < Takagi::Application
+  configure do
+    load_controllers(
+      ApiV1Controller,
+      ApiV2Controller,
+      AdminController
+    )
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  puts "Starting Nested API App..."
+  puts "CoAP server running on port 5683"
+  puts ""
+  puts "API Structure:"
+  puts "  /api/v1"
+  puts "    /api/v1/sensors"
+  puts "      GET  /api/v1/sensors"
+  puts "      GET  /api/v1/sensors/:id"
+  puts "      POST /api/v1/sensors/:id/readings"
+  puts "    /api/v1/users"
+  puts "      GET  /api/v1/users"
+  puts "      GET  /api/v1/users/:id"
+  puts ""
+  puts "  /api/v2 (Beta)"
+  puts "    /api/v2/sensors"
+  puts "      GET  /api/v2/sensors"
+  puts "      GET  /api/v2/sensors/:id"
+  puts ""
+  puts "  /admin"
+  puts "    GET    /admin/stats"
+  puts "    /admin/devices"
+  puts "      DELETE /admin/devices/:id"
+  puts ""
+  puts "Example commands:"
+  puts "  # API v1"
+  puts "  coap-client -m get coap://localhost/api/v1"
+  puts "  coap-client -m get coap://localhost/api/v1/sensors"
+  puts "  coap-client -m get coap://localhost/api/v1/sensors/temp-001"
+  puts "  coap-client -m post coap://localhost/api/v1/sensors/temp-001/readings -e '{\"value\":25.5}'"
+  puts ""
+  puts "  # API v2 (Beta)"
+  puts "  coap-client -m get coap://localhost/api/v2"
+  puts "  coap-client -m get coap://localhost/api/v2/sensors/temp-001"
+  puts ""
+  puts "  # Admin"
+  puts "  coap-client -m get coap://localhost/admin/stats"
+  puts "  coap-client -m delete coap://localhost/admin/devices/old-device-001"
+  puts ""
+
+  NestedApiApp.run!(port: 5683, protocols: [:udp])
+end

data/examples/simple_device_app.rb

@@ -0,0 +1,71 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Simple Device Application (IoT Device Pattern)
+#
+# This example demonstrates the simple pattern using Takagi::Base
+# for constrained IoT devices with minimal resources.
+#
+# Use case: Raspberry Pi, ESP32, or edge device with 1-10 endpoints
+#
+# Run with: ruby examples/simple_device_app.rb
+
+require_relative '../lib/takagi'
+
+# Simple device application using global router pattern
+class DeviceApp < Takagi::Base
+  # GET /sensor - Read sensor data
+  get '/sensor' do
+    {
+      temperature: 25.5,
+      humidity: 60,
+      timestamp: Time.now.to_i
+    }
+  end
+
+  # POST /command - Execute device command
+  post '/command' do |request|
+    command = request.data
+
+    case command['action']
+    when 'reboot'
+      { status: 'rebooting' }
+    when 'update'
+      { status: 'updating' }
+    else
+      { status: 'unknown_command' }
+    end
+  end
+
+  # OBSERVE /status - Stream device status (CoAP Observe)
+  observable '/status' do
+    {
+      online: true,
+      uptime: Process.clock_gettime(Process::CLOCK_MONOTONIC).to_i,
+      memory_used: `ps -o rss= -p #{Process.pid}`.to_i
+    }
+  end
+
+  # GET /config - Device configuration
+  get '/config' do
+    {
+      device_id: 'device-001',
+      firmware_version: '1.0.0',
+      update_interval: 60
+    }
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  puts "Starting Simple Device App..."
+  puts "CoAP server running on port 5683"
+  puts ""
+  puts "Try these commands:"
+  puts "  coap-client -m get coap://localhost/sensor"
+  puts "  coap-client -m post coap://localhost/command -e '{\"action\":\"reboot\"}'"
+  puts "  coap-client -m get -s 10 coap://localhost/status  # Observe for 10s"
+  puts "  coap-client -m get coap://localhost/config"
+  puts ""
+
+  DeviceApp.run!(port: 5683, protocols: [:udp])
+end

data/examples/takagi.yml

@@ -0,0 +1,138 @@
+# Takagi Configuration Example
+# Place this file as takagi.yml in your project root
+
+# ============================================
+# Server Settings
+# ============================================
+port: 5683
+bind_address: "0.0.0.0"  # Bind to all interfaces (default)
+                          # Use "127.0.0.1" for local-only
+                          # Use specific IP for single interface
+server_name: "Takagi CoAP Server"
+
+# Number of processes (for multi-process mode)
+processes: 1
+
+# Number of threads per process
+threads: 4
+
+# Supported protocols
+protocols:
+  - udp
+  - tcp
+
+# ============================================
+# Logger Configuration
+# ============================================
+logger:
+  level: info  # debug, info, warn, error
+  output: stdout
+
+# ============================================
+# Observability
+# ============================================
+observability:
+  backends:
+    - memory
+    # - prometheus  # Uncomment for Prometheus metrics
+    # - statsd      # Uncomment for StatsD metrics
+
+# ============================================
+# EventBus Configuration
+# ============================================
+event_bus:
+  # Worker pool size for async message delivery
+  # Higher values = more concurrent message processing
+  # Lower values = less memory/CPU usage
+  ractors: 10
+
+  # Current state cache (LRUCache)
+  # Stores latest value per address for fast lookups
+  state_cache_size: 1000   # Max number of addresses
+  state_cache_ttl: 3600    # Seconds (1 hour)
+
+  # Observer cleanup settings
+  # Removes stale CoAP observers periodically
+  cleanup_interval: 60     # Seconds between cleanup runs
+  max_observer_age: 600    # Seconds (10 minutes)
+
+  # ==========================================
+  # Message Buffering (for reliability)
+  # ==========================================
+  # Enable to buffer messages for late subscribers and reconnections
+  # Recommended for unreliable networks (WiFi, mesh, mobile)
+
+  message_buffering_enabled: false  # Set to true to enable
+
+  # When enabled:
+  message_buffer_max_messages: 100  # Messages per address
+  message_buffer_ttl: 300           # Seconds (5 minutes)
+
+# ============================================
+# Router Configuration
+# ============================================
+router:
+  # Default Content-Format when not specified
+  # 0  = text/plain
+  # 40 = application/link-format
+  # 41 = application/xml
+  # 42 = application/octet-stream
+  # 50 = application/json (default)
+  # 60 = application/cbor
+  default_content_format: 50
+
+# ============================================
+# Middleware Configuration
+# ============================================
+middleware:
+  # Enable/disable middleware globally
+  enabled: true
+
+  # Middleware stack (executed in order)
+  # Middleware wraps request/response processing
+  # First middleware in list runs first (outermost layer)
+  stack:
+    # Simple middleware (no options)
+    - Logging
+
+    # Middleware with options
+    - name: Caching
+      options:
+        ttl: 300  # Cache TTL in seconds
+
+    # Available built-in middleware:
+    # - Debugging: Debug logging for requests/responses
+    # - Logging: Request/response logging
+    # - Caching: Simple in-memory cache
+    # - RateLimiting: Rate limit requests (options: max_requests, window)
+    # - Metrics: Collect metrics (options: backend)
+    # - Authentication: Token-based auth (options: tokens, realm)
+
+    # Example: Rate Limiting
+    # - name: RateLimiting
+    #   options:
+    #     max_requests: 100
+    #     window: 60  # seconds
+
+    # Example: Authentication
+    # - name: Authentication
+    #   options:
+    #     tokens:
+    #       - "secret-token-1"
+    #       - "secret-token-2"
+    #     realm: "CoAP API"
+
+    # Example: Custom middleware (full class name)
+    # - name: MyApp::CustomMiddleware
+    #   options:
+    #     custom_option: value
+
+# ============================================
+# Custom Application Settings
+# ============================================
+# Add any custom settings here - accessible via Takagi.config[:key]
+custom:
+  # Example custom settings
+  app_name: "My IoT Application"
+  max_devices: 100
+  device_timeout: 30