1# Binding Patterns and Best Practices
2 
3## Service Binding Patterns
4 
5### RPC via Service Bindings
6 
7```typescript
8// auth-worker
9export default {
10  async fetch(request: Request, env: Env) {
11    const token = request.headers.get('Authorization');
12    return new Response(JSON.stringify({ valid: await validateToken(token) }));
13  }
14}
15 
16// api-worker
17const response = await env.AUTH_SERVICE.fetch(
18  new Request('https://fake-host/validate', {
19    headers: { 'Authorization': token }
20  })
21);
22```
23 
24**Why RPC?** Zero latency (same datacenter), no DNS, free, type-safe.
25 
26**HTTP vs Service:**
27```typescript
28// ❌ HTTP (slow, paid, cross-region latency)
29await fetch('https://auth-worker.example.com/validate');
30 
31// ✅ Service binding (fast, free, same isolate)
32await env.AUTH_SERVICE.fetch(new Request('https://fake-host/validate'));
33```
34 
35**URL doesn't matter:** Service bindings ignore hostname/protocol, routing happens via binding name.
36 
37### Typed Service RPC
38 
39```typescript
40// shared-types.ts
41export interface AuthRequest { token: string; }
42export interface AuthResponse { valid: boolean; userId?: string; }
43 
44// auth-worker
45export default {
46  async fetch(request: Request): Promise<Response> {
47    const body: AuthRequest = await request.json();
48    const response: AuthResponse = { valid: true, userId: '123' };
49    return Response.json(response);
50  }
51}
52 
53// api-worker
54const response = await env.AUTH_SERVICE.fetch(
55  new Request('https://fake/validate', {
56    method: 'POST',
57    body: JSON.stringify({ token } satisfies AuthRequest)
58  })
59);
60const data: AuthResponse = await response.json();
61```
62 
63## Secrets Management
64 
65```bash
66# Set secret
67npx wrangler secret put API_KEY
68cat api-key.txt | npx wrangler secret put API_KEY
69npx wrangler secret put API_KEY --env staging
70```
71 
72```typescript
73// Use secret
74const response = await fetch('https://api.example.com', {
75  headers: { 'Authorization': `Bearer ${env.API_KEY}` }
76});
77```
78 
79**Never commit secrets:**
80```jsonc
81// ❌ NEVER
82{ "vars": { "API_KEY": "sk_live_abc123" } }
83```
84 
85## Testing with Mock Bindings
86 
87### Vitest Mock
88 
89```typescript
90import { vi } from 'vitest';
91 
92const mockKV: KVNamespace = {
93  get: vi.fn(async (key) => key === 'test' ? 'value' : null),
94  put: vi.fn(async () => {}),
95  delete: vi.fn(async () => {}),
96  list: vi.fn(async () => ({ keys: [], list_complete: true, cursor: '' })),
97  getWithMetadata: vi.fn(),
98} as unknown as KVNamespace;
99 
100const mockEnv: Env = { MY_KV: mockKV };
101const mockCtx: ExecutionContext = {
102  waitUntil: vi.fn(),
103  passThroughOnException: vi.fn(),
104};
105 
106const response = await worker.fetch(
107  new Request('http://localhost/test'),
108  mockEnv,
109  mockCtx
110);
111```
112 
113## Binding Access Patterns
114 
115### Lazy Access
116 
117```typescript
118// ✅ Access only when needed
119if (url.pathname === '/cached') {
120  const cached = await env.MY_KV.get('data');
121  if (cached) return new Response(cached);
122}
123```
124 
125### Parallel Access
126 
127```typescript
128// ✅ Parallelize independent calls
129const [user, config, cache] = await Promise.all([
130  env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(userId).first(),
131  env.MY_KV.get('config'),
132  env.CACHE.get('data')
133]);
134```
135 
136## Storage Selection
137 
138### KV: CDN-Backed Reads
139 
140```typescript
141const config = await env.MY_KV.get('app-config', { type: 'json' });
142```
143 
144**Use when:** Read-heavy, <25MB, global distribution, eventual consistency OK  
145**Latency:** <10ms reads (cached), writes eventually consistent (60s)
146 
147### D1: Relational Queries
148 
149```typescript
150const results = await env.DB.prepare(`
151  SELECT u.name, COUNT(o.id) FROM users u
152  LEFT JOIN orders o ON u.id = o.user_id GROUP BY u.id
153`).all();
154```
155 
156**Use when:** Relational data, JOINs, ACID transactions  
157**Limits:** 10GB database size, 100k rows per query
158 
159### R2: Large Objects
160 
161```typescript
162const object = await env.MY_BUCKET.get('large-file.zip');
163return new Response(object.body);
164```
165 
166**Use when:** Files >25MB, S3-compatible API needed  
167**Limits:** 5TB per object, unlimited storage
168 
169### Durable Objects: Coordination
170 
171```typescript
172const id = env.COUNTER.idFromName('global');
173const stub = env.COUNTER.get(id);
174await stub.fetch(new Request('https://fake/increment'));
175```
176 
177**Use when:** Strong consistency, real-time coordination, WebSocket state  
178**Guarantees:** Single-threaded execution, transactional storage
179 
180## Anti-Patterns
181 
182**❌ Hardcoding credentials:** `const apiKey = 'sk_live_abc123'`  
183**✅** `npx wrangler secret put API_KEY`
184 
185**❌ Using REST API:** `fetch('https://api.cloudflare.com/.../kv/...')`  
186**✅** `env.MY_KV.get('key')`
187 
188**❌ Polling storage:** `setInterval(() => env.KV.get('config'), 1000)`  
189**✅** Use Durable Objects for real-time state
190 
191**❌ Large data in vars:** `{ "vars": { "HUGE_CONFIG": "..." } }` (5KB max)  
192**✅** `env.MY_KV.put('config', data)`
193 
194**❌ Caching env globally:** `const apiKey = env.API_KEY` outside fetch()  
195**✅** Access `env.API_KEY` per-request inside fetch()
196 
197## See Also
198 
199- [Service Bindings Docs](https://developers.cloudflare.com/workers/runtime-apis/bindings/service-bindings/)
200- [Miniflare Testing](https://miniflare.dev/)