105 lines
4.6 KiB
Go
105 lines
4.6 KiB
Go
// Package bundle provides producer-facing helpers for distributor source
|
|
// bundles.
|
|
//
|
|
// A source bundle is a local directory containing manifest.json and the files
|
|
// listed by that manifest. Producer applications use this package when they
|
|
// need to generate manifests, validate bundles locally, or write complete
|
|
// bundle directories for distributor to discover, upload, or publish.
|
|
//
|
|
// # Bundle Contract
|
|
//
|
|
// The source manifest is the producer-to-distributor contract. It is named by
|
|
// ManifestName, currently "manifest.json", and uses SchemaVersion, currently 1.
|
|
// A Manifest contains:
|
|
//
|
|
// - SchemaVersion: the source manifest schema version.
|
|
// - ID: the producer's stable bundle identifier.
|
|
// - Digest: the canonical digest of the ordered file records.
|
|
// - Created: an RFC3339 timestamp when marshaled to JSON.
|
|
// - Files: an ordered list of ManifestFile records.
|
|
//
|
|
// Each ManifestFile records a slash-separated bundle-relative Path, a lowercase
|
|
// sha256:<64 hex> SHA256 digest, and a byte Size. File order is significant for
|
|
// the bundle digest and should be chosen deliberately by the producer. Explicit
|
|
// file lists preserve caller order; scan mode sorts by slash-separated path.
|
|
//
|
|
// # Path Rules
|
|
//
|
|
// Public bundle paths are always slash-separated and relative to the bundle
|
|
// root. ValidateSourcePath rejects empty paths, absolute paths, path traversal,
|
|
// dot segments, backslashes, and reserved manifest/state paths. Source files
|
|
// must be regular files; symlinks and other special files are rejected.
|
|
//
|
|
// BuildManifest with Scan true recursively scans Root, includes regular files
|
|
// including dotfiles, excludes manifest.json and .distributor.json, rejects
|
|
// symlinks, and sorts paths lexically. BuildManifest with Files uses exactly
|
|
// the caller-provided paths and preserves their order. Exactly one selection
|
|
// mode must be used.
|
|
//
|
|
// # Manifest Workflows
|
|
//
|
|
// BuildManifest reads existing files under a local root, calculates each
|
|
// ManifestFile, defaults a zero Created value to the current UTC time, calculates
|
|
// the bundle digest, and validates the result. WriteManifest writes
|
|
// manifest.json and fails if it already exists unless WriteManifestOptions has
|
|
// Overwrite set. LoadManifest reads and parses manifest.json. ParseManifest and
|
|
// MarshalManifest are useful when an application stores or transmits manifest
|
|
// bytes directly; MarshalManifest validates before writing deterministic,
|
|
// indented JSON with a trailing newline.
|
|
//
|
|
// ValidateManifest checks manifest-only semantics, including schema version,
|
|
// required fields, path safety, duplicate file paths, digest syntax, file sizes,
|
|
// and bundle digest. ValidateBundle checks a supplied Manifest against local
|
|
// files under a root, including existence, regular-file type, size, SHA-256
|
|
// digest, path safety, and bundle digest.
|
|
//
|
|
// # Complete Bundle Writing
|
|
//
|
|
// WriteBundle is the most convenient producer workflow when source files live
|
|
// outside the final bundle directory. It copies each BundleFile.SourcePath into
|
|
// a staged bundle at BundleFile.Path, builds and writes a compliant manifest,
|
|
// validates the staged bundle, and promotes it to WriteBundleOptions.Root.
|
|
// Overwrite permits replacement of an existing bundle root using a best-effort
|
|
// sibling temporary and backup strategy.
|
|
//
|
|
// # Digest Helpers
|
|
//
|
|
// FileDigest returns the sha256:<64 hex> digest for file bytes. BundleDigest
|
|
// returns the canonical bundle digest for an ordered []ManifestFile.
|
|
// CanonicalFilePayload returns the JSON payload used by BundleDigest, which is
|
|
// mainly useful for tests and diagnostics. ValidateDigest checks digest syntax.
|
|
//
|
|
// Example: build and write a manifest for files already under a bundle root.
|
|
//
|
|
// root := "/var/lib/reports/daily-2026-06-06"
|
|
// manifest, err := bundle.BuildManifest(bundle.BuildOptions{
|
|
// Root: root,
|
|
// ID: "reports.daily.2026-06-06",
|
|
// Files: []string{"report.md", "summary.txt"},
|
|
// })
|
|
// if err != nil {
|
|
// return err
|
|
// }
|
|
// if err := bundle.WriteManifest(root, manifest, bundle.WriteManifestOptions{}); err != nil {
|
|
// return err
|
|
// }
|
|
// if err := bundle.ValidateBundle(root, manifest); err != nil {
|
|
// return err
|
|
// }
|
|
//
|
|
// Example: create a complete bundle from producer-generated files.
|
|
//
|
|
// manifest, err := bundle.WriteBundle(bundle.WriteBundleOptions{
|
|
// Root: "/var/lib/distributor-source/daily-2026-06-06",
|
|
// ID: "reports.daily.2026-06-06",
|
|
// Files: []bundle.BundleFile{
|
|
// {SourcePath: "/tmp/report.md", Path: "report.md"},
|
|
// {SourcePath: "/tmp/summary.txt", Path: "summary.txt"},
|
|
// },
|
|
// })
|
|
// if err != nil {
|
|
// return err
|
|
// }
|
|
// _ = manifest
|
|
package bundle
|