Handling EngineError Variants in the Hayate Rust Library

Every fallible function in the hayate crate returns Result<T, EngineError>. EngineError is a single flat enum that covers the full range of failure modes across the engine — from file system I/O errors and QUIC transport failures to cryptographic handshake problems and protocol mismatches. Because all errors are unified under one type, you can handle them with a single match arm in most callers, and drill into specifics only where your application needs to recover or provide user-facing messages.

EngineError Variants

Variant	Description
`Io(io::Error)`	File system or socket I/O error
`TimedOut(String)`	Operation timed out waiting for a peer or data
`Cancelled(String)`	Operation cancelled by the caller via the progress callback
`ProtocolMismatch { local, remote }`	Protocol version mismatch between sender and receiver
`TransferRejected`	Receiver explicitly rejected the transfer via the consent callback
`InvalidPassphrase`	Key exchange authentication failed due to a wrong pairing code
`Crypto(&str)`	Encryption, decryption, or HKDF key derivation error
`InvalidFrame(String)`	Malformed or oversized frame encountered on the stream
`Handshake(String)`	Handshake negotiation failed (e.g., endpoint closed during pairing)
`Connect(ConnectError)`	QUIC connection initiation error
`Connection(ConnectionError)`	Error on an active QUIC connection
`OpenStream(OpenStreamError)`	Error opening a bidirectional stream on the connection
`Write(WriteError)`	Error writing data to the QUIC stream
`ClosedStream(ClosedStream)`	Write attempted on an already-closed stream
`PathTraversal`	Archive entry attempted path traversal outside the output directory
`Compression(String)`	Zstd compression or decompression error

Matching Errors

Match on specific variants to give users actionable feedback or apply targeted recovery logic:

use hayate::{HayateSender, EngineError};

match sender.send("./file.txt", |_| Ok(())).await {
    Ok(checksum) => println!("Done: {checksum}"),
    Err(EngineError::InvalidPassphrase) => {
        eprintln!("Wrong pairing code — make sure sender and receiver use the same phrase");
    }
    Err(EngineError::TransferRejected) => {
        eprintln!("The receiver declined the transfer");
    }
    Err(EngineError::TimedOut(msg)) => {
        eprintln!("Transfer timed out: {msg}");
    }
    Err(EngineError::Io(e)) => {
        eprintln!("I/O error: {e}");
    }
    Err(e) => eprintln!("Transfer failed: {e}"),
}

Cancelling a Transfer

You can abort an in-progress transfer at any time by returning Err(EngineError::Cancelled(...)) from the progress callback. The engine stops sending immediately and propagates the error as the return value of .send() or .receive():

use hayate::{HayateSender, EngineError};

let mut bytes_so_far = 0u64;

let checksum = sender.send("./file.txt", |bytes| {
    bytes_so_far = bytes;
    if bytes_so_far > 500_000_000 {
        return Err(EngineError::Cancelled("file too large".into()));
    }
    Ok(())
}).await?;

This is the recommended way to implement user-initiated cancel buttons, size guards, or timeout policies at the application layer.

EngineError is marked #[non_exhaustive]. New variants may be added in future minor releases without a breaking change. Always include a wildcard arm (Err(e) => ...) at the end of your match to ensure your code compiles against newer versions of the crate.

​EngineError Variants

​Matching Errors

​Cancelling a Transfer

EngineError Variants

Matching Errors

Cancelling a Transfer