From 027e6b710caf7d97e46d145b03aad52551d6df2a Mon Sep 17 00:00:00 2001 From: yetao Date: Tue, 29 Oct 2024 16:42:05 +0800 Subject: [PATCH] =?UTF-8?q?refactor=F0=9F=8E=A8:=20=20(=E9=98=85=E8=AF=BB?= =?UTF-8?q?=E4=BB=A3=E7=A0=81)=EF=BC=9Assh2.ts=E5=A2=9E=E5=8A=A0=E6=B3=A8?= =?UTF-8?q?=E9=87=8A?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- common/src/ssh2.ts | 561 +++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 543 insertions(+), 18 deletions(-) diff --git a/common/src/ssh2.ts b/common/src/ssh2.ts index ae7c3f4..bf5a999 100644 --- a/common/src/ssh2.ts +++ b/common/src/ssh2.ts @@ -1,79 +1,119 @@ declare module 'ssh2' { + // 导入 net 模块，可能用于网络通信相关操作 import * as net from 'net'; + // 从 'ssh2/lib/agent' 导入 BaseAgent 类，可能是用于代理相关的功能 import { BaseAgent } from 'ssh2/lib/agent'; + // 从 'ssh2/lib/protocol/keyParser' 导入 parseKey 函数和 ParsedKey 类型，用于解析密钥相关操作 import { ParsedKey, parseKey } from 'ssh2/lib/protocol/keyParser'; + // 导入 'ssh2/lib/protocol/SFTP' 中的特定类型，用于 SFTP 相关操作 import type * as sftp from 'ssh2/lib/protocol/SFTP'; + // 从 'ssh2/lib/protocol/SFTP' 导入与 SFTP 相关的常量和函数，用于处理 SFTP 的状态码、标志等 import { flagsToString, OPEN_MODE, SFTP, STATUS_CODE, stringToFlags } from 'ssh2/lib/protocol/SFTP'; + // 导入 stream 模块，可能用于流相关的操作 import * as stream from 'stream'; // Export all the agent stuff. The exported members in it are also directly exported in the main module + // 这里将来自 'ssh2/lib/agent' 的所有内容导出，在主模块中也可以直接使用这些导出的成员。 export * from 'ssh2/lib/agent'; // Export type SFTP type so the user doesn't have to import `ssh2/lib/protocol/SFTP` to use it as a type. // The class/value itself is not exported here, since code-wise it also isn't present in the main module! + // 导出 SFTP 类型，这样用户不必导入 'ssh2/lib/protocol/SFTP' 就可以将其作为类型使用。 + // 该类或值本身在这里不被导出，因为从代码角度看它在主模块中也不存在。 export type { SFTP }; // Export all the other SFTP types as a type-only namespace (e.g. Stats, Attributes, ...) + // 将所有其他 SFTP 相关的类型作为仅类型的命名空间导出（例如 Stats、Attributes 等）。 export { sftp }; /** Used in {@link HandshakeNegotiation} */ + // 定义一个接口，表示握手协商算法。 export interface HandshakeNegotiationAlgorithms { /** The ciphre used, e.g. `aes128-gcm */ + // 所使用的加密算法，例如 'aes128-gcm'。 cipher: string; /** The mac. Can be an empty string, e.g. for AES in GCM mode */ + //消息认证码。可以为空字符串，例如在 AES GCM 模式下。 mac: string; + // 压缩算法。 compress: string; + // 语言。 lang: string; } /** Used for the `handshake` event on {@link Client} */ + // 定义一个接口，表示握手协商。 export interface HandshakeNegotiation { + // 密钥。 key: string; + // 服务器主机密钥。 srvHostKey: string; /** Client to server algorithms */ + // 客户端到服务器的算法。 cs: HandshakeNegotiationAlgorithms; /** Server to client algorithms */ + // 服务器到客户端的算法。 sc: HandshakeNegotiationAlgorithms; } /** Used for the `handshake` event on {@link Client} and in {@link AuthHandlerKeyboardInteractive} */ + // 定义一个接口，表示键盘交互式认证。 export type KeyboardInteractiveListener = ( + // 用户名。 name: string, + // 指令。 instructions: string, + // 语言。 instructionsLang: string, + // 提示信息数组，每个元素包含一个提示字符串和一个表示是否回显输入的布尔值。 prompts: { prompt: string; echo: boolean }[], + // 完成回调函数，接收用户输入的答案数组作为参数。 finish: (answers: string[]) => void ) => void; /** Used for the `tcp connection` event on {@link Client} */ + // 定义一个接口，表示 TCP 连接详细信息。 export interface TcpConnectionDetails { /** The remote IP the connection was received on (given in earlier call to `forwardIn()`). */ + // 连接接收时的远程 IP 地址（在之前对 `forwardIn()` 的调用中给出）。 destIP: string; /** The remote port the connection was received on (given in earlier call to `forwardIn()`). */ + // 连接接收时的远程端口号（在之前对 `forwardIn()` 的调用中给出）。 destPort: number; /** The originating IP of the connection. */ + // 连接的发起 IP 地址。 srcIP: string; /** The originating port of the connection. */ + // 连接的发起端口号。 srcPort: number; } /** Used for the `unix connection` event on {@link Client} */ + // 定义一个接口，表示 Unix 连接的详细信息。 export interface UnixConnectionDetails { /** The original UNIX socket path of the connection */ + // 连接的原始 Unix 套接字路径。 socketPath: string; } /** Used for the `x11` event on {@link Client} */ + // 定义一个接口，表示 X11 连接的详细信息。 export interface X11ConnectionDetails { /** The originating IP of the connection. */ + // 连接的发起 IP 地址。 srcIP: string; /** The originating port of the connection. */ + // 连接的发起端口号。 srcPort: number; } /** Used in {@link Algorithms}. Either an exact list or an object on how to modify the default list */ + // 定义一个类型，表示算法的条目。可以是一个字符串数组，也可以是一个对象，用于修改默认的算法列表。 export type AlgorithmEntry = string[] | { + // 可选的追加算法列表。 append?: (string | RegExp)[]; + // 可选的前置算法列表。 prepend?: (string | RegExp)[]; + // 可选的移除算法列表。 remove?: (string | RegExp)[]; }; @@ -82,73 +122,123 @@ declare module 'ssh2' { * See [the documentation](https://github.com/mscdex/ssh2/tree/master#api) of * the version you use to see the default/supported list algorithms. */ + /** + * 用于 {@link ConnectConfig.algorithms}. + * 查看 [文档](https://github.com/mscdex/ssh2/tree/master#api) + * 以了解默认和受支持的算法列表。 + */ + // 定义一个接口，表示算法集合。 export interface Algorithms { + // 加密算法，可选。 cipher?: AlgorithmEntry; + // 压缩算法，可选。 compress?: AlgorithmEntry; + // 哈希消息认证码算法，可选。 hmac?: AlgorithmEntry; + // 密钥交换算法，可选。 kex?: AlgorithmEntry; + // 服务器主机密钥算法，可选。 serverHostKey?: AlgorithmEntry; } - + + // 定义一个名为 AuthHandlerFunction 的类型，它可以是以下两种函数类型之一。 export type AuthHandlerFunction = + // 第一种函数类型：接收剩余的认证方法列表和部分成功的标志，返回认证处理对象、认证处理对象的类型或者 false。 ((methodsLeft: string[], partialSuccess: boolean) => AuthHandlerObject | AuthHandlerObject['type'] | false) + // 第二种函数类型：接收剩余的认证方法列表、部分成功的标志以及一个回调函数，在函数体内调用回调函数并传入认证处理对象、认证处理对象的类型或者 false。 | ((methodsLeft: string[], partialSuccess: boolean, callback: (method: AuthHandlerObject | AuthHandlerObject['type'] | false) => void) => void); + // 定义一个接口，表示认证处理方式为无认证。 export interface AuthHandlerNone { + // 认证类型为 'none'，表示无认证。 type: 'none'; + // 用户名。 username: string; } + // 定义一个接口，表示认证处理方式为密码认证。 export interface AuthHandlerPassword { + // 认证类型为 'password'，表示密码认证。 type: 'password'; + // 用户名。 username: string; + // 密码。 password: string; } + // 定义一个接口，表示认证处理方式为公钥认证。 + export interface AuthHandlerPublicKey { + // 认证类型为 'publickey'，表示公钥认证。 type: 'publickey'; + // 用户名。 username: string; /** Should be (parseable to) a ParsedKey containing a private key */ + // 应该是一个 ParsedKey，包含一个私钥。 key: string | Buffer | ParsedKey; /** Optional passphrase in case `key` is an encrypted key */ + // 可选的密码短语。 passphrase?: string; /** [PATCH:convertSha1#309] If true, make ssh-rsa keys use sha512/sha256 instead of sha1 if possible */ + // [PATCH:convertSha1#309] 如果为 true，则使 ssh-rsa 密钥使用 sha512/sha256 而不是 sha1（如果可能）。 convertSha1?: boolean; } + // 定义一个接口，表示认证处理方式为基于主机的认证。 export interface AuthHandlerHostBased { + // 认证类型为 'hostbased'，表示基于主机的认证。 type: 'hostbased'; + // 用户名。 username: string; + // 可选的密码短语。 localHostname: string; + // 可选的密码短语。 localUsername: string; /** Should be (parseable to) a ParsedKey containing a private key */ + // 应该是一个 ParsedKey，包含一个私钥。 key: string | Buffer | ParsedKey; /** Optional passphrase in case `key` is an encrypted key */ + // 可选的密码短语。 passphrase?: string; } + // 定义一个接口，表示认证处理方式为代理认证。 export interface AuthHandlerAgent { + // 认证类型为 'agent'，表示代理认证。 type: 'agent'; + // 用户名。 username: string; + // 可选的代理路径。 agent: string | BaseAgent; /** [PATCH:convertSha1#309] If true, make ssh-rsa keys use sha512/sha256 instead of sha1 if possible */ + // [PATCH:convertSha1#309] 如果为 true，则使 ssh-rsa 密钥使用 sha512/sha256 而不是 sha1（如果可能）。 convertSha1?: boolean; } + // 定义一个接口，表示认证处理方式为键盘交互式认证。 export interface AuthHandlerKeyboardInteractive { + // 认证类型为 'keyboard-interactive'，表示键盘交互式认证。 type: 'keyboard-interactive'; + // 用户名。 username: string; + // 可选的密码短语。 prompt: KeyboardInteractiveListener; } - + + // 定义一个类型，表示认证处理方式。公钥认证、密码认证 export type AuthHandlerObject = - | AuthHandlerNone | AuthHandlerPassword | AuthHandlerPublicKey + | AuthHandlerNone | AuthHandlerPassword | AuthHandlerPublicKey | AuthHandlerHostBased | AuthHandlerAgent | AuthHandlerKeyboardInteractive; - + + // 定义一个类型，表示认证处理方式。 export type AuthHandler = AuthHandlerFunction | AuthHandlerObject; /** Used in {@link Client.connect} */ + // 定义一个接口，表示连接配置。 export interface ConnectConfig { /** Path to `ssh-agent` (Cygwin) UNIX socket or Windows pipe, or `pageant` for Pageant */ + // 可选的代理路径。 agent?: string; /** Set to true to use OpenSSH agent forwarding (`auth-agent@openssh.com`). Needs `agent` for this */ + // 可选的代理转发标志。 agentForward?: boolean; /** Explicitly override default transport layer algorithms */ + // 可选的算法配置。 algorithms?: Algorithms; /** * AuthHandler which determines in which order/way the client tries to authenticate. @@ -158,102 +248,143 @@ declare module 'ssh2' { * * Default value is `['none', 'password', 'publickey', 'agent', 'keyboard-interactive', 'hostbased']`. */ + // 可选的认证处理方式。 authHandler?: AuthHandlerObject[] | AuthHandlerFunction | AuthHandlerObject['type'][]; /** Function to be called with detailed (local) debug information */ + // 可选的调试函数。 debug?(info: string): void; /** Only connect via resolved IPv4 address for `host`. */ + // 可选的强制使用 IPv4 地址的标志。 forceIPv4?: boolean; /** Only connect via resolved IPv6 address for `host`. */ + // 可选的强制使用 IPv6 地址的标志。 forceIPv6?: boolean; /** Hostname or IP address of the server. Default is `localhost` */ + // 可选的主机名或 IP 地址。默认是 'localhost'。 host?: string; /** * The host's key is hashed using this method and passed to `hostVerifier`. * Supports any valid hashing algorithm that the underlying NodeJS version supports. */ + // 可选的主机密钥哈希方法。 hostHash?: string; /** * Function to verify the hex hash of the host's key for verification purposes. * Either return a boolean, or call `callback` with a boolean to continue/abort the handshake. */ + // 可选的主机密钥验证函数。 hostVerifier?: (((hash: string) => boolean) | ((hash: string, callback: (success: boolean) => void) => void)); /** How many consecutive, unanswered SSH-level keepalive packets that can be sent to the server before disconnection. Default is `3` */ + // 可选的 SSH 级别的保持活动包的最大数量。默认是 3。 keepaliveCountMax?: number; /** How often (in milliseconds) to send SSH-level keepalive packets to the server. Set to `0` to disable */ + // 可选的 SSH 级别的保持活动包的间隔时间。设置为 0 表示禁用。 keepaliveInterval?: number; /** Along with `localUsername` and `privateKey`, set this to a non-empty string for hostbased user authentication */ + // 可选的本地主机名。 localHostname?: string; /** Local port number to connect from. Default is 0, as in determined by OS */ + // 可选的本地端口号。默认是 0，由操作系统决定。 localPort?: number; /** Along with `localHostname` and `privateKey`, set this to a non-empty string for hostbased user authentication */ + // 可选的本地用户名。 localUsername?: string; /** Passphrase to decrypt the `privateKey` if necessary */ + // 可选的私钥短语。 passphrase?: string; /** Password for password-based authentication */ + // 可选的密码。 password?: string; /** Port number of the server. Default is `22` */ + // 可选的端口号。默认是 22。 port?: number; /** Private key for key-based or hostbased authentication (OpenSSH/PPK format) */ + // 可选的私钥。 privateKey?: string | Buffer; /** How long (in milliseconds) to wait for the SSH handshake to complete. Default is `20000` */ + // 可选的握手超时时间。默认是 20000。 readyTimeout?: number; /** A `ReadableStream` to communicate with the server instead of automatically creating a new TCP connection (useful for connection hopping) */ + // 可选的可读流。 sock?: NodeJS.ReadableStream; /** Perform strict server vendor check before sending vendor-specific requests, such as `openssh_noMoreSessions`. Enabled by default */ + // 可选的严格的供应商检查标志。默认是 true。 strictVendor?: boolean; /** Try keyboard-interactive user authentication if other authentication methods fail */ + // 可选的尝试键盘交互式标志。默认是 true。 tryKeyboard?: boolean; /** Username for authentication */ + // 可选的用户名。 username?: string; } + // 定义一个接口，表示伪终端选项。 export interface PseudoTtyOptions { /** The number of rows. Default is `24` */ + // 可选的行数。默认是 24。 rows: number; /** The number of columns. Default is `80` */ + // 可选的列数。默认是 80。 cols: number; /** The height in pixels. Default is `480` */ + // 可选的高度。默认是 480。 height: number; /** The width in pixels. Default is `640` */ + // 可选的宽度。默认是 640。 width: number; /** The value to use for `$TERM`. Default is `vt100` */ + // 可选的终端名称。默认是 'vt100'。 term: string; /** * Object containing Terminal Modes as keys, with each value set to each mode argument. * See [the documentation](https://github.com/mscdex/ssh2/tree/master#api) of * the version you use to see the list of supported terminal modes. */ + // 可选的终端模式。 modes: Record | null; } + // 定义一个接口，表示 X11 选项。 export interface X11Options { /** Authentication cookie. Either a Buffer or a hex string. Defaults to a random 16 byte value */ + // 可选的认证 Cookie。可以是一个 Buffer 或一个十六进制字符串。默认是一个随机的 16 字节值。 cookie: Buffer | string; /** Authentication protocol name. Defaults to `MIT-MAGIC-COOKIE-1` */ + // 可选的认证协议名称。默认是 'MIT-MAGIC-COOKIE-1'。 protocol: string; /** Screen number to use. Defaults to `0` */ + // 可选的屏幕号。默认是 0。 screen: number; /** Whether to only allow a single connection. Allows multiple by default */ + // 可选的是否只允许单个连接。默认是允许多个。 single: boolean; } /** Used in {@link Client.shell} */ + // 定义一个接口，表示 Shell 选项。 export interface ShellOptions { + // 可选的环境变量。 env?: Record; /** A {@link PseudoTtyOptions}, `true` for a default pseudo-tty or `undefined` for none */ + // 可选的伪终端选项。可以是一个伪终端选项对象、true 或 undefined。 pty: Partial | true; } /** Used in {@link Client.exec} */ + // 定义一个接口，表示执行选项。 export interface ExecOptions extends ShellOptions { /** A {@link X11Options}, `true` for default values or `undefined` for none */ + // 可选的 X11 选项。可以是一个 X11 选项对象、true 或 undefined。 x11?: Partial | true; } + // 定义一个名为 ErrorCallback 的类型，它是一个函数类型。 export type ErrorCallback = (error: Error | undefined) => void; + // 定义一个名为 ClientChannelCallback 的类型，它是一个函数类型。 export type ClientChannelCallback = (error: Error | undefined, channel: ClientChannel) => void; + // 定义一个名为 Client 的类，它继承自 NodeJS.EventEmitter。 export class Client extends NodeJS.EventEmitter { constructor(); @@ -261,25 +392,32 @@ declare module 'ssh2' { /* METHODS */ /** Attempts a connection to the server using the given config */ + // 连接到服务器的方法。 connect(config: ConnectConfig): void; /** Disconnect the socket */ + // 断开连接的方法。 end(): void; /** Executes `command` on the server */ + // 执行命令的方法。 exec(command: string, callback: ClientChannelCallback): void; exec(command: string, options: ExecOptions, callback: ClientChannelCallback): void; /** Starts an interactive shell session on the server */ + // 启动交互式 shell 会话的方法。 shell(callback: ClientChannelCallback): void; + // 重载的 shell 方法。 shell(options: ShellOptions, callback: ClientChannelCallback): void; shell(pty: Partial | false, callback: ClientChannelCallback): void; shell(pty: Partial | false, options: ShellOptions, callback: ClientChannelCallback): void; /** Starts an SFTP session. The {@link SFTP} object can be used to perform SFTP operations */ + // 启动 SFTP 会话的方法。 sftp(callback: (error: Error | undefined, sftp: SFTP) => void): void; /** Invokes `subsystem` on the server */ + // 调用子系统的方法。 subsys(subsystem: string, callback: ClientChannelCallback): void; /** @@ -294,44 +432,56 @@ declare module 'ssh2' { * - `localhost` to accept connections on all loopback addresses (any protocol family) * - `127.0.0.1` or `::1` for a specific IPv4 or IPv6 loopback addresses */ + // 绑定到远程地址和端口的方法。 forwardIn(remoteAddr: string, remotePort: number, callback: (error: Error | undefined, port: number) => void): void; /** Method to revert {@link forwardIn}. Use the actual bound port, i.e. not `0` */ + // 取消绑定的方法。 unforwardIn(remoteAddr: string, remotePort: number, callback: ErrorCallback): void; /** Opens a connection from the given address/port to the given address/port */ + // 打开连接的方法。 forwardOut(srcIP: string, srcPort: number, dstIP: string, dstPort: number, callback: ClientChannelCallback): void; /** OpenSSH extension to listen on UNIX domain sockets, similar to {@link forwardIn} */ + // 打开 UNIX 域套接字的方法。 openssh_forwardInStreamLocal(socketPath: string, callback: (error?: Error) => void): void; /** OpenSSh extension to revert {@link openssh_forwardInStreamLocal} */ + // 取消 UNIX 域套接字的方法。 openssh_unforwardInStreamLocal(socketPath: string, callback: (error?: Error) => void): void; /** OpenSSH extension to make a connection to a UNIX domain sockets, similar to {@link forwardOut} */ + // 打开 UNIX 域套接字连接的方法。 openssh_forwardOutStreamLocal(socketPath: string, callback: ClientChannelCallback): void; /* OpenSSH extension that sends a request to reject any new sessions */ + // 拒绝新会话的方法。 openssh_noMoreSessions(callback: (error?: Error) => void): void; /** Initiates a rekey with the server */ + // 重新密钥的方法。 rekey(callback?: () => void): void; /* EVENTS */ /** A notice was sent by the server upon connection */ + // 通知事件。 on(event: 'banner', listener: (message: string, language: string) => void): this; /** If using password-based user authentication, the server has requested that the user's password be changed. Call `done` with the new password. */ + // 更改密码事件。 on(event: 'change password', listener: (prompt: string, done: (password: string) => void) => void): this; /** The socket was closed */ + // 关闭事件。 on(event: 'close', listener: () => void): this; /** The socket was disconnected */ + // 结束事件。 on(event: 'end', listener: () => void): this; /** @@ -339,86 +489,120 @@ declare module 'ssh2' { `client-ssh` for SSH disconnection messages. In the case of `client-ssh` messages, there may be a `description` property that provides more detail. */ + // 发生了一个错误。一个 “level” 属性指示 “client-socket” 表示套接字级别的错误，“client-ssh” 表示 SSH 断开连接的消息。 + // 在 “client-ssh” 消息的情况下，可能会有一个 “description” 属性提供更多细节。 on(event: 'error', listener: (error: Error & { level?: string; description?: string }) => void): this; /** Emitted when an initial or rekey handshake has completed */ + // 握手事件。 on(event: 'handshake', listener: (negotiated: HandshakeNegotiation) => void): this; /** Emitted when the server announces its available host keys */ + // 主机密钥事件。 on(event: 'hostkeys', listener: (keys: ParsedKey[]) => void): this; /** Emitted when the server is asking for replies for `keyboard-interactive` user authentication*/ + // 键盘交互事件。 on(event: 'keyboard-interactive', listener: KeyboardInteractiveListener): this; /** Emitted when authentication was successful */ + // 认证成功事件。 on(event: 'ready', listener: () => void): this; /** Emitted when a rekeying operation has completed (whether initiated by the client or server) */ + // 当重新密钥操作完成时发出。 on(event: 'rekey', listener: () => void): this; /** An incoming forwarded TCP connection is being requested. Need to call either `accept` or `reject` */ + // 正在请求一个传入的转发 TCP 连接。需要调用 “accept”（接受）或者 “reject”（拒绝）。 on(event: 'tcp connection', listener: (details: TcpConnectionDetails, accept: () => ClientChannel, reject: () => void) => void): this; /** An incoming forwarded UNIX connection is being requested. Need to call either `accept` or `reject` */ + // 正在请求一个传入的转发 Unix 连接。需要调用 “accept”（接受）或者 “reject”（拒绝）。 on(event: 'unix connection', listener: (details: UnixConnectionDetails, accept: () => ClientChannel, reject: () => void) => void): this; /** An incoming X11 connection is being requested. Need to call either `accept` or `reject` */ + // 正在请求一个传入的 X11 连接。需要调用 “accept”（接受）或者 “reject”（拒绝）。 on(event: 'x11', listener: (details: X11ConnectionDetails, accept: () => ClientChannel, reject: () => void) => void): this; } /** Used to create a {@link Server} object */ + // // 定义一个接口，表示服务器配置。 export interface ServerConfig { /** Explicitly override default transport layer algorithms */ + // 显式地覆盖默认的传输层算法。 algorithms?: Algorithms; /** Message that is sent to the client immediately, before handshaking behins */ + // 在握手开始之前立即发送给客户端的消息。 greeting?: string; /** Message that is sent to the client once, right before authentication begins */ + // 在认证开始之前发送给客户端的消息。 banner?: string; /** Function to be called with detailed (local) debug information */ + // 一个在有详细的（本地）调试信息时被调用的函数。 debug?(info: string): void; /** The `highWaterMark` used for the parser stream. Default is `32 * 1024` bytes */ + // 用于解析器流的高水位标记。默认是 32 * 1024 字节。 highWaterMark?: number; /** Array of host private keys */ + // 主机私钥数组。 hostKeys: (Buffer | string | { key: Buffer | string; passphrase?: string })[]; /** Custom server software name/version identifier. Default is `'ssh2js' + version + 'srv'` */ + // 自定义服务器软件名称/版本标识符。默认是 'ssh2js' + 版本号 + 'srv'。 ident?: string; } /** Used by the `authentication` event on {@link Server} */ // Internally this is an actual class (and so are the inheriting interfaces below) but they aren't exported + // 定义一个接口，表示认证上下文基础部分。 export interface AuthContextBase { /** The username the user is try to authenticate with */ + // 用户尝试进行认证的用户名。 username: string; /** Accept the authentication request, marking as and informing the user about being authenticated */ + // 接受认证请求，标记为已认证并通知用户已通过认证。 accept(): void; /** Reject the authentication request, and optionally suggest different auth methods and/or specify it was a partial success */ + // 拒绝认证请求，可以选择地建议不同的认证方法和/或指定这是一个部分成功的情况。 reject(partialSuccess: boolean): void; reject(authMethodsLeft?: AuthContext['method'][], partialSuccess?: boolean): void; /** Emitted when the client aborts this authentication request by starting a new one */ + // 当客户端通过开始新的认证请求而中止此认证请求时触发。 on(event: "abort", listener: () => void): this; } + // 定义一个接口，表示基于主机的认证上下文，它扩展了 AuthContextBase 接口。 export interface AuthContextHostBased extends AuthContextBase { + // 认证方法为 'hostbased'。 method: 'hostbased'; key: { /** Key algorithm, such as `ssh-rsa` */ + // 密钥算法，例如 'ssh-rsa'。 algo: string; /** The public key sent by the client */ + // 客户端发送的公钥。 data: Buffer; }; + // 本地主机名。 localHostname: string; + // 本地用户名。 localUsername: string; /** Data to be verified, passed (along with `signature`) to `parseKey(key.data).verify` */ + // 要验证的数据，与 `signature` 一起传递给 `parseKey(key.data).verify`。 blob: Buffer; /** Signature to be verified, passed (along with `blob`) to `parseKey(key.data).verifiy */ + // 要验证的签名，与 `blob` 一起传递给 `parseKey(key.data).verify`。 signature: Buffer; } + // 定义一个接口，表示完整的键盘提示。 export interface KeyboardPromptFull { /** The prompt text to display to the user */ + // 要向用户显示的提示文本。 prompt: string; /** Whether the input should be visible (e.g. `false` for passwords). Default is `false` */ + // 输入是否应该可见（例如，对于密码，应为 `false`）。默认值是 `false`。 echo?: boolean; } /** @@ -426,8 +610,11 @@ declare module 'ssh2' { * Prompts that are strings are converted to {@link KeyboardPromptFull}s * with {@link KeyboardPrompt.echo} set to `true` instead of the usual default of `false`. */ + // 定义一个类型，表示键盘提示，可以是字符串、完整的键盘提示对象或者它们的数组。 export type KeyboardPrompt = string | KeyboardPromptFull | (string | KeyboardPromptFull)[]; + // 定义一个接口，表示键盘交互认证上下文，它扩展了 AuthContextBase 接口。 export interface AuthContextKeyboardInteractive extends AuthContextBase { + // 认证方法为 'keyboard-interactive'。 method: 'keyboard-interactive'; /** * Sends prompts to the clients. @@ -435,6 +622,7 @@ declare module 'ssh2' { * In case this authentication request got aborted, the callback is passed an error instead. * String prompts will have {@link KeyboardPrompt.echo} set to `true`. */ + // 向客户端发送提示。回调函数将接收与提示顺序相同的所有提示的答案列表。如果此认证请求被中止，回调函数将接收一个错误。字符串提示将把{@link KeyboardPrompt.echo}设置为`true`。 prompt(prompts: KeyboardPrompt, callback: (answers: string[] | Error) => void): void; prompt(prompts: KeyboardPrompt, title: string, callback: (answers: string[] | Error) => void): void; prompt(prompts: KeyboardPrompt, title: string, instructions: string, callback: (answers: string[] | Error) => void): void; @@ -442,69 +630,93 @@ declare module 'ssh2' { prompt(prompts: { prompt: string; echo: boolean }[], instructions: string, callback: (answers: string[]) => void): void; /** List of preferred authentication "sub-methods" sent by the client */ + // 客户端发送的首选认证“子方法”列表。 submethods: string[]; } - + + // 定义一个接口，表示密码认证上下文，它扩展了 AuthContextBase 接口。 export interface AuthContextPassword extends AuthContextBase { + // 认证方法为 'password'。 method: 'password'; + // 密码字符串。 password: string; /** Sends a password change request to the client */ + // 向客户端发送密码更改请求。 requestChange(prompt: string, callback: (newPassword: string) => void): void; } + // 定义一个接口，表示公钥认证上下文，它扩展了 AuthContextBase 接口。 export interface AuthContextPublicKey extends AuthContextBase { + // 认证方法为 'publickey'。 method: 'publickey'; key: { /** Key algorithm, such as `ssh-rsa` */ + // 密钥算法，例如 'ssh-rsa'。 algo: string; /** The public key sent by the client */ + // 客户端发送的公钥。 data: Buffer; }; /** * Data to be verified, which should be passed with `signature` to `parseKey(key.data).verify`. * Can be `undefined` if the client is only checking the validity of the public key. */ + // 要验证的数据，应与 `signature` 一起传递给 `parseKey(key.data).verify`。如果客户端仅检查公钥的有效性，则可以为 `undefined`。 blob?: Buffer; /** * Data to be verified, which should be passed with `blob` to `parseKey(key.data).verify`. * Can be `undefined` if the client is only checking the validity of the public key. */ + // 要验证的数据，应与 `blob` 一起传递给 `parseKey(key.data).verify`。如果客户端仅检查公钥的有效性，则可以为 `undefined`。 signature?: Buffer; } - + + // 定义一个类型，表示认证上下文，可以是主机认证上下文、键盘交互认证上下文、密码认证上下文或公钥认证上下文。 export type AuthContext = AuthContextHostBased | AuthContextKeyboardInteractive | AuthContextPassword | AuthContextPublicKey; /** Used by the `connection` event on {@link Server} */ + // 定义一个接口，表示连接信息。 export interface ConnectionInfo { + // IP 地址字符串。 ip: string; + // IP 地址的地址族，例如 'IPv4' 或 'IPv6'。 family: string; + // 端口号。 port: number; /** Information about the client's header */ + // 客户端的头部信息。 header: { identRaw: string; versions: { /** SSH protocol version */ + // SSH 协议版本。 protocol: '1.99' | '2.0'; /** Software name and version of the client */ + // 客户端的软件名称和版本。 software: string; }; /** Any text that comes after the software name/version */ + // 软件名称/版本之后的任何文本。 comments: string; }; } + // 定义一个接口，表示通道，继承自 stream.Duplex。 export interface Channel extends stream.Duplex { /** * Similar as used in {@link net.Socket}: * If set to `true` (the default), and the stream's `end()` is called, only an EOF * if sent. The other side of the channel can still send data if they haven't sent EOF yet. */ + // 与{@link net.Socket}中的用法类似：如果设置为`true`（默认值），并且调用了流的`end()`，则仅发送一个 EOF。通道的另一端如果还没有发送 EOF，则仍然可以发送数据。 allowHalfOpen: boolean; /** For exec/shell channels, this is a Readable on the client and a Writable on the server*/ + // 对于执行/外壳通道，在客户端这是一个可读流，在服务器端这是一个可写流。 stderr?: stream.Readable | stream.Writable; /** Closes the channel */ + // 关闭通道。 close(): void; /** @@ -512,21 +724,25 @@ declare module 'ssh2' { * The exact arguments passed can be the same as `exit` in a ClientChannel but is unclear. * Might be arguments from the `close` event emitteed by `stream.Duplex` too, who knows. */ + // 一旦通道在客户端和服务器端都完全关闭时触发。传递的确切参数可能与客户端通道中的`exit`相同，但不清楚。也可能是来自`stream.Duplex`发出的`close`事件的参数，谁知道呢。 on(event: 'close', listener: () => void): this; on(event: string, listener: (...args: any) => void): this; } + // 定义一个接口，表示客户端通道，继承自 Channel 接口。 export interface ClientChannel extends Channel { /** Only available for `exec` and `shell` channels */ + // 仅在`exec`（执行）和`shell`（外壳）通道可用。 stderr?: stream.Readable | stream.Writable; /** * Only available for `exec` and `shell` channels. * Lets the server know tha tthe local terminal window has been resized. */ + // 仅在`exec`和`shell`通道可用。让服务器知道本地终端窗口已被调整大小。 setWindow?(rows: number, cols: number, height: number, width: number): void; /** @@ -537,6 +753,9 @@ declare module 'ssh2' { * Some server implementations may ignore this request if they do not support signals. * If you're trying to send `SIGINT` and you find this method doesn't work, try writing `\x03` to this channel stream. */ + // 仅在`exec`和`shell`通道可用。向服务器上的当前进程发送 POSIX 信号。 + // 有效的信号有`ABRT`、`ALRM`、`FPE`、`HUP`、`ILL`、`INT`、`KILL`、`PIPE`、`QUIT`、`SEGV`、`TERM`、`USR1`和`USR2`。 + // 如果服务器实现不支持信号，可能会忽略此请求。如果你试图发送`SIGINT`并且发现此方法不起作用，可以尝试向此通道流写入`\x03`。 signal?(signalName: string): void; /** @@ -546,149 +765,230 @@ declare module 'ssh2' { * a signal, `null, , , ` are passed instead. * If this event got emitted, `close` gets emitted with the same arguments for convenience. */ + // 仅在`exec`通道可用。当进程完成时可能会触发的事件（SSH2 规范中说是可选的）。 + // 如果进程正常完成，则传递返回值。如果进程被信号中断，则传递`null`、``、``、``。 + // 如果此事件被触发，为了方便，`close`事件也会用相同的参数触发。 on(event: 'exit', listener: (status: number | null, signalName?: string, didCoreDump?: boolean, description?: string) => void): this; on(event: string, listener: (...args: any) => void): this; } + // 定义一个接口，表示服务器通道，继承自 Channel 接口。 export interface ServerChannel extends Channel { /** Only available for `exec` and `shell` channels */ + // 仅在`exec`（执行）和`shell`（外壳）通道可用。 stderr?: stream.Writable; /** Available for `exec` channels. Can be called right before closing the channel */ + // 仅在`exec`通道可用。可以在关闭通道之前调用。 exit?(exitCode: number): void; exit?(signalName: string, coreDumped: boolean, errorMsg: string): void; } + // 定义一个类型，表示会话请求监听器，接受一个函数，该函数返回一个类型为 R 的值，默认为 void。 + // 这个类型的函数接收两个可选的参数，分别是 accept 和 reject。 + // accept 函数用于接受会话请求，并可以返回一个类型为 R 的值。 + // reject 函数用于拒绝会话请求，不返回值。 + // 这个函数通常用于处理来自客户端的会话请求，根据需要调用 accept 或 reject 来决定是否接受请求。 export type SessionRequestListener = (accept?: () => R, reject?: () => void) => void; + // 定义一个类型，表示带有特定信息的会话请求监听器，接受一个函数，该函数返回一个类型为 R 的值，默认为 void，以及一个特定类型 T 的信息。 + // 这个类型的函数接收三个参数，分别是 accept、reject 和 info。 + // accept 函数用于接受会话请求，并可以返回一个类型为 R 的值，是可选的。 + // reject 函数用于拒绝会话请求，不返回值，是可选的。 + // info 是一个特定类型 T 的对象，包含与会话请求相关的信息。 + // 这个函数通常用于处理来自客户端的会话请求，根据 info 中的信息以及需求调用 accept 或 reject 来决定是否接受请求。 export type SessionRequestInfoListener = ( accept: ((() => R) | undefined), reject: ((() => void) | undefined), info: T ) => void; + // 定义一个接口，表示会话，继承自 NodeJS.EventEmitter。 export interface Session extends NodeJS.EventEmitter { /** The session was closed */ + // 当会话关闭时触发。 on(event: 'close'): this; /** The client requested that incoming ssh-agent request be forward to them */ + // 当客户端请求将传入的 ssh-agent 请求转发给他们时触发。 on(event: 'auth-agent', listener: SessionRequestListener): this; /** The client requested an environment variable to be set for this session */ + // 当客户端请求为这个会话设置一个环境变量时触发。 on(event: 'env', listener: SessionRequestInfoListener<{ key: string; value: string }>): this; /** The client requested execution of a command string */ + // 当客户端请求执行一个命令字符串时触发，并返回一个通道对象。 on(event: 'exec', listener: SessionRequestInfoListener<{ command: string }, Channel>): this; /** The client requested allocation of a pseudo-TTY for this session */ + // 当客户端请求为这个会话分配一个伪终端时触发，并传入伪终端选项对象。 on(event: 'pty', listener: SessionRequestInfoListener): this; /** The client requested the SFTP subsystem */ + // 当客户端请求 SFTP 子系统时触发，并返回一个 SFTP 对象。 on(event: 'sftp', listener: SessionRequestListener): this; /** The client requested an interactive shell */ + // 当客户端请求一个交互式 shell 时触发，并返回一个通道对象。 on(event: 'shell', listener: SessionRequestListener): this; /** The client requested an arbitrary subsystem */ + // 当客户端请求一个任意子系统时触发，并传入子系统名称和返回一个通道对象。 on(event: 'subsystem', listener: SessionRequestInfoListener<{ name: string }, Channel>): this; /** The client requested X11 forwarding */ + // 当客户端请求 X11 转发时触发，并传入 X11 选项对象。 on(event: 'x11', listener: SessionRequestInfoListener): this; /** The client sent a signal, e.g. `SIGUSR1` */ + // 当客户端发送一个信号（例如`SIGUSR1`）时触发，并传入信号名称对象。 on(event: 'signal', listener: SessionRequestInfoListener<{ name: string }>): this; /** The client reported a change in window dimensions during this session */ + // 当客户端在这个会话中报告窗口尺寸变化时触发，并传入伪终端选项中关于列、行、宽度和高度的部分。 on(event: 'window-change', listener: SessionRequestInfoListener< Pick >): this; } + // 定义一个类型，表示请求通道的监听器，接受一个特定类型 T 的信息，并返回一个通道对象或拒绝请求。 + // 这个类型的函数接收三个参数，分别是 accept、reject 和 info。 + // accept 函数用于接受请求并返回一个通道对象。 + // reject 函数用于拒绝请求，不返回值。 + // info 是一个特定类型 T 的对象，包含与请求通道相关的信息。 export type RequestChannelListener = (accept: () => Channel, reject: () => void, info: T) => void; + // 定义一个类型，表示通道的回调函数，接受一个可能的错误对象和一个通道对象。 + // 这个类型的函数接收两个参数，分别是 error 和 channel。 + // error 是一个可能的错误对象，如果没有错误则为 undefined。 + // channel 是一个通道对象。 export type ChannelCallback = (error: Error | undefined, channel: Channel) => void; + // 定义一个接口，表示连接，继承自 NodeJS.EventEmitter。 export interface Connection extends NodeJS.EventEmitter { /** Close the client connection */ + // 关闭客户端连接。 end(): void; /** Alert the client of an incoming TCP connection */ + // 通知客户端有一个传入的 TCP 连接，并传入绑定地址、绑定端口、远程地址、远程端口和一个回调函数。 forwardOut(boundAddr: string, boundPort: number, remoteAddr: string, remotePort: number, callback: ChannelCallback): void; /** Alert the client of an incoming UNIX domain socket connection */ + // 通知客户端有一个传入的 UNIX 域套接字连接，并传入套接字路径和一个回调函数。 openssh_forwardOutStreamLocal(socketPath: string, callback: ChannelCallback): void; /** Alert the client of an incoming X11 client connection */ + // 通知客户端有一个传入的 X11 客户端连接，并传入源地址、源端口和一个回调函数。 x11(originAddr: string, originPort: number, callback: ChannelCallback): void; /** Initiates a rekey with the client */ + // 发起与客户端的重新密钥操作，可以传入一个可选的回调函数。 rekey(callback?: () => void): void; /** The client has requested authentication. See {@link AuthContext} */ + // 当客户端请求认证时触发，并传入认证上下文对象。 on(event: 'authentication', listener: (context: AuthContext) => void): this; /** Emitted when the client has been successfully authenticated */ + // 当客户端成功认证时触发。 on(event: 'ready', listener: () => void): this; /** The client socket was closed */ + // 当客户端套接字关闭时触发。 on(event: 'close', listener: () => void): this; /** The client socket disconnected */ + // 当客户端套接字断开连接时触发。 on(event: 'end', listener: () => void): this; /** An error occured */ + // 当发生错误时触发，并传入错误对象。 on(event: 'error', listener: (error: Error) => void): this; /** Emitted when a handshake (initial or rekey) has completed */ + // 当握手（初始或重新密钥）完成时触发，并传入握手协商对象。 on(event: 'handshake', listener: (handshake: HandshakeNegotiation) => void): this; /** Emitted when a rekeying operation has been completed (whether client or server-initiated) */ + // 当重新密钥操作完成时触发，无论由客户端还是服务器发起。 on(event: 'rekey', listener: () => void): this; + // 当客户端请求一个新会话时触发，并传入接受和拒绝函数，用于决定是否创建会话。 + // 当触发'request'事件时，会调用传入的监听器函数。 + // 这个函数返回 this，以便可以进行链式调用。 on(event: 'request', listener: ( + // accept 参数是一个函数或 undefined，当调用它时（可传入一个可选的端口号），表示接受请求。 accept: (((port?: number) => void) | undefined), + // reject 参数是一个函数，当调用它时，表示拒绝请求。 reject: ((() => void) | undefined), + // name 参数是一个字符串，表示请求的名称。 name: string, + // info 参数是一个任意类型的值，包含与请求相关的额外信息。 info: any ) => void): this; /** Emitted when the client has request a new session. Used to start interactive shells, X11, ... */ + // 当客户端请求一个新会话时触发，并传入接受和拒绝函数，用于决定是否创建会话。 on(event: 'session', listener: (accept: () => Session, reject: () => void) => void): this; /** Emitted when the client has requested an outbound TCP connection */ + // 当客户端请求一个出站 TCP 连接时触发，并传入接受、拒绝和 TCP 连接细节信息，用于处理连接请求。 on(event: 'openssh.streamlocal', listener: RequestChannelListener): this; /** Emitted when the client has requested a connection to a UNIX domain socket */ + // 当客户端请求连接到一个 UNIX 域套接字时触发，并传入接受、拒绝和 UNIX 连接细节信息，用于处理连接请求。 on(event: 'openssh.streamlocal', listener: RequestChannelListener): this; } + // 定义一个类型，表示连接监听器。 + // 这个类型的函数接收两个参数。 + // client 参数是一个 Connection 类型的对象，表示与客户端的连接。 + // info 参数是一个 ConnectionInfo 类型的对象，包含与连接相关的信息。 + // 这个函数通常用于处理客户端连接的事件，例如当有新的客户端连接时被调用。 export type ConnectionListener = (client: Connection, info: ConnectionInfo) => void; + // 定义一个类，表示服务器，继承自 NodeJS.EventEmitter。 export class Server extends NodeJS.EventEmitter { - + + // 构造函数接受服务器配置对象和可选的连接监听器函数。 constructor(config: ServerConfig, connectionListener?: ConnectionListener); // Methods "inherited" from (internally linked to) {@link net.Server} + // 继承自 net.Server 的 listen 方法，用于启动服务器监听指定端口。 listen: net.Server['listen']; + // 继承自 net.Server 的 close 方法，用于关闭服务器。 close: net.Server['close']; + // 继承自 net.Server 的 address 方法，返回服务器正在监听的地址信息。 address: net.Server['address']; + // 继承自 net.Server 的 getConnections 方法，用于获取当前的连接数量。 getConnections: net.Server['getConnections']; + // 继承自 net.Server 的 ref 方法，用于保持服务器对象不被垃圾回收。 ref: net.Server['ref']; + // 继承自 net.Server 的 unref 方法，用于允许程序在没有服务器的情况下退出。 unref: net.Server['unref']; + // 最大连接数。 maxConnections: number; /** * Inject a bidirectional stream as if it were a TCP socket. * For best compatibility, should have {@link net.Socket}-like fields such as `remoteAddress`. */ + // 注入一个双向流，就像它是一个 TCP 套接字一样。为了获得最佳兼容性，应该具有类似于{@link net.Socket}的字段，如`remoteAddress`。 injectSocket(socket: stream.Duplex): void; /** A new client has connected (and will soon go through handshaking/authentication) */ + // 当有新的客户端连接时触发，并传入连接对象和连接信息。 on(event: 'connection', listener: ConnectionListener): this; // Events "inherited" from {@link net.Server} + // 当服务器关闭时触发。 on(event: "close", listener: () => void): this; + // 当发生错误时触发，并传入错误对象。 on(event: "error", listener: (err: Error) => void): this; + // 当服务器开始监听时触发。 on(event: "listening", listener: () => void): this; + // 用于处理其他未指定的事件。 on(event: string, listener: (...args: any[]) => void): this; /** @@ -696,23 +996,29 @@ declare module 'ssh2' { * Needs to be a finite number above 0 to be enabled. * Shared between all servers. Defaults to `15000` milliseconds. */ + // 确定我们向客户端发送 ping 的频率。必须是大于 0 的有限数字才能启用。所有服务器共享此值。默认值为 15000 毫秒。 static KEEPALIVE_CLIENT_INTERVAL: number; /** * Determines how many unanswered pings we allow in a row before disconnecting the client. * Need to be a finite number >=0 to be enabled. * Shared between all servers. Defaults to `3` */ + // 确定在断开客户端连接之前，我们允许连续有多少个未应答的 ping。必须是大于等于 0 的有限数字才能启用。所有服务器共享此值。默认值为 3。 static KEEPALIVE_CLIENT_COUNT_MAX: number; } + // 定义一个名为 utils 的命名空间。 export namespace utils { + // 导出名为 parseKey 的函数。 export { parseKey }; + // 定义一个嵌套的命名空间 sftp。 export namespace sftp { + // 导出一些常量或函数。 export { - OPEN_MODE, - STATUS_CODE, - flagsToString, - stringToFlags, + OPEN_MODE, // 可能是与 SFTP 文件打开模式相关的常量。 + STATUS_CODE, // 可能是与 SFTP 操作状态码相关的常量。 + flagsToString, // 可能是将标志转换为字符串的函数。 + stringToFlags, // 可能是将字符串转换为标志的函数。 } } } @@ -720,38 +1026,60 @@ declare module 'ssh2' { } +// 声明一个名为 'ssh2/lib/protocol/SFTP' 的模块。 +// 这里可以包含对这个模块的具体类型声明、接口定义、函数声明等内容。 +// 通常用于为一个外部模块提供类型信息，以便在 TypeScript 项目中正确使用该模块并进行类型检查。 declare module 'ssh2/lib/protocol/SFTP' { + // 从 'ssh2' 模块导入特定的类型和函数。 + // Channel 可能表示 SSH 连接中的一个通信通道。 + // Client 可能是用于建立 SSH 连接的客户端对象。 + // ErrorCallback 可能是用于处理错误的回调函数类型。 import { Channel, Client, ErrorCallback } from 'ssh2'; + // 导入 Node.js 的流模块，用于处理数据的流式传输。 import * as stream from 'stream'; + // 定义一个唯一的符号常量 Handle。 const Handle: unique symbol; /** File handles are represented by a Buffer with a special value. Ignore the contents */ + // 文件句柄由一个带有特殊值的 Buffer 表示。忽略其内容。 + // 定义一个类型 Handle，它可以是一个 Buffer 对象或者是一个带有特殊值的 Buffer 对象与 Handle 符号常量的联合类型。 export type Handle = Buffer | Buffer & typeof Handle; + // 定义一个接口，表示 SFTP 的选项。 export interface SFTPOptions { /** Whether to read Uint64BE's as BigInts (or only for large numbers). Disabled by default */ + // 是否将大端序的 Uint64BE 类型数据读取为 BigInt（或者仅在处理大数字时这么做）。默认情况下禁用。 biOpt?: 'always' | 'maybe' | 'never'; /** Function to be called with detailed (local) debug information */ + // 一个函数，当调用时会传入详细的（本地）调试信息。 debug?(info: string): void; } /** Used in {@link SFTP.fastGet} */ + // 定义一个接口，表示快速操作的选项。 export interface FastOptions { /** Number of concurrent reads. Default is `64` */ + // 并发读取的数量。默认值是 64。 concurrency?: number; /** Size of each read in bytes. Default is `32768` */ + // 每次读取的字节大小。默认值是 32768。 chunkSize?: number; /** Called every time a part of a file was transferred */ + // 每次传输一部分文件时被调用。 + // 参数 totalTransferred 表示已传输的总字节数，chunk 表示本次传输的字节数，total 表示文件的总字节数。 step?(totalTransferred: number, chunk: number, total: number): void; } /** Used in {@link SFTP.fastPut} */ + // 定义一个接口，表示带有模式的快速操作选项，继承自 FastOptions 接口。 export interface FastOptionsWithMode extends FastOptions { /** File mode to set for the uploaded file */ + // 要为上传的文件设置的文件模式，可以是数字或字符串形式。 mode?: number | string; } /** Used in {@link SFTP.createWriteStream} */ + // // 定义一个接口，表示写流的选项。 export interface WriteStreamOptions { /** * Flags to open the remote file with: @@ -759,107 +1087,164 @@ declare module 'ssh2/lib/protocol/SFTP' { * - For {@link SFTP.createWriteStream} the default is `w` * - For {@link SFTP.createWriteStream} you might have to use `r+` to avoid replacing the whole file */ + // 用于打开远程文件的标志。对于{@link SFTP.createReadStream}，默认是`r`（只读）；对于{@link SFTP.createWriteStream}，默认是`w`（只写）；对于写入流，可能需要使用`r+`以避免完全替换整个文件。 flags?: string; + // 编码方式，可以是字符串或 null。 encoding?: string | null; /** File mode to set for the uploaded file */ + // 要为上传的文件设置的文件模式，可以是数字或字符串形式。 mode?: number | string; /** If false, the file handle will never close, even on error. Defaults is `true` */ + // 如果为 false，文件句柄即使在发生错误时也永远不会关闭。默认值是 true。 autoClose?: boolean; /** Start location to read/write to/from. Inclusive and starts at 0 */ + // 读写的起始位置。包含该位置且从 0 开始。 start?: number; } /** Used in {@link SFTP.createReadStream} */ + // 定义一个接口，表示读流的选项，继承自 WriteStreamOptions 接口。 export interface ReadStreamOptions extends WriteStreamOptions { /** Use an existing handle to read from instead */ + // 使用一个已有的句柄来进行读取。 handle?: Handle; /** End location to read from. Inclusive and starts at 0 */ + // 读取的结束位置。包含该位置且从 0 开始。 end?: number; } /** Used in {@link SFTP.readFile} */ + // 定义一个接口，表示读取文件的选项。 export interface ReadFileOptions { /** Flag to open the remote file with. Default is `r` */ + // 用于打开远程文件的标志。默认值为`r`，表示以只读模式打开文件。 flag?: string; /** Encoding if the callback should be passed a string instead of a Buffer. Default is `null` */ + // 如果希望回调函数接收一个字符串而不是一个 Buffer 对象，这里可以指定编码方式。默认值为`null`，表示不进行编码转换，直接返回 Buffer 对象。 encoding?: string | null; } /** Used in {@link SFTP.writeFile} */ + // 定义一个接口，表示写文件的选项。 export interface WriteFileOptions { /** Flag to open the remote file with. Default is `w` (or `a` for {@link SFTP.appendFile}) */ + // 用于打开远程文件的标志。默认值是`w`，表示以只写模式打开文件，如果是{@link SFTP.appendFile}方法调用时默认值是`a`，表示以追加模式打开文件。 flag?: string; /** Encoding of the data if is a string. Default is `utf8` */ + // 如果写入的数据是字符串类型，这里指定编码方式。默认值是`utf8`编码。 encoding?: string; /** File mode to set for the uploaded file. Default is `0o666` */ + // 要为上传的文件设置的文件模式，可以是数字或字符串形式。默认值是八进制的`0o666`，表示文件的权限模式。 mode?: number | string; } + // 定义一个接口，表示属性。 export interface Attributes { /** Mode/permission for the resource */ + // 资源的模式/权限。例如文件的读、写、执行权限等的组合值。 mode?: number; /** User ID of the resource */ + // 资源的用户 ID。用于确定资源的所有者。 uid?: number; /** Group ID of the resource */ + // 资源的组 ID。用于确定资源所属的用户组。 gid?: number; /** Resource size in bytes */ + // 资源的大小，以字节为单位。 size?: number; /** UNIX timestamp of the access time of the resource */ + // 资源的访问时间的 UNIX 时间戳。记录了资源最后一次被访问的时间。 atime?: number; /** UNIX timestamp of the modified time of the resource */ + // 资源的修改时间的 UNIX 时间戳。记录了资源最后一次被修改的时间。 mtime?: number; } + // 定义一个接口，表示统计信息，继承自 Attributes 接口。 export interface Stats extends Attributes { + // 如果资源是一个目录，则返回 true。 isDirectory(): boolean; + // 如果资源是一个文件，则返回 true。 isFile(): boolean; + // 如果资源是一个块设备，则返回 true。 isBlockDevice(): boolean; + // 如果资源是一个字符设备，则返回 true。 isCharacterDevice(): boolean; + // 如果资源是一个符号链接，则返回 true。 isSymbolicLink(): boolean; + // 如果资源是一个 FIFO（命名管道），则返回 true。 isFIFO(): boolean; + // 如果资源是一个套接字，则返回 true。 isSocket(): boolean; } + // 定义一个类型，表示句柄回调函数。 + // 这个类型的函数接收两个参数。 + // error 参数是一个可能的错误对象，如果没有错误则为 undefined。 + // handle 参数是一个类型为 Handle 的值，可能代表文件句柄或其他特定的标识。 export type HandleCallback = (error: Error | undefined, handle: Handle) => void; + // 定义一个类型，表示统计信息回调函数。 + // 这个类型的函数接收两个参数。 + // error 参数是一个可能的错误对象，如果没有错误则为 undefined。 + // stats 参数是一个类型为 Stats 的对象，可能包含文件或资源的统计信息，如大小、权限、时间戳等。 export type StatsCallback = (error: Error | undefined, stats: Stats) => void; /** Used in {@link SFTP.attrs} */ + // 定义一个接口，表示部分目录条目信息。 export interface DirectoryEntryPartial { + // 文件名。 filename: string; /** `ls -l`-style format, e.g. `-rwxr--r-- 1 bar bar 718 Dec 8 2009 foo` */ + // 类似于 `ls -l` 命令输出的格式字符串，例如权限、所有者、大小、日期等信息的组合。 longname: string; /** Attributes. Always present from e.g. {@link SFTP.readdir} but optional for {@link SFTP.attrs} */ + // 属性对象。在例如{@link SFTP.readdir}方法中通常会存在，但在{@link SFTP.attrs}方法中是可选的。 attrs?: Attributes; } /** Used in {@link SFTP.readdir} */ + // 定义一个接口，表示目录条目，继承自 DirectoryEntryPartial 接口。 export interface DirectoryEntry extends DirectoryEntryPartial { + // 一个包含资源属性的对象。 + // attrs 属性是一个 Attributes 类型的对象，它可能包含诸如资源的模式/权限、用户 ID、组 ID、大小、访问时间和修改时间等信息。 attrs: Attributes; } /** Used in {@link SFTP.ext_openssh_statvfs} and {@link SFTP.ext_openssh_fstatvfs} */ + // 定义一个接口，表示虚拟文件系统统计信息。 export interface StatsVfs { /** File system block size */ + // 文件系统的块大小。通常以字节为单位，用于衡量文件系统存储数据的基本单元大小。 f_bsize: number; /** Fundamental fs block size */ + // 基本文件系统块大小。可能与 f_bsize 有所不同，具体含义取决于特定的文件系统实现。 f_frsize: number; /** Number of blocks (unit f_frsize) */ + // 以 f_frsize 为单位的块数量。表示文件系统中可用的块总数。 f_blocks: number; /** Free blocks in file system */ + // 文件系统中的空闲块数量。 f_bfree: number; /** Free blocks for unprivileged users */ + // 非特权用户可用的空闲块数量。 f_bavail: number; /** Total file inodes */ + // 文件系统中的总索引节点数量。索引节点用于跟踪文件和目录的信息。 f_files: number; /** Free file inodes */ + // 文件系统中的空闲索引节点数量 f_ffree: number; /** Free file inodes for unprivileged users */ + // 非特权用户可用的空闲索引节点数量。 f_favail: number; /** File system id */ + // 文件系统的标识符。可能用于区分不同的文件系统实例。 f_sid: number; /** Bit mask of f_flag values */ + // f_flag 值的位掩码。可能用于表示文件系统的特定属性或状态标志。 f_flag: number; /** Maximum filename length */ + // 文件名的最大长度。 f_namemax: number; } @@ -877,69 +1262,88 @@ declare module 'ssh2/lib/protocol/SFTP' { /* CLIENT-ONLY METHODS */ /** **Client-only**: Downloads a file using parallel reads for faster throughput */ + // **客户端-only**：使用并行读取来提高吞吐量下载文件。 fastGet(remotePath: string, localPath: string, callback: ErrorCallback): void; fastGet(remotePath: string, localPath: string, options: FastOptions, callback: ErrorCallback): void; /** **Client-only**: Uploads a file using parallel reads for faster throughput */ + // **客户端-only**：使用并行读取来提高吞吐量上传文件。 fastPut(localPath: string, remotePath: string, callback: ErrorCallback): void; fastPut(localPath: string, remotePath: string, options: FastOptionsWithMode, callback: ErrorCallback): void; /** **Client-only**: Creates a readable stream from a remote file */ + // **客户端-only**：从远程文件创建可读流。 createReadStream(path: string, options?: ReadStreamOptions): stream.Readable; /** **Client-only**: Creates a writable stream to a remote file */ + // **客户端-only**：创建可写入远程文件的可写流。 createWriteStream(path: string, options?: WriteStreamOptions): stream.Writable; /** **Client-only**: Read the data from the remote file at the given path */ + // **客户端-only**：从远程文件中读取给定路径的数据。 readFile(path: string, options: ReadFileOptions & { encoding: string }, callback: (error: Error | undefined, data: string) => void): void; readFile(path: string, options: ReadFileOptions & { encoding?: null }, callback: (error: Error | undefined, data: Buffer) => void): void; readFile(path: string, options: ReadFileOptions, callback: (error: Error | undefined, data: Buffer | string) => void): void; readFile(path: string, encoding: string, callback: (error: Error | undefined, data: string) => void): void; /** **Client-only**: Write the given data to the remote file at the given path */ + // **客户端-only**：将给定的数据写入远程文件的给定路径。 writeFile(path: string, data: string | Buffer, callback?: ErrorCallback): void; writeFile(path: string, data: string | Buffer, encoding: string, callback?: ErrorCallback): void; writeFile(path: string, data: string | Buffer, options: WriteFileOptions, callback?: ErrorCallback): void; /** **Client-only**: Appends the given data to the remote file at the given path */ + // **客户端-only**：将给定的数据追加到远程文件的给定路径。 writeFile(path: string, data: string | Buffer, callback?: ErrorCallback): void; writeFile(path: string, data: string | Buffer, encoding: string, callback?: ErrorCallback): void; writeFile(path: string, data: string | Buffer, options: WriteFileOptions, callback?: ErrorCallback): void; /** **Client-only**: Check whether the given path exists, by checking whether we can {@link stat} it */ + // **客户端-only**：检查给定路径是否存在，通过检查是否可以{@link stat}它。 exists(path: string, callback: (exists: boolean) => void): void; /** **Client-only**: Opens a remote file. `flags` is any flag supported by `fs.open` except the sync flag */ + // **客户端-only**：打开远程文件。`flags`是任何支持`fs.open`的标志，除了同步标志。 open(filename: string, flags: string, attrsMode: Attributes, callback: HandleCallback): void; /** **Client-only**: Closes the resource associated with the given handle */ + // **客户端-only**：关闭与给定句柄关联的资源。 close(handle: Handle, callback: ErrorCallback): void; /** **Client-only**: Reads a chunk of bytes from the given handle and writes it to the given buffer */ + // **客户端-only**：从给定句柄中读取一个字节块，并将其写入给定缓冲区。 read(handle: Handle, buffer: Buffer, offset: number, length: number, position: number, callback: ( err: Error | undefined, bytesRead: number, /** Mind that the written bytes start at `offset` instead of just `0` */ + // 注意，写入的字节从`offset`开始，而不是从`0`开始。 buffer: Buffer, position: number) => void): void; /** **Client-only**: Writes a chunk of bytes from the given buffer and writes it to the given handle */ + // **客户端-only**：从给定缓冲区中读取一个字节块，并将其写入给定句柄。 write(handle: Handle, buffer: Buffer, offset: number, length: number, position: number, callback: ErrorCallback): void; /** **Client-only**: Retrieves attributes for the resource associated with the given handle */ + // **客户端-only**：检索与给定句柄关联的资源的属性。 fstat(handle: Handle, callback: StatsCallback): void; /** **Client-only**: Sets the attributes for the resource associated with the given handle */ + // **客户端-only**：设置与给定句柄关联的资源的属性。 fsetstat(handle: Handle, attributes: Attributes, callback: ErrorCallback): void; /** **Client-only**: Sets the access time and modified time for the resource associated with the given handle */ + // **客户端-only**：设置与给定句柄关联的资源的访问时间和修改时间。 futimes(handle: Handle, atime: Date | number, mtime: Date | number, callback: ErrorCallback): void; /** **Client-only**: Sets the owher for the resource associated with the given handle */ + // **客户端-only**：设置与给定句柄关联的资源的所有者。 fchown(handle: Handle, uid: number, gid: number, callback: ErrorCallback): void; /** **Client-only**: Sets the mode for the resource associated with the given handle */ + // **客户端-only**：设置与给定句柄关联的资源的模式。 fchmod(handle: Handle, mode: number | string, callback: ErrorCallback): void; /** **Client-only**: Opens a directory */ + // **客户端-only**：打开目录。 opendir(path: string, callback: HandleCallback): void; /** @@ -947,16 +1351,20 @@ declare module 'ssh2/lib/protocol/SFTP' { * If the location is a handle, this function may need to be called multiple times * until `list` is `false`, which indicates that no more directory entries are available. */ + // **客户端-only**：检索给定路径/句柄的目录列表。 readdir(location: string, callback: (error: Error | undefined, list: DirectoryEntry[]) => void): void; readdir(location: Handle, callback: (error: Error | undefined, list: DirectoryEntry[] | false) => void): void; /** **Client-only**: Removes the file/symlink at the given path */ + // **客户端-only**：删除给定路径的文件/符号链接。 unlink(path: string, callback: ErrorCallback): void; /** **Client-only**: Renames/moves the resource at th egiven path to a new path */ + // **客户端-only**：将给定路径的资源重命名/移动到新路径。 rename(srcPath: string, destPath: string, callback: ErrorCallback): void; /** **Client-only**: Creates a new directory at the given path */ + // **客户端-only**：在给定路径创建一个新目录。 mkdir(path: string, callback: ErrorCallback): void; mkdir(path: string, attrs: Attributes, callback: ErrorCallback): void; @@ -964,182 +1372,264 @@ declare module 'ssh2/lib/protocol/SFTP' { rmdir(path: string, callback: ErrorCallback): void; /** **Client-only**: Retrieves the attributes for a given path, following symlinks */ + // **客户端-only**：检索给定路径的属性，遵循符号链接。 stat(path: string, callback: StatsCallback): void; /** **Client-only**: Retrieves the attributes for a given path. If it's a symlink, the stats are for the link itself */ + // **客户端-only**：检索给定路径的属性。如果它是一个符号链接，那么这些属性是链接本身的属性。 lstat(path: string, callback: StatsCallback): void; /** **Client-only**: Sets the attributes for the given path */ + // **客户端-only**：设置给定路径的属性。 setstat(path: string, attributes: Attributes, callback: ErrorCallback): void; /** **Client-only**: Sets the access time and modified time for the given path */ + // **客户端-only**：设置给定路径的访问时间和修改时间。 utimes(path: string, atime: Date | number, mtime: Date | number, callback: ErrorCallback): void; /** **Client-only**: Sets the owher for the given path */ + // **客户端-only**：设置给定路径的所有者。 chown(path: string, uid: number, gid: number, callback: ErrorCallback): void; /** **Client-only**: Sets the mode for the given path */ + // **客户端-only**：设置给定路径的模式。 chmod(path: string, mode: number | string, callback: ErrorCallback): void; /** **Client-only**: Retrieves the link target for the given path */ + // **客户端-only**：检索给定路径的链接目标。 readlink(path: string, callback: (error: Error | undefined, target: string) => void): void; /** **Client-only**: Creates a symlink at the given path to the given target path */ + // **客户端-only**：在给定路径创建一个符号链接到给定目标路径。 symlink(targetPath: string, linkPath: string, callback: ErrorCallback): void; /** **Client-only**: Resolves the given path to an absolute path */ + // **客户端-only**：将给定路径解析为绝对路径。 realpath(path: string, callback: (error: Error | undefined, absolutePath: string) => void): void; /** **Client-only**: OpenSSH extension to perform a POSIX rename(3) operation */ + // **客户端-only**：OpenSSH扩展执行POSIX rename(3)操作。 ext_openssh_rename(srcPath: string, destPath: string, callback: ErrorCallback): void; /** **Client-only**: OpenSSH extension to perform a POSIX statvfs(2) operation on the given path */ + // **客户端-only**：OpenSSH扩展执行POSIX statvfs(2)操作。 ext_openssh_statvfs(path: string, callback: (error: Error | undefined, stats: StatsVfs) => void): void; /** **Client-only**: OpenSSH extension to perform a POSIX statvfs(2) operation on the open handle */ + // **客户端-only**：OpenSSH扩展执行POSIX statvfs(2)操作。 ext_openssh_fstatvfs(handle: Handle, callback: (error: Error | undefined, stats: StatsVfs) => void): void; /** **Client-only**: OpenSSH extension to perform a POSIX link(2) to create a hard link */ + // **客户端-only**：OpenSSH扩展执行POSIX link(2)以创建硬链接。 ext_openssh_hardlink(targetPath: string, linkPath: string, callback: ErrorCallback): void; /** **Client-only**: OpenSSH extension to perform a POSIX fsync(3) on the open handle */ + // **客户端-only**：OpenSSH扩展执行POSIX fsync(3)。 ext_openssh_fsync(handle: Handle, callback: ErrorCallback): void; /** **Client-only**: OpenSSH extension to perform a {@link setstat} but on a symlink itself */ + // **客户端-only**：OpenSSH扩展执行{@link setstat}，但在符号链接本身。 ext_openssh_lsetstat(path: string, attributes: Attributes, callback: ErrorCallback): void; /** **Client-only**: OpenSSH extension to perform a {@link realpath} but with support for tilde-expansion using shell-like rules */ + // **客户端-only**：OpenSSH扩展执行{@link realpath}，但支持使用类似shell的规则进行tilde展开。 ext_openssh_expandPath(path: string, callback: (error: Error | undefined, absolutePath: string) => void): void; /* CLIENT-ONLY EVENTS */ /** Emitted after the initial protocol version check has passed */ + // **客户端-only**：在初始协议版本检查通过后发出。 on(event: 'ready', listener: () => void): this; /* SERVER-ONLY METHODS */ /** **Server-only**: Send a status response for the request identified by the given id */ + // **服务器-only**：发送请求标识为给定id的响应状态。 status(reqId: number, statusCode: number, message: string): void; /** * **Server-only**: Send a handle response for the request identified by the given id. * The handle must be less than 256 bytes and is opaque to the user, it only has to be unique. */ + // **服务器-only**：发送请求标识为给定id的响应句柄。 handle(reqId: number, handle: Handle): void; /** Send a data response for the request identified by the given id */ + // **服务器-only**：发送请求标识为给定id的响应数据。 data(reqId: number, data: Buffer | string, encoding?: string): void; /** Send a name response for the request identified by the given id */ + // **服务器-only**：发送请求标识为给定id的响应名称。 name(reqId: number, names: DirectoryEntryPartial[]): void; /** Send an Attributes response for the request identified by the given id */ + // **服务器-only**：发送请求标识为给定id的响应属性。 attrs(reqId: number, attributes: Attributes): void; /* SERVER-ONLY EVENTS */ // For these, since it's more if you're creating your own SFTP/SSH server, // check https://github.com/mscdex/ssh2/blob/master/SFTP.md#useful-standalone-methods - + // 当发生 'OPEN' 事件时调用对应的监听器函数。监听器函数接收请求 ID、文件名、标志和属性对象作为参数。可能在打开文件时触发此事件。 on(event: 'OPEN', listener: (reqId: number, filename: string, flags: number, attrs: Attributes) => void): this; + // 当发生 'READ' 事件时调用对应的监听器函数。监听器函数接收请求 ID、文件句柄、偏移量和要读取的长度作为参数。可能在读取文件内容时触发此事件。 on(event: 'READ', listener: (reqId: number, handle: Handle, offset: number, length: number) => void): this; + // 当发生 'WRITE' 事件时调用对应的监听器函数。监听器函数接收请求 ID、文件句柄、偏移量和要写入的数据（以 Buffer 形式）作为参数。可能在写入文件内容时触发此事件。 on(event: 'WRITE', listener: (reqId: number, handle: Handle, offset: number, data: Buffer) => void): this; + // 当发生 'FSTAT' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和文件句柄作为参数。可能在获取文件状态信息时触发此事件。 on(event: 'FSTAT', listener: (reqId: number, handle: Handle) => void): this; + // 当发生 'FSETSTAT' 事件时调用对应的监听器函数。监听器函数接收请求 ID、文件句柄和属性对象作为参数。可能在设置文件状态信息时触发此事件。 on(event: 'FSETSTAT', listener: (reqId: number, handle: Handle, attrs: Attributes) => void): this; + // 当发生 'CLOSE' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和文件句柄作为参数。可能在关闭文件时触发此事件。 on(event: 'CLOSE', listener: (reqId: number, handle: Handle) => void): this; + // 当发生 'OPENDIR' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和目录路径作为参数。可能在打开目录时触发此事件。 on(event: 'OPENDIR', listener: (reqId: number, path: string) => void): this; + // 当发生 'READDIR' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和目录句柄作为参数。可能在读取目录内容时触发此事件。 on(event: 'READDIR', listener: (reqId: number, handle: Handle) => void): this; + // 当发生 'LSTAT' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和路径作为参数。可能在获取符号链接的状态信息时触发此事件。 on(event: 'LSTAT', listener: (reqId: number, path: string) => void): this; + // 当发生 'STAT' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和路径作为参数。可能在获取文件或目录的状态信息时触发此事件。 on(event: 'STAT', listener: (reqId: number, path: string) => void): this; + // 当发生 'REMOVE' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和路径作为参数。可能在删除文件或目录时触发此事件。 on(event: 'REMOVE', listener: (reqId: number, path: string) => void): this; + // 当发生 'RMDIR' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和路径作为参数。可能在删除目录时触发此事件。 on(event: 'RMDIR', listener: (reqId: number, path: string) => void): this; + // 当发生 'REALPATH' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和路径作为参数。可能在获取真实路径时触发此事件。 on(event: 'REALPATH', listener: (reqId: number, path: string) => void): this; + // 当发生 'READLINK' 事件时调用对应的监听器函数。监听器函数接收请求 ID 和路径作为参数。可能在读取符号链接的目标路径时触发此事件。 on(event: 'READLINK', listener: (reqId: number, path: string) => void): this; + // 当发生 'SETSTAT' 事件时调用对应的监听器函数。监听器函数接收请求 ID、路径和属性对象作为参数。可能在设置文件或目录的状态信息时触发此事件。 on(event: 'SETSTAT', listener: (reqId: number, path: string, attrs: Attributes) => void): this; + // 当发生 'MKDIR' 事件时调用对应的监听器函数。监听器函数接收请求 ID、路径和属性对象作为参数。可能在创建目录时触发此事件。 on(event: 'MKDIR', listener: (reqId: number, path: string, attrs: Attributes) => void): this; + // 当发生 'RENAME' 事件时调用对应的监听器函数。监听器函数接收请求 ID、旧路径和新路径作为参数。可能在重命名文件或目录时触发此事件。 on(event: 'RENAME', listener: (reqId: number, oldPath: string, newPath: string) => void): this; + // 当发生 'SYMLINK' 事件时调用对应的监听器函数。监听器函数接收请求 ID、符号链接路径和目标路径作为参数。可能在创建符号链接时触发此事件。 on(event: 'SYMLINK', listener: (reqId: number, linkPath: string, targetPath: string) => void): this; /* GENERAL */ /** Closes the underlying Channel object, thus ending this SFTP connection */ + // **关闭底层Channel对象，从而结束此SFTP连接。 destroy(): void; /** Alias for {@link destroy} */ + // **别名**：用于销毁SFTP连接。 end(): void; /** **Internal**: Sends the INIT request (with client version). Becomes a NOOP after first use */ + // **内部**：发送INIT请求（带有客户端版本）。第一次使用后变为NOOP。 _init(): void; /** **Internal**: Used to deliver data into the SFTP object */ + // **内部**：用于将数据传递给SFTP对象。 push(data: Buffer): void; /** Emitted when the SFTP stream/channel has ended */ + // **内部**：当SFTP流/通道结束时触发。 on(event: 'end', listener: () => void): this; } /** Contains various open file flags */ + // 定义一个命名空间 OPEN_MODE，可能用于表示文件打开模式的常量集合。 export namespace OPEN_MODE { + // 以只读模式打开文件。 export const READ = 0x00000001; + // 以只写模式打开文件。 export const WRITE = 0x00000002; + // 以追加模式打开文件。 export const APPEND = 0x00000004; + // 创建新文件，如果文件不存在。 export const CREAT = 0x00000008; + // 如果文件存在，截断文件长度为零。 export const TRUNC = 0x00000010; + // 如果文件存在，打开操作失败。 export const EXCL = 0x00000020; } /** Contains various status codes (for use especially with {@link SFTP.status}) */ +// 定义一个命名空间 STATUS_CODE，可能用于表示各种状态码的常量集合。 export namespace STATUS_CODE { + // 操作成功。 export const OK = 0; + // 已到达文件末尾。 export const EOF = 1; + // 没有找到指定的文件。 export const NO_SUCH_FILE = 2; + // 权限被拒绝。 export const PERMISSION_DENIED = 3; + // 操作失败，一般错误。 export const FAILURE = 4; + // 接收到错误的消息格式。 export const BAD_MESSAGE = 5; + // 没有建立连接。 export const NO_CONNECTION = 6; + // 连接丢失。 export const CONNECTION_LOST = 7; + // 不支持的操作。 export const OP_UNSUPPORTED = 8; } /** Converts a flag mask (e.g. a number containing `OPEN_MODE` values) to a string */ + // 将标志掩码（例如包含 `OPEN_MODE` 值的数字）转换为字符串。 export function flagsToString(flagsMask: number): string | null; /** Converts string flags (e.g. `r+`, `a+`, etc) to the appropriate `OPEN_MODE` mask */ + // 将字符串标志（例如 `r+`、`a+` 等）转换为相应的 `OPEN_MODE` 掩码。 export function stringToFlags(flagsStr: string): number | null; } +// 声明一个名为 'ssh2/lib/agent' 的模块。 +// 这里可以包含对这个模块的具体类型声明、接口定义、函数声明等内容。 +// 通常用于为一个外部模块提供类型信息，以便在 TypeScript 项目中正确使用该模块并进行类型检查。 declare module 'ssh2/lib/agent' { + // 从 'ssh2' 模块中导入特定的类型和函数。 + // Client 可能是用于建立 SSH 连接的客户端对象。 + // ConnectConfig 可能是用于配置 SSH 连接的对象类型。 import { Client, ConnectConfig } from 'ssh2'; + // ParsedKey 可能是经过解析的 SSH 密钥对象，用于与 SSH 协议的密钥解析相关的操作。 import { ParsedKey } from 'ssh2/lib/protocol/keyParser'; + // 导入 Node.js 的流模块，用于处理数据的流式传输。 import * as stream from 'stream'; // Prevent the `Client` import from being organized away, as we use it below in a TSDoc comment + // 定义一个类型别名 _Client。 + // 这个类型是由 'ssh2' 模块中的 Client 类型和 ConnectConfig 类型进行交叉类型（Intersection Types）得到的。 + // 意味着这个类型同时具有 Client 类型和 ConnectConfig 类型的所有属性和方法，可能用于表示一个既具有客户端功能又具有连接配置属性的对象。 type _Client = Client & ConnectConfig; // Export AgentProtocol, BaseAgent, createAgent, CygwinAgent, OpenSSHAgent, PageantAgent + // 定义一个接口，表示签名选项。 export interface SignOptions { /** The explicitly desired hash algorithm, e.g. `sha256` or `sha512` for RSA keys */ + // 明确指定所需的哈希算法，例如对于 RSA 密钥可以是`sha256`或`sha512`。 hash: string; } - + + // 定义一个名为 AgentProtocol 的类，它继承自 Node.js 的流模块中的 Duplex 类。 export class AgentProtocol extends stream.Duplex { - + // 构造函数，接收一个布尔值参数 isClient，表示是否为客户端。 constructor(isClient: boolean); /** **Server-only**: Reply to the given `request` with a failure response */ + // 仅在服务端使用：用失败响应回复给定的请求。 failureReply(request: any): void; /** **Client-only**: Request a list of public keys from the agent */ + // 仅在客户端使用：从代理请求公钥列表。 getIdentities(callback: (err: Error | undefined, keys: Buffer[]) => void): void; /** **Server--only**: Respond to an `identities` event's `request` */ + // 仅在服务端使用：响应 `identities` 事件的请求。 getIdentitiesReply(request: any, keys: Buffer[]): void; /** **Client-only**: Request that the agent signs the given data */ + // 仅在客户端使用：请求代理对给定的数据进行签名。 sign(pubKey: Buffer | string | ParsedKey, data: Buffer, options: SignOptions, callback: (err: Error | undefined, signature: Buffer) => void): void; /** **Server-only**: Respond to an `sign` event's `request` */ + // 仅在服务端使用：响应 `sign` 事件的请求。 signReply(request: any, signature: Buffer): void; /** @@ -1147,6 +1637,7 @@ declare module 'ssh2/lib/agent' { * Emitted when the client requests a list of public keys stored in the agent. * Use {@link failureReply} or {@link getIdentitiesReply} to reply appropriately. */ + // 仅在服务端使用：当客户端请求存储在代理中的公钥列表时触发此事件。可以使用{@link failureReply}或{@link getIdentitiesReply}进行适当的回复。 on(event: 'identities', listener: (request: any) => void): this; /** @@ -1154,18 +1645,23 @@ declare module 'ssh2/lib/agent' { * Emitted when the client requests data to be signed. * Use {@link failureReply} or {@link signReply} to reply appropriately. */ + // 仅在客户端使用：当客户端请求对数据进行签名时触发此事件。可以使用{@link failureReply}或{@link signReply}进行适当的回复。 on(event: 'sign', listener: (request: any, pubKey: Buffer | string | ParsedKey, data: Buffer, options: SignOptions) => void): this; - + // 通用的事件监听器方法，可以监听任何字符串类型的事件，并接收任意参数的回调函数。 on(event: string, listener: (...args: any[]) => void): this; } /** See [documentation](https://github.com/mscdex/ssh2/tree/master#baseagent) of the used version */ + // 定义一个抽象类 BaseAgent。 export abstract class BaseAgent { - + // 抽象方法，用于获取身份信息。 + // 这个方法接收一个回调函数作为参数，回调函数接收可能的错误对象和一个 Buffer 数组，数组中可能包含身份信息的表示。 getIdentities(callback: (err: Error | undefined, keys: Buffer[]) => void): void; - + // 抽象方法，用于对数据进行签名。 + // 接收公钥、数据、签名选项以及回调函数作为参数。回调函数接收可能的错误对象和签名后的 Buffer。 sign(pubKey: Buffer | string | ParsedKey, data: Buffer, options: SignOptions, callback: (err: Error | undefined, signature: Buffer) => void): void; - + // 可选的抽象方法，用于获取流。 + // 这个方法是可选的，接收一个回调函数作为参数，回调函数接收可能的错误对象和一个双工流对象。 getStream?(callback: (err: Error | undefined, stream: stream.Duplex) => void): void; } @@ -1176,39 +1672,67 @@ declare module 'ssh2/lib/agent' { * - On Windows with a non-pipe it creates a {@link CygwinAgent} * - In all other cases it creates a {@link OpenSSHAgent} */ + // 定义一个函数 createAgent，用于创建一个新的代理实例。 export function createAgent(agentValue: string): BaseAgent; /** Communicates with a UNIX domain socket in a Cygwin environment */ + // 定义一个类 CygwinAgent，它继承自 BaseAgent。 export class CygwinAgent extends BaseAgent { + // 构造函数，接收一个字符串参数 socketPath，表示套接字路径。 constructor(socketPath: string); } /** Communicates with an OpenSSH listening on a UNIX domain socket or Windows named pipe */ + // 定义一个类 OpenSSHAgent，它继承自 BaseAgent。 export class OpenSSHAgent extends BaseAgent { + // 构造函数，接收一个字符串参数 socketPath，表示套接字路径。 constructor(socketPath: string); } /** Communicates with a running Pageant agent process on Windows */ + // 定义一个类 PageantAgent，它继承自 BaseAgent。 export class PageantAgent extends BaseAgent { } } +// 定义一个名为'ssh2/lib/protocol/keyParser'的模块。 declare module 'ssh2/lib/protocol/keyParser' { + // 定义一个类型别名 InputData。 type InputData = string | Buffer | NodeJS.ArrayBufferView; + // 定义一个接口 ParsedKey。 + // 这个类型可以是字符串、Buffer 对象或者 Node.js 的 ArrayBufferView（如 TypedArray 或 DataView）。 + // 通常用于表示可以作为输入数据的不同类型。 export interface ParsedKey { /** Key type, such as `ssh-rsa`, `ecdsa-sha2-nistp256`, ... */ + // 键类型，例如`ssh-rsa`、`ecdsa-sha2-nistp256`等。 type: string; /** Key comment. Can be an empty string (e.g. old OpenSSH format) */ + // 键注释。可以是空字符串（例如旧的 OpenSSH 格式）。 comment: string; + // 对数据进行签名的方法。 + // 参数 data 是要签名的数据，可以是字符串、Buffer 或 NodeJS.ArrayBufferView。algo 是可选的签名算法参数。返回值可以是签名后的 Buffer 或者 Error 对象表示签名失败。 sign(data: InputData, algo?: string): Buffer | Error; + // 验证数据和签名的方法。 + // 参数 data 是要验证的数据，signature 是签名数据，algo 是可选的验证算法参数。返回值可以是布尔值表示验证成功与否，或者 Error 对象表示验证失败。 verify(data: InputData, signature: InputData, algo?: string): boolean | Error; + // 判断是否为私钥的方法。 + // 返回一个布尔值，表示当前对象是否为私钥。 isPrivateKey(): boolean; + // 获取私钥的 PEM 格式字符串的方法。 + // 返回私钥的 PEM 格式字符串。 getPrivatePEM(): string; + // 获取公钥的 PEM 格式字符串的方法。 + // 返回公钥的 PEM 格式字符串。 getPublicPEM(): string; + // 获取公钥的 SSH 格式 Buffer 的方法。 + // 返回公钥的 SSH 格式的 Buffer。 getPublicSSH(): Buffer; + // 判断当前对象与另一个 ParsedKey 对象是否相等的方法。 + // 参数 parsedKey 是另一个已解析的密钥对象。返回一个布尔值表示两个密钥是否相等。 equals(parsedKey: ParsedKey): boolean; } + // 定义一个函数 isParsedKey，用于判断一个对象是否为 ParsedKey 类型。 export function isParsedKey(key: any): key is ParsedKey; /** * Supported key types (differs per key format): @@ -1228,5 +1752,6 @@ declare module 'ssh2/lib/protocol/keyParser' { * * And yes, this function can **return** an Error **and** throw one! */ + // 定义一个函数 parseKey，用于解析密钥数据。 export function parseKey(keyData: ParsedKey | Buffer | string, passphrase?: string | Buffer): ParsedKey | Error; }