Document batch distributor uploads
This commit is contained in:
@@ -57,12 +57,14 @@ batch before any report is generated.
|
||||
|
||||
After planning succeeds, batch commands print a JSON summary to stdout, write
|
||||
compact per-report status lines to stderr, continue independent reports after
|
||||
one report fails, and return nonzero when any report failed. When notification
|
||||
is configured, the summary and status lines include notification status,
|
||||
accepted distributor run ID, or notification error fields for each attempted
|
||||
report. `--out-dir PATH` writes extra Markdown copies using report default
|
||||
filenames such as `today.md` and `tomorrow.md`; dynamic Daily copies use
|
||||
`daily-YYYY-MM-DD.md`. These copies are not used as distributor upload sources.
|
||||
one report fails, and return nonzero when any report failed. Batch commands do
|
||||
not upload each report independently. When distributor notification and batch
|
||||
notification are enabled, weatherreporter uploads one distributor bundle only
|
||||
after every planned report succeeds. If any report fails, the batch upload is
|
||||
skipped for the whole batch. `--out-dir PATH` writes extra Markdown copies
|
||||
using report default filenames such as `today.md` and `tomorrow.md`; dynamic
|
||||
Daily copies use `daily-YYYY-MM-DD.md`. These copies are not used as
|
||||
distributor upload sources.
|
||||
|
||||
## Filesystem Layout
|
||||
|
||||
@@ -160,6 +162,13 @@ workspace/
|
||||
YYYY-MM-DD/
|
||||
<run_id>.render.json
|
||||
notifications/
|
||||
batches/
|
||||
morning/
|
||||
YYYY-MM-DD/
|
||||
<batch_run_id>.distributor.json
|
||||
evening/
|
||||
YYYY-MM-DD/
|
||||
<batch_run_id>.distributor.json
|
||||
daily/
|
||||
YYYY-MM-DD/
|
||||
<run_id>.distributor.json
|
||||
@@ -206,14 +215,21 @@ period do not overwrite each other.
|
||||
RunIDs are based on generation time plus report ID. Reports that can be
|
||||
generated more than once in a single command may append a report-specific
|
||||
disambiguator. Daily appends the local valid date so multiple dynamic Daily
|
||||
reports in one batch have distinct managed artifacts and notification
|
||||
idempotency keys:
|
||||
reports in one batch have distinct managed artifacts:
|
||||
|
||||
```text
|
||||
20260529T100000.123456789Z_daily_2026-05-31
|
||||
20260529T100000.123456789Z_today
|
||||
```
|
||||
|
||||
Batch notification RunIDs use the batch start timestamp plus the batch command
|
||||
name:
|
||||
|
||||
```text
|
||||
20260529T100000.123456789Z_morning
|
||||
20260529T220000.123456789Z_evening
|
||||
```
|
||||
|
||||
Each generated report writes metadata that links:
|
||||
|
||||
- RunID, report ID, variant, and prompt ID
|
||||
@@ -227,19 +243,33 @@ Each generated report writes metadata that links:
|
||||
generated-text-template reports
|
||||
- distributor notification debug artifact path, when notification is attempted
|
||||
|
||||
Batch summaries include report status, error text when applicable, notification
|
||||
outcome when attempted, valid period, and known artifact paths for each
|
||||
attempted report. Notification fields are `notificationStatus`,
|
||||
`notificationRunId`, and `notificationError`.
|
||||
Batch summaries include report status, error text when applicable, valid
|
||||
period, and known artifact paths for each attempted report. Single-report
|
||||
notification fields on report items are empty for batch commands. When a batch
|
||||
notification is attempted, skipped, or fails, the summary includes one
|
||||
top-level `notification` object with fields such as `status`, `reason`,
|
||||
`runId`, `pipelineId`, `bundleId`, `idempotencyKey`, `path`,
|
||||
`includedReports`, and `error`.
|
||||
|
||||
## Distributor Notification
|
||||
|
||||
Distributor notification is configured with `notify.distributor` and is
|
||||
disabled by default. When enabled, weatherreporter uploads the managed Markdown
|
||||
report path recorded in the report result and metadata. That single source file
|
||||
can be mapped to one or more configured bundle paths. By default, it is mapped
|
||||
to one dated report path. Extra copies written by `--out` or `--out-dir` are
|
||||
operator conveniences only.
|
||||
disabled by default. For `generate <report>`, weatherreporter uploads the
|
||||
managed Markdown report path recorded in the report result and metadata. That
|
||||
single source file can be mapped to one or more configured bundle paths. By
|
||||
default, it is mapped to one dated report path. Extra copies written by `--out`
|
||||
or `--out-dir` are operator conveniences only.
|
||||
|
||||
For `run morning` and `run evening`, per-report notification is suppressed. If
|
||||
`notify.distributor.enabled` and `notify.distributor.batch.enabled` are both
|
||||
true, the batch uploads once after all reports finish successfully. The upload
|
||||
contains one file mapping set per included report. Each mapping uses the
|
||||
managed Markdown report as the source and renders `report_path_templates` using
|
||||
that report's normal template values. All rendered bundle paths across the
|
||||
batch must be unique. If any report fails, weatherreporter records a top-level
|
||||
notification status of `skipped` with reason `one or more reports failed` and
|
||||
does not call distributor. If batch notification is disabled, run commands do
|
||||
not fall back to per-report uploads.
|
||||
|
||||
The rendered pipeline ID selects the configured distributor `http_upload`
|
||||
workflow. The default bundle ID is a stable logical source identity derived from
|
||||
@@ -249,31 +279,40 @@ producer name, location ID, and report ID:
|
||||
weatherreporter.{location_id}.{report_id}
|
||||
```
|
||||
|
||||
The default idempotency key appends RunID to the rendered bundle ID so each
|
||||
report generation has a distinct retry identity. The default bundle path uses
|
||||
the valid-period start date, artifact group, and RunID. Distributor owns
|
||||
destination merge, retention, and derived snapshot behavior such as `latest`.
|
||||
For Daily, the default report ID and artifact group values are both `daily`,
|
||||
and the default output filename value is `daily.md`.
|
||||
For Today, the default report ID and artifact group values are both `today`,
|
||||
and the batch output filename value is `today.md`.
|
||||
The default single-report idempotency key appends RunID to the rendered bundle
|
||||
ID so each report generation has a distinct retry identity. The default bundle
|
||||
path uses the valid-period start date, artifact group, and RunID. Batch bundle
|
||||
IDs default to `weatherreporter.{location_id}.{batch}`, and batch idempotency
|
||||
keys default to `{bundle_id}.{batch_run_id}`. Distributor owns destination
|
||||
merge, retention, and derived snapshot behavior such as `latest`. For Daily,
|
||||
the default report ID and artifact group values are both `daily`, and the
|
||||
default output filename value is `daily.md`. For Today, the default report ID
|
||||
and artifact group values are both `today`, and the batch output filename value
|
||||
is `today.md`.
|
||||
|
||||
Notification happens after final metadata save for generated reports.
|
||||
Collection, module snapshot, data-package, render preflight, Scriptorium run,
|
||||
generated-text validation, template rendering, and metadata-save failures do
|
||||
not trigger notification. A notification failure fails that report.
|
||||
In a batch, other reports continue, the failed report includes notification
|
||||
fields in the JSON summary, and the batch returns nonzero.
|
||||
Single-report notification happens after final metadata save for generated
|
||||
reports. Batch notification happens after all planned reports have finished and
|
||||
only when all report generations succeeded. Collection, module snapshot,
|
||||
data-package, render preflight, Scriptorium run, generated-text validation,
|
||||
template rendering, and metadata-save failures do not trigger notification. A
|
||||
single-report notification failure fails that report. A batch notification
|
||||
failure makes the batch return nonzero and increments the aggregate failure
|
||||
count, but individual report items remain succeeded.
|
||||
|
||||
Each notification attempt writes a debug artifact under `notifications/`. The
|
||||
artifact records the rendered pipeline ID, bundle ID, idempotency key, managed
|
||||
source path, bundle-relative paths, bundle created timestamp, accepted upload
|
||||
response, and the latest distributor run status response when available.
|
||||
Weatherreporter polls status until distributor reports `succeeded` or `failed`,
|
||||
or until the configured notification timeout expires. The run status includes
|
||||
the distributor status, error text, and raw run report JSON, which can show
|
||||
actions such as `replace_older`, `skip_same`, `skip_destination_newer`, or
|
||||
`failed`. Token values are not written.
|
||||
Each notification attempt writes a debug artifact under `notifications/`.
|
||||
Single-report artifacts live under
|
||||
`notifications/<artifact_group>/<YYYY-MM-DD>/<run_id>.distributor.json`. Batch
|
||||
artifacts live under
|
||||
`notifications/batches/<batch>/<YYYY-MM-DD>/<batch_run_id>.distributor.json`,
|
||||
where the date directory is the batch start date in the effective report
|
||||
timezone. The artifact records the rendered pipeline ID, bundle ID,
|
||||
idempotency key, managed source paths, bundle-relative paths, bundle created
|
||||
timestamp, accepted upload response, and the latest distributor run status
|
||||
response when available. Weatherreporter polls status until distributor reports
|
||||
`succeeded` or `failed`, or until the configured notification timeout expires.
|
||||
The run status includes the distributor status, error text, and raw run report
|
||||
JSON, which can show actions such as `replace_older`, `skip_same`,
|
||||
`skip_destination_newer`, or `failed`. Token values are not written.
|
||||
|
||||
Weatherreporter is responsible for selecting the managed Markdown report,
|
||||
constructing a source bundle, and submitting it to the configured distributor
|
||||
@@ -333,10 +372,13 @@ A failed generation run may still leave useful artifacts:
|
||||
available intermediate artifacts, such as the structured run result, raw
|
||||
generated-text JSON, validated generated text, and render context. Metadata
|
||||
links those paths when it can be safely written.
|
||||
- If distributor notification fails, report artifacts and final metadata remain
|
||||
available, but the report or batch command returns nonzero.
|
||||
- If single-report distributor notification fails, report artifacts and final
|
||||
metadata remain available, but the report command returns nonzero.
|
||||
- If batch distributor notification fails, report artifacts and final metadata
|
||||
remain available, the top-level batch notification links the debug artifact,
|
||||
and the batch command returns nonzero.
|
||||
- For batch commands, inspect the stdout JSON summary first, then inspect the
|
||||
artifact paths for each failed report.
|
||||
artifact paths for each failed report or the top-level notification path.
|
||||
|
||||
For a bad report, start with:
|
||||
|
||||
|
||||
Reference in New Issue
Block a user