Skip to main content

Production Deployment Guide

Health Checks​

The Flow API provides health check endpoints for monitoring and orchestration:

Liveness Probe​

GET /health/liveness

Returns 200 OK if the service is running. Use this for basic health monitoring.

Readiness Probe​

GET /health/readiness

Returns 200 OK if the service is ready to accept traffic. Checks database connectivity.

Comprehensive Health Check​

GET /health/health

Returns detailed health status including:

  • Overall status (healthy, degraded, unhealthy)
  • Database connectivity and latency
  • Storage (R2) connectivity
  • Queue connectivity

Response:

{
  "status": "healthy",
  "timestamp": 1703123456000,
  "version": "1.0.0",
  "checks": {
    "database": {
      "status": "ok",
      "latency": 5
    },
    "storage": {
      "status": "ok"
    },
    "queue": {
      "status": "ok"
    }
  }
}

Security​

CORS Configuration​

  • Production: Only configured origins allowed
  • Development: Localhost origins allowed
  • Configure via APP_URL environment variable

Request Limits​

  • Maximum request body size: 1MB
  • Maximum URL length: 2048 characters
  • Maximum query string: 1024 characters

Rate Limits​

  • Default: 100 requests/minute per API key
  • Post creation: 30 requests/minute
  • Webhook creation: 10 requests/minute
  • API key creation: 5 requests/minute

Security Headers​

All responses include:

  • X-Content-Type-Options: nosniff
  • X-Frame-Options: DENY
  • X-XSS-Protection: 1; mode=block
  • Referrer-Policy: strict-origin-when-cross-origin
  • Strict-Transport-Security: max-age=31536000 (production only)

Input Validation​

Channel Names​

  • Required
  • Maximum 100 characters
  • HTML tags removed

Post Content​

  • Required (or media must be provided)
  • Maximum 10,000 characters
  • HTML tags removed

Webhook URLs​

  • Must be HTTPS in production
  • Must be valid URL format
  • Localhost/private IPs blocked in production

UUIDs​

  • All resource IDs must be valid UUIDs
  • Validated on all endpoints

Error Handling​

Circuit Breakers​

External API calls (Twitter, LinkedIn) are protected by circuit breakers:

  • Opens after 5 consecutive failures
  • Resets after 1 minute
  • Prevents cascading failures

Timeouts​

  • Database operations: 5 seconds
  • Storage operations: 10 seconds
  • External API calls: 30 seconds
  • Webhook delivery: 10 seconds

Graceful Degradation​

  • Database failures: Service marked as unhealthy
  • Storage failures: Service marked as degraded (non-critical)
  • Queue failures: Service marked as degraded (non-critical)

Monitoring​

Audit Logging​

The following operations are audited:

  • API key creation/deletion
  • Webhook creation/deletion
  • All operations include: user ID, API key ID, IP address, timestamp, request ID

Request Logging​

All API requests are logged with:

  • Request ID
  • Method and path
  • Status code
  • Response time
  • API key ID (if applicable)
  • User ID (if applicable)

Deployment Checklist​

  • Set APP_URL environment variable
  • Configure CORS allowed origins
  • Set up health check monitoring
  • Configure alerting for health check failures
  • Set up audit log collection
  • Configure rate limit monitoring
  • Set up error tracking
  • Configure backup strategy for D1 database
  • Test circuit breakers
  • Verify timeout configurations
  • Review security headers
  • Test input validation
  • Verify webhook URL validation
  • Test graceful degradation

Performance Targets​

  • API response time: < 200ms (p95)
  • Database query time: < 50ms (p95)
  • Health check latency: < 100ms
  • Uptime target: 99.9%

SLA​

  • Uptime: 99.9% (43 minutes downtime/month)
  • Response Time: 95% of requests < 200ms
  • Error Rate: < 0.1% of requests
  • Webhook Delivery: 95% success rate