Module lifecycle 

Service lifecycle state machine.

Each service managed by the Supervisor progresses through a well-defined set of states:

  ┌──────────┐
  │ Starting │──────────────────────────┐
  └────┬─────┘                          │
       │ run() entered                  │ init error
       ▼                                ▼
  ┌──────────┐                    ┌────────────┐
  │ Running  │───── error ──────▶│ BackingOff │
  └────┬─────┘                    └──────┬─────┘
       │                                 │
       │ cancel / Ok(())                 │ retry
       │                                 │
       │    ┌────────────────────────────┘
       ▼    ▼
  ┌──────────┐         ┌────────────┐
  │ Stopping │────────▶│ Terminated │
  └──────────┘         └────────────┘

• Starting: the service is initializing.
• Running: the service’s run() loop is active.
• BackingOff: the service failed and is waiting for the backoff timer before the supervisor retries.
• Stopping: a cancellation signal was received; the service is finalizing.
• Terminated: terminal state — the service has exited (or the circuit breaker tripped and the supervisor gave up).

The BackingOff state prevents the supervisor from tight-looping on a persistent failure, which would burn CPU and flood logs.

Structs

ServiceLifecycle

Full lifecycle tracker for a single supervised service.

ServiceLifecycleSnapshot

Point-in-time snapshot of a service’s lifecycle, suitable for serialization (e.g., for a /health JSON endpoint).

TransitionError

Error returned when an invalid state transition is attempted.

Enums

ServicePhase

Lifecycle phase of a supervised service.

TerminationReason

Why a service reached the Terminated phase.