dotfiles/.agents/skills/cloudflare-deploy/references/workers-vpc/configuration.md

Configuration

Setup and configuration for TCP Sockets in Cloudflare Workers.

Wrangler Configuration

Basic Setup

TCP Sockets are available by default in Workers runtime. No special configuration required in wrangler.jsonc:

{
  "name": "private-network-worker",
  "main": "src/index.ts",
  "compatibility_date": "2025-01-01"
}

Environment Variables

Store connection details as env vars:

{
  "vars": { "DB_HOST": "10.0.1.50", "DB_PORT": "5432" }
}

interface Env { DB_HOST: string; DB_PORT: string; }

export default {
  async fetch(req: Request, env: Env): Promise<Response> {
    const socket = connect({ hostname: env.DB_HOST, port: parseInt(env.DB_PORT) });
  }
};

Per-Environment Configuration

{
  "vars": { "DB_HOST": "localhost" },
  "env": {
    "staging": { "vars": { "DB_HOST": "staging-db.internal.net" } },
    "production": { "vars": { "DB_HOST": "prod-db.internal.net" } }
  }
}

Deploy: wrangler deploy --env staging or wrangler deploy --env production

Integration with Cloudflare Tunnel

To connect Workers to private networks, combine TCP Sockets with Cloudflare Tunnel:

Worker (TCP Socket) → Tunnel hostname → cloudflared → Private Network

Quick Setup

1. Install cloudflared on a server inside your private network
2. Create tunnel: cloudflared tunnel create my-private-network
3. Configure routing in config.yml:

tunnel: <TUNNEL_ID>
credentials-file: /path/to/<TUNNEL_ID>.json
ingress:
  - hostname: db.internal.example.com
    service: tcp://10.0.1.50:5432
  - service: http_status:404  # Required catch-all

4. Run tunnel: cloudflared tunnel run my-private-network
5. Connect from Worker:

const socket = connect(
  { hostname: "db.internal.example.com", port: 5432 },  // Tunnel hostname
  { secureTransport: "on" }
);

For detailed Tunnel setup, see Tunnel configuration reference.

Smart Placement Integration

Reduce latency by auto-placing Workers near backends:

{ "placement": { "mode": "smart" } }

Workers automatically relocate closer to TCP socket destinations after observing connection latency. See Smart Placement reference.

Secrets Management

Store sensitive credentials as secrets (not in wrangler.jsonc):

wrangler secret put DB_PASSWORD  # Enter value when prompted

Access in Worker via env.DB_PASSWORD. Use in protocol handshake or authentication.

Local Development

Test with wrangler dev. Note: Local mode may not access private networks. Use public endpoints or mock servers for development:

const config = process.env.NODE_ENV === 'dev' 
  ? { hostname: 'localhost', port: 5432 }  // Mock
  : { hostname: 'db.internal.example.com', port: 5432 };  // Production

Connection String Patterns

Parse connection strings to extract host and port:

function parseConnectionString(connStr: string): SocketAddress {
  const url = new URL(connStr); // e.g., "postgres://10.0.1.50:5432/mydb"
  return { hostname: url.hostname, port: parseInt(url.port) || 5432 };
}

Hyperdrive Integration

For PostgreSQL/MySQL, prefer Hyperdrive over raw TCP sockets (includes connection pooling):

{ "hyperdrive": [{ "binding": "DB", "id": "<HYPERDRIVE_ID>" }] }

See Hyperdrive reference for complete setup.

Compatibility

TCP Sockets available in all modern Workers. Use current date: "compatibility_date": "2025-01-01". No special flags required.

Related Configuration

• Tunnel Configuration - Detailed cloudflared setup
• Smart Placement - Placement mode options
• Hyperdrive - Database connection pooling setup