ddn.net.scp

Raised for SCP contract violations: unsafe pathnames, malformed construction inputs, or protocol framing violations.

SCP limits from the support matrix.

Direction of a single-file SCP transfer.

Options for remote command construction.

Explicit metadata policy for the transferred file. Nothing is applied unless the corresponding flag is set: permission bits and timestamps are never implied.

Parameters of a single-file send (local to remote).

Parameters of a single-file receive (remote to local).

Typed SCP operation error (local or remote).

Terminal and non-terminal states of an SCP operation.

Acknowledgment and error statuses carried by single status bytes.

A T timestamp record (seconds resolution).

A C file header record.

One parsed stream event from ScpStreamParser.

Event kinds produced by ScpStreamParser.

Incremental bounded parser for an SCP stream.

The parser consumes arbitrary byte fragments and delivers self-describing events through a sink: status records (acknowledg- ments, end markers, errors), T timestamp records, C headers, and raw data bytes while a data phase is active. Record lengths, numeric fields, and names are validated before use; malformed, truncated, or overflowing input raises ScpException exactly once and the parser must then be discarded.

File data phases are explicit: after a C header is accepted, the state machine calls ScpStreamParser.beginDataPhase with the declared size. Exactly that many bytes are then delivered as ScpEventKind.DATA events before the stream returns to record framing, where the sender's terminator status record arrives. The distinction between an acknowledgment status record and an end-of-list status record is positional and belongs to the transfer state machine; the parser reports both as ScpEventKind.STATUS.

Single-file SCP send (local to remote) over an accepted exec channel.

The caller owns the session, the exec request (buildScpCommand with ScpDirection.SEND), and the channel; the operation never closes the channel. The operation sequences the optional timestamp record, the file header, exactly ScpSendOptions.sourceSize data bytes pulled from the caller's source within a bounded buffer, the data terminator, and a half-close of the channel's write direction as the end of transfer, honoring the remote sink's acknowledgment after every record. Completion requires protocol success and the remote command's clean completion: source exhaustion before the declared size, channel EOF before the end byte, remote error or fatal records, and nonzero or signal exits all fail the operation with distinct messages. Cancellation is cooperative and terminal; already-accepted channel bytes may still drain and the caller then closes the channel. Single-file only: recursive directory mode is not implemented (see the module documentation).

Staged, race-safe local destination file for SCP receives.

A private staging name is created in a pinned, trusted parent. On success linkat publishes it at the destination without replacing an existing name. Once that link succeeds publication is committed; failure to unlink the private staging name is deferred to later cleanup and cannot turn the published transfer into failure. Cleanup only unlinks the private staging name, never the public destination name. Local file support is POSIX-only in this version.

Single-file SCP receive (remote to local) over an accepted exec channel.

The caller owns the session, the exec request (buildScpCommand with ScpDirection.RECEIVE), and the channel; the operation never closes the channel. The operation accepts exactly one file whose C header name matches ScpReceiveOptions.expectedName when set, streams exactly the declared size to the caller-selected destination, and applies only caller-authorized metadata. Content is written under a private staging name in a trusted parent and published without replacement (see ScpLocalFile); a pre-existing destination is refused.

Completion requires the data terminator, the source's end of transfer (channel EOF), and the remote command's clean completion. Local create, write, metadata, or close failures, unsafe or unexpected names, malformed records, and premature EOF all fail the operation with the staging file removed, so incomplete content is never published or reported successful; a file whose content completed exactly as declared is kept even when the later remote completion check fails. Local failures are reported to the remote source with an error record in place of the per-file acknowledgment, preserving the protocol's error semantics. Cancellation is cooperative and terminal with the same cleanup. Single-file only: directory-enter and directory-leave records are protocol failures (see the module documentation).