Binding Patterns and Best Practices

Service Binding Patterns

RPC via Service Bindings

// auth-worker
export default {
  async fetch(request: Request, env: Env) {
    const token = request.headers.get('Authorization');
    return new Response(JSON.stringify({ valid: await validateToken(token) }));
  }
}

// api-worker
const response = await env.AUTH_SERVICE.fetch(
  new Request('https://fake-host/validate', {
    headers: { 'Authorization': token }
  })
);

Why RPC? Zero latency (same datacenter), no DNS, free, type-safe.

HTTP vs Service:

// ❌ HTTP (slow, paid, cross-region latency)
await fetch('https://auth-worker.example.com/validate');

// ✅ Service binding (fast, free, same isolate)
await env.AUTH_SERVICE.fetch(new Request('https://fake-host/validate'));

URL doesn't matter: Service bindings ignore hostname/protocol, routing happens via binding name.

Typed Service RPC

// shared-types.ts
export interface AuthRequest { token: string; }
export interface AuthResponse { valid: boolean; userId?: string; }

// auth-worker
export default {
  async fetch(request: Request): Promise<Response> {
    const body: AuthRequest = await request.json();
    const response: AuthResponse = { valid: true, userId: '123' };
    return Response.json(response);
  }
}

// api-worker
const response = await env.AUTH_SERVICE.fetch(
  new Request('https://fake/validate', {
    method: 'POST',
    body: JSON.stringify({ token } satisfies AuthRequest)
  })
);
const data: AuthResponse = await response.json();

Secrets Management

# Set secret
npx wrangler secret put API_KEY
cat api-key.txt | npx wrangler secret put API_KEY
npx wrangler secret put API_KEY --env staging

// Use secret
const response = await fetch('https://api.example.com', {
  headers: { 'Authorization': `Bearer ${env.API_KEY}` }
});

Never commit secrets:

// ❌ NEVER
{ "vars": { "API_KEY": "sk_live_abc123" } }

Testing with Mock Bindings

Vitest Mock

import { vi } from 'vitest';

const mockKV: KVNamespace = {
  get: vi.fn(async (key) => key === 'test' ? 'value' : null),
  put: vi.fn(async () => {}),
  delete: vi.fn(async () => {}),
  list: vi.fn(async () => ({ keys: [], list_complete: true, cursor: '' })),
  getWithMetadata: vi.fn(),
} as unknown as KVNamespace;

const mockEnv: Env = { MY_KV: mockKV };
const mockCtx: ExecutionContext = {
  waitUntil: vi.fn(),
  passThroughOnException: vi.fn(),
};

const response = await worker.fetch(
  new Request('http://localhost/test'),
  mockEnv,
  mockCtx
);

Binding Access Patterns

Lazy Access

// ✅ Access only when needed
if (url.pathname === '/cached') {
  const cached = await env.MY_KV.get('data');
  if (cached) return new Response(cached);
}

Parallel Access

// ✅ Parallelize independent calls
const [user, config, cache] = await Promise.all([
  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first(),
  env.MY_KV.get('config'),
  env.CACHE.get('data')
]);

Storage Selection

KV: CDN-Backed Reads

const config = await env.MY_KV.get('app-config', { type: 'json' });

Use when: Read-heavy, <25MB, global distribution, eventual consistency OK
Latency: <10ms reads (cached), writes eventually consistent (60s)

D1: Relational Queries

const results = await env.DB.prepare(`
  SELECT u.name, COUNT(o.id) FROM users u
  LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id
`).all();

Use when: Relational data, JOINs, ACID transactions
Limits: 10GB database size, 100k rows per query

R2: Large Objects

const object = await env.MY_BUCKET.get('large-file.zip');
return new Response(object.body);

Use when: Files >25MB, S3-compatible API needed
Limits: 5TB per object, unlimited storage

Durable Objects: Coordination

const id = env.COUNTER.idFromName('global');
const stub = env.COUNTER.get(id);
await stub.fetch(new Request('https://fake/increment'));

Use when: Strong consistency, real-time coordination, WebSocket state
Guarantees: Single-threaded execution, transactional storage

Anti-Patterns

❌ Hardcoding credentials: const apiKey = 'sk_live_abc123'
✅ npx wrangler secret put API_KEY

❌ Using REST API: fetch('https://api.cloudflare.com/.../kv/...')
✅ env.MY_KV.get('key')

❌ Polling storage: setInterval(() => env.KV.get('config'), 1000)
✅ Use Durable Objects for real-time state

❌ Large data in vars: { "vars": { "HUGE_CONFIG": "..." } } (5KB max)
✅ env.MY_KV.put('config', data)

❌ Caching env globally: const apiKey = env.API_KEY outside fetch()
✅ Access env.API_KEY per-request inside fetch()

/cloudflare-deploy

referencesbindingspatterns.md