# TURN Implementation Patterns

Production-ready patterns for implementing Cloudflare TURN in WebRTC applications.

## Prerequisites

Before implementing these patterns, ensure you have:

- TURN key created: see [api.md#create-turn-key](./api.md#create-turn-key)
- Worker configured: see [configuration.md#cloudflare-worker-integration](./configuration.md#cloudflare-worker-integration)

## Basic TURN Configuration (Browser)

```typescript
interface RTCIceServer {
  urls: string | string[]
  username?: string
  credential?: string
  credentialType?: 'password' | 'oauth'
}

async function getTURNConfig(): Promise<RTCIceServer[]> {
  const response = await fetch('/api/turn-credentials')
  const data = await response.json()

  return [
    {
      urls: 'stun:stun.cloudflare.com:3478',
    },
    {
      urls: [
        'turn:turn.cloudflare.com:3478?transport=udp',
        'turn:turn.cloudflare.com:3478?transport=tcp',
        'turns:turn.cloudflare.com:5349?transport=tcp',
        'turns:turn.cloudflare.com:443?transport=tcp',
      ],
      username: data.username,
      credential: data.credential,
      credentialType: 'password',
    },
  ]
}

// Use in RTCPeerConnection
const iceServers = await getTURNConfig()
const peerConnection = new RTCPeerConnection({ iceServers })
```

## Port Selection Strategy

Recommended order for browser clients:

1. **3478/udp** (primary, lowest latency)
2. **3478/tcp** (fallback for UDP-blocked networks)
3. **5349/tls** (corporate firewalls, most reliable)
4. **443/tls** (alternate TLS port, firewall-friendly)

**Avoid port 53**—blocked by Chrome and Firefox.

```typescript
function filterICEServersForBrowser(urls: string[]): string[] {
  return urls
    .filter((url) => !url.includes(':53')) // Remove port 53
    .sort((a, b) => {
      // Prioritize UDP over TCP over TLS
      if (a.includes('transport=udp')) return -1
      if (b.includes('transport=udp')) return 1
      if (a.includes('transport=tcp') && !a.startsWith('turns:')) return -1
      if (b.includes('transport=tcp') && !b.startsWith('turns:')) return 1
      return 0
    })
}
```

## Credential Refresh (Mid-Session)

When credentials expire during long calls:

```typescript
async function refreshTURNCredentials(pc: RTCPeerConnection): Promise<void> {
  const newCreds = await fetch('/turn-credentials').then((r) => r.json())
  const config = pc.getConfiguration()
  config.iceServers = newCreds.iceServers
  pc.setConfiguration(config)
  // Note: setConfiguration() does NOT trigger ICE restart
  // Combine with restartIce() if connection fails
}

// Auto-refresh before expiry
setInterval(async () => {
  await refreshTURNCredentials(peerConnection)
}, 3000000) // 50 minutes if TTL is 1 hour
```

## ICE Restart Pattern

After network change, TURN server maintenance, or credential expiry:

```typescript
pc.addEventListener('iceconnectionstatechange', async () => {
  if (pc.iceConnectionState === 'failed') {
    console.warn('ICE connection failed, restarting...')

    // Refresh credentials
    await refreshTURNCredentials(pc)

    // Trigger ICE restart
    pc.restartIce()
    const offer = await pc.createOffer({ iceRestart: true })
    await pc.setLocalDescription(offer)

    // Send offer to peer via signaling channel...
  }
})
```

## Credentials Caching Pattern

```typescript
class TURNCredentialsManager {
  private creds: {
    username: string
    credential: string
    urls: string[]
    expiresAt: number
  } | null = null

  async getCredentials(keyId: string, keySecret: string): Promise<RTCIceServer[]> {
    const now = Date.now()

    if (this.creds && this.creds.expiresAt > now) {
      return this.buildIceServers(this.creds)
    }

    const ttl = 3600
    if (ttl > 172800) throw new Error('TTL max 48hrs')

    const res = await fetch(
      `https://rtc.live.cloudflare.com/v1/turn/keys/${keyId}/credentials/generate`,
      {
        method: 'POST',
        headers: { Authorization: `Bearer ${keySecret}`, 'Content-Type': 'application/json' },
        body: JSON.stringify({ ttl }),
      }
    )

    const data = await res.json()
    const filteredUrls = data.iceServers.urls.filter((url: string) => !url.includes(':53'))

    this.creds = {
      username: data.iceServers.username,
      credential: data.iceServers.credential,
      urls: filteredUrls,
      expiresAt: now + ttl * 1000 - 60000,
    }

    return this.buildIceServers(this.creds)
  }

  private buildIceServers(c: {
    username: string
    credential: string
    urls: string[]
  }): RTCIceServer[] {
    return [
      { urls: 'stun:stun.cloudflare.com:3478' },
      {
        urls: c.urls,
        username: c.username,
        credential: c.credential,
        credentialType: 'password' as const,
      },
    ]
  }
}
```

## Common Use Cases

```typescript
// Video conferencing: TURN as fallback
const config = { iceServers: await getTURNConfig(), iceTransportPolicy: 'all' }

// IoT/predictable connectivity: force TURN
const config = { iceServers: await getTURNConfig(), iceTransportPolicy: 'relay' }

// Screen sharing: reduce overhead
const pc = new RTCPeerConnection({ iceServers: await getTURNConfig(), bundlePolicy: 'max-bundle' })
```

## Integration with Cloudflare Calls SFU

```typescript
// TURN is automatically used when needed
// Cloudflare Calls handles TURN + SFU coordination
const session = await callsClient.createSession({
  appId: 'your-app-id',
  sessionId: 'meeting-123',
})
```

## Debugging ICE Connectivity

```typescript
pc.addEventListener('icecandidate', (event) => {
  if (event.candidate) {
    console.log('ICE candidate:', event.candidate.type, event.candidate.protocol)
  }
})

pc.addEventListener('iceconnectionstatechange', () => {
  console.log('ICE state:', pc.iceConnectionState)
})

// Check selected candidate pair
const stats = await pc.getStats()
stats.forEach((report) => {
  if (report.type === 'candidate-pair' && report.selected) {
    console.log('Selected:', report)
  }
})
```

## See Also

- [api.md](./api.md) - Credential generation API, types
- [configuration.md](./configuration.md) - Worker setup, environment variables
- [gotchas.md](./gotchas.md) - Common mistakes, troubleshooting