Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Health Check System

Since: v0.2.0+ (yanshi-core::health); real /health/ready wiring since W5.3 Status: Production-ready, intentionally minimal

Overview

yanshi-core::health::HealthChecker is a small registry of named async checks that fold into an overall healthy/unhealthy verdict. It has no built-in checks, no metadata, no metrics, and no timestamps — it is deliberately just enough to answer “is this dependency reachable right now?” Callers register whatever checks matter to them.

yanshi-server is the one real consumer today: GET /health/ready builds a HealthChecker, registers a "database" check that runs SELECT 1 against the primary read pool, and returns 503 with the per-check results when it fails.

API

#![allow(unused)]
fn main() {
pub enum HealthStatus {
  Healthy,
  Degraded,
  Unhealthy,
}

pub struct HealthCheckResult {
  pub name: String,
  pub status: HealthStatus,
  pub message: Option<String>,
}

pub struct HealthReport {
  pub is_healthy: bool,
  pub checks: Vec<HealthCheckResult>,
}

pub struct HealthChecker { /* ... */ }

impl HealthChecker {
  pub fn new() -> Self;

  pub async fn add_check<F>(&self, name: impl Into<String>, check: F)
  where
    F: Fn() -> Pin<Box<dyn Future<Output = yanshi_core::Result<HealthStatus>> + Send>>
       + Send + Sync + 'static;

  pub async fn check_health(&self) -> HealthReport;
}
}

That is the entire surface. add_check’s closure returns yanshi_core::Result<HealthStatus> (i.e. Result<HealthStatus, YanshiError>) — an Err is folded into HealthStatus::Unhealthy with the error’s Display output as the message. HealthReport::is_healthy is true iff no registered check resolved to Unhealthy (a Degraded check still counts as healthy for this aggregate — callers that want stricter readiness semantics should inspect checks directly).

There is no remove_check, no set_metadata, no built-in add_memory_check/add_metrics_check, and HealthReport has no status() method or timestamp/metadata fields. Earlier drafts of this document described a larger surface that was never implemented — this revision matches the real 79-line yanshi-core/src/health.rs.

Usage

#![allow(unused)]
fn main() {
use yanshi_core::{YanshiError, HealthChecker, HealthStatus};

let checker = HealthChecker::new();
let pool = my_pg_pool.clone();
checker
  .add_check("database", move || {
    let pool = pool.clone();
    Box::pin(async move {
      sqlx::query("SELECT 1")
        .execute(&pool)
        .await
        .map(|_| HealthStatus::Healthy)
        .map_err(|e| YanshiError::NetworkError {
          message: format!("database readiness check failed: {e}"),
        })
    })
  })
  .await;

let report = checker.check_health().await;
if !report.is_healthy {
  for check in &report.checks {
    tracing::warn!(name = %check.name, status = ?check.status, "unhealthy dependency");
  }
}
}

yanshi-server’s /health* routes

RouteBehaviorK8s probe convention
GET /healthUnconditional 200 {"status":"ok","service":"yanshi-server"}.Generic health check
GET /health/liveSame unconditional 200 as /health.Liveness — must never depend on dependencies
GET /health/readyBuilds a HealthChecker, runs the "database" SELECT 1 check, 200 if healthy else 503.Readiness — should reflect real dependencies

/health and /health/live deliberately stay unconditional per the standard Kubernetes convention: a liveness probe that depends on an external service (the database) causes cascading restarts when that service degrades, which is exactly the failure mode liveness probes exist to avoid. Only readiness should gate traffic on dependency health.

A 503 response body from /health/ready looks like:

{
  "status": "unhealthy",
  "service": "yanshi-server",
  "checks": [
    { "name": "database", "status": "unhealthy", "message": "database readiness check failed: ..." }
  ]
}

All three routes are unauthenticated (same convention as /metrics) so orchestrator/load-balancer probes don’t need a bearer token.

See Also


Last Updated: 2026-08-12 (W5.3 — rewritten to match the real API and document the /health/ready database check; the previous revision described add_memory_check/add_metrics_check/report.status()/ set_metadata, none of which exist in yanshi-core::health)