Module bundle 

Pull a whole bundle: every blob a bundle manifest names, into an output directory, over the paid cdn/client/v1 path.

A bundle is a JSON manifest of (path, hash, size, chunks) entries (adr/appendix-bundles.md). BundlePuller fetches each distinct blob once, from one shared payment pool, and lands it at every path that names it. It resumes from what an earlier run left: a file already on disk is skipped, a byte-identical file elsewhere in the output directory is linked, a range a sibling entry shares is spliced from disk, and a .partial an interrupted run left is the next fetch’s prefix.

A pull, end to end

1. Resolve the holders once for the run with select_nodes: the pinned node, or every active registered node for each entry to sample.
2. Build a BundlePuller over the chain, the local site, an endpoint, a buyer-pool store and the Funding the pull pays from.
3. Get the manifest: BundlePuller::fetch_manifest it by its hash, or BundleManifest::parse bytes you already hold.
4. Drop the entries you do not want, then BundlePuller::pull the rest. Progress reaches a BundleObserver; the result is a BundleOutcome.
5. BundlePuller::finish waits for the lanes’ watermark writes.

The pull future is not Send: every entry and lane runs on the task that awaits it. Await it in place, or on a tokio::task::LocalSet.

Structs

BundleManifest

A bundle manifest: the files a bundle publishes (adr/appendix-bundles.md).

BundleOutcome

How a bundle pull ended, and what it did.

BundlePuller

Pulls bundles into a directory over one paid run: one pool, one connection per node, one progress clock.

BundlePullerBuilder

Builds a BundlePuller (BundlePuller::builder).

BundleReport

What a bundle pull did. Counts are per entry, and fetched, linked, skipped, reused, failed and not_run add up to the manifest’s entry count. Every byte total but Self::paid_bytes is content bytes and leaves out the bao proof overhead.

EntryFailure

One entry a bundle pull failed to land.

EntryLanded

One blob that landed (BundleObserver::entry_landed). No byte counts in more than one of paid, spliced and resumed.

ForeignPath

A path a pull may replace that no record vouches for (foreign_paths).

ManifestChunk

One chunk of a ManifestEntry: an independently BLAKE3-addressed run of the file’s bytes, placed at the running sum of the earlier chunks’ sizes.

ManifestEntry

One file of a BundleManifest.

NodeSelection

Where a pull’s entries find their holders: the pinned node, or every active registered node for each entry to sample. Resolve it with select_nodes.

NotAManifest

Bytes that are not a v1 bundle manifest: BundleManifest::parse’s error, so a caller can tell a blob that is not a manifest from a failed fetch.

Enums

BundleEnd

Why a bundle pull ended.

ForeignReason

Why no skip-cache record vouches for a ForeignPath.

Funding

What a bundle pull pays from.

Constants

STAGING_DIR

The directory under the output root where a pull stages the blobs it fetches: <hex>.partial and its resume record while a blob is in flight, and <hex> once it is verified and before it lands at its paths.

Traits

BundleObserver

Where a bundle pull reports its progress. Every method has a default that does nothing. The pull calls them from the task that awaits it.

FileObserver

Where one blob of a bundle pull reports its progress. Every method has a default that does nothing.

Functions

foreign_paths

The entries of manifest whose path under out_dir holds something that a pull of the same entry may replace without the user’s say: a file, directory or link that no record in the skip-cache in out_dir vouches for. A record vouches for a path when the file there still has the recorded size and mtime, and the record names this entry (this manifest hash and manifest path) or holds this entry’s bytes. A caller that did not choose out_dir can refuse the pull first.

parse_hash

Parse a BLAKE3 hash as a bundle manifest or a user names it: 64 hex characters, with an optional 0x or b3: prefix.

select_nodes

Resolve where a pull’s entries find their holders, once for the run.