1# Workers Runtime APIs
2 
3## Fetch Handler
4 
5```typescript
6export default {
7  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
8    const url = new URL(request.url);
9    if (request.method === 'POST' && url.pathname === '/api') {
10      const body = await request.json();
11      return new Response(JSON.stringify({ id: 1 }), {
12        headers: { 'Content-Type': 'application/json' }
13      });
14    }
15    return fetch(request);  // Subrequest to origin
16  },
17};
18```
19 
20## Execution Context
21 
22```typescript
23ctx.waitUntil(logAnalytics(request));  // Background work, don't block response
24ctx.passThroughOnException();  // Failover to origin on error
25```
26 
27**Never** `await` background operations - use `ctx.waitUntil()`.
28 
29## Bindings
30 
31```typescript
32// KV
33await env.MY_KV.get('key');
34await env.MY_KV.put('key', 'value', { expirationTtl: 3600 });
35 
36// R2
37const obj = await env.MY_BUCKET.get('file.txt');
38await env.MY_BUCKET.put('file.txt', 'content');
39 
40// D1
41const result = await env.DB.prepare('SELECT * FROM users WHERE id = ?').bind(1).first();
42 
43// D1 Sessions (2024+) - read-after-write consistency
44const session = env.DB.withSession();
45await session.prepare('INSERT INTO users (name) VALUES (?)').bind('Alice').run();
46const user = await session.prepare('SELECT * FROM users WHERE name = ?').bind('Alice').first(); // Guaranteed fresh
47 
48// Queues
49await env.MY_QUEUE.send({ timestamp: Date.now() });
50 
51// Secrets/vars
52const key = env.API_KEY;
53```
54 
55## Cache API
56 
57```typescript
58const cache = caches.default;
59let response = await cache.match(request);
60 
61if (!response) {
62  response = await fetch(request);
63  response = new Response(response.body, response);
64  response.headers.set('Cache-Control', 'max-age=3600');
65  ctx.waitUntil(cache.put(request, response.clone()));  // Clone before caching
66}
67```
68 
69## HTMLRewriter
70 
71```typescript
72return new HTMLRewriter()
73  .on('a[href]', {
74    element(el) {
75      const href = el.getAttribute('href');
76      if (href?.startsWith('http://')) {
77        el.setAttribute('href', href.replace('http://', 'https://'));
78      }
79    }
80  })
81  .transform(response);
82```
83 
84**Use cases**: A/B testing, analytics injection, link rewriting
85 
86## WebSockets
87 
88### Standard WebSocket
89 
90```typescript
91const [client, server] = Object.values(new WebSocketPair());
92 
93server.accept();
94server.addEventListener('message', event => {
95  server.send(`Echo: ${event.data}`);
96});
97 
98return new Response(null, { status: 101, webSocket: client });
99```
100 
101### WebSocket Hibernation (Recommended for idle connections)
102 
103```typescript
104// In Durable Object
105export class WebSocketDO {
106  async webSocketMessage(ws: WebSocket, message: string) {
107    ws.send(`Echo: ${message}`);
108  }
109  
110  async webSocketClose(ws: WebSocket, code: number, reason: string) {
111    // Cleanup on close
112  }
113  
114  async webSocketError(ws: WebSocket, error: Error) {
115    console.error('WebSocket error:', error);
116  }
117}
118```
119 
120Hibernation automatically suspends inactive connections (no CPU cost), wakes on events
121 
122## Durable Objects
123 
124### RPC Pattern (Recommended 2024+)
125 
126```typescript
127export class Counter {
128  private value = 0;
129  
130  constructor(private state: DurableObjectState) {
131    state.blockConcurrencyWhile(async () => {
132      this.value = (await state.storage.get('value')) || 0;
133    });
134  }
135  
136  // Export methods directly - called via RPC (type-safe, zero serialization)
137  async increment(): Promise<number> {
138    this.value++;
139    await this.state.storage.put('value', this.value);
140    return this.value;
141  }
142  
143  async getValue(): Promise<number> {
144    return this.value;
145  }
146}
147 
148// Worker usage:
149const stub = env.COUNTER.get(env.COUNTER.idFromName('global'));
150const count = await stub.increment(); // Direct method call, full type safety
151```
152 
153### Legacy Fetch Pattern (Pre-2024)
154 
155```typescript
156async fetch(request: Request): Promise<Response> {
157  const url = new URL(request.url);
158  if (url.pathname === '/increment') {
159    await this.state.storage.put('value', ++this.value);
160  }
161  return new Response(String(this.value));
162}
163// Usage: await stub.fetch('http://x/increment')
164```
165 
166**When to use DOs**: Real-time collaboration, rate limiting, strongly consistent state
167 
168## Other Handlers
169 
170```typescript
171// Cron: async scheduled(event, env, ctx) { ctx.waitUntil(doCleanup(env)); }
172// Queue: async queue(batch) { for (const msg of batch.messages) { await process(msg.body); msg.ack(); } }
173// Tail: async tail(events, env) { for (const e of events) if (e.outcome === 'exception') await log(e); }
174```
175 
176## Service Bindings
177 
178```typescript
179// Worker-to-worker RPC (zero latency, no internet round-trip)
180return env.SERVICE_B.fetch(request);
181 
182// With RPC (2024+) - same as Durable Objects RPC
183export class ServiceWorker {
184  async getData() { return { data: 'value' }; }
185}
186// Usage: const data = await env.SERVICE_B.getData();
187```
188 
189**Benefits**: Type-safe method calls, no HTTP overhead, share code between Workers
190 
191## See Also
192 
193- [Configuration](./configuration.md) - Binding setup
194- [Patterns](./patterns.md) - Common workflows
195- [KV](../kv/README.md), [D1](../d1/README.md), [R2](../r2/README.md), [Durable Objects](../durable-objects/README.md), [Queues](../queues/README.md)
196