rapitapir 0.1.0

data/examples/oauth2/test_songs_api.sh

@@ -0,0 +1,110 @@
+#!/bin/bash
+
+# Test script for Songs API with Auth0
+echo "🎵 Testing Songs API with Auth0 OAuth2..."
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Get a fresh token
+echo "🔑 Getting Auth0 token..."
+TOKEN=$(ruby get_token.rb 2>/dev/null | grep "📋 Full token:" -A1 | tail -1)
+
+if [ -z "$TOKEN" ]; then
+    echo -e "${RED}❌ Failed to get token${NC}"
+    exit 1
+fi
+
+echo -e "${GREEN}✅ Token obtained${NC}"
+
+# Test 1: Public endpoint (should work without auth)
+echo
+echo "🧪 Test 1: GET /songs (public endpoint)"
+RESPONSE=$(curl -s -w "%{http_code}" http://localhost:4567/songs)
+HTTP_CODE=${RESPONSE: -3}
+BODY=${RESPONSE%???}
+
+if [ "$HTTP_CODE" = "200" ]; then
+    echo -e "${GREEN}✅ Public endpoint accessible${NC}"
+    echo "📋 Response: $BODY"
+else
+    echo -e "${RED}❌ Public endpoint failed (HTTP $HTTP_CODE)${NC}"
+    echo "📋 Response: $BODY"
+fi
+
+# Test 2: Protected endpoint without auth (should fail)
+echo
+echo "🧪 Test 2: POST /songs without authentication"
+RESPONSE=$(curl -s -w "%{http_code}" -X POST http://localhost:4567/songs \
+    -H "Content-Type: application/json" \
+    -d '{"name":"Test Song","url":"https://example.com/test"}')
+HTTP_CODE=${RESPONSE: -3}
+BODY=${RESPONSE%???}
+
+if [ "$HTTP_CODE" = "401" ]; then
+    echo -e "${GREEN}✅ Authentication required (as expected)${NC}"
+    echo "📋 Response: $BODY"
+else
+    echo -e "${RED}❌ Should require authentication (HTTP $HTTP_CODE)${NC}"
+    echo "📋 Response: $BODY"
+fi
+
+# Test 3: Protected endpoint with valid token (should work)
+echo
+echo "🧪 Test 3: POST /songs with valid Auth0 token"
+RESPONSE=$(curl -s -w "%{http_code}" -X POST http://localhost:4567/songs \
+    -H "Content-Type: application/json" \
+    -H "Authorization: Bearer $TOKEN" \
+    -d '{"name":"Test Song from API","url":"https://example.com/test-api"}')
+HTTP_CODE=${RESPONSE: -3}
+BODY=${RESPONSE%???}
+
+if [ "$HTTP_CODE" = "200" ] || [ "$HTTP_CODE" = "201" ]; then
+    echo -e "${GREEN}✅ Song created successfully${NC}"
+    echo "📋 Response: $BODY"
+else
+    echo -e "${RED}❌ Song creation failed (HTTP $HTTP_CODE)${NC}"
+    echo "📋 Response: $BODY"
+fi
+
+# Test 4: Verify the song was added
+echo
+echo "🧪 Test 4: GET /songs (verify new song added)"
+RESPONSE=$(curl -s -w "%{http_code}" http://localhost:4567/songs)
+HTTP_CODE=${RESPONSE: -3}
+BODY=${RESPONSE%???}
+
+if [ "$HTTP_CODE" = "200" ]; then
+    echo -e "${GREEN}✅ Songs list retrieved${NC}"
+    echo "📋 Response: $BODY"
+    
+    # Check if our test song appears in the list
+    if [[ $BODY == *"Test Song from API"* ]]; then
+        echo -e "${GREEN}🎉 Test song found in the list!${NC}"
+    else
+        echo -e "${YELLOW}⚠️ Test song not found in the list${NC}"
+    fi
+else
+    echo -e "${RED}❌ Failed to retrieve songs list (HTTP $HTTP_CODE)${NC}"
+fi
+
+# Test 5: Test /me endpoint
+echo
+echo "🧪 Test 5: GET /me (user info with token)"
+RESPONSE=$(curl -s -w "%{http_code}" -H "Authorization: Bearer $TOKEN" http://localhost:4567/me)
+HTTP_CODE=${RESPONSE: -3}
+BODY=${RESPONSE%???}
+
+if [ "$HTTP_CODE" = "200" ]; then
+    echo -e "${GREEN}✅ User info retrieved${NC}"
+    echo "📋 Response: $BODY"
+else
+    echo -e "${RED}❌ User info failed (HTTP $HTTP_CODE)${NC}"
+    echo "📋 Response: $BODY"
+fi
+
+echo
+echo "🎵 Songs API testing complete!"

data/examples/observability/.env.example

@@ -0,0 +1,35 @@
+# Honeycomb.io Configuration for RapiTapir Demo
+# Copy this file to .env and update with your actual Honeycomb API key
+
+# Required: Your Honeycomb API key (get from https://ui.honeycomb.io/account)
+# Replace 'your-honeycomb-api-key-here' with your actual API key
+OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=your-honeycomb-api-key-here
+
+# Honeycomb endpoint (US instance - change to EU if needed)
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+
+# For EU instance, uncomment the line below instead:
+# OTEL_EXPORTER_OTLP_ENDPOINT=https://api.eu1.honeycomb.io
+
+# Service configuration
+OTEL_SERVICE_NAME=rapitapir-demo
+OTEL_SERVICE_VERSION=1.0.0
+
+# Resource attributes (optional but recommended)
+OTEL_RESOURCE_ATTRIBUTES=service.name=rapitapir-demo,service.version=1.0.0,deployment.environment=development
+
+# Sampling configuration (optional - keep 100% for demo, adjust for production)
+# OTEL_TRACES_SAMPLER=traceidratio
+# OTEL_TRACES_SAMPLER_ARG=0.1
+# OTEL_RESOURCE_ATTRIBUTES=SampleRate=10
+
+# Logging level for OpenTelemetry (optional)
+OTEL_LOG_LEVEL=info
+
+# Enable/disable specific signals (optional)
+OTEL_TRACES_EXPORTER=otlp
+OTEL_METRICS_EXPORTER=otlp
+OTEL_LOGS_EXPORTER=otlp
+
+# Additional debugging (optional - set to true for troubleshooting)
+OTEL_RUBY_TRACES_EXPORTER_DEBUG=false

data/examples/observability/README.md

@@ -0,0 +1,230 @@
+# RapiTapir Honeycomb.io Observability Example
+
+This example demonstrates how to integrate Honeycomb.io observability with a Ruby API using OpenTelemetry and RapiTapir patterns.
+
+## Prerequisites
+
+1. **Honeycomb.io Account**: Sign up at [honeycomb.io](https://honeycomb.io)
+2. **API Key**: Get your API key from Honeycomb settings
+3. **Ruby 3.1+**: Ensure you have Ruby installed
+4. **Bundler**: For managing dependencies
+
+## Setup
+
+### 1. Install Dependencies
+
+From the project root directory:
+
+```bash
+cd /path/to/ruby-tapir
+bundle install
+```
+
+### 2. Configure Environment
+
+Create a `.env` file in the `examples/observability/` directory:
+
+```bash
+# Honeycomb.io Configuration
+HONEYCOMB_API_KEY=your_api_key_here
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=your_api_key_here
+OTEL_SERVICE_NAME=rapitapir-demo
+OTEL_RESOURCE_ATTRIBUTES=service.name=rapitapir-demo,service.version=1.0.0
+```
+
+Replace `your_api_key_here` with your actual Honeycomb API key.
+
+### 3. Run the Server
+
+From the project root directory:
+
+```bash
+bundle exec ruby examples/observability/honeycomb_working_example.rb
+```
+
+The server will start on `http://localhost:4567` and display available endpoints.
+
+## API Endpoints
+
+### Health Check
+```bash
+curl http://localhost:4567/health
+```
+
+### User Management
+```bash
+# List users (with pagination and filtering)
+curl "http://localhost:4567/users?page=1&limit=10&department=engineering"
+
+# Create user
+curl -X POST http://localhost:4567/users \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Alice Johnson","email":"alice@example.com","age":28,"department":"engineering"}'
+
+# Get user by ID
+curl http://localhost:4567/users/USER_ID
+
+# Update user
+curl -X PUT http://localhost:4567/users/USER_ID \
+  -H 'Content-Type: application/json' \
+  -d '{"name":"Alice Johnson-Smith","department":"product"}'
+
+# Delete user
+curl -X DELETE http://localhost:4567/users/USER_ID
+```
+
+### Analytics
+```bash
+curl http://localhost:4567/analytics/department-stats
+```
+
+## Testing the Integration
+
+Run the comprehensive test suite:
+
+```bash
+ruby examples/observability/complete_test.rb
+```
+
+This will:
+1. Start the server
+2. Test all endpoints
+3. Generate sample data
+4. Create traces in Honeycomb
+5. Clean up the server
+
+## Observability Features
+
+### Automatic Instrumentation
+- **HTTP Requests**: All incoming requests are automatically traced
+- **Database Queries**: Simulated database operations with realistic timings
+- **External API Calls**: Net::HTTP requests are automatically instrumented
+- **Error Tracking**: Exceptions and errors are captured in spans
+
+### Custom Business Context
+Each request includes business-relevant attributes:
+- User information (ID, department, etc.)
+- Request metadata (pagination, filters)
+- Performance metrics (database response times)
+- Error context and stack traces
+
+### Span Hierarchy
+```
+HTTP Request Span (e.g., "POST /users")
+├── Database Operation Span (e.g., "users.create")
+├── Validation Span (e.g., "validate_user_data")
+└── Business Logic Span (e.g., "process_user_creation")
+```
+
+### Custom Metrics
+- Request duration and status codes
+- Database operation timing
+- User activity by department
+- Error rates and types
+
+## Viewing Traces in Honeycomb
+
+1. Log into your Honeycomb.io dashboard
+2. Navigate to the `rapitapir-demo` dataset
+3. You'll see traces for:
+   - HTTP requests with full request/response context
+   - Database operations with query timing
+   - Business operations with custom attributes
+   - Error traces with stack traces and context
+
+### Useful Queries
+
+**Find slow requests:**
+```
+duration_ms > 1000
+```
+
+**Group by endpoint:**
+```
+GROUP BY http.route
+```
+
+**Filter by department:**
+```
+user.department = "engineering"
+```
+
+**Find errors:**
+```
+status_code >= 400 OR error = true
+```
+
+## Architecture
+
+### OpenTelemetry Integration
+- **SDK**: Full OpenTelemetry SDK with OTLP exporter
+- **Auto-instrumentation**: Rack, Sinatra, and Net::HTTP
+- **Custom spans**: Business logic and database operations
+- **Baggage**: Cross-service context propagation
+
+### RapiTapir Extension
+The `RapiTapirObservability` module provides:
+- Automatic span creation for route handlers
+- Business context extraction from requests
+- Error handling and exception tracking
+- Performance monitoring helpers
+
+### Trace Context
+Each trace includes:
+- **Service metadata**: Name, version, environment
+- **Request context**: Method, path, query parameters, headers
+- **User context**: ID, department, business attributes
+- **Performance data**: Timing, resource usage, dependencies
+- **Error information**: Exception details, stack traces
+
+## Best Practices
+
+1. **Meaningful Span Names**: Use business-relevant names like "create_user" instead of generic ones
+2. **Rich Attributes**: Include business context that helps with debugging
+3. **Error Handling**: Always capture errors with full context
+4. **Performance Monitoring**: Track both technical and business metrics
+5. **Security**: Never log sensitive data like passwords or tokens
+
+## Production Considerations
+
+- **Sampling**: Configure sampling rates for high-traffic applications
+- **Resource Limits**: Set memory and CPU limits for the OpenTelemetry SDK
+- **Security**: Use environment variables for API keys, never commit them
+- **Monitoring**: Monitor the observability system itself for health
+- **Privacy**: Ensure compliance with data protection regulations
+
+## Troubleshooting
+
+### Server Won't Start
+```bash
+# Check if gems are installed
+bundle install
+
+# Run from project root with bundle exec
+bundle exec ruby examples/observability/honeycomb_working_example.rb
+```
+
+### No Traces in Honeycomb
+1. Verify API key is correct
+2. Check environment variables are loaded
+3. Confirm network connectivity to api.honeycomb.io
+4. Look for OpenTelemetry initialization messages in logs
+
+### Port Already in Use
+```bash
+# Kill any existing processes on port 4567
+lsof -ti:4567 | xargs kill -9
+```
+
+## Contributing
+
+Feel free to extend this example with:
+- Additional instrumentation for your specific use cases
+- Custom metrics and dashboards
+- Integration with other observability tools
+- Performance optimizations
+
+---
+
+This example demonstrates production-ready observability integration that you can adapt for your own RapiTapir applications. The patterns shown here scale from development to production environments.

data/examples/observability/README_HONEYCOMB.md

@@ -0,0 +1,332 @@
+# 🍯 RapiTapir Honeycomb.io Observability Example
+
+This example demonstrates how to integrate **RapiTapir** with **Honeycomb.io** using **OpenTelemetry** for comprehensive observability, including distributed tracing, custom spans, baggage propagation, and business metrics.
+
+## 🚀 Features Demonstrated
+
+- **OpenTelemetry Integration**: Full SDK setup with Honeycomb.io OTLP exporter
+- **Automatic Instrumentation**: Sinatra, Rack, HTTP, and JSON instrumentation
+- **Custom Spans**: Business logic tracing with detailed attributes
+- **Baggage Propagation**: Context sharing across spans
+- **Error Handling**: Comprehensive error tracing and status reporting
+- **Health Checks**: Traced health check endpoints
+- **Business Analytics**: Custom spans for complex operations
+- **Performance Monitoring**: Request timing and resource usage
+
+## 📋 Prerequisites
+
+1. **Ruby 3.2+** installed
+2. **Honeycomb.io account** (free account available at [honeycomb.io](https://ui.honeycomb.io/signup))
+3. **Honeycomb API Key** with "Can create datasets" permission
+
+## 🔧 Setup Instructions
+
+### 1. Install Dependencies
+
+First, install the required OpenTelemetry gems. The main Gemfile already includes them:
+
+```bash
+bundle install
+```
+
+### 2. Get Your Honeycomb API Key
+
+1. Sign up for a free Honeycomb account at [honeycomb.io](https://ui.honeycomb.io/signup)
+2. Go to **Environment Settings** → **API Keys**
+3. Create a new API key with **"Can create datasets"** checked
+4. Copy your API key (you won't be able to see it again!)
+
+### 3. Configure Environment Variables
+
+Copy the example environment file and update it with your API key:
+
+```bash
+cd examples/observability
+cp .env.example .env
+```
+
+Edit `.env` and replace `your-honeycomb-api-key-here` with your actual API key:
+
+```bash
+# Required: Your Honeycomb API key
+OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=YOUR_ACTUAL_API_KEY_HERE
+
+# Honeycomb endpoint (US instance)
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io
+
+# Service configuration
+OTEL_SERVICE_NAME=rapitapir-demo
+OTEL_SERVICE_VERSION=1.0.0
+```
+
+For EU instance users, use:
+```bash
+OTEL_EXPORTER_OTLP_ENDPOINT=https://api.eu1.honeycomb.io
+```
+
+### 4. Load Environment Variables
+
+```bash
+# Install dotenv if not already installed
+gem install dotenv
+
+# Load the environment
+source .env
+# Or use dotenv if you prefer
+dotenv -f .env
+```
+
+## 🏃‍♂️ Running the Demo
+
+### Start the Server
+
+```bash
+cd examples/observability
+ruby honeycomb_example.rb
+```
+
+The server will start on `http://localhost:4567` and display:
+
+```
+🍯 Starting RapiTapir Demo API with Honeycomb.io Observability
+📊 Traces will be sent to: https://api.honeycomb.io
+🔧 Service Name: rapitapir-demo
+
+🚀 Available endpoints:
+   GET    /health                   - Health check
+   GET    /users                    - List users
+   POST   /users                    - Create user
+   GET    /users/:id                - Get user by ID
+   PUT    /users/:id                - Update user
+   DELETE /users/:id                - Delete user
+   GET    /analytics/department-stats - Department analytics
+```
+
+### Test the API
+
+Generate some traces by making requests:
+
+```bash
+# Health check
+curl http://localhost:4567/health
+
+# Create users
+curl -X POST http://localhost:4567/users \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "Alice Engineer",
+    "email": "alice@example.com",
+    "age": 28,
+    "department": "engineering"
+  }'
+
+curl -X POST http://localhost:4567/users \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "name": "Bob Sales",
+    "email": "bob@example.com", 
+    "age": 32,
+    "department": "sales"
+  }'
+
+# List users with filtering and pagination
+curl "http://localhost:4567/users"
+curl "http://localhost:4567/users?department=engineering&page=1&limit=5"
+
+# Get analytics (complex operation with multiple spans)
+curl http://localhost:4567/analytics/department-stats
+
+# Test error handling
+curl -X POST http://localhost:4567/users \
+  -H 'Content-Type: application/json' \
+  -d '{"invalid": "data"}'
+```
+
+## 📊 Viewing Data in Honeycomb
+
+1. Go to [Honeycomb.io](https://ui.honeycomb.io/) and log in
+2. You should see a new dataset called **"rapitapir-demo"** (or whatever you set as `OTEL_SERVICE_NAME`)
+3. Click on the dataset to start exploring your traces
+
+### Key Honeycomb Features to Explore
+
+#### 1. **Traces View**
+- See complete request flows from HTTP request to business logic
+- Identify performance bottlenecks and slow operations
+- Visualize parent-child span relationships
+
+#### 2. **Useful Queries to Try**
+
+```sql
+-- Find slow requests
+WHERE duration_ms > 100
+
+-- Find errors by type
+WHERE error.type EXISTS
+
+-- Analyze by department
+GROUP BY user.department
+
+-- Find database operations
+WHERE db.operation EXISTS
+
+-- Look at business operations
+WHERE business.operation = "create_user"
+
+-- Health check performance
+WHERE business.operation = "health_check"
+```
+
+#### 3. **Custom Attributes Added**
+
+The example adds rich context to spans:
+
+**HTTP Attributes:**
+- `http.method`, `http.url`, `http.status_code`
+- `http.user_agent`, `http.response_size`
+
+**Business Attributes:**
+- `business.operation` (create_user, list_users, etc.)
+- `business.entity` (user, analytics)
+- `user.id`, `user.department`
+
+**Database Simulation:**
+- `db.operation` (SELECT, INSERT, UPDATE, DELETE)
+- `db.table` (users)
+- Query timing and performance
+
+**Custom Metrics:**
+- `duration_ms` - Request/operation timing
+- `result.count` - Number of items returned
+- `pagination.*` - Pagination metadata
+
+#### 4. **Baggage Propagation**
+
+The example demonstrates OpenTelemetry baggage:
+- `request.id` - Unique identifier for each request
+- `service.name` - Service context
+- `user.created` - Business event flags
+
+## 🔧 Advanced Configuration
+
+### Sampling for Production
+
+For high-traffic production environments, enable sampling:
+
+```bash
+# Keep 10% of traces (1/10)
+OTEL_TRACES_SAMPLER=traceidratio
+OTEL_TRACES_SAMPLER_ARG=0.1
+OTEL_RESOURCE_ATTRIBUTES=SampleRate=10
+```
+
+### Custom Span Processors
+
+The example includes custom span processors:
+
+```ruby
+# Add baggage to all spans
+config.add_span_processor(OpenTelemetry::Processor::Baggage::BaggageSpanProcessor.new)
+
+# Batch export to Honeycomb
+config.add_span_processor(
+  OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(
+    OpenTelemetry::Exporter::OTLP::Exporter.new
+  )
+)
+```
+
+### Error Handling
+
+Comprehensive error tracking:
+
+```ruby
+rescue StandardError => e
+  span.set_attribute('error.type', e.class.name)
+  span.set_attribute('error.message', e.message)
+  span.status = OpenTelemetry::Trace::Status.error(e.message)
+end
+```
+
+## 🏗️ Architecture
+
+The example demonstrates a layered observability approach:
+
+```
+┌─────────────────────────────────────┐
+│ HTTP Request (Automatic Instrumentation) │
+├─────────────────────────────────────┤
+│ Sinatra Route Handler               │
+├─────────────────────────────────────┤
+│ Business Logic Spans               │
+├─────────────────────────────────────┤
+│ Database/External Service Simulation│
+├─────────────────────────────────────┤
+│ Honeycomb.io via OTLP             │
+└─────────────────────────────────────┘
+```
+
+### Span Hierarchy Example
+
+```
+POST /users
+├─ users.create (business logic)
+│  ├─ validation.user_input
+│  └─ database.insert.user
+└─ HTTP span (automatic)
+```
+
+## 🐛 Troubleshooting
+
+### No Data in Honeycomb?
+
+1. **Check API Key**: Ensure your API key is correct and has "Can create datasets" permission
+2. **Check Endpoint**: US vs EU instance
+3. **Check Environment**: Make sure environment variables are loaded
+4. **Enable Debug Mode**:
+   ```bash
+   OTEL_RUBY_TRACES_EXPORTER_DEBUG=true
+   OTEL_LOG_LEVEL=debug
+   ```
+
+### Debugging OpenTelemetry
+
+Add debug logging to see what's happening:
+
+```ruby
+# Add this to the top of honeycomb_example.rb
+ENV['OTEL_LOG_LEVEL'] = 'debug'
+```
+
+### Common Issues
+
+1. **Missing Dataset**: Ensure API key has "Can create datasets" permission
+2. **EU vs US Instance**: Check you're using the correct endpoint
+3. **Firewall**: Ensure outbound HTTPS to Honeycomb is allowed
+4. **Gem Conflicts**: Run `bundle install` to ensure all OpenTelemetry gems are compatible
+
+## 📚 Further Reading
+
+- [Honeycomb OpenTelemetry Ruby Guide](https://docs.honeycomb.io/send-data/ruby/opentelemetry-sdk/)
+- [OpenTelemetry Ruby Documentation](https://opentelemetry.io/docs/instrumentation/ruby/)
+- [Honeycomb Query Language](https://docs.honeycomb.io/query-data/)
+- [OpenTelemetry Semantic Conventions](https://opentelemetry.io/docs/specs/semconv/)
+
+## 🎯 Production Considerations
+
+1. **Sampling**: Enable sampling for high-traffic applications
+2. **Resource Attributes**: Add deployment environment, version tags
+3. **Security**: Store API keys securely (not in code)
+4. **Monitoring**: Set up alerts in Honeycomb for error rates and latency
+5. **Performance**: Monitor the overhead of instrumentation
+
+## 🤝 Integration with RapiTapir
+
+This example shows how to extend RapiTapir with comprehensive observability:
+
+- **Custom Sinatra Extension**: `RapiTapir::Extensions::HoneycombObservability`
+- **Automatic Context Propagation**: Request IDs and business context
+- **Health Check Integration**: Traced health checks with timing
+- **Error Handling**: Structured error reporting with context
+
+The pattern can be extended to other frameworks (Rails, Roda, etc.) and provides a foundation for production-ready observability in RapiTapir applications.