0
# Transport
1

2
Transport configuration and message handling for different communication channels between client and server.
3

4
## Capabilities
5

6
### Transport Types (Node.js)
7

8
Configuration for various transport mechanisms in Node.js environments.
9

10
```typescript { .api }
11
/**
12
 * Available transport mechanisms for Node.js
13
 */
14
enum TransportKind {
15
  /** Standard input/output streams */
16
  stdio,
17
  /** Inter-process communication */
18
  ipc,
19
  /** Named pipes */
20
  pipe,
21
  /** TCP sockets */
22
  socket
23
}
24

25
/**
26
 * Transport configuration union type
27
 */
28
type Transport = SocketTransport | { kind: TransportKind.stdio | TransportKind.ipc | TransportKind.pipe };
29

30
/**
31
 * Socket transport configuration
32
 */
33
interface SocketTransport {
34
  /** Transport type identifier */
35
  kind: TransportKind.socket;
36
  /** Port number for socket connection */
37
  port: number;
38
}
39
```
40

41
**Usage Examples:**
42

43
Standard I/O transport:
44

45
```typescript
46
const serverOptions: ServerOptions = {
47
  command: 'language-server',
48
  transport: TransportKind.stdio
49
};
50
```
51

52
Socket transport:
53

54
```typescript
55
const serverOptions: ServerOptions = {
56
  command: 'language-server',
57
  transport: { kind: TransportKind.socket, port: 8080 }
58
};
59
```
60

61
IPC transport:
62

63
```typescript
64
const serverOptions: ServerOptions = {
65
  module: './server.js',
66
  transport: TransportKind.ipc
67
};
68
```
69

70
### Executable Configuration
71

72
Configuration for running language servers as external executables.
73

74
```typescript { .api }
75
/**
76
 * Configuration for executable language servers
77
 */
78
interface Executable {
79
  /** Command to execute (e.g., 'node', 'python', 'java') */
80
  command: string;
81
  
82
  /** Command line arguments passed to the executable */
83
  args?: string[];
84
  
85
  /** Transport mechanism for communication */
86
  transport?: Transport;
87
  
88
  /** Additional execution options */
89
  options?: ExecutableOptions;
90
}
91

92
/**
93
 * Options for executable processes
94
 */
95
interface ExecutableOptions {
96
  /** Current working directory for the process */
97
  cwd?: string;
98
  
99
  /** Environment variables for the process */
100
  env?: NodeJS.ProcessEnv;
101
  
102
  /** Whether to detach the process */
103
  detached?: boolean;
104
  
105
  /** Shell to use for command execution */
106
  shell?: boolean | string;
107
}
108
```
109

110
**Usage Examples:**
111

112
Simple executable:
113

114
```typescript
115
const executable: Executable = {
116
  command: 'my-language-server',
117
  args: ['--stdio', '--log-level', 'info']
118
};
119
```
120

121
Executable with custom environment:
122

123
```typescript
124
const executable: Executable = {
125
  command: 'java',
126
  args: ['-jar', 'language-server.jar'],
127
  options: {
128
    cwd: '/path/to/server',
129
    env: {
130
      ...process.env,
131
      JAVA_OPTS: '-Xmx512m'
132
    }
133
  }
134
};
135
```
136

137
### Node Module Configuration
138

139
Configuration for language servers implemented as Node.js modules.
140

141
```typescript { .api }
142
/**
143
 * Configuration for Node.js module language servers
144
 */
145
interface NodeModule {
146
  /** Path to the Node.js module (relative or absolute) */
147
  module: string;
148
  
149
  /** Arguments passed to the module */
150
  args?: string[];
151
  
152
  /** Transport mechanism for communication */
153
  transport?: Transport;
154
  
155
  /** Node.js runtime executable path (defaults to 'node') */
156
  runtime?: string;
157
  
158
  /** Fork options for the child process */
159
  options?: ForkOptions;
160
}
161

162
/**
163
 * Options for forking Node.js processes
164
 */
165
interface ForkOptions {
166
  /** Current working directory */
167
  cwd?: string;
168
  
169
  /** Environment variables */
170
  env?: NodeJS.ProcessEnv;
171
  
172
  /** Additional execution arguments for Node.js runtime */
173
  execArgv?: string[];
174
  
175
  /** Whether to use silent mode */
176
  silent?: boolean;
177
  
178
  /** File descriptors for stdio */
179
  stdio?: string | string[];
180
  
181
  /** Whether to detach the process */
182
  detached?: boolean;
183
  
184
  /** User ID to run the process as */
185
  uid?: number;
186
  
187
  /** Group ID to run the process as */
188
  gid?: number;
189
}
190
```
191

192
**Usage Examples:**
193

194
Basic Node module:
195

196
```typescript
197
const nodeModule: NodeModule = {
198
  module: './dist/server.js',
199
  transport: TransportKind.ipc
200
};
201
```
202

203
Node module with custom runtime:
204

205
```typescript
206
const nodeModule: NodeModule = {
207
  module: 'typescript-language-server',
208
  args: ['--stdio'],
209
  runtime: '/usr/local/bin/node',
210
  options: {
211
    env: { ...process.env, TS_NODE_PROJECT: './tsconfig.json' }
212
  }
213
};
214
```
215

216
### Stream Information
217

218
Direct stream configuration for custom transport scenarios.
219

220
```typescript { .api }
221
/**
222
 * Stream-based communication configuration
223
 */
224
interface StreamInfo {
225
  /** Writable stream for sending messages to server */
226
  writer: NodeJS.WritableStream;
227
  
228
  /** Readable stream for receiving messages from server */
229
  reader: NodeJS.ReadableStream;
230
  
231
  /** Whether the streams are detached from client lifecycle */
232
  detached?: boolean;
233
}
234

235
/**
236
 * Child process information with metadata
237
 */
238
interface ChildProcessInfo {
239
  /** The spawned child process */
240
  process: ChildProcess;
241
  
242
  /** Whether the process is detached from client lifecycle */
243
  detached?: boolean;
244
}
245
```
246

247
**Usage Examples:**
248

249
Custom stream setup:
250

251
```typescript
252
import { spawn } from 'child_process';
253

254
const serverProcess = spawn('my-server', ['--pipe']);
255
const streamInfo: StreamInfo = {
256
  reader: serverProcess.stdout,
257
  writer: serverProcess.stdin,
258
  detached: false
259
};
260
```
261

262
### Message Transports
263

264
Low-level message transport interfaces for custom communication.
265

266
```typescript { .api }
267
/**
268
 * Message transport configuration
269
 */
270
interface MessageTransports {
271
  /** Message reader for receiving from server */
272
  reader: MessageReader;
273
  
274
  /** Message writer for sending to server */
275
  writer: MessageWriter;
276
  
277
  /** Whether the transport is detached from client lifecycle */
278
  detached?: boolean;
279
}
280

281
/**
282
 * Interface for reading LSP messages
283
 */
284
interface MessageReader {
285
  /** Event fired when a message is received */
286
  readonly onError: Event<Error>;
287
  
288
  /** Event fired when the reader is closed */
289
  readonly onClose: Event<void>;
290
  
291
  /** Event fired when a partial message is received */
292
  readonly onPartialMessage: Event<PartialMessageInfo>;
293
  
294
  /** Start listening for messages */
295
  listen(callback: DataCallback): Disposable;
296
  
297
  /** Dispose the reader */
298
  dispose(): void;
299
}
300

301
/**
302
 * Interface for writing LSP messages
303
 */
304
interface MessageWriter {
305
  /** Event fired when an error occurs during writing */
306
  readonly onError: Event<[Error, Message | undefined, number | undefined]>;
307
  
308
  /** Event fired when the writer is closed */
309
  readonly onClose: Event<void>;
310
  
311
  /** Write a message */
312
  write(msg: Message): Promise<void>;
313
  
314
  /** End the writer */
315
  end(): void;
316
  
317
  /** Dispose the writer */
318
  dispose(): void;
319
}
320
```
321

322
### Browser Transport
323

324
Browser-specific transport using Web Workers.
325

326
```typescript { .api }
327
/**
328
 * Browser message reader using Web Worker communication
329
 */
330
class BrowserMessageReader implements MessageReader {
331
  constructor(worker: Worker);
332
  
333
  readonly onError: Event<Error>;
334
  readonly onClose: Event<void>;
335
  readonly onPartialMessage: Event<PartialMessageInfo>;
336
  
337
  listen(callback: DataCallback): Disposable;
338
  dispose(): void;
339
}
340

341
/**
342
 * Browser message writer using Web Worker communication
343
 */
344
class BrowserMessageWriter implements MessageWriter {
345
  constructor(worker: Worker);
346
  
347
  readonly onError: Event<[Error, Message | undefined, number | undefined]>;
348
  readonly onClose: Event<void>;
349
  
350
  write(msg: Message): Promise<void>;
351
  end(): void;
352
  dispose(): void;
353
}
354
```
355

356
**Usage Examples:**
357

358
Browser client with Web Worker:
359

360
```typescript
361
import { LanguageClient, BrowserMessageReader, BrowserMessageWriter } from "vscode-languageclient/browser";
362

363
const worker = new Worker('./language-server-worker.js');
364

365
const client = new LanguageClient(
366
  'browser-client',
367
  'Browser Language Client',
368
  clientOptions,
369
  worker
370
);
371
```
372

373
### Transport Utilities
374

375
Utility functions for creating transport instances.
376

377
```typescript { .api }
378
/**
379
 * Create client pipe transport for named pipe communication
380
 */
381
function createClientPipeTransport(pipeName: string, encoding?: string): Promise<MessageTransports>;
382

383
/**
384
 * Generate a random pipe name for IPC
385
 */
386
function generateRandomPipeName(): string;
387

388
/**
389
 * Create client socket transport for TCP communication
390
 */
391
function createClientSocketTransport(port: number, encoding?: string): Promise<MessageTransports>;
392

393
/**
394
 * Stream message reader for Node.js streams
395
 */
396
class StreamMessageReader implements MessageReader {
397
  constructor(readable: NodeJS.ReadableStream, encoding?: string);
398
}
399

400
/**
401
 * Stream message writer for Node.js streams
402
 */
403
class StreamMessageWriter implements MessageWriter {
404
  constructor(writable: NodeJS.WritableStream, encoding?: string);
405
}
406

407
/**
408
 * IPC message reader for inter-process communication
409
 */
410
class IPCMessageReader implements MessageReader {
411
  constructor(process: NodeJS.Process | ChildProcess);
412
}
413

414
/**
415
 * IPC message writer for inter-process communication
416
 */
417
class IPCMessageWriter implements MessageWriter {
418
  constructor(process: NodeJS.Process | ChildProcess);
419
}
420
```
421

422
**Usage Examples:**
423

424
Custom pipe transport:
425

426
```typescript
427
const pipeName = generateRandomPipeName();
428
const transport = await createClientPipeTransport(pipeName);
429

430
const client = new LanguageClient(
431
  'pipe-client',
432
  'Pipe Language Client',
433
  () => Promise.resolve(transport),
434
  clientOptions
435
);
436
```
437

438
Socket transport:
439

440
```typescript
441
const transport = await createClientSocketTransport(8080);
442

443
const client = new LanguageClient(
444
  'socket-client', 
445
  'Socket Language Client',
446
  () => Promise.resolve(transport),
447
  clientOptions
448
);
449
```