From 56d51347b9e9ffa109925fc506a6f52d934edcdd Mon Sep 17 00:00:00 2001 From: Owen Date: Mon, 9 Nov 2026 22:24:09 +0100 Subject: [PATCH] Add JSON health check with database and tablebase status (#106) --- deploy/README.md | 4 ++ lib/chesstrainer/health.ex | 62 +++++++++++++++++++ .../controllers/health_controller.ex | 10 ++- .../controllers/health_controller_test.exs | 62 +++++++++++++++++++ 4 files changed, 135 insertions(+), 3 deletions(-) create mode 100644 lib/chesstrainer/health.ex create mode 100644 test/chesstrainer_web/controllers/health_controller_test.exs diff --git a/deploy/README.md b/deploy/README.md index 2804198..155372c 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -377,6 +377,10 @@ sudo journalctl -u chesstrainer -n 100 --no-pager curl -i http://127.0.0.1:4100/health ``` +`/health` returns JSON with `status`, `db`, `tablebase`, and `process`. +It returns 200 for `ok`/`degraded` and 503 for `down`. A missing local tablebase +reports `degraded` but still 200 because Lichess fallback is available. + ## Backups Take a logical backup of the production database: diff --git a/lib/chesstrainer/health.ex b/lib/chesstrainer/health.ex new file mode 100644 index 0000000..f5b396c --- /dev/null +++ b/lib/chesstrainer/health.ex @@ -0,0 +1,62 @@ +defmodule Chesstrainer.Health do + @moduledoc """ + Runtime health snapshot for deploy smoke tests and uptime monitors. + + The database is the only hard dependency. Tablebase status is informational: + local Syzygy files are preferred, but falling back to Lichess is not an + outage, so a missing or broken local cache reports `degraded` with HTTP 200. + """ + + alias Chesstrainer.Endgames.Tablebase.Local + alias Chesstrainer.Repo + + @type status :: %{ + status: String.t(), + db: String.t(), + tablebase: String.t(), + process: String.t() + } + + @doc "Returns the current health status." + @spec status() :: status() + def status do + db = if database_up?(), do: "ok", else: "down" + tablebase = tablebase_status() + + overall = + cond do + db == "down" -> "down" + tablebase == "local" -> "ok" + true -> "degraded" + end + + %{status: overall, db: db, tablebase: tablebase, process: "ok"} + end + + defp database_up? do + case Application.get_env(:chesstrainer, :health_database_check) do + fun when is_function(fun, 0) -> fun.() + _ -> default_database_up?() + end + end + + defp default_database_up? do + case Repo.query("SELECT 1") do + {:ok, _result} -> true + _ -> false + end + rescue + _ -> false + catch + _, _ -> false + end + + defp tablebase_status do + case Local.check() do + {:ok, largest} when largest > 0 -> "local" + {:ok, _largest} -> "fallback" + {:error, :not_configured} -> "not_configured" + {:error, _reason} -> "fallback" + end + end +end diff --git a/lib/chesstrainer_web/controllers/health_controller.ex b/lib/chesstrainer_web/controllers/health_controller.ex index 2796852..ea44d93 100644 --- a/lib/chesstrainer_web/controllers/health_controller.ex +++ b/lib/chesstrainer_web/controllers/health_controller.ex @@ -1,13 +1,17 @@ defmodule ChesstrainerWeb.HealthController do @moduledoc """ - Lightweight health check used by deploys and uptime monitors. + JSON health check used by deploys and uptime monitors. """ use ChesstrainerWeb, :controller def index(conn, _params) do + health = Chesstrainer.Health.status() + status = if health.status == "down", do: :service_unavailable, else: :ok + conn - |> put_resp_content_type("text/plain") - |> send_resp(200, "ok") + |> put_resp_header("x-robots-tag", "noindex") + |> put_status(status) + |> json(health) end end diff --git a/test/chesstrainer_web/controllers/health_controller_test.exs b/test/chesstrainer_web/controllers/health_controller_test.exs new file mode 100644 index 0000000..d6cae5e --- /dev/null +++ b/test/chesstrainer_web/controllers/health_controller_test.exs @@ -0,0 +1,62 @@ +defmodule ChesstrainerWeb.HealthControllerTest do + use ChesstrainerWeb.ConnCase, async: false + + describe "GET /health" do + test "returns ok with all four fields", %{conn: conn} do + conn = get(conn, ~p"/health") + body = json_response(conn, 200) + + assert body["status"] == "ok" + assert body["db"] == "ok" + assert body["tablebase"] == "local" + assert body["process"] == "ok" + assert get_resp_header(conn, "x-robots-tag") == ["noindex"] + end + + test "returns degraded when local tablebases are not configured", %{conn: conn} do + previous = Application.get_env(:chesstrainer, :tablebase_path) + on_exit(fn -> restore_env(:tablebase_path, previous) end) + Application.delete_env(:chesstrainer, :tablebase_path) + + conn = get(conn, ~p"/health") + body = json_response(conn, 200) + + assert body["status"] == "degraded" + assert body["db"] == "ok" + assert body["tablebase"] == "not_configured" + assert body["process"] == "ok" + end + + test "returns degraded when local tablebases are misconfigured", %{conn: conn} do + previous = Application.get_env(:chesstrainer, :tablebase_path) + on_exit(fn -> restore_env(:tablebase_path, previous) end) + Application.put_env(:chesstrainer, :tablebase_path, "/definitely/not/a/tablebase") + + conn = get(conn, ~p"/health") + body = json_response(conn, 200) + + assert body["status"] == "degraded" + assert body["db"] == "ok" + assert body["tablebase"] == "fallback" + assert body["process"] == "ok" + end + + test "returns 503 when the database is down", %{conn: conn} do + previous = Application.get_env(:chesstrainer, :health_database_check) + on_exit(fn -> restore_env(:health_database_check, previous) end) + Application.put_env(:chesstrainer, :health_database_check, fn -> false end) + + conn = get(conn, ~p"/health") + body = json_response(conn, 503) + + assert body["status"] == "down" + assert body["db"] == "down" + assert body["tablebase"] == "local" + assert body["process"] == "ok" + assert get_resp_header(conn, "x-robots-tag") == ["noindex"] + end + end + + defp restore_env(key, nil), do: Application.delete_env(:chesstrainer, key) + defp restore_env(key, value), do: Application.put_env(:chesstrainer, key, value) +end