Skip to main content

The handler exposes the embedded dashboard, /healthz, /readyz, /metrics, and JSON routes under /api. It supports job filtering, cancel/delete/retry/ reschedule, queue pause/resume, and per-state queue counts. Redis uses a migrated created-at index and DynamoDB uses its queue/state GSI for scoped reads. Unscoped DynamoDB reads and Cassandra/Firestore administrative paths still scan records and are intended for moderate operational use rather than high-frequency scraping.

The default JSON representation removes job arguments, unique keys, and panic stack traces. Use admin.WithJobRedactor only when an application has a safe, explicit policy for exposing or replacing those fields. admin.WithReadOnly(true) disables every mutation while retaining inspection and metrics. The authorization hook receives separate dashboard, read, mutate, metrics, and health operations; return admin.ErrUnauthenticated for HTTP 401 and any other error for HTTP 403.

/healthz is a process liveness probe and does not touch storage. /readyz checks that the backing driver can answer a query and returns HTTP 503 when it cannot. Metrics are buffered until all queue statistics have been collected, so a collection failure returns 503 without a misleading partial Prometheus body.

To serve futures metrics from the same endpoint, aggregate them with future.NewMetrics and pass it to admin.WithMetrics (any value with WritePrometheus(io.Writer) error works):

MetricTypeLabels
goncordia_future_awaits_in_flightgauge—
goncordia_future_await_duration_secondshistogramkind, outcome
goncordia_future_await_polls_totalcounterkind
goncordia_future_await_wakeups_totalcounterkind
goncordia_future_store_duration_secondshistogramkind, status
goncordia_future_result_size_byteshistogramkind

These values describe the process that runs the Manager: awaits are counted where producers wait, stores where workers run. Expose the admin handler in each instance and let Prometheus aggregate. Queue gauges, by contrast, come from storage and are the same in every instance. The embedded dashboard serves script and style assets separately under a strict Content Security Policy.

Every mutation requires X-Goncordia-Confirm to exactly match the action name (pause, resume, cancel, delete, retry, or reschedule). This is an additional guard against accidental requests, not a substitute for authorization:

GET /api/jobs and GET /api/queues return a page envelope:

Pass next_cursor back as the cursor query parameter. Cursors are opaque and versioned; callers must not parse or construct them. Job cursors preserve the stable created_at DESC, id DESC order, including ties, and queue cursors use queue-name order. Invalid cursors return HTTP 400. Driver errors map consistently: not found to 404, conflict or stale claim to 409, and unsupported operations to 501. Applications can classify the same errors with errors.Is and driver.ErrNotFound, driver.ErrConflict, driver.ErrStaleClaim, driver.ErrUnsupported, or driver.ErrInvalidCursor.