Bundles

Purpose

internal/bundle discovers and validates source bundles through the storage interface. The source manifest model, manifest parsing, manifest validation, path rules, digest calculation, and producer-side local writer come from pkg/bundle so producer-facing APIs and distributor validation share one manifest contract.

Inputs and outputs

Input is a backend-rooted directory tree containing one or more manifest.json files. Output is a deterministic list of validated bundles with relative bundle paths and normalized manifest data.

Manifest behavior

The source manifest requires:

schema_version: 1
id
digest
created
non-empty files

Each file requires path, sha256, and size. Digests must use lowercase sha256:<64 hex> format. created must parse as RFC3339.

Validation

pkg/bundle.ValidateManifest owns normalized source manifest semantics: schema version, id, digest format, timestamp presence, file list presence, source path safety, duplicate file paths, reserved paths, file digest format, non-negative file sizes, and the top-level bundle digest.

Storage-backed bundle validation in internal/bundle additionally checks file existence, regular-file type, file size, and per-file SHA-256 for configured storage backends.

The bundle digest is SHA-256 of a deterministic JSON array of file records in manifest order with fields path, sha256, and size.

Discovery

Discovery walks a storage backend beneath a source root, finds manifest.json files, sorts bundle paths lexically, and rejects nested manifests.

Failure behavior

Manifest parsing and validation fail before destination planning. Storage-backed validation fails when listed files are missing, are not regular files, have unexpected sizes, have unexpected SHA-256 digests, or when a source bundle includes unsafe or reserved paths.

Boundaries

Internal bundle discovery uses internal/storage and does not import concrete adapters. Producer-side local filesystem manifest building, complete bundle writing, and validation belong to pkg/bundle. CLI local path support is wired in internal/app.

Tests

Before changing bundle behavior, inspect tests under pkg/bundle and internal/bundle.

Invariants

manifest.json is the only source bundle contract.
Source file paths must stay relative to the bundle root.
The top-level bundle digest is derived from manifest file records in order.
Discovery order is lexical and deterministic.
Nested manifests are rejected.

2.5 KiB Raw Blame History