Source Bundle Internals

Audience: developers and LLM coding agents changing internal/bundle.

Purpose

internal/bundle discovers and validates source bundles through the storage abstraction. It adapts the public producer-facing source manifest contract from pkg/bundle to local, SSH/SFTP, S3-compatible, and test storage backends.

Inputs And Outputs

Inputs are a context, a storage.Backend, and a source-root prefix or bundle root path. Outputs are sorted Bundle records containing the source-root-relative bundle path and validated manifest.

Boundaries

internal/bundle delegates manifest parsing, digest calculation, source path validation, and manifest validation to pkg/bundle. It does not publish files, inspect destination state, choose pipelines, or know concrete backend implementations.

The external source bundle file-format contract is documented in docs/integrations/source-bundle.md.

Config Fields Used

The package does not read config directly. App workflows pass it storage backends that were opened from configured source fields.

Adapters Used

The package depends only on internal/storage.Backend. Concrete local, SSH/SFTP, S3-compatible, and fake backends are hidden behind that interface.

State And Manifest Behavior

Discovery walks recursively under the source root, finds entries whose basename is manifest.json, converts each manifest path to a bundle root, sorts roots, rejects nested bundle roots, and validates each bundle.

Validation reads manifest.json, parses it, stats each manifest-listed file, requires regular files, verifies file sizes, reads file bytes, checks per-file SHA-256 digests, and recomputes the bundle digest.

Skip And Resume Behavior

The package has no skip or resume state. Each call performs discovery or validation from the supplied backend state.

Failure Behavior

Failures include invalid storage prefixes, missing manifests, parse errors, nested manifests, unsafe manifest paths, non-regular files, size mismatches, digest mismatches, backend stat/read errors, and no discovered bundles.

Tests To Inspect

internal/bundle/*_test.go
pkg/bundle/*_test.go
internal/storage/fake/*_test.go

Architectural Invariants

Source manifest semantics remain owned by pkg/bundle.
Discovery order is deterministic.
Nested manifests are rejected before returning bundles.
Source paths stay clean, relative, slash-separated, and confined to the backend root.
Concrete adapters never leak into bundle validation logic.

2.5 KiB Raw Blame History