Seed the blobs core, not just the metadata
The operational trap of Hyperdrive hosting, which we hit publishing the
p2pbuilders web build to HiveRelay.
The symptom
Publish the site as a Hyperdrive. Ask relays to pin drive.key. Relays
accept; status shows replicas across regions. Publisher goes offline.
A visitor opens the site: listings resolve, every file read hangs.
The cause
A Hyperdrive is two Hypercores: a metadata core
(the file tree — this is what drive.key names) and a separate
content/blobs core holding the actual bytes. Seeding by drive key pinned
the metadata only. The relays could prove the shape of the site and serve
none of it. And once the publisher left, the bytes existed nowhere always-on
— the drive was unrecoverable until we came back online.
The fix
Resolve the blobs core and seed it explicitly, every publish:
await drive.ready()
const blobs = await drive.getBlobs()
await relay.seed(drive.key) // metadata core
await relay.seed(blobs.core.key) // content core — the actual site
Then verify like you mean it: our publisher waits for proof a relay
replicated the bytes (waitForDurable) before exiting, instead of
trusting an acceptance handshake.
The general lessons
- Know your object graph. Abstractions that feel like one thing
(a "drive") are often several replicable units. Pin the closure, not the
handle.
- "Accepted" is not "replicated." A pin request succeeding means a
relay will try. Durability claims need evidence: bytes confirmed on a
machine that is not yours.
- Test the dead-publisher path. Publish, kill the publisher, fetch cold
from another network. It is the only test that means anything for
availability — and it is exactly the check web/check-durable.mjs in
this repo automates.