bee-check 0.4.0

# bee-check

Retrievability checker for Ethereum Swarm references — like
`check.ipfs.network`, but for Swarm and built on plain HTTP via
[bee-rs](https://github.com/ethswarm-tools/bee-rs).

```
bee-check c79394...bdc36a \
    --bee https://my-bee.example.com \
    --bee http://localhost:1633 \
    --gateway https://api.gateway.ethswarm.org \
    --per-chunk

# Resolve a Swarm feed first, then probe the current reference:
bee-check feed:<40-hex-owner>:<64-hex-topic> --bee http://localhost:1633
```

For each Bee URL ("vantage") it calls `GET /stewardship/{ref}` in
parallel and reports whether the reference is retrievable through that
node. Each vantage also reports its **overlay address**, **proximity
order** to the reference, and **Bee version** — so a miss tells you
*which neighborhood* the probe was in, not just that the answer was
no. With `--per-chunk` it walks the manifest, fetches every reachable
chunk via `GET /chunks/{addr}`, and shows which chunks are missing on
which vantage, tagged with the per-chunk proximity. With `--reseed
--stamp <id>` it first calls `GET /stamps/{id}` to confirm the batch
is usable, then issues `PUT /stewardship/{ref}` against the first
vantage.

## Install

```bash
cargo install bee-check
```

Or build from source: `cargo build --release` then take the binary at
`target/release/bee-check`.

## Quick examples

```bash
# Single-vantage check against the default node.
bee-check <ref>

# Multi-vantage; --bee may repeat.
bee-check <ref> --bee https://a.example --bee https://b.example

# Manifest drill-down: probe every chunk on every vantage.
bee-check <ref> --per-chunk

# Machine-readable output (see SPEC.md).
bee-check <ref> --output json

# Re-seed after probing (requires the postage batch you want to use).
bee-check <ref> --reseed --stamp <batch-id> --bee https://my-bee.example
```

## Configuration

- `BEE_API_URL` — used as the single default vantage when no `--bee` flag
  is provided. Falls back to `http://localhost:1633`.

## Exit codes

| code | meaning                                                       |
|------|---------------------------------------------------------------|
| `0`  | At least one vantage returned `retrievable: true`.            |
| `2`  | No vantage returned `retrievable: true` (unretrievable, partial-with-no-success, or all-error). |
| other| Unexpected error (parse failure, invalid arg, etc.).          |

## Multi-vantage semantics

Each vantage gets its own probe. The top-level `status` aggregates them:

- `retrievable` — every vantage said yes
- `unretrievable` — every vantage said no (or errored)
- `partial` — mixed: some yes, some no
- `error` — every vantage errored before producing an answer

This is the "from MY vantage" model, not "globally retrievable" — see
the **Limitations** section.

## Limitations

- **`/stewardship/{ref}` must be exposed.** Most public Swarm gateways
  serve only `/bzz` and `/bytes`. For a meaningful check, point
  `--bee` at a Bee node whose API you can reach (your own, a private
  gateway, etc.).
- **The probe is "from this vantage", not "globally retrievable".**
  Stewardship's `IsRetrievable` walks the manifest through the probed
  node's own retrieval path; another node in a different neighborhood
  might see different results.
- **Per-chunk drill-down is best-effort.** When the root or a child
  manifest can't be fetched, the walker can't recurse past it; the
  top-level `stewardship` result is still authoritative.
- **Re-seed needs a usable stamp.** `--reseed` calls
  `PUT /stewardship/{ref}`, which requires the postage batch ID to be
  known to the probing node.

## See also

- `SPEC.md` — JSON output shape (consumed by the in-progress
  `bee-check-web` static SPA).
- [bee-rs](https://github.com/ethswarm-tools/bee-rs) — the underlying
  Rust SDK.

## License

MIT OR Apache-2.0.