@pyrokine/mcp-ssh 3.2.0 → 3.3.0

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,14 +6,16 @@ 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
21
  import { checkWindowsAcl, windowsAclScript } from './windows-acl.js';
@@ -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'
@@ -1640,10 +1703,12 @@ function verifyWindowsDownloadNames(localPath, remoteNames, timeout) {
1640
1703
  maxBuffer: 16_384,
1641
1704
  });
1642
1705
  if (result.error || result.status !== 0) {
1706
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1643
1707
  throw new Error('Windows directory case query failed');
1644
1708
  }
1645
1709
  const collision = parseWindowsCaseSemantics(result.stdout, names);
1646
1710
  if (collision) {
1711
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1647
1712
  throw new Error(`Windows local filename collision at ${localPath}: ${collision.join(' / ')}`);
1648
1713
  }
1649
1714
  }
@@ -1671,6 +1736,7 @@ async function verifyWindowsUploadNames(alias, localPath, remotePath, options) {
1671
1736
  try {
1672
1737
  const timeout = deadline - Date.now();
1673
1738
  if (timeout <= 0) {
1739
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1674
1740
  throw new Error('name preflight timeout was exhausted');
1675
1741
  }
1676
1742
  const result = await sessionManager.exec(alias, encodedPowershell(windowsCaseSemanticsScript(remoteShellPath(parent, style), names)), { timeout, maxOutputSize: 65_536, useLoginUser: true, loadProfile: false });
@@ -1679,6 +1745,7 @@ async function verifyWindowsUploadNames(alias, localPath, remotePath, options) {
1679
1745
  result.timedOut ||
1680
1746
  result.stdoutTruncated ||
1681
1747
  result.stderrTruncated) {
1748
+ // noinspection ExceptionCaughtLocallyJS — 保留传输失败阶段及所属资源清理
1682
1749
  throw new Error(result.stderr || 'Windows case semantics query failed or returned truncated output');
1683
1750
  }
1684
1751
  collision = parseWindowsCaseSemantics(result.stdout, names);
@@ -1702,6 +1769,10 @@ async function verifyWindowsUploadNames(alias, localPath, remotePath, options) {
1702
1769
  */
1703
1770
  export async function syncFiles(alias, localPath, remotePath, direction, options = {}) {
1704
1771
  const startedAt = Date.now();
1772
+ if (options.bandwidthLimitKiBps !== undefined &&
1773
+ (!Number.isSafeInteger(options.bandwidthLimitKiBps) || options.bandwidthLimitKiBps <= 0)) {
1774
+ throw new Error('bandwidthLimitKiBps must be a positive safe integer in KiB/s');
1775
+ }
1705
1776
  options = { ...options, deadline: options.deadline ?? startedAt + (options.operationTimeout ?? 600_000) };
1706
1777
  remainingSftpTimeout(options.deadline, options.signal);
1707
1778
  localPath = expandTilde(localPath);
@@ -1831,9 +1902,12 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1831
1902
  }
1832
1903
  // 构建 rsync 参数
1833
1904
  const args = ['-avz', '--itemize-changes', '--stats'];
1834
- if (options.onProgress) {
1905
+ if (options.onProgress || options.signal) {
1835
1906
  args.push('--progress');
1836
1907
  }
1908
+ if (options.bandwidthLimitKiBps !== undefined) {
1909
+ args.push(`--bwlimit=${options.bandwidthLimitKiBps}K`);
1910
+ }
1837
1911
  if (options.delete) {
1838
1912
  args.push('--delete');
1839
1913
  }
@@ -1992,7 +2066,8 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
1992
2066
  operationStatus: 'failed',
1993
2067
  failureStage: 'local_prepare',
1994
2068
  retryable: false,
1995
- output: `Local download parent preparation failed: ${error instanceof Error ? error.message : String(error)}`,
2069
+ output: 'Local download parent preparation failed: ' +
2070
+ (error instanceof Error ? error.message : String(error)),
1996
2071
  };
1997
2072
  }
1998
2073
  }
@@ -2001,17 +2076,19 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
2001
2076
  const operationTimeout = remainingSftpTimeout(options.deadline, options.signal) ?? options.operationTimeout ?? 600_000;
2002
2077
  const stats = { added: 0, updated: 0, deleted: 0, skipped: 0, failed: 0 };
2003
2078
  let partial = '';
2079
+ let lastProgress;
2004
2080
  let discardTail = false;
2005
2081
  const collectStats = (chunk, final = false) => {
2006
2082
  for (const [index, segment] of chunk.split(/[\r\n]/).entries()) {
2007
2083
  if (index > 0) {
2008
- const progress = /^\s*([\d,]+)\s+(\d+)%\s+[\d.]+[kMGTPE]?B\/s/i.exec(partial);
2084
+ const progress = /^\s*(?<bytes>[\d,]+)\s+(?<percent>\d+)%\s+[\d.]+[KMGTPE]?B\/s/i.exec(partial);
2009
2085
  if (progress) {
2010
- options.onProgress?.({
2011
- transferred: Number(progress[1].replace(/,/g, '')),
2086
+ lastProgress = {
2087
+ transferred: Number(progress.groups.bytes.replace(/,/g, '')),
2012
2088
  total: 0,
2013
- percent: Number(progress[2]),
2014
- });
2089
+ percent: Number(progress.groups.percent),
2090
+ };
2091
+ options.onProgress?.(lastProgress);
2015
2092
  }
2016
2093
  parseRsyncStats(partial, stats);
2017
2094
  partial = '';
@@ -2029,7 +2106,7 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
2029
2106
  partial = '';
2030
2107
  }
2031
2108
  };
2032
- const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout, childEnv, connection, collectStats);
2109
+ const result = await runLocalProcess('rsync', rsyncArgs, operationTimeout, childEnv, connection, collectStats, options.signal);
2033
2110
  if (!isCurrentRsyncGeneration(alias, generation)) {
2034
2111
  return {
2035
2112
  success: false,
@@ -2042,8 +2119,26 @@ async function syncWithRsync(alias, localPath, remotePath, direction, options, c
2042
2119
  output: `SSH session '${alias}' changed during rsync; remote transfer state is unknown`,
2043
2120
  };
2044
2121
  }
2045
- if (result.error || result.status !== 0) {
2122
+ if (result.cancelled || result.error || result.status !== 0) {
2046
2123
  const stderr = result.stderr.trim();
2124
+ if (result.cancelled) {
2125
+ return {
2126
+ success: false,
2127
+ method: 'rsync',
2128
+ connectDuration,
2129
+ connectStatus: 'completed',
2130
+ operationStatus: 'unknown',
2131
+ cancelled: true,
2132
+ timedOut: result.timedOut || undefined,
2133
+ retryable: false,
2134
+ fallbackReason: result.timedOut ? 'rsync_operation_timeout' : 'rsync_operation_cancelled',
2135
+ lastProgress,
2136
+ stats,
2137
+ output: result.stdout +
2138
+ '\nrsync stopped after request cancellation; remote transfer and deletion state is unknown',
2139
+ outputTruncated: result.stdoutTruncated || undefined,
2140
+ };
2141
+ }
2047
2142
  const reason = result.timedOut
2048
2143
  ? `timed out after ${operationTimeout}ms`
2049
2144
  : (result.error?.message ?? `exit code ${result.status}`);
@@ -2371,9 +2466,20 @@ async function syncWithSftpWithTimeout(alias, localPath, remotePath, direction,
2371
2466
  if (options.signal?.aborted) {
2372
2467
  abort();
2373
2468
  }
2469
+ let nextByteAt = performance.now();
2470
+ const throttle = options.bandwidthLimitKiBps === undefined
2471
+ ? undefined
2472
+ : async (bytes) => {
2473
+ nextByteAt =
2474
+ Math.max(nextByteAt, performance.now()) + (bytes * 1000) / (options.bandwidthLimitKiBps * 1024);
2475
+ await delay(Math.ceil(Math.max(0, nextByteAt - performance.now())), undefined, {
2476
+ signal: controller.signal,
2477
+ });
2478
+ };
2374
2479
  const operation = syncWithSftp(alias, localPath, remotePath, direction, {
2375
2480
  ...options,
2376
2481
  signal: controller.signal,
2482
+ throttle,
2377
2483
  deadline,
2378
2484
  }, accumulator, warnings);
2379
2485
  const timer = setTimeout(() => controller.abort(new SftpOperationTimeoutError(timeout)), timeout);
@@ -2449,12 +2555,12 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options, ac
2449
2555
  };
2450
2556
  }
2451
2557
  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);
2558
+ 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
2559
  return buildDirectorySyncResult(result, warnings);
2454
2560
  }
2455
2561
  const targetRemotePath = await resolveSftpUploadFileTarget(alias, localPath, remotePath, options.remotePathStyle, options.deadline, options.signal);
2456
2562
  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));
2563
+ 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
2564
  accumulator.addFile(size, existed);
2459
2565
  return {
2460
2566
  ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
@@ -2478,13 +2584,13 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options, ac
2478
2584
  files: 0,
2479
2585
  directories: 0,
2480
2586
  bytes: 0,
2481
- }, 0, options.signal, '', options.remotePathStyle, accumulator, options.deadline, options.onProgress);
2587
+ }, 0, options.signal, '', options.remotePathStyle, accumulator, options.deadline, options.onProgress, options.throttle);
2482
2588
  return buildDirectorySyncResult(result, warnings);
2483
2589
  }
2484
2590
  remainingSftpTimeout(options.deadline, options.signal);
2485
2591
  const targetLocalPath = resolveSftpDownloadFileTarget(remotePath, localPath, options.remotePathStyle);
2486
2592
  const existed = fs.existsSync(targetLocalPath);
2487
- const { size } = await downloadFile(alias, remotePath, targetLocalPath, options.onProgress, undefined, options.signal, remainingSftpTimeout(options.deadline, options.signal));
2593
+ const { size } = await downloadFile(alias, remotePath, targetLocalPath, options.onProgress, undefined, options.signal, remainingSftpTimeout(options.deadline, options.signal), options.throttle);
2488
2594
  accumulator.addFile(size, existed);
2489
2595
  return {
2490
2596
  ...buildSyncResult(1, size, warnings, 0, { added: existed ? 0 : 1, updated: existed ? 1 : 0 }),
@@ -2509,7 +2615,7 @@ async function syncWithSftp(alias, localPath, remotePath, direction, options, ac
2509
2615
  /**
2510
2616
  * 递归上传目录
2511
2617
  */
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) {
2618
+ 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
2619
  throwIfAborted(signal);
2514
2620
  recordSftpDirectory(traversal, depth, localPath);
2515
2621
  const realPath = fs.realpathSync(localPath);
@@ -2579,7 +2685,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
2579
2685
  const itemRemotePath = remoteJoin(style, remotePath, name);
2580
2686
  const existed = await sftpExists(sftp, itemRemotePath, remainingSftpTimeout(deadline, signal), signal);
2581
2687
  try {
2582
- await uploadFile(alias, itemLocalPath, itemRemotePath, onProgress, sftp, undefined, signal, followSymlinks, false, remainingSftpTimeout(deadline, signal));
2688
+ await uploadFile(alias, itemLocalPath, itemRemotePath, onProgress, sftp, undefined, signal, followSymlinks, false, remainingSftpTimeout(deadline, signal), throttle);
2583
2689
  accumulator.addFile(stats.size, existed);
2584
2690
  }
2585
2691
  catch (error) {
@@ -2592,7 +2698,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
2592
2698
  for (const item of subDirItems) {
2593
2699
  const itemLocalPath = path.join(localPath, item);
2594
2700
  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);
2701
+ await uploadDirectory(alias, itemLocalPath, itemRemotePath, exclude, sftp, followSymlinks, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item}` : item, style, inspectNames, accumulator, deadline, onProgress, throttle);
2596
2702
  }
2597
2703
  }
2598
2704
  finally {
@@ -2606,7 +2712,7 @@ async function uploadDirectory(alias, localPath, remotePath, exclude, sharedSftp
2606
2712
  /**
2607
2713
  * 递归下载目录
2608
2714
  */
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) {
2715
+ 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
2716
  throwIfAborted(signal);
2611
2717
  recordSftpDirectory(traversal, depth, remotePath);
2612
2718
  const ownSftp = !sharedSftp;
@@ -2665,7 +2771,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
2665
2771
  const itemLocalPath = path.join(localPath, item.name);
2666
2772
  const existed = fs.existsSync(itemLocalPath);
2667
2773
  try {
2668
- await downloadFile(alias, item.path, itemLocalPath, onProgress, sftp, signal, remainingSftpTimeout(deadline, signal));
2774
+ await downloadFile(alias, item.path, itemLocalPath, onProgress, sftp, signal, remainingSftpTimeout(deadline, signal), throttle);
2669
2775
  accumulator.addFile(item.size, existed);
2670
2776
  }
2671
2777
  catch (error) {
@@ -2675,7 +2781,7 @@ async function downloadDirectory(alias, remotePath, localPath, exclude, sharedSf
2675
2781
  });
2676
2782
  for (const item of dirItems) {
2677
2783
  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);
2784
+ await downloadDirectory(alias, item.path, itemLocalPath, exclude, sftp, traversal, depth + 1, signal, relativeBase ? `${relativeBase}/${item.name}` : item.name, style, accumulator, deadline, onProgress, throttle);
2679
2785
  }
2680
2786
  for (const item of symlinkItems) {
2681
2787
  console.warn(`[ssh_sync] skipping remote symlink: ${item.path}`);