Add a maintenance-only runtime role
- Dominant language
- Rust
- Stars
- 32
- Forks
- 5
- Avg merge
- 15h 21m
- Merged PRs (30d)
- 21
Description
## Context
Callback-only ingress does not replace the runtime work that keeps time-based state moving. If no Awa runtime performs maintenance, scheduled/retryable jobs may not promote, stale heartbeats may not rescue, expired callbacks may remain parked, and storage hygiene may drift.
ADR-028 proposes a persistent maintenance-only role that runs maintenance loops and leader election without claiming or executing ordinary jobs.
Related design draft: #277. Related existing work: #242 for isolating user-visible maintenance lanes from background hygiene, and #118 for bounded scale-to-zero `tick()` exploration.
## Proposed work
Add a maintenance-only runtime mode that can be used from both library and CLI entry points.
Potential library shape:
```rust
Client::builder(pool)
.maintenance_only()
.build()?
.run()
.await?;
```
Potential CLI shape:
```text
awa maintenance run
```
The library form can include code-owned declarations registered on `ClientBuilder`. The pool-only CLI form should only run maintenance that does not require application declarations.
## Acceptance criteria
- Maintenance-only mode does not claim available jobs.
- It does not invoke Rust/Python user handlers.
- It does not dispatch `HttpWorker` calls.
- It runs the relevant maintenance lanes: scheduled/retry promotion, stale heartbeat rescue, deadline rescue, callback rescue, queue-storage rotation/pruning, cleanup, admin metadata refresh, and runtime liveness for the maintenance process.
- It preserves the existing maintenance leader-election and shutdown/cancellation semantics.
- Tests cover that maintenance-only does not claim/execute jobs while still running at least one promotion/rescue path.
- Docs explicitly distinguish maintenance-only from a worker/dispatcher.
- The implementation composes with #242 rather than baking in another monolithic maintenance loop.
Contributor guide
No contributing guide indexed for this repository
Assessment
This issue has not been assessed yet.