@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/README.md +77 -18
- package/README_zh.md +40 -10
- package/dist/command-risk.js +1 -1
- package/dist/directory-verification.js +10 -10
- package/dist/file-ops.d.ts +9 -5
- package/dist/file-ops.js +163 -57
- package/dist/known-hosts.js +11 -1
- package/dist/openssh.d.ts +5 -5
- package/dist/openssh.js +92 -38
- package/dist/remote-platform.js +2 -2
- package/dist/session-manager.d.ts +7 -1
- package/dist/session-manager.js +139 -22
- package/dist/sftp-timeout.d.ts +1 -1
- package/dist/sftp-timeout.js +12 -2
- package/dist/tools/connection.js +14 -10
- package/dist/tools/exec.js +66 -35
- package/dist/tools/file.js +93 -21
- package/dist/transfer-outcome.js +1 -1
- package/dist/types.d.ts +4 -1
- package/dist/windows-acl.js +6 -6
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -231,7 +231,10 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
231
231
|
OpenSSH
|
|
232
232
|
entries also include `masterReused` and `identityStatus` . Use `detail=true` for connection details or `fields=[...]`
|
|
233
233
|
to
|
|
234
|
-
select fields. Neither mode returns `keyPath`. For ssh2, `connected` checks the underlying socket's writable/open
|
|
234
|
+
select fields. Neither mode returns `keyPath`. For ssh2, `connected` checks the underlying socket's writable/open
|
|
235
|
+
state, so dead transport is reported disconnected before a delayed close event arrives. An implicit bastion alias
|
|
236
|
+
that conflicts with another live connection uses a target-scoped alias; compatible bastions are still shared, and
|
|
237
|
+
an explicitly chosen conflicting alias returns an error.
|
|
235
238
|
|
|
236
239
|
ssh2 connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests.
|
|
237
240
|
Direct,
|
|
@@ -256,12 +259,22 @@ pending, a channel returned by the delayed callback is destroyed before the conn
|
|
|
256
259
|
| `ssh_quick_exec` | One-shot: connect, execute, disconnect |
|
|
257
260
|
| `ssh_exec_script` | Upload and run a temporary remote script |
|
|
258
261
|
|
|
259
|
-
`ssh_exec_script.interpreter` is an executable name or path. Pass flags separately as `interpreterArgs`, such as
|
|
262
|
+
`ssh_exec_script.interpreter` is an executable name or path. Pass flags separately as `interpreterArgs`, such as
|
|
263
|
+
`interpreter="python3", interpreterArgs=["-I"]`. Each array entry is one escaped argument; omitting the array
|
|
264
|
+
preserves the default empty argument list. POSIX defaults to bash; Windows defaults to the connection shell and
|
|
265
|
+
retains its cmd or PowerShell script invocation.
|
|
260
266
|
|
|
261
267
|
For a Windows remote, `ssh_exec_script` saves PowerShell scripts as UTF-8 with BOM so Windows PowerShell reads Unicode
|
|
262
268
|
correctly. CMD scripts switch to code page 65001 before running UTF-8 commands; an unavailable code page stops
|
|
263
269
|
execution. POSIX scripts retain their original content.
|
|
264
270
|
|
|
271
|
+
Host cancellation stops subsequent batch commands and queued parallel work, including batches with `stopOnError=false`.
|
|
272
|
+
It also stops later script upload, permission preparation, interpreter dispatch, and password input to a late sudo
|
|
273
|
+
channel.
|
|
274
|
+
Script cleanup uses a separate timeout of at most 30000 ms and removes only this request's temporary file.
|
|
275
|
+
`keepScript=true` retains a script once execution has started; an upload or preparation failure still cleans it up.
|
|
276
|
+
Canceling a request closes its own channels and leaves other requests and any reused OpenSSH master available.
|
|
277
|
+
|
|
265
278
|
### Tracked operations
|
|
266
279
|
|
|
267
280
|
| Tool | Description |
|
|
@@ -285,7 +298,8 @@ execution. POSIX scripts retain their original content.
|
|
|
285
298
|
| `ssh_mkdir` | Create remote directory |
|
|
286
299
|
| `ssh_sync` | Smart sync with rsync (fallback to SFTP) |
|
|
287
300
|
|
|
288
|
-
`ssh_read_file` accepts regular files, including empty files. A directory is rejected before opening a read stream
|
|
301
|
+
`ssh_read_file` accepts regular files, including empty files. A directory is rejected before opening a read stream
|
|
302
|
+
with guidance to use `ssh_list_dir`; other non-regular targets return a type error.
|
|
289
303
|
|
|
290
304
|
### PTY Sessions (Persistent Interactive Terminal)
|
|
291
305
|
|
|
@@ -454,7 +468,7 @@ that command. A reported exit signal is retained as `exitSignal` and classified
|
|
|
454
468
|
### Basic: Connect and Execute
|
|
455
469
|
|
|
456
470
|
```
|
|
457
|
-
ssh_connect(host="<server-host>", user="root", keyPath="
|
|
471
|
+
ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="myserver")
|
|
458
472
|
ssh_exec(alias="myserver", command="ls -la /home")
|
|
459
473
|
ssh_disconnect(alias="myserver")
|
|
460
474
|
```
|
|
@@ -492,6 +506,11 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
|
|
|
492
506
|
from the session that was actually published. Concurrent calls reuse an alias only when the complete session
|
|
493
507
|
configuration matches, including endpoint, authentication, `runAs`, environment, jump host, keepalive, and timeout
|
|
494
508
|
settings. A conflicting pending or active connection is rejected even when its `user@host:port` identity is unchanged.
|
|
509
|
+
Conflict errors include `details.differingFields` with configuration field names only. OpenSSH configuration preparation
|
|
510
|
+
registers the requested alias, `configHost`, or initial endpoint. Disconnect cancels its owned `ssh -G` process and
|
|
511
|
+
prevents a later connection, including the preparation-to-connect handoff. A later connection can reuse the resolved
|
|
512
|
+
alias when `ssh -G` changes the hostname, user, or port.
|
|
513
|
+
|
|
495
514
|
Missing templates include available template names when they can be loaded. Missing `configHost` returns SSH config
|
|
496
515
|
candidates and suggests `ssh_config_list`.
|
|
497
516
|
|
|
@@ -503,12 +522,12 @@ Connect to internal server via jump host:
|
|
|
503
522
|
ssh_connect(
|
|
504
523
|
host="<internal-host>",
|
|
505
524
|
user="root",
|
|
506
|
-
keyPath="
|
|
525
|
+
keyPath="~/.ssh/id_rsa",
|
|
507
526
|
alias="internal",
|
|
508
527
|
jumpHost={
|
|
509
528
|
host: "bastion.example.com",
|
|
510
529
|
user: "admin",
|
|
511
|
-
keyPath: "
|
|
530
|
+
keyPath: "~/.ssh/bastion_key"
|
|
512
531
|
}
|
|
513
532
|
)
|
|
514
533
|
```
|
|
@@ -518,7 +537,7 @@ ssh_connect(
|
|
|
518
537
|
Perfect for scenarios where you SSH as root but need to run commands as another user:
|
|
519
538
|
|
|
520
539
|
```
|
|
521
|
-
1. ssh_connect(host="<server-host>", user="root", keyPath="
|
|
540
|
+
1. ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="server")
|
|
522
541
|
2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
|
|
523
542
|
// Output: appuser
|
|
524
543
|
```
|
|
@@ -623,11 +642,12 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
|
|
|
623
642
|
ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
|
|
624
643
|
```
|
|
625
644
|
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
645
|
+
Log querying uses the general command and file tools. `ssh_exec_script.timeout` independently limits temporary script
|
|
646
|
+
upload, permission preparation, and execution. Explicit values use positive integer milliseconds, up to 3600000. Cleanup
|
|
647
|
+
has its own timeout: the smaller of the requested value and 30000 ms, or 30000 ms when omitted. Without an explicit
|
|
648
|
+
timeout, commands retain their 30000 ms default and SFTP retains 600000 ms. Host request deadlines apply separately.
|
|
649
|
+
Use `ssh_operation_start/status/read/cancel` for long observations: a host abort of synchronous exec leaves the remote
|
|
650
|
+
process's stop state unknown.
|
|
631
651
|
|
|
632
652
|
### With Environment Variables
|
|
633
653
|
|
|
@@ -635,7 +655,7 @@ A stalled SFTP upload therefore ends on the requested timeout instead of using t
|
|
|
635
655
|
ssh_connect(
|
|
636
656
|
host="<server-host>",
|
|
637
657
|
user="root",
|
|
638
|
-
keyPath="
|
|
658
|
+
keyPath="~/.ssh/id_rsa",
|
|
639
659
|
env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
|
|
640
660
|
)
|
|
641
661
|
```
|
|
@@ -649,7 +669,7 @@ No need to manage connections for single commands. `ssh_quick_exec` creates a un
|
|
|
649
669
|
ssh_quick_exec(
|
|
650
670
|
host="<server-host>",
|
|
651
671
|
user="root",
|
|
652
|
-
keyPath="
|
|
672
|
+
keyPath="~/.ssh/id_rsa",
|
|
653
673
|
command="uptime"
|
|
654
674
|
)
|
|
655
675
|
```
|
|
@@ -720,7 +740,9 @@ tools.
|
|
|
720
740
|
|
|
721
741
|
`ssh_upload` , `ssh_download` , `ssh_read_file` , `ssh_write_file` , `ssh_list_dir` , `ssh_file_info` , and
|
|
722
742
|
`ssh_mkdir` accept
|
|
723
|
-
`timeout` for one SFTP operation.
|
|
743
|
+
`timeout` for one SFTP operation. Downloads use one total deadline for transfer and failure diagnostics;
|
|
744
|
+
when time expires or the host cancels, remote probing stops and local diagnostics remain available. It defaults to
|
|
745
|
+
10 minutes and accepts up to one hour. Timeouts retain local and
|
|
724
746
|
remote probe diagnostics. Uploads and writes report `operationStatus="unknown"` when an
|
|
725
747
|
OPEN, WRITE, or CLOSE request was dispatched without a completion reply. Explicit server refusal returns `failed` .
|
|
726
748
|
Read-only upload preflight failures also return `failed` ,
|
|
@@ -842,9 +864,18 @@ mode. Directory sources reject `recursive=false`. Relative exclude patterns are
|
|
|
842
864
|
source root; patterns without `/` match each basename. A trailing `/` restricts a pattern to directories:
|
|
843
865
|
`provider/` skips directories with that basename and their contents while retaining regular files named `provider`.
|
|
844
866
|
|
|
845
|
-
A single-file upload requires an existing remote parent directory. A known missing parent or a parent that is a
|
|
867
|
+
A single-file upload requires an existing remote parent directory. A known missing parent or a parent that is a
|
|
868
|
+
file fails before upload with `failureStage="remote_prepare"` and `REMOTE_PARENT_NOT_FOUND` or
|
|
869
|
+
`REMOTE_PARENT_NOT_DIRECTORY`; use `ssh_mkdir` for a missing parent. Directory sync retains its recursive creation
|
|
870
|
+
behavior. Downloads create missing local parents; a failure during rsync parent preparation returns
|
|
871
|
+
`failureStage="local_prepare"` before the transfer process starts.
|
|
846
872
|
|
|
847
|
-
Clients requesting `_meta.progressToken` receive `notifications/progress` from SFTP and rsync transfers, including
|
|
873
|
+
Clients requesting `_meta.progressToken` receive `notifications/progress` from SFTP and rsync transfers, including
|
|
874
|
+
recursive sync, at most once per second while transfer bytes advance. `progress` is an increasing notification
|
|
875
|
+
sequence; `message` reports the current file's bytes and percentage, with its total when known. Calls without a
|
|
876
|
+
token keep the same transfer result. Cancellation stops later notifications. Notification errors produce a warning,
|
|
877
|
+
with `progressWarning` when available, while the transfer retains its own outcome. The operation deadline and the
|
|
878
|
+
client's absolute request deadline remain separate from progress-driven idle-timeout resets.
|
|
848
879
|
|
|
849
880
|
For a regular file, `verify.sha256`, `verify.owner`, `verify.mode`, and Windows `verify.aclSddl` apply to the actual
|
|
850
881
|
transferred file in either direction. The result uses `kind="single_file"` and includes the file digest, not a
|
|
@@ -855,7 +886,7 @@ local and remote hashing, including the SFTP transport check. `verify.count`, `v
|
|
|
855
886
|
require a directory source and are rejected before transfer for a file. A known source file larger than the requested
|
|
856
887
|
hash budget is also rejected before transfer.
|
|
857
888
|
|
|
858
|
-
Directory verification builds bounded local and remote manifests. It can compare entry count,
|
|
889
|
+
Directory verification builds bounded local and remote manifests. It can compare entry count, a SHA-256 root
|
|
859
890
|
manifest,
|
|
860
891
|
owner, all four octal mode digits (including setuid, setgid, and sticky), stale entries, and deletion results.
|
|
861
892
|
`verify.deletions=true` requires `delete=true` ; it records the destination before transfer and only checks whether
|
|
@@ -897,6 +928,29 @@ hash streams and stops later checks, while preserving completed file and byte co
|
|
|
897
928
|
result
|
|
898
929
|
has `success=false` and a timed-out verification outcome.
|
|
899
930
|
|
|
931
|
+
`bandwidthLimitKiBps` optionally limits aggregate transfer payload to KiB/s (1 KiB = 1024 bytes), for rsync and
|
|
932
|
+
SFTP, in either direction. Omit it for the existing unrestricted speed. Concurrent and recursive SFTP file
|
|
933
|
+
transfers share one limit; metadata and explicitly requested verification reads have separate costs. For example,
|
|
934
|
+
`ssh_sync(..., bandwidthLimitKiBps=1024)` requests 1 MiB/s.
|
|
935
|
+
|
|
936
|
+
Canceling a running rsync request terminates and waits for its own local process group, retaining reported
|
|
937
|
+
itemization/deletion counts and `lastProgress`. The result is `cancelled=true`, `operationStatus="unknown"`: remote
|
|
938
|
+
writes or deletions already dispatched require inspection. The alias, other requests, and the reused OpenSSH master
|
|
939
|
+
remain available.
|
|
940
|
+
|
|
941
|
+
Directory `checks` uses `null` for unrequested checks, `true` for an executed match, and `false` for a mismatch.
|
|
942
|
+
Top-level `verificationStatus` distinguishes unrequested, skipped, matched, mismatched, and error outcomes.
|
|
943
|
+
Explicit single-file SHA-256 verification reads each endpoint once and shares its digest with
|
|
944
|
+
`transportVerification`; byte limits and metadata stability checks still apply.
|
|
945
|
+
|
|
946
|
+
`ssh_mkdir` uses the SFTP login identity, independently of command `runAs`. Its response includes `loginUser`,
|
|
947
|
+
`runAs`, `creationIdentity="sftp_login"`, and actual numeric `owner`, `group`, `mode`, and `permissions`. Directory
|
|
948
|
+
access follows those returned permissions; the tool preserves ownership and permission policy. Once creation is
|
|
949
|
+
acknowledged, a later metadata read failure returns `success=true`, `operationStatus="completed"`, `retryable=false`,
|
|
950
|
+
and `metadataStatus="unavailable"`. `metadataError` contains the metadata failure in the existing error format,
|
|
951
|
+
including any timeout details; unavailable `owner`, `group`, `mode`, and `permissions` are omitted. Use `ssh_file_info`
|
|
952
|
+
to read metadata again. Directory creation failures retain their original error response.
|
|
953
|
+
|
|
900
954
|
Directory root digests sort paths by their UTF-8 bytes, independent of enumeration order or locale. Case-distinct and
|
|
901
955
|
Unicode NFC/NFD-distinct names remain separate entries; file names are not normalized.
|
|
902
956
|
|
|
@@ -1073,6 +1127,11 @@ also include
|
|
|
1073
1127
|
|
|
1074
1128
|
### Exec Options
|
|
1075
1129
|
|
|
1130
|
+
`ssh_exec(..., stdin="text")` sends UTF-8 input followed by EOF through ssh2 or the reused OpenSSH channel. Empty
|
|
1131
|
+
input sends EOF; omitting `stdin` retains existing behavior. Input stays out of the command string and
|
|
1132
|
+
input-delivery errors. A canceled request closes its own channel and returns remote state `unknown`, while the
|
|
1133
|
+
alias and master remain available. Commands that intentionally print their input still control their own output.
|
|
1134
|
+
|
|
1076
1135
|
| Option | Type | Default | Description |
|
|
1077
1136
|
| --------------- | ------- | ------------- | ------------------------------------------ |
|
|
1078
1137
|
| `timeout` | number | 30000 | Command timeout in ms |
|
package/README_zh.md
CHANGED
|
@@ -401,7 +401,7 @@ channel 关闭且没有收到退出状态时,返回 `exitCode=null`、`failure
|
|
|
401
401
|
### 基础:连接和执行
|
|
402
402
|
|
|
403
403
|
```
|
|
404
|
-
ssh_connect(host="<server-host>", user="root", keyPath="
|
|
404
|
+
ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="myserver")
|
|
405
405
|
ssh_exec(alias="myserver", command="ls -la /home")
|
|
406
406
|
ssh_disconnect(alias="myserver")
|
|
407
407
|
```
|
|
@@ -438,6 +438,19 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
|
|
|
438
438
|
host、keepalive 和 timeout;pending 或 active 连接的配置冲突时会被拒绝,即使 `user@host:port`
|
|
439
439
|
identity 相同,template 缺失时返回可用模板名,`configHost` 缺失时返回 SSH config 候选并提示调用 `ssh_config_list`
|
|
440
440
|
|
|
441
|
+
配置冲突通过 `details.differingFields` 返回不同的配置字段名,字段值和凭证保持私有
|
|
442
|
+
OpenSSH 配置准备按请求 alias、`configHost` 或初始连接地址登记,disconnect 会终止本次自有 `ssh -G` 进程
|
|
443
|
+
准备结束与连接登记之间发生的取消同样生效,`ssh -G` 改变主机名、用户或端口后,后续请求仍可重新连接解析后的 alias
|
|
444
|
+
|
|
445
|
+
`ssh_exec(..., stdin="text")` 经 ssh2 或复用的 OpenSSH 通道写入 UTF-8 内容并发送 EOF,空字符串只发送 EOF,省略时保持原输入行为,输入不写入命令字符串或输入发送错误,
|
|
446
|
+
请求取消会关闭本次通道并返回远端状态 `unknown`,alias 与 master 继续可用,命令主动输出输入内容时按实际命令输出返回
|
|
447
|
+
|
|
448
|
+
宿主取消请求后,批量命令与排队中的并行任务停止派发,`stopOnError=false` 同样生效
|
|
449
|
+
脚本停止后续上传、权限准备和解释器执行,迟到的 sudo 通道不再接收密码
|
|
450
|
+
脚本清理使用独立期限,最长 30000 ms,仅删除本次创建的临时文件
|
|
451
|
+
`keepScript=true` 在开始执行后保留脚本,上传或准备失败时仍执行清理
|
|
452
|
+
取消仅关闭本次通道,其他请求及复用的 OpenSSH master 继续可用
|
|
453
|
+
|
|
441
454
|
### 跳板机
|
|
442
455
|
|
|
443
456
|
通过跳板机连接内网服务器:
|
|
@@ -446,12 +459,12 @@ identity 相同,template 缺失时返回可用模板名,`configHost` 缺失
|
|
|
446
459
|
ssh_connect(
|
|
447
460
|
host="<internal-host>",
|
|
448
461
|
user="root",
|
|
449
|
-
keyPath="
|
|
462
|
+
keyPath="~/.ssh/id_rsa",
|
|
450
463
|
alias="internal",
|
|
451
464
|
jumpHost={
|
|
452
465
|
host: "bastion.example.com",
|
|
453
466
|
user: "admin",
|
|
454
|
-
keyPath: "
|
|
467
|
+
keyPath: "~/.ssh/bastion_key"
|
|
455
468
|
}
|
|
456
469
|
)
|
|
457
470
|
```
|
|
@@ -461,7 +474,7 @@ ssh_connect(
|
|
|
461
474
|
适用于 SSH 以 root 登录,但需要以其他用户执行命令的场景:
|
|
462
475
|
|
|
463
476
|
```
|
|
464
|
-
1. ssh_connect(host="<server-host>", user="root", keyPath="
|
|
477
|
+
1. ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="server")
|
|
465
478
|
2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
|
|
466
479
|
// 输出: appuser
|
|
467
480
|
```
|
|
@@ -554,8 +567,9 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
|
|
|
554
567
|
ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
|
|
555
568
|
```
|
|
556
569
|
|
|
557
|
-
|
|
558
|
-
|
|
570
|
+
日志查询由通用命令和文件工具组合完成;`ssh_exec_script.timeout` 分别限制临时脚本上传、权限准备和执行阶段,每阶段独立计时,显式值为正整数,最大 3600000 ms;清理阶段独立计时,使用请求值与 30000 ms 中的较小值,省略参数时为 30000 ms
|
|
571
|
+
|
|
572
|
+
未传显式超时时,命令保持 30000 ms 默认值,SFTP 保持 600000 ms 默认值,宿主请求期限独立生效;长时间观察使用 `ssh_operation_start/status/read/cancel`,同步 exec 被宿主中止时远端进程停止状态仍为未知
|
|
559
573
|
|
|
560
574
|
### 设置环境变量
|
|
561
575
|
|
|
@@ -563,7 +577,7 @@ ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=655
|
|
|
563
577
|
ssh_connect(
|
|
564
578
|
host="<server-host>",
|
|
565
579
|
user="root",
|
|
566
|
-
keyPath="
|
|
580
|
+
keyPath="~/.ssh/id_rsa",
|
|
567
581
|
env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
|
|
568
582
|
)
|
|
569
583
|
```
|
|
@@ -577,7 +591,7 @@ ssh_connect(
|
|
|
577
591
|
ssh_quick_exec(
|
|
578
592
|
host="<server-host>",
|
|
579
593
|
user="root",
|
|
580
|
-
keyPath="
|
|
594
|
+
keyPath="~/.ssh/id_rsa",
|
|
581
595
|
command="uptime"
|
|
582
596
|
)
|
|
583
597
|
```
|
|
@@ -638,7 +652,8 @@ user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB
|
|
|
638
652
|
`next_offset`;行范围读取不执行远端 shell 工具
|
|
639
653
|
|
|
640
654
|
`ssh_upload`、`ssh_download`、`ssh_read_file`、`ssh_write_file`、`ssh_list_dir`、`ssh_file_info` 和 `ssh_mkdir`
|
|
641
|
-
|
|
655
|
+
支持 `timeout`,默认 10 分钟,最大 1 小时,下载与失败诊断共用一次总期限
|
|
656
|
+
取消或超期后停止远端探测,保留原错误与本地详情,其他文件工具仍按单个 SFTP 操作计时
|
|
642
657
|
上传和写入已派发 OPEN、WRITE 或 CLOSE 且丢失完成应答时,返回 `operationStatus="unknown"`;服务端明确拒绝返回 `failed`
|
|
643
658
|
上传前只读探测失败也返回 `failed`,`failureStage="preflight"`,已确认写入字节为 0
|
|
644
659
|
`failureStage`、受影响路径与 `acknowledgedBytes` 保留已确认进度,`retryable=false` 表示写入不会自动重放,重写前检查路径状态
|
|
@@ -751,7 +766,8 @@ ssh_sync(..., delete=true, verify={deletions: true})
|
|
|
751
766
|
会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
|
|
752
767
|
尾部 `/` 将模式限定为目录,`provider/` 排除每一级同名目录及其内容,保留名为 `provider` 的普通文件
|
|
753
768
|
|
|
754
|
-
单文件上传要求远端父目录存在,已知父目录缺失或父路径为文件时,在上传前返回 `failureStage="remote_prepare"` 和 `REMOTE_PARENT_NOT_FOUND` 或
|
|
769
|
+
单文件上传要求远端父目录存在,已知父目录缺失或父路径为文件时,在上传前返回 `failureStage="remote_prepare"` 和 `REMOTE_PARENT_NOT_FOUND` 或
|
|
770
|
+
`REMOTE_PARENT_NOT_DIRECTORY`
|
|
755
771
|
缺失目录使用 `ssh_mkdir` 创建,目录同步仍按递归创建规则执行
|
|
756
772
|
下载自动创建缺失的本地父目录,rsync 的本地准备失败在传输进程启动前返回 `failureStage="local_prepare"`
|
|
757
773
|
|
|
@@ -797,6 +813,20 @@ session 不经过这项凭证选择,也不回退到 SFTP,`preflightTimeout`
|
|
|
797
813
|
校验超期会关闭本次持有的哈希流并停止后续检查,保留已完成的文件数、字节数与 `transferSuccess`,整体返回 `success=false`
|
|
798
814
|
并明确报告校验超期
|
|
799
815
|
|
|
816
|
+
`bandwidthLimitKiBps` 为可选总传输限速,单位 KiB/s(1 KiB = 1024 bytes),适用于双向 rsync 和 SFTP,省略时保持原不限速行为,SFTP 并发文件和递归子目录共用本次限速,
|
|
817
|
+
元数据和显式校验读取单独消耗资源,例如 `ssh_sync(..., bandwidthLimitKiBps=1024)` 请求 1 MiB/s
|
|
818
|
+
|
|
819
|
+
取消运行中的 rsync 请求时,工具终止并等待本次自有本地进程组,保留已报告的文件明细、删除计数和 `lastProgress`,返回 `cancelled=true`、`operationStatus="unknown"`,
|
|
820
|
+
已派发的远端写入和删除需要检查实际状态,alias、其他请求和复用的 OpenSSH master 保持可用
|
|
821
|
+
|
|
822
|
+
目录 `checks` 使用 `null` 表示未请求,`true` 表示已执行且匹配,`false` 表示不匹配,顶层 `verificationStatus` 区分未请求、跳过、匹配、不匹配和错误,
|
|
823
|
+
显式单文件 SHA-256 校验只完整读取每端一次,并将摘要共享给 `transportVerification`,保留字节预算及元数据稳定性检查
|
|
824
|
+
|
|
825
|
+
`ssh_mkdir` 使用 SFTP 登录身份,命令 `runAs` 单独生效,响应包含 `loginUser`、`runAs`、`creationIdentity="sftp_login"` 和实际数值 `owner`、
|
|
826
|
+
`group`、`mode` 及 `permissions`,后续目录访问由返回的权限决定,工具保持既有属主和权限策略
|
|
827
|
+
创建已确认后,后续元信息读取失败时返回 `success=true`、`operationStatus="completed"`、`retryable=false` 和 `metadataStatus="unavailable"`,
|
|
828
|
+
`metadataError` 按既有错误格式保留元信息读取错误及超时详情,未取得的 `owner`、`group`、`mode` 和 `permissions` 省略,使用 `ssh_file_info` 重新读取元信息,目录创建自身失败时保留原错误响应
|
|
829
|
+
|
|
800
830
|
目录根摘要按路径的 UTF-8 字节排序,不依赖枚举顺序或 locale,大小写不同与 NFC/NFD 不同的名称保持独立,不归一化文件名
|
|
801
831
|
|
|
802
832
|
rsync 模式设置
|
package/dist/command-risk.js
CHANGED
|
@@ -123,7 +123,7 @@ function withoutQuotedText(command, shell) {
|
|
|
123
123
|
const bodyStart = index;
|
|
124
124
|
let bodyEnd = limit;
|
|
125
125
|
let afterDelimiter = limit;
|
|
126
|
-
// Delimiters are case-sensitive; input
|
|
126
|
+
// Delimiters are case-sensitive; quoted input leaves the command parser quote state unchanged.
|
|
127
127
|
for (let lineStart = index; lineStart < limit;) {
|
|
128
128
|
let lineEnd = lineStart;
|
|
129
129
|
let line = '';
|
|
@@ -512,15 +512,15 @@ export async function createOpenSshDirectoryManifest(connection, rootPath, reque
|
|
|
512
512
|
throw new Error('OpenSSH manifest field exceeded its byte budget');
|
|
513
513
|
}
|
|
514
514
|
}, remaining());
|
|
515
|
-
if (pending.length || fields.length) {
|
|
516
|
-
throw new Error('OpenSSH manifest ended with incomplete metadata');
|
|
517
|
-
}
|
|
518
515
|
}
|
|
519
516
|
catch (error) {
|
|
520
517
|
if (error !== limit) {
|
|
521
518
|
throw error;
|
|
522
519
|
}
|
|
523
520
|
}
|
|
521
|
+
if (!limitReason && (pending.length || fields.length)) {
|
|
522
|
+
throw new Error('OpenSSH manifest ended with incomplete metadata');
|
|
523
|
+
}
|
|
524
524
|
if (!limitReason && request.sha256) {
|
|
525
525
|
let hashedBytes = 0;
|
|
526
526
|
for (const entry of entries) {
|
|
@@ -658,18 +658,18 @@ export function compareDirectoryManifests(expected, actual, request, deletionBas
|
|
|
658
658
|
}
|
|
659
659
|
const checks = {
|
|
660
660
|
entries: missing === 0 && typeMismatch === 0,
|
|
661
|
-
count: request.count ? expected.count === actual.count :
|
|
662
|
-
sha256: request.sha256 ? expected.rootSha256 === actual.rootSha256 :
|
|
663
|
-
owner: request.owner ? ownerMismatch === 0 :
|
|
664
|
-
mode: request.mode ? modeMismatch === 0 :
|
|
661
|
+
count: request.count ? expected.count === actual.count : null,
|
|
662
|
+
sha256: request.sha256 ? expected.rootSha256 === actual.rootSha256 : null,
|
|
663
|
+
owner: request.owner ? ownerMismatch === 0 : null,
|
|
664
|
+
mode: request.mode ? modeMismatch === 0 : null,
|
|
665
665
|
deletions: request.deletions
|
|
666
666
|
? deletionBaseline !== undefined && remainingDeletionCandidates.length === 0
|
|
667
|
-
:
|
|
668
|
-
staleFiles: request.staleFiles ? stale === 0 :
|
|
667
|
+
: null,
|
|
668
|
+
staleFiles: request.staleFiles ? stale === 0 : null,
|
|
669
669
|
};
|
|
670
670
|
return {
|
|
671
671
|
kind: 'directory',
|
|
672
|
-
matched: Object.values(checks).every(
|
|
672
|
+
matched: Object.values(checks).every((value) => value !== false),
|
|
673
673
|
checks,
|
|
674
674
|
expected: { count: expected.count, rootSha256: request.sha256 ? expected.rootSha256 : undefined },
|
|
675
675
|
actual: { count: actual.count, rootSha256: request.sha256 ? actual.rootSha256 : undefined },
|
package/dist/file-ops.d.ts
CHANGED
|
@@ -91,7 +91,7 @@ export declare class UploadFileError extends Error {
|
|
|
91
91
|
/**
|
|
92
92
|
* 上传文件
|
|
93
93
|
*/
|
|
94
|
-
export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, createMode?: number, signal?: AbortSignal, followSymlinks?: boolean, exclusive?: boolean, timeout?: number): Promise<{
|
|
94
|
+
export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, createMode?: number, signal?: AbortSignal, followSymlinks?: boolean, exclusive?: boolean, timeout?: number, throttle?: (bytes: number) => Promise<void>): Promise<{
|
|
95
95
|
success: boolean;
|
|
96
96
|
size: number;
|
|
97
97
|
createMode: string;
|
|
@@ -99,7 +99,7 @@ export declare function uploadFile(alias: string, localPath: string, remotePath:
|
|
|
99
99
|
/**
|
|
100
100
|
* 下载文件
|
|
101
101
|
*/
|
|
102
|
-
export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, signal?: AbortSignal, timeout?: number): Promise<{
|
|
102
|
+
export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, signal?: AbortSignal, timeout?: number, throttle?: (bytes: number) => Promise<void>): Promise<{
|
|
103
103
|
success: boolean;
|
|
104
104
|
size: number;
|
|
105
105
|
atomic: true;
|
|
@@ -141,12 +141,12 @@ type ReadFileResult = {
|
|
|
141
141
|
* 读取远程文件内容
|
|
142
142
|
*/
|
|
143
143
|
export declare function readFile(alias: string, remotePath: string, options?: number | ReadFileOptions): Promise<ReadFileResult>;
|
|
144
|
-
export declare function createEmptyRemoteFile(alias: string, remotePath: string, timeout?: number): Promise<void>;
|
|
145
|
-
export declare function prepareWindowsRemotePrivateFile(alias: string, remotePath: string, timeout?: number, shellPath?: string): Promise<void>;
|
|
144
|
+
export declare function createEmptyRemoteFile(alias: string, remotePath: string, timeout?: number, signal?: AbortSignal): Promise<void>;
|
|
145
|
+
export declare function prepareWindowsRemotePrivateFile(alias: string, remotePath: string, timeout?: number, shellPath?: string, signal?: AbortSignal): Promise<void>;
|
|
146
146
|
/**
|
|
147
147
|
* 写入远程文件
|
|
148
148
|
*/
|
|
149
|
-
export declare function writeFile(alias: string, remotePath: string, content: string, append?: boolean, timeout?: number): Promise<{
|
|
149
|
+
export declare function writeFile(alias: string, remotePath: string, content: string, append?: boolean, timeout?: number, signal?: AbortSignal): Promise<{
|
|
150
150
|
success: boolean;
|
|
151
151
|
size: number;
|
|
152
152
|
}>;
|
|
@@ -173,6 +173,8 @@ type SyncOptions = {
|
|
|
173
173
|
recursive?: boolean;
|
|
174
174
|
followSymlinks?: boolean;
|
|
175
175
|
verifySha256?: boolean;
|
|
176
|
+
bandwidthLimitKiBps?: number;
|
|
177
|
+
throttle?: (bytes: number) => Promise<void>;
|
|
176
178
|
preflightTimeout?: number;
|
|
177
179
|
connectTimeout?: number;
|
|
178
180
|
operationTimeout?: number;
|
|
@@ -225,6 +227,8 @@ type SyncResult = {
|
|
|
225
227
|
connectStatus?: 'completed' | 'failed' | 'not_applicable';
|
|
226
228
|
operationStatus?: 'completed' | 'failed' | 'unknown';
|
|
227
229
|
failureStage?: string;
|
|
230
|
+
cancelled?: boolean;
|
|
231
|
+
lastProgress?: TransferProgress;
|
|
228
232
|
timedOut?: boolean;
|
|
229
233
|
retryable?: boolean;
|
|
230
234
|
direction?: 'upload' | 'download';
|