hardbyte / hardbyte/awa

Add a maintenance-only runtime role

Open
#282 0 comments 0 reactions 0 assignees View on GitHub
feature operational
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.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.