65 lines
3.3 KiB
Markdown
65 lines
3.3 KiB
Markdown
# Application Orchestration
|
|
|
|
## Purpose
|
|
|
|
`internal/app` owns top-level use cases for `run`, `validate`, and `inspect`. It wires configuration, storage backends, transforms, publish planning, execution, summaries, and notification handoff.
|
|
|
|
## Inputs and outputs
|
|
|
|
`Run` accepts a context, optional config path, dry-run flag, stdout writer, and optional notifier. It loads YAML config, discovers source bundles for each configured pipeline, plans each destination independently, optionally executes publish plans, writes summary output when stdout is supplied, and returns an aggregated error if any destination fails.
|
|
|
|
`Validate` and `Inspect` accept a local path. `Validate` discovers and validates bundles. `Inspect` writes bundle metadata and manifest file entries to stdout when provided.
|
|
|
|
## Run flow
|
|
|
|
The runner:
|
|
|
|
1. loads config from the supplied path or `config.DefaultConfigPath`;
|
|
2. opens the configured source backend;
|
|
3. discovers validated bundles from the source root;
|
|
4. opens each destination backend independently;
|
|
5. builds a publish plan for each bundle and destination;
|
|
6. prints plan lines and records summary counters;
|
|
7. executes publish or replacement plans unless dry-run is enabled;
|
|
8. invokes the notifier after successful publish or replacement actions.
|
|
|
|
Destination failures are collected while later destinations continue to run. Source open and source discovery failures stop the run because there are no valid bundles to fan out.
|
|
|
|
## Backend and transform wiring
|
|
|
|
The app-level backend factory registers only the local backend for execution. Config validation accepts other backend shapes, but `Run` can execute only local sources and local destinations.
|
|
|
|
The app-level transform registry registers Markdown-to-HTML using `internal/transform/markdown`. Lower-level publish code receives a resolver and does not import concrete transform implementations.
|
|
|
|
## Dry-run behavior
|
|
|
|
Dry-run still loads config, opens backends, discovers bundles, inspects destinations, resolves transforms, and builds publish plans. It does not write destination outputs, write `.distributor.json`, delete managed outputs, or notify.
|
|
|
|
## Failure behavior
|
|
|
|
`Run` returns immediately for config loading errors, context cancellation before work starts, source open errors, and source discovery errors. Per-destination backend, planning, execution, and notification errors are aggregated into one run error after remaining destinations have been attempted.
|
|
|
|
Stdout write errors are returned immediately because the caller's requested output stream can no longer be trusted.
|
|
|
|
## Boundaries
|
|
|
|
`internal/app` coordinates packages but does not own manifest validation rules, destination state comparison, storage path rules, output planning, transform rendering, or backend-specific filesystem behavior.
|
|
|
|
`Validate` and `Inspect` are local path commands. Remote execution wiring is outside current behavior.
|
|
|
|
## Tests
|
|
|
|
Before changing app orchestration, inspect tests under:
|
|
|
|
- `internal/app`
|
|
- `internal/cli`
|
|
- `internal/publish`
|
|
|
|
## Invariants
|
|
|
|
- One source fans out to each destination independently.
|
|
- Destination failures do not prevent later destinations from being planned.
|
|
- Dry-run must not mutate destination storage or invoke notifications.
|
|
- Concrete backend and transform registration stays at the app layer.
|
|
- The default notifier is `notify.Noop`.
|