@linxin666/dsh-ssh 0.1.14 → 0.1.16

package/src/engine/connection-pool.ts

@@ -0,0 +1,318 @@
+/**
+ * Connection pool: per-alias persistent ssh2 connections with multi-hop jump
+ * support, the acquire / dispose / sweep lifecycle, and the pooled exec path.
+ */
+
+import { existsSync, readFileSync } from 'node:fs'
+import { Client, type ConnectConfig } from 'ssh2'
+import type { ExecResult, SshHostEntry } from '../protocol.ts'
+import { expandHome, 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 const DEFAULTS: Required<EngineOptions> = {
+  idleTimeoutMs: 30 * 60_000,
+  connectTimeoutMs: 15_000,
+  keepaliveIntervalMs: 15_000,
+  maxOutputBytes: 2 * 1024 * 1024,
+  defaultExecTimeoutMs: 60_000,
+  defaultMaxWorkers: 8,
+  sftpConcurrency: 8,
+}
+
+/** 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 function buildConnectConfig(entry: SshHostEntry, sock?: ConnectConfig['sock']): ConnectConfig {
+  const config: ConnectConfig = {
+    host: entry.host,
+    port: entry.port,
+    username: entry.user,
+    readyTimeout: 15_000,
+    keepaliveInterval: 15_000,
+    keepaliveCountMax: 3,
+  }
+  if (sock !== undefined) config.sock = sock
+  if (entry.auth.kind === 'password') {
+    config.password = entry.auth.password
+  } else {
+    const keyPath = entry.auth.keyPath === undefined ? undefined : expandHome(entry.auth.keyPath)
+    if (keyPath === undefined || !existsSync(keyPath)) {
+      throw new Error('private key not found: ' + (entry.auth.keyPath ?? '(unset)'))
+    }
+    config.privateKey = readFileSync(keyPath, 'utf8')
+    if (entry.auth.passphrase !== undefined && entry.auth.passphrase !== '') {
+      config.passphrase = entry.auth.passphrase
+    }
+  }
+  return config
+}
+
+/** Connect one ssh2 client (resolve on ready, reject on error/close). */
+export function connectClient(config: ConnectConfig): Promise<Client> {
+  return new Promise((resolve, reject) => {
+    const client = new Client()
+    let settled = false
+    const fail = (error: unknown): void => {
+      if (settled) return
+      settled = true
+      try { client.destroy() } catch { /* already closed */ }
+      reject(error instanceof Error ? error : new Error(String(error)))
+    }
+    client.once('ready', () => {
+      if (settled) return
+      settled = true
+      resolve(client)
+    })
+    // Keep an error listener attached after the handshake: when TCP connects
+    // but the handshake drops, ssh2 can emit a second 'error' after a single
+    // once-listener is gone, which would surface as an unhandled 'error' event.
+    // The settled guard turns later emissions into a no-op; other callers
+    // (like doAcquire) attach their own error listeners and all fire together.
+    client.on('error', fail)
+    try {
+      client.connect(config)
+    } catch (error) {
+      fail(error)
+    }
+  })
+}
+
+/** Cap captured output at the configured byte budget (marks truncation). */
+export function appendOutput(target: { text: string; truncated: boolean }, chunk: Buffer, maxBytes: number): void {
+  if (target.truncated) return
+  if (target.text.length + chunk.length > maxBytes) {
+    let cut = chunk.toString('utf8').slice(0, maxBytes - target.text.length)
+    // Never split a surrogate pair at the cut boundary.
+    if (/[\uD800-\uDBFF]$/.test(cut)) cut = cut.slice(0, -1)
+    target.text += cut + '…[output truncated]'
+    target.truncated = true
+    return
+  }
+  target.text += chunk.toString('utf8')
+}
+
+/**
+ * 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 async function connectChain(engine: PoolEngine, entry: SshHostEntry): Promise<{ client: Client; hops: Client[] }> {
+  const hops: Client[] = []
+  let sock: ConnectConfig['sock']
+  const chain = entry.proxyJump
+  for (let index = 0; index < chain.length; index += 1) {
+    const hopAlias = chain[index]
+    const hop = engine.store.find(hopAlias)
+    if (hop === undefined) {
+      for (const client of hops) client.end()
+      throw new Error('proxyJump alias \'' + hopAlias + '\' not found — create it first')
+    }
+    const hopClient = await connectClient(buildConnectConfig(hop, sock))
+    hops.push(hopClient)
+    const next = index + 1 < chain.length ? engine.store.find(chain[index + 1]) : undefined
+    const nextHost = next !== undefined ? next.host : entry.host
+    const nextPort = next !== undefined ? next.port : entry.port
+    sock = await new Promise<ConnectConfig['sock']>((resolve, reject) => {
+      hopClient.forwardOut('127.0.0.1', 0, nextHost, nextPort, (error, stream) => {
+        if (error !== undefined) {
+          for (const client of hops) client.end()
+          reject(error)
+        } else {
+          resolve(stream)
+        }
+      })
+    })
+  }
+  let target: Client | undefined
+  try {
+    target = await connectClient(buildConnectConfig(entry, sock))
+    return { client: target, hops }
+  } catch (error) {
+    for (const client of hops) client.end()
+    // connectClient already destroys the failed target on its own failure
+    // path; destroy defensively only when a reference leaked through, and
+    // guard it so a second destroy is never an issue.
+    if (target !== undefined) {
+      try { target.destroy() } catch { /* already destroyed */ }
+    }
+    throw error
+  }
+}
+
+/** Connect (or reuse) the pooled chain for one alias; pins nothing. */
+export async function acquire(engine: PoolEngine, alias: string): Promise<PoolRecord> {
+  const pending = engine.acquireQueue.get(alias)
+  if (pending !== undefined) return pending
+  const task = doAcquire(engine, alias)
+  engine.acquireQueue.set(alias, task)
+  try {
+    return await task
+  } finally {
+    if (engine.acquireQueue.get(alias) === task) engine.acquireQueue.delete(alias)
+  }
+}
+
+async function doAcquire(engine: PoolEngine, alias: string): Promise<PoolRecord> {
+  const entry = engine.store.find(alias)
+  if (entry === undefined) throw new Error('alias \'' + alias + '\' not found — add it first')
+  const { client, hops } = await connectChain(engine, entry)
+  const record: PoolRecord = { client, hops, idleAt: Date.now(), pinned: false, broken: false, inFlight: 0 }
+  client.on('error', () => { record.broken = true })
+  client.on('close', () => { record.broken = true })
+  engine.pool.set(alias, record)
+  return record
+}
+
+/**
+ * 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 function disposeRecord(engine: PoolEngine, alias: string, record?: PoolRecord): void {
+  const current = engine.pool.get(alias)
+  if (record !== undefined && current !== record) return
+  if (current === undefined) return
+  engine.pool.delete(alias)
+  try { current.client.end() } catch { /* already closed */ }
+  for (const hop of current.hops) {
+    try { hop.end() } catch { /* already closed */ }
+  }
+}
+
+/** Close connections idle beyond the threshold (skips pinned and in-flight). */
+export function sweepPool(engine: PoolEngine): void {
+  const cutoff = Date.now() - engine.opts.idleTimeoutMs
+  for (const [alias, record] of engine.pool) {
+    if (!record.pinned && record.inFlight === 0 && record.idleAt < cutoff) {
+      disposeRecord(engine, alias, record)
+    }
+  }
+}
+
+/**
+ * Run `fn` with a live client for `alias`, reconnecting (up to the
+ * attempt budget) when the connection broke mid-flight.
+ */
+export async function withClient<T>(engine: PoolEngine, alias: string, fn: (client: Client) => Promise<T>, attempts = 3): Promise<T> {
+  let lastError: unknown
+  for (let attempt = 1; attempt <= attempts; attempt += 1) {
+    let record = engine.pool.get(alias)
+    if (record === undefined || record.broken) {
+      if (record !== undefined) disposeRecord(engine, alias, record)
+      record = await acquire(engine, alias)
+    }
+    record.idleAt = Date.now()
+    record.inFlight += 1
+    try {
+      const result = await fn(record.client)
+      record.idleAt = Date.now()
+      return result
+    } finally {
+      record.inFlight -= 1
+    }
+  }
+  throw lastError instanceof Error ? lastError : new Error(String(lastError))
+}
+
+/** Run one command on `alias` (reusing the pooled connection). */
+export async function execCommand(engine: PoolEngine, alias: string, command: string, timeoutMs?: number): Promise<ExecResult> {
+  const started = Date.now()
+  const budget = timeoutMs !== undefined && timeoutMs > 0 ? timeoutMs : engine.opts.defaultExecTimeoutMs
+  return withClient(engine, alias, async (client) => {
+    return await new Promise<ExecResult>((resolve, reject) => {
+      client.exec(command, (error, stream) => {
+        if (error !== undefined) {
+          reject(error)
+          return
+        }
+        const stdout = { text: '', truncated: false }
+        const stderr = { text: '', truncated: false }
+        let timedOut = false
+        let settled = false
+        const finish = (): void => {
+          if (settled) return
+          settled = true
+          clearTimeout(timer)
+          resolve({
+            success: false,
+            exitCode: null,
+            timedOut,
+            stdout: stdout.text,
+            stderr: stderr.text,
+            durationMs: Date.now() - started,
+            error: timedOut ? 'command timed out after ' + budget + ' ms' : undefined,
+          })
+        }
+        const timer = setTimeout(() => {
+          timedOut = true
+          try { stream.signal('KILL') } catch { /* channel gone */ }
+          try { stream.close() } catch { /* channel gone */ }
+          // Hard deadline: settle now even if the peer never acks the
+          // channel close (the stream 'close' handler is then a no-op).
+          finish()
+        }, budget)
+        stream.on('data', (chunk: Buffer) => appendOutput(stdout, chunk, engine.opts.maxOutputBytes))
+        stream.stderr.on('data', (chunk: Buffer) => appendOutput(stderr, chunk, engine.opts.maxOutputBytes))
+        stream.on('close', (code: number | null) => {
+          if (settled) return
+          settled = true
+          clearTimeout(timer)
+          resolve({
+            success: code === 0 && !timedOut,
+            exitCode: code,
+            timedOut,
+            stdout: stdout.text,
+            stderr: stderr.text,
+            durationMs: Date.now() - started,
+          })
+        })
+        stream.on('error', (streamError: Error) => {
+          if (settled) return
+          settled = true
+          clearTimeout(timer)
+          reject(streamError)
+        })
+      })
+    })
+  })
+}

package/src/engine/pty.ts

@@ -0,0 +1,74 @@
+/**
+ * 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 { Client } from 'ssh2'
+import { connectChain, 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 async function openShell(engine: PoolEngine, alias: string, size: { cols: number; rows: number }): Promise<ShellSession> {
+  const entry = engine.store.find(alias)
+  if (entry === undefined) throw new Error('alias \'' + alias + '\' not found — add it first')
+  const { client, hops } = await connectChain(engine, entry)
+  return await new Promise<ShellSession>((resolve, reject) => {
+    client.shell({ term: 'xterm-256color', cols: size.cols, rows: size.rows }, (error, stream) => {
+      if (error !== undefined) {
+        try { client.end() } catch { /* closed */ }
+        for (const hop of hops) { try { hop.end() } catch { /* closed */ } }
+        reject(error)
+        return
+      }
+      let tornDown = false
+      const teardown = (): void => {
+        if (tornDown) return
+        tornDown = true
+        try { client.end() } catch { /* closed */ }
+        for (const hop of hops) { try { hop.end() } catch { /* closed */ } }
+      }
+      const session: ShellSession = {
+        send: (data) => { try { stream.write(data) } catch { /* channel gone */ } },
+        resize: (cols, rows) => { try { stream.setWindow(rows, cols, rows, cols) } catch { /* channel gone */ } },
+        close: () => {
+          try { stream.close() } catch { /* channel gone */ }
+          teardown()
+        },
+        pause: () => { try { stream.pause() } catch { /* channel gone */ } },
+        resume: () => { try { stream.resume() } catch { /* channel gone */ } },
+      }
+      stream.on('data', (chunk: Buffer) => { session.onData?.(chunk) })
+      stream.on('close', (code: number | null) => {
+        teardown()
+        session.onExit?.(code)
+      })
+      stream.on('error', (streamError: Error) => {
+        teardown()
+        session.onExit?.(null, streamError instanceof Error ? streamError.message : String(streamError))
+      })
+      resolve(session)
+    })
+  })
+}

package/src/engine/sftp.ts

@@ -0,0 +1,235 @@
+/**
+ * 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 { existsSync, mkdirSync, readdirSync, statSync } from 'node:fs'
+import { dirname, join, relative, resolve as resolvePath } from 'node:path'
+import { Client, type SFTPWrapper } from 'ssh2'
+import type { RemoteDirEntry, TransferProgress } from '../protocol.ts'
+import { withClient, type PoolEngine } from './connection-pool.ts'
+
+/** Walk a local directory, collecting relative paths of every file. */
+export function walkLocalDir(root: string): string[] {
+  const files: string[] = []
+  const visit = (dir: string): void => {
+    for (const name of readdirSync(dir)) {
+      const full = join(dir, name)
+      const stat = statSync(full)
+      if (stat.isDirectory()) visit(full)
+      else if (stat.isFile()) files.push(relative(root, full))
+    }
+  }
+  visit(root)
+  return files
+}
+
+/** Upload one local file (or directory tree) to a remote path. */
+export async function upload(
+  engine: PoolEngine,
+  alias: string,
+  localPath: string,
+  remotePath: string,
+  recursive: boolean,
+  onProgress?: (progress: TransferProgress) => void,
+): Promise<{ bytes: number; files: number }> {
+  // Remote paths must be absolute: the mkdir chain and fastPut must agree
+  // on one resolution (relative paths previously created dirs at the root).
+  if (!remotePath.startsWith('/')) {
+    throw new Error('remotePath must be an absolute path (got \'' + remotePath + '\')')
+  }
+  const local = resolvePath(localPath)
+  if (!existsSync(local)) throw new Error('local path not found: \'' + localPath + '\'')
+  return withClient(engine, alias, (client) => withSftp(client, async (sftp) => {
+    const stat = statSync(local)
+    let files: string[]
+    if (stat.isDirectory()) {
+      if (!recursive) throw new Error('\'' + localPath + '\' is a directory — enable recursive upload')
+      files = walkLocalDir(local)
+      await ensureRemoteDir(sftp, remotePath)
+    } else {
+      files = ['']
+      await ensureRemoteDir(sftp, dirname(remotePath))
+    }
+    let bytes = 0
+    for (const rel of files) {
+      const src = rel === '' ? local : join(local, rel)
+      // Remote paths always use forward slashes; normalize any OS separators.
+      const remoteRel = rel.split(/[\\/]/).join('/')
+      const dst = rel === '' ? remotePath : remotePath.replace(/\/$/, '') + '/' + remoteRel
+      await fastPut(sftp, src, dst, engine.opts.sftpConcurrency, onProgress)
+      bytes += statSync(src).size
+    }
+    return { bytes, files: files.length }
+  }))
+}
+
+/** Download one remote file to a local path. */
+export async function download(
+  engine: PoolEngine,
+  alias: string,
+  remotePath: string,
+  localPath: string,
+  onProgress?: (progress: TransferProgress) => void,
+): Promise<{ bytes: number }> {
+  return withClient(engine, alias, (client) => withSftp(client, async (sftp) => {
+    const stat = await new Promise<{ isDirectory: () => boolean }>((resolve, reject) => {
+      sftp.stat(remotePath, (error, stats) => error !== undefined ? reject(error) : resolve(stats))
+    })
+    if (stat.isDirectory()) {
+      throw new Error('\'' + remotePath + '\' is a directory — directory download is not supported yet (download individual files)')
+    }
+    const local = resolvePath(localPath)
+    if (!existsSync(dirname(local))) mkdirSync(dirname(local), { recursive: true })
+    await fastGet(sftp, remotePath, local, engine.opts.sftpConcurrency, onProgress)
+    return { bytes: statSync(local).size }
+  }))
+}
+
+/** List a remote directory (file browser). */
+export async function ls(engine: PoolEngine, alias: string, path: string): Promise<RemoteDirEntry[]> {
+  return withClient(engine, alias, (client) => withSftp(client, async (sftp) => {
+    return await new Promise((resolve, reject) => {
+      sftp.readdir(path, (error, list) => {
+        if (error !== undefined) {
+          reject(error)
+          return
+        }
+        const entries: RemoteDirEntry[] = list.map(item => ({
+          name: item.filename,
+          type: item.attrs.isDirectory() ? 'dir' : item.attrs.isFile() ? 'file' : 'other',
+          size: item.attrs.size,
+          mtimeMs: item.attrs.mtime * 1000,
+          mode: item.attrs.mode,
+        }))
+        resolve(entries)
+      })
+    })
+  }))
+}
+
+/**
+ * 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.
+ */
+async function withSftp<T>(client: Client, run: (sftp: SFTPWrapper) => Promise<T>): Promise<T> {
+  const sftp = await sftpChannel(client)
+  let ended = false
+  const endOnce = (): void => {
+    if (ended) return
+    ended = true
+    try { sftp.end() } catch { /* channel already closed */ }
+  }
+  // The channel can also close underneath us (peer reset, timeout); the
+  // guard makes the finally below a no-op instead of ending it twice.
+  sftp.once('close', endOnce)
+  try {
+    return await run(sftp)
+  } finally {
+    endOnce()
+  }
+}
+
+function sftpChannel(client: Client): Promise<SFTPWrapper> {
+  return new Promise((resolve, reject) => {
+    client.sftp((error, sftp) => error !== undefined ? reject(error) : resolve(sftp))
+  })
+}
+
+/** Create a remote directory chain (stat-then-mkdir per segment). */
+function ensureRemoteDir(sftp: SFTPWrapper, remote: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const segments = remote.replace(/^\/+/, '').split('/').filter(segment => segment !== '')
+    const walk = (index: number): void => {
+      if (index >= segments.length) {
+        resolve()
+        return
+      }
+      const current = '/' + segments.slice(0, index + 1).join('/')
+      sftp.stat(current, (statError) => {
+        if (statError === undefined) {
+          walk(index + 1)
+          return
+        }
+        // Statting a missing path fails; mkdir it (idempotent because the
+        // stat check runs first — some sftp servers throw on EEXIST).
+        sftp.mkdir(current, (mkdirError) => {
+          if (mkdirError !== undefined) {
+            reject(mkdirError)
+            return
+          }
+          walk(index + 1)
+        })
+      })
+    }
+    walk(0)
+  })
+}
+
+function fastPut(sftp: SFTPWrapper, src: string, dst: string, concurrency: number, onProgress?: (progress: TransferProgress) => void): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let last = 0
+    let lastEmit = 0
+    const started = Date.now()
+    onProgress?.({ phase: 'transferring', file: dst, transferred: 0, total: statSync(src).size, percent: 0 })
+    sftp.fastPut(src, dst, { concurrency, step: (transferred: number, _chunk: number, total: number) => {
+      const now = Date.now()
+      // Throttle: high-speed links fire one callback per chunk; the UI only
+      // needs ~10 frames per second.
+      if (now - lastEmit < 100 && transferred < total) return
+      lastEmit = now
+      const elapsed = (now - started) / 1000
+      onProgress?.({
+        phase: 'transferring',
+        file: dst,
+        transferred,
+        total,
+        percent: total > 0 ? Math.round((transferred / total) * 1000) / 10 : 0,
+        speedBps: elapsed > 0 ? Math.round((transferred - last) / elapsed) : undefined,
+      })
+      last = transferred
+    } }, (error) => {
+      if (error !== undefined) {
+        onProgress?.({ phase: 'error', file: dst, transferred: 0, total: 0, percent: 0, error: String(error) })
+        reject(error)
+      } else {
+        onProgress?.({ phase: 'done', file: dst, transferred: statSync(src).size, total: statSync(src).size, percent: 100 })
+        resolve()
+      }
+    })
+  })
+}
+
+function fastGet(sftp: SFTPWrapper, src: string, dst: string, concurrency: number, onProgress?: (progress: TransferProgress) => void): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let last = 0
+    let lastEmit = 0
+    const started = Date.now()
+    sftp.fastGet(src, dst, { concurrency, step: (transferred: number, _chunk: number, total: number) => {
+      const now = Date.now()
+      if (now - lastEmit < 100 && transferred < total) return
+      lastEmit = now
+      const elapsed = (now - started) / 1000
+      onProgress?.({
+        phase: 'transferring',
+        file: src,
+        transferred,
+        total,
+        percent: total > 0 ? Math.round((transferred / total) * 1000) / 10 : 0,
+        speedBps: elapsed > 0 ? Math.round((transferred - last) / elapsed) : undefined,
+      })
+      last = transferred
+    } }, (error) => {
+      if (error !== undefined) {
+        onProgress?.({ phase: 'error', file: src, transferred: 0, total: 0, percent: 0, error: String(error) })
+        reject(error)
+      } else {
+        onProgress?.({ phase: 'done', file: src, transferred: statSync(dst).size, total: statSync(dst).size, percent: 100 })
+        resolve()
+      }
+    })
+  })
+}