healthx

type CheckFunc ¶

type CheckFunc func(context.Context) error

CheckFunc is the ergonomic adapter for normal error-returning checks.

func (f CheckFunc) Check(ctx context.Context) Result

type Checker ¶

type Checker interface {
	Check(context.Context) Result
}

Checker supports checks that need pass/warn/fail control.

type Lifecycle ¶

type Lifecycle uint32

Lifecycle is the Manager's coarse operating state (docs §5, §7).

const (
	LifecycleStarting Lifecycle = iota
	LifecycleRunning
	LifecycleDraining
	LifecycleStopped
)

type Manager ¶

type Manager struct {
	// contains filtered or unexported fields
}

Manager owns the matched set of health checks plus their execution and lifecycle state, and backs the /livez, /readyz, and /startupz probe dispatch. All methods are nil-receiver safe so a disabled subsystem (New returning a nil *Manager) is a legal, inert value callers can use without a nil check at every call site.

func New(cfg *configx.HealthConfig, regs []Registration, opts ...Option) (*Manager, error)

func (m *Manager) BeginDrain()

func (m *Manager) Dispatch(app http.Handler) http.Handler

func (m *Manager) DrainDelay() time.Duration

func (m *Manager) Evaluate(ctx context.Context, probe Probe) ProbeResult

func (m *Manager) ReservePaths(mux *http.ServeMux)

func (m *Manager) ShutdownTimeout() time.Duration

func (m *Manager) Stop()

type Option ¶

type Option func(*Manager)

Option configures a Manager at construction time.

func WithLogger(l *slog.Logger) Option

func WithMetrics(m obsx.MetricsProvider) Option

type Probe ¶

type Probe string

Probe identifies one of the three generated probe endpoints (see docs/HEALTH_CHECK_ENHANCEMENT.md §2 and §6).

const (
	ProbeLiveness  Probe = "liveness"
	ProbeReadiness Probe = "readiness"
	ProbeStartup   Probe = "startup"
)

type ProbeResult ¶

type ProbeResult struct {
	Status   Status
	Probe    Probe
	Duration time.Duration
	Total    int
	Passed   int
	Warned   int
	Failed   int
}

ProbeResult is the aggregated outcome of evaluating one probe. It is the data source for the §8 public response shape (docs/HEALTH_CHECK_ENHANCEMENT.md): it carries the overall Status, the probe it describes, the wall-clock Duration of the evaluation, and the pass/warn/fail summary counts — but never the names of individual checks, which would disclose architecture on an unauthenticated endpoint (§8).

type Reason ¶

type Reason string

Reason further qualifies a non-pass Status. This is the closed value space for apic_health_check_total's reason label (docs/OBSERVABILITY.md): every value here must be reachable on that metric, or be removed from both this enum and that doc together (GAP-0101). The check-outcome metric (and the transition logs) are emitted exclusively by invoke() on a real check completion, whose hook runs on a context.Background()-rooted context bounded by the per-check timeout — so the only cancellation it can ever observe is its own deadline (context.DeadlineExceeded -> ReasonTimeout), never a caller's cancellation. Hence the five reasons below are the complete set.

ReasonCanceled/ReasonStarting/ReasonDraining were previously declared here with no reachable emission and have been removed:

• canceled: a caller canceling its probe (client/LB disconnect, a kubelet probe timeout shorter than the check budget, shutdown) is NOT a check outcome. runCheck's give-up branch returns fail without emitting any check metric or log — the still-running invoke() emits the real outcome once — so "canceled" could only ever reach the metric by double-counting (a spurious second emission on top of the real one), which is exactly the regression this removal closes. A canceled probe surfaces at the probe level (apic_health_probe_total{status=fail}), not as a per-check reason.
• starting/draining: probe-level lifecycle states, not per-check reasons. evaluateReadiness's Draining/Stopped branches short-circuit to a bare ProbeResult{Status: StatusFail} without running any check. A not-yet- latched Starting DOES run its startup checks (via ensureStartupLatched -> evaluateChecks), but each reports its OWN real reason (pass/error/ timeout/panic/busy), never "starting". Draining is signaled via ProbeResult.Status and the readiness_state_changed/server_draining logs.

const (
	ReasonNone    Reason = ""
	ReasonError   Reason = "error"
	ReasonTimeout Reason = "timeout"
	ReasonPanic   Reason = "panic"
	ReasonBusy    Reason = "busy"
)

type Registration ¶

type Registration struct {
	Name    string
	Checker Checker
}

Registration binds a declared health.checks name (see docs/HEALTH_CHECK_ENHANCEMENT.md §2) to the Checker implementation a service provides at startup via WithHealthCheck/WithHealthChecker.

type Result ¶

type Result struct {
	Status Status
	Reason Reason
}

Result is the outcome of one Checker invocation.

type Status ¶

type Status string

Status is the outcome of a single check invocation, using the pass/warn/fail vocabulary of the (expired) IETF health+json draft as a compatibility convention rather than a standards guarantee.

const (
	StatusPass Status = "pass"
	StatusWarn Status = "warn"
	StatusFail Status = "fail"
)