eric/weatherreporter
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Refresh Distributor integration guides

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-31 01:17:37 +00:00
parent ff2e664c62
commit 1130d807dc
3 changed files with 119 additions and 313 deletions
Download Patch File Download Diff File Expand all files Collapse all files

112
docs/integrations/distributor/pkg-bundle.md
View File

@@ -1,92 +1,36 @@
# `pkg/bundle`
# Distributor Source Bundle Mapping
Audience: upstream Go producer developers and LLM coding agents using `distributor` source bundle helpers.
Weatherreporter uses the source-bundle format through Distributor's
`pkg/upload.UploadFiles` helper. It does not create bundle directories or call
`pkg/bundle` directly. The helper creates a temporary bundle, writes and
validates `manifest.json`, archives it, and removes the temporary bundle when
the upload call returns.
Import path:
## File Mappings
```go
import "gitea.maximumdirect.net/eric/distributor/pkg/bundle"
```
Every mapping pairs a managed Markdown report source with one bundle-relative
path. A single-report notification maps its one managed report to each rendered
path configured for that report. A batch notification combines mappings for
every included managed report and rejects duplicate bundle paths.
`pkg/bundle` builds, writes, parses, and validates local source bundles. Use it directly when a producer writes bundles for `distributor` to discover, or when a producer wants to assemble and validate a bundle before using another transport.
The report source is never an `--out` copy or an arbitrary workspace scan. The
application selects it and renders notification paths; see the [operations guide](../../operations.md)
for the managed-upload rule and the [Distributor adapter](../../internal/distributor-adapter.md)
for the adapter boundary.
The canonical source bundle file-format contract is
`docs/integrations/source-bundle.md` in the Distributor repository.
Bundle paths must be clean, relative, slash-separated paths. They cannot be
empty or absolute, contain backslashes, empty segments, `.` or `..`, or use
`manifest.json` or `.distributor.json` as a basename. The mapped source must be
a regular file. File mapping order is preserved and affects the bundle digest.
## Preferred Complete-Bundle Workflow
The bundle manifest uses schema version `1`, carries the rendered bundle ID and
creation time, and records each mapped file's path, SHA-256 digest, and size.
Destination routing, publication, and Distributor-managed destination state are
not source-bundle fields.
Use `WriteBundle` when producer-generated files live outside the final bundle root.
## Compatibility Reference
```go
manifest, err := bundle.WriteBundle(bundle.WriteBundleOptions{
Root: "/var/spool/distributor/weather/hourly-2026-06-07T15",
ID: "weather.hourly.brentwood",
Files: []bundle.BundleFile{
{SourcePath: "/tmp/weather/report.md", Path: "report.md"},
{SourcePath: "/tmp/weather/summary.txt", Path: "summary.txt"},
},
})
if err != nil {
return err
}
_ = manifest
```
`WriteBundle` copies each source file into a staged bundle root, writes `manifest.json`, validates the staged bundle, and promotes it into place. Set `Overwrite: true` only when the producer intentionally replaces an existing bundle root.
## Existing Bundle Root Workflow
Use `BuildManifest` and `WriteManifest` when files are already staged under the final bundle root.
```go
root := "/var/spool/distributor/weather/hourly-2026-06-07T15"
manifest, err := bundle.BuildManifest(bundle.BuildOptions{
Root: root,
ID: "weather.hourly.brentwood",
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
}
```
Use `Scan: true` instead of `Files` only when every valid regular file under the root should be included. Scan mode includes dotfiles, skips reserved metadata files, rejects symlinks, and sorts paths lexically.
## Paths And Ordering
Bundle paths are slash-separated paths relative to the bundle root.
Invalid paths include:
- empty paths;
- absolute paths;
- paths containing backslashes;
- `.` or `..` path segments;
- empty path segments;
- any reserved basename, including `manifest.json` and the distributor sidecar
basename formed from a leading dot plus `distributor.json`.
Explicit file lists preserve caller order. File order is part of the bundle digest, so producers should choose it deliberately and keep it stable.
The manifest `ID` is the logical source identity used by `distributor` destination comparison. Keep it stable for runs that should replace the same managed destination artifact. If every run uses a different manifest `ID`, `distributor` treats those runs as different sources and may report a destination conflict instead of replacing older output.
## Validation And Digest Helpers
Use `ValidateBundle` before handing an existing local bundle to another process. It verifies manifest semantics, file existence, regular-file type, file size, per-file SHA-256 digests, and bundle digest.
Useful helpers:
- `LoadManifest`: read `manifest.json` from a bundle root.
- `ParseManifest` and `MarshalManifest`: parse or write manifest bytes.
- `ValidateManifest`: validate manifest-only semantics.
- `FileDigest`, `BundleDigest`, and `ValidateDigest`: digest helpers for diagnostics and tests.
## Boundaries
`pkg/bundle` does not upload bundles, publish destinations, transform Markdown, select pipelines, configure credentials, or write destination state. Those concerns belong to `pkg/upload` or the `distributor` application.
The upstream canonical file-format contract is
`docs/integrations/source-bundle.md` in the Distributor repository. It defines
the complete manifest and archive format; this page records only the mapping and
path constraints Weatherreporter relies on.