@linxin666/dsh-ssh 0.1.13 → 0.1.15

package/lib/types/client/panel/TunnelsTab.d.ts

@@ -1,4 +1,14 @@
 import type { SshApi } from '../api.ts';
+import type { TunnelInfo } from '../../protocol.ts';
+/** Live-tunnel polling interval while the tab is mounted (ms). */
+export declare const TUNNEL_POLL_MS = 5000;
+/**
+ * Return `next` only when the tunnel list changed in a user-visible way
+ * (identity, ordering or any renderable field), else `null` so a poll tick
+ * with no real change keeps the previous reference and React skips the
+ * re-render. `prev === null` (first load) always accepts the list.
+ */
+export declare function diffTunnels(prev: TunnelInfo[] | null, next: TunnelInfo[]): TunnelInfo[] | null;
 /** Tunnels tab props. */
 export interface TunnelsTabProps {
     api: SshApi;

package/lib/types/engine/cluster.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cluster execution: run one command concurrently across many hosts (all, or
+ * filtered by explicit aliases / environment / tags with ALL semantics).
+ */
+import type { ClusterResult } from '../protocol.ts';
+import { type PoolEngine } from './connection-pool.ts';
+interface ClusterOptions {
+    command: string;
+    aliases?: string[];
+    environment?: string;
+    tags?: string[];
+    timeoutMs?: number;
+    maxWorkers?: number;
+}
+/** Run one command against many hosts concurrently. */
+export declare function cluster(engine: PoolEngine, options: ClusterOptions): Promise<ClusterResult[]>;
+export {};

package/lib/types/engine/connection-pool.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Connection pool: per-alias persistent ssh2 connections with multi-hop jump
+ * support, the acquire / dispose / sweep lifecycle, and the pooled exec path.
+ */
+import { Client, type ConnectConfig } from 'ssh2';
+import type { ExecResult, SshHostEntry } from '../protocol.ts';
+import { type HostStore } from '../store.ts';
+/** Default engine knobs. */
+export interface EngineOptions {
+    /** Connections idle longer than this are closed (ms). */
+    idleTimeoutMs?: number;
+    /** SSH handshake timeout (ms). */
+    connectTimeoutMs?: number;
+    /** Keepalive ping interval (ms). */
+    keepaliveIntervalMs?: number;
+    /** Cap on captured stdout/stderr bytes per exec (ms). */
+    maxOutputBytes?: number;
+    /** Default exec timeout (ms). */
+    defaultExecTimeoutMs?: number;
+    /** Default cluster concurrency. */
+    defaultMaxWorkers?: number;
+    /** SFTP concurrent channel count for transfers. */
+    sftpConcurrency?: number;
+}
+/** Default engine knobs (applied when an option is omitted). */
+export declare const DEFAULTS: Required<EngineOptions>;
+/** One pooled connection record. */
+export interface PoolRecord {
+    client: Client;
+    /** Jump-chain clients kept alive under the target. */
+    hops: Client[];
+    idleAt: number;
+    /** Pinned connections (tunnels) are never swept. */
+    pinned: boolean;
+    broken: boolean;
+    /** Operations currently running on this connection (sweep guard). */
+    inFlight: number;
+}
+/**
+ * The slice of the engine the pool and exec paths need. The host class
+ * (engine.ts facade) satisfies this structurally.
+ */
+export interface PoolEngine {
+    readonly store: HostStore;
+    readonly opts: Required<EngineOptions>;
+    readonly pool: Map<string, PoolRecord>;
+    readonly acquireQueue: Map<string, Promise<PoolRecord>>;
+}
+/** Build the ssh2 connect config for one entry (key read from disk). */
+export declare function buildConnectConfig(entry: SshHostEntry, sock?: ConnectConfig['sock']): ConnectConfig;
+/** Cap captured output at the configured byte budget (marks truncation). */
+export declare function appendOutput(target: {
+    text: string;
+    truncated: boolean;
+}, chunk: Buffer, maxBytes: number): void;
+/**
+ * Build one full jump chain for an entry: hop clients connected through in
+ * order, each forwarding a stream to the next destination, ending with the
+ * target client. Shared by the pool and standalone shell sessions.
+ */
+export declare function connectChain(engine: PoolEngine, entry: SshHostEntry): Promise<{
+    client: Client;
+    hops: Client[];
+}>;
+/** Connect (or reuse) the pooled chain for one alias; pins nothing. */
+export declare function acquire(engine: PoolEngine, alias: string): Promise<PoolRecord>;
+/**
+ * Tear down one alias's record. When `record` is given and no longer the
+ * pooled record for the alias (a concurrent acquire replaced it), nothing
+ * is torn down — the connection belongs to someone else now.
+ */
+export declare function disposeRecord(engine: PoolEngine, alias: string, record?: PoolRecord): void;
+/** Close connections idle beyond the threshold (skips pinned and in-flight). */
+export declare function sweepPool(engine: PoolEngine): void;
+/**
+ * Run `fn` with a live client for `alias`, reconnecting (up to the
+ * attempt budget) when the connection broke mid-flight.
+ */
+export declare function withClient<T>(engine: PoolEngine, alias: string, fn: (client: Client) => Promise<T>, attempts?: number): Promise<T>;
+/** Run one command on `alias` (reusing the pooled connection). */
+export declare function execCommand(engine: PoolEngine, alias: string, command: string, timeoutMs?: number): Promise<ExecResult>;

package/lib/types/engine/pty.d.ts

@@ -0,0 +1,32 @@
+/**
+ * PTY shell sessions for the web terminal: a standalone (non-pooled)
+ * ssh2 connection with a long-lived shell channel, resize, and pausable
+ * output delivery.
+ */
+import { type PoolEngine } from './connection-pool.ts';
+/** A live PTY shell session. */
+export interface ShellSession {
+    /** Assign to receive remote output. */
+    onData?: (data: Buffer) => void;
+    /** Assign to be notified when the channel closes. */
+    onExit?: (code: number | null, error?: string) => void;
+    /** Write raw input to the shell. */
+    send(data: string): void;
+    /** Resize the remote PTY. */
+    resize(cols: number, rows: number): void;
+    /** Close the session and its channel. */
+    close(): void;
+    /** Pause remote output delivery (transport backpressure). */
+    pause(): void;
+    /** Resume remote output delivery. */
+    resume(): void;
+}
+/**
+ * Open a PTY shell session for the web terminal (standalone connection).
+ * The shell is a long-lived exclusive stream: it uses its own connection so
+ * closing it can never tear down a pooled exec/tunnel sharing the alias.
+ */
+export declare function openShell(engine: PoolEngine, alias: string, size: {
+    cols: number;
+    rows: number;
+}): Promise<ShellSession>;

package/lib/types/engine/sftp.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SFTP transfers: upload (file or recursive tree), single-file download, and
+ * remote directory listing. Every channel is opened once per operation and
+ * released exactly once so sshd's MaxSessions cap is never exhausted.
+ */
+import type { RemoteDirEntry, TransferProgress } from '../protocol.ts';
+import { type PoolEngine } from './connection-pool.ts';
+/** Walk a local directory, collecting relative paths of every file. */
+export declare function walkLocalDir(root: string): string[];
+/** Upload one local file (or directory tree) to a remote path. */
+export declare function upload(engine: PoolEngine, alias: string, localPath: string, remotePath: string, recursive: boolean, onProgress?: (progress: TransferProgress) => void): Promise<{
+    bytes: number;
+    files: number;
+}>;
+/** Download one remote file to a local path. */
+export declare function download(engine: PoolEngine, alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
+    bytes: number;
+}>;
+/** List a remote directory (file browser). */
+export declare function ls(engine: PoolEngine, alias: string, path: string): Promise<RemoteDirEntry[]>;

package/lib/types/engine/tunnel.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Local port-forward tunnels: one loopback-only listener per tunnel, pinned
+ * to a pooled connection so an idle sweep never closes it, with per-tunnel
+ * socket tracking and stop (single / alias-scoped / all).
+ */
+import { type Server as NetServer, type Socket } from 'node:net';
+import type { TunnelInfo } from '../protocol.ts';
+import { type PoolEngine } from './connection-pool.ts';
+/** One active tunnel record (server + pinned client + live sockets). */
+export interface TunnelRecord {
+    info: TunnelInfo;
+    server: NetServer;
+    alias: string;
+    sockets: Set<Socket>;
+}
+/** The engine slice the tunnel module needs (adds the tunnel registry). */
+export interface TunnelEngine extends PoolEngine {
+    readonly tunnels: Map<string, TunnelRecord>;
+    nextTunnelId: number;
+}
+/** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
+export declare function startTunnel(engine: TunnelEngine, alias: string, options: {
+    remotePort: number;
+    remoteHost?: string;
+    localPort?: number;
+}): Promise<TunnelInfo>;
+/** All active tunnels. */
+export declare function listTunnels(engine: TunnelEngine): TunnelInfo[];
+/** Stop one tunnel (closes the listener, live sockets, and the pinned connection). */
+export declare function stopTunnel(engine: TunnelEngine, id: string): boolean;
+/** Stop all tunnels (optionally for one alias). */
+export declare function stopAllTunnels(engine: TunnelEngine, alias?: string): number;

package/lib/types/engine.d.ts

@@ -1,56 +1,31 @@
 /**
- * The SSH engine: a per-alias persistent connection pool (ssh2) with
+ * The SSH engine facade: a per-alias persistent connection pool (ssh2) with
  * multi-hop jump support, command execution, PTY shells, SFTP transfers,
- * local port-forward tunnels and cluster execution — the DSH counterpart of
- * ssh-skill's daemon + scripts, living entirely in the host process.
+ * local port-forward tunnels and cluster execution. The heavy lifting lives
+ * in the engine/ modules (connection-pool, pty, sftp, tunnel, cluster); this
+ * class composes them behind one new SshEngine instance per plugin apply.
  */
 import type { ClusterResult, ExecResult, SshHostSummary, TestResult, TransferProgress, TunnelInfo } from './protocol.ts';
-import { type HostStore } from './store.ts';
-/** Default engine knobs. */
-export interface EngineOptions {
-    /** Connections idle longer than this are closed (ms). */
-    idleTimeoutMs?: number;
-    /** SSH handshake timeout (ms). */
-    connectTimeoutMs?: number;
-    /** Keepalive ping interval (ms). */
-    keepaliveIntervalMs?: number;
-    /** Cap on captured stdout/stderr bytes per exec (ms). */
-    maxOutputBytes?: number;
-    /** Default exec timeout (ms). */
-    defaultExecTimeoutMs?: number;
-    /** Default cluster concurrency. */
-    defaultMaxWorkers?: number;
-    /** SFTP concurrent channel count for transfers. */
-    sftpConcurrency?: number;
-}
-/** A live PTY shell session. */
-export interface ShellSession {
-    /** Assign to receive remote output. */
-    onData?: (data: Buffer) => void;
-    /** Assign to be notified when the channel closes. */
-    onExit?: (code: number | null, error?: string) => void;
-    /** Write raw input to the shell. */
-    send(data: string): void;
-    /** Resize the remote PTY. */
-    resize(cols: number, rows: number): void;
-    /** Close the session and its channel. */
-    close(): void;
-    /** Pause remote output delivery (transport backpressure). */
-    pause(): void;
-    /** Resume remote output delivery. */
-    resume(): void;
-}
+import type { HostStore } from './store.ts';
+import { type EngineOptions, type PoolRecord } from './engine/connection-pool.ts';
+import { type ShellSession } from './engine/pty.ts';
+import { type TunnelRecord } from './engine/tunnel.ts';
+export type { EngineOptions } from './engine/connection-pool.ts';
+export type { ShellSession } from './engine/pty.ts';
+export type { PoolRecord } from './engine/connection-pool.ts';
+export type { TunnelRecord } from './engine/tunnel.ts';
 /**
  * The engine. Owns the pool, tunnels, and all operations. One instance per
  * plugin apply; dispose() closes every connection.
  */
 export declare class SshEngine {
-    private readonly store;
-    private readonly opts;
-    private readonly pool;
-    private readonly tunnels;
+    readonly store: HostStore;
+    readonly opts: Required<EngineOptions>;
+    readonly pool: Map<string, PoolRecord>;
+    readonly acquireQueue: Map<string, Promise<PoolRecord>>;
+    readonly tunnels: Map<string, TunnelRecord>;
+    nextTunnelId: number;
     private sweepTimer;
-    private nextTunnelId;
     /**
      * @param store - the host config store.
      * @param options - engine knobs (defaults applied).
@@ -60,30 +35,6 @@ export declare class SshEngine {
     list(query?: string): SshHostSummary[];
     /** One host summary by alias. */
     find(alias: string): SshHostSummary | undefined;
-    /**
-     * Run `fn` with a live client for `alias`, reconnecting (up to the
-     * attempt budget) when the connection broke mid-flight.
-     */
-    private withClient;
-    /**
-     * Build one full jump chain for an entry: hop clients connected through in
-     * order, each forwarding a stream to the next destination, ending with the
-     * target client. Shared by the pool and standalone shell sessions.
-     */
-    private connectChain;
-    /** In-flight acquire promises, deduped per alias (concurrent first use). */
-    private readonly acquireQueue;
-    /** Connect (or reuse) the pooled chain for one alias; pins nothing. */
-    private acquire;
-    private doAcquire;
-    /**
-     * Tear down one alias's record. When `record` is given and no longer the
-     * pooled record for the alias (a concurrent acquire replaced it), nothing
-     * is torn down — the connection belongs to someone else now.
-     */
-    private disposeRecord;
-    /** Close connections idle beyond the threshold (skips pinned and in-flight). */
-    private sweep;
     /** Run one command on `alias` (reusing the pooled connection). */
     exec(alias: string, command: string, timeoutMs?: number): Promise<ExecResult>;
     /** Run one command against many hosts concurrently. */
@@ -111,18 +62,6 @@ export declare class SshEngine {
     }>;
     /** List a remote directory (file browser). */
     ls(alias: string, path: string): Promise<import('./protocol.ts').RemoteDirEntry[]>;
-    /**
-     * Open one SFTP channel, run the operation, and release the channel exactly
-     * once when the operation settles (success or error). ssh2 keeps each
-     * subsystem channel open until end(); without this, every transfer leaks a
-     * channel until sshd's MaxSessions cap makes all later opens fail.
-     */
-    private withSftp;
-    private sftp;
-    /** Create a remote directory chain (stat-then-mkdir per segment). */
-    private ensureRemoteDir;
-    private fastPut;
-    private fastGet;
     /** Start a local port-forward tunnel (listens on 127.0.0.1 only). */
     startTunnel(alias: string, options: {
         remotePort: number;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@linxin666/dsh-ssh",
   "description": "Remote SSH operations for the dsh web GUI: host config store (~/.dsh/dsh-ssh.json, import from ~/.ssh/config), a persistent ssh2 connection pool with jump-host support, exec / PTY web terminal / SFTP transfer / local port-forward tunnels / cluster execution, plus agent tools (ssh_list, ssh_exec, ssh_upload, ssh_download, ssh_tunnel, ssh_cluster). Hot-pluggable — mounted via ~/.dsh/cordis.patch.yml + a profile node_modules symlink, no dsh source changes.",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "type": "module",
   "engines": {
     "node": "^22.19.0 || >=24.0.0"

package/src/client/panel/TerminalTab.tsx

@@ -6,7 +6,7 @@
  * once per page load (module-level guard).
  */
 import { useEffect, useRef, useState } from 'react'
-import { Terminal } from '@xterm/xterm'
+import { Terminal, type IDisposable } from '@xterm/xterm'
 import { FitAddon } from '@xterm/addon-fit'
 import type { SshApi, TerminalConnection } from '../api.ts'
 import type { SshHostSummary } from '../../protocol.ts'
@@ -53,6 +53,7 @@ export function TerminalTab({ api, presetAlias, requestId }: TerminalTabProps) {
   const termRef = useRef<Terminal | null>(null)
   const fitRef = useRef<FitAddon | null>(null)
   const connRef = useRef<TerminalConnection | null>(null)
+  const dataSubRef = useRef<IDisposable | null>(null)
 
   useEffect(() => { ensureXtermCss() }, [])
 
@@ -84,6 +85,11 @@ export function TerminalTab({ api, presetAlias, requestId }: TerminalTabProps) {
       connection.onExit = undefined
       connection.close()
     }
+    // Release the xterm input subscription explicitly and dispose the
+    // terminal so no listener (or the terminal Renderer) survives a
+    // disconnect or the tab unmounting.
+    dataSubRef.current?.dispose()
+    dataSubRef.current = null
     termRef.current?.dispose()
     termRef.current = null
     fitRef.current = null
@@ -128,13 +134,14 @@ export function TerminalTab({ api, presetAlias, requestId }: TerminalTabProps) {
     fitRef.current = fit
     connRef.current = connection
     let settled = false
-    const dataSub = term.onData(data => { connection.send(data) })
+    dataSubRef.current = term.onData(data => { connection.send(data) })
     connection.onReady = () => { setStatus({ kind: 'connected', alias: target }) }
     connection.onOutput = data => { term.write(data) }
     connection.onExit = (code, error) => {
       if (settled) return
       settled = true
-      dataSub.dispose()
+      dataSubRef.current?.dispose()
+      dataSubRef.current = null
       term.options.disableStdin = true
       connRef.current = null
       // Keep the last output visible; input is now disabled.

package/src/client/panel/TunnelsTab.tsx

@@ -9,6 +9,31 @@ import type { SshHostSummary, TunnelInfo } from '../../protocol.ts'
 import { errorMessage, tt } from './helpers.ts'
 import css from './panel.module.css'
 
+/** Live-tunnel polling interval while the tab is mounted (ms). */
+export const TUNNEL_POLL_MS = 5000
+
+/**
+ * Return `next` only when the tunnel list changed in a user-visible way
+ * (identity, ordering or any renderable field), else `null` so a poll tick
+ * with no real change keeps the previous reference and React skips the
+ * re-render. `prev === null` (first load) always accepts the list.
+ */
+export function diffTunnels(prev: TunnelInfo[] | null, next: TunnelInfo[]): TunnelInfo[] | null {
+  if (prev === null) return next
+  if (prev.length !== next.length) return next
+  for (let index = 0; index < prev.length; index += 1) {
+    const a = prev[index]
+    const b = next[index]
+    if (a.id !== b.id || a.alias !== b.alias || a.state !== b.state
+      || a.localPort !== b.localPort || a.remoteHost !== b.remoteHost
+      || a.remotePort !== b.remotePort || a.startedAt !== b.startedAt
+      || a.error !== b.error) {
+      return next
+    }
+  }
+  return null
+}
+
 /** Tunnels tab props. */
 export interface TunnelsTabProps {
   api: SshApi
@@ -40,8 +65,10 @@ export function TunnelsTab({ api }: TunnelsTabProps) {
     return () => { disposed = true }
   }, [api])
 
-  // Live list with a 5s heartbeat while mounted. Every load carries a
-  // sequence number so stale responses never overwrite newer state.
+  // Live list with a TUNNEL_POLL_MS heartbeat while mounted. Every load
+  // carries a sequence number so stale responses never overwrite newer
+  // state, and the list is diff-set so an unchanged poll tick keeps the
+  // previous state reference (no wasted re-render).
   const seqRef = useRef(0)
   useEffect(() => {
     const load = async (): Promise<void> => {
@@ -49,7 +76,7 @@ export function TunnelsTab({ api }: TunnelsTabProps) {
       try {
         const list = await api.listTunnels()
         if (seq !== seqRef.current) return
-        setTunnels(list)
+        setTunnels(prev => diffTunnels(prev, list) ?? prev)
         setError(null)
       } catch (cause) {
         if (seq !== seqRef.current) return
@@ -57,7 +84,7 @@ export function TunnelsTab({ api }: TunnelsTabProps) {
       }
     }
     void load()
-    const timer = setInterval(() => { void load() }, 5000)
+    const timer = setInterval(() => { void load() }, TUNNEL_POLL_MS)
     return () => { clearInterval(timer) }
   }, [api])
 

package/src/engine/cluster.ts

@@ -0,0 +1,51 @@
+/**
+ * Cluster execution: run one command concurrently across many hosts (all, or
+ * filtered by explicit aliases / environment / tags with ALL semantics).
+ */
+
+import type { ClusterResult } from '../protocol.ts'
+import { execCommand, type PoolEngine } from './connection-pool.ts'
+
+interface ClusterOptions {
+  command: string
+  aliases?: string[]
+  environment?: string
+  tags?: string[]
+  timeoutMs?: number
+  maxWorkers?: number
+}
+
+/** Run one command against many hosts concurrently. */
+export async function cluster(engine: PoolEngine, options: ClusterOptions): Promise<ClusterResult[]> {
+  let targets = engine.store.list()
+  if (options.aliases !== undefined && options.aliases.length > 0) {
+    targets = targets.filter(entry => options.aliases!.includes(entry.alias))
+  }
+  if (options.environment !== undefined && options.environment !== '') {
+    targets = targets.filter(entry => entry.environment === options.environment)
+  }
+  if (options.tags !== undefined && options.tags.length > 0) {
+    // ALL semantics (matches the ssh_cluster tool description).
+    targets = targets.filter(entry => options.tags!.every(tag => entry.tags.includes(tag)))
+  }
+  if (targets.length === 0) return []
+  if (options.maxWorkers !== undefined && (!Number.isInteger(options.maxWorkers) || options.maxWorkers < 1)) {
+    throw new Error('maxWorkers must be a positive integer')
+  }
+  const workers = Math.min(engine.opts.defaultMaxWorkers, options.maxWorkers ?? engine.opts.defaultMaxWorkers, targets.length)
+  const results: ClusterResult[] = []
+  const queue = [...targets]
+  const run = async (): Promise<void> => {
+    while (queue.length > 0) {
+      const entry = queue.shift()!
+      try {
+        const result = await execCommand(engine, entry.alias, options.command, options.timeoutMs)
+        results.push({ alias: entry.alias, ok: result.success, exitCode: result.exitCode, timedOut: result.timedOut, stdout: result.stdout, stderr: result.stderr, durationMs: result.durationMs })
+      } catch (error) {
+        results.push({ alias: entry.alias, ok: false, error: error instanceof Error ? error.message : String(error) })
+      }
+    }
+  }
+  await Promise.all(Array.from({ length: workers }, () => run()))
+  return results
+}