1# Common Patterns
2 
3Real-world patterns and examples for TCP Sockets in Cloudflare Workers.
4 
5```typescript
6import { connect } from 'cloudflare:sockets';
7```
8 
9## Basic Patterns
10 
11### Simple Request-Response
12 
13```typescript
14const socket = connect({ hostname: "echo.example.com", port: 7 }, { secureTransport: "on" });
15try {
16  await socket.opened;
17  const writer = socket.writable.getWriter();
18  await writer.write(new TextEncoder().encode("Hello\n"));
19  await writer.close();
20  
21  const reader = socket.readable.getReader();
22  const { value } = await reader.read();
23  return new Response(value);
24} finally {
25  await socket.close();
26}
27```
28 
29### Reading All Data
30 
31```typescript
32async function readAll(socket: Socket): Promise<Uint8Array> {
33  const reader = socket.readable.getReader();
34  const chunks: Uint8Array[] = [];
35  while (true) {
36    const { done, value } = await reader.read();
37    if (done) break;
38    chunks.push(value);
39  }
40  const total = chunks.reduce((sum, c) => sum + c.length, 0);
41  const result = new Uint8Array(total);
42  let offset = 0;
43  for (const chunk of chunks) { result.set(chunk, offset); offset += chunk.length; }
44  return result;
45}
46```
47 
48### Streaming Response
49 
50```typescript
51// Stream socket data directly to HTTP response
52const socket = connect({ hostname: "stream.internal", port: 9000 }, { secureTransport: "on" });
53const writer = socket.writable.getWriter();
54await writer.write(new TextEncoder().encode("STREAM\n"));
55await writer.close();
56return new Response(socket.readable);
57```
58 
59## Protocol Examples
60 
61### Redis RESP
62 
63```typescript
64// Send: *2\r\n$3\r\nGET\r\n$<keylen>\r\n<key>\r\n
65// Recv: $<len>\r\n<data>\r\n or $-1\r\n for null
66const socket = connect({ hostname: "redis.internal", port: 6379 });
67const writer = socket.writable.getWriter();
68await writer.write(new TextEncoder().encode(`*2\r\n$3\r\nGET\r\n$3\r\nkey\r\n`));
69```
70 
71### PostgreSQL
72 
73**Use [Hyperdrive](../hyperdrive/) for production.** Raw Postgres protocol is complex (startup, auth, query messages).
74 
75### MQTT
76 
77```typescript
78const socket = connect({ hostname: "mqtt.broker", port: 1883 });
79const writer = socket.writable.getWriter();
80// CONNECT: 0x10 <len> 0x00 0x04 "MQTT" 0x04 <flags> ...
81// PUBLISH: 0x30 <len> <topic_len> <topic> <message>
82```
83 
84## Error Handling Patterns
85 
86### Retry with Backoff
87 
88```typescript
89async function connectWithRetry(addr: SocketAddress, opts: SocketOptions, maxRetries = 3): Promise<Socket> {
90  for (let i = 1; i <= maxRetries; i++) {
91    try {
92      const socket = connect(addr, opts);
93      await socket.opened;
94      return socket;
95    } catch (error) {
96      if (i === maxRetries) throw error;
97      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i - 1))); // Exponential backoff
98    }
99  }
100  throw new Error('Unreachable');
101}
102```
103 
104### Timeout
105 
106```typescript
107async function connectWithTimeout(addr: SocketAddress, opts: SocketOptions, ms = 5000): Promise<Socket> {
108  const socket = connect(addr, opts);
109  const timeout = new Promise<never>((_, reject) => setTimeout(() => reject(new Error('Timeout')), ms));
110  await Promise.race([socket.opened, timeout]);
111  return socket;
112}
113```
114 
115### Fallback
116 
117```typescript
118async function connectWithFallback(primary: string, fallback: string, port: number): Promise<Socket> {
119  try {
120    const socket = connect({ hostname: primary, port }, { secureTransport: "on" });
121    await socket.opened;
122    return socket;
123  } catch {
124    return connect({ hostname: fallback, port }, { secureTransport: "on" });
125  }
126}
127```
128 
129## Security Patterns
130 
131### Destination Allowlist (Prevent SSRF)
132 
133```typescript
134const ALLOWED_HOSTS = ['db.internal.company.net', 'api.internal.company.net', /^10\.0\.1\.\d+$/];
135 
136function isAllowed(hostname: string): boolean {
137  return ALLOWED_HOSTS.some(p => p instanceof RegExp ? p.test(hostname) : p === hostname);
138}
139 
140export default {
141  async fetch(req: Request): Promise<Response> {
142    const target = new URL(req.url).searchParams.get('host');
143    if (!target || !isAllowed(target)) return new Response('Forbidden', { status: 403 });
144    const socket = connect({ hostname: target, port: 443 });
145    // Use socket...
146  }
147};
148```
149 
150### Connection Pooling
151 
152```typescript
153class SocketPool {
154  private pool = new Map<string, Socket[]>();
155  
156  async acquire(hostname: string, port: number): Promise<Socket> {
157    const key = `${hostname}:${port}`;
158    const sockets = this.pool.get(key) || [];
159    if (sockets.length > 0) return sockets.pop()!;
160    const socket = connect({ hostname, port }, { secureTransport: "on" });
161    await socket.opened;
162    return socket;
163  }
164  
165  release(hostname: string, port: number, socket: Socket): void {
166    const key = `${hostname}:${port}`;
167    const sockets = this.pool.get(key) || [];
168    if (sockets.length < 3) { sockets.push(socket); this.pool.set(key, sockets); }
169    else socket.close();
170  }
171}
172```
173 
174## Multi-Protocol Gateway
175 
176```typescript
177interface Protocol { name: string; defaultPort: number; test(host: string, port: number): Promise<string>; }
178 
179const PROTOCOLS: Record<string, Protocol> = {
180  redis: {
181    name: 'redis',
182    defaultPort: 6379,
183    async test(host, port) {
184      const socket = connect({ hostname: host, port });
185      try {
186        const writer = socket.writable.getWriter();
187        await writer.write(new TextEncoder().encode('*1\r\n$4\r\nPING\r\n'));
188        writer.releaseLock();
189        const reader = socket.readable.getReader();
190        const { value } = await reader.read();
191        return new TextDecoder().decode(value || new Uint8Array());
192      } finally { await socket.close(); }
193    }
194  }
195};
196 
197export default {
198  async fetch(req: Request): Promise<Response> {
199    const url = new URL(req.url);
200    const proto = url.pathname.slice(1);  // /redis
201    const host = url.searchParams.get('host');
202    if (!host || !PROTOCOLS[proto]) return new Response('Invalid', { status: 400 });
203    const result = await PROTOCOLS[proto].test(host, parseInt(url.searchParams.get('port') || '') || PROTOCOLS[proto].defaultPort);
204    return new Response(result);
205  }
206};
207```
208 
209 
210