# TCP Sockets API Reference

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

## Core Function: `connect()`

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

Creates an outbound TCP connection to the specified address.

### Parameters

#### `SocketAddress`

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

| Field      | Type     | Description           | Example                            |
| ---------- | -------- | --------------------- | ---------------------------------- |
| `hostname` | `string` | Target hostname or IP | `"db.internal.net"`, `"10.0.1.50"` |
| `port`     | `number` | TCP port number       | `5432`, `443`, `22`                |

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

#### `SocketOptions`

```typescript
interface SocketOptions {
  secureTransport?: 'off' | 'on' | 'starttls'
  allowHalfOpen?: boolean
}
```

| Field             | Type                          | Default | Description                   |
| ----------------- | ----------------------------- | ------- | ----------------------------- |
| `secureTransport` | `"off" \| "on" \| "starttls"` | `"off"` | TLS mode                      |
| `allowHalfOpen`   | `boolean`                     | `false` | Allow half-closed connections |

**`secureTransport` modes:**

| Mode         | Behavior                                     | Use Case                           |
| ------------ | -------------------------------------------- | ---------------------------------- |
| `"off"`      | Plain TCP, no encryption                     | Testing, internal trusted networks |
| `"on"`       | Immediate TLS handshake                      | HTTPS, secure databases, SSH       |
| `"starttls"` | Start plain, upgrade later with `startTls()` | Postgres, SMTP, IMAP               |

**`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

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
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

```typescript
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](./patterns.md) for multi-chunk reading, error handling, and protocol implementations.

## Quick Reference

| Task           | Code                                              |
| -------------- | ------------------------------------------------- |
| Import         | `import { connect } from 'cloudflare:sockets';`   |
| Connect        | `connect({ hostname: "host", port: 443 })`        |
| With TLS       | `connect(addr, { secureTransport: "on" })`        |
| StartTLS       | `socket.startTls()` after handshake               |
| Write          | `await writer.write(data); await writer.close();` |
| Read           | `const { value } = await reader.read();`          |
| Error handling | `try { await socket.opened; } catch { }`          |
| Always close   | `try { } finally { await socket.close(); }`       |

## See Also

- [patterns.md](./patterns.md) - Real-world protocol implementations
- [configuration.md](./configuration.md) - Wrangler setup and environment variables
- [gotchas.md](./gotchas.md) - Limits and error handling