sftp

SFTP v3 file transfers and directory operations. Bulk I/O uses native request pipelining. Requires Hot 3.0.5 or later, which includes the SSH and SFTP runtime bindings.

hot.project.my-app.deps {
    "hot.dev/sftp": "0.1.2"
}
::sftp ::sftp
::ctx ::hot::ctx

session ::sftp/connect({
    host: "files.example.com",
    user: "integration",
    host-key: ::ctx/get("files.host.key"),
    private-key: ::ctx/get("files.private.key")
})

entries ::sftp/list(session, "/incoming")
data ::sftp/read-file(session, "/incoming/report.csv")
::sftp/write-file(session, "/outgoing/report.csv", data)
::sftp/rename(session, "/outgoing/report.csv", "/outgoing/ready.csv")
::sftp/close(session)

Use a trusted OpenSSH public key or SHA256 fingerprint for host-key. A full public key also selects which of the server's host keys is used; see the hot.dev/ssh README. Connection options are shared with hot.dev/ssh: port defaults to 22; timeout defaults to 30000 milliseconds. Supply either private-key contents (with optional passphrase) or password. Hot's outbound network policy applies.

Operations

FunctionsBehavior
connect(options), start(ssh-connection)Open SFTP on a new or shared SSH connection
list(session, path)Directory entries with name, path, and attributes; buffers the directory listing
stat, lstatAttributes with optional size, uid, gid, permissions, accessed/modified Unix seconds, and kind
exists, realpath, readlinkExistence, canonical path, and symbolic-link target
mkdir, rmdir, removeCreate a directory, remove an empty directory, or remove a file/link
rename(session, old, new), symlink(session, target, link)Rename or create a symbolic link
read-file(session, path[, max])Read Bytes up to a limit; default and maximum 64 MiB
write-file(session, path, data)Create/truncate, write Bytes or UTF-8 Str, acknowledge and close; return byte count
open(session, path[, mode])Open a file: read (default), write, append, or read-write
read(file, max), write(file, data), seek(file, offset)Chunk I/O and absolute cursor positioning
close(file-or-session)Release resources; safe to repeat

Paths are remote POSIX paths. exists returns false for a missing path; permission and connection errors remain Err. Rename replacement behavior follows the server's SFTP v3 implementation. Writes acknowledge server acceptance, without requesting an additional durable filesystem sync.

Large files and errors

Use open and repeated read/write calls for large files. Each read is limited to 64 MiB and may return fewer bytes than requested; only null indicates EOF. write flushes outstanding requests before returning. A failed file operation invalidates its cursor handle; close it and reopen as appropriate. Failed or cancelled writes may have partially modified the remote file. Upload to a temporary remote path and rename when the application needs a publish step.

Operations on one file handle serialize cursor access. Separate files may be used in parallel on one session. Close files before closing their session. connect owns and closes its SSH connection; start leaves the caller's shared SSH connection open. Runtime handles cannot be restored from checkpoints.

Development checks

From the repository root, run the hermetic native tests and the optional local OpenSSH interoperability test (requires sshd and ssh-keygen):

cargo test -p hot --test ssh_sftp
python3 scripts/test-sftp-openssh.py --hot-bin target/debug/hot

The OpenSSH check creates temporary keys, files, and a loopback server, and cleans them up when it exits.

License

Apache-2.0. See LICENSE.