Documentation/Channels and files

Channels and files

Commands, interactive terminals, file transfers and forwarding share one SSH connection implementation. Keep the resource's lifetime inside the callback that owns it, or explicitly dispose the returned handle.

Interactive channels

withShell owns a PTY for the callback's lifetime. Wait for the remote channel to close before returning. The request timeout bounds opening; the application separately bounds its use of the returned channel:

import { once } from 'node:events';
import { SSHClient } from '@xec-sh/ssh';

async function terminalProbe(ssh: SSHClient): Promise<void> {
  const signal = AbortSignal.timeout(10_000);
  await ssh.withShell(async channel => {
    channel.setWindow(40, 120, 0, 0);
    const closed = once(channel, 'close', { signal });
    channel.end('exit\n');
    await closed;
  }, { term: 'xterm-256color' }, { timeoutMs: 5_000, signal });
}

Use requestShell when another owner needs the channel beyond a callback. The channel is a typed duplex stream with stdout, stderr, resize and signal operations. Sending a signal requests remote action; it does not prove delivery or termination. Attach error and terminal listeners before writing. A request signal stops opening; after handoff, the channel owner must handle its ongoing lifetime. In the example, the same signal bounds waiting for closure, and withShell destroys the channel when the callback settles.

For a terminal application's complete connection and pinned-key example, see interactive SSH.

SFTP streams

Use Node stream composition so read errors, write errors and backpressure reach the same owner:

import { createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import { SSHClient } from '@xec-sh/ssh';

async function download(ssh: SSHClient, destination: string): Promise<void> {
  await ssh.withSFTP(async sftp => {
    await pipeline(
      sftp.createReadStream('/srv/export/data.csv'),
      createWriteStream(destination, { flags: 'wx', mode: 0o600 }),
    );
  }, {
    signal: AbortSignal.timeout(60_000),
    operationTimeoutMs: 15_000,
    maxPendingRequests: 32,
  });
}

The deadline bounds total time; the SFTP inactivity limit bounds stalled requests. Normal downstream backpressure does not count as a network stall. An interrupted download can leave a partial local file. For publication, write an application-owned temporary file, verify it, and then perform the application's intended commit operation.

requestSFTP exposes the typed callback/stream interface when callback ownership is inconvenient. The caller must end or destroy that subsystem. Session closure settles pending operations; late callbacks cannot resurrect ownership.

For small files, sftp.readFile(path, options, callback) collects up to 64 MiB by default. Its maxBytes option accepts integers from 0 to 1 GiB and is checked before opening the file; a limit breach fails the read and closes the owned handle. The limit applies to bytes received, not the server's claimed file size. Use streams for larger files. Transfer worker counts and chunk sizes are bounded; a failed handle operation is not silently retried against the path.

Convenience transfers

import { SSHClient } from '@xec-sh/ssh';

async function transferAssets(ssh: SSHClient): Promise<void> {
  await ssh.putFile('./dist/app.js', '/srv/assets/app.js');
  await ssh.getFile('./downloaded.log', '/srv/log/app.log');
  await ssh.putFiles([
    { local: './dist/index.html', remote: '/srv/assets/index.html' },
    { local: './dist/app.css', remote: '/srv/assets/app.css' },
  ], { concurrency: 2 });
}

Both putFile and getFile take the local path first. To control an individual transfer's deadline or SFTP admission limits, call it inside withSFTP and pass that subsystem as its third argument. The fourth argument contains transfer options, not the subsystem lifecycle options. Transfers do not provide deployment transactions, content verification or rollback. A successful write acknowledgement is not a durability guarantee for the remote filesystem. Use the supported SFTP fsync extension when the server and application require it, and inspect its actual result.

Directory transfer methods preserve empty directories, do not traverse symlinks or special files, and reject unsafe remote entry names before joining paths. Traversal defaults to a maximum depth of 64 and 10,000 entries, counting filtered entries too; configure these through the directory options. Downloads stage each file privately before replacement, reject existing symlink destinations and check observed directory identities. The destination must be owned exclusively by the caller during the operation. Portable filesystem APIs do not make this safe against arbitrary concurrent ancestor replacement by another local writer; the whole directory is not an atomic transaction. mkdir uses SFTP; it does not construct a shell command as a fallback.

Forwarding

APIOwnership
forwardOutAn outgoing TCP channel, owned by its caller
forwardOutStreamLocalAn outgoing Unix-socket channel
forwardIn / forwardInStreamLocalAn acknowledged remote listener with dispose() and closed
SSHConnectionPool.tunnelA local listener and its connection lease
SSHConnectionPool.reverseTunnelA dedicated connection and remote-listener ownership

Prefer Core's target-bound tunnelling API for command automation. A pool's direct forwarding methods require an explicit connection configuration.

Remote listener requests have no application request ID in the SSH response FIFO. Losing an allocation acknowledgement invalidates that connection and reports an unknown outcome; it must not silently issue a second allocation. Closing a remote listener waits for unbind acknowledgement. A refused or timed-out unbind retains ownership for reconciliation or a deliberate retry.

See also

MADE FOR BUILDERS.Static pages. Local search. Built with Lumen + Prism.