@tiphareth/dsh-hardssh 0.1.2

package/src/seam-state.ts

@@ -0,0 +1,185 @@
+/**
+ * The shared derived seam state: ONE ledger-derived routing snapshot
+ * (records + normalized anchor index) plus the per-record fs/subprocess
+ * instances, owned by the hardssh core and consumed by BOTH switch rows
+ * (./fs and ./subprocess). Because both seams read the SAME state, they can
+ * never disagree with each other or with the ledger's own index for a given
+ * session cwd — eliminating the split-brain window of the old per-seam
+ * async refresh caches.
+ *
+ * The state re-applies SYNCHRONOUSLY on every ledger commit: ledger
+ * listeners run synchronously AFTER the commit already swapped the
+ * in-memory records, so a synchronous re-apply is always current — no async
+ * refresh pipeline, no stale-snapshot race, no revision-guard interleaving.
+ * The initial file load is awaited before the state is marked ready; until
+ * then routing degrades to local with a one-time warning from the rows.
+ *
+ * Per-record instances are built lazily on first route and kept alive
+ * across refreshes (connections survive); removing a workspace drops its
+ * instances so stale target keys resolve to NOTHING (fail closed), never to
+ * the local backend.
+ *
+ * @module dsh-hardssh/seam-state
+ */
+
+import type { SshWorkspaceRecord } from './protocol.ts'
+import { isPathUnderAnchor, normalizeAnchorPath, type SshWorkspaceLedger } from './ledger.ts'
+import { REMOTE_PREFIX, type WorkspaceWorld } from './switch/switch-fs.ts'
+import type { SshSubprocessRuntime } from './remote/remote-subprocess.ts'
+
+/** Per-record seam instances, built lazily by the owning rows. */
+interface SeamInstances {
+  fs?: WorkspaceWorld
+  subprocess?: SshSubprocessRuntime
+}
+
+/** One anchor-index entry: a normalized anchor plus its lowercased record id. */
+interface AnchorEntry {
+  anchor: string
+  id: string
+}
+
+/** Shared routing state for the fs/subprocess switch rows. */
+export class WorkspaceSeamState {
+  private readonly records = new Map<string, SshWorkspaceRecord>()
+  private readonly instances = new Map<string, SeamInstances>()
+  private anchors: AnchorEntry[] = []
+  private appliedRevision = -1
+  private ready = false
+  private readyResolvers: Array<() => void> = []
+  private fsFactory: ((record: SshWorkspaceRecord) => WorkspaceWorld) | undefined
+  private subFactory: ((record: SshWorkspaceRecord) => SshSubprocessRuntime) | undefined
+
+  constructor(private readonly ledger: SshWorkspaceLedger) {}
+
+  /** Bind the fs-row's per-record backend builder (called once at apply). */
+  bindFs(factory: (record: SshWorkspaceRecord) => WorkspaceWorld): void {
+    this.fsFactory = factory
+  }
+
+  /** Bind the subprocess-row's per-record runtime builder (called once at apply). */
+  bindSub(factory: (record: SshWorkspaceRecord) => SshSubprocessRuntime): void {
+    this.subFactory = factory
+  }
+
+  /** True once the initial ledger snapshot has been applied. */
+  isReady(): boolean {
+    return this.ready
+  }
+
+  /** Resolves once the initial ledger snapshot has been applied. */
+  whenReady(): Promise<void> {
+    if (this.ready) return Promise.resolve()
+    return new Promise((resolve) => {
+      this.readyResolvers.push(resolve)
+    })
+  }
+
+  /**
+   * Subscribe to ledger commits and kick the initial load. Returns the
+   * subscription disposer (register it through ctx.effect for HMR cleanup).
+   */
+  attach(): () => void {
+    const unsubscribe = this.ledger.subscribe(() => {
+      this.applySync()
+    })
+    void this.ledger.load()
+      .then(() => {
+        this.applySync()
+        this.markReady()
+      })
+      .catch((error: unknown) => {
+        console.warn('[dsh-hardssh] failed to load the workspace ledger:', error instanceof Error ? error.message : String(error))
+      })
+    return unsubscribe
+  }
+
+  /** Re-apply the ledger's current in-memory state (idempotent, guarded). */
+  applySync(): void {
+    const snapshot = this.ledger.snapshotSync()
+    if (snapshot.revision < this.appliedRevision) return
+
+    const next = new Map<string, SshWorkspaceRecord>()
+    for (const record of snapshot.records) next.set(record.id.toLowerCase(), record)
+    // Drop instances of removed workspaces so stale routing can never reach them.
+    for (const id of this.records.keys()) {
+      if (!next.has(id)) this.instances.delete(id)
+    }
+    this.records.clear()
+    for (const [id, record] of next) this.records.set(id, record)
+    this.anchors = [...this.records.entries()]
+      .map(([id, record]) => ({ anchor: normalizeAnchorPath(record.anchorPath), id }))
+      .sort((a, b) => b.anchor.length - a.anchor.length) // longest prefix first
+    this.appliedRevision = snapshot.revision
+  }
+
+  /** The record owning a session cwd, or undefined when the cwd is local. */
+  private recordFor(cwd: string | undefined): SshWorkspaceRecord | undefined {
+    if (cwd === undefined || cwd === '') return undefined
+    for (const { anchor, id } of this.anchors) {
+      if (isPathUnderAnchor(anchor, cwd)) {
+        const record = this.records.get(id)
+        if (record !== undefined) return record
+      }
+    }
+    return undefined
+  }
+
+  private ensureFs(record: SshWorkspaceRecord): WorkspaceWorld | undefined {
+    if (this.fsFactory === undefined) return undefined
+    const id = record.id.toLowerCase()
+    let entry = this.instances.get(id)
+    if (entry === undefined) {
+      entry = {}
+      this.instances.set(id, entry)
+    }
+    if (entry.fs === undefined) entry.fs = this.fsFactory(record)
+    return entry.fs
+  }
+
+  private ensureSubprocess(record: SshWorkspaceRecord): SshSubprocessRuntime | undefined {
+    if (this.subFactory === undefined) return undefined
+    const id = record.id.toLowerCase()
+    let entry = this.instances.get(id)
+    if (entry === undefined) {
+      entry = {}
+      this.instances.set(id, entry)
+    }
+    if (entry.subprocess === undefined) entry.subprocess = this.subFactory(record)
+    return entry.subprocess
+  }
+
+  /** The fs world owning a session cwd, or undefined (local). */
+  worldForFs(cwd: string | undefined): WorkspaceWorld | undefined {
+    const record = this.recordFor(cwd)
+    return record === undefined ? undefined : this.ensureFs(record)
+  }
+
+  /** The fs world for one namespaced target key (`wfs://<id>/…` or legacy
+   *  `ssh:<id>:`), or undefined when the owning workspace no longer exists
+   *  (stale key → fail closed). */
+  worldForFsNamespace(namespace: string): WorkspaceWorld | undefined {
+    let id: string | undefined
+    if (namespace.startsWith('wfs://')) {
+      id = namespace.slice('wfs://'.length, -1) // strip trailing '/'
+    } else if (namespace.startsWith(REMOTE_PREFIX)) {
+      id = namespace.slice(REMOTE_PREFIX.length, -1)
+    }
+    if (id === undefined || id === '') return undefined
+    const record = this.records.get(id)
+    return record === undefined ? undefined : this.ensureFs(record)
+  }
+
+  /** The subprocess runtime owning a session cwd, or undefined (local). */
+  runtimeForSub(cwd: string | undefined): SshSubprocessRuntime | undefined {
+    const record = this.recordFor(cwd)
+    return record === undefined ? undefined : this.ensureSubprocess(record)
+  }
+
+  private markReady(): void {
+    this.ready = true
+    const resolvers = this.readyResolvers
+    this.readyResolvers = []
+    for (const resolve of resolvers) resolve()
+  }
+}

package/src/shell.ts

@@ -0,0 +1,10 @@
+/**
+ * Canonical POSIX shell single-quoting for remote command construction.
+ * Replaces the three near-identical copies that used to live in backend.ts,
+ * tools.ts and remote/environment.ts.
+ */
+
+/** Quote one argument for a POSIX login shell (single-quote, `'\''` for embedded quotes). */
+export function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`
+}

package/src/ssh/connection/lease.ts

@@ -0,0 +1,17 @@
+import type { Client } from 'ssh2'
+
+/** What kind of resource owns a lease (drives diagnostics and teardown). */
+export type LeaseKind = 'operation' | 'stream' | 'session' | 'tunnel'
+
+/** One unit of ownership over a pooled SSH connection. */
+export interface ClientLease {
+  readonly alias: string
+  readonly client: Client
+  readonly generation: number
+  readonly kind: LeaseKind
+  readonly released: boolean
+  /** Mark the underlying connection broken (surfaces to every holder). */
+  markBroken(error?: unknown): void
+  /** Idempotent: release this holder's ownership of the connection. */
+  release(): void
+}

package/src/ssh/connection/pool.ts

@@ -0,0 +1,275 @@
+import type { Client } from 'ssh2'
+import type { ClientLease, LeaseKind } from './lease.ts'
+
+export interface AcquireLeaseOptions {
+  kind: LeaseKind
+  signal?: AbortSignal
+}
+
+/** The connection-ownership service (replaces pinned+inFlight bookkeeping). */
+export interface SshConnectionService {
+  acquire(alias: string, options: AcquireLeaseOptions): Promise<ClientLease>
+  invalidate(
+    alias: string,
+    options?: {
+      includeDependents?: boolean
+      mode?: 'drain' | 'force'
+    },
+  ): void
+  invalidateAll(): void
+  /** Aliases currently holding a live pooled transport. */
+  liveAliases(): string[]
+}
+
+export interface ConnectionPoolOptions {
+  idleTimeoutMs: number
+  /** Open a fresh SSH connection (with jump chain) for one alias. */
+  connect(alias: string): Promise<{ client: Client; hops: Client[] }>
+  /** Called when a pooled connection is torn down (e.g. drop SFTP cache). */
+  onDispose?(client: Client): void
+}
+
+interface PoolRecord {
+  client: Client
+  hops: Client[]
+  idleAt: number
+  broken: boolean
+  generation: number
+  /** The single source of truth for whether the connection is in use. */
+  leases: Set<ClientLease>
+  draining: boolean
+  closed: boolean
+}
+
+function createAbortError(): Error {
+  const error = new Error('SSH connection lease acquisition aborted')
+  error.name = 'AbortError'
+  return error
+}
+
+/**
+ * Per-alias connection pool with explicit leases. A connection is swept only
+ * when it has zero leases AND it is idle past the threshold (or draining);
+ * `invalidate` bumps the generation so a half-open handshake can never
+ * re-enter the pool after a config change.
+ */
+export class ConnectionPool implements SshConnectionService {
+  private readonly records = new Map<string, PoolRecord>()
+  private readonly acquireQueue = new Map<string, Promise<PoolRecord>>()
+  private readonly generations = new Map<string, number>()
+  private readonly options: ConnectionPoolOptions
+  private readonly sweepTimer: NodeJS.Timeout
+
+  constructor(options: ConnectionPoolOptions) {
+    this.options = options
+    this.sweepTimer = setInterval(
+      () => this.sweep(),
+      Math.max(10_000, options.idleTimeoutMs / 4),
+    )
+    this.sweepTimer.unref?.()
+  }
+
+  async acquire(alias: string, options: AcquireLeaseOptions): Promise<ClientLease> {
+    if (options.signal !== undefined && options.signal.aborted) throw createAbortError()
+
+    let record = this.records.get(alias)
+    if (record?.draining === true || record?.broken === true) {
+      throw new Error(`SSH connection '${alias}' is draining`)
+    }
+
+    if (record === undefined) {
+      record = await this.acquireRecord(alias)
+    }
+
+    if (options.signal !== undefined && options.signal.aborted) throw createAbortError()
+
+    if (
+      record.draining
+      || record.broken
+      || record.closed
+      || this.records.get(alias) !== record
+    ) {
+      throw new Error(`SSH connection '${alias}' is unavailable`)
+    }
+
+    const lease = this.createLease(alias, record, options.kind)
+    record.leases.add(lease)
+    record.idleAt = Date.now()
+    return lease
+  }
+
+  invalidate(alias: string, options?: { includeDependents?: boolean; mode?: 'drain' | 'force' }): void {
+    // Today every target owns its full jump chain (no shared hop records), so
+    // there are no dependents to cascade to; reserved for shared-hop pools.
+    void options?.includeDependents
+
+    this.generations.set(alias, (this.generations.get(alias) ?? 0) + 1)
+
+    const record = this.records.get(alias)
+    if (record === undefined) return
+
+    record.draining = true
+
+    if (options?.mode === 'force') {
+      this.closeTransport(record)
+    }
+
+    if (record.leases.size === 0) {
+      this.disposeRecord(alias, record)
+    }
+  }
+
+  invalidateAll(): void {
+    clearInterval(this.sweepTimer)
+
+    const aliases = new Set([...this.records.keys(), ...this.acquireQueue.keys()])
+    for (const alias of aliases) {
+      this.invalidate(alias, { mode: 'force' })
+    }
+  }
+
+  /** Aliases currently holding a live pooled transport. A record that is
+   *  closed / broken / draining is retired and does not count as connected. */
+  liveAliases(): string[] {
+    const aliases: string[] = []
+    for (const [alias, record] of this.records) {
+      if (!record.closed && !record.broken && !record.draining) aliases.push(alias)
+    }
+    return aliases
+  }
+
+  private async acquireRecord(alias: string): Promise<PoolRecord> {
+    const pending = this.acquireQueue.get(alias)
+    if (pending !== undefined) return pending
+
+    const task = this.connectRecord(alias)
+    this.acquireQueue.set(alias, task)
+
+    try {
+      return await task
+    } finally {
+      if (this.acquireQueue.get(alias) === task) {
+        this.acquireQueue.delete(alias)
+      }
+    }
+  }
+
+  private async connectRecord(alias: string): Promise<PoolRecord> {
+    const generation = this.generations.get(alias) ?? 0
+    const { client, hops } = await this.options.connect(alias)
+
+    const record: PoolRecord = {
+      client,
+      hops,
+      idleAt: Date.now(),
+      broken: false,
+      generation,
+      leases: new Set<ClientLease>(),
+      draining: false,
+      closed: false,
+    }
+
+    const breakRecord = (): void => {
+      record.broken = true
+      record.draining = true
+
+      for (const lease of [...record.leases]) {
+        lease.markBroken()
+      }
+
+      if (record.leases.size === 0) {
+        this.disposeRecord(alias, record)
+      }
+    }
+
+    client.on('error', breakRecord)
+    client.on('close', breakRecord)
+
+    // An invalidate may land while the handshake is in flight; a stale
+    // generation connection must not re-enter the pool afterwards.
+    if ((this.generations.get(alias) ?? 0) !== generation) {
+      this.closeTransport(record)
+      throw new Error(`SSH connection '${alias}' was invalidated while connecting`)
+    }
+
+    this.records.set(alias, record)
+    return record
+  }
+
+  private createLease(alias: string, record: PoolRecord, kind: LeaseKind): ClientLease {
+    let released = false
+    let broken = false
+
+    const lease: ClientLease = {
+      alias,
+      client: record.client,
+      generation: record.generation,
+      kind,
+
+      get released(): boolean {
+        return released
+      },
+
+      markBroken: (_error?: unknown): void => {
+        if (released || broken) return
+
+        broken = true
+        record.broken = true
+        record.draining = true
+      },
+
+      release: (): void => {
+        if (released) return
+
+        released = true
+        record.leases.delete(lease)
+        record.idleAt = Date.now()
+
+        if (record.leases.size === 0 && (record.draining || record.broken)) {
+          this.disposeRecord(alias, record)
+        }
+      },
+    }
+
+    return lease
+  }
+
+  private sweep(): void {
+    const cutoff = Date.now() - this.options.idleTimeoutMs
+
+    for (const [alias, record] of this.records) {
+      if (record.leases.size === 0 && (record.draining || record.idleAt < cutoff)) {
+        this.disposeRecord(alias, record)
+      }
+    }
+  }
+
+  private disposeRecord(alias: string, record: PoolRecord): void {
+    if (this.records.get(alias) === record) {
+      this.records.delete(alias)
+    }
+
+    this.closeTransport(record)
+  }
+
+  private closeTransport(record: PoolRecord): void {
+    if (record.closed) return
+    record.closed = true
+
+    this.options.onDispose?.(record.client)
+
+    try {
+      record.client.end()
+    } catch {
+      // already closed
+    }
+
+    for (const hop of record.hops) {
+      try {
+        hop.end()
+      } catch {
+        // already closed
+      }
+    }
+  }
+}