0
# Server Framework
1

2
Production-ready server implementations supporting single and multiplexed services with configurable protocols, transports, event-driven architecture, and comprehensive error handling for Node.js applications.
3

4
## Capabilities
5

6
### Basic Server
7

8
Standard single-service Thrift server providing efficient request processing with configurable protocols and transports.
9

10
```javascript { .api }
11
/**
12
 * Create a single-service Thrift server
13
 * @param processor - Service processor (usually generated service class)
14
 * @param handler - Service implementation object with method handlers
15
 * @param options - Server configuration options
16
 * @returns Server instance
17
 */
18
function createServer(processor, handler, options): Server;
19

20
/**
21
 * Basic Thrift server class
22
 */
23
class Server extends EventEmitter {
24
  constructor(processor, handler, options);
25
  
26
  // Server lifecycle
27
  listen(port, host?, callback?): void;
28
  close(callback?): void;
29
  
30
  // Event handling
31
  on(event, listener): void;
32
  emit(event, ...args): void;
33
  
34
  // Server properties
35
  connections: Set<Connection>;
36
  listening: boolean;
37
  
38
  // Configuration
39
  transport: TransportConstructor;
40
  protocol: ProtocolConstructor;
41
}
42
```
43

44
**Usage Examples:**
45

46
```javascript
47
const thrift = require('thrift');
48
const MyService = require('./gen-nodejs/MyService');
49

50
// Service implementation
51
const serviceHandler = {
52
  ping: function(callback) {
53
    console.log('Received ping');
54
    callback(null, 'pong');
55
  },
56
  
57
  calculate: function(num1, num2, operation, callback) {
58
    let result;
59
    switch (operation) {
60
      case 'ADD':
61
        result = num1 + num2;
62
        break;
63
      case 'SUBTRACT':
64
        result = num1 - num2;
65
        break;
66
      case 'MULTIPLY':
67
        result = num1 * num2;
68
        break;
69
      case 'DIVIDE':
70
        result = num1 / num2;
71
        break;
72
      default:
73
        callback(new Error('Invalid operation'));
74
        return;
75
    }
76
    callback(null, result);
77
  }
78
};
79

80
// Create server with binary protocol and buffered transport
81
const server = thrift.createServer(MyService, serviceHandler, {
82
  transport: thrift.TBufferedTransport,
83
  protocol: thrift.TBinaryProtocol
84
});
85

86
// Server event handling
87
server.on('connection', (connection) => {
88
  console.log('Client connected');
89
});
90

91
server.on('disconnect', (connection) => {
92
  console.log('Client disconnected');
93
});
94

95
server.on('error', (error) => {
96
  console.error('Server error:', error);
97
});
98

99
// Start server
100
server.listen(9090, 'localhost', () => {
101
  console.log('Thrift server listening on port 9090');
102
});
103

104
// Graceful shutdown
105
process.on('SIGINT', () => {
106
  console.log('Shutting down server...');
107
  server.close(() => {
108
    console.log('Server closed');
109
    process.exit(0);
110
  });
111
});
112
```
113

114
### Multiplexed Server
115

116
Advanced server supporting multiple services over a single connection with automatic service routing and processor management.
117

118
```javascript { .api }
119
/**
120
 * Create a multiplexed server supporting multiple services
121
 * @param processor - Multiplexed processor instance
122
 * @param options - Server configuration options
123
 * @returns MultiplexedServer instance
124
 */
125
function createMultiplexServer(processor, options): MultiplexedServer;
126

127
/**
128
 * Multiplexed Thrift server class
129
 */
130
class MultiplexedServer extends EventEmitter {
131
  constructor(processor, options);
132
  
133
  // Server lifecycle
134
  listen(port, host?, callback?): void;
135
  close(callback?): void;
136
  
137
  // Service management
138
  registerProcessor(serviceName, serviceProcessor, serviceHandler): void;
139
  unregisterProcessor(serviceName): void;
140
  getProcessor(serviceName): Processor;
141
  
142
  // Event handling
143
  on(event, listener): void;
144
  emit(event, ...args): void;
145
  
146
  // Server properties
147
  connections: Set<Connection>;
148
  listening: boolean;
149
  services: Map<string, Processor>;
150
  
151
  // Configuration
152
  transport: TransportConstructor;
153
  protocol: ProtocolConstructor;
154
}
155
```
156

157
**Usage Examples:**
158

159
```javascript
160
const thrift = require('thrift');
161
const CalculatorService = require('./gen-nodejs/Calculator');
162
const WeatherService = require('./gen-nodejs/Weather');
163

164
// Create multiplexed processor
165
const processor = new thrift.MultiplexedProcessor();
166

167
// Calculator service implementation
168
const calculatorHandler = {
169
  add: (num1, num2, callback) => {
170
    callback(null, num1 + num2);
171
  },
172
  subtract: (num1, num2, callback) => {
173
    callback(null, num1 - num2);
174
  }
175
};
176

177
// Weather service implementation  
178
const weatherHandler = {
179
  getTemperature: (city, callback) => {
180
    // Simulate weather API call
181
    const temp = Math.round(Math.random() * 40);
182
    callback(null, temp);
183
  },
184
  getForecast: (city, days, callback) => {
185
    const forecast = [];
186
    for (let i = 0; i < days; i++) {
187
      forecast.push({
188
        day: i + 1,
189
        temperature: Math.round(Math.random() * 40),
190
        condition: 'Sunny'
191
      });
192
    }
193
    callback(null, forecast);
194
  }
195
};
196

197
// Register services with multiplexed processor
198
processor.registerProcessor('Calculator', CalculatorService, calculatorHandler);
199
processor.registerProcessor('Weather', WeatherService, weatherHandler);
200

201
// Create multiplexed server
202
const server = thrift.createMultiplexServer(processor, {
203
  transport: thrift.TFramedTransport,
204
  protocol: thrift.TBinaryProtocol
205
});
206

207
// Handle service-specific events
208
server.on('Calculator:request', (method, args) => {
209
  console.log(`Calculator.${method} called with:`, args);
210
});
211

212
server.on('Weather:request', (method, args) => {
213
  console.log(`Weather.${method} called with:`, args);
214
});
215

216
// Start multiplexed server
217
server.listen(9090, () => {
218
  console.log('Multiplexed server listening on port 9090');
219
  console.log('Available services: Calculator, Weather');
220
});
221
```
222

223
### Web Server
224

225
HTTP and WebSocket server implementation providing web-friendly access to Thrift services with CORS support and flexible routing.
226

227
```javascript { .api }
228
/**
229
 * Create a web server with HTTP and WebSocket support
230
 * @param processor - Service processor or multiplexed processor
231
 * @param options - Web server configuration options
232
 * @returns WebServer instance
233
 */
234
function createWebServer(processor, options): WebServer;
235

236
/**
237
 * Web Thrift server class with HTTP and WebSocket support
238
 */
239
class WebServer extends EventEmitter {
240
  constructor(processor, options);
241
  
242
  // Server lifecycle
243
  listen(port, host?, callback?): void;
244
  close(callback?): void;
245
  
246
  // HTTP handling
247
  handleRequest(request, response): void;
248
  
249
  // WebSocket handling
250
  handleUpgrade(request, socket, head): void;
251
  
252
  // Event handling
253
  on(event, listener): void;
254
  emit(event, ...args): void;
255
  
256
  // Server properties
257
  httpServer: HttpServer;
258
  wsServer: WebSocketServer;
259
  connections: Set<Connection>;
260
  listening: boolean;
261
  
262
  // Configuration
263
  cors: CorsOptions;
264
  static: StaticFileOptions;
265
  protocol: ProtocolConstructor;
266
}
267
```
268

269
**Usage Examples:**
270

271
```javascript
272
const thrift = require('thrift');
273
const path = require('path');
274
const ApiService = require('./gen-nodejs/ApiService');
275

276
// API service implementation
277
const apiHandler = {
278
  getData: (id, callback) => {
279
    callback(null, { id, data: `Data for ${id}`, timestamp: Date.now() });
280
  },
281
  saveData: (data, callback) => {
282
    console.log('Saving data:', data);
283
    callback(null, { success: true, id: Date.now() });
284
  }
285
};
286

287
// Create web server with HTTP and WebSocket support
288
const webServer = thrift.createWebServer(ApiService, apiHandler, {
289
  protocol: thrift.TJSONProtocol,
290
  
291
  // CORS configuration
292
  cors: {
293
    origin: ['http://localhost:3000', 'https://myapp.com'],
294
    credentials: true,
295
    methods: ['GET', 'POST', 'OPTIONS']
296
  },
297
  
298
  // Static file serving
299
  static: {
300
    root: path.join(__dirname, 'public'),
301
    index: 'index.html'
302
  },
303
  
304
  // WebSocket options
305
  websocket: {
306
    path: '/thrift-ws',
307
    maxConnections: 100
308
  }
309
});
310

311
// Handle HTTP requests
312
webServer.on('request', (req, res) => {
313
  console.log(`HTTP ${req.method} ${req.url}`);
314
});
315

316
// Handle WebSocket connections
317
webServer.on('websocket:connection', (ws) => {
318
  console.log('WebSocket client connected');
319
  
320
  ws.on('close', () => {
321
    console.log('WebSocket client disconnected');
322
  });
323
});
324

325
// Start web server
326
webServer.listen(8080, () => {
327
  console.log('Web server listening on port 8080');
328
  console.log('HTTP endpoint: http://localhost:8080/');
329
  console.log('WebSocket endpoint: ws://localhost:8080/thrift-ws');
330
});
331
```
332

333
## Server Configuration Options
334

335
```javascript { .api }
336
// Common server configuration interface
337
interface ServerOptions {
338
  /** Transport class to use for connections */
339
  transport?: TransportConstructor;
340
  
341
  /** Protocol class to use for serialization */
342
  protocol?: ProtocolConstructor;
343
  
344
  /** Enable TLS/SSL encryption */
345
  tls?: TLSOptions;
346
  
347
  /** Connection timeout in milliseconds */
348
  timeout?: number;
349
  
350
  /** Maximum number of concurrent connections */
351
  maxConnections?: number;
352
  
353
  /** Enable keep-alive for connections */
354
  keepAlive?: boolean;
355
  
356
  /** Custom error handler function */
357
  errorHandler?: (error: Error, connection: Connection) => void;
358
}
359

360
// TLS/SSL configuration
361
interface TLSOptions {
362
  /** Private key file path or buffer */
363
  key?: string | Buffer;
364
  
365
  /** Certificate file path or buffer */
366
  cert?: string | Buffer;
367
  
368
  /** Certificate Authority certificates */
369
  ca?: string | Buffer | Array<string | Buffer>;
370
  
371
  /** Require client certificates */
372
  requestCert?: boolean;
373
  
374
  /** Reject unauthorized certificates */
375
  rejectUnauthorized?: boolean;
376
}
377

378
// Web server specific options
379
interface WebServerOptions extends ServerOptions {
380
  /** CORS configuration */
381
  cors?: CorsOptions;
382
  
383
  /** Static file serving options */
384
  static?: StaticFileOptions;
385
  
386
  /** WebSocket configuration */
387
  websocket?: WebSocketOptions;
388
}
389

390
// CORS configuration
391
interface CorsOptions {
392
  /** Allowed origins */
393
  origin?: string | string[] | RegExp;
394
  
395
  /** Allowed methods */
396
  methods?: string[];
397
  
398
  /** Allowed headers */
399
  allowedHeaders?: string[];
400
  
401
  /** Enable credentials */
402
  credentials?: boolean;
403
}
404
```
405

406
## Server Events
407

408
```javascript { .api }
409
// Server event types and handlers
410
interface ServerEvents {
411
  /** Emitted when server starts listening */
412
  'listening': () => void;
413
  
414
  /** Emitted when a client connects */
415
  'connection': (connection: Connection) => void;
416
  
417
  /** Emitted when a client disconnects */
418
  'disconnect': (connection: Connection) => void;
419
  
420
  /** Emitted on server errors */
421
  'error': (error: Error) => void;
422
  
423
  /** Emitted before processing a request */
424
  'request': (method: string, args: any[]) => void;
425
  
426
  /** Emitted after processing a request */
427
  'response': (method: string, result: any) => void;
428
  
429
  /** Emitted when server is closing */
430
  'close': () => void;
431
}
432

433
// Multiplexed server additional events
434
interface MultiplexedServerEvents extends ServerEvents {
435
  /** Emitted for service-specific requests */
436
  [serviceName: string]: (method: string, args: any[]) => void;
437
}
438

439
// Web server additional events  
440
interface WebServerEvents extends ServerEvents {
441
  /** Emitted for HTTP requests */
442
  'request': (req: IncomingMessage, res: ServerResponse) => void;
443
  
444
  /** Emitted for WebSocket connections */
445
  'websocket:connection': (ws: WebSocket) => void;
446
  
447
  /** Emitted for WebSocket disconnections */
448
  'websocket:disconnect': (ws: WebSocket) => void;
449
}
450
```
451

452
## Error Handling
453

454
```javascript { .api }
455
// Server error handling patterns
456
interface ErrorHandling {
457
  // Global error handler
458
  server.on('error', (error) => {
459
    console.error('Server error:', error);
460
    // Log error, send alerts, etc.
461
  });
462
  
463
  // Connection-specific error handler
464
  server.on('connection', (connection) => {
465
    connection.on('error', (error) => {
466
      console.error('Connection error:', error);
467
      // Handle connection-specific errors
468
    });
469
  });
470
  
471
  // Service method error handling
472
  serviceHandler: {
473
    myMethod: (args, callback) => {
474
      try {
475
        const result = processRequest(args);
476
        callback(null, result);
477
      } catch (error) {
478
        callback(error); // Pass error to Thrift framework
479
      }
480
    }
481
  };
482
}
483
```