Module liveness 

Liveness probes for provider plugins per ADR-021 §6 (“the validation framework”) and ADR-021 §9 (doctor integration — “current status: provisioned / expiring / missing / format-invalid”).

ADR-020’s format validator (epic phase P9.1) tells you a candidate value looks right. Liveness asks the upstream the harder question: does it actually work? Plugins implement LivenessProbe against their native auth-introspection endpoint (GitHub /user, GitLab /personal_access_tokens/self, …) and report a typed LivenessResult. The wider validation flow (P9.4 devboy secrets validate, P9.3 expiry tracking) consumes the result.

This module is the contract; concrete impls live in crates/plugins/api/{github,gitlab,…}.

Token argument

test(&self, token: &SecretString) deliberately takes the token as a parameter rather than reading from self. The validate flow may want to test a candidate token before storing it — see also the format validator’s same pattern (it takes the value, not the path).

Variants

• LivenessStatus::Live: token authenticated and the upstream returned account info.
• LivenessStatus::Revoked: token was rejected as permanently invalid (401 with revoke semantics, or 403 on a probe endpoint that the token previously had access to).
• LivenessStatus::Expired: token was rejected because it had a hard expiration (mostly GitLab personal-access-tokens with expires_at < today).
• LivenessStatus::Throttled: probe hit a 429. Caller may retry later; the result is inconclusive.
• LivenessStatus::NotImplemented: the provider plugin has no native introspection (or hasn’t been wired yet). The shared default in this module returns this; concrete plugins override.
• LivenessStatus::Error: anything else (network failure, non-JSON body, unexpected 5xx). The detail field carries the message.

Structs

LivenessResult

Outcome of LivenessProbe::test.

Enums

LivenessStatus

What the upstream said about a probed token.

Traits

LivenessProbe

Liveness probe a provider plugin implements against its native introspection endpoint. The test method is async because it does network I/O.