1# TURN Implementation Patterns
2 
3Production-ready patterns for implementing Cloudflare TURN in WebRTC applications.
4 
5## Prerequisites
6 
7Before implementing these patterns, ensure you have:
8- TURN key created: see [api.md#create-turn-key](./api.md#create-turn-key)
9- Worker configured: see [configuration.md#cloudflare-worker-integration](./configuration.md#cloudflare-worker-integration)
10 
11## Basic TURN Configuration (Browser)
12 
13```typescript
14interface RTCIceServer {
15  urls: string | string[];
16  username?: string;
17  credential?: string;
18  credentialType?: "password" | "oauth";
19}
20 
21async function getTURNConfig(): Promise<RTCIceServer[]> {
22  const response = await fetch('/api/turn-credentials');
23  const data = await response.json();
24  
25  return [
26    {
27      urls: 'stun:stun.cloudflare.com:3478'
28    },
29    {
30      urls: [
31        'turn:turn.cloudflare.com:3478?transport=udp',
32        'turn:turn.cloudflare.com:3478?transport=tcp',
33        'turns:turn.cloudflare.com:5349?transport=tcp',
34        'turns:turn.cloudflare.com:443?transport=tcp'
35      ],
36      username: data.username,
37      credential: data.credential,
38      credentialType: 'password'
39    }
40  ];
41}
42 
43// Use in RTCPeerConnection
44const iceServers = await getTURNConfig();
45const peerConnection = new RTCPeerConnection({ iceServers });
46```
47 
48## Port Selection Strategy
49 
50Recommended order for browser clients:
51 
521. **3478/udp** (primary, lowest latency)
532. **3478/tcp** (fallback for UDP-blocked networks)
543. **5349/tls** (corporate firewalls, most reliable)
554. **443/tls** (alternate TLS port, firewall-friendly)
56 
57**Avoid port 53**—blocked by Chrome and Firefox.
58 
59```typescript
60function filterICEServersForBrowser(urls: string[]): string[] {
61  return urls
62    .filter(url => !url.includes(':53'))  // Remove port 53
63    .sort((a, b) => {
64      // Prioritize UDP over TCP over TLS
65      if (a.includes('transport=udp')) return -1;
66      if (b.includes('transport=udp')) return 1;
67      if (a.includes('transport=tcp') && !a.startsWith('turns:')) return -1;
68      if (b.includes('transport=tcp') && !b.startsWith('turns:')) return 1;
69      return 0;
70    });
71}
72```
73 
74## Credential Refresh (Mid-Session)
75 
76When credentials expire during long calls:
77 
78```typescript
79async function refreshTURNCredentials(pc: RTCPeerConnection): Promise<void> {
80  const newCreds = await fetch('/turn-credentials').then(r => r.json());
81  const config = pc.getConfiguration();
82  config.iceServers = newCreds.iceServers;
83  pc.setConfiguration(config);
84  // Note: setConfiguration() does NOT trigger ICE restart
85  // Combine with restartIce() if connection fails
86}
87 
88// Auto-refresh before expiry
89setInterval(async () => {
90  await refreshTURNCredentials(peerConnection);
91}, 3000000);  // 50 minutes if TTL is 1 hour
92```
93 
94## ICE Restart Pattern
95 
96After network change, TURN server maintenance, or credential expiry:
97 
98```typescript
99pc.addEventListener('iceconnectionstatechange', async () => {
100  if (pc.iceConnectionState === 'failed') {
101    console.warn('ICE connection failed, restarting...');
102    
103    // Refresh credentials
104    await refreshTURNCredentials(pc);
105    
106    // Trigger ICE restart
107    pc.restartIce();
108    const offer = await pc.createOffer({ iceRestart: true });
109    await pc.setLocalDescription(offer);
110    
111    // Send offer to peer via signaling channel...
112  }
113});
114```
115 
116## Credentials Caching Pattern
117 
118```typescript
119class TURNCredentialsManager {
120  private creds: { username: string; credential: string; urls: string[]; expiresAt: number; } | null = null;
121 
122  async getCredentials(keyId: string, keySecret: string): Promise<RTCIceServer[]> {
123    const now = Date.now();
124    
125    if (this.creds && this.creds.expiresAt > now) {
126      return this.buildIceServers(this.creds);
127    }
128 
129    const ttl = 3600;
130    if (ttl > 172800) throw new Error('TTL max 48hrs');
131 
132    const res = await fetch(
133      `https://rtc.live.cloudflare.com/v1/turn/keys/${keyId}/credentials/generate`,
134      {
135        method: 'POST',
136        headers: { 'Authorization': `Bearer ${keySecret}`, 'Content-Type': 'application/json' },
137        body: JSON.stringify({ ttl })
138      }
139    );
140 
141    const data = await res.json();
142    const filteredUrls = data.iceServers.urls.filter((url: string) => !url.includes(':53'));
143 
144    this.creds = {
145      username: data.iceServers.username,
146      credential: data.iceServers.credential,
147      urls: filteredUrls,
148      expiresAt: now + (ttl * 1000) - 60000
149    };
150 
151    return this.buildIceServers(this.creds);
152  }
153 
154  private buildIceServers(c: { username: string; credential: string; urls: string[] }): RTCIceServer[] {
155    return [
156      { urls: 'stun:stun.cloudflare.com:3478' },
157      { urls: c.urls, username: c.username, credential: c.credential, credentialType: 'password' as const }
158    ];
159  }
160}
161```
162 
163## Common Use Cases
164 
165```typescript
166// Video conferencing: TURN as fallback
167const config = { iceServers: await getTURNConfig(), iceTransportPolicy: 'all' };
168 
169// IoT/predictable connectivity: force TURN
170const config = { iceServers: await getTURNConfig(), iceTransportPolicy: 'relay' };
171 
172// Screen sharing: reduce overhead
173const pc = new RTCPeerConnection({ iceServers: await getTURNConfig(), bundlePolicy: 'max-bundle' });
174```
175 
176## Integration with Cloudflare Calls SFU
177 
178```typescript
179// TURN is automatically used when needed
180// Cloudflare Calls handles TURN + SFU coordination
181const session = await callsClient.createSession({
182  appId: 'your-app-id',
183  sessionId: 'meeting-123'
184});
185```
186 
187## Debugging ICE Connectivity
188 
189```typescript
190pc.addEventListener('icecandidate', (event) => {
191  if (event.candidate) {
192    console.log('ICE candidate:', event.candidate.type, event.candidate.protocol);
193  }
194});
195 
196pc.addEventListener('iceconnectionstatechange', () => {
197  console.log('ICE state:', pc.iceConnectionState);
198});
199 
200// Check selected candidate pair
201const stats = await pc.getStats();
202stats.forEach(report => {
203  if (report.type === 'candidate-pair' && report.selected) {
204    console.log('Selected:', report);
205  }
206});
207```
208 
209## See Also
210 
211- [api.md](./api.md) - Credential generation API, types
212- [configuration.md](./configuration.md) - Worker setup, environment variables
213- [gotchas.md](./gotchas.md) - Common mistakes, troubleshooting
214