[javi11]

Summary

Second PR of the peer network stack, on top of #1068. Adds exposure level 3 (share bundles): a node can serve a sanitised, compressed description of a finished import, and another node can mount the release from it after verifying it locally, without downloading or analysing the NZB.

Design: docs/superpowers/specs/2026-11-12-peer-network-design.md (the "Phase 3" sections)
User docs: docs/docs/3. Configuration/peer-network.md

Bundle format

• Own versioned schema, canonical protobuf wire encoding, strict decoding (decode then re-encode must reproduce the bytes), zstd with bounded streaming decompression and bundle-wide budgets. Limits: 8 MB compressed, 64 MB decompressed, 500,000 segments, 10,000 files.
• The Bundle ID is the hash of the canonical bytes and is carried in the signed release record, so a peer cannot substitute another bundle.
• Never contains local or store paths, rclone password or salt, known holes, indexer, category, ARR or provider data.
• Not shareable: rclone-encrypted files, files repaired by local PAR2 patches, and keyed releases unless the password came inside the NZB itself (recorded at import time; user-supplied and filename passwords do not count).

Serving and fetching

• Served only on the mutual-TLS peer listener, only at level 3, only for bundles this node announced in that network, with exclusions re-checked at serve time. Rate, byte and concurrency limits per peer, per address and node-wide.
• Bundles are rebuilt on demand; builds are deterministic.
• Fetched only on demand from a local caller, only from the publisher itself, and verified against the IDs in the signed record.

Receiving (verified in every network before anything is written)

• Hash and structure, no gap references, each file exactly one NZB entry in order, declared sizes against the NZB, article presence on the user's own providers, yEnc headers of randomly sampled articles against the layout, and a structural media check through the real reader stack that reads to the end of the file.
• Only verified media plus subtitles and small NFO files are written; files a media server or the application could act on reject the bundle.
• The import is playable at once. A full check of every segment is forced. It is announced to ARR applications and published to the network only after that check passes. While verifying, an ARR-submitted item stays in the SABnzbd-compatible queue as in progress; a failed or stale import is removed and reported as failed.
• No archive parser and no key derivation run when a bundle is accepted.

Importer fast path

When an NZB is imported and a peer offers a bundle for the same release, the layout is taken from the bundle and archive analysis is skipped. On by default for private networks; for the open network it is off unless peernet.open_network.fast_path is enabled, and then only for bundles announced identically by two known publishers. It falls back to the normal import on any error.

Older library content

Imports in the older metadata format had a file ID but no release ID. They now get a release identity derived from their set of file IDs, computed from the existing index with no NZB parsing, and health evidence matches by file ID.

Stream listings

Releases offered by peers with a fetchable bundle are listed for a media ID, marked as coming from the peer network, and are fetched, verified and imported on play. Media IDs learned this way are not republished.

Changes outside the feature

• internal/importer: optional fast-path hook after NZB parsing, password-origin recording, a hold flag for imports awaiting verification.
• internal/health: optional gate that forces full checks for peer imports and reports their results.
• internal/api: SABnzbd-compatible queue and history handling of held items, additive DTO fields, stream listing and play route.
• Migrations 057-062 for SQLite and PostgreSQL.

Test plan

• go build ./..., go vet ./...
• go test -race ./...
• internal/database tests against PostgreSQL 16, migrations applied from empty
• golangci-lint clean on the new and touched packages (run per package)
• Frontend: type check, unit tests, production build
• Fuzzing of the bundle decoder, decompressor and validator
• Multi-node tests on loopback: publish at level 3, fetch, verify, import, forced full check, announce once; failure variant
• Two live instances: serve and import a real release over a private network
• yEnc sampling cost and behaviour against real providers
• ARR client behaviour while an item is verifying (reasoned from their status handling, not run)
• Stream listing and play with a real client
• Settings UI checked in a browser

Notes for reviewers

• The structural media check accepts Matroska, MP4 (including fragmented) and transport streams; other containers get bounded reads through the file. A Matroska file with no seek index has its end checked only by size and readability.
• Each accepted bundle costs up to 24 sampled articles of extra download.
• Password-protected releases imported before this change, or while the feature was off, are not shareable as bundles.