54 lines
2.5 KiB
Markdown
54 lines
2.5 KiB
Markdown
# 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.
|