# ADR-003: Checkable Interface

**Status:** Accepted
**Date:** 2026-03-18

## Context

The health handler needs to interrogate arbitrary infrastructure components without knowing their concrete types. The options were:

1. Pass `func(ctx context.Context) error` callbacks directly.
2. Require a shared `Checkable` interface that infrastructure modules must implement.
3. Accept an external registry where components register themselves by name.

The health module also needs a way to know what to call a component in the JSON output (`name`) and how to treat its failure (`priority`). Without these pieces of metadata, every caller would have to pass them as separate arguments alongside the check function.

## Decision

A `Checkable` interface is defined in the `health` package with three methods:

```go
type Checkable interface {
    HealthCheck(ctx context.Context) error
    Name() string
    Priority() Level
}
```

Infrastructure modules (`postgres`, `mysql`, etc.) embed `health.Checkable` in their own `Component` interface and implement all three methods. The `health` package does not import any infrastructure module — the dependency flows inward only: infra → health.

`Name()` returns a stable string used as the JSON key in the `components` map. `Priority()` returns the `Level` value that governs the HTTP status code logic (ADR-002). `HealthCheck(ctx)` performs the actual probe (e.g., `pool.Ping(ctx)`).

The handler accepts `...Checkable` as a variadic parameter, so callers can register zero or more components at construction time. No dynamic registration or remove-after-register is supported.

## Consequences

- **Positive**: Infrastructure components carry their own health metadata — no out-of-band registration with name strings and level constants at the call site.
- **Positive**: Compile-time safety: if a component does not implement all three methods, the assignment `var _ health.Checkable = myComponent{}` fails.
- **Positive**: The interface is minimal (three methods) and stable; adding a fourth method would be a breaking change and should be versioned.
- **Negative**: Any new type that wants to participate in health checking must implement three methods, not just a single function. For trivial cases (one-off checks) this is more boilerplate than a bare function callback. However, the named interface is preferred because metadata (`Name`, `Priority`) cannot be forgotten.