@pyrokine/mcp-ssh 3.2.0 → 3.3.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.
package/dist/file-ops.js CHANGED
@@ -6,17 +6,19 @@ import { createHash, randomBytes } from 'crypto';
6
6
  import * as fs from 'fs';
7
7
  import { Readable } from 'node:stream';
8
8
  import { StringDecoder } from 'node:string_decoder';
9
+ import { setTimeout as delay } from 'node:timers/promises';
9
10
  import * as os from 'os';
10
11
  import * as path from 'path';
12
+ import { Transform } from 'stream';
11
13
  import { matchesDirectoryExclude } from './directory-verification.js';
12
14
  import { extractFileMode, FILE_CREATE_MODE_MASK, formatFileMode, formatFilePermissions } from './file-mode.js';
13
15
  import { OpenSshError } from './openssh.js';
14
16
  import { encodedPowershell, remoteDirname, remoteJoin, remoteNormalize, remotePathModule, remoteShellPath, windowsCaseSemanticsScript, } from './remote-platform.js';
15
17
  import { sessionManager } from './session-manager.js';
16
- import { SftpOperationTimeoutError, SftpWriteState, sftpOperationOutcome, withSftpOperationTimeout, } from './sftp-timeout.js';
18
+ import { sftpOperationOutcome, SftpOperationTimeoutError, SftpWriteState, withSftpOperationTimeout, } from './sftp-timeout.js';
17
19
  import { escapeShellArg, expandTilde } from './tools/utils.js';
18
20
  import { ensureUtf8Boundary, isUtf8ContinuationByte } from './utf8.js';
19
- import { checkWindowsAcl, windowsAclScript } from './windows-acl.js';
21
+ import { checkWindowsAcl, getWindowsPowerShellEnv, windowsAclScript } from './windows-acl.js';
20
22
  // 文件类型 mode 常量
21
23
  const S_IFMT = 0o170000; // 文件类型位掩码
22
24
  const S_IFDIR = 0o40000;
@@ -34,7 +36,7 @@ function appendLimitedOutput(current, chunk) {
34
36
  }
35
37
  return (current + chunk).slice(0, LOCAL_PROCESS_OUTPUT_LIMIT);
36
38
  }
37
- function runLocalProcess(command, args, timeout, env, connection, onStdout) {
39
+ function runLocalProcess(command, args, timeout, env, connection, onStdout, signal) {
38
40
  return new Promise((resolve) => {
39
41
  let stdout = '';
40
42
  let stderr = '';
@@ -42,17 +44,19 @@ function runLocalProcess(command, args, timeout, env, connection, onStdout) {
42
44
  let stdoutTruncated = false;
43
45
  let settled = false;
44
46
  let timedOut = false;
47
+ let cancelled = false;
48
+ throwIfAborted(signal);
45
49
  let killTimer;
46
50
  connection?.assertCurrent();
47
51
  const child = spawn(command, args, {
48
52
  stdio: ['ignore', 'pipe', 'pipe'],
49
53
  env: env ?? process.env,
50
54
  windowsHide: true,
51
- detached: connection !== undefined,
55
+ detached: process.platform !== 'win32',
52
56
  });
53
- connection?.trackProcess(child, true);
57
+ connection?.trackProcess(child, process.platform !== 'win32');
54
58
  const kill = (signal) => {
55
- if (connection && child.pid) {
59
+ if (process.platform !== 'win32' && child.pid) {
56
60
  try {
57
61
  process.kill(-child.pid, signal);
58
62
  }
@@ -66,11 +70,26 @@ function runLocalProcess(command, args, timeout, env, connection, onStdout) {
66
70
  child.kill(signal);
67
71
  }
68
72
  };
69
- const timer = setTimeout(() => {
70
- timedOut = true;
73
+ const stop = () => {
74
+ if (settled || killTimer) {
75
+ return;
76
+ }
71
77
  kill('SIGTERM');
72
78
  killTimer = setTimeout(() => kill('SIGKILL'), 5000);
79
+ };
80
+ const onAbort = () => {
81
+ cancelled = true;
82
+ timedOut ||= signal?.reason instanceof SftpOperationTimeoutError;
83
+ stop();
84
+ };
85
+ const timer = setTimeout(() => {
86
+ timedOut = true;
87
+ stop();
73
88
  }, timeout);
89
+ signal?.addEventListener('abort', onAbort, { once: true });
90
+ if (signal?.aborted) {
91
+ onAbort();
92
+ }
74
93
  child.stdout.on('data', (chunk) => {
75
94
  const text = stdoutDecoder.write(chunk);
76
95
  onStdout?.(text);
@@ -86,11 +105,12 @@ function runLocalProcess(command, args, timeout, env, connection, onStdout) {
86
105
  }
87
106
  settled = true;
88
107
  clearTimeout(timer);
108
+ signal?.removeEventListener('abort', onAbort);
89
109
  if (killTimer) {
90
110
  clearTimeout(killTimer);
91
111
  }
92
112
  onStdout?.(stdoutDecoder.end(), true);
93
- resolve({ status: null, stdout, stderr, error, timedOut, stdoutTruncated });
113
+ resolve({ status: null, stdout, stderr, error, timedOut, cancelled, stdoutTruncated });
94
114
  });
95
115
  child.on('close', (status) => {
96
116
  if (settled) {
@@ -98,6 +118,7 @@ function runLocalProcess(command, args, timeout, env, connection, onStdout) {
98
118
  }
99
119
  settled = true;
100
120
  clearTimeout(timer);
121
+ signal?.removeEventListener('abort', onAbort);
101
122
  if (killTimer) {
102
123
  clearTimeout(killTimer);
103
124
  }
@@ -105,7 +126,7 @@ function runLocalProcess(command, args, timeout, env, connection, onStdout) {
105
126
  onStdout?.(tail, true);
106
127
  stdoutTruncated ||= stdout.length + tail.length > LOCAL_PROCESS_OUTPUT_LIMIT;
107
128
  stdout = appendLimitedOutput(stdout, tail);
108
- resolve({ status, stdout, stderr, timedOut, stdoutTruncated });
129
+ resolve({ status, stdout, stderr, timedOut, cancelled, stdoutTruncated });
109
130
  });
110
131
  });
111
132
  }
@@ -566,7 +587,17 @@ export async function removeRemoteFile(alias, remotePath, timeout) {
566
587
  /**
567
588
  * 带进度追踪的流传输
568
589
  */
569
- function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, closeSftp = true, signal) {
590
+ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, closeSftp = true, signal, throttle) {
591
+ const originalReadStream = readStream;
592
+ if (throttle) {
593
+ const limiter = new Transform({
594
+ transform(chunk, _encoding, callback) {
595
+ void throttle(chunk.length).then(() => callback(null, chunk), callback);
596
+ },
597
+ });
598
+ originalReadStream.on('error', (error) => limiter.destroy(error));
599
+ readStream = originalReadStream.pipe(limiter);
600
+ }
570
601
  return new Promise((resolve, reject) => {
571
602
  let settled = false;
572
603
  const onAbort = () => cleanup(abortError(signal));
@@ -579,6 +610,7 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress,
579
610
  detachAbort();
580
611
  // 先解管道并强制销毁两端,避免错误后流仍持有 sftp 资源
581
612
  try {
613
+ originalReadStream.unpipe();
582
614
  readStream.unpipe(writeStream);
583
615
  }
584
616
  catch {
@@ -586,6 +618,7 @@ function pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress,
586
618
  }
587
619
  try {
588
620
  ;
621
+ originalReadStream.destroy?.(err);
589
622
  readStream.destroy?.(err);
590
623
  }
591
624
  catch {
@@ -668,7 +701,7 @@ export class UploadFileError extends Error {
668
701
  /**
669
702
  * 上传文件
670
703
  */
671
- export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp, createMode, signal, followSymlinks = false, exclusive = false, timeout) {
704
+ export async function uploadFile(alias, localPath, remotePath, onProgress, sharedSftp, createMode, signal, followSymlinks = false, exclusive = false, timeout, throttle) {
672
705
  const deadline = timeout === undefined ? undefined : Date.now() + timeout;
673
706
  throwIfAborted(signal);
674
707
  const source = followSymlinks
@@ -713,7 +746,7 @@ export async function uploadFile(alias, localPath, remotePath, onProgress, share
713
746
  writeStream.once('open', () => {
714
747
  state.remoteCreated = true;
715
748
  });
716
- const result = await withSftpDeadline(sftp, pipeWithProgress(fs.createReadStream(localPath), writeStream, sftp, totalSize, onProgress, !sharedSftp, signal), remainingSftpTimeout(deadline, signal), signal);
749
+ const result = await withSftpDeadline(sftp, pipeWithProgress(fs.createReadStream(localPath), writeStream, sftp, totalSize, onProgress, !sharedSftp, signal, throttle), remainingSftpTimeout(deadline, signal), signal);
717
750
  return { ...result, createMode: formatFileMode(safeCreateMode) };
718
751
  }
719
752
  catch (error) {
@@ -755,6 +788,7 @@ async function prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath
755
788
  const handle = await fs.promises.open(temporaryPath, 'wx', 0o600);
756
789
  await handle.close();
757
790
  if (checkWindowsAcl(temporaryPath, true) !== 'key_path_usable') {
791
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
758
792
  throw new Error('privacy_not_enforced_on_windows: temporary download file ACL could not ' + 'be verified');
759
793
  }
760
794
  }
@@ -786,7 +820,7 @@ async function prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath
786
820
  /**
787
821
  * 下载文件
788
822
  */
789
- export async function downloadFile(alias, remotePath, localPath, onProgress, sharedSftp, signal, timeout) {
823
+ export async function downloadFile(alias, remotePath, localPath, onProgress, sharedSftp, signal, timeout, throttle) {
790
824
  const deadline = timeout === undefined ? undefined : Date.now() + timeout;
791
825
  throwIfAborted(signal);
792
826
  localPath = expandTilde(localPath);
@@ -799,13 +833,15 @@ export async function downloadFile(alias, remotePath, localPath, onProgress, sha
799
833
  let localWriteStream;
800
834
  try {
801
835
  const { totalSize, readStream, writeStream } = await prepareDownloadTransfer(sftp, remotePath, localDir, temporaryPath, !sharedSftp, deadline, signal);
836
+ // noinspection JSUnusedAssignment -- read by the failure cleanup path
802
837
  localWriteStream = writeStream;
803
- const result = await withSftpDeadline(sftp, pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, !sharedSftp, signal), remainingSftpTimeout(deadline, signal), signal);
838
+ const result = await withSftpDeadline(sftp, pipeWithProgress(readStream, writeStream, sftp, totalSize, onProgress, !sharedSftp, signal, throttle), remainingSftpTimeout(deadline, signal), signal);
804
839
  if (process.platform !== 'win32') {
805
840
  await fs.promises.chmod(temporaryPath, preservedMode ?? 0o600);
806
841
  }
807
842
  remainingSftpTimeout(deadline, signal);
808
843
  validateLocalPathAgainstAllowList(localPath);
844
+ // noinspection JSUnusedAssignment -- read by the failure cleanup path
809
845
  failureStage = 'local_rename';
810
846
  await fs.promises.rename(temporaryPath, localPath);
811
847
  return { ...result, atomic: true };
@@ -1119,20 +1155,21 @@ export async function readFile(alias, remotePath, options) {
1119
1155
  const readOptions = normalizeReadFileOptions(options);
1120
1156
  validateReadFileOptions(readOptions);
1121
1157
  const sftp = await getSftpWithinDeadline(alias, readOptions.timeout);
1122
- let actualSize;
1158
+ let stats;
1123
1159
  try {
1124
- const stats = await sftpStat(sftp, remotePath, readOptions.timeout);
1125
- if ((stats.mode & S_IFMT) !== S_IFREG) {
1126
- throw new Error((stats.mode & S_IFMT) === S_IFDIR
1127
- ? 'Target is a directory; use ssh_list_dir to read its entries'
1128
- : 'Target is not a regular file');
1129
- }
1130
- actualSize = stats.size;
1160
+ stats = await sftpStat(sftp, remotePath, readOptions.timeout);
1131
1161
  }
1132
1162
  catch (error) {
1133
1163
  sftp.end();
1134
1164
  throw error;
1135
1165
  }
1166
+ if ((stats.mode & S_IFMT) !== S_IFREG) {
1167
+ sftp.end();
1168
+ throw new Error((stats.mode & S_IFMT) === S_IFDIR
1169
+ ? 'Target is a directory; use ssh_list_dir to read its entries'
1170
+ : 'Target is not a regular file');
1171
+ }
1172
+ const actualSize = stats.size;
1136
1173
  if (readOptions.lineRange) {
1137
1174
  return readLineRange(sftp, remotePath, actualSize, readOptions.maxBytes, readOptions.lineRange, readOptions.encoding ?? 'auto', readOptions.binary === true, readOptions.timeout);
1138
1175
  }
@@ -1192,7 +1229,8 @@ export async function readFile(alias, remotePath, options) {
1192
1229
  detected.startsWith('utf16') &&
1193
1230
  !readOptions.tail &&
1194
1231
  requestedOffset % 2) {
1195
- throw new Error(`Invalid ${detected} offset is not a character boundary`);
1232
+ reject(new Error(`Invalid ${detected} offset is not a character boundary`));
1233
+ return;
1196
1234
  }
1197
1235
  let contentStart = 0;
1198
1236
  if (!readOptions.binary && detected === 'utf8' && readOptions.tail && requestedOffset > 0) {
@@ -1209,13 +1247,14 @@ export async function readFile(alias, remotePath, options) {
1209
1247
  const firstUnit = detected === 'utf16be'
1210
1248
  ? buffer.readUInt16BE(contentStart)
1211
1249
  : buffer.readUInt16LE(contentStart);
1212
- if (firstUnit >= 0xdc00 && firstUnit <= 0xdfff) {
1250
+ if (firstUnit >= 0xdc00 && firstUnit < 0xe000) {
1213
1251
  contentStart += 2;
1214
1252
  }
1215
1253
  }
1216
1254
  }
1217
1255
  if (!readOptions.binary && buffer.length > 0 && contentStart >= buffer.length) {
1218
- throw new Error(`maxBytes is too small to read a complete ${detected} tail character`);
1256
+ reject(new Error(`maxBytes is too small to read a complete ${detected} tail character`));
1257
+ return;
1219
1258
  }
1220
1259
  const decoded = decodeReadBuffer(buffer.subarray(contentStart), detected, readOptions.binary === true, requestedOffset + buffer.length < actualSize, requestedOffset + contentStart === 0);
1221
1260
  const contentBuffer = buffer.subarray(contentStart, contentStart + decoded.read_bytes);
@@ -1261,35 +1300,53 @@ export async function readFile(alias, remotePath, options) {
1261
1300
  readStream.once('error', (error) => finish(error));
1262
1301
  }), readOptions.timeout);
1263
1302
  }
1264
- export async function createEmptyRemoteFile(alias, remotePath, timeout) {
1265
- const sftp = await getSftpWithinDeadline(alias, timeout);
1303
+ export async function createEmptyRemoteFile(alias, remotePath, timeout, signal) {
1304
+ const deadline = timeout === undefined ? undefined : Date.now() + timeout;
1305
+ const sftp = await getSftpWithinDeadline(alias, remainingSftpTimeout(deadline, signal), signal);
1306
+ const state = new SftpWriteState(remotePath);
1266
1307
  try {
1267
1308
  await withSftpDeadline(sftp, new Promise((resolve, reject) => {
1268
- const stream = sftp.createWriteStream(remotePath, { flags: 'wx', mode: 0o600 });
1309
+ throwIfAborted(signal);
1310
+ const stream = state.track(sftp, signal).createWriteStream(remotePath, { flags: 'wx', mode: 0o600 });
1269
1311
  stream.once('error', reject);
1270
1312
  stream.once('close', resolve);
1271
1313
  stream.end();
1272
- }), timeout);
1314
+ }), remainingSftpTimeout(deadline, signal), signal);
1315
+ }
1316
+ catch (error) {
1317
+ throw new UploadFileError(error instanceof Error ? error.message : String(error), state.remoteCreated, {
1318
+ cause: error,
1319
+ details: state.outcome(error),
1320
+ });
1273
1321
  }
1274
1322
  finally {
1275
1323
  sftp.end();
1276
1324
  }
1277
1325
  }
1278
- export async function prepareWindowsRemotePrivateFile(alias, remotePath, timeout, shellPath = remotePath) {
1279
- await createEmptyRemoteFile(alias, remotePath, timeout);
1326
+ export async function prepareWindowsRemotePrivateFile(alias, remotePath, timeout, shellPath = remotePath, signal) {
1327
+ const deadline = timeout === undefined ? undefined : Date.now() + timeout;
1328
+ let created = false;
1280
1329
  try {
1330
+ await createEmptyRemoteFile(alias, remotePath, remainingSftpTimeout(deadline, signal), signal);
1331
+ created = true;
1332
+ throwIfAborted(signal);
1281
1333
  const acl = await sessionManager.exec(alias, encodedPowershell(windowsAclScript(shellPath, true)), {
1282
- timeout,
1334
+ timeout: remainingSftpTimeout(deadline, signal),
1335
+ signal,
1283
1336
  useLoginUser: true,
1284
1337
  maxOutputSize: 4096,
1285
1338
  });
1286
1339
  if (!acl.success || acl.stdout.trim() !== 'usable') {
1340
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1287
1341
  throw new Error('privacy_not_enforced_on_windows: remote temporary file ACL was not verified');
1288
1342
  }
1289
1343
  }
1290
1344
  catch (error) {
1345
+ if (!created && !(error instanceof UploadFileError && error.remoteCreated)) {
1346
+ throw error;
1347
+ }
1291
1348
  try {
1292
- await removeRemoteFile(alias, remotePath, timeout);
1349
+ await removeRemoteFile(alias, remotePath, Math.min(timeout ?? 30_000, 30_000));
1293
1350
  }
1294
1351
  catch (cleanupError) {
1295
1352
  throw new AggregateError([error, cleanupError], 'privacy_not_enforced_on_windows: remote ACL check and cleanup failed', { cause: cleanupError });
@@ -1300,20 +1357,25 @@ export async function prepareWindowsRemotePrivateFile(alias, remotePath, timeout
1300
1357
  /**
1301
1358
  * 写入远程文件
1302
1359
  */
1303
- export async function writeFile(alias, remotePath, content, append = false, timeout) {
1360
+ export async function writeFile(alias, remotePath, content, append = false, timeout, signal) {
1304
1361
  const state = new SftpWriteState(remotePath);
1305
- const sftp = await getSftpWithinDeadline(alias, timeout).catch((error) => {
1362
+ const sftp = await getSftpWithinDeadline(alias, timeout, signal).catch((error) => {
1306
1363
  throw new UploadFileError(error instanceof Error ? error.message : String(error), false, {
1307
1364
  cause: error,
1308
1365
  details: state.outcome(error),
1309
1366
  });
1310
1367
  });
1311
1368
  const contentBuffer = Buffer.from(content, 'utf-8');
1369
+ let writeStream;
1312
1370
  try {
1313
- const writeStream = state.track(sftp).createWriteStream(remotePath, { flags: append ? 'a' : 'w' });
1314
- return await withSftpDeadline(sftp, pipeWithProgress(Readable.from([contentBuffer]), writeStream, sftp, contentBuffer.length), timeout);
1371
+ throwIfAborted(signal);
1372
+ writeStream = state.track(sftp, signal).createWriteStream(remotePath, { flags: append ? 'a' : 'w' });
1373
+ return await withSftpDeadline(sftp, pipeWithProgress(Readable.from([contentBuffer]), writeStream, sftp, contentBuffer.length, undefined, true, signal), timeout, signal);
1315
1374
  }
1316
1375
  catch (error) {
1376
+ if (!writeStream) {
1377
+ sftp.end();
1378
+ }
1317
1379
  throw new UploadFileError(error instanceof Error ? error.message : String(error), state.remoteCreated, {
1318
1380
  cause: error,
1319
1381
  details: state.outcome(error),
@@ -1397,7 +1459,7 @@ export async function getFileInfo(alias, remotePath, timeout, style = 'posix', s
1397
1459
  const connection = sessionManager.getOpenSshConnection(alias);
1398
1460
  let stats;
1399
1461
  if (connection) {
1400
- stats = await connection.stat(remotePath, timeout ?? 600_000);
1462
+ stats = await connection.stat(remotePath, remainingSftpTimeout(deadline, signal) ?? 600_000, true, signal);
1401
1463
  }
1402
1464
  else {
1403
1465
  const sftp = await getSftpWithinDeadline(alias, remainingSftpTimeout(deadline, signal), signal);
@@ -1516,6 +1578,7 @@ export async function checkRsync(alias, timeout = 10_000, executable = 'rsync',
1516
1578
  const startedAt = Date.now();
1517
1579
  try {
1518
1580
  if (/[\r\n\0]/.test(executable)) {
1581
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1519
1582
  throw new Error('Invalid rsync executable path');
1520
1583
  }
1521
1584
  const probeCommand = shell === 'posix'
@@ -1634,16 +1697,19 @@ function verifyWindowsDownloadNames(localPath, remoteNames, timeout) {
1634
1697
  const script = encodedPowershell(windowsCaseSemanticsScript(parent)).split(' ').at(-1);
1635
1698
  const result = spawnSync('powershell.exe', ['-NoProfile', '-NonInteractive', '-EncodedCommand', script], {
1636
1699
  input: Buffer.from(JSON.stringify(names)).toString('base64'),
1700
+ env: getWindowsPowerShellEnv(),
1637
1701
  encoding: 'utf8',
1638
1702
  windowsHide: true,
1639
1703
  timeout: Math.min(timeout ?? 10_000, 10_000),
1640
1704
  maxBuffer: 16_384,
1641
1705
  });
1642
1706
  if (result.error || result.status !== 0) {
1707
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1643
1708
  throw new Error('Windows directory case query failed');
1644
1709
  }
1645
1710
  const collision = parseWindowsCaseSemantics(result.stdout, names);
1646
1711
  if (collision) {
1712
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1647
1713
  throw new Error(`Windows local filename collision at ${localPath}: ${collision.join(' / ')}`);
1648
1714
  }
1649
1715
  }
@@ -1671,6 +1737,7 @@ async function verifyWindowsUploadNames(alias, localPath, remotePath, options) {
1671
1737
  try {
1672
1738
  const timeout = deadline - Date.now();
1673
1739
  if (timeout <= 0) {
1740
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1674
1741
  throw new Error('name preflight timeout was exhausted');
1675
1742
  }
1676
1743
  const result = await sessionManager.exec(alias, encodedPowershell(windowsCaseSemanticsScript(remoteShellPath(parent, style), names)), { timeout, maxOutputSize: 65_536, useLoginUser: true, loadProfile: false });
@@ -1679,6 +1746,7 @@ async function verifyWindowsUploadNames(alias, localPath, remotePath, options) {
1679
1746
  result.timedOut ||
1680
1747
  result.stdoutTruncated ||
1681
1748
  result.stderrTruncated) {
1749
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1682
1750
  throw new Error(result.stderr || 'Windows case semantics query failed or returned truncated output');
1683
1751
  }
1684
1752
  collision = parseWindowsCaseSemantics(result.stdout, names);
@@ -1702,6 +1770,10 @@ async function verifyWindowsUploadNames(alias, localPath, remotePath, options) {
1702
1770
  */
1703
1771
  export async function syncFiles(alias, localPath, remotePath, direction, options = {}) {
1704
1772
  const startedAt = Date.now();
1773
+ if (options.bandwidthLimitKiBps !== undefined &&
1774
+ (!Number.isSafeInteger(options.bandwidthLimitKiBps) || options.bandwidthLimitKiBps <= 0)) {
1775
+ throw new Error('bandwidthLimitKiBps must be a positive safe integer in KiB/s');
1776
+ }
1705
1777
  options = { ...options, deadline: options.deadline ?? startedAt + (options.operationTimeout ?? 600_000) };
1706
1778
  remainingSftpTimeout(options.deadline, options.signal);
1707
1779
  localPath = expandTilde(localPath);
@@ -1831,9 +1903,12 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1831
1903
  }
1832
1904
  // 构建 rsync 参数
1833
1905
  const args = ['-avz', '--itemize-changes', '--stats'];
1834
- if (options.onProgress) {
1906
+ if (options.onProgress || options.signal) {
1835
1907
  args.push('--progress');
1836
1908
  }
1909
+ if (options.bandwidthLimitKiBps !== undefined) {
1910
+ args.push(`--bwlimit=${options.bandwidthLimitKiBps}K`);
1911
+ }
1837
1912
  if (options.delete) {
1838
1913
  args.push('--delete');
1839
1914
  }
@@ -1992,7 +2067,8 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1992
2067
  operationStatus: 'failed',
1993
2068
  failureStage: 'local_prepare',
1994
2069
  retryable: false,
1995
- output: `Local download parent preparation failed: ${error instanceof Error ? error.message : String(error)}`,
2070
+ output: 'Local download parent preparation failed: ' +
2071
+ (error instanceof Error ? error.message : String(error)),
1996
2072
  };
1997
2073
  }
1998
2074
  }
@@ -2001,17 +2077,19 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
2001
2077
  const operationTimeout = remainingSftpTimeout(options.deadline, options.signal) ?? options.operationTimeout ?? 600_000;
2002
2078
  const stats = { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 0 };
2003
2079
  let partial = '';
2080
+ let lastProgress;
2004
2081
  let discardTail = false;
2005
2082
  const collectStats = (chunk, final = false) => {
2006
2083
  for (const [index, segment] of chunk.split(/[\r\n]/).entries()) {
2007
2084
  if (index > 0) {
2008
- const progress = /^\s*([\d,]+)\s+(\d+)%\s+[\d.]+[kMGTPE]?B\/s/i.exec(partial);
2085
+ const progress = /^\s*(?<bytes>[\d,]+)\s+(?<percent>\d+)%\s+[\d.]+[KMGTPE]?B\/s/i.exec(partial);
2009
2086
  if (progress) {
2010
- options.onProgress?.({
2011
- transferred: Number(progress[1].replace(/,/g, '')),
2087
+ lastProgress = {
2088
+ transferred: Number(progress.groups.bytes.replace(/,/g, '')),
2012
2089
  total: 0,
2013
- percent: Number(progress[2]),
2014
- });
2090
+ percent: Number(progress.groups.percent),
2091
+ };
2092
+ options.onProgress?.(lastProgress);
2015
2093
  }
2016
2094
  parseRsyncStats(partial, stats);
2017
2095
  partial = '';
@@ -2029,7 +2107,7 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
2029
2107
  partial = '';
2030
2108
  }
2031
2109
  };
2032
- const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout, childEnv, connection, collectStats);
2110
+ const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout, childEnv, connection, collectStats, options.signal);
2033
2111
  if (!isCurrentRsyncGeneration(alias, generation)) {
2034
2112
  return {
2035
2113
  success: false,
@@ -2042,8 +2120,26 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
2042
2120
  output: `SSH session '${alias}' changed during rsync; remote transfer state is unknown`,
2043
2121
  };
2044
2122
  }
2045
- if (result.error || result.status !== 0) {
2123
+ if (result.cancelled || result.error || result.status !== 0) {
2046
2124
  const stderr = result.stderr.trim();
2125
+ if (result.cancelled) {
2126
+ return {
2127
+ success: false,
2128
+ method: 'rsync',
2129
+ connectDuration,
2130
+ connectStatus: 'completed',
2131
+ operationStatus: 'unknown',
2132
+ cancelled: true,
2133
+ timedOut: result.timedOut || undefined,
2134
+ retryable: false,
2135
+ fallbackReason: result.timedOut ? 'rsync_operation_timeout' : 'rsync_operation_cancelled',
2136
+ lastProgress,
2137
+ stats,
2138
+ output: result.stdout +
2139
+ '\nrsync stopped after request cancellation; remote transfer and deletion state is unknown',
2140
+ outputTruncated: result.stdoutTruncated || undefined,
2141
+ };
2142
+ }
2047
2143
  const reason = result.timedOut
2048
2144
  ? `timed out after ${operationTimeout}ms`
2049
2145
  : (result.error?.message ?? `exit code ${result.status}`);
@@ -2371,9 +2467,20 @@ async function syncWithSftpWithTimeout(alias, localPath, remotePath, direction,
2371
2467
  if (options.signal?.aborted) {
2372
2468
  abort();
2373
2469
  }
2470
+ let nextByteAt = performance.now();
2471
+ const throttle = options.bandwidthLimitKiBps === undefined
2472
+ ? undefined
2473
+ : async (bytes) => {
2474
+ nextByteAt =
2475
+ Math.max(nextByteAt, performance.now()) + (bytes * 1000) / (options.bandwidthLimitKiBps * 1024);
2476
+ await delay(Math.ceil(Math.max(0, nextByteAt - performance.now())), undefined, {
2477
+ signal: controller.signal,
2478
+ });
2479
+ };
2374
2480
  const operation = syncWithSftp(alias, localPath, remotePath, direction, {
2375
2481
  ...options,
2376
2482
  signal: controller.signal,
2483
+ throttle,
2377
2484
  deadline,
2378
2485
  }, accumulator, warnings);
2379
2486
  const timer = setTimeout(() => controller.abort(new SftpOperationTimeoutError(timeout)), timeout);
@@ -2449,12 +2556,12 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options, ac
2449
2556
  };
2450
2557
  }
2451
2558
  if (stats.isDirectory()) {
2452
- const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0, options.signal, '', options.remotePathStyle, undefined, accumulator, options.deadline, options.onProgress);
2559
+ const result = await uploadDirectory(alias, localPath, remotePath, options.exclude, undefined, options.followSymlinks ?? false, { files: 0, directories: 0, bytes: 0 }, 0, options.signal, '', options.remotePathStyle, undefined, accumulator, options.deadline, options.onProgress, options.throttle);
2453
2560
  return buildDirectorySyncResult(result, warnings);
2454
2561
  }
2455
2562
  const targetRemotePath = await resolveSftpUploadFileTarget(alias, localPath, remotePath, options.remotePathStyle, options.deadline, options.signal);
2456
2563
  const existed = await remoteExists(alias, targetRemotePath, options.deadline, options.signal);
2457
- const { size } = await uploadFile(alias, localPath, targetRemotePath, options.onProgress, undefined, undefined, options.signal, options.followSymlinks === true, false, remainingSftpTimeout(options.deadline, options.signal));
2564
+ const { size } = await uploadFile(alias, localPath, targetRemotePath, options.onProgress, undefined, undefined, options.signal, options.followSymlinks === true, false, remainingSftpTimeout(options.deadline, options.signal), options.throttle);
2458
2565
  accumulator.addFile(size, existed);
2459
2566
  return {
2460
2567
  ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
@@ -2478,13 +2585,13 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options, ac
2478
2585
  files: 0,
2479
2586
  directories: 0,
2480
2587
  bytes: 0,
2481
- }, 0, options.signal, '', options.remotePathStyle, accumulator, options.deadline, options.onProgress);
2588
+ }, 0, options.signal, '', options.remotePathStyle, accumulator, options.deadline, options.onProgress, options.throttle);
2482
2589
  return buildDirectorySyncResult(result, warnings);
2483
2590
  }
2484
2591
  remainingSftpTimeout(options.deadline, options.signal);
2485
2592
  const targetLocalPath = resolveSftpDownloadFileTarget(remotePath, localPath, options.remotePathStyle);
2486
2593
  const existed = fs.existsSync(targetLocalPath);
2487
- const { size } = await downloadFile(alias, remotePath, targetLocalPath, options.onProgress, undefined, options.signal, remainingSftpTimeout(options.deadline, options.signal));
2594
+ const { size } = await downloadFile(alias, remotePath, targetLocalPath, options.onProgress, undefined, options.signal, remainingSftpTimeout(options.deadline, options.signal), options.throttle);
2488
2595
  accumulator.addFile(size, existed);
2489
2596
  return {
2490
2597
  ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
@@ -2509,7 +2616,7 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options, ac
2509
2616
  /**
2510
2617
  * 递归上传目录
2511
2618
  */
2512
- async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '', style = 'posix', inspectNames, accumulator = new DirectoryTransferAccumulator(), deadline, onProgress) {
2619
+ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp, followSymlinks = false, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '', style = 'posix', inspectNames, accumulator = new DirectoryTransferAccumulator(), deadline, onProgress, throttle) {
2513
2620
  throwIfAborted(signal);
2514
2621
  recordSftpDirectory(traversal, depth, localPath);
2515
2622
  const realPath = fs.realpathSync(localPath);
@@ -2579,7 +2686,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
2579
2686
  const itemRemotePath = remoteJoin(style, remotePath, name);
2580
2687
  const existed = await sftpExists(sftp, itemRemotePath, remainingSftpTimeout(deadline, signal), signal);
2581
2688
  try {
2582
- await uploadFile(alias, itemLocalPath, itemRemotePath, onProgress, sftp, undefined, signal, followSymlinks, false, remainingSftpTimeout(deadline, signal));
2689
+ await uploadFile(alias, itemLocalPath, itemRemotePath, onProgress, sftp, undefined, signal, followSymlinks, false, remainingSftpTimeout(deadline, signal), throttle);
2583
2690
  accumulator.addFile(stats.size, existed);
2584
2691
  }
2585
2692
  catch (error) {
@@ -2592,7 +2699,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
2592
2699
  for (const item of subDirItems) {
2593
2700
  const itemLocalPath = path.join(localPath, item);
2594
2701
  const itemRemotePath = remoteJoin(style, remotePath, item);
2595
- await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item}` : item, style, inspectNames, accumulator, deadline, onProgress);
2702
+ await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item}` : item, style, inspectNames, accumulator, deadline, onProgress, throttle);
2596
2703
  }
2597
2704
  }
2598
2705
  finally {
@@ -2606,7 +2713,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
2606
2713
  /**
2607
2714
  * 递归下载目录
2608
2715
  */
2609
- async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '', style = 'posix', accumulator = new DirectoryTransferAccumulator(), deadline, onProgress) {
2716
+ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSftp, traversal = { files: 0, directories: 0, bytes: 0 }, depth = 0, signal, relativeBase = '', style = 'posix', accumulator = new DirectoryTransferAccumulator(), deadline, onProgress, throttle) {
2610
2717
  throwIfAborted(signal);
2611
2718
  recordSftpDirectory(traversal, depth, remotePath);
2612
2719
  const ownSftp = !sharedSftp;
@@ -2665,7 +2772,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
2665
2772
  const itemLocalPath = path.join(localPath, item.name);
2666
2773
  const existed = fs.existsSync(itemLocalPath);
2667
2774
  try {
2668
- await downloadFile(alias, item.path, itemLocalPath, onProgress, sftp, signal, remainingSftpTimeout(deadline, signal));
2775
+ await downloadFile(alias, item.path, itemLocalPath, onProgress, sftp, signal, remainingSftpTimeout(deadline, signal), throttle);
2669
2776
  accumulator.addFile(item.size, existed);
2670
2777
  }
2671
2778
  catch (error) {
@@ -2675,7 +2782,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
2675
2782
  });
2676
2783
  for (const item of dirItems) {
2677
2784
  const itemLocalPath = path.join(localPath, item.name);
2678
- await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item.name}` : item.name, style, accumulator, deadline, onProgress);
2785
+ await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item.name}` : item.name, style, accumulator, deadline, onProgress, throttle);
2679
2786
  }
2680
2787
  for (const item of symlinkItems) {
2681
2788
  console.warn(`[ssh_sync] skipping remote symlink: ${item.path}`);
@@ -1,5 +1,5 @@
1
1
  import { type ServerHostKeyAlgorithm } from 'ssh2';
2
- import type { ConnectionFailureDetails } from './types.js';
2
+ import { type ConnectionFailureDetails } from './types.js';
3
3
  export interface HostKeyTrust {
4
4
  status: 'known' | 'added';
5
5
  fingerprint: string;
@@ -14,7 +14,7 @@ export declare class KnownHosts {
14
14
  private readonly userFile;
15
15
  private readonly systemFiles;
16
16
  constructor(userFile?: string, systemFiles?: string[]);
17
- getHostKeyAlgorithms(host: string, port: number): ServerHostKeyAlgorithm[];
17
+ getHostKeyAlgorithms(host: string, port: number, signal?: AbortSignal, deadline?: number): ServerHostKeyAlgorithm[];
18
18
  verify(host: string, port: number, rawKey: Buffer, signal?: AbortSignal, deadline?: number): Promise<HostKeyTrust>;
19
19
  private read;
20
20
  private matchingKeys;