1## Routing Patterns
2 
3### Session Affinity (Stateful)
4 
5```typescript
6export class SessionBackend extends Container {
7  defaultPort = 3000;
8  sleepAfter = "30m";
9}
10 
11export default {
12  async fetch(request: Request, env: Env) {
13    const sessionId = request.headers.get("X-Session-ID") || crypto.randomUUID();
14    const container = env.SESSION_BACKEND.getByName(sessionId);
15    await container.startAndWaitForPorts();
16    return container.fetch(request);
17  }
18};
19```
20 
21**Use:** User sessions, WebSocket, stateful games, per-user caching.
22 
23### Load Balancing (Stateless)
24 
25```typescript
26export default {
27  async fetch(request: Request, env: Env) {
28    const container = env.STATELESS_API.getRandom();
29    await container.startAndWaitForPorts();
30    return container.fetch(request);
31  }
32};
33```
34 
35**Use:** Stateless HTTP APIs, CPU-intensive work, read-only queries.
36 
37### Singleton Pattern
38 
39```typescript
40export default {
41  async fetch(request: Request, env: Env) {
42    const container = env.GLOBAL_SERVICE.getByName("singleton");
43    await container.startAndWaitForPorts();
44    return container.fetch(request);
45  }
46};
47```
48 
49**Use:** Global cache, centralized coordinator, single source of truth.
50 
51## WebSocket Forwarding
52 
53```typescript
54export default {
55  async fetch(request: Request, env: Env) {
56    if (request.headers.get("Upgrade") === "websocket") {
57      const sessionId = request.headers.get("X-Session-ID") || crypto.randomUUID();
58      const container = env.WS_BACKEND.getByName(sessionId);
59      await container.startAndWaitForPorts();
60      
61      // ⚠️ MUST use fetch(), not containerFetch()
62      return container.fetch(request);
63    }
64    return new Response("Not a WebSocket request", { status: 400 });
65  }
66};
67```
68 
69**⚠️ Critical:** Always use `fetch()` for WebSocket.
70 
71## Graceful Shutdown
72 
73```typescript
74export class GracefulContainer extends Container {
75  private connections = new Set<WebSocket>();
76 
77  onStop() {
78    // SIGTERM received, 15 minutes until SIGKILL
79    for (const ws of this.connections) {
80      ws.close(1001, "Server shutting down");
81    }
82    this.ctx.storage.put("shutdown-time", Date.now());
83  }
84 
85  onActivityExpired(): boolean {
86    return this.connections.size > 0;  // Keep alive if connections
87  }
88}
89```
90 
91## Concurrent Request Handling
92 
93```typescript
94export class SafeContainer extends Container {
95  private initialized = false;
96 
97  async fetch(request: Request) {
98    await this.ctx.blockConcurrencyWhile(async () => {
99      if (!this.initialized) {
100        await this.startAndWaitForPorts();
101        this.initialized = true;
102      }
103    });
104    return super.fetch(request);
105  }
106}
107```
108 
109**Use:** One-time initialization, preventing concurrent startup.
110 
111## Activity Timeout Renewal
112 
113```typescript
114export class LongRunningContainer extends Container {
115  sleepAfter = "5m";
116 
117  async processLongJob(data: unknown) {
118    const interval = setInterval(() => {
119      this.ctx.storage.put("keepalive", Date.now());
120    }, 60000);
121 
122    try {
123      await this.doLongWork(data);
124    } finally {
125      clearInterval(interval);
126    }
127  }
128}
129```
130 
131**Use:** Long operations exceeding `sleepAfter`.
132 
133## Multiple Port Routing
134 
135```typescript
136export class MultiPortContainer extends Container {
137  requiredPorts = [8080, 8081, 9090];
138 
139  async fetch(request: Request) {
140    const path = new URL(request.url).pathname;
141    if (path.startsWith("/grpc")) this.switchPort(8081);
142    else if (path.startsWith("/metrics")) this.switchPort(9090);
143    return super.fetch(request);
144  }
145}
146```
147 
148**Use:** Multi-protocol services (HTTP + gRPC), separate metrics endpoints.
149 
150## Workflow Integration
151 
152```typescript
153import { WorkflowEntrypoint } from "cloudflare:workers";
154 
155export class ProcessingWorkflow extends WorkflowEntrypoint {
156  async run(event, step) {
157    const container = this.env.PROCESSOR.getByName(event.payload.jobId);
158    
159    await step.do("start", async () => {
160      await container.startAndWaitForPorts();
161    });
162    
163    const result = await step.do("process", async () => {
164      return container.fetch("/process", {
165        method: "POST",
166        body: JSON.stringify(event.payload.data)
167      }).then(r => r.json());
168    });
169    
170    return result;
171  }
172}
173```
174 
175**Use:** Orchestrating multi-step container operations, durable execution.
176 
177## Queue Consumer Integration
178 
179```typescript
180export default {
181  async queue(batch, env) {
182    for (const msg of batch.messages) {
183      try {
184        const container = env.PROCESSOR.getByName(msg.body.jobId);
185        await container.startAndWaitForPorts();
186        
187        const response = await container.fetch("/process", {
188          method: "POST",
189          body: JSON.stringify(msg.body)
190        });
191        
192        response.ok ? msg.ack() : msg.retry();
193      } catch (err) {
194        console.error("Queue processing error:", err);
195        msg.retry();
196      }
197    }
198  }
199};
200```
201 
202**Use:** Asynchronous job processing, batch operations, event-driven execution.
203