diff --git a/README.md b/README.md index 1c38c0e..755a141 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,30 @@ Now you can visit [`localhost:4000`](http://localhost:4000) from your browser. Ready to run in production? Please [check our deployment guides](https://phoenix.hexdocs.pm/deployment.html). +## Local tablebases (optional) + +Positions with five or fewer pieces are answered locally from Syzygy +tablebases when `TABLEBASE_PATH` points at a directory of `.rtbw`/`.rtbz` +files. When it is unset the trainer falls back to the Lichess API. + +`TABLEBASE_PATH` lets each environment point at its own copy — it differs on a +dev machine and a VPS: + +```sh +# Fetch the complete 3/4/5-piece WDL+DTZ set (~939 MB) once per host. +mix tablebase.fetch --path /path/to/syzygy/3-4-5 +mix tablebase.check --path /path/to/syzygy/3-4-5 + +# Dev +TABLEBASE_PATH=/path/to/syzygy/3-4-5 mix phx.server + +# Production +TABLEBASE_PATH=/data/syzygy/3-4-5 bin/chesstrainer start +``` + +On boot the app logs whether the local tablebases loaded and the largest piece +count they cover, so a wrong path shows up immediately. + ## Learn more * Official website: https://www.phoenixframework.org/ diff --git a/lib/chesstrainer/application.ex b/lib/chesstrainer/application.ex index 10519b6..b03f425 100644 --- a/lib/chesstrainer/application.ex +++ b/lib/chesstrainer/application.ex @@ -20,7 +20,8 @@ defmodule Chesstrainer.Application do ChesstrainerWeb.Endpoint, {Registry, keys: :unique, name: Chesstrainer.CacheRegistry}, {Task.Supervisor, name: Chesstrainer.Cache.BackupSupervisor}, - {Chesstrainer.Cache, {:tablebase, cache_opts}} + {Chesstrainer.Cache, {:tablebase, cache_opts}}, + Chesstrainer.Endgames.Tablebase.Local ] # See https://elixir.hexdocs.pm/Supervisor.html diff --git a/lib/chesstrainer/endgames/tablebase/backend/fathom.ex b/lib/chesstrainer/endgames/tablebase/backend/fathom.ex index 60e9b00..652b1ab 100644 --- a/lib/chesstrainer/endgames/tablebase/backend/fathom.ex +++ b/lib/chesstrainer/endgames/tablebase/backend/fathom.ex @@ -15,13 +15,13 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do alias Chesstrainer.Endgames.Tablebase alias Chesstrainer.Endgames.Tablebase.Backend.Lichess alias Chesstrainer.Endgames.Tablebase.Fathom, as: Nif + alias Chesstrainer.Endgames.Tablebase.Local alias Chesstrainer.Endgames.Tablebase.Move alias Chesstrainer.Endgames.Tablebase.San @impl true def probe(fen) do - with {:ok, path} <- tablebase_path(), - {:ok, _largest} <- Nif.init(path), + with {:ok, _largest} <- Local.check(), {:ok, {root, moves}} <- Nif.probe(fen) do case root do :failed -> fallback(fen) @@ -32,13 +32,6 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do end end - defp tablebase_path do - case Application.get_env(:chesstrainer, :tablebase_path) do - path when is_binary(path) and path != "" -> {:ok, path} - _ -> :error - end - end - defp fallback(fen) do (Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen) end diff --git a/lib/chesstrainer/endgames/tablebase/local.ex b/lib/chesstrainer/endgames/tablebase/local.ex new file mode 100644 index 0000000..d311d4b --- /dev/null +++ b/lib/chesstrainer/endgames/tablebase/local.ex @@ -0,0 +1,68 @@ +defmodule Chesstrainer.Endgames.Tablebase.Local do + @moduledoc """ + Local Syzygy tablebase configuration and verification. + + The directory is read from `TABLEBASE_PATH` (see `config/runtime.exs`), so the + same release can point at a different location on a dev machine and on a VPS + without a rebuild. When it is unset the local backend stays disabled and + lookups fall back to Lichess. + + On boot this logs whether the local tablebases loaded and how many pieces they + cover, so a misconfigured path is visible in the logs. + """ + + use GenServer + require Logger + + alias Chesstrainer.Endgames.Tablebase.Fathom + + @spec path() :: String.t() | nil + def path do + case Application.get_env(:chesstrainer, :tablebase_path) do + path when is_binary(path) and path != "" -> path + _ -> nil + end + end + + @doc """ + Initialises Fathom against the configured directory. + + Returns `{:ok, largest}` where `largest` is the biggest piece count available + (`0` when the directory has no tablebase files), or `{:error, :not_configured}` + when `TABLEBASE_PATH` is unset. + """ + @spec check() :: {:ok, non_neg_integer()} | {:error, term()} + def check do + with path when is_binary(path) <- path(), + {:ok, largest} <- Fathom.init(path) do + {:ok, largest} + else + nil -> {:error, :not_configured} + {:error, _reason} = error -> error + end + end + + def start_link(_opts), do: GenServer.start_link(__MODULE__, :ok, name: __MODULE__) + + @impl true + def init(:ok) do + log_status() + {:ok, %{}} + end + + defp log_status do + case check() do + {:ok, 0} -> + Logger.warning("local Syzygy tablebases at #{path()} contain no files") + + {:ok, largest} -> + Logger.info("local Syzygy tablebases ready at #{path()} (largest=#{largest})") + + {:error, :not_configured} -> + Logger.info("local Syzygy tablebases disabled (TABLEBASE_PATH unset)") + + {:error, reason} -> + Logger.warning("local Syzygy tablebases failed: #{inspect(reason)}") + end + end +end diff --git a/lib/mix/tasks/tablebase.check.ex b/lib/mix/tasks/tablebase.check.ex new file mode 100644 index 0000000..a5d54c0 --- /dev/null +++ b/lib/mix/tasks/tablebase.check.ex @@ -0,0 +1,37 @@ +defmodule Mix.Tasks.Tablebase.Check do + use Mix.Task + + @shortdoc "Verify the local Syzygy tablebases" + + @moduledoc """ + Verifies that the configured local Syzygy tablebases load. + + TABLEBASE_PATH=/data/syzygy/3-4-5 mix tablebase.check + mix tablebase.check --path /data/syzygy/3-4-5 + + Exits non-zero when the path is unset, empty, or Fathom fails to initialise. + """ + @impl Mix.Task + def run(args) do + {opts, _rest, _invalid} = OptionParser.parse(args, strict: [path: :string]) + + path = + opts[:path] || System.get_env("TABLEBASE_PATH") || + Chesstrainer.Endgames.Tablebase.Local.path() + + if is_nil(path) do + Mix.raise("set TABLEBASE_PATH or pass --path") + end + + case Chesstrainer.Endgames.Tablebase.Fathom.init(Path.expand(path)) do + {:ok, 0} -> + Mix.raise("no tablebase files found in #{path}") + + {:ok, largest} -> + Mix.shell().info("local tablebases at #{path}: largest=#{largest}") + + {:error, reason} -> + Mix.raise("failed to initialise Fathom: #{inspect(reason)}") + end + end +end diff --git a/lib/mix/tasks/tablebase.fetch.ex b/lib/mix/tasks/tablebase.fetch.ex new file mode 100644 index 0000000..6b39800 --- /dev/null +++ b/lib/mix/tasks/tablebase.fetch.ex @@ -0,0 +1,91 @@ +defmodule Mix.Tasks.Tablebase.Fetch do + use Mix.Task + + @default_mirror "http://tablebase.sesse.net/syzygy/3-4-5/" + + @shortdoc "Download the 3/4/5-piece Syzygy tablebases" + + @moduledoc """ + Downloads the complete 3/4/5-piece Syzygy WDL + DTZ set (~939 MB). + + mix tablebase.fetch --path /data/syzygy/3-4-5 + TABLEBASE_PATH=/data/syzygy/3-4-5 mix tablebase.fetch + + Existing files are skipped, so re-running resumes an interrupted download. + Use `--mirror` to override the source (defaults to `#{@default_mirror}`), or + `--dry-run` to see how many files are available without downloading. + + Verify the result with `mix tablebase.check`. + """ + + @impl Mix.Task + def run(args) do + {opts, _rest, _invalid} = + OptionParser.parse(args, + strict: [path: :string, mirror: :string, dry_run: :boolean] + ) + + path = + opts[:path] || System.get_env("TABLEBASE_PATH") || + Mix.raise("pass --path or set TABLEBASE_PATH, e.g. --path /data/syzygy/3-4-5") + + mirror = opts[:mirror] || @default_mirror + path = Path.expand(path) + + {:ok, _apps} = Application.ensure_all_started(:req) + + files = list_files(mirror) + + if opts[:dry_run] do + Mix.shell().info("Would fetch #{length(files)} files into #{path}") + else + File.mkdir_p!(path) + Mix.shell().info("Fetching 3/4/5 Syzygy tablebases into #{path}") + Mix.shell().info("#{length(files)} files to check") + + {downloaded, skipped} = + Enum.reduce(files, {0, 0}, fn file, {downloaded, skipped} -> + target = Path.join(path, file) + + if present?(target) do + {downloaded, skipped + 1} + else + download(mirror <> file, target, file) + {downloaded + 1, skipped} + end + end) + + Mix.shell().info("Done: #{downloaded} downloaded, #{skipped} already present") + Mix.shell().info("Verify with: mix tablebase.check --path #{path}") + end + end + + defp list_files(mirror) do + %{status: 200, body: body} = Req.get!(mirror) + + ~r/href="([^"]+\.rtb[zw])"/ + |> Regex.scan(body) + |> Enum.map(fn [_, file] -> file end) + |> Enum.uniq() + end + + defp present?(target), do: File.exists?(target) and File.stat!(target).size > 0 + + defp download(url, target, file) do + partial = target <> ".part" + Mix.shell().info(" #{file}") + + case Req.get(url, into: File.stream!(partial)) do + {:ok, %{status: 200}} -> + File.rename!(partial, target) + + {:ok, %{status: status}} -> + File.rm(partial) + Mix.raise("HTTP #{status} while fetching #{url}") + + {:error, reason} -> + File.rm(partial) + Mix.raise("failed to fetch #{url}: #{inspect(reason)}") + end + end +end diff --git a/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs b/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs index f25659f..f055228 100644 --- a/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs +++ b/test/chesstrainer/endgames/tablebase/backend/fathom_test.exs @@ -13,6 +13,7 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do alias Chesstrainer.Endgames.Tablebase alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend alias Chesstrainer.Endgames.Tablebase.Cache, as: TablebaseCache + alias Chesstrainer.Endgames.Tablebase.Local alias Chesstrainer.FEN @krk "4k3/8/8/8/8/8/8/R3K3 w - - 0 1" @@ -36,6 +37,11 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do FathomBackend.probe(@mate) end + test "Local.check/0 reports the configured fixture set" do + assert is_binary(Local.path()) + assert {:ok, 3} = Local.check() + end + test "answers through Tablebase.new without a cached entry" do # A draw-returning fallback proves the win came from Fathom, not Lichess. previous = Application.get_env(:chesstrainer, :tablebase_fallback)