# Streaming API
**License:** **GPL-3.0-only** — see [`../LICENSE`](../LICENSE).
## Why streaming?
Large files (or pipes) should not require loading the entire input into RAM.
ZEX streaming processes **one block at a time** (default 256 KiB).
## Encoder (`StreamEncoder`)
Implements `std::io::Write`.
```rust
use std::io::Write;
use zexc::{StreamEncoder, CompressOptions, CompressionMode};
let out = std::fs::File::create("big.zex")?;
let mut enc = StreamEncoder::new(
out,
CompressOptions::default()
.mode(CompressionMode::Turbo)
.level(1)
.block_size(256 * 1024),
);
// from any Read:
std::io::copy(&mut std::fs::File::open("big.bin")?, &mut enc)?;
let file = enc.finish()?; // required!
```
### Lifecycle
1. First write → emit `ZexHeader` (`content_size = unknown`)
2. Each full `block_size` of input → compress + write one block
3. `finish()` → last partial block, `End`, CRC32
4. Drop without `finish()` → **incomplete frame** (don’t do that)
### Not supported
- AEAD encryption (use one-shot `compress` + password)
- Dependent blocks / sliding window across blocks
## Decoder (`StreamDecoder`)
Implements `std::io::Read`.
```rust
use std::io::Read;
use zexc::StreamDecoder;
let inp = std::fs::File::open("big.zex")?;
let mut dec = StreamDecoder::new(inp);
let mut out = std::fs::File::create("big.bin")?;
std::io::copy(&mut dec, &mut out)?;
```
### Lifecycle
1. First read → parse header
2. Pull next block when output buffer empty
3. On `End` → verify CRC if present
4. Encrypted frames → error (use one-shot)
## Pipes
```bash
# compress stdin → stdout
# library style
# StreamEncoder::new(stdout, opts) ...
```
CLI currently focuses on files; library streaming is the full pipe solution.
## Memory
| Encoder input buffer | 1 × `block_size` |
| Decoder output buffer | 1 × last block |
| Match tables (encode) | ~`2^hash_log` × 4 bytes per block |
## Errors
Streaming maps `zexc::Error` → `std::io::Error` with `ErrorKind::InvalidData`
or `Other`. Checksum failures surface on the final `read` that hits End.