> ## Documentation Index
> Fetch the complete documentation index at: https://hayate.shiina.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Low-Level Hayate Modules for Custom QUIC Integrations

> Access hayate's public modules directly for custom transport control, protocol-level handshakes, discovery management, and buffer pooling.

The `hayate` crate exposes all of its internal subsystems as public modules. Most applications should start and finish with `HayateSender` and `HayateReceiver` — they handle connection setup, handshake, consent, and payload streaming end-to-end. The modules documented here are intended for advanced use cases: custom UI integrations that need to interleave progress UI between handshake stages, applications that manage their own QUIC endpoint lifetime, testing harnesses that probe the protocol directly, or performance-sensitive code paths that want direct access to the buffer pool or cipher selection.

## Module Overview

| Module               | Purpose                                                   |
| -------------------- | --------------------------------------------------------- |
| `hayate::runner`     | High-level `HayateSender` / `HayateReceiver` builders     |
| `hayate::transfer`   | Handshake, consent flow, payload send/receive pipelines   |
| `hayate::protocol`   | Wire constants, `Metadata` struct, frame flags            |
| `hayate::crypto`     | X25519, HKDF, AEAD sealing/opening, hardware detection    |
| `hayate::network`    | QUIC endpoint binding, TLS configuration                  |
| `hayate::discovery`  | mDNS registration/browsing, UDP broadcast                 |
| `hayate::tar`        | Streaming tar pack/extract with path-traversal protection |
| `hayate::pool`       | Zero-alloc buffer leasing (`BufferPool`)                  |
| `hayate::error`      | `EngineError` enum                                        |
| `hayate::local_addr` | Local IPv4 helpers for UI and discovery                   |

## BufferPool: Hot-Path Buffer Reuse

`hayate::pool::BufferPool` is a lock-free channel-backed pool of fixed-size byte buffers. The transfer engine uses it to avoid heap allocations in the frame encode/decode hot loop. You can use the same pool in your own integration code when processing large numbers of frames:

```rust theme={null}
use hayate::pool::BufferPool;
use hayate::protocol::CHUNK_SIZE;

#[compio::main]
async fn main() {
    let pool = BufferPool::new(32, CHUNK_SIZE);
    let buf = pool.lease().await;
    // ... use buffer ...
    pool.release(buf);
}
```

Buffers are zeroed on release to prevent cryptographic plaintext from leaking into subsequently leased buffers.

## Detecting Hardware AES Acceleration

Hayate automatically negotiates the cipher suite during the handshake: AES-256-GCM is selected when the host CPU has hardware AES instructions (AES-NI on x86/x86\_64, AES extension on aarch64), and ChaCha20-Poly1305 is used otherwise. You can query this directly if you want to surface cipher information in your UI:

```rust theme={null}
use hayate::crypto;

if crypto::is_aes_hw_accelerated() {
    println!("AES-NI is available — using AES-256-GCM");
} else {
    println!("No AES-NI — using ChaCha20-Poly1305");
}
```

Set the environment variable `HAYATE_FORCE_CHACHA20` to override hardware detection and always use ChaCha20-Poly1305, which is useful for benchmarking or testing on machines with AES-NI.

## Discovery API

`start_broadcaster_hybrid()` registers both an mDNS `_hayate._udp.local.` service and a UDP broadcast loop simultaneously. It returns a `BroadcasterGuard` — an RAII handle that shuts down both channels when dropped. Use this directly if you are managing the pairing handshake outside of `HayateSender`:

```rust theme={null}
use hayate::discovery;
use hayate::EngineError;

fn start_pairing() -> Result<(), EngineError> {
    let guard = discovery::start_broadcaster_hybrid(
        "my-channel-id",
        50001,
        "linux",
    ).map_err(EngineError::Io)?;

    // Transfer happens here...

    drop(guard); // stops mDNS registration and UDP broadcast loop
    Ok(())
}
```

The channel ID passed to `start_broadcaster_hybrid` should be derived from the pairing phrase using `discovery::derive_channel_id(&phrase)` — this produces a short, phrase-bound hex identifier that is safe to broadcast on the LAN without revealing the passphrase itself.

## Concurrency Model

Understanding how Hayate schedules work helps when integrating it alongside other async or threaded subsystems in your application:

| Layer            | Strategy                                                    |
| ---------------- | ----------------------------------------------------------- |
| I/O              | Single-thread compio event loop (io\_uring / IOCP / kqueue) |
| CPU-bound work   | Dedicated OS thread pool (`std::thread::spawn`) per worker  |
| Frame reassembly | `BTreeMap`-based out-of-order reassembly                    |
| Discovery        | mDNS daemon thread + UDP broadcast task, background         |

Full generated API documentation for all modules is available at [docs.rs/hayate](https://docs.rs/hayate).

<Note>
  Hayate requires **Rust edition 2024** and a minimum supported Rust version (MSRV) of **Rust 1.96**. Ensure your toolchain meets this requirement before adding `hayate` as a dependency.
</Note>