Transferetto.Protocols 2.0.4

Transferetto.Protocols

Transferetto.Protocols contains the FTP, FTPS, FXP, SFTP, SCP, and SSH implementations used by Transferetto.

The package provides the existing TransferettoClient protocol API together with FtpTransferEndpoint and SftpTransferEndpoint adapters for the provider-neutral Transferetto.Core copy engine.

Use the protocol API for protocol-specific operations such as FTP synchronization, SSH commands, shells, and tunnels. Use the endpoint adapters with TransferEngine.CopyAsync when data must move between FTP/SFTP, filesystems, S3, or Azure Blob Storage through one streaming contract.

Local directory transfers and synchronization reject symbolic links and Windows junctions instead of following them. Remote names must be representable on the destination filesystem; Windows downloads reject backslash traversal, alternate data streams, and reserved device names. The selected local root must be controlled by the caller, since path checks cannot prevent another process from replacing directories during a transfer.

Filesystem synchronization resolves TransferettoSyncOptions.PathComparison.Automatic from the selected destination directory. Windows per-directory settings, macOS volume settings, and Linux filesystem/per-directory casefold settings are queried without creating probe files. Unknown Unix filesystems use existing entries to detect case aliases and conservatively treat names without distinguishing evidence as case-insensitive. Receive registries keep those comparison decisions for the operation. Explicit comparison options affect planning, but cannot disable destination collision checks. Mirror plans reject a delete that addresses a file copied or retained through another spelling.

SFTP and FTP directory downloads freeze one validated listing of each directory before receiving content. Reads and recursion use the listed child name beneath the selected remote directory, so a server-provided full path cannot redirect them. SCP checks incoming members as they arrive. Distinct remote names that map to one destination, including case-equivalent directory names, fail instead of overwriting or silently skipping another source member. FTP manifest traversal lists literal directory names, including * and ? on compatible filesystems, and observes cancellation between entries and descents.

SFTP, FTP and SCP directory downloads stage incoming content privately on the destination filesystem and publish it only after every selected file succeeds. SCP also waits for the complete directory stream and successful remote command. Rejected names, incomplete content, cancellation, and transport failures discard the staged download. Publication preserves unrelated existing files, gives new files their destination directory's access rules, and rolls back replacements and newly created directories if a local write fails. FTP mirror deletions are deferred until receipt succeeds and are included in rollback. If rollback itself fails, the original error retains the rollback exception and recovery directory in its Data entries Transferetto.RollbackException and Transferetto.RecoveryDirectory, and backups remain available. Cleanup failures are recorded through transfer diagnostics without replacing the transfer result. This requires temporary space for incoming files, replaced or removed originals, and one adjacent publishing copy; it does not provide crash recovery or isolation from concurrent local writers, or a server-side snapshot of remote contents.

FTP retains its native skip/resume policy, verification options, transfer rules and configured excluded-file deletion policy. A failed FTP directory receive returns failed results without publishing staged files or mirror deletions; entries received successfully before another failure are marked failed with an explanation that the directory was not published. Entries skipped because they already exist or fail a rule remain skipped. SFTP raises its receive error after discarding staging. Successful directory calls return per-item results after publication. The separate synchronization APIs continue to execute their explicit plans incrementally.

FTP file, batch and directory downloads independently compare staged binary files with their advertised size, so a successful control reply cannot conceal a short data stream. Unknown remote sizes and ASCII transfers cannot provide this byte-length check; configured native checksum verification still applies. Disabling zero-byte downloads intentionally skips empty members and retains any corresponding local file. Progress events identify the selected destination rather than the private staging path.

Single-file FTP receives stage overwrite and resume data before replacing the destination. Batch downloads validate all destination names before receiving and preserve the selected error policy: None continues after a failed file, Stop returns after the failure, and Throw raises an FTP exception. Without DeleteProcessed, earlier completed files remain published while the failed file retains its original content. With DeleteProcessed, the whole batch is staged until it succeeds, so failure or cancellation discards incoming files and preserves originals instead of deleting previously overwritten destinations. Returned results distinguish failed, skipped and unattempted files; files withheld by batch rollback are reported as unpublished. FTP synchronization uses the protected single-file receive and retains its incremental plan behavior, stopping mirror deletions after a file fails.

ASCII FTP downloads use the native read-to-end path because newline conversion can expand content beyond its binary size. They report completion progress using the received length and check cancellation before and after each file; intermediate byte progress and mid-file cancellation callbacks are available for binary downloads. Batch error policies also cover ordinary local publication failures. If rollback itself fails, the original exception is raised with its recovery details regardless of the batch policy.

Endpoint synchronization preserves the source's exact name when inspecting and reading it. Literal backslashes are preserved on Unix destinations and rejected before writes on Windows destinations. Unrepresentable destination names fail explicitly instead of becoming a different directory hierarchy.

Known-host and FTPS certificate stores serialize updates across processes and replace the store atomically. Malformed stores fail closed; repair or replace the affected store explicitly. SSH SHA-256 pins preserve the case-sensitive Base64 digest, while MD5 hexadecimal pins accept either hex case.

SFTP file transfers stage replacement content before committing it. The asynchronous file APIs use asynchronous SFTP I/O, close remote handles on cancellation, and report upload progress as source bytes read. Shell readers check their deadline even during continuous output. Use TransferettoSshShellReadOptions.MaxCapturedCharacters to bound retained output and OutputProgress to consume arriving chunks; exceeding the capture limit throws IOException.