TCP Sockets API Reference

TCP Sockets API Reference

Complete API reference for the Cloudflare Workers TCP Sockets API (cloudflare:sockets).

Core Function: connect()

function connect(
  address: SocketAddress,
  options?: SocketOptions
): Socket

Creates an outbound TCP connection to the specified address.

Parameters

SocketAddress

interface SocketAddress {
  hostname: string; // DNS hostname or IP address
  port: number;     // TCP port (1-65535, excluding blocked ports)
}

DNS names are resolved at connection time. IPv4, IPv6, and private IPs (10.x, 172.16.x, 192.168.x) supported.

SocketOptions

interface SocketOptions {
  secureTransport?: "off" | "on" | "starttls";
  allowHalfOpen?: boolean;
}

secureTransport modes:

allowHalfOpen: When false (default), closing read stream auto-closes write stream. When true, streams are independent.

Returns

A Socket object with readable/writable streams.

Socket Interface

interface Socket {
  // Streams
  readable: ReadableStream<Uint8Array>;
  writable: WritableStream<Uint8Array>;
  
  // Connection state
  opened: Promise<SocketInfo>;
  closed: Promise<void>;
  
  // Methods
  close(): Promise<void>;
  startTls(): Socket;
}

Properties

readable: ReadableStream<Uint8Array>

Stream for reading data from the socket. Use getReader() to consume data.

const reader = socket.readable.getReader();
const { done, value } = await reader.read(); // Read one chunk

writable: WritableStream<Uint8Array>

Stream for writing data to the socket. Use getWriter() to send data.

const writer = socket.writable.getWriter();
await writer.write(new TextEncoder().encode("HELLO\r\n"));
await writer.close();

opened: Promise<SocketInfo>

Promise that resolves when connection succeeds, rejects on failure.

interface SocketInfo {
  remoteAddress?: string; // May be undefined
  localAddress?: string;  // May be undefined
}

try {
  const info = await socket.opened;
} catch (error) {
  // Connection failed
}

closed: Promise<void>

Promise that resolves when socket is fully closed (both directions).

Methods

close(): Promise<void>

Closes the socket gracefully, waiting for pending writes to complete.

const socket = connect({ hostname: "api.internal", port: 443 });
try {
  // Use socket
} finally {
  await socket.close(); // Always call in finally block
}

startTls(): Socket

Upgrades connection to TLS. Only available when secureTransport: "starttls" was specified.

const socket = connect(
  { hostname: "db.internal", port: 5432 },
  { secureTransport: "starttls" }
);

// Send protocol-specific StartTLS command
const writer = socket.writable.getWriter();
await writer.write(new TextEncoder().encode("STARTTLS\r\n"));

// Upgrade to TLS - use returned socket, not original
const secureSocket = socket.startTls();
const secureWriter = secureSocket.writable.getWriter();

Complete Example

import { connect } from 'cloudflare:sockets';

export default {
  async fetch(req: Request): Promise<Response> {
    const socket = connect({ hostname: "echo.example.com", port: 7 }, { secureTransport: "on" });

    try {
      await socket.opened;
      
      const writer = socket.writable.getWriter();
      await writer.write(new TextEncoder().encode("Hello, TCP!\n"));
      await writer.close();

      const reader = socket.readable.getReader();
      const { value } = await reader.read();
      
      return new Response(value);
    } finally {
      await socket.close();
    }
  }
};

See patterns.md for multi-chunk reading, error handling, and protocol implementations.

Quick Reference

See Also

• patterns.md - Real-world protocol implementations
• configuration.md - Wrangler setup and environment variables
• gotchas.md - Limits and error handling