Add local tablebase path config, fetch and check tasks (#31)

Read the local Syzygy directory from TABLEBASE_PATH so a dev machine and a VPS can point at their own copies. Add mix tablebase.fetch (downloads the 3/4/5 WDL+DTZ set, resumable) and mix tablebase.check (verifies it loads), plus a boot log reporting whether local tablebases are ready and the largest piece count.

Covers the codeable part of #31; installing on the VPS and setting TABLEBASE_PATH there remains a manual step.
This commit is contained in:
2026-11-03 14:26:30 +01:00
parent cb35351f8c
commit f37242ed29
7 changed files with 230 additions and 10 deletions
+24
View File
@@ -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). 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 ## Learn more
* Official website: https://www.phoenixframework.org/ * Official website: https://www.phoenixframework.org/
+2 -1
View File
@@ -20,7 +20,8 @@ defmodule Chesstrainer.Application do
ChesstrainerWeb.Endpoint, ChesstrainerWeb.Endpoint,
{Registry, keys: :unique, name: Chesstrainer.CacheRegistry}, {Registry, keys: :unique, name: Chesstrainer.CacheRegistry},
{Task.Supervisor, name: Chesstrainer.Cache.BackupSupervisor}, {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 # See https://elixir.hexdocs.pm/Supervisor.html
@@ -15,13 +15,13 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do
alias Chesstrainer.Endgames.Tablebase alias Chesstrainer.Endgames.Tablebase
alias Chesstrainer.Endgames.Tablebase.Backend.Lichess alias Chesstrainer.Endgames.Tablebase.Backend.Lichess
alias Chesstrainer.Endgames.Tablebase.Fathom, as: Nif alias Chesstrainer.Endgames.Tablebase.Fathom, as: Nif
alias Chesstrainer.Endgames.Tablebase.Local
alias Chesstrainer.Endgames.Tablebase.Move alias Chesstrainer.Endgames.Tablebase.Move
alias Chesstrainer.Endgames.Tablebase.San alias Chesstrainer.Endgames.Tablebase.San
@impl true @impl true
def probe(fen) do def probe(fen) do
with {:ok, path} <- tablebase_path(), with {:ok, _largest} <- Local.check(),
{:ok, _largest} <- Nif.init(path),
{:ok, {root, moves}} <- Nif.probe(fen) do {:ok, {root, moves}} <- Nif.probe(fen) do
case root do case root do
:failed -> fallback(fen) :failed -> fallback(fen)
@@ -32,13 +32,6 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do
end end
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 defp fallback(fen) do
(Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen) (Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen)
end end
@@ -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
+37
View File
@@ -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
+91
View File
@@ -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
@@ -13,6 +13,7 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.FathomTest do
alias Chesstrainer.Endgames.Tablebase alias Chesstrainer.Endgames.Tablebase
alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend
alias Chesstrainer.Endgames.Tablebase.Cache, as: TablebaseCache alias Chesstrainer.Endgames.Tablebase.Cache, as: TablebaseCache
alias Chesstrainer.Endgames.Tablebase.Local
alias Chesstrainer.FEN alias Chesstrainer.FEN
@krk "4k3/8/8/8/8/8/8/R3K3 w - - 0 1" @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) FathomBackend.probe(@mate)
end 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 test "answers through Tablebase.new without a cached entry" do
# A draw-returning fallback proves the win came from Fathom, not Lichess. # A draw-returning fallback proves the win came from Fathom, not Lichess.
previous = Application.get_env(:chesstrainer, :tablebase_fallback) previous = Application.get_env(:chesstrainer, :tablebase_fallback)