@pyrokine/mcp-ssh 2.4.0 → 2.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,12 +5,23 @@ export const DEFAULT_OPERATION_READ_BYTES = 64 * 1024;
5
5
  export const HARD_OPERATION_READ_BYTES = 1024 * 1024;
6
6
  export const DEFAULT_OPERATION_RETENTION_MS = 60 * 60_000;
7
7
  export const MAX_OPERATION_RETENTION_MS = 24 * 60 * 60_000;
8
+ export const DEFAULT_OPERATION_START_TIMEOUT_MS = 30_000;
9
+ export const MAX_OPERATION_START_TIMEOUT_MS = 600_000;
10
+ export class OperationStartError extends Error {
11
+ details;
12
+ constructor(message, details) {
13
+ super(message);
14
+ this.details = details;
15
+ this.name = 'OperationStartError';
16
+ }
17
+ }
8
18
  const MARKER_PREFIX = '__MCP_SSH_OPERATION__';
9
19
  const MARKER_LINE_LIMIT = 512;
10
20
  export class OperationManager {
11
21
  dependencies;
12
22
  now;
13
23
  operations = new Map();
24
+ pendingStarts = new Map();
14
25
  sweeper;
15
26
  constructor(dependencies, now = Date.now) {
16
27
  this.dependencies = dependencies;
@@ -19,11 +30,20 @@ export class OperationManager {
19
30
  this.sweeper.unref?.();
20
31
  }
21
32
  async start(alias, command, options = {}) {
33
+ const pendingOperationId = this.pendingStarts.get(alias);
34
+ if (pendingOperationId) {
35
+ throw new OperationStartError(`Alias '${alias}' already has an operation start awaiting SSH channel setup`, {
36
+ alias,
37
+ operationId: pendingOperationId,
38
+ retryable: true,
39
+ suggestion: '等待当前 operation start 完成,或断开该 alias 以释放未完成的 SSH channel request',
40
+ });
41
+ }
22
42
  const operationId = `op_${randomUUID()}`;
23
43
  const marker = randomBytes(32).toString('hex');
24
44
  const maxOutputBytes = this.normalizeMaxOutputBytes(options.maxOutputBytes);
25
45
  const retentionMs = this.normalizeRetentionMs(options.retentionMs);
26
- const stream = await this.dependencies.openStream(alias, command, marker, options);
46
+ const startTimeoutMs = this.normalizeStartTimeoutMs(options.startTimeoutMs);
27
47
  const record = {
28
48
  operationId,
29
49
  alias,
@@ -50,11 +70,74 @@ export class OperationManager {
50
70
  stderrTruncated: false,
51
71
  maxOutputBytes,
52
72
  markerBuffer: Buffer.alloc(0),
53
- stream,
54
- options: { ...options, maxOutputBytes, retentionMs },
73
+ options: { ...options, maxOutputBytes, retentionMs, startTimeoutMs },
55
74
  };
56
75
  this.operations.set(operationId, record);
57
- this.attachStream(record);
76
+ this.pendingStarts.set(alias, operationId);
77
+ const opening = this.dependencies.openStream(alias, command, marker, record.options, (stream) => {
78
+ if (record.stream) {
79
+ stream.destroy();
80
+ throw new Error('Operation stream was adopted more than once');
81
+ }
82
+ if (record.finishedAt !== null) {
83
+ stream.destroy();
84
+ throw new Error('Operation stream arrived after operation start finished');
85
+ }
86
+ record.stream = stream;
87
+ this.attachStream(record, stream);
88
+ });
89
+ void opening.then(() => this.clearPendingStart(alias, operationId), () => this.clearPendingStart(alias, operationId));
90
+ let timer;
91
+ try {
92
+ await Promise.race([
93
+ opening,
94
+ new Promise((_resolve, reject) => {
95
+ timer = setTimeout(() => {
96
+ reject(new OperationStartError(`Operation start timed out after ${startTimeoutMs}ms`, {
97
+ alias,
98
+ operationId,
99
+ startTimeoutMs,
100
+ status: 'unknown',
101
+ retryable: false,
102
+ suggestion: 'SSH channel request 状态无法确认;使用 ssh_operation_status 查询记录,必要时 ssh_disconnect 释放底层 pending channel',
103
+ }));
104
+ }, startTimeoutMs);
105
+ }),
106
+ ]);
107
+ }
108
+ catch (error) {
109
+ if (record.finishedAt === null) {
110
+ record.status = error instanceof OperationStartError ? 'unknown' : 'failed';
111
+ record.error = error instanceof Error ? error.message : String(error);
112
+ this.finish(record);
113
+ }
114
+ record.stream?.destroy();
115
+ if (error instanceof OperationStartError) {
116
+ throw error;
117
+ }
118
+ throw new OperationStartError(record.error ?? 'Operation start failed', {
119
+ alias,
120
+ operationId,
121
+ status: record.status,
122
+ retryable: false,
123
+ });
124
+ }
125
+ finally {
126
+ if (timer) {
127
+ clearTimeout(timer);
128
+ }
129
+ }
130
+ if (!record.stream) {
131
+ record.status = 'failed';
132
+ record.error = 'Operation stream was not adopted';
133
+ this.finish(record);
134
+ throw new OperationStartError(record.error, {
135
+ alias,
136
+ operationId,
137
+ status: record.status,
138
+ retryable: false,
139
+ });
140
+ }
58
141
  return this.info(record);
59
142
  }
60
143
  status(operationId) {
@@ -143,6 +226,7 @@ export class OperationManager {
143
226
  .map((record) => this.info(record));
144
227
  }
145
228
  markAliasDisconnected(alias) {
229
+ this.pendingStarts.delete(alias);
146
230
  for (const record of this.operations.values()) {
147
231
  if (record.alias === alias && (record.status === 'starting' || record.status === 'running')) {
148
232
  record.status = 'unknown';
@@ -162,22 +246,22 @@ export class OperationManager {
162
246
  close() {
163
247
  clearInterval(this.sweeper);
164
248
  }
165
- attachStream(record) {
166
- record.stream.on('data', (data) => {
249
+ attachStream(record, stream) {
250
+ stream.on('data', (data) => {
167
251
  record.stdoutBytes += data.length;
168
252
  this.appendOutput(record, 'stdout', data);
169
253
  });
170
- record.stream.stderr.on('data', (data) => {
254
+ stream.stderr.on('data', (data) => {
171
255
  this.consumeMarker(record, data);
172
256
  });
173
- record.stream.on('error', (error) => {
257
+ stream.on('error', (error) => {
174
258
  if (record.cancelInFlight) {
175
259
  record.pendingTermination ??= { type: 'error', error };
176
260
  return;
177
261
  }
178
262
  this.finishStreamError(record, error);
179
263
  });
180
- record.stream.on('close', (code, signal) => {
264
+ stream.on('close', (code, signal) => {
181
265
  const close = { type: 'close', code, signal: signal ?? null };
182
266
  if (record.cancelInFlight) {
183
267
  record.pendingTermination ??= close;
@@ -202,6 +286,7 @@ export class OperationManager {
202
286
  if (record.status === 'unknown' || record.finishedAt !== null) {
203
287
  return;
204
288
  }
289
+ this.flushMarkerBuffer(record);
205
290
  record.status = 'failed';
206
291
  record.error = error.message;
207
292
  this.finish(record);
@@ -212,12 +297,13 @@ export class OperationManager {
212
297
  }
213
298
  record.exitCode = code;
214
299
  record.signal = signal;
300
+ this.flushMarkerBuffer(record);
215
301
  if (record.cancelRequested) {
216
302
  record.status = 'cancelled';
217
303
  }
218
304
  else if (!record.markerVerified) {
219
305
  record.status = 'failed';
220
- record.error = 'Remote operation exited before its marker was verified';
306
+ record.error ??= 'Remote operation exited before its marker was verified';
221
307
  }
222
308
  else {
223
309
  record.status = code === 0 ? 'completed' : 'failed';
@@ -225,49 +311,94 @@ export class OperationManager {
225
311
  this.finish(record);
226
312
  }
227
313
  consumeMarker(record, data) {
228
- if (record.markerVerified) {
229
- record.stderrBytes += data.length;
230
- this.appendOutput(record, 'stderr', data);
314
+ if (record.markerVerified || record.status !== 'starting') {
315
+ this.appendStderr(record, data);
231
316
  return;
232
317
  }
318
+ const markerPrefix = Buffer.from(MARKER_PREFIX);
233
319
  record.markerBuffer = Buffer.concat([record.markerBuffer, data]);
234
- const newline = record.markerBuffer.indexOf(0x0a);
235
- if (newline < 0) {
236
- if (record.markerBuffer.length > MARKER_LINE_LIMIT) {
237
- record.status = 'failed';
238
- record.error = 'Remote operation marker exceeded the allowed length';
239
- record.stderrBytes += record.markerBuffer.length;
240
- this.appendOutput(record, 'stderr', record.markerBuffer);
320
+ while (!record.markerVerified) {
321
+ const markerIndex = record.markerBuffer.indexOf(markerPrefix);
322
+ if (markerIndex > 0) {
323
+ this.appendStderr(record, record.markerBuffer.subarray(0, markerIndex));
324
+ record.markerBuffer = record.markerBuffer.subarray(markerIndex);
325
+ continue;
326
+ }
327
+ if (markerIndex < 0) {
328
+ const newline = record.markerBuffer.indexOf(0x0a);
329
+ if (newline >= 0) {
330
+ this.appendStderr(record, record.markerBuffer.subarray(0, newline + 1));
331
+ record.markerBuffer = record.markerBuffer.subarray(newline + 1);
332
+ continue;
333
+ }
334
+ const retainedBytes = Math.min(record.markerBuffer.length, markerPrefix.length - 1);
335
+ const streamedBytes = record.markerBuffer.length - retainedBytes;
336
+ if (streamedBytes > 0) {
337
+ this.appendStderr(record, record.markerBuffer.subarray(0, streamedBytes));
338
+ record.markerBuffer = record.markerBuffer.subarray(streamedBytes);
339
+ }
340
+ return;
341
+ }
342
+ const newline = record.markerBuffer.indexOf(0x0a);
343
+ if (newline < 0) {
344
+ if (record.markerBuffer.length > MARKER_LINE_LIMIT) {
345
+ this.appendStderr(record, record.markerBuffer);
346
+ record.markerBuffer = Buffer.alloc(0);
347
+ this.failMarker(record, 'Remote operation marker exceeded the allowed length');
348
+ }
349
+ return;
350
+ }
351
+ const lineBytes = record.markerBuffer.subarray(0, newline + 1);
352
+ const line = record.markerBuffer.subarray(0, newline).toString('utf8').trim();
353
+ record.markerBuffer = record.markerBuffer.subarray(newline + 1);
354
+ if (newline > MARKER_LINE_LIMIT) {
355
+ this.appendStderr(record, lineBytes);
356
+ this.appendStderr(record, record.markerBuffer);
241
357
  record.markerBuffer = Buffer.alloc(0);
358
+ this.failMarker(record, 'Remote operation marker exceeded the allowed length');
359
+ return;
242
360
  }
243
- return;
244
- }
245
- const line = record.markerBuffer.subarray(0, newline).toString('utf8').trim();
246
- const remainder = record.markerBuffer.subarray(newline + 1);
247
- record.markerBuffer = Buffer.alloc(0);
248
- const expectedPrefix = `${MARKER_PREFIX}:${record.marker}:`;
249
- if (!line.startsWith(expectedPrefix)) {
250
- record.status = 'failed';
251
- record.error = 'Remote operation marker did not match the local operation';
252
- const invalidMarker = Buffer.from(`${line}\n`);
253
- record.stderrBytes += invalidMarker.length + remainder.length;
254
- this.appendOutput(record, 'stderr', invalidMarker);
255
- this.appendOutput(record, 'stderr', remainder);
256
- return;
361
+ const expectedPrefix = `${MARKER_PREFIX}:${record.marker}:`;
362
+ if (!line.startsWith(expectedPrefix)) {
363
+ this.appendStderr(record, lineBytes);
364
+ this.appendStderr(record, record.markerBuffer);
365
+ record.markerBuffer = Buffer.alloc(0);
366
+ this.failMarker(record, 'Remote operation marker did not match the local operation');
367
+ return;
368
+ }
369
+ const metadata = line.slice(expectedPrefix.length).match(/^([1-9]\d*):(0|1)$/);
370
+ const pid = metadata ? Number(metadata[1]) : Number.NaN;
371
+ if (!metadata || !Number.isSafeInteger(pid)) {
372
+ this.appendStderr(record, lineBytes);
373
+ this.appendStderr(record, record.markerBuffer);
374
+ record.markerBuffer = Buffer.alloc(0);
375
+ this.failMarker(record, 'Remote operation marker contained invalid process metadata');
376
+ return;
377
+ }
378
+ record.pid = pid;
379
+ record.processGroup = metadata[2] === '1';
380
+ record.markerVerified = true;
381
+ record.status = 'running';
382
+ this.appendStderr(record, record.markerBuffer);
383
+ record.markerBuffer = Buffer.alloc(0);
257
384
  }
258
- const [pidText, groupText] = line.slice(expectedPrefix.length).split(':');
259
- const pid = Number(pidText);
260
- if (!Number.isSafeInteger(pid) || pid <= 0 || (groupText !== '0' && groupText !== '1')) {
261
- record.status = 'failed';
262
- record.error = 'Remote operation marker contained invalid process metadata';
385
+ }
386
+ failMarker(record, error) {
387
+ record.status = 'failed';
388
+ record.error = error;
389
+ this.finish(record);
390
+ record.stream?.destroy();
391
+ }
392
+ flushMarkerBuffer(record) {
393
+ if (record.markerBuffer.length === 0) {
263
394
  return;
264
395
  }
265
- record.pid = pid;
266
- record.processGroup = groupText === '1';
267
- record.markerVerified = true;
268
- record.status = 'running';
269
- record.stderrBytes += remainder.length;
270
- this.appendOutput(record, 'stderr', remainder);
396
+ this.appendStderr(record, record.markerBuffer);
397
+ record.markerBuffer = Buffer.alloc(0);
398
+ }
399
+ appendStderr(record, data) {
400
+ record.stderrBytes += data.length;
401
+ this.appendOutput(record, 'stderr', data);
271
402
  }
272
403
  appendOutput(record, stream, data) {
273
404
  const storedBytes = record.stdout.length + record.stderr.length;
@@ -315,6 +446,11 @@ export class OperationManager {
315
446
  ...(record.error ? { error: record.error } : {}),
316
447
  };
317
448
  }
449
+ clearPendingStart(alias, operationId) {
450
+ if (this.pendingStarts.get(alias) === operationId) {
451
+ this.pendingStarts.delete(alias);
452
+ }
453
+ }
318
454
  requireOperation(operationId) {
319
455
  this.sweepExpired();
320
456
  const record = this.operations.get(operationId);
@@ -344,6 +480,13 @@ export class OperationManager {
344
480
  }
345
481
  return normalized;
346
482
  }
483
+ normalizeStartTimeoutMs(value) {
484
+ const normalized = value ?? DEFAULT_OPERATION_START_TIMEOUT_MS;
485
+ if (!Number.isSafeInteger(normalized) || normalized <= 0 || normalized > MAX_OPERATION_START_TIMEOUT_MS) {
486
+ throw new Error(`startTimeoutMs must be between 1 and ${MAX_OPERATION_START_TIMEOUT_MS}`);
487
+ }
488
+ return normalized;
489
+ }
347
490
  normalizeOffset(value, length, field) {
348
491
  const normalized = value ?? 0;
349
492
  if (!Number.isSafeInteger(normalized) || normalized < 0 || normalized > length) {
@@ -20,10 +20,23 @@ interface SSHSession {
20
20
  /** 当前正在等待的重连定时器,disconnect 时需要清除以防 zombie 重连 */
21
21
  reconnectTimer?: NodeJS.Timeout;
22
22
  }
23
+ interface SessionConnectionInfo {
24
+ alias: string;
25
+ identity: string;
26
+ loginUser: string;
27
+ runAs?: string;
28
+ host: string;
29
+ port: number;
30
+ defaultEnvKeys: string[];
31
+ envKeys: string[];
32
+ hasJumpHost: boolean;
33
+ }
23
34
  export declare class SessionManager {
24
35
  private sessions;
25
36
  /** per-alias connect 进行中的 Promise,防止并发 connect 同一 alias 时重复建连 */
26
37
  private connectInFlight;
38
+ private pendingConnections;
39
+ private connectionGenerations;
27
40
  private readonly ptyManager;
28
41
  private readonly forwardManager;
29
42
  private readonly operationManager;
@@ -55,6 +68,7 @@ export declare class SessionManager {
55
68
  getSession(alias: string): SSHSession;
56
69
  listSessions(): SSHSessionBrief[];
57
70
  listSessionDetails(): SSHSessionDetail[];
71
+ getSessionConnectionInfo(alias: string): SessionConnectionInfo;
58
72
  getExternalTransferCapability(alias: string): ExternalTransferCapability;
59
73
  /**
60
74
  * 执行命令
@@ -114,13 +128,17 @@ export declare class SessionManager {
114
128
  forwardId: string;
115
129
  localPort: number;
116
130
  }>;
117
- forwardRemote(alias: string, remotePort: number, localHost: string, localPort: number, remoteHost?: string): Promise<string>;
131
+ forwardRemote(alias: string, remotePort: number, localHost: string, localPort: number, remoteHost?: string): Promise<{
132
+ forwardId: string;
133
+ remotePort: number;
134
+ }>;
118
135
  forwardClose(forwardId: string, options?: ForwardCloseOptions): Promise<ForwardCloseResult>;
119
136
  forwardList(): PortForwardInfo[];
120
137
  private isSshAgentAvailable;
121
138
  private isOpenSshKeyPathUsable;
122
139
  private sessionIdentity;
123
140
  private configIdentity;
141
+ private connectionFingerprint;
124
142
  private resultMetadata;
125
143
  private appendOutputTail;
126
144
  private recommendedReadCommand;
@@ -144,10 +162,17 @@ export declare class SessionManager {
144
162
  * 通过跳板机转发连接
145
163
  */
146
164
  private forwardConnection;
165
+ private getConnectionGeneration;
166
+ private isCurrentPendingConnection;
167
+ private cancelPendingConnection;
168
+ private invalidateAliasResources;
147
169
  /**
148
170
  * 检查连接是否存活
149
171
  */
150
172
  private isAlive;
173
+ private isCurrentSession;
174
+ private closeClientChannel;
175
+ private destroySftp;
151
176
  /**
152
177
  * 调度自动重连(支持多次重试)
153
178
  */