0
# Transport Layer
1

2
Flexible transport implementations providing buffering, framing, and WebSocket capabilities with seamless protocol integration, error handling, and optimized I/O operations for Node.js environments.
3

4
## Capabilities
5

6
### Buffered Transport
7

8
Standard buffered transport providing efficient I/O operations with configurable buffer sizes and automatic flushing for optimal performance in most scenarios.
9

10
```javascript { .api }
11
/**
12
 * Buffered transport implementation for efficient I/O operations
13
 * @param buffer - Optional initial buffer or underlying transport
14
 * @param callback - Optional callback function for transport events
15
 */
16
class TBufferedTransport {
17
  constructor(buffer?, callback?);
18
  
19
  // Connection management
20
  isOpen(): boolean;
21
  open(callback?): void;
22
  close(): void;
23
  
24
  // I/O operations
25
  read(len): Buffer;
26
  readAll(len): Buffer;
27
  write(buf): void;
28
  flush(callback?): void;
29
  
30
  // Buffer management
31
  getCurrent(): number;
32
  commitPosition(): void;
33
  rollbackPosition(): void;
34
  
35
  // Event handling
36
  on(event, listener): void;
37
  emit(event, ...args): void;
38
  
39
  // Configuration properties
40
  readBufferSize: number;
41
  writeBufferSize: number;
42
}
43
```
44

45
**Usage Examples:**
46

47
```javascript
48
const thrift = require('thrift');
49

50
// Basic buffered transport
51
const transport = new thrift.TBufferedTransport();
52

53
// With custom buffer sizes
54
const customTransport = new thrift.TBufferedTransport(null, {
55
  readBufferSize: 8192,
56
  writeBufferSize: 8192
57
});
58

59
// With callback for events
60
const callbackTransport = new thrift.TBufferedTransport(null, (err, result) => {
61
  if (err) {
62
    console.error('Transport error:', err);
63
  } else {
64
    console.log('Transport operation completed');
65
  }
66
});
67

68
// Writing data
69
transport.write(Buffer.from('Hello, Thrift!'));
70
transport.flush((err) => {
71
  if (err) {
72
    console.error('Flush error:', err);
73
  } else {
74
    console.log('Data flushed successfully');
75
  }
76
});
77

78
// Reading data
79
const data = transport.read(1024);
80
console.log('Read data:', data.toString());
81
```
82

83
### Framed Transport
84

85
Framed transport implementation that adds length prefixes to messages for reliable message boundaries and improved parsing efficiency over stream-oriented connections.
86

87
```javascript { .api }
88
/**
89
 * Framed transport implementation with message framing
90
 * @param buffer - Optional initial buffer or underlying transport
91
 * @param callback - Optional callback function for transport events
92
 */
93
class TFramedTransport {
94
  constructor(buffer?, callback?);
95
  
96
  // Same interface as TBufferedTransport with framing support
97
  isOpen(): boolean;
98
  open(callback?): void;
99
  close(): void;
100
  
101
  read(len): Buffer;
102
  readAll(len): Buffer;
103
  write(buf): void;
104
  flush(callback?): void;
105
  
106
  getCurrent(): number;
107
  commitPosition(): void;
108
  rollbackPosition(): void;
109
  
110
  on(event, listener): void;
111
  emit(event, ...args): void;
112
  
113
  // Framing-specific properties
114
  frameSize: number;
115
  maxFrameSize: number;
116
}
117
```
118

119
**Usage Examples:**
120

121
```javascript
122
// Basic framed transport for reliable message boundaries
123
const framedTransport = new thrift.TFramedTransport();
124

125
// With custom frame size limits
126
const customFramedTransport = new thrift.TFramedTransport(null, {
127
  maxFrameSize: 1024 * 1024 // 1MB max frame size
128
});
129

130
// Automatic message framing
131
framedTransport.write(Buffer.from('Message 1'));
132
framedTransport.write(Buffer.from('Message 2'));
133
framedTransport.flush(); // Sends both messages with proper framing
134

135
// Frame boundaries are handled automatically
136
const message1 = framedTransport.read(); // Reads exactly one complete message
137
const message2 = framedTransport.read(); // Reads the next complete message
138
```
139

140
### WebSocket Transport
141

142
WebSocket transport implementation for real-time, bidirectional communication with support for browser and Node.js environments.
143

144
```javascript { .api }
145
/**
146
 * WebSocket transport implementation for real-time communication
147
 * @param websocket - WebSocket instance or connection options
148
 */
149
class TWSTransport {
150
  constructor(websocket);
151
  
152
  // WebSocket-specific interface
153
  isOpen(): boolean;
154
  open(callback?): void;
155
  close(code?, reason?): void;
156
  
157
  read(len): Buffer;
158
  readAll(len): Buffer;
159
  write(buf): void;
160
  flush(callback?): void;
161
  
162
  // WebSocket event handling
163
  on(event, listener): void;
164
  emit(event, ...args): void;
165
  
166
  // WebSocket properties
167
  readyState: number;
168
  protocol: string;
169
  extensions: object;
170
}
171
```
172

173
**Usage Examples:**
174

175
```javascript
176
const WebSocket = require('ws');
177

178
// WebSocket transport for real-time communication
179
const ws = new WebSocket('ws://localhost:8080/thrift');
180
const wsTransport = new thrift.TWSTransport(ws);
181

182
// Handle WebSocket events
183
wsTransport.on('open', () => {
184
  console.log('WebSocket transport connected');
185
});
186

187
wsTransport.on('message', (data) => {
188
  console.log('Received WebSocket message');
189
});
190

191
wsTransport.on('close', (code, reason) => {
192
  console.log(`WebSocket closed: ${code} - ${reason}`);
193
});
194

195
wsTransport.on('error', (error) => {
196
  console.error('WebSocket error:', error);
197
});
198

199
// Real-time bidirectional communication
200
wsTransport.write(Buffer.from('Real-time message'));
201
wsTransport.flush();
202
```
203

204
### Memory Transport
205

206
In-memory transport implementation for testing, debugging, and local inter-process communication without network overhead.
207

208
```javascript { .api }
209
/**
210
 * Memory transport implementation for in-memory communication
211
 * @param buffer - Optional initial buffer content
212
 */
213
class TMemoryBuffer {
214
  constructor(buffer?);
215
  
216
  // Memory-specific interface
217
  isOpen(): boolean;
218
  open(): void;
219
  close(): void;
220
  
221
  read(len): Buffer;
222
  readAll(len): Buffer;
223
  write(buf): void;
224
  flush(): void;
225
  
226
  // Memory buffer operations
227
  clear(): void;
228
  getBuffer(): Buffer;
229
  available(): number;
230
  
231
  // Position management
232
  getCurrent(): number;
233
  setCurrent(position): void;
234
  reset(): void;
235
}
236
```
237

238
**Usage Examples:**
239

240
```javascript
241
// Memory transport for testing and debugging
242
const memoryTransport = new thrift.TMemoryBuffer();
243

244
// Pre-populate with test data
245
const testData = Buffer.from('test message');
246
const preloadedTransport = new thrift.TMemoryBuffer(testData);
247

248
// Write and read operations
249
memoryTransport.write(Buffer.from('Hello'));
250
memoryTransport.write(Buffer.from(', World!'));
251

252
// Read back the data
253
const result = memoryTransport.read(13);
254
console.log('Memory transport result:', result.toString()); // "Hello, World!"
255

256
// Useful for unit testing
257
const protocol = new thrift.TBinaryProtocol(memoryTransport);
258
protocol.writeString('test');
259
protocol.flush();
260

261
memoryTransport.reset(); // Reset position to beginning
262
const readResult = protocol.readString();
263
console.log('Round-trip test:', readResult); // "test"
264
```
265

266
## Transport Layering
267

268
```javascript { .api }
269
// Transport layering for combining features
270
interface TransportLayering {
271
  // Base transport provides the actual I/O
272
  baseTransport: TSocket | THttpTransport | TWSTransport;
273
  
274
  // Layered transports add functionality
275
  bufferedTransport: TBufferedTransport;
276
  framedTransport: TFramedTransport;
277
  
278
  // Example: Framed + Buffered over TCP
279
  layeredStack: TFramedTransport(TBufferedTransport(TSocket));
280
}
281
```
282

283
**Usage Examples:**
284

285
```javascript
286
// Layering transports for enhanced functionality
287
const socket = new thrift.TSocket('localhost', 9090);
288
const buffered = new thrift.TBufferedTransport(socket);
289
const framed = new thrift.TFramedTransport(buffered);
290

291
// Use the layered transport with protocol
292
const protocol = new thrift.TBinaryProtocol(framed);
293

294
// Benefits:
295
// - Socket provides network I/O
296
// - Buffered improves I/O efficiency  
297
// - Framed ensures message boundaries
298
// - Protocol handles serialization
299
```
300

301
## Transport Selection Guidelines
302

303
```javascript { .api }
304
// Transport selection criteria and use cases
305
interface TransportSelection {
306
  TBufferedTransport: {
307
    performance: 'High',
308
    reliability: 'Good',
309
    useCase: 'General purpose, most common choice'
310
  };
311
  
312
  TFramedTransport: {
313
    performance: 'High',
314
    reliability: 'Excellent',
315
    useCase: 'Stream protocols, message boundaries required'
316
  };
317
  
318
  TWSTransport: {
319
    performance: 'Good',
320
    reliability: 'Good',
321
    useCase: 'Real-time communication, browser compatibility'
322
  };
323
  
324
  TMemoryBuffer: {
325
    performance: 'Highest',
326
    reliability: 'Excellent',
327
    useCase: 'Testing, debugging, in-memory processing'
328
  };
329
}
330
```