Capacity & Certificate Probes

These probes exist to catch two specific failure modes that traditional liveness checks miss entirely: a node that's still technically running but is about to run out of disk, and a certificate that's about to expire on a schedule nobody's watching.

Capacity probes

AbstractCapacityProbe defines a tri-state response: below warnPct is healthy, between warnPct and criticalPct degrades readiness (the node stops receiving new traffic but keeps running), and at or above criticalPct fails outright.

final class DiskCapacityProbe extends AbstractCapacityProbe
{
    public function __construct(
        CapacityReaderInterface $reader,
        string $path = '/',
        float $warnPct = 85.0,
        float $criticalPct = 95.0,
    ) {}
}

curl http://localhost:8000/health/ready

{
  "status": "degraded",
  "checks": {
    "disk-capacity": { "status": "warn", "used_pct": 87.3 }
  }
}

Three drivers ship: DiskCapacityProbe, MemoryCapacityProbe, and CpuLoadProbe — all reading through CapacityReaderInterface, with ProcCapacityReader as the real /proc-backed implementation and InMemoryCapacityReader for tests.

< warnPct           → ProbeStatus::Pass
[warnPct, criticalPct) → ProbeStatus::Warn   — drains the node from the load balancer
>= criticalPct       → ProbeStatus::Fail   — out of rotation entirely

warnPct must be strictly less than criticalPct, both must be in (0, 100] — enforced at construction. An unreadable capacity value (the /proc read fails) reports Warn with capacity_unreadable rather than Pass — an unknown reading is never silently treated as "fine."

Certificate expiry probe

CertExpiryProbe inspects a live TLS connection's certificate and reports based on days remaining until expiry. It declares ProbeKind::Monitoring, so it runs only on /health/monitor — never on /health/ready:

new CertExpiryProbe(
    inspector: new StreamCertInspector(),
    host: 'api.example.com',
    port: 443,
    thresholds: new CertExpiryThresholds(warnDays: 14, secondWarnDays: 7, criticalDays: 1),
);

final readonly class CertExpiryThresholds
{
    public function statusFor(int $daysUntilExpiry): ProbeStatus
    {
        if ($daysUntilExpiry <= $this->criticalDays) return ProbeStatus::Fail;
        if ($daysUntilExpiry <= $this->warnDays) return ProbeStatus::Warn;
        return ProbeStatus::Pass;
    }
}

The thresholds are graduated deliberately: a 14-day warning is meant to be the first nudge to renew, not an emergency. Only the final day before expiry escalates to Fail — certificate renewal is a routine, proactive task, and these thresholds are built so it stays one. Construction enforces criticalDays < secondWarnDays < warnDays, so a misconfigured threshold set (e.g. a critical window longer than the warning window) fails immediately rather than producing a confusing alert ordering later.

StreamCertInspector performs the actual TLS handshake and certificate read; InMemoryCertInspector is the test double for exercising threshold logic without a real socket.