aris 1.4.2 → 1.5.0

data/docs/plugins/RATE_LIMITER.md

@@ -0,0 +1,368 @@
+# Rate Limiter Plugin
+
+Throttle requests to prevent abuse, brute force attacks, and API overuse.
+
+## Installation
+
+```ruby
+# lib/aris.rb already includes this
+require_relative 'aris/plugins/rate_limiter'
+```
+
+## How It Works
+
+Tracks request counts per key (API key, IP address, user ID) within a time window. Returns **429 Too Many Requests** when limit exceeded.
+
+**Default:** 100 requests per 60 seconds per key.
+
+---
+
+## Basic Usage
+
+### Simple API Rate Limiting
+
+```ruby
+Aris.routes({
+  "api.example.com": {
+    use: [:rate_limit],  # Default: 100 requests/60s
+    "/data": { get: { to: DataHandler } }
+  }
+})
+```
+
+Requests include rate limit headers:
+```
+X-RateLimit-Limit: 100
+X-RateLimit-Remaining: 47
+```
+
+When limit exceeded:
+```
+HTTP/1.1 429 Too Many Requests
+Retry-After: 60
+Rate limit exceeded. Try again later.
+```
+
+---
+
+## Configuration
+
+Rate limiting keys **default to API key or host**:
+
+```ruby
+# Uses HTTP_X_API_KEY header if present, else falls back to HTTP_HOST
+request.headers['HTTP_X_API_KEY'] || request.host
+```
+
+**For custom configuration**, you need to build a custom instance. The plugin is currently not configurable via symbol registration.
+
+---
+
+## Advanced Usage
+
+### Custom Instance (Not Yet Supported)
+
+The current implementation is fixed at 100 requests per 60 seconds. For production use, you'll want to enhance it:
+
+```ruby
+# Future enhancement - custom limits
+rate_limit = Aris::Plugins::RateLimiter.build(
+  limit: 1000,
+  window: 3600,  # 1 hour
+  key_extractor: ->(request) {
+    # Rate limit by authenticated user
+    request.instance_variable_get(:@current_user)
+  }
+)
+
+Aris.routes({
+  "api.example.com": {
+    use: [rate_limit],
+    "/data": { get: { to: DataHandler } }
+  }
+})
+```
+
+---
+
+## Combining with Authentication
+
+Always rate limit **after** authentication to prevent brute force:
+
+```ruby
+bearer_auth = Aris::Plugins::BearerAuth.build(
+  validator: ->(token) { ApiKey.valid?(token) }
+)
+
+Aris.routes({
+  "api.example.com": {
+    use: [bearer_auth, :rate_limit],  # Auth first, then rate limit
+    "/data": { get: { to: DataHandler } }
+  }
+})
+```
+
+**Why this order?**
+- Invalid auth fails fast (no rate limit check needed)
+- Valid requests get rate limited per authenticated user
+
+---
+
+## Production Setup
+
+### Use Redis Instead of Memory
+
+The current implementation uses in-memory storage. **For production, use Redis:**
+
+```ruby
+# lib/aris/plugins/rate_limiter_redis.rb
+require 'redis'
+
+class RateLimiterRedis
+  REDIS = Redis.new(url: ENV['REDIS_URL'])
+  
+  def initialize(limit: 100, window: 60)
+    @limit = limit
+    @window = window
+  end
+  
+  def call(request, response)
+    key = rate_limit_key(request)
+    redis_key = "rate_limit:#{key}"
+    
+    count = REDIS.multi do |r|
+      r.incr(redis_key)
+      r.expire(redis_key, @window)
+    end.first
+    
+    response.headers['X-RateLimit-Limit'] = @limit.to_s
+    response.headers['X-RateLimit-Remaining'] = [@limit - count, 0].max.to_s
+    
+    if count > @limit
+      response.status = 429
+      response.headers['Retry-After'] = @window.to_s
+      response.body = ['Rate limit exceeded. Try again later.']
+      return response
+    end
+    
+    nil
+  end
+  
+  private
+  
+  def rate_limit_key(request)
+    request.headers['HTTP_X_API_KEY'] || request.headers['REMOTE_ADDR']
+  end
+end
+
+# Use it
+redis_limiter = RateLimiterRedis.new(limit: 1000, window: 3600)
+
+Aris.routes({
+  "api.example.com": {
+    use: [redis_limiter],
+    "/data": { get: { to: DataHandler } }
+  }
+})
+```
+
+---
+
+## Common Patterns
+
+### Different Limits for Different Endpoints
+
+```ruby
+strict_limit = RateLimiterRedis.new(limit: 10, window: 60)
+normal_limit = RateLimiterRedis.new(limit: 100, window: 60)
+
+Aris.routes({
+  "api.example.com": {
+    use: [normal_limit],  # Default for all routes
+    
+    "/expensive": {
+      use: [strict_limit],  # Override with stricter limit
+      post: { to: ExpensiveHandler }
+    }
+  }
+})
+```
+
+### Per-User Rate Limiting
+
+```ruby
+user_limiter = RateLimiterRedis.new(
+  limit: 1000,
+  window: 3600,
+  key_extractor: ->(request) {
+    # Rate limit by authenticated user ID
+    user = request.instance_variable_get(:@current_user)
+    "user:#{user.id}"
+  }
+)
+```
+
+### Bypass Rate Limiting for Premium Users
+
+```ruby
+class SmartRateLimiter
+  def call(request, response)
+    user = request.instance_variable_get(:@current_user)
+    
+    # Premium users skip rate limiting
+    return nil if user&.premium?
+    
+    # Regular rate limiting logic
+    # ...
+  end
+end
+```
+
+### Per-IP Brute Force Protection
+
+```ruby
+login_limiter = RateLimiterRedis.new(
+  limit: 5,
+  window: 300,  # 5 attempts per 5 minutes
+  key_extractor: ->(request) {
+    request.headers['REMOTE_ADDR']
+  }
+)
+
+Aris.routes({
+  "example.com": {
+    "/login": {
+      use: [login_limiter],  # Rate limit login attempts
+      post: { to: LoginHandler }
+    }
+  }
+})
+```
+
+---
+
+## Testing
+
+```ruby
+class RateLimiterTest < Minitest::Test
+  def test_requests_under_limit_pass
+    Aris.routes({
+      "api.example.com": {
+        use: [:rate_limit],
+        "/data": { get: { to: DataHandler } }
+      }
+    })
+    
+    app = Aris::Adapters::RackApp.new
+    Aris::Plugins::RateLimiter.reset!  # Clear state
+    
+    env = build_env('/data', api_key: 'test-key')
+    
+    # First 100 requests succeed
+    100.times do
+      status, _, _ = app.call(env)
+      assert_equal 200, status
+    end
+    
+    # 101st fails
+    status, headers, _ = app.call(env)
+    assert_equal 429, status
+    assert_equal '60', headers['Retry-After']
+  end
+end
+```
+
+---
+
+## Production Tips
+
+### 1. Monitor Rate Limit Hits
+
+```ruby
+class MonitoredRateLimiter < RateLimiterRedis
+  def call(request, response)
+    result = super
+    
+    if result == response && response.status == 429
+      # Log rate limit hit
+      key = rate_limit_key(request)
+      Rails.logger.warn("Rate limit exceeded: #{key}")
+      Metrics.increment('api.rate_limit.exceeded', tags: ["key:#{key}"])
+    end
+    
+    result
+  end
+end
+```
+
+### 2. Graceful Degradation
+
+```ruby
+def call(request, response)
+  begin
+    # Rate limiting logic
+  rescue Redis::ConnectionError => e
+    # If Redis is down, allow requests through
+    Rails.logger.error("Rate limiter Redis error: #{e.message}")
+    return nil
+  end
+end
+```
+
+### 3. Different Limits by Tier
+
+```ruby
+LIMITS = {
+  'free' => { limit: 100, window: 3600 },
+  'pro' => { limit: 1000, window: 3600 },
+  'enterprise' => { limit: 10000, window: 3600 }
+}
+
+class TieredRateLimiter
+  def call(request, response)
+    user = request.instance_variable_get(:@current_user)
+    config = LIMITS[user.tier]
+    
+    # Apply tier-specific limit
+    # ...
+  end
+end
+```
+
+---
+
+## Security Notes
+
+**✅ Use for:**
+- API endpoints
+- Login/authentication endpoints
+- Password reset endpoints
+- Resource-intensive operations
+- Public endpoints
+
+**⚠️ Considerations:**
+- Rate limit by user/token (not just IP) to prevent shared IP issues
+- Use Redis for distributed systems (in-memory won't work across servers)
+- Set appropriate limits (too strict = bad UX, too loose = ineffective)
+- Monitor for legitimate users hitting limits
+
+**❌ Don't rely solely on:**
+- Rate limiting alone for security (defense in depth)
+- IP-based limiting in cloud environments (shared IPs)
+
+---
+
+## Current Limitations
+
+The built-in rate limiter:
+- ✅ Works for single-server deployments
+- ✅ Thread-safe with mutex
+- ❌ Uses in-memory storage (won't persist across restarts)
+- ❌ Won't work across multiple servers
+- ❌ Fixed at 100 requests per 60 seconds
+
+**For production:** Implement Redis-backed rate limiting as shown above.
+
+---
+
+Need help? Check out the [full plugin development guide](../docs/plugin-development.md).

data/docs/plugins/REQUEST_ID.md

@@ -0,0 +1,369 @@
+# Request ID Plugin
+
+Generates unique request IDs for distributed tracing and log correlation. Essential for debugging in production environments.
+
+## Installation
+
+```ruby
+require 'aris/plugins/request_id'
+```
+
+## Basic Usage
+
+```ruby
+request_id = Aris::Plugins::RequestId.build
+
+Aris.routes({
+  "api.example.com": {
+    use: [request_id],  # Apply to all routes
+    "/users": { get: { to: UsersHandler } }
+  }
+})
+```
+
+## Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `header_name` | String | `'X-Request-ID'` | HTTP header name for request ID |
+| `generator` | Proc | `-> { SecureRandom.uuid }` | Custom ID generator function |
+
+## How It Works
+
+1. **Check for existing ID**: If request has `X-Request-ID` header (from proxy/load balancer), use it
+2. **Generate new ID**: If none provided, generate UUID
+3. **Store on request**: Handlers can access via `@request_id` instance variable
+4. **Return in response**: Set `X-Request-ID` header in response
+
+## Examples
+
+### Default Configuration
+
+```ruby
+request_id = Aris::Plugins::RequestId.build
+
+# Request without ID:
+# Response: X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
+
+# Request with ID:
+# Request: X-Request-ID: existing-id-123
+# Response: X-Request-ID: existing-id-123 (preserved)
+```
+
+### Custom Header Name
+
+```ruby
+request_id = Aris::Plugins::RequestId.build(
+  header_name: 'X-Trace-ID'
+)
+
+# Response will have X-Trace-ID instead of X-Request-ID
+```
+
+### Custom Generator
+
+```ruby
+# Sequential IDs
+counter = 0
+request_id = Aris::Plugins::RequestId.build(
+  generator: -> { "REQ-#{counter += 1}" }
+)
+
+# Timestamp-based IDs
+request_id = Aris::Plugins::RequestId.build(
+  generator: -> { "#{Time.now.to_i}-#{SecureRandom.hex(4)}" }
+)
+
+# Short IDs
+request_id = Aris::Plugins::RequestId.build(
+  generator: -> { SecureRandom.hex(8) }  # 16 characters
+)
+```
+
+### Accessing Request ID in Handlers
+
+```ruby
+class UsersHandler
+  def self.call(request, params)
+    request_id = request.instance_variable_get(:@request_id)
+    
+    # Use in logging
+    logger.info("Processing user request", request_id: request_id)
+    
+    # Return in response
+    {
+      users: User.all,
+      request_id: request_id
+    }
+  end
+end
+```
+
+### With Logging Plugin
+
+```ruby
+request_id = Aris::Plugins::RequestId.build
+logger = Aris::Plugins::RequestLogger.build(format: :json)
+
+Aris.routes({
+  "api.example.com": {
+    use: [request_id, logger],  # Request ID first
+    "/users": { get: { to: UsersHandler } }
+  }
+})
+
+# Logs will include request_id for correlation
+```
+
+## Production Tips
+
+### 1. Plugin Order (Critical)
+
+Place **first** in plugin chain:
+
+```ruby
+Aris.routes({
+  "api.example.com": {
+    use: [
+      request_id,       # ← FIRST - generate ID
+      bearer_auth,      # Use request_id in auth logs
+      json_parser,      # Use request_id in parser logs
+      request_logger    # Log request_id
+    ]
+  }
+})
+```
+
+### 2. Structured Logging
+
+Combine with logging plugin for correlation:
+
+```ruby
+class CustomLogger
+  def self.call(request, response)
+    request_id = request.instance_variable_get(:@request_id)
+    
+    logger.info({
+      request_id: request_id,
+      method: request.method,
+      path: request.path,
+      timestamp: Time.now.iso8601
+    }.to_json)
+    
+    nil
+  end
+end
+```
+
+### 3. Load Balancer Integration
+
+Preserve IDs from upstream:
+
+```ruby
+# AWS ALB sends X-Amzn-Trace-Id
+request_id = Aris::Plugins::RequestId.build(
+  header_name: 'X-Amzn-Trace-Id'
+)
+
+# Or check multiple headers
+class SmartRequestId
+  def self.call(request, response)
+    request_id = request.headers['HTTP_X_AMZN_TRACE_ID'] ||
+                 request.headers['HTTP_X_REQUEST_ID'] ||
+                 SecureRandom.uuid
+    
+    request.instance_variable_set(:@request_id, request_id)
+    response.headers['X-Request-ID'] = request_id
+    
+    nil
+  end
+end
+```
+
+### 4. Error Tracking
+
+Include request ID in error responses:
+
+```ruby
+class ErrorHandler
+  def self.call(request, exception)
+    request_id = request.instance_variable_get(:@request_id)
+    
+    [500, { 'content-type' => 'application/json' }, [
+      {
+        error: 'Internal Server Error',
+        request_id: request_id,
+        message: exception.message
+      }.to_json
+    ]]
+  end
+end
+
+Aris.default(error: ErrorHandler)
+```
+
+### 5. Distributed Tracing
+
+Propagate to downstream services:
+
+```ruby
+class ServiceClient
+  def self.call_api(request, endpoint)
+    request_id = request.instance_variable_get(:@request_id)
+    
+    # Pass to downstream service
+    HTTParty.get(
+      "https://api.example.com#{endpoint}",
+      headers: { 'X-Request-ID' => request_id }
+    )
+  end
+end
+```
+
+### 6. Database Query Tagging
+
+Tag queries with request ID:
+
+```ruby
+class UsersHandler
+  def self.call(request, params)
+    request_id = request.instance_variable_get(:@request_id)
+    
+    # Tag ActiveRecord queries
+    ActiveRecord::Base.connection.execute(
+      "SET application_name = 'request_#{request_id}'"
+    )
+    
+    User.all
+  end
+end
+```
+
+### 7. APM Integration
+
+Send to monitoring services:
+
+```ruby
+class APMHandler
+  def self.call(request, params)
+    request_id = request.instance_variable_get(:@request_id)
+    
+    # NewRelic
+    NewRelic::Agent.add_custom_attributes(request_id: request_id)
+    
+    # Datadog
+    Datadog::Tracing.active_span&.set_tag('request.id', request_id)
+    
+    # Your logic here
+  end
+end
+```
+
+## Common Patterns
+
+### Multi-Service Architecture
+
+```ruby
+# Service A (Frontend API)
+request_id = Aris::Plugins::RequestId.build
+
+# Service B (Backend API)
+# Receives X-Request-ID from Service A
+request_id = Aris::Plugins::RequestId.build  # Preserves existing ID
+
+# All logs across services have same request_id for correlation
+```
+
+### Request ID in Sidekiq Jobs
+
+```ruby
+class ProcessOrderJob
+  def perform(order_id, request_id)
+    logger.tagged(request_id) do
+      logger.info "Processing order #{order_id}"
+      # Process order
+    end
+  end
+end
+
+class OrdersHandler
+  def self.call(request, params)
+    request_id = request.instance_variable_get(:@request_id)
+    
+    # Enqueue with request_id
+    ProcessOrderJob.perform_async(params[:id], request_id)
+    
+    { status: 'processing', request_id: request_id }
+  end
+end
+```
+
+### Client Response Headers
+
+```ruby
+# Clients can use request_id for support tickets
+# Response: X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
+
+# User: "Error with request ID: 550e8400-..."
+# Support: grep logs for 550e8400-... → full request trace
+```
+
+## ID Format Options
+
+**UUID (default):**
+```ruby
+# 550e8400-e29b-41d4-a716-446655440000
+generator: -> { SecureRandom.uuid }
+```
+
+**Short hex:**
+```ruby
+# a3f2bc9e
+generator: -> { SecureRandom.hex(4) }
+```
+
+**Timestamp + random:**
+```ruby
+# 1634567890-a3f2bc9e
+generator: -> { "#{Time.now.to_i}-#{SecureRandom.hex(4)}" }
+```
+
+**Sequential (testing only):**
+```ruby
+# REQ-1, REQ-2, REQ-3...
+counter = 0
+generator: -> { "REQ-#{counter += 1}" }
+```
+
+## Benchmarks
+
+**Performance impact:**
+- UUID generation: ~0.01ms
+- Header setting: ~0.001ms
+- Total overhead: <0.02ms per request
+
+Negligible impact, essential value.
+
+## Notes
+
+- Thread-safe (UUID generation is thread-safe)
+- Preserves IDs from load balancers/proxies
+- Available to all downstream handlers
+- Always returned in response headers
+- Compatible with AWS ALB, Nginx, HAProxy trace IDs
+
+## Troubleshooting
+
+**Request ID not showing up?**
+- Check plugin is in `use:` array
+- Verify plugin runs before logging/handlers
+- Confirm response headers are visible
+
+**Different IDs in logs vs response?**
+- Ensure request_id plugin runs first
+- Check no other plugin overwrites header
+
+**Load balancer ID not preserved?**
+- Check header name matches (`X-Request-ID` vs `X-Amzn-Trace-Id`)
+- Verify load balancer is forwarding header
+```