0
# Transport Configuration
1

2
SockJS-client uses an intelligent transport fallback system that automatically selects the best available communication method based on browser capabilities, network environment, and user configuration. It supports 11+ different transport protocols ranging from native WebSockets to JSONP polling.
3

4
## Capabilities
5

6
### Transport Selection and Fallback
7

8
The transport system attempts to use the most efficient protocol available, falling back to alternatives when necessary.
9

10
```javascript { .api }
11
/**
12
 * Available transport types in priority order
13
 */
14
const availableTransports = [
15
  'websocket',           // Native WebSocket (fastest)
16
  'xhr-streaming',       // XHR with streaming
17
  'xdr-streaming',       // XDomainRequest streaming (IE8-9)
18
  'eventsource',         // Server-Sent Events
19
  'iframe-eventsource',  // EventSource via iframe
20
  'htmlfile',            // HtmlFile transport (IE)
21
  'iframe-htmlfile',     // HtmlFile via iframe
22
  'xhr-polling',         // XHR long-polling
23
  'xdr-polling',         // XDomainRequest polling (IE8-9)
24
  'iframe-xhr-polling',  // XHR polling via iframe
25
  'jsonp-polling'        // JSONP polling (slowest, widest compatibility)
26
];
27

28
/**
29
 * Constructor options for transport configuration
30
 */
31
interface SockJSOptions {
32
  /** Transport whitelist - restrict allowed transports */
33
  transports?: string | string[];
34
  
35
  /** Transport-specific configuration options */
36
  transportOptions?: {
37
    [transportName: string]: any;
38
  };
39
  
40
  /** Minimum timeout for transport connections (ms) */
41
  timeout?: number;
42
}
43
```
44

45
**Basic Transport Configuration:**
46

47
```javascript
48
// Allow all transports (default behavior)
49
const sock1 = new SockJS('https://example.com/sockjs');
50

51
// Restrict to WebSocket and XHR only
52
const sock2 = new SockJS('https://example.com/sockjs', null, {
53
  transports: ['websocket', 'xhr-streaming', 'xhr-polling']
54
});
55

56
// Allow only polling transports (for restrictive firewalls)
57
const sock3 = new SockJS('https://example.com/sockjs', null, {
58
  transports: ['xhr-polling', 'jsonp-polling']
59
});
60

61
// Force specific transport for testing
62
const sock4 = new SockJS('https://example.com/sockjs', null, {
63
  transports: 'websocket'  // String or array
64
});
65
```
66

67
### Transport-Specific Options
68

69
Individual transport protocols can be configured with specific parameters.
70

71
```javascript { .api }
72
/**
73
 * Transport-specific configuration options
74
 */
75
interface TransportOptions {
76
  /** WebSocket transport options */
77
  'websocket'?: {
78
    heartbeat?: number;     // Heartbeat interval (ms)
79
    timeout?: number;       // Connection timeout (ms)
80
  };
81
  
82
  /** XHR-based transport options */
83
  'xhr-streaming'?: {
84
    timeout?: number;       // Request timeout (ms)
85
    withCredentials?: boolean; // Include credentials
86
  };
87
  
88
  'xhr-polling'?: {
89
    timeout?: number;       // Request timeout (ms)
90
    withCredentials?: boolean; // Include credentials
91
  };
92
  
93
  /** EventSource transport options */
94
  'eventsource'?: {
95
    timeout?: number;       // Connection timeout (ms)
96
  };
97
  
98
  /** JSONP transport options */
99
  'jsonp-polling'?: {
100
    timeout?: number;       // Request timeout (ms)
101
    callbackName?: string;  // Custom callback name
102
  };
103
}
104
```
105

106
**Transport Options Usage:**
107

108
```javascript
109
const sock = new SockJS('https://example.com/sockjs', null, {
110
  transports: ['websocket', 'xhr-streaming', 'xhr-polling'],
111
  transportOptions: {
112
    'websocket': {
113
      heartbeat: 30000,     // 30 second heartbeat
114
      timeout: 10000        // 10 second connection timeout
115
    },
116
    'xhr-streaming': {
117
      timeout: 15000,       // 15 second request timeout
118
      withCredentials: true // Include cookies
119
    },
120
    'xhr-polling': {
121
      timeout: 5000,        // 5 second polling timeout
122
      withCredentials: true
123
    }
124
  }
125
});
126
```
127

128
### Timeout Configuration
129

130
Configure connection and transport timeouts for different network conditions.
131

132
```javascript { .api }
133
/**
134
 * Timeout configuration options
135
 */
136
interface TimeoutOptions {
137
  /** 
138
   * Minimum timeout for transport connections (milliseconds)
139
   * Default: Calculated dynamically based on RTT
140
   * Range: Typically 300ms to several seconds
141
   */
142
  timeout?: number;
143
}
144

145
/**
146
 * Internal timeout calculation (for reference)
147
 * - If RTT > 100ms: timeout = 4 * RTT (minimum 400ms)
148
 * - If RTT <= 100ms: timeout = 300ms + RTT
149
 * - User-specified timeout establishes minimum value
150
 */
151
```
152

153
**Timeout Configuration Examples:**
154

155
```javascript
156
// Use default timeout calculation
157
const sock1 = new SockJS('https://example.com/sockjs');
158

159
// Set minimum timeout of 10 seconds
160
const sock2 = new SockJS('https://example.com/sockjs', null, {
161
  timeout: 10000
162
});
163

164
// Very aggressive timeout for fast networks
165
const sock3 = new SockJS('https://example.com/sockjs', null, {
166
  timeout: 1000,
167
  transports: ['websocket', 'xhr-streaming']
168
});
169

170
// Conservative timeout for slow/unreliable networks
171
const sock4 = new SockJS('https://example.com/sockjs', null, {
172
  timeout: 30000,
173
  transports: ['xhr-polling', 'jsonp-polling']
174
});
175
```
176

177
## Transport Types and Characteristics
178

179
Detailed information about each transport type and when they are used.
180

181
### Streaming Transports
182

183
High-performance transports that maintain persistent connections for real-time communication.
184

185
```javascript { .api }
186
/**
187
 * Streaming transport characteristics
188
 */
189
const streamingTransports = {
190
  'websocket': {
191
    description: 'Native WebSocket protocol (RFC 6455)',
192
    pros: ['Lowest latency', 'Bidirectional', 'Full-duplex', 'Standard protocol'],
193
    cons: ['Blocked by some proxies', 'Not supported in old browsers'],
194
    browserSupport: 'IE 10+, Chrome 14+, Firefox 10+, Safari 6+',
195
    fallback: 'xhr-streaming'
196
  },
197
  
198
  'xhr-streaming': {
199
    description: 'XMLHttpRequest with streaming response',
200
    pros: ['Good performance', 'Wide browser support', 'Works through most proxies'],
201
    cons: ['HTTP overhead', 'Unidirectional', 'Browser connection limits'],
202
    browserSupport: 'IE 10+, All modern browsers',
203
    fallback: 'xhr-polling'
204
  },
205
  
206
  'xdr-streaming': {
207
    description: 'XDomainRequest streaming (IE 8-9 only)',
208
    pros: ['Cross-domain support in IE 8-9', 'Streaming capability'],
209
    cons: ['IE-specific', 'No cookies', 'Limited headers'],
210
    browserSupport: 'IE 8-9 only',
211
    fallback: 'iframe-htmlfile'
212
  },
213
  
214
  'eventsource': {
215
    description: 'Server-Sent Events (HTML5)',
216
    pros: ['Built-in reconnection', 'Standard protocol', 'Event-based'],
217
    cons: ['Unidirectional only', 'Browser connection limits'],
218
    browserSupport: 'IE 10+, All modern browsers (not IE 8-9)',
219
    fallback: 'xhr-streaming'
220
  }
221
};
222
```
223

224
### Polling Transports
225

226
Fallback transports that simulate real-time communication through periodic requests.
227

228
```javascript { .api }
229
/**
230
 * Polling transport characteristics
231
 */
232
const pollingTransports = {
233
  'xhr-polling': {
234
    description: 'XMLHttpRequest long-polling',
235
    pros: ['Reliable', 'Works through proxies', 'Good browser support'],
236
    cons: ['Higher latency', 'More server resources', 'HTTP overhead'],
237
    browserSupport: 'IE 10+, All modern browsers',
238
    fallback: 'jsonp-polling'
239
  },
240
  
241
  'xdr-polling': {
242
    description: 'XDomainRequest polling (IE 8-9)',
243
    pros: ['Cross-domain in IE 8-9', 'Reliable'],
244
    cons: ['IE-specific', 'No cookies', 'Higher latency'],
245
    browserSupport: 'IE 8-9 only',
246
    fallback: 'iframe-xhr-polling'
247
  },
248
  
249
  'jsonp-polling': {
250
    description: 'JSONP polling for maximum compatibility',
251
    pros: ['Universal browser support', 'Works around CORS issues'],
252
    cons: ['Highest latency', 'Most overhead', 'Shows loading indicator'],
253
    browserSupport: 'All browsers including IE 6-7',
254
    fallback: 'Connection failure'
255
  }
256
};
257
```
258

259
### Iframe-Based Transports
260

261
Specialized transports that use iframes to work around browser limitations.
262

263
```javascript { .api }
264
/**
265
 * Iframe transport characteristics
266
 */
267
const iframeTransports = {
268
  'iframe-eventsource': {
269
    description: 'EventSource running in iframe with postMessage',
270
    pros: ['Cross-domain capability', 'Streaming', 'Cookie support'],
271
    cons: ['Complex setup', 'iframe overhead', 'Limited to specific scenarios'],
272
    browserSupport: 'Browsers supporting postMessage and EventSource',
273
    fallback: 'iframe-xhr-polling'
274
  },
275
  
276
  'iframe-htmlfile': {
277
    description: 'HtmlFile transport via iframe (IE specific)',
278
    pros: ['Persistent connection in IE', 'Cookie support'],
279
    cons: ['IE-specific', 'Complex implementation', 'iframe overhead'],
280
    browserSupport: 'IE 8-9 primarily',
281
    fallback: 'iframe-xhr-polling'
282
  },
283
  
284
  'iframe-xhr-polling': {
285
    description: 'XHR polling in iframe with postMessage',
286
    pros: ['Cross-domain support', 'Cookie support', 'Wide compatibility'],
287
    cons: ['Higher overhead', 'iframe complexity', 'Polling latency'],
288
    browserSupport: 'Browsers supporting postMessage',
289
    fallback: 'jsonp-polling'
290
  }
291
};
292
```
293

294
## Browser-Specific Transport Selection
295

296
Understanding which transports are selected based on browser capabilities and environment.
297

298
### Desktop Browser Support
299

300
```javascript { .api }
301
/**
302
 * Transport selection by browser (modern versions)
303
 */
304
const desktopBrowserTransports = {
305
  'Chrome 14+': ['websocket', 'xhr-streaming', 'xhr-polling'],
306
  'Firefox 10+': ['websocket', 'xhr-streaming', 'xhr-polling'], 
307
  'Safari 6+': ['websocket', 'xhr-streaming', 'xhr-polling'],
308
  'Edge': ['websocket', 'xhr-streaming', 'xhr-polling'],
309
  'IE 11': ['websocket', 'xhr-streaming', 'xhr-polling'],
310
  'IE 10': ['websocket', 'xhr-streaming', 'xhr-polling'],
311
  'IE 8-9 (same domain)': ['xdr-streaming', 'xdr-polling'],
312
  'IE 8-9 (cross domain)': ['iframe-htmlfile', 'iframe-xhr-polling'],
313
  'IE 6-7': ['jsonp-polling']
314
};
315
```
316

317
### Mobile Browser Support
318

319
```javascript { .api }
320
/**
321
 * Transport selection for mobile browsers
322
 */
323
const mobileBrowserTransports = {
324
  'iOS Safari': ['websocket', 'xhr-streaming', 'xhr-polling'],
325
  'Android Chrome': ['websocket', 'xhr-streaming', 'xhr-polling'],
326
  'Android Browser (old)': ['xhr-streaming', 'xhr-polling', 'jsonp-polling'],
327
  'Opera Mobile': ['xhr-streaming', 'xhr-polling'],
328
  'Windows Phone': ['websocket', 'xhr-streaming', 'xhr-polling']
329
};
330
```
331

332
### Environment-Specific Configuration
333

334
Configure transports based on deployment environment and network conditions.
335

336
**Corporate Network (Restrictive Proxy):**
337

338
```javascript
339
// Conservative configuration for corporate environments
340
const corporateSock = new SockJS('https://example.com/sockjs', null, {
341
  transports: ['xhr-polling', 'jsonp-polling'],  // Avoid WebSocket/streaming
342
  timeout: 15000,  // Longer timeout for slow networks
343
  transportOptions: {
344
    'xhr-polling': {
345
      timeout: 10000,
346
      withCredentials: true  // Maintain session
347
    }
348
  }
349
});
350
```
351

352
**High-Performance Network:**
353

354
```javascript
355
// Optimized for fast, reliable networks
356
const fastSock = new SockJS('https://example.com/sockjs', null, {
357
  transports: ['websocket', 'xhr-streaming'],  // Only fastest transports
358
  timeout: 3000,  // Aggressive timeout
359
  transportOptions: {
360
    'websocket': {
361
      heartbeat: 15000  // Frequent heartbeat
362
    }
363
  }
364
});
365
```
366

367
**Mobile/Unreliable Network:**
368

369
```javascript
370
// Configuration for mobile or unreliable networks
371
const mobileSock = new SockJS('https://example.com/sockjs', null, {
372
  transports: ['websocket', 'xhr-streaming', 'xhr-polling'],
373
  timeout: 20000,  // Patient timeout
374
  transportOptions: {
375
    'websocket': {
376
      heartbeat: 45000  // Less frequent heartbeat
377
    },
378
    'xhr-polling': {
379
      timeout: 8000
380
    }
381
  }
382
});
383
```
384

385
**Development/Testing:**
386

387
```javascript
388
// Force specific transport for testing
389
const testSock = new SockJS('https://example.com/sockjs', null, {
390
  transports: 'jsonp-polling',  // Test worst-case scenario
391
  timeout: 30000
392
});
393

394
// Test transport fallback
395
const fallbackTestSock = new SockJS('https://example.com/sockjs', null, {
396
  transports: ['fake-transport', 'xhr-polling'],  // Will skip fake and use xhr
397
  timeout: 5000
398
});
399
```
400

401
## Advanced Transport Configuration
402

403
Sophisticated transport configuration for specialized use cases.
404

405
### Session Management and Sticky Sessions
406

407
```javascript { .api }
408
/**
409
 * Configure session handling for load-balanced environments
410
 */
411
const sessionSock = new SockJS('https://example.com/sockjs', null, {
412
  server: 'server-01',  // Pin to specific server
413
  sessionId: () => 'session-' + Date.now(),  // Custom session ID
414
  transports: ['websocket', 'xhr-streaming', 'xhr-polling'],
415
  transportOptions: {
416
    'xhr-streaming': {
417
      withCredentials: true  // Include cookies for sticky sessions
418
    },
419
    'xhr-polling': {
420
      withCredentials: true
421
    }
422
  }
423
});
424
```
425

426
### Cross-Domain Configuration
427

428
```javascript { .api }
429
/**
430
 * Configure for cross-domain connections
431
 */
432
const crossDomainSock = new SockJS('https://api.example.com/sockjs', null, {
433
  // Use transports that support cross-domain
434
  transports: [
435
    'websocket',         // Native cross-domain support
436
    'iframe-eventsource', // Cross-domain via iframe
437
    'iframe-xhr-polling',
438
    'jsonp-polling'      // Always cross-domain capable
439
  ],
440
  transportOptions: {
441
    'jsonp-polling': {
442
      timeout: 8000
443
    }
444
  }
445
});
446
```
447

448
### Performance Monitoring
449

450
```javascript { .api }
451
/**
452
 * Monitor transport performance and selection
453
 */
454
const monitoredSock = new SockJS('https://example.com/sockjs', null, {
455
  transports: ['websocket', 'xhr-streaming', 'xhr-polling']
456
});
457

458
monitoredSock.onopen = function() {
459
  console.log('Connected using transport:', this.transport);
460
  console.log('Connection URL:', this.url);
461
  
462
  // Log transport performance
463
  const startTime = Date.now();
464
  this.send('ping');
465
  
466
  this.onmessage = function(event) {
467
    if (event.data === 'pong') {
468
      console.log('Round-trip time:', Date.now() - startTime, 'ms');
469
    }
470
  };
471
};
472

473
// Monitor transport failures
474
monitoredSock.addEventListener('error', function() {
475
  console.log('Transport error, will try fallback');
476
});
477
```
478

479
## Transport Limitations and Considerations
480

481
Important limitations and considerations when configuring transports.
482

483
### Connection Limits
484

485
```javascript { .api }
486
/**
487
 * Browser connection limitations
488
 */
489
const connectionLimits = {
490
  maxConnectionsPerDomain: 6,      // Most browsers
491
  maxConnectionsPerDomainIE8: 2,   // IE 8 specifically
492
  sockjsConnectionsRequired: 2,    // One for sending, one for receiving
493
  
494
  // Implications
495
  maxSockJSConnectionsPerDomain: 1, // Generally only one SockJS per domain
496
  workaround: 'Use subdomains for multiple connections'
497
};
498
```
499

500
**Multiple Connection Workaround:**
501

502
```javascript
503
// DON'T: Multiple connections to same domain (will likely block)
504
const sock1 = new SockJS('https://example.com/sockjs');
505
const sock2 = new SockJS('https://example.com/sockjs'); // May block
506

507
// DO: Use subdomains for multiple connections
508
const sock1 = new SockJS('https://api1.example.com/sockjs');
509
const sock2 = new SockJS('https://api2.example.com/sockjs');
510
```
511

512
### Security Considerations
513

514
```javascript { .api }
515
/**
516
 * Security-related transport considerations
517
 */
518
const securityConsiderations = {
519
  httpsToHttp: 'Blocked unless connecting to localhost/127.0.0.1',
520
  xdrLimitations: 'No cookies, limited headers in IE 8-9',
521
  jsonpSecurity: 'Script injection risks if server is compromised',
522
  iframeSecurity: 'Same-origin policy bypass, use with trusted servers only'
523
};
524
```
525

526
**Secure Configuration Example:**
527

528
```javascript
529
// Secure configuration for production
530
const secureSock = new SockJS('https://secure-api.example.com/sockjs', null, {
531
  // Avoid potentially insecure transports
532
  transports: ['websocket', 'xhr-streaming', 'xhr-polling'],
533
  
534
  // Enable credentials for authentication
535
  transportOptions: {
536
    'xhr-streaming': { withCredentials: true },
537
    'xhr-polling': { withCredentials: true }
538
  },
539
  
540
  // Conservative timeout
541
  timeout: 10000
542
});
543
```
544

545
### Performance Characteristics
546

547
```javascript { .api }
548
/**
549
 * Transport performance characteristics (approximate)
550
 */
551
const performanceMetrics = {
552
  'websocket': {
553
    latency: 'Lowest (~1-10ms overhead)',
554
    throughput: 'Highest',
555
    resourceUsage: 'Lowest',
556
    connectionSetup: 'Fast'
557
  },
558
  'xhr-streaming': {
559
    latency: 'Low (~10-50ms overhead)', 
560
    throughput: 'High',
561
    resourceUsage: 'Medium',
562
    connectionSetup: 'Medium'  
563
  },
564
  'xhr-polling': {
565
    latency: 'Medium (~100-500ms)',
566
    throughput: 'Medium', 
567
    resourceUsage: 'High',
568
    connectionSetup: 'Fast'
569
  },
570
  'jsonp-polling': {
571
    latency: 'Highest (~200-1000ms)',
572
    throughput: 'Lowest',
573
    resourceUsage: 'Highest', 
574
    connectionSetup: 'Slow'
575
  }
576
};
577
```