SCP Transfers

Traversio exposes single-file SCP helpers on SSHConnection for endpoints and tools that still expect the legacy scp protocol.

The helpers open an exec session with the remote scp command, exchange SCP acknowledgements, and close the session after one regular file transfer.

Download One File

Use receiveSCPFile(_:maximumFileSize:) when you want the file contents buffered in memory:

let file = try await connection.receiveSCPFile(
    "/var/log/app/current.log",
    maximumFileSize: 16 * 1024 * 1024
)

print(file.fileName)
print(file.permissions)
print(file.byteCount)

Use downloadSCPFile(_:to:maximumFileSize:) when the destination is a local file URL:

let destination = URL(fileURLWithPath: "/tmp/current.log")

let result = try await connection.downloadSCPFile(
    "/var/log/app/current.log",
    to: destination,
    maximumFileSize: 16 * 1024 * 1024
)

print(result.byteCount)

The buffered receive path defaults to SSHSCPTransferDefaults.maximumBufferedFileByteCount, currently 64 MiB.

Upload One File

Use sendSCPFile(_:remotePath:fileName:permissions:) when your app already has the bytes:

let payload = Array("hello\n".utf8)

let result = try await connection.sendSCPFile(
    payload,
    remotePath: "/tmp/hello.txt",
    permissions: 0o644
)

print(result.fileName)
print(result.exitStatus as Any)

Use uploadSCPFile(from:to:fileName:permissions:) when the source is a local file URL:

let source = URL(fileURLWithPath: "/tmp/hello.txt")

let result = try await connection.uploadSCPFile(
    from: source,
    to: "/tmp/hello.txt"
)

print(result.byteCount)

When permissions is omitted, Traversio reads the local POSIX permissions and masks them to the SCP mode range.

Current Boundaries

The SCP helpers currently cover:

• one regular file per call
• remote paths that can be passed safely to the remote shell
• filenames without path separators or line breaks
• server-side scp implementations available on the remote endpoint
• live round trips on the local OpenSSH, Dropbear, and AsyncSSH validation targets

Use SFTP for directory trees, resumable transfers, progress callbacks, request-window control, metadata workflows, symlinks, and richer error details.

Error Surface

SSHSCPTransferError covers:

• invalid remote paths, filenames, permissions, and maximum buffered sizes
• malformed or unexpected SCP control messages
• remote SCP warnings and fatal errors
• directory records on the single-file receive path
• oversized files
• premature stream end
• non-zero remote exit status

SSHSCPReceivedFile reports the remote path, received filename, permissions, byte count, contents, and optional remote exit status.

SSHSCPTransferResult reports the remote path, resolved filename, byte count, and optional remote exit status for send, upload, and download helpers.