hayate 5.1.0

High-performance completion-based QUIC transfer engine.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136

<p align="center">
  <img src="../assets/logo.svg" width="140" height="140" alt="Hayate Logo">
</p>

<h1 align="center">Hayate Engine</h1>

<p align="center">
  <strong>Standalone high-performance completion-based transfer engine powering the Hayate CLI.</strong>
</p>

<p align="center">
  <a href="https://crates.io/crates/hayate"><img src="https://img.shields.io/crates/v/hayate.svg" alt="Crates.io"></a>
  <a href="https://docs.rs/hayate"><img src="https://docs.rs/hayate/badge.svg" alt="Documentation"></a>
  <a href="https://shiinasaku.github.io/Hayate/"><img src="https://img.shields.io/badge/website-docs-black" alt="Website"></a>
  <a href="../LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT"></a>
</p>

---

`hayate` is the high-performance transfer engine powering the Hayate CLI. It provides high-level `HayateSender` and `HayateReceiver` builders for encrypted file and directory transfers over QUIC, plus low-level modules for apps needing custom protocol control.

Driven by `compio` (an `io_uring`/IOCP runtime) and `compio-quic`, Hayate achieves blazing fast throughput utilizing a multi-threaded AEAD and Zstd pipeline, ephemeral X25519 key agreements, dynamic payload hashing (`blake3`, `rapidhash`, `sha256`), and safe `tar` streaming.

## Installation

```toml
[dependencies]
hayate = "4.0"
compio = { version = "0.19", features = ["macros", "runtime", "fs", "net", "time"] }
```

## Receive API

```rust
use std::net::SocketAddr;
use hayate::HayateReceiver;

#[compio::main]
async fn main() -> Result<(), hayate::EngineError> {
    let bind_addr: SocketAddr = "0.0.0.0:50001".parse().unwrap();

    let receiver = HayateReceiver::new().bind(bind_addr);
    let (checksum, path) = receiver.receive(
        "./downloads",
        |meta| {
            println!("Incoming: {} ({} bytes)", meta.filename, meta.total_size);
            true // Accept the transfer
        },
        |bytes| println!("Received {bytes} bytes"),
    ).await?;

    // Saved payload info
    println!("Saved to {}", path.display());
    println!("Checksum: {checksum}");
    Ok(())
}
```

## Send API

```rust
use std::net::SocketAddr;
use hayate::HayateSender;

#[compio::main]
async fn main() -> Result<(), hayate::EngineError> {
    let target: SocketAddr = "192.168.1.50:50001".parse().unwrap();

    let checksum = HayateSender::new()
        .target(target)
        .compress(true)
        .hash_algo("blake3".to_string())
        .send("photos", |bytes| println!("Sent {bytes} bytes"))
        .await?;

    println!("Checksum: {checksum}");
    Ok(())
}
```

## Pairing Mode

Discover peers across the LAN via UDP broadcasts. The code phrase doubles as the HKDF salt.

```rust
use hayate::{HayateReceiver, HayateSender};

# async fn sender() -> Result<(), hayate::EngineError> {
HayateSender::new()
    .code("alpha-bravo-charlie".to_owned())
    .send("report.pdf", |_| {})
    .await?;
# Ok(())
# }

# async fn receiver() -> Result<(), hayate::EngineError> {
let (_checksum, _path) = HayateReceiver::new()
    .code("alpha-bravo-charlie".to_owned())
    .auto_accept(true)
    .receive("./downloads", |_| true, |_| {})
    .await?;
# Ok(())
# }
```

> [!NOTE]
> Android devices and VPNs often block broadcasts. Fallback to direct IP mode when necessary.

## Module Architecture

| Module       | Purpose                                                                      |
| ------------ | ---------------------------------------------------------------------------- |
| `runner`     | Builder-style APIs: `HayateSender` and `HayateReceiver`.                     |
| `transfer`   | Pipeline orchestration: handshake, consent, multithreaded receive/send pool. |
| `protocol`   | Wire constants, frame flags, metadata structure, and limits.                 |
| `crypto`     | Ephemeral X25519, HKDF, AEAD wrappers, and cipher selection.                 |
| `network`    | QUIC bindings and ephemeral `rustls` configurations.                         |
| `discovery`  | Pairing-code UDP broadcast and listener logic.                               |
| `tar`        | Streaming directory packing and extraction.                                  |
| `local_addr` | Network interface and subnet utilities.                                      |
| `error`      | Defines `EngineError`.                                                       |

## Runtime Notes

`compio` uses completion-based I/O. Buffers must be owned and passed by value to I/O operations (returning via `compio::BufResult`).

Hayate isolates blocking logic (`tar` extraction) and heavy CPU tasks (`zstd` / AEAD) off the executor using dedicated worker threads (`std::thread::spawn`) and `flume` channels. A `BTreeMap` handles chunk reordering on the receiver to guarantee sequential disk writes.

## Safety Guarantees

Hayate treats network data as fundamentally hostile:

- **Encrypted Metadata**: Filename, size, and hashing choices are authenticated before prompting the user.
- **Strict Framing**: Frames are length-capped and verified via AEAD before decompression.
- **Size Verification**: Completed file sizes must match the exact announced byte count.
- **Path Sanitization**: Directory unpacking rigorously prevents absolute paths, parent directory traversals (`..`), symlinks, and hard links.