# Fuzzing Infrastructure (INT-12)

This document describes the libFuzzer-based fuzzing harness for the HDF5 format parser.

## Overview

Fuzzing is a technique that generates random or mutated inputs to uncover edge cases and crashes in parsers. This harness ensures that clawhdf5's format parsers handle malformed input gracefully without panicking or exhibiting undefined behavior.

## Fuzz Targets

### fuzz_superblock

Tests the `Superblock::parse()` function with random binary data.

**What it tests:**
- Signature detection (`signature::find_signature()`)
- Superblock header parsing
- Handling of truncated/invalid superblock data

**Coverage:** Superblock parsing code path

### fuzz_datatype

Tests the `Datatype::parse()` function with random binary data.

**What it tests:**
- Datatype message parsing
- Handling of unknown/invalid datatype classes
- Endianness field parsing

**Coverage:** Datatype parsing code path

## Running the Fuzzer

### Prerequisites

Install Rust nightly and libfuzzer support:

```bash
rustup install nightly
cargo +nightly install cargo-fuzz
```

### Run a single target

```bash
cd crates/clawhdf5-format
cargo +nightly fuzz run fuzz_superblock
```

This will run indefinitely, generating and testing inputs. Press Ctrl+C to stop.

### Run with time limit

```bash
cargo +nightly fuzz run fuzz_superblock -- -max_total_time=60  # 60 second timeout
```

### Reproduce a crash

If a crash is found, libfuzzer saves the input to `fuzz/artifacts/fuzz_<target>/`. To reproduce:

```bash
cargo +nightly fuzz run fuzz_superblock /path/to/crash_input
```

## CI Integration

Add to your CI workflow:

```yaml
- name: Run format parser fuzzing (1 minute timeout)
  run: |
    cd crates/clawhdf5-format
    timeout 60 cargo +nightly fuzz run fuzz_superblock -- -max_total_time=60 || true
    timeout 60 cargo +nightly fuzz run fuzz_datatype -- -max_total_time=60 || true
```

## Coverage Goals

- **Superblock parser:** >90% code coverage
- **Datatype parser:** >85% code coverage
- **Filter pipeline:** >80% code coverage (future)

## Known Limitations

- Fuzzing requires `cargo-fuzz`, which requires Rust nightly
- Some edge cases may require manual seed corpus construction
- Fuzzing is time-limited in CI (1-2 minutes) to avoid long build times

## References

- [libfuzzer documentation](https://llvm.org/docs/LibFuzzer/)
- [cargo-fuzz guide](https://rust-fuzz.github.io/book/cargo-fuzz.html)
- INT-11 (unsafe code audit) — pairs with fuzzing for robustness