0
# Connection Management
1

2
Comprehensive connection management supporting multiple transport mechanisms with flexible configuration options, automatic error handling, and event-driven architecture for Node.js applications.
3

4
## Capabilities
5

6
### TCP Connections
7

8
Standard TCP socket connections with support for SSL/TLS, Unix Domain Sockets, and STDIO communication.
9

10
```javascript { .api }
11
/**
12
 * Create a standard TCP connection to a Thrift server
13
 * @param host - Server hostname or IP address
14
 * @param port - Server port number  
15
 * @param options - Connection configuration options
16
 * @returns Connection instance
17
 */
18
function createConnection(host, port, options): Connection;
19

20
/**
21
 * Create an SSL/TLS encrypted TCP connection
22
 * @param host - Server hostname or IP address
23
 * @param port - Server port number
24
 * @param options - Connection configuration with SSL options
25
 * @returns Connection instance
26
 */
27
function createSSLConnection(host, port, options): Connection;
28

29
/**
30
 * Create Unix Domain Socket connection for local communication
31
 * @param path - Unix socket file path
32
 * @param options - Connection configuration options
33
 * @returns Connection instance
34
 */
35
function createUDSConnection(path, options): Connection;
36

37
/**
38
 * Create STDIO connection for subprocess communication
39
 * @param command - Command to execute for STDIO transport
40
 * @param options - Connection configuration options
41
 * @returns Connection instance
42
 */
43
function createStdIOConnection(command, options): Connection;
44

45
/**
46
 * Base Connection class for TCP connections
47
 */
48
class Connection extends EventEmitter {
49
  constructor(stream, options);
50
  
51
  /**
52
   * Check if connection is currently open
53
   * @returns true if connection is open
54
   */
55
  isOpen(): boolean;
56
  
57
  /**
58
   * Open the connection
59
   * @param callback - Optional callback when connection opens
60
   */
61
  open(callback?): void;
62
  
63
  /**
64
   * Close the connection
65
   */
66
  close(): void;
67
  
68
  /**
69
   * Write data to the connection
70
   * @param data - Data to write
71
   */
72
  write(data): void;
73
  
74
  /**
75
   * Connection timeout in milliseconds
76
   */
77
  timeout: number;
78
  
79
  /**
80
   * Transport class for this connection
81
   */
82
  transport: TransportConstructor;
83
  
84
  /**
85
   * Protocol class for this connection
86
   */
87
  protocol: ProtocolConstructor;
88
}
89
```
90

91
**Usage Examples:**
92

93
```javascript
94
const thrift = require('thrift');
95

96
// Basic TCP connection
97
const connection = thrift.createConnection('localhost', 9090, {
98
  transport: thrift.TBufferedTransport,
99
  protocol: thrift.TBinaryProtocol,
100
  timeout: 5000
101
});
102

103
// SSL connection with certificates
104
const sslConnection = thrift.createSSLConnection('secure.example.com', 9091, {
105
  transport: thrift.TFramedTransport,
106
  protocol: thrift.TCompactProtocol,
107
  https: true,
108
  key: fs.readFileSync('client-key.pem'),
109
  cert: fs.readFileSync('client-cert.pem'),
110
  ca: fs.readFileSync('ca-cert.pem')
111
});
112

113
// Unix Domain Socket
114
const udsConnection = thrift.createUDSConnection('/tmp/thrift.sock', {
115
  transport: thrift.TBufferedTransport,
116
  protocol: thrift.TBinaryProtocol
117
});
118

119
// Connection event handling
120
connection.on('connect', () => {
121
  console.log('Connected to Thrift server');
122
});
123

124
connection.on('error', (err) => {
125
  console.error('Connection error:', err);
126
});
127

128
connection.on('close', () => {
129
  console.log('Connection closed');
130
});
131
```
132

133
### HTTP Connections
134

135
HTTP-based connections supporting both standard HTTP and HTTP over Unix Domain Sockets with configurable headers and request options.
136

137
```javascript { .api }
138
/**
139
 * Create HTTP connection to a Thrift server
140
 * @param host - Server hostname or IP address
141
 * @param port - Server port number
142
 * @param options - HTTP connection configuration options
143
 * @returns HttpConnection instance
144
 */
145
function createHttpConnection(host, port, options): HttpConnection;
146

147
/**
148
 * Create HTTP connection over Unix Domain Socket
149
 * @param path - Unix socket file path
150
 * @param options - HTTP connection configuration options
151
 * @returns HttpConnection instance
152
 */
153
function createHttpUDSConnection(path, options): HttpConnection;
154

155
/**
156
 * Create HTTP client with service binding
157
 * @param ServiceClient - Generated service client class
158
 * @param connection - HTTP connection instance
159
 * @returns Bound service client
160
 */
161
function createHttpClient(ServiceClient, connection): Client;
162

163
/**
164
 * HTTP Connection class for HTTP transport
165
 */
166
class HttpConnection {
167
  constructor(host, port, options);
168
  
169
  /**
170
   * Check if connection is currently open
171
   * @returns true if connection is open
172
   */
173
  isOpen(): boolean;
174
  
175
  /**
176
   * Open the HTTP connection
177
   */
178
  open(): void;
179
  
180
  /**
181
   * Close the HTTP connection
182
   */
183
  close(): void;
184
  
185
  /**
186
   * Write data via HTTP request
187
   * @param data - Data to write
188
   */
189
  write(data): void;
190
  
191
  /**
192
   * HTTP request options
193
   */
194
  nodeOptions: object;
195
  
196
  /**
197
   * HTTP headers to send with requests
198
   */
199
  headers: object;
200
  
201
  /**
202
   * URL path for HTTP requests
203
   */
204
  path: string;
205
  
206
  /**
207
   * Use HTTPS instead of HTTP
208
   */
209
  https: boolean;
210
}
211
```
212

213
**Usage Examples:**
214

215
```javascript
216
// Basic HTTP connection
217
const httpConnection = thrift.createHttpConnection('api.example.com', 80, {
218
  path: '/thrift',
219
  headers: {
220
    'Content-Type': 'application/x-thrift',
221
    'Authorization': 'Bearer token123'
222
  },
223
  transport: thrift.TBufferedTransport,
224
  protocol: thrift.TJSONProtocol
225
});
226

227
// HTTPS connection with custom options
228
const httpsConnection = thrift.createHttpConnection('secure-api.example.com', 443, {
229
  path: '/api/v1/thrift',
230
  https: true,
231
  headers: {
232
    'User-Agent': 'MyApp/1.0',
233
    'Accept': 'application/x-thrift'
234
  },
235
  nodeOptions: {
236
    timeout: 30000,
237
    keepAlive: true
238
  }
239
});
240

241
// HTTP over Unix Domain Socket
242
const httpUdsConnection = thrift.createHttpUDSConnection('/tmp/http-thrift.sock', {
243
  path: '/service',
244
  headers: { 'X-Service-Version': '2.0' }
245
});
246
```
247

248
### WebSocket Connections
249

250
WebSocket connections for real-time, bidirectional communication with support for secure WebSockets (WSS) and custom headers.
251

252
```javascript { .api }
253
/**
254
 * Create WebSocket connection to a Thrift server
255
 * @param host - Server hostname or IP address
256
 * @param port - Server port number
257
 * @param options - WebSocket connection configuration options
258
 * @returns WSConnection instance
259
 */
260
function createWSConnection(host, port, options): WSConnection;
261

262
/**
263
 * Create WebSocket client with service binding
264
 * @param ServiceClient - Generated service client class
265
 * @param connection - WebSocket connection instance
266
 * @returns Bound service client
267
 */
268
function createWSClient(ServiceClient, connection): Client;
269

270
/**
271
 * WebSocket Connection class
272
 */
273
class WSConnection extends EventEmitter {
274
  constructor(host, port, options);
275
  
276
  /**
277
   * Check if WebSocket connection is currently open
278
   * @returns true if connection is open
279
   */
280
  isOpen(): boolean;
281
  
282
  /**
283
   * Open the WebSocket connection
284
   */
285
  open(): void;
286
  
287
  /**
288
   * Close the WebSocket connection
289
   * @param code - WebSocket close code
290
   * @param reason - Close reason string
291
   */
292
  close(code?, reason?): void;
293
  
294
  /**
295
   * Write data via WebSocket
296
   * @param data - Data to write
297
   */
298
  write(data): void;
299
  
300
  /**
301
   * Use secure WebSocket (WSS)
302
   */
303
  secure: boolean;
304
  
305
  /**
306
   * WebSocket headers
307
   */
308
  headers: object;
309
  
310
  /**
311
   * WebSocket-specific options
312
   */
313
  wsOptions: object;
314
}
315
```
316

317
**Usage Examples:**
318

319
```javascript
320
// Basic WebSocket connection
321
const wsConnection = thrift.createWSConnection('localhost', 8080, {
322
  transport: thrift.TFramedTransport,
323
  protocol: thrift.TBinaryProtocol,
324
  wsOptions: {
325
    perMessageDeflate: false
326
  }
327
});
328

329
// Secure WebSocket with authentication
330
const wssConnection = thrift.createWSConnection('secure.example.com', 8443, {
331
  secure: true,
332
  headers: {
333
    'Authorization': 'Bearer jwt-token',
334
    'X-Client-Version': '1.2.3'
335
  },
336
  wsOptions: {
337
    rejectUnauthorized: true,
338
    ca: fs.readFileSync('ca-cert.pem')
339
  }
340
});
341

342
// WebSocket event handling
343
wsConnection.on('open', () => {
344
  console.log('WebSocket connected');
345
});
346

347
wsConnection.on('message', (data) => {
348
  console.log('Received WebSocket message');
349
});
350

351
wsConnection.on('close', (code, reason) => {
352
  console.log(`WebSocket closed: ${code} - ${reason}`);
353
});
354
```
355

356
### Browser XHR Connections
357

358
XMLHttpRequest connections optimized for browser environments with CORS support and configurable request options.
359

360
```javascript { .api }
361
/**
362
 * Create XMLHttpRequest connection for browser environments
363
 * @param host - Server hostname or IP address
364
 * @param port - Server port number
365
 * @param options - XHR connection configuration options
366
 * @returns XHRConnection instance
367
 */
368
function createXHRConnection(host, port, options): XHRConnection;
369

370
/**
371
 * Create XHR client with service binding
372
 * @param ServiceClient - Generated service client class
373
 * @param connection - XHR connection instance
374
 * @returns Bound service client
375
 */
376
function createXHRClient(ServiceClient, connection): Client;
377

378
/**
379
 * XMLHttpRequest Connection class for browser environments
380
 */
381
class XHRConnection {
382
  constructor(host, port, options);
383
  
384
  /**
385
   * Check if XHR connection is ready
386
   * @returns true if connection is ready
387
   */
388
  isOpen(): boolean;
389
  
390
  /**
391
   * Open the XHR connection
392
   */
393
  open(): void;
394
  
395
  /**
396
   * Close the XHR connection
397
   */
398
  close(): void;
399
  
400
  /**
401
   * Write data via XMLHttpRequest
402
   * @param data - Data to write
403
   */
404
  write(data): void;
405
  
406
  /**
407
   * HTTP headers for XHR requests
408
   */
409
  headers: object;
410
  
411
  /**
412
   * Use HTTPS for requests
413
   */
414
  https: boolean;
415
  
416
  /**
417
   * URL path for XHR requests
418
   */
419
  path: string;
420
}
421
```
422

423
### Generic Client Creation
424

425
Generic client factory functions that work with any connection type for maximum flexibility.
426

427
```javascript { .api }
428
/**
429
 * Create generic Thrift client for any connection type
430
 * @param ServiceClient - Generated service client class
431
 * @param connection - Any connection instance
432
 * @returns Bound service client
433
 */
434
function createClient(ServiceClient, connection): Client;
435

436
/**
437
 * Create STDIO client with service binding
438
 * @param ServiceClient - Generated service client class
439
 * @param connection - STDIO connection instance
440
 * @returns Bound service client
441
 */
442
function createStdIOClient(ServiceClient, connection): Client;
443
```
444

445
## Connection Options
446

447
```javascript { .api }
448
// Common connection options interface
449
interface ConnectionOptions {
450
  /** Transport class to use */
451
  transport?: TransportConstructor;
452
  
453
  /** Protocol class to use */
454
  protocol?: ProtocolConstructor;
455
  
456
  /** Connection timeout in milliseconds */
457
  timeout?: number;
458
  
459
  /** Enable debug logging */
460
  debug?: boolean;
461
  
462
  /** Maximum connection attempts */
463
  max_attempts?: number;
464
  
465
  /** Maximum retry delay in milliseconds */
466
  retry_max_delay?: number;
467
  
468
  /** Connection timeout in milliseconds */
469
  connect_timeout?: number;
470
}
471

472
// HTTP-specific options
473
interface HttpConnectionOptions extends ConnectionOptions {
474
  /** URL path for HTTP requests */
475
  path?: string;
476
  
477
  /** HTTP headers to send */
478
  headers?: object;
479
  
480
  /** Use HTTPS instead of HTTP */
481
  https?: boolean;
482
  
483
  /** Node.js HTTP request options */
484
  nodeOptions?: object;
485
}
486

487
// WebSocket-specific options  
488
interface WSConnectionOptions extends ConnectionOptions {
489
  /** Use secure WebSocket (WSS) */
490
  secure?: boolean;
491
  
492
  /** WebSocket headers */
493
  headers?: object;
494
  
495
  /** WebSocket-specific options */
496
  wsOptions?: object;
497
}
498

499
// SSL/TLS options
500
interface SSLConnectionOptions extends ConnectionOptions {
501
  /** Private key for client certificate */
502
  key?: Buffer | string;
503
  
504
  /** Client certificate */
505
  cert?: Buffer | string;
506
  
507
  /** Certificate Authority certificates */
508
  ca?: Buffer | string | Array<Buffer | string>;
509
  
510
  /** Reject unauthorized certificates */
511
  rejectUnauthorized?: boolean;
512
}
513
```