Eve library

BFF (Backend for Frontend) Patterns

Guide

Revision 1

On this page

Reference documentation for the BFF service architecture, client adapters, error handling, and rate limiting.

Overview#

The BFF (Backend for Frontend) service provides:

  • Request Routing: Multi-region service discovery with retry logic
  • Response Aggregation: Parallel/sequential multi-service requests
  • Response Shaping: Client-specific payload optimization
  • Circuit Breaker: Graceful degradation with mock fallbacks
  • Error Normalization: Consistent error format with correlation IDs

Service Request Routing#

Configuration#

Service registry defines backend service configurations:

typescript
interface ServiceConfig {
  url: string; // Primary service URL
  timeout?: number; // Request timeout (default: 30000ms)
  retries?: number; // Retry attempts (default: 0)
  retryDelayMs?: number; // Base retry delay (default: 150ms)
  regionalUrls?: Record<string, string>; // Region-specific URLs
  defaultRegionId?: string; // Default region
}

Multi-Region Support#

Requests are routed to the appropriate regional endpoint:

typescript
// Region resolution priority:
// 1. x-region-id or x-preferred-region-id header
// 2. Service defaultRegionId
// 3. First active region

Region Configuration:

typescript
interface Region {
  region_id: string;
  region_name: string;
  endpoint: string;
  availability_zones: string[];
  status: 'active' | 'degraded' | 'inactive';
}

Request Flow#

text
Client Request
    ↓
Check Circuit Breaker State
    ↓
Resolve Regional URL
    ↓
Add Headers (correlation, trace, span)
    ↓
Execute Request with Timeout
    ↓
    ├─ Success → Record Success → Return Response
    │
    └─ Failure → Retry with Backoff → Record Failure
                     ↓
                 Mock Fallback Response

Tracing Headers#

All requests include distributed tracing headers:

Header Description
x-correlation-id Request correlation ID (inherited or generated)
x-trace-id Trace ID for distributed tracing
x-span-id Current span ID (16 chars)
x-parent-span-id Parent span ID
x-service-name Service name (bff)
x-service-version Service version

Response Aggregation#

Combine multiple service requests in a single API call.

Aggregation Endpoint#

http
POST /v1/aggregate
Content-Type: application/json
Authorization: Bearer <token>

{
  "strategy": "parallel",
  "requests": [
    {
      "id": "user_profile",
      "service": "auth",
      "path": "/v1/users/me",
      "method": "GET"
    },
    {
      "id": "content_feed",
      "service": "content",
      "path": "/v1/feed",
      "method": "GET"
    },
    {
      "id": "notifications",
      "service": "notification",
      "path": "/v1/notifications",
      "method": "GET",
      "headers": { "x-limit": "10" }
    }
  ]
}

Aggregation Strategies#

Strategy Description
parallel Execute all requests concurrently (default)
sequential Execute requests in order

Response Format#

json
{
  "results": [
    {
      "id": "user_profile",
      "success": true,
      "data": { "user_id": "...", "name": "..." },
      "latency": 45
    },
    {
      "id": "content_feed",
      "success": true,
      "data": { "items": [...] },
      "latency": 120
    },
    {
      "id": "notifications",
      "success": false,
      "error": "Service unavailable",
      "latency": 30000
    }
  ],
  "totalLatency": 120,
  "strategy": "parallel"
}

Client-Specific Response Shaping#

Optimize responses based on client type and capabilities.

Client Types#

Client Type Detection Optimizations
web Default Full payload
mobile mobile, android, iphone in UA Image optimization, lightweight items, 500KB limit
tablet tablet, ipad in UA Medium-res images
embedded embedded, iot in UA Minimal essential fields only

Configuration#

typescript
interface ResponseShapingConfig {
  clientType?: 'web' | 'mobile' | 'tablet' | 'embedded';
  apiVersion?: string;
  features?: string[];
  maxPayloadSize?: number;
  compressionLevel?: 'low' | 'medium' | 'high';
  includeMetadata?: boolean;
}

Mobile Optimizations#

typescript
// Image URLs transformed
img.url.replace('/original/', '/mobile/');
img.thumbnail = img.url.replace('/original/', '/thumb/');

// List items stripped of heavy content
const { full_content, raw_data, ...lightweight } = item;

// Numbers reduced to 2 decimal places
metrics[key] = Number(value.toFixed(2));

Embedded/IoT Optimizations#

Only critical fields are returned:

typescript
const criticalFields = ['id', 'status', 'value', 'timestamp', 'error'];

Payload Size Limits#

When payload exceeds limit, fields are removed in priority order:

  1. raw_data
  2. full_content
  3. debug_info
  4. metadata
  5. internal_notes
  6. related_items

Then arrays are truncated to 50%.

Response Metadata#

When includeMetadata: true:

json
{
  "data": "...",
  "_meta": {
    "client_type": "mobile",
    "api_version": "v1",
    "shaped": true,
    "timestamp": "2025-01-15T10:30:00.000Z"
  }
}

Headers for Client Detection#

Header Description
User-Agent Client type detection
X-API-Version API version (default: v1)
X-Features Comma-separated feature flags

Enable Debug Metadata#

http
GET /v1/endpoint?debug=true

Circuit Breaker Pattern#

Graceful degradation when services fail.

Circuit Breaker States#

State Description
closed Normal operation, requests pass through
open Service failed, reject requests immediately
half-open Testing recovery, limited requests

State Transitions#

text
CLOSED → OPEN (after 5 failures)
    ↓
OPEN (30 second cooldown)
    ↓
HALF-OPEN (test requests)
    ↓
    ├─ 3 successes → CLOSED
    │
    └─ Any failure → OPEN

Configuration#

typescript
// Failure threshold to open circuit
const FAILURE_THRESHOLD = 5;

// Cooldown before half-open state
const COOLDOWN_MS = 30000;

// Successes needed to close circuit
const SUCCESS_THRESHOLD = 3;

Mock Fallback Responses#

When circuit is open, mock fallback responses are returned:

json
{
  "status": 200,
  "body": { "mock": true, "data": [] },
  "fallback": true,
  "trace_id": "abc123",
  "error": "Circuit breaker is open for service auth"
}

Circuit Breaker API#

http
GET /v1/admin/circuit-breakers

Returns state of all circuit breakers.

Error Handling#

Consistent error normalization with correlation tracking.

Error Response Format#

json
{
  "error": "Authentication failed",
  "code": "auth.invalid_credentials",
  "category": "authentication",
  "severity": "error",
  "http_status": 401,
  "trace_id": "abc123-def456",
  "correlation_id": "xyz789",
  "service": "bff",
  "timestamp": "2025-01-15T10:30:00.000Z",
  "retry_after": 60
}

Error Headers#

Header Description
x-correlation-id Request correlation ID
x-error-category Error category
x-error-severity Error severity level
retry-after Seconds until retry (for rate limits)

Error Categories#

Category HTTP Status Description
validation 400 Invalid request data
authentication 401 Auth failure
authorization 403 Permission denied
not_found 404 Resource not found
rate_limit 429 Too many requests
service_unavailable 503 Backend service down
network_error 502 Network/timeout error
internal 500 Internal error

Error Management API#

Get Error Mappings:

http
GET /v1/admin/errors/mappings

Test Error Normalization:

http
POST /v1/admin/errors/normalize
Content-Type: application/json

{
  "error": {
    "message": "Custom error",
    "code": "custom_error"
  },
  "context": {
    "service": "content"
  }
}

Simulate Error Types:

http
POST /v1/admin/errors/test
Content-Type: application/json

{
  "error_type": "rate_limit",
  "simulate_service": "auth"
}

Available error types:

  • validation
  • authentication
  • rate_limit
  • service_unavailable
  • network_timeout
  • internal

Rate Limiting#

Rate limiting via circuit breaker pattern and graceful degradation.

Implementation#

Rate limiting is implemented through:

  1. Circuit Breaker: Protects against cascading failures
  2. Timeout Enforcement: Per-service configurable timeouts
  3. Retry Limiting: Maximum retry attempts with exponential backoff

Per-Service Limits#

typescript
const serviceConfig = {
  timeout: 30000, // 30 second timeout
  retries: 2, // 2 retry attempts
  retryDelayMs: 150, // Base delay (doubles each retry)
};

Backoff Strategy#

Exponential backoff with maximum cap:

typescript
const backoff = retryDelayBase * Math.pow(2, attempt - 1);
const delay = Math.min(backoff, 2000); // Max 2 second delay

Rate Limit Response#

When rate limited by backend:

json
{
  "error": "Rate limit exceeded",
  "code": "rate_limit_exceeded",
  "retry_after": 60,
  "trace_id": "abc123"
}

Headers#

Header Description
Retry-After Seconds until rate limit resets
X-RateLimit-Limit Request limit
X-RateLimit-Remaining Remaining requests
X-RateLimit-Reset Reset timestamp

Multi-Region Configuration#

Register Region#

typescript
registerRegion({
  region_id: 'us-east-1',
  region_name: 'US East',
  endpoint: 'https://api-east.example.com',
  availability_zones: ['us-east-1a', 'us-east-1b'],
  status: 'active',
});

Update Region Status#

typescript
updateRegionStatus('us-east-1', 'degraded');

Set Region Priority#

typescript
setRegionPriority('us-east-1', 1); // Highest priority
setRegionPriority('us-west-2', 2);

Get Configuration#

typescript
const config = getMultiRegionConfig();
// {
//   regions: [...],
//   active_regions_count: 2,
//   total_availability_zones: 6,
//   is_active_active: true,
//   priorities: [{ region_id: 'us-east-1', priority: 1 }, ...],
//   last_updated: "2025-01-15T10:30:00.000Z"
// }

Active-Active Requirements#

Active-active mode requires at least 2 active regions.

Integration Example#

typescript
import { createServiceRequest } from './setup/create-service-request';
import { initializeCircuitBreakers } from './utils/circuit-breaker';

// Initialize
const serviceRegistry = {
  auth: { url: 'http://auth:8080', timeout: 5000, retries: 2 },
  content: { url: 'http://content:8080', timeout: 10000 },
  notification: { url: 'http://notification:8080' },
};

const circuitBreakers = initializeCircuitBreakers(serviceRegistry);

const makeRequest = createServiceRequest({
  serviceRegistry,
  circuitBreakers,
  recordCircuitBreakerSuccess,
  recordCircuitBreakerFailure,
  getMockFallbackResponse,
  delay: (ms) => new Promise((r) => setTimeout(r, ms)),
  randomUUID: () => crypto.randomUUID(),
});

// Make service request
const response = await makeRequest('auth', '/v1/users/me', 'GET', {
  Authorization: 'Bearer token',
});

if (response.fallback) {
  console.log('Using fallback response');
}