842 lines
17 KiB
Markdown
842 lines
17 KiB
Markdown
---
|
|
name: rack-middleware
|
|
description: Rack middleware development, configuration, and integration patterns. Use when working with middleware stacks or creating custom middleware.
|
|
---
|
|
|
|
# Rack Middleware Skill
|
|
|
|
## Tier 1: Quick Reference - Middleware Basics
|
|
|
|
### Middleware Structure
|
|
|
|
```ruby
|
|
class MyMiddleware
|
|
def initialize(app, options = {})
|
|
@app = app
|
|
@options = options
|
|
end
|
|
|
|
def call(env)
|
|
# Before request
|
|
# Modify env if needed
|
|
|
|
# Call next middleware
|
|
status, headers, body = @app.call(env)
|
|
|
|
# After request
|
|
# Modify response if needed
|
|
|
|
[status, headers, body]
|
|
end
|
|
end
|
|
|
|
# Usage
|
|
use MyMiddleware, option: 'value'
|
|
```
|
|
|
|
### Common Middleware
|
|
|
|
```ruby
|
|
# Session management
|
|
use Rack::Session::Cookie, secret: ENV['SESSION_SECRET']
|
|
|
|
# Security
|
|
use Rack::Protection
|
|
|
|
# Compression
|
|
use Rack::Deflater
|
|
|
|
# Logging
|
|
use Rack::CommonLogger
|
|
|
|
# Static files
|
|
use Rack::Static, urls: ['/css', '/js'], root: 'public'
|
|
```
|
|
|
|
### Middleware Ordering
|
|
|
|
```ruby
|
|
# config.ru - Correct order
|
|
use Rack::Deflater # 1. Compression
|
|
use Rack::Static # 2. Static files
|
|
use Rack::CommonLogger # 3. Logging
|
|
use Rack::Session::Cookie # 4. Sessions
|
|
use Rack::Protection # 5. Security
|
|
use CustomAuth # 6. Authentication
|
|
run Application # 7. Application
|
|
```
|
|
|
|
### Request/Response Access
|
|
|
|
```ruby
|
|
class SimpleMiddleware
|
|
def initialize(app)
|
|
@app = app
|
|
end
|
|
|
|
def call(env)
|
|
# Access request via env hash
|
|
method = env['REQUEST_METHOD']
|
|
path = env['PATH_INFO']
|
|
query = env['QUERY_STRING']
|
|
|
|
# Or use Rack::Request
|
|
request = Rack::Request.new(env)
|
|
params = request.params
|
|
|
|
# Process request
|
|
status, headers, body = @app.call(env)
|
|
|
|
# Modify response
|
|
headers['X-Custom-Header'] = 'value'
|
|
|
|
[status, headers, body]
|
|
end
|
|
end
|
|
```
|
|
|
|
---
|
|
|
|
## Tier 2: Detailed Instructions - Advanced Middleware
|
|
|
|
### Custom Middleware Development
|
|
|
|
**Request Logging Middleware:**
|
|
```ruby
|
|
require 'logger'
|
|
|
|
class RequestLogger
|
|
def initialize(app, options = {})
|
|
@app = app
|
|
@logger = options[:logger] || Logger.new(STDOUT)
|
|
@skip_paths = options[:skip_paths] || []
|
|
end
|
|
|
|
def call(env)
|
|
return @app.call(env) if skip_logging?(env)
|
|
|
|
start_time = Time.now
|
|
request = Rack::Request.new(env)
|
|
|
|
log_request_start(request)
|
|
|
|
status, headers, body = @app.call(env)
|
|
|
|
duration = Time.now - start_time
|
|
log_request_end(request, status, duration)
|
|
|
|
[status, headers, body]
|
|
rescue StandardError => e
|
|
log_error(request, e)
|
|
raise
|
|
end
|
|
|
|
private
|
|
|
|
def skip_logging?(env)
|
|
path = env['PATH_INFO']
|
|
@skip_paths.any? { |skip| path.start_with?(skip) }
|
|
end
|
|
|
|
def log_request_start(request)
|
|
@logger.info({
|
|
event: 'request.start',
|
|
method: request.request_method,
|
|
path: request.path,
|
|
ip: request.ip,
|
|
user_agent: request.user_agent
|
|
}.to_json)
|
|
end
|
|
|
|
def log_request_end(request, status, duration)
|
|
@logger.info({
|
|
event: 'request.end',
|
|
method: request.request_method,
|
|
path: request.path,
|
|
status: status,
|
|
duration: duration.round(3)
|
|
}.to_json)
|
|
end
|
|
|
|
def log_error(request, error)
|
|
@logger.error({
|
|
event: 'request.error',
|
|
method: request.request_method,
|
|
path: request.path,
|
|
error: error.class.name,
|
|
message: error.message,
|
|
backtrace: error.backtrace[0..5]
|
|
}.to_json)
|
|
end
|
|
end
|
|
|
|
# Usage
|
|
use RequestLogger, skip_paths: ['/health', '/metrics']
|
|
```
|
|
|
|
**Authentication Middleware:**
|
|
```ruby
|
|
class TokenAuthentication
|
|
def initialize(app, options = {})
|
|
@app = app
|
|
@token_header = options[:header] || 'HTTP_AUTHORIZATION'
|
|
@skip_paths = options[:skip_paths] || []
|
|
@realm = options[:realm] || 'Application'
|
|
end
|
|
|
|
def call(env)
|
|
return @app.call(env) if skip_authentication?(env)
|
|
|
|
token = extract_token(env)
|
|
|
|
if valid_token?(token)
|
|
user = find_user_by_token(token)
|
|
env['current_user'] = user
|
|
@app.call(env)
|
|
else
|
|
unauthorized_response
|
|
end
|
|
end
|
|
|
|
private
|
|
|
|
def skip_authentication?(env)
|
|
path = env['PATH_INFO']
|
|
method = env['REQUEST_METHOD']
|
|
|
|
# Skip for public paths
|
|
@skip_paths.any? { |skip| path.start_with?(skip) } ||
|
|
# Skip for OPTIONS (CORS preflight)
|
|
method == 'OPTIONS'
|
|
end
|
|
|
|
def extract_token(env)
|
|
auth_header = env[@token_header]
|
|
return nil unless auth_header
|
|
|
|
# Support "Bearer TOKEN" format
|
|
if auth_header.start_with?('Bearer ')
|
|
auth_header.split(' ', 2).last
|
|
else
|
|
auth_header
|
|
end
|
|
end
|
|
|
|
def valid_token?(token)
|
|
return false unless token
|
|
|
|
# Implement your token validation logic
|
|
# This is a placeholder
|
|
token.length >= 32
|
|
end
|
|
|
|
def find_user_by_token(token)
|
|
# Implement your user lookup logic
|
|
# This is a placeholder
|
|
{ id: 1, email: 'user@example.com' }
|
|
end
|
|
|
|
def unauthorized_response
|
|
[
|
|
401,
|
|
{
|
|
'Content-Type' => 'application/json',
|
|
'WWW-Authenticate' => "Bearer realm=\"#{@realm}\""
|
|
},
|
|
['{"error": "Unauthorized"}']
|
|
]
|
|
end
|
|
end
|
|
|
|
# Usage
|
|
use TokenAuthentication,
|
|
skip_paths: ['/login', '/register', '/public']
|
|
```
|
|
|
|
**Caching Middleware:**
|
|
```ruby
|
|
require 'digest/md5'
|
|
|
|
class SimpleCache
|
|
def initialize(app, options = {})
|
|
@app = app
|
|
@cache = {}
|
|
@ttl = options[:ttl] || 300 # 5 minutes
|
|
@cache_methods = options[:methods] || ['GET']
|
|
end
|
|
|
|
def call(env)
|
|
request = Rack::Request.new(env)
|
|
|
|
return @app.call(env) unless cacheable?(request)
|
|
|
|
cache_key = generate_cache_key(env)
|
|
|
|
if cached_response = get_from_cache(cache_key)
|
|
return cached_response
|
|
end
|
|
|
|
status, headers, body = @app.call(env)
|
|
|
|
if cacheable_response?(status)
|
|
cache_response(cache_key, [status, headers, body])
|
|
end
|
|
|
|
[status, headers, body]
|
|
end
|
|
|
|
private
|
|
|
|
def cacheable?(request)
|
|
@cache_methods.include?(request.request_method)
|
|
end
|
|
|
|
def cacheable_response?(status)
|
|
status == 200
|
|
end
|
|
|
|
def generate_cache_key(env)
|
|
# Include method, path, and query string
|
|
Digest::MD5.hexdigest([
|
|
env['REQUEST_METHOD'],
|
|
env['PATH_INFO'],
|
|
env['QUERY_STRING']
|
|
].join('|'))
|
|
end
|
|
|
|
def get_from_cache(key)
|
|
entry = @cache[key]
|
|
return nil unless entry
|
|
|
|
# Check if cache entry is still valid
|
|
if Time.now - entry[:cached_at] <= @ttl
|
|
entry[:response]
|
|
else
|
|
@cache.delete(key)
|
|
nil
|
|
end
|
|
end
|
|
|
|
def cache_response(key, response)
|
|
@cache[key] = {
|
|
response: response,
|
|
cached_at: Time.now
|
|
}
|
|
end
|
|
end
|
|
|
|
# Usage with Redis for distributed caching
|
|
class RedisCache
|
|
def initialize(app, options = {})
|
|
@app = app
|
|
@redis = Redis.new(url: options[:redis_url])
|
|
@ttl = options[:ttl] || 300
|
|
@namespace = options[:namespace] || 'cache'
|
|
end
|
|
|
|
def call(env)
|
|
request = Rack::Request.new(env)
|
|
|
|
return @app.call(env) unless request.get?
|
|
|
|
cache_key = generate_cache_key(env)
|
|
|
|
if cached = @redis.get(cache_key)
|
|
return Marshal.load(cached)
|
|
end
|
|
|
|
status, headers, body = @app.call(env)
|
|
|
|
if status == 200
|
|
@redis.setex(cache_key, @ttl, Marshal.dump([status, headers, body]))
|
|
end
|
|
|
|
[status, headers, body]
|
|
end
|
|
|
|
private
|
|
|
|
def generate_cache_key(env)
|
|
"#{@namespace}:#{Digest::MD5.hexdigest(env['PATH_INFO'] + env['QUERY_STRING'])}"
|
|
end
|
|
end
|
|
```
|
|
|
|
**Request Transformation Middleware:**
|
|
```ruby
|
|
class JSONBodyParser
|
|
def initialize(app)
|
|
@app = app
|
|
end
|
|
|
|
def call(env)
|
|
if json_request?(env)
|
|
body = env['rack.input'].read
|
|
env['rack.input'].rewind
|
|
|
|
begin
|
|
parsed = JSON.parse(body)
|
|
env['rack.request.form_hash'] = parsed
|
|
env['parsed_json'] = parsed
|
|
rescue JSON::ParserError => e
|
|
return error_response('Invalid JSON', 400)
|
|
end
|
|
end
|
|
|
|
@app.call(env)
|
|
end
|
|
|
|
private
|
|
|
|
def json_request?(env)
|
|
content_type = env['CONTENT_TYPE']
|
|
content_type && content_type.include?('application/json')
|
|
end
|
|
|
|
def error_response(message, status)
|
|
[
|
|
status,
|
|
{ 'Content-Type' => 'application/json' },
|
|
[{ error: message }.to_json]
|
|
]
|
|
end
|
|
end
|
|
|
|
# XML Parser
|
|
class XMLBodyParser
|
|
def initialize(app)
|
|
@app = app
|
|
end
|
|
|
|
def call(env)
|
|
if xml_request?(env)
|
|
body = env['rack.input'].read
|
|
env['rack.input'].rewind
|
|
|
|
begin
|
|
parsed = Hash.from_xml(body)
|
|
env['rack.request.form_hash'] = parsed
|
|
env['parsed_xml'] = parsed
|
|
rescue StandardError => e
|
|
return error_response('Invalid XML', 400)
|
|
end
|
|
end
|
|
|
|
@app.call(env)
|
|
end
|
|
|
|
private
|
|
|
|
def xml_request?(env)
|
|
content_type = env['CONTENT_TYPE']
|
|
content_type && (content_type.include?('application/xml') ||
|
|
content_type.include?('text/xml'))
|
|
end
|
|
|
|
def error_response(message, status)
|
|
[
|
|
status,
|
|
{ 'Content-Type' => 'application/json' },
|
|
[{ error: message }.to_json]
|
|
]
|
|
end
|
|
end
|
|
```
|
|
|
|
### Middleware Ordering Patterns
|
|
|
|
**Security-First Stack:**
|
|
```ruby
|
|
# config.ru
|
|
# 1. SSL redirect (production only)
|
|
use Rack::SSL if ENV['RACK_ENV'] == 'production'
|
|
|
|
# 2. Rate limiting (before everything else)
|
|
use Rack::Attack
|
|
|
|
# 3. Security headers
|
|
use SecurityHeaders
|
|
|
|
# 4. CORS (for API applications)
|
|
use Rack::Cors do
|
|
allow do
|
|
origins '*'
|
|
resource '*', headers: :any, methods: [:get, :post, :put, :delete, :options]
|
|
end
|
|
end
|
|
|
|
# 5. Compression
|
|
use Rack::Deflater
|
|
|
|
# 6. Static files
|
|
use Rack::Static, urls: ['/public'], root: 'public'
|
|
|
|
# 7. Logging
|
|
use Rack::CommonLogger
|
|
|
|
# 8. Request parsing
|
|
use JSONBodyParser
|
|
|
|
# 9. Sessions
|
|
use Rack::Session::Cookie,
|
|
secret: ENV['SESSION_SECRET'],
|
|
same_site: :strict,
|
|
httponly: true,
|
|
secure: ENV['RACK_ENV'] == 'production'
|
|
|
|
# 10. Protection (CSRF, etc.)
|
|
use Rack::Protection
|
|
|
|
# 11. Authentication
|
|
use TokenAuthentication, skip_paths: ['/login', '/public']
|
|
|
|
# 12. Performance monitoring
|
|
use PerformanceMonitor
|
|
|
|
# 13. Application
|
|
run Application
|
|
```
|
|
|
|
**API-Focused Stack:**
|
|
```ruby
|
|
# config.ru for API
|
|
# 1. CORS first for preflight
|
|
use Rack::Cors do
|
|
allow do
|
|
origins ENV.fetch('ALLOWED_ORIGINS', '*').split(',')
|
|
resource '*',
|
|
headers: :any,
|
|
methods: [:get, :post, :put, :patch, :delete, :options],
|
|
credentials: true,
|
|
max_age: 86400
|
|
end
|
|
end
|
|
|
|
# 2. Rate limiting
|
|
use Rack::Attack
|
|
|
|
# 3. Compression
|
|
use Rack::Deflater
|
|
|
|
# 4. Logging (structured JSON logs)
|
|
use RequestLogger
|
|
|
|
# 5. Request parsing
|
|
use JSONBodyParser
|
|
|
|
# 6. Authentication
|
|
use TokenAuthentication, skip_paths: ['/auth']
|
|
|
|
# 7. Caching
|
|
use RedisCache, ttl: 300
|
|
|
|
# 8. Application
|
|
run API
|
|
```
|
|
|
|
### Conditional Middleware
|
|
|
|
**Environment-Based:**
|
|
```ruby
|
|
class ConditionalMiddleware
|
|
def initialize(app, condition, middleware, *args)
|
|
@app = if condition.call
|
|
middleware.new(app, *args)
|
|
else
|
|
app
|
|
end
|
|
end
|
|
|
|
def call(env)
|
|
@app.call(env)
|
|
end
|
|
end
|
|
|
|
# Usage
|
|
use ConditionalMiddleware,
|
|
-> { ENV['RACK_ENV'] == 'development' },
|
|
Rack::ShowExceptions
|
|
|
|
use ConditionalMiddleware,
|
|
-> { ENV['ENABLE_PROFILING'] == 'true' },
|
|
RackMiniProfiler
|
|
```
|
|
|
|
**Path-Based:**
|
|
```ruby
|
|
class PathBasedMiddleware
|
|
def initialize(app, pattern, middleware, *args)
|
|
@app = app
|
|
@pattern = pattern
|
|
@middleware = middleware.new(app, *args)
|
|
end
|
|
|
|
def call(env)
|
|
if env['PATH_INFO'].match?(@pattern)
|
|
@middleware.call(env)
|
|
else
|
|
@app.call(env)
|
|
end
|
|
end
|
|
end
|
|
|
|
# Usage
|
|
use PathBasedMiddleware, %r{^/api}, CacheMiddleware, ttl: 300
|
|
use PathBasedMiddleware, %r{^/admin}, AdminAuth
|
|
```
|
|
|
|
### Error Handling Middleware
|
|
|
|
```ruby
|
|
class ErrorHandler
|
|
def initialize(app, options = {})
|
|
@app = app
|
|
@logger = options[:logger] || Logger.new(STDOUT)
|
|
@error_handlers = options[:handlers] || {}
|
|
end
|
|
|
|
def call(env)
|
|
@app.call(env)
|
|
rescue StandardError => e
|
|
handle_error(env, e)
|
|
end
|
|
|
|
private
|
|
|
|
def handle_error(env, error)
|
|
request = Rack::Request.new(env)
|
|
|
|
# Log error
|
|
@logger.error({
|
|
error: error.class.name,
|
|
message: error.message,
|
|
path: request.path,
|
|
method: request.request_method,
|
|
backtrace: error.backtrace[0..10]
|
|
}.to_json)
|
|
|
|
# Custom handler for specific error types
|
|
if handler = @error_handlers[error.class]
|
|
return handler.call(error)
|
|
end
|
|
|
|
# Default error response
|
|
status = status_for_error(error)
|
|
[
|
|
status,
|
|
{ 'Content-Type' => 'application/json' },
|
|
[{ error: error.message, type: error.class.name }.to_json]
|
|
]
|
|
end
|
|
|
|
def status_for_error(error)
|
|
case error
|
|
when ArgumentError, ValidationError
|
|
400
|
|
when NotFoundError
|
|
404
|
|
when AuthorizationError
|
|
403
|
|
when AuthenticationError
|
|
401
|
|
else
|
|
500
|
|
end
|
|
end
|
|
end
|
|
|
|
# Usage
|
|
use ErrorHandler,
|
|
handlers: {
|
|
ValidationError => ->(e) {
|
|
[422, { 'Content-Type' => 'application/json' },
|
|
[{ error: e.message, details: e.details }.to_json]]
|
|
}
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Tier 3: Resources & Examples
|
|
|
|
### Complete Middleware Examples
|
|
|
|
**Performance Monitoring:**
|
|
```ruby
|
|
class PerformanceMonitor
|
|
def initialize(app, options = {})
|
|
@app = app
|
|
@threshold = options[:threshold] || 1.0 # 1 second
|
|
@logger = options[:logger] || Logger.new(STDOUT)
|
|
end
|
|
|
|
def call(env)
|
|
start_time = Time.now
|
|
memory_before = memory_usage
|
|
|
|
status, headers, body = @app.call(env)
|
|
|
|
duration = Time.now - start_time
|
|
memory_after = memory_usage
|
|
memory_delta = memory_after - memory_before
|
|
|
|
# Add performance headers
|
|
headers['X-Runtime'] = duration.to_s
|
|
headers['X-Memory-Delta'] = memory_delta.to_s
|
|
|
|
# Log slow requests
|
|
if duration > @threshold
|
|
log_slow_request(env, duration, memory_delta)
|
|
end
|
|
|
|
[status, headers, body]
|
|
end
|
|
|
|
private
|
|
|
|
def memory_usage
|
|
`ps -o rss= -p #{Process.pid}`.to_i / 1024.0 # MB
|
|
end
|
|
|
|
def log_slow_request(env, duration, memory)
|
|
@logger.warn({
|
|
event: 'slow_request',
|
|
method: env['REQUEST_METHOD'],
|
|
path: env['PATH_INFO'],
|
|
duration: duration.round(3),
|
|
memory_delta: memory.round(2)
|
|
}.to_json)
|
|
end
|
|
end
|
|
```
|
|
|
|
**Request ID Tracking:**
|
|
```ruby
|
|
class RequestID
|
|
def initialize(app, options = {})
|
|
@app = app
|
|
@header = options[:header] || 'X-Request-ID'
|
|
end
|
|
|
|
def call(env)
|
|
request_id = env["HTTP_#{@header.upcase.tr('-', '_')}"] || generate_id
|
|
env['request.id'] = request_id
|
|
|
|
status, headers, body = @app.call(env)
|
|
|
|
headers[@header] = request_id
|
|
|
|
[status, headers, body]
|
|
end
|
|
|
|
private
|
|
|
|
def generate_id
|
|
SecureRandom.uuid
|
|
end
|
|
end
|
|
```
|
|
|
|
**Response Modification:**
|
|
```ruby
|
|
class ResponseTransformer
|
|
def initialize(app, &block)
|
|
@app = app
|
|
@transformer = block
|
|
end
|
|
|
|
def call(env)
|
|
status, headers, body = @app.call(env)
|
|
|
|
if should_transform?(headers)
|
|
body = transform_body(body)
|
|
end
|
|
|
|
[status, headers, body]
|
|
end
|
|
|
|
private
|
|
|
|
def should_transform?(headers)
|
|
headers['Content-Type']&.include?('application/json')
|
|
end
|
|
|
|
def transform_body(body)
|
|
content = body.is_a?(Array) ? body.join : body.read
|
|
transformed = @transformer.call(content)
|
|
[transformed]
|
|
end
|
|
end
|
|
|
|
# Usage
|
|
use ResponseTransformer do |body|
|
|
data = JSON.parse(body)
|
|
data['timestamp'] = Time.now.to_i
|
|
data.to_json
|
|
end
|
|
```
|
|
|
|
### Testing Middleware
|
|
|
|
```ruby
|
|
RSpec.describe RequestLogger do
|
|
let(:app) { ->(env) { [200, {}, ['OK']] } }
|
|
let(:logger) { double('Logger', info: nil, error: nil) }
|
|
let(:middleware) { RequestLogger.new(app, logger: logger) }
|
|
let(:request) { Rack::MockRequest.new(middleware) }
|
|
|
|
describe 'request logging' do
|
|
it 'logs request start' do
|
|
expect(logger).to receive(:info).with(hash_including(event: 'request.start'))
|
|
request.get('/')
|
|
end
|
|
|
|
it 'logs request end with duration' do
|
|
expect(logger).to receive(:info).with(hash_including(
|
|
event: 'request.end',
|
|
duration: kind_of(Numeric)
|
|
))
|
|
request.get('/')
|
|
end
|
|
|
|
it 'includes request details' do
|
|
expect(logger).to receive(:info).with(hash_including(
|
|
method: 'GET',
|
|
path: '/test'
|
|
))
|
|
request.get('/test')
|
|
end
|
|
end
|
|
|
|
describe 'error logging' do
|
|
let(:app) { ->(env) { raise StandardError, 'Test error' } }
|
|
|
|
it 'logs errors' do
|
|
expect(logger).to receive(:error).with(hash_including(
|
|
event: 'request.error',
|
|
error: 'StandardError'
|
|
))
|
|
|
|
expect { request.get('/') }.to raise_error(StandardError)
|
|
end
|
|
end
|
|
|
|
describe 'skip paths' do
|
|
let(:middleware) { RequestLogger.new(app, logger: logger, skip_paths: ['/health']) }
|
|
|
|
it 'skips logging for configured paths' do
|
|
expect(logger).not_to receive(:info)
|
|
request.get('/health')
|
|
end
|
|
end
|
|
end
|
|
```
|
|
|
|
### Additional Resources
|
|
|
|
- **Middleware Template:** `assets/middleware-template.rb` - Boilerplate for new middleware
|
|
- **Middleware Examples:** `assets/middleware-examples/` - Collection of useful middleware
|
|
- **Configuration Guide:** `assets/configuration-guide.md` - Best practices for middleware configuration
|
|
- **Performance Guide:** `references/performance-optimization.md` - Optimizing middleware performance
|
|
- **Testing Guide:** `references/middleware-testing.md` - Comprehensive testing strategies
|