@pyrokine/mcp-ssh 1.0.0

package/dist/session-manager.d.ts

@@ -0,0 +1,193 @@
+/**
+ * SSH Session Manager - 连接池管理
+ *
+ * 功能：
+ * - 连接池复用
+ * - 心跳保持
+ * - 自动重连
+ * - 会话持久化
+ */
+import { Client, ClientChannel, SFTPWrapper } from 'ssh2';
+import { SSHConnectionConfig, SSHSessionInfo, ExecOptions, ExecResult, PersistedSession, PtyOptions, PtySessionInfo, PortForwardInfo } from './types.js';
+interface SSHSession {
+    client: Client;
+    config: SSHConnectionConfig;
+    connectedAt: number;
+    lastUsedAt: number;
+    reconnectAttempts: number;
+    connected: boolean;
+    tcpDispatcher?: TcpConnectionHandler;
+}
+type TcpConnectionHandler = (info: {
+    destIP: string;
+    destPort: number;
+    srcIP: string;
+    srcPort: number;
+}, accept: () => ClientChannel, reject: () => void) => void;
+export declare class SessionManager {
+    private sessions;
+    private ptySessions;
+    private forwardSessions;
+    private ptyIdCounter;
+    private forwardIdCounter;
+    private persistPath;
+    private defaultKeepaliveInterval;
+    private defaultKeepaliveCountMax;
+    private defaultTimeout;
+    private maxReconnectAttempts;
+    private defaultPtyBufferSize;
+    constructor(persistPath?: string);
+    private ensurePersistDir;
+    /**
+     * 生成连接别名
+     */
+    private generateAlias;
+    /**
+     * 建立 SSH 连接
+     */
+    connect(config: SSHConnectionConfig): Promise<string>;
+    /**
+     * 通过跳板机转发连接
+     */
+    private forwardConnection;
+    /**
+     * 检查连接是否存活
+     */
+    private isAlive;
+    /**
+     * 重新连接
+     */
+    reconnect(alias: string): Promise<void>;
+    /**
+     * 断开连接
+     */
+    disconnect(alias: string): boolean;
+    /**
+     * 断开所有连接
+     */
+    disconnectAll(): void;
+    /**
+     * 获取会话
+     */
+    getSession(alias: string): SSHSession;
+    /**
+     * 列出所有会话
+     */
+    listSessions(): SSHSessionInfo[];
+    /**
+     * 转义 shell 参数（使用单引号方式）
+     */
+    private escapeShellArg;
+    /**
+     * 执行命令
+     */
+    exec(alias: string, command: string, options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * 校验用户名（只允许字母、数字、下划线、连字符）
+     */
+    private isValidUsername;
+    /**
+     * 校验环境变量名（只允许字母、数字、下划线，不能以数字开头）
+     */
+    private isValidEnvKey;
+    /**
+     * 以其他用户身份执行命令
+     */
+    execAsUser(alias: string, command: string, targetUser: string, options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * 使用 sudo 执行命令
+     */
+    execSudo(alias: string, command: string, sudoPassword?: string, options?: ExecOptions): Promise<ExecResult>;
+    /**
+     * 获取 SFTP 客户端
+     */
+    getSftp(alias: string): Promise<SFTPWrapper>;
+    /**
+     * 持久化会话信息
+     */
+    private persistSessions;
+    /**
+     * 加载持久化的会话信息（仅用于显示，不自动重连）
+     */
+    loadPersistedSessions(): PersistedSession[];
+    /**
+     * 生成 PTY 会话 ID
+     */
+    private generatePtyId;
+    /**
+     * 启动持久化 PTY 会话
+     */
+    ptyStart(alias: string, command: string, options?: PtyOptions): Promise<string>;
+    /**
+     * 向 PTY 写入数据
+     */
+    ptyWrite(ptyId: string, data: string): boolean;
+    /**
+     * 从终端仿真器获取当前屏幕内容
+     */
+    private getScreenContent;
+    /**
+     * 读取 PTY 输出
+     * @param mode 'screen' 返回当前屏幕内容，'raw' 返回原始 ANSI 流
+     */
+    ptyRead(ptyId: string, options?: {
+        mode?: 'screen' | 'raw';
+        clear?: boolean;
+    }): {
+        data: string;
+        active: boolean;
+        rows: number;
+        cols: number;
+    };
+    /**
+     * 调整 PTY 窗口大小
+     */
+    ptyResize(ptyId: string, rows: number, cols: number): boolean;
+    /**
+     * 关闭 PTY 会话
+     */
+    ptyClose(ptyId: string): boolean;
+    /**
+     * 列出所有 PTY 会话
+     */
+    ptyList(): PtySessionInfo[];
+    /**
+     * 关闭所有 PTY 会话
+     */
+    ptyCloseAll(): number;
+    /**
+     * 生成端口转发 ID
+     */
+    private generateForwardId;
+    /**
+     * 创建本地端口转发
+     * 本地监听 localHost:localPort，转发到远程 remoteHost:remotePort
+     */
+    forwardLocal(alias: string, localPort: number, remoteHost: string, remotePort: number, localHost?: string): Promise<string>;
+    /**
+     * 创建远程端口转发
+     * 远程监听 remoteHost:remotePort，转发到本地 localHost:localPort
+     */
+    forwardRemote(alias: string, remotePort: number, localHost: string, localPort: number, remoteHost?: string): Promise<string>;
+    /**
+     * 确保 SSH session 有共享的 tcp connection dispatcher
+     * 所有 remote forward 共用一个 dispatcher，根据 destIP/destPort 路由
+     * @param alias - session 的 map key
+     */
+    private ensureTcpDispatcher;
+    /**
+     * 移除 SSH session 的 tcp dispatcher（当没有 remote forward 时）
+     * @param alias - session 的 map key
+     */
+    private removeTcpDispatcherIfEmpty;
+    /**
+     * 关闭端口转发
+     */
+    forwardClose(forwardId: string): boolean;
+    /**
+     * 列出所有端口转发
+     */
+    forwardList(): PortForwardInfo[];
+}
+export declare const sessionManager: SessionManager;
+export {};