docs: add a Role in the framework section to every module README

Each module README now says where the module sits in the dependency
graph, why it is its own module, and lists use cases for application
developers.
This commit is contained in:
2026-10-11 00:58:17 +02:00
parent 87953f68bf
commit 602e0412f3
24 changed files with 240 additions and 0 deletions

View File

@@ -14,6 +14,16 @@ Every River client runs on the one `*sql.DB` pool that `lagoon` opens. A worker
The scheduler is the Go form of WinterCMS `registerSchedule`. Plugins declare recurring console commands through `pact.HasSchedule`; every worker turns them into River periodic jobs on wall-clock `conga.Daily` and `conga.Every` schedules in the `app.timezone` location. Each due run is a job on the `scheduled` queue that calls the command in-process through the app's `bonfire.Catalog`.
## Role in the framework
A service module over `lagoon`'s Postgres pool, using `backpack`, `pact`, `party`, `bouncer` and `bonfire`. `lighthouse` depends on it to send broadcasts as jobs, and `surf` runs its workers next to the HTTP server. Jobs are separate from the data layer because not every application runs workers, and the queue has its own lifecycle (dispatch, retry, schedule).
Use cases:
- Send mail, resize images or call slow external APIs outside the request.
- Dispatch a job in the same transaction as the write that caused it, so it never runs for a rolled-back change.
- Run scheduled work such as nightly cleanups, and show progress to users through the job record.
## Features
- River-free job declarations: `conga.Job` turns `func(ctx context.Context, args T) error` into a `pact.Job`; `conga.OnQueue`, `conga.MaxAttempts` and `conga.Timeout` set per-job defaults, which `conga.Describe` reports back for tests. A `pact.Job` not built by `conga.Job` is rejected with `conga.ErrNotCongaJob`.