Skip to content

Add a maintenance-only runtime role #282

@hardbyte

Description

@hardbyte

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:

Client::builder(pool)
    .maintenance_only()
    .build()?
    .run()
    .await?;

Potential CLI shape:

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 Isolate user-visible maintenance lanes from background hygiene #242 rather than baking in another monolithic maintenance loop.

Metadata

Metadata

Assignees

No one assigned

    Labels

    featureNew functionalityoperationalOperational tooling and configuration

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions