Compare commits

...
29 Commits
Author SHA1 Message Date
owenrees 2759b34296 Derive only-move, underpromotion and 50-move motif themes (#195)
Motifs describe the kind of problem, independent of the material family. One
local tablebase probe returns the root WDL, the DTZ and every legal move with
its own WDL, so each motif is proved without a search or a remote lookup.

- only move: more than one legal move and exactly one preserves the
  50-move-aware result, for wins and draws.
- underpromotion: a preserving underpromotion exists while no preserving queen
  promotion does.
- 50-move draw: cursed/blessed WDL, or a win whose DTZ exceeds the remaining
  halfmove budget.

Motif links are recorded as derived and refreshed as a whole, scoped to the
motif themes, so material, curated and community links survive. Loss endgames
are skipped because only-move is undefined there.

Stalemate is deferred: a stored endgame cannot itself be terminal, so it can
only describe a line and needs a definition before it becomes a predicate.

Release helpers run the derivation without starting the web application, so
`bin/chesstrainer eval` works on the server.

Closes #188
2026-11-17 22:37:37 +01:00
owenrees e6f08e0ca6 Add a workspace for tagging technique themes by family (#194)
An admin picks a technique theme and sees candidate endgames grouped by Key
with counts. Expanding a family previews its boards without starting a puzzle,
and selecting positions applies the theme in bulk as curated. Large families are
paginated so a 600-endgame group stays usable, and curated links can be removed
from the same surface.

Removal is scoped to curated links, so derived and community links are never
deleted by hand. Material themes are refused because derivation owns them.

Closes #187
2026-11-17 21:55:37 +01:00
owenrees 946fc38756 Derive disjoint material family themes from each endgame's Key (#193)
Every endgame now belongs to exactly one material family derived from its Key:
pawn, rook, rook and pawn, queen, queen and pawn, minor piece, minor piece and
pawn, basic mate, king and pawn, or bare king other. The bare-king families are
split out because those positions teach a mating or promotion technique rather
than a general material class.

Family membership is objective, so a derivation pass owns links to its themes:
refreshing rewrites them as derived and removes a curated link that contradicts
the family, while technique themes are untouched. Re-running is idempotent.

A mix task applies the mapping to the whole library. Seeds add the king
technique themes for later human tagging.

Closes #186
2026-11-17 21:18:11 +01:00
owenrees 80cb033077 Add theme slugs, kinds and link provenance (#192)
* add function for upgrading a user's plan in interactive Elixir

* Add theme slugs, kinds and link provenance

Themes gain a stable slug, an optional description and a kind so the app can
tell material, motif and technique labels apart. Slugs are generated from the
name on first save and keep their value when the theme is renamed, so links to
a theme stay valid.

Endgame-to-theme links now record their source (derived, curated or community)
and creation time. Existing links are backfilled as curated. A derived pass can
therefore replace only its own links, leaving human work untouched.

The admin index shows each theme's kind and its coverage across the library.
Creating a theme name requires the manage_themes capability, and members get an
unauthorized error instead, ahead of the suggestion flow.

Closes #185
2026-11-17 20:46:43 +01:00
owenrees 7209923de7 Align board file labels with their squares 2026-11-17 15:13:47 +01:00
owenrees f4ff1e00fb Move colour mode and Discord controls into the mobile menu 2026-11-17 15:05:02 +01:00
owenrees 514c6ac924 Add Discord invite link to navbar and footer 2026-11-17 15:00:38 +01:00
owenrees e0b446bbfb Weight puzzle selection and stop repeats inside a session (#183)
Selection took a hard rating band (medium = user rating ± 100), removed
everything attempted in the last 30 days, and drew uniformly from what was
left. Because the bulk importer gives every endgame in a batch the same
rating, the band held either the whole library or — once a user's rating
drifted past it — only the endgames that user had already played. With
`fresh` empty, the fallback re-drew from the same band ignoring recency, so
recently played puzzles came straight back. An empty band used a
deterministic nearest-match, alternating between the same two puzzles.

Difficulty is now a bias rather than a filter: candidates are weighted by
`exp(-|rating - target| / spread)` and drawn with an exponential race, so
the whole library stays reachable and a thin region around the user's rating
can never empty the pool. `easy` and `hard` keep one-sided guards so the
labels stay honest. When every candidate is excluded, selection serves the
least recently attempted endgame instead of a random recent one.

Sessions now carry the ids they have served, which fixes the observed
in-session repeat (only the current puzzle used to be excluded), and guest
training gets the same treatment. The 30-day window is configurable as the
repeat window and is now named in GLOSSARY.md, distinct from the rating
window and from the tablebase cooldown.

Difficulty copy is qualitative, since the band numbers no longer describe
how selection works.
2026-11-17 14:28:24 +01:00
owenrees fa1fef7b62 Launch amendments: one login, crawler policy, and asset caching (#180)
* lesson library shown as com,ing soon. re-enable learngin strip

* replace learning strip text with a lasker quote

* remove admin login endpoint

* fix crawler directives and prelaunch login

- noindex the authenticated scope and the 404 catch-all, and cover the
  mailing-list confirmation redirect
- emit noindex, nofollow from the robots meta and /health, and assert
  public pages stay indexable and followable
- stop inventing lastmod values in the sitemap
- log in through /users/log-in during prelaunch now that the admin login
  endpoint is gone; drop create_admin/2 and its orphaned tests

* update caching length to 1 year - name change will invalidate cache

* remove logger

* fix tablebase path breaking tests

* test: check cache headers without requiring built assets

CI's test job does not run mix assets.build, so /assets/css/app.css is a
404 there. Committed piece art is already content-hashed and takes the same
Plug.Static cache option, so the test no longer needs a build step and
passes on a fresh checkout.
2026-11-17 12:55:47 +01:00
owenrees 37e0ac8e56 Transactional mail, crawler metadata, and asset measurement (#179)
* Send transactional email from no-reply@mail.innersquare.app

Centralise the sender identity, reply-to address and SES configuration set in Chesstrainer.Mail so no notifier can drift. Add MAIL_REDIRECT_TO for smoke tests and a mix mail.check task that exercises the SES mailbox simulators, and document the setup in the deploy guide and .env.example.

* Tighten crawler metadata and keep play pages out of search

Canonical URLs no longer carry query strings, public pages get an OG image, WebSite JSON-LD and a per-page language, and the sitemap dates the landing page only. Play and guest-training routes are marked noindex so tens of thousands of near-identical pages stay out of the index.

* Measure built asset sizes with mix assets.sizes

Report raw, gzip and brotli sizes for built JS and CSS, and record the current numbers plus the board-code split recommendation in docs/assets.md.
2026-11-17 10:29:45 +01:00
owenrees b33c5e334a Update to OTP 29 / Elixir 1.20 and refresh dependencies (#175) 2026-11-15 09:34:15 +01:00
owenrees aebb2aecfb Fix the error-state regressions from the #164 verification (#171) (#173)
T8: the invalid-FEN flash is generic; the client message and FEN go to the
log. A2: an expired confirmation link says so and lands on log-in, where an
unconfirmed account resends the email. W3: the connection banner gains Reload
and Home actions. D1: a failed export logs and redirects to the data tab with
a support address instead of a bare 500. D2: an unknown export format renders
the styled 404. H1: the empty-database home CTA points at the guest trainer
instead of auth-gated /endgames. X2/X3: the importer hides inspect(reason)
behind generic copy and logs it.

Adds coverage for the T8 copy, A2 destination, D2 404 page, H1 CTA and the W3
actions; the H1 tests now restore the curated-code override so async page
tests cannot poison each other.
2026-11-13 16:46:29 +01:00
owenrees 8934d191ad Record the launch observability decision and verify the error states (#172)
ADR 0012 states the launch bar, the deferred error tracking/metrics/log
shipping with a concrete revisit trigger for each, and the accepted risk of
journald plus off-box backups.

The verification page walks the #162 checklist against a local MIX_ENV=prod
build with forced failures: Postgres stopped, missing tablebase, empty pool,
expired tokens and exhausted guest budget. 14 rows pass, 6 fail; the eight
regressions are filed in #171. The audit's X1 row is corrected: an unknown
play code already returns the styled 404 page.
2026-11-13 16:10:42 +01:00
owenrees 021e412167 Make tablebase and empty-pool failures recoverable (#163) (#170)
Tablebase failures now render one message per class, with a Retry action
when fetching again can help. The generic class no longer interpolates
inspect(reason) into the page; the reason goes to the log instead.
Positions outside the tablebase offer the next puzzle (in a session) or the
existing back link, rather than a futile retry.

Train's no-puzzles and exhausted-difficulty flashes become in-page states
with Retry and Change difficulty. The guest pool gets the same treatment,
and GuestLimits.remaining/1 lets a guest see the wall, or the empty pool,
without spending a puzzle.
2026-11-13 15:36:59 +01:00
owenrees 0563b5aca2 Audit the user-facing error states (#162) (#169)
Records 35 states across play, sessions, accounts, mailing list, site-level, data and admin surfaces, each with its trigger, today's copy, a verdict and a concrete action. Calls out the five places where an internal detail can reach rendered HTML, and closes with the sign-off checklist for #164.
2026-11-13 15:04:30 +01:00
owenrees 0ae4c5b6fd Record the probe outage drill and its outcome (#168)
Adds the stop-Phoenix drill to the runbook, using forced probe runs so the
outage stays under a minute, and a dated drill log with the first run's
results. The log notes that the manual probe was started twice during the
outage, which is why two notifications arrived for one down/up transition.
2026-11-13 14:48:01 +01:00
owenrees b41c8bf1a6 Fix deploy docs: Bot Fight Mode status and probe reinstall (#167)
* Record that Bot Fight Mode is off

Both docs still claimed Bot Fight Mode was enabled. It is off; the Caddy
origin allowlist stays in force. Neither CI nor the on-box probe can get
past it on the free plan, so re-enabling needs the changes tracked in #153.

* Note that the probe must be installed to two places

The timer runs /usr/local/sbin/chesstrainer-probe, not the copy under
/opt/chesstrainer/src. Say so next to the install block, as the backup
section already does, so a changed deploy/probe does not silently drift
from what the timer runs.
2026-11-13 13:57:33 +01:00
owenrees 69b89f68ef Add a public health probe and monitoring runbook (#166)
* move theme picker position in add endgames form

* Add branded favicons and web manifest

- Replace the placeholder favicon with the knight mark: .ico (16/32/48),
  SVG, and 16/32 PNGs.
- Add opaque apple-touch and Android launcher icons plus a site
  webmanifest naming the app and using the brand palette.
- Link the icon set, manifest, and theme-color from the root layout and
  the 404/500 pages.
- Whitelist the new static files in static_paths/0 and the prelaunch
  allowlist so they are served in production and behind the gate.
- Sync the coming-soon site's favicon.ico and drop the unused Phoenix
  logo.

* Add a public health probe and monitoring runbook

Probe https://<PHX_HOST>/health through Cloudflare every two minutes and
report to a healthchecks.io check. A healthy run posts the raw health JSON;
a tablebase mismatch is a green check-in with the mismatch recorded; a
non-200, non-JSON, down database or network failure posts one fail ping with
the response body and a loopback cross-check as evidence.

--dry-run evaluates the success, degraded, fail, non-JSON and unreachable
fixtures without reading config or touching the network. The runbook covers
the healthchecks.io check, install, what /health proves, Beszel's blind spot
and the drills.

* Fix theme picker search after moving it into the endgame form

The picker moved inside the endgame form, which nested the component's
own <form>. Browsers, and the LiveView test DOM, drop a nested form along
with its phx-change and phx-submit bindings, so the search box did nothing
and three form tests lost their #theme-form selector.

The component now renders no form: phx-change sits on the search input,
which works both inside the endgame form and standalone on the bulk
importer. The unreachable create_theme_from_search handlers go away; theme
creation uses the existing button. Tests search through the input and
click that button.
2026-11-13 13:24:35 +01:00
owenrees f27e16af1d Allow bulk importer through prelaunch gate (#159)
The new EndgameLive.Import view was missing from the prelaunch allowlist, so PRELAUNCH=true redirected it to the home page.
2026-11-12 22:58:34 +01:00
owenrees fddb94e2bd Add admin bulk FEN importer (#156)
* change position of theme picker

* Add admin bulk FEN importer

Paste FENs, resolve results from the local Syzygy tablebase only, preview each line's status, and bulk insert with themes and a batch rating.
2026-11-12 22:44:13 +01:00
owenrees 20b53dae6f Show rating changes on puzzle completion (#146) (#154)
* Show rating changes in flashes and session UI (#146)

- Flash the new rating and delta on every rated completion, with a
  dedicated success flash kind for solved puzzles
- Move flash notifications to the top-left
- Add a colour-coded rating-change pill and show the current rating with
  the session's net change in the train session bar
- Show the user's rating and change beside the puzzle rating after an
  attempt, and show the finishing rating in the last-session summary

* fix header component and start reusing it

* Hide the sign-up link on the prelaunch admin login

The header refactor dropped the @prelaunch guard, so the gated admin login linked to the public registration page again.
2026-11-12 21:13:54 +01:00
owenrees 9e76045862 Automate, verify, and ship database backups off-box (#145) (#152)
The VPS now takes a daily logical dump, verifies it, encrypts it, and hands
it to a workstation; a monthly drill proves the archive restores.

- deploy/backup: pg_dump -Fc plus pg_dumpall --globals-only, pg_restore -l
  and globals-role checks before anything is promoted, row counts for the
  drill, sha256, age encryption into offsite/, retention (3d plaintext,
  14d encrypted, 5 pre-deploy sets), JSON logging and a healthchecks.io
  heartbeat
- systemd service and timer (03:15 UTC, Persistent, jittered) plus an
  OnFailure unit that logs a distinct event
- deploy/activate takes a pre-deploy dump after extracting and before
  flipping current, because migrations run in ExecStartPre; a failed dump
  aborts the activation, with SKIP_PRE_DEPLOY_BACKUP=1 as the escape hatch
- deploy/workstation/backup-pull: rsync the encrypted archives over SSH,
  verify by decrypting and checking the inner sha256, retain 7d/4w/6m, and
  fail when the newest archive is older than 48h
- deploy/workstation/backup-drill: restore the newest archive into a
  throwaway postgres:18.6, replay the globals dump as the same superuser,
  assert both roles, compare users/endgames/attempts, and append the result
  to drills.log
- user units for the daily pull and monthly drill, with a shared OnFailure
  alert template
- docs: install, key handling, retention, restore, disaster recovery, a run
  by hand section, monitoring and troubleshooting

Verified against production: the first backup completed and pinged the
heartbeat, the pull verified the archive, and the drill restored
users=1 endgames=39 attempts=0, matching the live database.
2026-11-11 22:59:54 +01:00
owenrees 624ddab644 Admin panel, login throttling, and Cloudflare edge hardening (#150)
* Document the remote shell for production user management

* add sitemap to footer links

* remove border under theme selection

* Add admin theme and user management (#144)

Add /admin/themes CRUD and /admin/users list/detail with role and plan editing, guarded by a shared Policy module. Include last-super-admin and self-role protections plus structured id-only admin logs.

Also add admin invitations, confirmation resends and password-reset emails, which work in development through the Swoosh mailbox before SES is configured.

* Rate-limit password logins and emit auth events (#142)

Add a two-bucket login throttle (5 failures per login, 10 per IP in a 15-minute window) and a shared client-address helper for controllers and LiveViews. Blocked attempts skip the database and bcrypt.

Log auth.login.failed and auth.login.throttled warnings with boot-scoped HMAC addresses only, and stop repeated confirmation emails on unconfirmed login attempts.

* Harden the production login edge for Cloudflare

Document the layered login defence: the app throttle is primary, Caddy must pass Cloudflare's CF-Connecting-IP to the app, and Cloudflare edge rate limiting covers request floods.

Update the reference Caddyfile to accept only Cloudflare ranges and reject direct-to-origin traffic, and document the exact Cloudflare dashboard rules.

* Document 10-second Cloudflare rate-limit window

Cloudflare may only offer a 10-second period. Keep the edge rule at 10 login POSTs per 10 seconds per IP and rely on the app's 15-minute login/address throttle for credential guessing.

* Document Cloudflare limits for LiveView registration

Registration submits over the shared LiveView socket, so a Cloudflare rule on POST /users/register will not count account creations. Note the app-level throttle/Turnstile options instead.

* Document current Cloudflare free-plan edge controls

Record the production setup: Cloudflare-only Caddy origins, Bot Fight Mode, and the 10-second login flood rule (10 POSTs per 10 seconds, 10-second block). Clarify that the application's 15-minute throttle remains the real credential lockout.

* Auto-refresh Cloudflare CIDRs for Caddy

Move the origin allowlist into a generated cloudflare-ranges.caddy imported by Caddy. Add an hourly systemd timer and script that fetch Cloudflare's v4/v6 lists, reject malformed responses, validate the candidate Caddyfile, and reload Caddy only when the ranges change. Restore the previous file on validation or reload failure.

* Document Cloudflare CIDR refresher setup and operations

Record the installed paths, permissions, timer checks, manual run, update procedure, and the direct-on-VPS setup fallback when the deploy directory is absent.
2026-11-11 21:27:59 +01:00
owenrees 202b9b1f6a Add structured production logging (#105, #107) (#141)
* Update README.md

* Add structured JSON production logging (#105)

* Log requests and background failures (#107)

* Document production logging and the VPS runbook
2026-11-10 22:00:05 +01:00
owenrees f8897fa5ae Add French legal notice and complete privacy disclosures (#134)
- Add /mentions-legales (LCEN art. 6-III): publisher, SIRET, VAT status,
  publication director, and host details
- Name the data controller in the privacy policy and the terms
- Disclose Hetzner/Cloudflare hosting, third-country transfers, the CDN
  security cookie, and backup/suppression-list retention
- Remove the children section; the age floor now lives in the terms
- State that request logs are kept by the providers, not by us
- Mirror all changes in the pre-launch static site

The publisher address is a placeholder pending a domiciliation address.
2026-11-10 11:41:40 +01:00
owenrees 73ba25afe3 Add cookieless Matomo analytics and opt-out (#131) (#133)
* Align Postgres version on 18.6

* Document production tablebase path and permissions

* Add cookieless Matomo analytics with opt-out (#131)
2026-11-10 10:12:48 +01:00
owenrees be57f21729 Add manual CD dispatch and deployment docs (#128) 2026-11-10 09:29:20 +01:00
owenrees ee687dfb2d update with deploy job 2026-11-10 09:27:40 +01:00
owenrees fa90e1102d pin action versions 2026-11-10 09:15:06 +01:00
196 changed files with 13430 additions and 763 deletions
+6
View File
@@ -7,6 +7,12 @@ MAILING_LIST_ENABLED=false
SES_REGION=eu-north-1
SES_ACCESS_KEY_ID=AKIA...
SES_SECRET_ACCESS_KEY=...
SES_CONFIGURATION_SET=my-first-configuration-set
# Optional: override the sender or send everything to one address while testing.
# MAIL_FROM=no-reply@mail.innersquare.app
# MAIL_REDIRECT_TO=you@example.com
# Optional: directory of local Syzygy .rtbw/.rtbz files. Ignored by the test
# suite, which always uses the committed 3-piece fixtures.
TABLEBASE_PATH=
MATOMO_URL=https://analytics.owenrees.eu/
+48 -7
View File
@@ -4,6 +4,7 @@ on:
pull_request:
push:
branches: [main]
workflow_dispatch:
permissions:
contents: read
@@ -21,7 +22,7 @@ jobs:
services:
postgres:
image: postgres:18.0
image: postgres:18.6
env:
POSTGRES_USER: postgres
POSTGRES_PASSWORD: postgres
@@ -34,10 +35,10 @@ jobs:
--health-retries 10
steps:
- uses: actions/checkout@v7
- uses: jdx/mise-action@v2
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #v7.0.1
- uses: jdx/mise-action@b44d12e7d0d8ee7461bb893e1b1993500433185b #v5.2.7
- uses: actions/cache@v4
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 #v6.1.0
with:
path: |
deps
@@ -66,10 +67,10 @@ jobs:
SES_SECRET_ACCESS_KEY: build
steps:
- uses: actions/checkout@v7
- uses: jdx/mise-action@v2
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 #v7.0.1
- uses: jdx/mise-action@b44d12e7d0d8ee7461bb893e1b1993500433185b #v5.2.7
- uses: actions/cache@v4
- uses: actions/cache@55cc8345863c7cc4c66a329aec7e433d2d1c52a9 #v6.1.0
with:
path: |
deps
@@ -94,3 +95,43 @@ jobs:
name: chesstrainer-release
path: chesstrainer-release.tar.gz
retention-days: 7
deploy:
name: Deploy
needs: build-release
if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
runs-on: ubuntu-24.04
environment: production
concurrency:
group: production
cancel-in-progress: false
steps:
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 #v8.0.2
with:
name: chesstrainer-release
- name: Install SSH key
run: |
mkdir -p ~/.ssh
printf '%s\n' "${{ secrets.VPS_SSH_KEY }}" > ~/.ssh/id_ed25519
chmod 600 ~/.ssh/id_ed25519
printf '%s\n' "${{ secrets.VPS_KNOWN_HOSTS }}" > ~/.ssh/known_hosts
chmod 644 ~/.ssh/known_hosts
- name: Upload release
run: |
scp -i ~/.ssh/id_ed25519 -o BatchMode=yes \
chesstrainer-release.tar.gz \
"${{ secrets.VPS_USER }}@${{ secrets.VPS_HOST }}:/tmp/chesstrainer-release.tar.gz"
- name: Activate release
run: |
ssh -i ~/.ssh/id_ed25519 -o BatchMode=yes \
"${{ secrets.VPS_USER }}@${{ secrets.VPS_HOST }}" \
'sudo -n /opt/chesstrainer/src/deploy/activate /tmp/chesstrainer-release.tar.gz'
- name: Public smoke test
run: |
curl -fsS https://innersquare.app/health
curl -fsS -o /dev/null https://innersquare.app/
+15 -5
View File
@@ -105,6 +105,14 @@ carries a start time and a rating baseline for the timer and rating-gain
monitor. Ephemeral — it lives only in the running LiveView, never persisted.
_Avoid_: Run, game, attempt
**Repeat window**:
The minimum interval before the same endgame may be served to the same user
again. Selection skips endgames attempted inside the window; only when nothing
else is available does the least recently attempted endgame come back. It is
independent of the rating window, which decides whether a replay may move a
rating.
_Avoid_: Cooldown (reserved for tablebase rate-limiting), due date
## Ratings
**Rating**:
@@ -128,11 +136,13 @@ systems; the trainer deliberately does not track it.
_Avoid_: Variance, inconsistency
**Difficulty**:
A choice — `easy`, `medium` or `hard` — that selects which puzzles to serve
relative to the current user's rating: `medium` is near the user's rating,
`easy` below it, `hard` above it. The band width is a configured constant. It is
a property of a session, not of an endgame — the same endgame is easy for one
user and hard for another.
A choice — `easy`, `medium` or `hard` — that biases which puzzles are served
relative to the current user's rating: `medium` centres on the user's rating,
`easy` below it, `hard` above it. Candidates are weighted by how close their
rating is to that centre, so a session draws mostly from near the target but the
whole library stays reachable. The spread is a configured constant. It is a
property of a session, not of an endgame — the same endgame is easy for one user
and hard for another.
_Avoid_: Level, rank, tier
## Infrastructure
+12
View File
@@ -21,9 +21,21 @@ mix tablebase.fetch --path /path/to/syzygy/3-4-5 # once per host (~939 MB)
export TABLEBASE_PATH=/path/to/syzygy/3-4-5 # set per environment
```
On the production VPS the directory is `/opt/chesstrainer/tablebases`, owned by
the `chesstrainer` user. Set `TABLEBASE_PATH` in `/etc/chesstrainer/env` and
restart the service; the value is read at boot.
See [docs/tablebases.md](docs/tablebases.md) for the full reference — dev vs
VPS paths, `mix tablebase.check`, and boot logging.
## Logging
Production logs are one JSON object per line so they can be filtered with
`journalctl` and `jq`; development and test keep the readable formatter. See
[docs/logging.md](docs/logging.md) for the line shape, redaction rules and the
background-work audit, and [`deploy/README.md`](deploy/README.md) for the VPS
runbook.
## Learn more
* Official website: https://www.phoenixframework.org/
+5
View File
@@ -43,6 +43,10 @@
.avatar-stack i:last-child { background: var(--color-deep); color: var(--color-on-deep); }
.puzzle-section { width: min(1180px, calc(100% - 48px)); margin: 0 auto; padding: 110px 0 125px; }
.puzzle-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 16px; }
.puzzle-coming-soon { min-height: 285px; display: grid; place-content: center; justify-items: center; gap: 10px; padding: 46px 28px; text-align: center; border: 1px dashed var(--color-hairline); border-radius: 12px; background: var(--color-canvas-raised); }
.puzzle-coming-soon .eyebrow { margin-bottom: 6px; }
.puzzle-coming-soon strong { font-family: 'DM Serif Display', serif; font-size: 30px; font-weight: 400; }
.puzzle-coming-soon p { max-width: 420px; margin: 0; color: var(--color-muted); font-size: 14px; line-height: 1.7; }
.puzzle-card { display: block; position: relative; min-height: 285px; padding: 25px; text-align: left; text-decoration: none; color: inherit; cursor: pointer; border: 1px solid var(--color-hairline); border-radius: 12px; background: rgba(255,255,255,.28); overflow: hidden; transition: transform .25s, background .25s, box-shadow .25s; }
.puzzle-card:hover, .puzzle-card.active { transform: translateY(-5px); background: var(--color-canvas-raised); box-shadow: 0 18px 36px rgba(23,53,45,.08); }
.puzzle-card.active { border-color: var(--color-success-text); }
@@ -69,6 +73,7 @@ html[data-theme="dark"] .learning-strip { box-shadow: inset 0 1px 0 var(--color-
@media (max-width: 650px) {
.puzzle-section { width: calc(100% - 36px); padding: 80px 0; }
.puzzle-grid { grid-template-columns: 1fr; }
.puzzle-coming-soon { min-height: 255px; padding: 38px 22px; }
.puzzle-card { min-height: 255px; }
.progress-banner { width: calc(100% - 36px); padding: 48px 28px; flex-direction: column; align-items: flex-start; gap: 34px; }
}
+1
View File
@@ -41,6 +41,7 @@ h1 em { color: var(--color-coral); font-weight: 400; }
.settings-subtitle {
font-size: 1rem;;
color: var(--color-muted);
margin-top: 0.5rem;
}
@media (max-width: 650px) {
+7
View File
@@ -43,6 +43,13 @@
/* Play board */
#endgame-board { position: relative; }
/* Chessground's stock stylesheet shifts the file labels 24px right of the
board, assuming a gutter we don't have, so they land on square boundaries
instead of under each file. Place the row on the board and right-justify
each label within its square; the row's width already matches the board
because the container is sized to whole squares. */
#endgame-board coords.files { left: 0; text-align: right; }
/* Chessground's wrapper has no intrinsic height; let it fill the sized
aspect-ratio container so the board scales with the viewport. */
#endgame-board .cg-wrap { width: 100%; height: 100%; }
+7
View File
@@ -1,2 +1,9 @@
.eyebrow { display: flex; align-items: center; gap: 9px; margin-bottom: 27px; color: var(--color-coral-text); text-transform: uppercase; letter-spacing: .13em; font-size: 12px; font-weight: 700; }
.eyebrow svg { width: 20px; height: 20px; }
/* Icon-only external links, e.g. the Discord invite in the navbar and footer.
Colour is inherited so the glyph matches the surrounding link row. */
.discord-link { display: inline-flex; align-items: center; color: inherit; transition: opacity .2s; }
.discord-link:hover { opacity: .55; }
.discord-link:focus-visible { outline: 2px solid var(--color-coral-control); outline-offset: 3px; border-radius: 4px; }
.discord-link svg { width: 20px; height: 20px; }
+4 -2
View File
@@ -3,7 +3,9 @@
display: grid; grid-template-columns: 1.5fr repeat(3, 1fr); align-items: center; background: var(--color-deep); color: var(--color-on-deep);
}
.learning-strip > p { max-width: 260px; color: var(--color-on-deep-muted); font-family: 'DM Serif Display', serif; font-size: 19px; line-height: 1.25; }
.learning-quote { margin: 0; max-width: 300px; }
.learning-quote blockquote { margin: 0; color: var(--color-on-deep); font-family: 'DM Serif Display', serif; font-size: 19px; line-height: 1.25; }
.learning-quote figcaption { margin-top: 10px; color: var(--color-on-deep-faint); font-size: 10px; text-transform: uppercase; letter-spacing: .09em; }
.stat { padding-left: 34px; border-left: 1px solid rgba(255,255,255,.17); }
.stat strong { display: block; font-family: 'DM Serif Display', serif; font-size: 28px; font-weight: 400; }
@@ -15,7 +17,7 @@
@media (max-width: 650px) {
.learning-strip { padding: 38px 24px; grid-template-columns: 1fr 1fr; gap: 30px 10px; }
.learning-strip > p { grid-column: 1 / -1; }
.learning-quote { grid-column: 1 / -1; }
.stat { padding-left: 18px; }
.stat:last-child { grid-column: 1 / -1; }
}
+8
View File
@@ -14,6 +14,9 @@
.nav-links a { transition: opacity .2s; }
.nav-links a:hover { opacity: .55; }
.nav-links a.nav-cta:hover { opacity: 1; }
/* Utilities (colour mode, Discord) sit in the bar on desktop and in the
collapsible menu on small screens. */
.nav-menu-tools { display: none; }
.nav-user-menu { position: relative; }
.nav-user-menu summary { display: flex; align-items: center; gap: 6px; list-style: none; cursor: pointer; color: var(--color-muted); font-weight: 500; }
.nav-user-menu summary::-webkit-details-marker { display: none; }
@@ -42,6 +45,11 @@ html[data-theme="dark"] .nav-user-menu-panel { box-shadow: 0 18px 40px rgba(0, 0
.nav-links.open { display: flex; }
.nav-cta { width: 100%; }
.nav-links { display: none; position: absolute; top: 65px; left: 0; right: 0; padding: 24px; flex-direction: column; align-items: stretch; gap: 22px; border-radius: 10px; background: var(--color-canvas-raised); box-shadow: 0 18px 40px rgba(23,53,45,.15); }
.nav-menu-tools { display: flex; align-items: center; justify-content: space-between; gap: 18px; width: 100%; }
/* The menu owns these on small screens; keep them in the bar only when no
menu is rendered (prelaunch with no links). */
.nav-wrap:has(#nav-links) .nav-right > [role="radiogroup"],
.nav-wrap:has(#nav-links) .nav-right > .discord-link { display: none; }
.nav-user-menu-panel { position: static; min-width: 0; padding: 12px 0 0; background: transparent; box-shadow: none; }
html[data-theme="dark"] .nav-links { box-shadow: 0 18px 40px rgba(0, 0, 0, .45); }
}
+105
View File
@@ -0,0 +1,105 @@
// Cookieless Matomo for anonymous public pages. The server only renders the
// #matomo-config element for anonymous visitors, so account and admin pages
// never load a tracker.
const OPT_OUT_KEY = "matomo_optout";
export function isOptedOut() {
try {
return localStorage.getItem(OPT_OUT_KEY) === "1";
} catch (_error) {
// If storage is unavailable we cannot remember an opt-out. Fail closed.
return true;
}
}
function setOptedOut(optedOut) {
try {
if (optedOut) {
localStorage.setItem(OPT_OUT_KEY, "1");
} else {
localStorage.removeItem(OPT_OUT_KEY);
}
} catch (_error) {
// Nothing else to do; the current page remains untracked.
}
}
function updateUI() {
const optOutButton = document.getElementById("analytics-opt-out");
const optInButton = document.getElementById("analytics-opt-in");
const status = document.getElementById("analytics-status");
if (!optOutButton && !optInButton && !status) return;
const optedOut = isOptedOut();
if (optOutButton) optOutButton.hidden = optedOut;
if (optInButton) optInButton.hidden = !optedOut;
if (status) {
status.textContent = optedOut
? "Analytics is currently off in this browser."
: "Analytics is currently on in this browser.";
}
}
function isPrivatePath() {
return window.location.pathname.startsWith("/admin");
}
function trackPageView() {
if (isPrivatePath() || isOptedOut() || !window._paq) return;
window._paq.push(["setCustomUrl", window.location.href]);
window._paq.push(["trackPageView"]);
}
function loadTracker() {
const config = document.getElementById("matomo-config");
if (!config || isPrivatePath() || isOptedOut()) return;
const url = config.dataset.url;
const siteId = config.dataset.siteId;
if (!url || !siteId) return;
const _paq = (window._paq = window._paq || []);
_paq.push(["disableCookies"]);
_paq.push(["setDoNotTrack", true]);
_paq.push(["trackPageView"]);
_paq.push(["setTrackerUrl", `${url}matomo.php`]);
_paq.push(["setSiteId", siteId]);
const script = document.createElement("script");
script.async = true;
script.src = `${url}matomo.js`;
document.head.appendChild(script);
}
function handleClick(event) {
const target = event.target instanceof Element ? event.target : null;
if (!target) return;
if (target.closest("#analytics-opt-out")) {
event.preventDefault();
setOptedOut(true);
updateUI();
return;
}
if (target.closest("#analytics-opt-in")) {
event.preventDefault();
setOptedOut(false);
// The tracker was not loaded while opted out. Reload to start it.
window.location.reload();
}
}
export function initAnalytics() {
if (window.__matomoInitialised) return;
window.__matomoInitialised = true;
loadTracker();
window.addEventListener("phx:navigate", trackPageView);
document.addEventListener("click", handleClick);
updateUI();
}
+4
View File
@@ -21,6 +21,8 @@
import "phoenix_html";
// Plain-DOM mobile navigation (works on controller and LiveView pages).
import "./nav";
// Cookieless Matomo for anonymous public pages.
import { initAnalytics } from "./analytics";
// Establish Phoenix Socket and LiveView configuration.
import { Socket } from "phoenix";
import { LiveSocket } from "phoenix_live_view";
@@ -58,6 +60,8 @@ liveSocket.connect();
// >> liveSocket.disableLatencySim()
window.liveSocket = liveSocket;
initAnalytics();
// The lines below enable quality of life phoenix_live_reload
// development features:
//
+3
View File
@@ -2,3 +2,6 @@
// page. Keep this small: no Phoenix Socket, LiveView, hooks, or topbar.
import "phoenix_html";
import "./nav";
import { initAnalytics } from "./analytics";
initAnalytics();
+22 -6
View File
@@ -15,7 +15,8 @@ config :chesstrainer, :branding,
wordmark: "INNERSQUARE",
tagline: "Endgame Trainer",
support_email: "support@innersquare.app",
mail_from: "no-reply@innersquare.app"
mail_from: "no-reply@mail.innersquare.app",
discord_invite: "https://discord.gg/Z2NfkG7thV"
# Prelaunch gating. Production sets these from PRELAUNCH and
# MAILING_LIST_ENABLED; dev and test use these defaults.
@@ -39,6 +40,16 @@ config :chesstrainer,
ecto_repos: [Chesstrainer.Repo],
generators: [timestamp_type: :utc_datetime]
# Password-login throttle. Failures are counted in fixed windows for each
# client address and each normalised login. The address bucket is deliberately
# wider so one account stays protected from distributed guessing while one
# address cannot spray many accounts.
config :chesstrainer, ChesstrainerWeb.LoginThrottle,
window_ms: :timer.minutes(15),
max_per_login: 5,
max_per_ip: 10,
confirmation_cooldown_ms: :timer.minutes(15)
# Glicko rating system.
#
# `system_constant` is the volatility constraint passed through to the Glicko
@@ -51,11 +62,16 @@ config :chesstrainer, :ratings,
window_days: 7,
rd_inflation_c: 10.0
# Difficulty bands for puzzle sessions. An endgame is "medium" when its rating
# falls within `band_width` of the user's rating, "easy" below that band and
# "hard" above it. Tweak to widen or narrow the served difficulty (e.g. 150 or
# 200).
config :chesstrainer, :puzzles, band_width: 100
# Puzzle selection. Difficulty is a weighted bias towards a target rating —
# `medium` targets the user's rating, `easy` 200 below it and `hard` 200 above
# it — and `spread` is how many rating points it takes for a puzzle's chance to
# fall off by a factor of e. `repeat_window_days` is how long an attempted
# puzzle stays out of the pool. Tweak `spread` to widen or narrow the served
# difficulty (e.g. 100 or 250).
config :chesstrainer, :puzzles,
spread: 150,
repeat_window_days: 30,
targets: [easy: -200, medium: 0, hard: 200]
# Public codes of the endgames pinned to the landing-page puzzle grid, in
# display order. When empty (or short) the grid is topped up with a date-seeded
+5
View File
@@ -33,5 +33,10 @@ config :swoosh, local: false
# Do not print debug messages in production
config :logger, level: :info
# Emit one JSON object per line in production so journald output can be
# filtered and shipped without parsing prose. Dev and test keep the readable
# default formatter configured in config.exs.
config :logger, :default_handler, formatter: {Chesstrainer.JSONLogFormatter, %{}}
# Runtime production configuration, including reading
# of environment variables, is done on config/runtime.exs.
+29 -3
View File
@@ -28,11 +28,33 @@ if mailing_list_enabled = System.get_env("MAILING_LIST_ENABLED") do
config :chesstrainer, :mailing_list_enabled, mailing_list_enabled in ~w(true 1)
end
# Sender address override. The default lives in config/config.exs; this lets a
# deploy try a different From address (for example a new sending subdomain)
# without a rebuild.
if mail_from = System.get_env("MAIL_FROM") do
branding = Application.get_env(:chesstrainer, :branding, [])
config :chesstrainer, :branding, Keyword.put(branding, :mail_from, mail_from)
end
# SES configuration set stamped on every outgoing email. The set is what links
# a message to its SNS bounce and complaint notifications.
config :chesstrainer,
:ses_configuration_set,
System.get_env("SES_CONFIGURATION_SET", "my-first-configuration-set")
# Rewrite every recipient to one address while testing. Leave unset in normal
# operation; see `mix mail.check`.
config :chesstrainer, :mail_redirect_to, System.get_env("MAIL_REDIRECT_TO")
# Local Syzygy tablebases: set TABLEBASE_PATH to the directory holding the
# .rtbw/.rtbz files. When unset, the local backend stays disabled and lookups
# fall back to Lichess.
if tablebase_path = System.get_env("TABLEBASE_PATH") do
config :chesstrainer, :tablebase_path, tablebase_path
# fall back to Lichess. Tests are always pinned to the committed 3-piece
# fixtures by config/test.exs, so an exported TABLEBASE_PATH cannot make them
# depend on whatever tables the developer happens to have downloaded.
if config_env() != :test do
if tablebase_path = System.get_env("TABLEBASE_PATH") do
config :chesstrainer, :tablebase_path, tablebase_path
end
end
# Tablebase cache: size and the UTC time of the daily backup. Environment
@@ -121,6 +143,10 @@ if config_env() == :prod do
System.get_env("SES_SECRET_ACCESS_KEY") ||
raise("environment variable SES_SECRET_ACCESS_KEY is missing")
config :chesstrainer, :matomo,
url: System.get_env("MATOMO_URL"),
site_id: System.get_env("MATOMO_SITE_ID")
config :chesstrainer, Chesstrainer.Repo,
# ssl: true,
url: database_url,
+27 -4
View File
@@ -3,13 +3,36 @@
# This file is not installed automatically. On the shared VPS, add this block
# to the existing Caddy config by hand, then validate and reload Caddy.
#
# The app listens on loopback only; Caddy is the public entry point.
# Cloudflare sits in front of Caddy. Two things matter here:
#
# 1. Only accept requests from Cloudflare's published edge ranges.
# 2. Replace X-Forwarded-For with Cloudflare's single-value CF-Connecting-IP
# header, so the app's TRUST_FORWARDED_FOR=true path sees the visitor, not a
# Cloudflare edge address.
#
# The ranges live in cloudflare-ranges.caddy next to this file. A systemd
# timer refreshes them from https://www.cloudflare.com/ips-v4 and /ips-v6;
# see deploy/update-cloudflare-ranges.sh and deploy/README.md.
innersquare.app {
encode zstd gzip
reverse_proxy 127.0.0.1:4100
encode zstd gzip
@cloudflare {
import cloudflare-ranges.caddy
}
handle @cloudflare {
reverse_proxy 127.0.0.1:4100 {
header_up X-Forwarded-For {http.request.header.CF-Connecting-IP}
}
}
# Direct-to-origin requests cannot spoof Cloudflare's client-IP header.
handle {
respond "Access Denied" 403
}
}
www.innersquare.app {
redir https://innersquare.app{uri} permanent
redir https://innersquare.app{uri} permanent
}
+1078 -29
View File
File diff suppressed because it is too large Load Diff
+27 -1
View File
@@ -7,7 +7,8 @@ set -euo pipefail
# sudo deploy/activate /tmp/chesstrainer-20261109.tar.gz
#
# Environment overrides:
# APP_USER, APP_ROOT, SERVICE, HEALTH_URL, KEEP_RELEASES, RELEASE_ID
# APP_USER, APP_ROOT, SERVICE, HEALTH_URL, KEEP_RELEASES, RELEASE_ID,
# BACKUP_BIN, SKIP_PRE_DEPLOY_BACKUP=1
if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
echo "activate: run with sudo" >&2
@@ -26,6 +27,8 @@ SERVICE="${SERVICE:-chesstrainer}"
HEALTH_URL="${HEALTH_URL:-http://127.0.0.1:4100/health}"
KEEP_RELEASES="${KEEP_RELEASES:-5}"
RELEASE_ID="${RELEASE_ID:-$(date -u +%Y%m%d%H%M%S)}"
BACKUP_BIN="${BACKUP_BIN:-/usr/local/sbin/chesstrainer-backup}"
SKIP_PRE_DEPLOY_BACKUP="${SKIP_PRE_DEPLOY_BACKUP:-0}"
if [[ ! "$RELEASE_ID" =~ ^[A-Za-z0-9._-]+$ ]]; then
echo "activate: RELEASE_ID may contain only letters, digits, dot, underscore and dash" >&2
@@ -53,6 +56,29 @@ install -d -o "$APP_USER" -g "$APP_USER" "$RELEASE_DIR"
tar -xzf "$TARBALL" -C "$RELEASE_DIR"
chown -R "$APP_USER:$APP_USER" "$RELEASE_DIR"
if [[ "$SKIP_PRE_DEPLOY_BACKUP" == "1" ]]; then
echo "activate: SKIP_PRE_DEPLOY_BACKUP=1, not taking a pre-deploy dump"
else
backup_script="$BACKUP_BIN"
if [[ ! -x "$backup_script" ]]; then
backup_script="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/backup"
fi
if [[ ! -x "$backup_script" ]]; then
echo "activate: no backup script at $BACKUP_BIN or next to activate" >&2
echo "activate: install deploy/backup or set SKIP_PRE_DEPLOY_BACKUP=1" >&2
exit 1
fi
# Migrations run in ExecStartPre after this, so the dump must exist first.
echo "activate: taking a pre-deploy dump"
if ! BACKUP_TAG=predeploy LOCK_WAIT=120 "$backup_script"; then
echo "activate: pre-deploy dump failed, aborting" >&2
echo "activate: fix the backup or re-run with SKIP_PRE_DEPLOY_BACKUP=1" >&2
exit 1
fi
fi
echo "activate: pointing current at $RELEASE_DIR"
ln -sfn "$RELEASE_DIR" "$APP_ROOT/current"
Executable
+266
View File
@@ -0,0 +1,266 @@
#!/usr/bin/env bash
#
# Dump, verify, encrypt, prune and report on the production database.
#
# Installed as /usr/local/sbin/chesstrainer-backup (root-owned 0755) and run by
# chesstrainer-backup.timer. deploy/activate also calls it before migrations.
# Do not run the copy under /opt/chesstrainer/src as root: that tree belongs to
# the application user.
#
# sudo systemctl start chesstrainer-backup # daily run, as the timer does
# sudo BACKUP_TAG=manual chesstrainer-backup # ad-hoc, pruned by age
#
# Configuration lives in /etc/chesstrainer/backup.env (root:root 0600). See
# deploy/README.md §Backups. Every setting can also be passed as an environment
# variable.
#
# Each run prints exactly one JSON line (backup.completed or backup.failed) so
# journald, and #140's log shipping, can pick it up.
set -euo pipefail
umask 077
ENV_FILE="${ENV_FILE:-/etc/chesstrainer/backup.env}"
if [[ -r "$ENV_FILE" ]]; then
# shellcheck disable=SC1090
source "$ENV_FILE"
fi
DB_CONTAINER="${DB_CONTAINER:-chesstrainer-db}"
PG_USER="${PG_USER:-chesstrainer}"
PG_DB="${PG_DB:-chesstrainer_prod}"
BACKUP_DIR="${BACKUP_DIR:-/var/backups/chesstrainer}"
EXPECTED_ROLES="${EXPECTED_ROLES:-chesstrainer chesstrainer_ro}"
AGE_RECIPIENT="${AGE_RECIPIENT:-}"
HEALTHCHECK_URL="${HEALTHCHECK_URL:-}"
SKIP_HEARTBEAT="${SKIP_HEARTBEAT:-0}"
MIN_FREE_MB="${MIN_FREE_MB:-2048}"
LOCAL_PLAINTEXT_DAYS="${LOCAL_PLAINTEXT_DAYS:-3}"
LOCAL_ENCRYPTED_DAYS="${LOCAL_ENCRYPTED_DAYS:-14}"
PREDEPLOY_KEEP="${PREDEPLOY_KEEP:-5}"
BACKUP_TAG="${BACKUP_TAG:-daily}"
LOCK_WAIT="${LOCK_WAIT:-0}"
START_SECONDS=$SECONDS
FAILURE=""
log_event() {
local event="$1"
local extra="${2:-}"
printf '{"timestamp":"%s","event":"%s","tag":"%s"%s}\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$event" "$BACKUP_TAG" "$extra"
}
heartbeat() {
local outcome="$1"
[[ "$SKIP_HEARTBEAT" == "1" ]] && return 0
[[ -n "$HEALTHCHECK_URL" ]] || return 0
local url="${HEALTHCHECK_URL%/}"
[[ "$outcome" == "fail" ]] && url="$url/fail"
if ! curl --fail --silent --show-error \
--max-time 10 --retry 2 --retry-delay 2 \
--output /dev/null "$url"; then
echo "backup: heartbeat ping failed (run result is unaffected)" >&2
fi
}
fail() {
FAILURE="$*"
exit 1
}
on_exit() {
local status=$?
if ((status != 0)); then
find "$BACKUP_DIR" -maxdepth 1 -name '*.partial' -delete 2>/dev/null || true
log_event backup.failed ",\"reason\":\"${FAILURE:-exit $status}\""
heartbeat fail
fi
exit "$status"
}
trap on_exit EXIT
trap 'exit 143' TERM INT
if [[ "${EUID:-$(id -u)}" -ne 0 ]]; then
fail "run as root"
fi
[[ "$BACKUP_TAG" =~ ^[a-z0-9]+$ ]] || fail "BACKUP_TAG may contain only lowercase letters and digits"
[[ "$MIN_FREE_MB" =~ ^[0-9]+$ ]] || fail "MIN_FREE_MB must be an integer"
[[ "$LOCAL_PLAINTEXT_DAYS" =~ ^[0-9]+$ ]] || fail "LOCAL_PLAINTEXT_DAYS must be an integer"
[[ "$LOCAL_ENCRYPTED_DAYS" =~ ^[0-9]+$ ]] || fail "LOCAL_ENCRYPTED_DAYS must be an integer"
[[ "$PREDEPLOY_KEEP" =~ ^[0-9]+$ ]] || fail "PREDEPLOY_KEEP must be an integer"
[[ "$LOCK_WAIT" =~ ^[0-9]+$ ]] || fail "LOCK_WAIT must be an integer"
[[ "$AGE_RECIPIENT" == age1* ]] || fail "AGE_RECIPIENT is not set to an age public key"
if [[ "$SKIP_HEARTBEAT" != "1" && -z "$HEALTHCHECK_URL" ]]; then
fail "HEALTHCHECK_URL is not set (set SKIP_HEARTBEAT=1 to skip the ping)"
fi
for cmd in docker flock curl age tar sha256sum; do
command -v "$cmd" >/dev/null 2>&1 || fail "missing command: $cmd"
done
install -d -m 0711 -o root -g root "$BACKUP_DIR"
install -d -m 0755 -o root -g root "$BACKUP_DIR/offsite"
# 0711 on the vault lets the workstation user traverse to offsite/ without
# being able to list the plaintext dumps.
chmod 0711 "$BACKUP_DIR"
chmod 0755 "$BACKUP_DIR/offsite"
exec 9>/run/lock/chesstrainer-backup.lock
if ! flock -w "$LOCK_WAIT" 9; then
if [[ "$LOCK_WAIT" == "0" ]]; then
# Overlapping timer/manual runs are not failures; the other run reports.
log_event backup.skipped ',"reason":"another backup is running"'
exit 0
fi
fail "another backup is still running"
fi
free_mb="$(df -Pm "$BACKUP_DIR" | awk 'NR == 2 { print $4 }')"
[[ "$free_mb" =~ ^[0-9]+$ ]] || fail "cannot read free space for $BACKUP_DIR"
if ((free_mb < MIN_FREE_MB)); then
fail "only ${free_mb}MB free on $BACKUP_DIR, need ${MIN_FREE_MB}MB"
fi
timestamp="$(date -u +%Y%m%dT%H%M%SZ)"
if [[ "$BACKUP_TAG" == "daily" ]]; then
prefix="$timestamp"
else
prefix="$timestamp-$BACKUP_TAG"
fi
dump="$BACKUP_DIR/$prefix.dump"
globals="$BACKUP_DIR/$prefix.globals.sql"
counts="$BACKUP_DIR/$prefix.counts"
checksums="$BACKUP_DIR/$prefix.sha256"
archive="$BACKUP_DIR/offsite/$prefix.tar.age"
# Row counts first: writes between this query and the dump can only push the
# restored counts up, so the drill treats this file as a lower bound.
read -r -d '' counts_sql <<'SQL' || true
select 'users=' || count(*) from users
union all select 'endgames=' || count(*) from endgames
union all select 'attempts=' || count(*) from attempts;
SQL
docker exec "$DB_CONTAINER" psql -U "$PG_USER" -d "$PG_DB" \
-At -v ON_ERROR_STOP=1 -c "$counts_sql" >"$counts.partial" ||
fail "row count query failed"
[[ -s "$counts.partial" ]] || fail "row count query returned nothing"
docker exec "$DB_CONTAINER" pg_dump -U "$PG_USER" -d "$PG_DB" -Fc \
>"$dump.partial" || fail "pg_dump failed"
[[ -s "$dump.partial" ]] || fail "pg_dump produced an empty file"
# pg_restore -l reads the archive header and table of contents. It needs the
# Postgres client matching the server, so run it inside the container.
docker exec -i "$DB_CONTAINER" pg_restore -l \
<"$dump.partial" >/dev/null || fail "pg_restore -l rejected the dump"
docker exec "$DB_CONTAINER" pg_dumpall -U "$PG_USER" --globals-only \
>"$globals.partial" || fail "pg_dumpall --globals-only failed"
[[ -s "$globals.partial" ]] || fail "globals dump is empty"
# shellcheck disable=SC2086 # EXPECTED_ROLES is a space-separated list
for role in $EXPECTED_ROLES; do
grep -Eq "^CREATE ROLE \"?${role}\"?( |;)" "$globals.partial" ||
fail "globals dump is missing role $role"
done
# Promote only after every check passes, so a broken dump never looks finished.
mv "$counts.partial" "$counts"
mv "$dump.partial" "$dump"
mv "$globals.partial" "$globals"
(
cd "$BACKUP_DIR"
sha256sum "${dump##*/}" "${globals##*/}" "${counts##*/}" >"${checksums##*/}"
)
tar -C "$BACKUP_DIR" -cf - \
"${dump##*/}" "${globals##*/}" "${counts##*/}" "${checksums##*/}" |
age --recipient "$AGE_RECIPIENT" --output "$archive.partial" ||
fail "encrypting the dump failed"
chmod 0644 "$archive.partial"
mv "$archive.partial" "$archive"
# ---------------------------------------------------------------------------
# Retention
# ---------------------------------------------------------------------------
aged() {
[[ -n "$(find "$1" -maxdepth 0 -mtime +"$2" -print -quit 2>/dev/null)" ]]
}
remove_plaintext_set() {
local prefix="$1"
rm -f -- \
"$BACKUP_DIR/$prefix.dump" \
"$BACKUP_DIR/$prefix.globals.sql" \
"$BACKUP_DIR/$prefix.counts" \
"$BACKUP_DIR/$prefix.sha256"
}
prune_plaintext_by_age() {
local dump base prefix
while IFS= read -r dump; do
base="${dump##*/}"
prefix="${base%%.*}"
[[ "$base" == *-predeploy.dump ]] && continue
if aged "$dump" "$LOCAL_PLAINTEXT_DAYS"; then
echo "backup: pruning $prefix (plaintext older than ${LOCAL_PLAINTEXT_DAYS}d)" >&2
remove_plaintext_set "$prefix"
fi
done < <(find "$BACKUP_DIR" -maxdepth 1 -type f -name '*.dump')
}
prune_predeploy_plaintext() {
local -a dumps
local i prefix
mapfile -t dumps < <(
find "$BACKUP_DIR" -maxdepth 1 -type f -name '*-predeploy.dump' -printf '%f\n' | sort -r
)
for ((i = PREDEPLOY_KEEP; i < ${#dumps[@]}; i++)); do
prefix="${dumps[i]%%.*}"
echo "backup: pruning $prefix (keeping last ${PREDEPLOY_KEEP} pre-deploy dumps)" >&2
remove_plaintext_set "$prefix"
done
}
prune_encrypted() {
local archive
while IFS= read -r archive; do
echo "backup: pruning ${archive##*/} (encrypted older than ${LOCAL_ENCRYPTED_DAYS}d)" >&2
rm -f -- "$archive"
done < <(
find "$BACKUP_DIR/offsite" -maxdepth 1 -type f -name '*.tar.age' -mtime +"$LOCAL_ENCRYPTED_DAYS"
)
}
prune_plaintext_by_age
prune_predeploy_plaintext
prune_encrypted
dump_bytes="$(stat -c %s "$dump")"
archive_bytes="$(stat -c %s "$archive")"
log_event backup.completed ",\"dump\":\"$prefix\",\"dump_bytes\":$dump_bytes,\"offsite_bytes\":$archive_bytes,\"duration_s\":$((SECONDS - START_SECONDS))"
heartbeat ok
+33
View File
@@ -0,0 +1,33 @@
# /etc/chesstrainer/backup.env -- root:root, mode 0600.
#
# Sourced by /usr/local/sbin/chesstrainer-backup. Every value below shows the
# default; only AGE_RECIPIENT and HEALTHCHECK_URL must be set. Keep secrets out
# of the repo and out of world-readable files.
# age public key, generated on the workstation with `age-keygen`.
# The private key never leaves the workstation.
AGE_RECIPIENT=age1...
# healthchecks.io (or compatible) ping URL. The script pings it after a good
# run and pings <url>/fail after a bad one. Set SKIP_HEARTBEAT=1 to run without
# monitoring (testing only).
HEALTHCHECK_URL=https://hc-ping.com/00000000-0000-0000-0000-000000000000
# Refuse to dump when the filesystem has less than this much free space.
MIN_FREE_MB=2048
# Retention. Dumps and their globals/counts/checksum siblings disappear as a
# set; only the encrypted archives in offsite/ live for the longer window.
LOCAL_PLAINTEXT_DAYS=3
LOCAL_ENCRYPTED_DAYS=14
PREDEPLOY_KEEP=5
# Postgres coordinates. The container trusts local Unix-socket connections, so
# no password belongs here.
DB_CONTAINER=chesstrainer-db
PG_USER=chesstrainer
PG_DB=chesstrainer_prod
BACKUP_DIR=/var/backups/chesstrainer
# Roles the globals dump must be able to recreate.
EXPECTED_ROLES="chesstrainer chesstrainer_ro"
@@ -0,0 +1,7 @@
[Unit]
Description=Report a failed Inner Square Chess database backup
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Service]
Type=oneshot
ExecStart=/usr/bin/logger --tag chesstrainer-backup --priority daemon.err --stderr backup.unit-failed: chesstrainer-backup.service failed, see journalctl -u chesstrainer-backup
+16
View File
@@ -0,0 +1,16 @@
[Unit]
Description=Inner Square Chess database backup
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
After=network-online.target docker.service
Wants=network-online.target
OnFailure=chesstrainer-backup-failure.service
[Service]
Type=oneshot
User=root
Group=root
ExecStart=/usr/local/sbin/chesstrainer-backup
Nice=10
IOSchedulingClass=idle
TimeoutStartSec=10min
SyslogIdentifier=chesstrainer-backup
+13
View File
@@ -0,0 +1,13 @@
[Unit]
Description=Daily Inner Square Chess database backup
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Timer]
OnCalendar=*-*-* 03:15:00 UTC
RandomizedDelaySec=5m
AccuracySec=1m
Persistent=true
Unit=chesstrainer-backup.service
[Install]
WantedBy=timers.target
@@ -0,0 +1,11 @@
[Unit]
Description=Refresh Cloudflare CIDRs for Caddy
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/docs/security.md
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
ExecStart=/usr/local/sbin/chesstrainer-update-cloudflare-ranges
TimeoutStartSec=2min
Nice=10
@@ -0,0 +1,11 @@
[Unit]
Description=Hourly refresh of Cloudflare CIDRs for Caddy
[Timer]
OnCalendar=hourly
RandomizedDelaySec=10m
Persistent=true
Unit=chesstrainer-cloudflare-ranges.service
[Install]
WantedBy=timers.target
+13
View File
@@ -0,0 +1,13 @@
[Unit]
Description=Probe the public Inner Square Chess app and report to healthchecks.io
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
After=network-online.target
Wants=network-online.target
[Service]
Type=oneshot
User=root
Group=root
ExecStart=/usr/local/sbin/chesstrainer-probe
TimeoutStartSec=90s
SyslogIdentifier=chesstrainer-probe
+12
View File
@@ -0,0 +1,12 @@
[Unit]
Description=Probe the public Inner Square Chess app every two minutes
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Timer]
OnBootSec=30s
OnUnitActiveSec=2min
AccuracySec=5s
Unit=chesstrainer-probe.service
[Install]
WantedBy=timers.target
+3
View File
@@ -0,0 +1,3 @@
# Generated by deploy/update-cloudflare-ranges.sh.
# Source: https://www.cloudflare.com/ips-v4 and /ips-v6
remote_ip 173.245.48.0/20 103.21.244.0/22 103.22.200.0/22 103.31.4.0/22 141.101.64.0/18 108.162.192.0/18 190.93.240.0/20 188.114.96.0/20 197.234.240.0/22 198.41.128.0/17 162.158.0.0/15 104.16.0.0/13 104.24.0.0/14 172.64.0.0/13 131.0.72.0/22 2400:cb00::/32 2606:4700::/32 2803:f800::/32 2405:b500::/32 2405:8100::/32 2a06:98c0::/29 2c0f:f248::/32
+2 -2
View File
@@ -3,12 +3,12 @@
#
# Pin the Postgres image directly in the unified file. Replace the tag with
# an exact digest if you want immutable image pinning:
# image: postgres:18.0@sha256:...
# image: postgres:18.6@sha256:...
services:
chesstrainer-db:
container_name: chesstrainer-db
image: postgres:18.0
image: postgres:18.6
restart: unless-stopped
env_file: /etc/chesstrainer/postgres.env
ports:
Executable
+359
View File
@@ -0,0 +1,359 @@
#!/usr/bin/env bash
#
# Probe the public Inner Square Chess app and report the verdict to
# healthchecks.io.
#
# Installed as /usr/local/sbin/chesstrainer-probe (root-owned 0755) and run by
# chesstrainer-probe.timer every two minutes. The probe deliberately goes
# through the public hostname, not loopback: DNS, Cloudflare, Caddy and the
# origin allowlist are part of what a visitor depends on. A loopback health
# URL is still consulted on failure, as evidence only.
#
# sudo /usr/local/sbin/chesstrainer-probe
# sudo /usr/local/sbin/chesstrainer-probe --dry-run # no network, no config
#
# Configuration lives in /etc/chesstrainer/probe.env (root:root 0600). See
# deploy/README.md §Monitoring and alerting. Individual settings can be passed
# as environment variables to a manual run, which is how the drills vary the
# URL and the expected tablebase.
#
# Each run prints exactly one JSON line (probe.ok, probe.degraded or
# probe.failed) so journald, and #140's log shipping, can pick it up.
set -euo pipefail
umask 077
ENV_FILE="${ENV_FILE:-/etc/chesstrainer/probe.env}"
START_SECONDS=$SECONDS
DRY_RUN=0
TMPDIR_PROBE=""
HTTP_BODY_FILE=""
HTTP_HEADER_FILE=""
HTTP_ERROR_FILE=""
usage() {
cat <<'EOF'
Usage: chesstrainer-probe [--dry-run]
--dry-run print the verdict for the success, degraded, fail, non-JSON and
unreachable fixtures without reading the env file or making a
network request
EOF
}
while (($# > 0)); do
case "$1" in
--dry-run) DRY_RUN=1 ;;
-h | --help)
usage
exit 0
;;
*)
usage >&2
echo "probe: unknown argument: $1" >&2
exit 2
;;
esac
shift
done
log_event() {
local event="$1"
local extra="${2:-}"
printf '{"timestamp":"%s","event":"%s"%s}\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$event" "$extra"
}
fail() {
echo "probe: $*" >&2
exit 1
}
json_escape() {
local text="$1"
text="${text//\\/\\\\}"
text="${text//\"/\\\"}"
text="${text//$'\n'/\\n}"
text="${text//$'\r'/\\r}"
text="${text//$'\t'/\\t}"
text="$(printf '%s' "$text" | LC_ALL=C tr -d '[:cntrl:]')"
printf '%s' "$text"
}
body_snippet() {
local file="$1"
if [[ -s "$file" ]]; then
head -c "$MAX_BODY_BYTES" "$file"
fi
}
json_field() {
local key="$1"
local json="$2"
if [[ "$json" =~ \"$key\"[[:space:]]*:[[:space:]]*\"([^\"]*)\" ]]; then
printf '%s' "${BASH_REMATCH[1]}"
fi
}
http_get() {
local url="$1"
local prefix="$2"
local proto="$3"
local status=""
local exit_code=0
HTTP_BODY_FILE="$prefix.body"
HTTP_HEADER_FILE="$prefix.headers"
HTTP_ERROR_FILE="$prefix.error"
: >"$HTTP_BODY_FILE"
: >"$HTTP_HEADER_FILE"
: >"$HTTP_ERROR_FILE"
if status="$(curl --silent --show-error --location \
--proto "$proto" \
--connect-timeout 5 \
--max-time "$PROBE_TIMEOUT_SECONDS" \
--output "$HTTP_BODY_FILE" \
--dump-header "$HTTP_HEADER_FILE" \
--write-out '%{http_code}' \
"$url")"; then
exit_code=0
else
exit_code=$?
fi
HTTP_STATUS="${status:-000}"
CURL_EXIT="$exit_code"
}
# Sets VERDICT (ok, degraded, failed), REASON, DB and TABLEBASE. The database is
# the only hard dependency; a missing local tablebase still serves users from
# Lichess, so it is reported as a green but degraded check-in.
evaluate() {
local status="$1"
local exit_code="$2"
local body="$3"
local trimmed=""
VERDICT="failed"
REASON=""
DB=""
TABLEBASE=""
if ((exit_code != 0)); then
REASON="unreachable: curl exit $exit_code"
return
fi
if [[ "$status" != "200" ]]; then
REASON="http $status"
return
fi
trimmed="${body#"${body%%[![:space:]]*}"}"
trimmed="${trimmed%"${trimmed##*[![:space:]]}"}"
if [[ "${trimmed:0:1}" != "{" || "${trimmed: -1}" != "}" ]]; then
REASON="non-JSON response"
return
fi
DB="$(json_field db "$body")"
TABLEBASE="$(json_field tablebase "$body")"
if [[ -z "$DB" ]]; then
REASON="response has no db field"
return
fi
if [[ "$DB" != "ok" ]]; then
REASON="db is $DB"
return
fi
if [[ "$EXPECT_TABLEBASE" != "any" && "$TABLEBASE" != "$EXPECT_TABLEBASE" ]]; then
VERDICT="degraded"
REASON="tablebase is ${TABLEBASE:-unknown}, expected $EXPECT_TABLEBASE"
return
fi
VERDICT="ok"
}
# Exactly one call site per run, and one call site per outcome, so a forced
# failure can only ever produce one fail ping.
ping_check() {
local outcome="$1"
local body="$2"
local url=""
local body_file=""
if [[ -z "$HEALTHCHECK_URL" ]]; then
echo "probe: HEALTHCHECK_URL is not set, not reporting" >&2
return 0
fi
url="${HEALTHCHECK_URL%/}"
if [[ "$outcome" == "fail" ]]; then
url="$url/fail"
fi
body_file="$(mktemp)"
printf '%s' "$body" >"$body_file"
if ! curl --silent --show-error --fail \
--max-time 10 --retry 2 --retry-delay 2 \
--header 'Content-Type: application/json' \
--data-binary "@$body_file" \
--output /dev/null "$url"; then
echo "probe: check-in ping failed (run result is unaffected)" >&2
fi
rm -f "$body_file"
}
origin_evidence() {
local prefix="$1"
http_get "$ORIGIN_URL" "$prefix" '=https,http'
ORIGIN_STATUS="$HTTP_STATUS"
ORIGIN_EXIT="$CURL_EXIT"
ORIGIN_BODY="$(body_snippet "$HTTP_BODY_FILE")"
ORIGIN_ERROR="$(body_snippet "$HTTP_ERROR_FILE")"
}
fail_evidence() {
local evidence=""
evidence="$(printf '{"probe":"failed","reason":"%s","url":"%s","http_status":"%s","curl_exit":%s' \
"$(json_escape "$REASON")" "$(json_escape "$PROBE_URL")" "$PUBLIC_STATUS" "$PUBLIC_EXIT")"
if [[ -n "$ERROR_TEXT" ]]; then
evidence+="$(printf ',"error":"%s"' "$(json_escape "$ERROR_TEXT")")"
fi
if [[ -n "$BODY" ]]; then
evidence+="$(printf ',"body":"%s"' "$(json_escape "$BODY")")"
fi
evidence+="$(printf ',"origin_url":"%s","origin_status":"%s","origin_curl_exit":%s' \
"$(json_escape "$ORIGIN_URL")" "$ORIGIN_STATUS" "$ORIGIN_EXIT")"
if [[ -n "$ORIGIN_BODY" ]]; then
evidence+="$(printf ',"origin_body":"%s"' "$(json_escape "$ORIGIN_BODY")")"
fi
if [[ -n "$ORIGIN_ERROR" ]]; then
evidence+="$(printf ',"origin_error":"%s"' "$(json_escape "$ORIGIN_ERROR")")"
fi
printf '%s}' "$evidence"
}
dry_run() {
local -a scenarios=(
'HTTP 200, healthy|200|0|{"process":"ok","status":"ok","db":"ok","tablebase":"local"}'
'HTTP 200, tablebase fallback|200|0|{"process":"ok","status":"degraded","db":"ok","tablebase":"fallback"}'
'HTTP 503, db down|503|0|{"process":"ok","status":"down","db":"down","tablebase":"local"}'
'HTTP 200, non-JSON|200|0|<html><body>502 Bad Gateway</body></html>'
'timeout, no response|000|28|'
)
local row name status exit_code body action
printf 'probe: dry run, no network calls and no configuration read\n'
printf 'probe: every fixture is evaluated with EXPECT_TABLEBASE=local\n\n'
printf '%-28s %-9s %-46s %s\n' "scenario" "verdict" "reason" "would ping"
for row in "${scenarios[@]}"; do
IFS='|' read -r name status exit_code body <<<"$row"
EXPECT_TABLEBASE="local"
evaluate "$status" "$exit_code" "$body"
case "$VERDICT" in
ok) action="success, raw /health JSON" ;;
degraded) action="success, mismatch evidence" ;;
*) action="fail, evidence JSON" ;;
esac
printf '%-28s %-9s %-46s %s\n' "$name" "$VERDICT" "${REASON:--}" "$action"
done
printf '\nprobe: dry run complete, no check-ins sent\n'
}
if ((DRY_RUN)); then
dry_run
exit 0
fi
# Overrides passed on the command line survive the env file, so the drills can
# vary the URL or the expected tablebase without editing a root-only file.
_OVERRIDE_PROBE_URL="${PROBE_URL:-}"
_OVERRIDE_EXPECT_TABLEBASE="${EXPECT_TABLEBASE:-}"
_OVERRIDE_PROBE_TIMEOUT_SECONDS="${PROBE_TIMEOUT_SECONDS:-}"
if [[ -r "$ENV_FILE" ]]; then
# shellcheck disable=SC1090
source "$ENV_FILE"
else
fail "cannot read $ENV_FILE (set ENV_FILE to override)"
fi
PROBE_URL="${_OVERRIDE_PROBE_URL:-${PROBE_URL:-}}"
EXPECT_TABLEBASE="${_OVERRIDE_EXPECT_TABLEBASE:-${EXPECT_TABLEBASE:-local}}"
PROBE_TIMEOUT_SECONDS="${_OVERRIDE_PROBE_TIMEOUT_SECONDS:-${PROBE_TIMEOUT_SECONDS:-10}}"
HEALTHCHECK_URL="${HEALTHCHECK_URL:-}"
ORIGIN_URL="${ORIGIN_URL:-http://127.0.0.1:4100/health}"
MAX_BODY_BYTES="${MAX_BODY_BYTES:-2000}"
[[ "$PROBE_URL" == https://* ]] || fail "PROBE_URL must be an https URL"
[[ -n "$HEALTHCHECK_URL" ]] || fail "HEALTHCHECK_URL is not set"
[[ "$EXPECT_TABLEBASE" =~ ^(local|fallback|not_configured|any)$ ]] ||
fail "EXPECT_TABLEBASE must be local, fallback, not_configured or any"
[[ "$PROBE_TIMEOUT_SECONDS" =~ ^[0-9]+$ ]] || fail "PROBE_TIMEOUT_SECONDS must be an integer"
command -v curl >/dev/null 2>&1 || fail "missing command: curl"
TMPDIR_PROBE="$(mktemp -d)"
cleanup() {
if [[ -n "$TMPDIR_PROBE" && -d "$TMPDIR_PROBE" ]]; then
rm -rf "$TMPDIR_PROBE"
fi
}
trap cleanup EXIT
trap 'exit 143' TERM INT
http_get "$PROBE_URL" "$TMPDIR_PROBE/public" '=https'
PUBLIC_STATUS="$HTTP_STATUS"
PUBLIC_EXIT="$CURL_EXIT"
BODY="$(body_snippet "$HTTP_BODY_FILE")"
ERROR_TEXT="$(body_snippet "$HTTP_ERROR_FILE")"
evaluate "$PUBLIC_STATUS" "$PUBLIC_EXIT" "$BODY"
case "$VERDICT" in
ok)
log_event probe.ok ",\"status\":\"$PUBLIC_STATUS\",\"tablebase\":\"$(json_escape "$TABLEBASE")\",\"duration_s\":$((SECONDS - START_SECONDS))"
ping_check ok "$BODY"
;;
degraded)
evidence="$(printf '{"expected_tablebase":"%s","health":%s}' \
"$(json_escape "$EXPECT_TABLEBASE")" "$BODY")"
log_event probe.degraded ",\"reason\":\"$(json_escape "$REASON")\",\"tablebase\":\"$(json_escape "$TABLEBASE")\",\"duration_s\":$((SECONDS - START_SECONDS))"
ping_check ok "$evidence"
;;
*)
origin_evidence "$TMPDIR_PROBE/origin"
evidence="$(fail_evidence)"
log_event probe.failed ",\"reason\":\"$(json_escape "$REASON")\",\"http_status\":\"$PUBLIC_STATUS\",\"curl_exit\":$PUBLIC_EXIT,\"duration_s\":$((SECONDS - START_SECONDS))"
ping_check fail "$evidence"
exit 1
;;
esac
+28
View File
@@ -0,0 +1,28 @@
# /etc/chesstrainer/probe.env -- root:root, mode 0600.
#
# Sourced by /usr/local/sbin/chesstrainer-probe. The check-in URL is a secret:
# anyone who has it can mark the check green, so keep it out of the repo and
# out of world-readable files.
# The public URL a visitor actually requests. Probing the edge rather than
# loopback is deliberate: DNS, TLS, Cloudflare, Caddy and the origin allowlist
# are part of the contract. Must be https.
PROBE_URL=https://innersquare.app/health
# healthchecks.io ping URL for the two-minute probe check. A healthy run posts
# to it; a failed run posts to <url>/fail.
HEALTHCHECK_URL=https://hc-ping.com/00000000-0000-0000-0000-000000000000
# The tablebase value /health should report. "local" means Syzygy files are
# loaded, "fallback" means Lichess is used, "not_configured" means
# TABLEBASE_PATH is unset. A mismatch is reported as degraded, never as down.
# Set to "any" to accept whatever the app reports.
EXPECT_TABLEBASE=local
# Whole-request timeout. The timer runs every two minutes, so keep this well
# under that.
PROBE_TIMEOUT_SECONDS=10
# Loopback health URL. It is consulted only when the public probe fails, and
# only as evidence: it does not change the verdict. Defaults to the value shown.
# ORIGIN_URL=http://127.0.0.1:4100/health
+4 -2
View File
@@ -9,6 +9,7 @@ deploy/static/
├── index.html # page + inline CSS; uses the app's real brand tokens
├── privacy.html # privacy policy, served at /privacy
├── terms-conditions.html # terms, served at /terms-conditions
├── mentions-legales.html # French legal notice, served at /mentions-legales
├── legal.css # shared styles for the legal pages
├── fonts/ # DM Sans + DM Serif Display woff2 files
├── favicon.ico # copied from priv/static
@@ -17,8 +18,9 @@ deploy/static/
└── README.md
```
The Caddyfile uses `try_files {path}.html {path}` so `/privacy` and
`/terms-conditions` serve the matching `.html` files without a redirect.
The Caddyfile uses `try_files {path}.html {path}` so `/privacy`,
`/terms-conditions`, and `/mentions-legales` serve the matching `.html` files
without a redirect.
## Preview locally
Binary file not shown.

Before

Width:  |  Height:  |  Size: 152 B

After

Width:  |  Height:  |  Size: 15 KiB

+1
View File
@@ -699,6 +699,7 @@
<nav class="footer-links" aria-label="Legal">
<a href="/privacy">Privacy</a>
<a href="/terms-conditions">Terms</a>
<a href="/mentions-legales">Mentions légales</a>
</nav>
<small>&copy; 2026 Inner Square Chess</small>
</footer>
+22
View File
@@ -201,6 +201,28 @@ main {
opacity: 0.75;
}
.analytics-buttons {
display: flex;
flex-wrap: wrap;
gap: 12px;
margin-top: 16px;
}
.analytics-buttons button {
padding: 10px 16px;
border: 1px solid var(--color-hairline);
border-radius: 8px;
background: var(--color-canvas-raised);
color: var(--color-body);
font: inherit;
font-weight: 600;
cursor: pointer;
}
.analytics-buttons button:hover {
background: var(--color-canvas);
}
.site-footer {
width: min(1180px, calc(100% - 48px));
margin: 0 auto;
+108
View File
@@ -0,0 +1,108 @@
<!doctype html>
<html lang="fr">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Mentions légales — Inner Square Chess</title>
<meta
name="description"
content="Éditeur, hébergeur et informations légales du site Inner Square Chess."
/>
<meta name="robots" content="noindex, nofollow" />
<meta name="theme-color" content="#f4f0e6" />
<meta property="og:type" content="website" />
<meta property="og:site_name" content="Inner Square Chess" />
<meta property="og:title" content="Mentions légales — Inner Square Chess" />
<meta
property="og:description"
content="Éditeur, hébergeur et informations légales du site Inner Square Chess."
/>
<meta name="twitter:card" content="summary" />
<link rel="icon" href="/favicon.ico" />
<link rel="stylesheet" href="/legal.css" />
</head>
<body>
<header>
<nav class="nav-wrap" aria-label="Main navigation">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<span class="status">Launching soon</span>
</nav>
</header>
<main id="main-content">
<article class="legal" lang="fr">
<h1>Mentions légales</h1>
<p class="legal-meta">Dernière mise à jour : 10 novembre 2026</p>
<p>
Ces mentions sont publiées en application de l'article 6-III de la loi
n° 2004-575 du 21 juin 2004 pour la confiance dans l'économie numérique.
</p>
<h2>Éditeur du site</h2>
<p>
Le site <a href="/">innersquare.app</a>, édité sous le nom commercial
«&nbsp;Inner Square Chess&nbsp;», est édité par&nbsp;:
</p>
<ul>
<li><strong>Owen REES</strong>, entrepreneur individuel (EI)</li>
<li>Adresse&nbsp;: [adresse à compléter]</li>
<li>SIRET&nbsp;: 929 553 774 00019</li>
<li>Téléphone&nbsp;: <a href="tel:+33683019513">+33 6 83 01 95 13</a></li>
<li>
Courriel&nbsp;:
<a href="mailto:support@innersquare.app">support@innersquare.app</a>
</li>
<li>TVA non applicable, article 293 B du Code général des impôts.</li>
</ul>
<h2>Directeur de la publication</h2>
<p>Owen REES.</p>
<h2>Hébergeur</h2>
<p>
Hetzner Online GmbH<br />
Industriestraße 25<br />
91710 Gunzenhausen<br />
Allemagne<br />
Téléphone&nbsp;: <a href="tel:+4998315050">+49 9831 505-0</a>
</p>
<h2>Propriété intellectuelle</h2>
<p>
Les contenus du site — textes, interface, code, éléments graphiques, ainsi
que les positions et solutions d'échecs — sont protégés par le droit
d'auteur et restent la propriété de l'éditeur ou de ses concédants. Toute
reproduction ou réutilisation non autorisée est interdite.
</p>
<h2>Données personnelles</h2>
<p>
Les données traitées, les finalités, les durées de conservation et vos
droits sont décrits dans la
<a href="/privacy">politique de confidentialité</a>, disponible en anglais.
</p>
</article>
</main>
<footer class="site-footer">
<div class="footer-brand">
<a class="brand" href="/" aria-label="Inner Square Chess home">
<span class="brand-mark" aria-hidden="true">♞</span>
<span>INNERSQUARE</span>
</a>
<p>Short, focused endgame training.</p>
</div>
<nav class="footer-links" aria-label="Legal">
<a href="/privacy">Privacy</a>
<a href="/terms-conditions">Terms</a>
<a href="/mentions-legales">Mentions légales</a>
</nav>
<small>&copy; 2026 Inner Square Chess</small>
</footer>
</body>
</html>
+161 -23
View File
@@ -36,7 +36,7 @@
<main id="main-content">
<article class="legal">
<h1>Privacy Policy</h1>
<p class="legal-meta">Last updated: 6 November 2026</p>
<p class="legal-meta">Last updated: 10 November 2026</p>
<p>
Inner Square Chess is an endgame training site. This policy explains what
@@ -45,6 +45,17 @@
guest trainer.
</p>
<h2>Data controller</h2>
<p>
The controller responsible for your personal information is Owen REES,
an entrepreneur individuel (EI) established in France, trading as
Inner Square Chess. Our business register number (SIRET) is
929&nbsp;553&nbsp;774&nbsp;00019. You can contact us about anything in
this policy, or about your data, at
<a href="mailto:support@innersquare.app">support@innersquare.app</a>
or <a href="tel:+33683019513">+33 6 83 01 95 13</a>.
</p>
<h2>What we collect</h2>
<ul>
<li>
@@ -66,9 +77,18 @@
</li>
<li>
<strong>Technical data.</strong>
Our hosting and server infrastructure may keep standard request logs
(IP address, browser, timestamps) for security and troubleshooting.
These logs are rotated regularly.
We do not keep our own access logs. The companies that host the site
and run our content delivery network keep short-lived request logs
(IP address, browser, timestamps) for security, abuse prevention, and
troubleshooting, under their own retention policies.
</li>
<li>
<strong>Usage data.</strong>
On public pages and the guest trainer, we use a self-hosted Matomo
instance to understand aggregate usage. Matomo is configured without
cookies, with IP addresses shortened before storage, and to respect
Do Not Track. We do not use user IDs, track signed-in account pages,
or share this data with third parties.
</li>
<li>
<strong>Messages you send us.</strong>
@@ -85,20 +105,56 @@
<ul>
<li>a session cookie that keeps you signed in;</li>
<li>a CSRF token that protects forms from cross-site requests;</li>
<li>
a security cookie that our content delivery network, Cloudflare, may
set when it checks that a request is not automated abuse;
</li>
<li>a colour-mode preference stored in your browser.</li>
<li>
an analytics opt-out preference stored in your browser's local
storage, if you choose to opt out.
</li>
</ul>
<p>
We do not use advertising cookies, third-party analytics, or cross-site
tracking. You can clear these entries at any time in your browser
settings; doing so will sign you out and reset your colour mode.
We do not use advertising cookies, analytics cookies, or cross-site
tracking. The only cookie not set by this site is Cloudflare's security
check described above; our analytics is self-hosted Matomo and is
configured without cookies. You can clear these entries at any time in
your browser settings; doing so will sign you out, reset your colour
mode, and reset your analytics preference.
</p>
<h2>Analytics</h2>
<p>
We use a self-hosted Matomo instance at
<a href="https://analytics.owenrees.eu/">analytics.owenrees.eu</a>
to understand aggregate use of the public site and guest trainer. It is
configured without cookies, with IP addresses shortened before storage,
and to respect Do Not Track. We do not use user IDs, track signed-in
account pages, or share this data with third parties.
</p>
<p>
Raw analytics data is retained for up to 180 days. We process it on the
basis of our legitimate interests in improving the service. You can
object at any time using the control below or by emailing
<a href="mailto:support@innersquare.app">support@innersquare.app</a>.
</p>
<p id="analytics-status">Analytics is currently on in this browser.</p>
<div class="analytics-buttons">
<button id="analytics-opt-out" type="button">Opt out of analytics</button>
<button id="analytics-opt-in" type="button" hidden>Opt back in</button>
</div>
<h2>How we use your information</h2>
<ul>
<li>To create and secure your account and sign you in.</li>
<li>To run the trainer and remember your progress.</li>
<li>To send service emails, such as confirmation and password reset links.</li>
<li>To send occasional endgame tips and site news, if you opted in.</li>
<li>
To understand aggregate use of the public site and guest trainer, and
improve the service.
</li>
<li>To keep the site available, prevent abuse, and fix faults.</li>
<li>To respond when you ask for help.</li>
</ul>
@@ -130,13 +186,41 @@
to object to this processing; to do so, contact us using the address below.
</p>
<h2 id="hosting-and-infrastructure">Hosting and infrastructure</h2>
<p>
The site runs on a virtual private server operated for us by Hetzner
inside the European Union. Our database runs on the same server, our
transactional email is sent through Amazon SES in the EU, and our
self-hosted Matomo analytics runs on infrastructure we control in the
EU.
</p>
<p>
We also use Cloudflare as our content delivery network and security
proxy. Because Cloudflare sits between your browser and our server, it
processes your IP address, the requested URL, and request headers.
Cloudflare is a US company, so that request data may be transferred
outside the UK and EEA. The transfer relies on the EU–US Data Privacy
Framework and standard contractual clauses. Cloudflare and Hetzner each
keep their own logs under their own retention policies; we do not
receive or keep them.
</p>
<p>
These providers act as our processors under data protection law. We
share with them only what they need to run the service, and we remain
responsible for how your information is handled.
</p>
<h2>Sharing</h2>
<p>
We do not sell your personal information. We share it only with providers
who help us run the site — for example hosting, database, and email
delivery providers — and only as far as they need it to perform that work.
We may also disclose information where the law requires it or to protect
the rights and safety of our users.
We do not sell your personal information. We share it only with the
providers described under
<a href="#hosting-and-infrastructure">hosting and infrastructure</a>
— our hosting, content delivery, database, and email delivery providers
— and only as far as they need it to perform that work. Self-hosted
Matomo analytics is operated by us on infrastructure we control; we do
not share that data with third parties. We may also disclose
information where the law requires it or to protect the rights and
safety of our users.
</p>
<h2>Retention</h2>
@@ -144,23 +228,28 @@
We keep account and training data while your account is open. If you
delete your account, we remove your personal information within a
reasonable period, except where we must keep records for legal, security,
or accounting reasons.
or accounting reasons. We retain raw analytics data for up to 180 days.
</p>
<p>
Two exceptions are worth naming. If you unsubscribe from the mailing
list, or ask us not to email you, we keep your address on a suppression
list so that we do not contact you again; we hold only what is needed to
recognise the address. We also keep database backups for disaster
recovery, stored off the primary server, so a deleted account may remain
in a backup for some time after deletion. We do not use backups to
restore individual accounts, and we delete them once they are no longer
needed.
</p>
<h2>Your rights</h2>
<p>
Depending on where you live, you may have the right to access, correct,
delete, restrict, or export your personal information, and to object to
some uses of it. To make a request, contact us using the address below. If
you are in the UK or EU and are unhappy with our response, you can complain
to your local data protection authority.
</p>
<h2>Children</h2>
<p>
The service is not directed at children under 13, and we do not knowingly
collect their personal information. If you believe a child has created an
account, contact us and we will remove it.
some uses of it. You can object to analytics processing at any time using
the control on this page or by contacting us. To make a request, contact
us using the address below. If you are in the UK or EU and are unhappy
with our response, you can complain to your local data protection
authority.
</p>
<h2>Changes</h2>
@@ -189,8 +278,57 @@
<nav class="footer-links" aria-label="Legal">
<a href="/privacy">Privacy</a>
<a href="/terms-conditions">Terms</a>
<a href="/mentions-legales">Mentions légales</a>
</nav>
<small>&copy; 2026 Inner Square Chess</small>
</footer>
<script>
(function () {
var key = "matomo_optout";
var optOut = document.getElementById("analytics-opt-out");
var optIn = document.getElementById("analytics-opt-in");
var status = document.getElementById("analytics-status");
function optedOut() {
try {
return localStorage.getItem(key) === "1";
} catch (error) {
return true;
}
}
function update() {
var off = optedOut();
if (optOut) optOut.hidden = off;
if (optIn) optIn.hidden = !off;
if (status) {
status.textContent = off
? "Analytics is currently off in this browser."
: "Analytics is currently on in this browser.";
}
}
if (optOut) {
optOut.addEventListener("click", function () {
try {
localStorage.setItem(key, "1");
} catch (error) {}
update();
});
}
if (optIn) {
optIn.addEventListener("click", function () {
try {
localStorage.removeItem(key);
} catch (error) {}
update();
});
}
update();
})();
</script>
</body>
</html>
+12 -1
View File
@@ -36,13 +36,19 @@
<main id="main-content">
<article class="legal">
<h1>Terms &amp; Conditions</h1>
<p class="legal-meta">Last updated: 6 November 2026</p>
<p class="legal-meta">Last updated: 10 November 2026</p>
<p>
These terms govern your use of Inner Square Chess. By browsing the site,
using the guest trainer, or creating an account, you agree to them. If you
do not agree, please do not use the service.
</p>
<p>
Inner Square Chess is operated by Owen REES, entrepreneur individuel (EI),
established in France, business register number (SIRET)
929&nbsp;553&nbsp;774&nbsp;00019. Full publisher details are on the
<a href="/mentions-legales">mentions légales</a> page.
</p>
<h2>The service</h2>
<p>
@@ -60,6 +66,10 @@
<h2>Accounts</h2>
<ul>
<li>You must be at least 13 years old to create an account.</li>
<li>
If you are under 16 and in the UK or EU, you may only use an account
with the consent of a parent or guardian.
</li>
<li>Give accurate information and keep it up to date.</li>
<li>Keep your password private and tell us promptly about unauthorised use.</li>
<li>You are responsible for activity that happens under your account.</li>
@@ -163,6 +173,7 @@
<nav class="footer-links" aria-label="Legal">
<a href="/privacy">Privacy</a>
<a href="/terms-conditions">Terms</a>
<a href="/mentions-legales">Mentions légales</a>
</nav>
<small>&copy; 2026 Inner Square Chess</small>
</footer>
+115
View File
@@ -0,0 +1,115 @@
#!/usr/bin/env bash
#
# Refresh Caddy's Cloudflare origin allowlist from Cloudflare's published
# ranges. Called by chesstrainer-cloudflare-ranges.timer.
#
# The generated file is imported by /etc/caddy/Caddyfile:
#
# @cloudflare {
# import cloudflare-ranges.caddy
# }
#
# The script validates the candidate Caddyfile before reloading Caddy. If the
# download or validation fails, the previous ranges stay in place.
set -euo pipefail
CADDYFILE="${CADDYFILE:-/etc/caddy/Caddyfile}"
RANGES_FILE="${RANGES_FILE:-/etc/caddy/cloudflare-ranges.caddy}"
CADDY_BIN="${CADDY_BIN:-caddy}"
RELOAD_CMD="${RELOAD_CMD:-systemctl reload caddy}"
LOCK_FILE="${LOCK_FILE:-/run/lock/chesstrainer-cloudflare-ranges.lock}"
tmpdir="$(mktemp -d)"
trap 'rm -rf "$tmpdir"' EXIT
exec 9>"$LOCK_FILE"
if ! flock -n 9; then
echo "another Cloudflare range update is already running" >&2
exit 0
fi
fetch() {
local url="$1"
local output="$2"
curl --fail --silent --show-error --location \
--proto '=https' \
--retry 3 --retry-delay 2 --connect-timeout 10 \
"$url" --output "$output"
}
validate_download() {
local file="$1"
[[ -s "$file" ]] || return 1
# One CIDR per line. Caddy performs the real validation; this prevents
# obviously malformed or injected content from being written.
if grep -Evq '^[0-9A-Fa-f:.]+/[0-9]{1,3}$' "$file"; then
return 1
fi
}
fetch "https://www.cloudflare.com/ips-v4" "$tmpdir/ips-v4"
fetch "https://www.cloudflare.com/ips-v6" "$tmpdir/ips-v6"
validate_download "$tmpdir/ips-v4"
validate_download "$tmpdir/ips-v6"
ranges="$(awk 'NF { printf "%s ", $0 }' "$tmpdir/ips-v4" "$tmpdir/ips-v6" | sed -e 's/[[:space:]]*$//')"
if [[ -z "$ranges" ]]; then
echo "Cloudflare returned an empty CIDR list" >&2
exit 1
fi
candidate="$tmpdir/cloudflare-ranges.caddy"
{
echo "# Generated by deploy/update-cloudflare-ranges.sh."
echo "# Source: https://www.cloudflare.com/ips-v4 and /ips-v6"
echo "remote_ip $ranges"
} >"$candidate"
if cmp -s "$candidate" "$RANGES_FILE"; then
echo "Cloudflare ranges are unchanged"
exit 0
fi
install -d -m 0755 "$(dirname "$RANGES_FILE")"
backup="$tmpdir/previous-ranges.caddy"
if [[ -e "$RANGES_FILE" ]]; then
cp -a "$RANGES_FILE" "$backup"
fi
install -m 0644 "$candidate" "$RANGES_FILE"
if ! "$CADDY_BIN" validate --config "$CADDYFILE" --adapter caddyfile; then
echo "Caddy rejected the new Cloudflare ranges; restoring the previous file" >&2
if [[ -e "$backup" ]]; then
install -m 0644 "$backup" "$RANGES_FILE"
else
rm -f "$RANGES_FILE"
fi
exit 1
fi
read -r -a reload_command <<<"$RELOAD_CMD"
if ! "${reload_command[@]}"; then
echo "Caddy reload failed; restoring the previous ranges" >&2
if [[ -e "$backup" ]]; then
install -m 0644 "$backup" "$RANGES_FILE"
else
rm -f "$RANGES_FILE"
fi
exit 1
fi
echo "Cloudflare ranges updated and Caddy reloaded"
+190
View File
@@ -0,0 +1,190 @@
#!/usr/bin/env bash
#
# Restore the newest (or a named) archive into a throwaway Postgres container
# and prove that the dump, the roles and the row counts all came back.
#
# backup-drill # newest archive in DEST
# backup-drill 20261111T031500Z.tar.age
#
# Runs on the workstation. The production database is never contacted: the
# container is created and destroyed by this script. Results are appended to
# $DRILL_LOG (default $DEST/drills.log).
#
# Configuration: same file as backup-pull,
# ~/.config/chesstrainer/backup-pull.env.
set -euo pipefail
umask 077
CONFIG="${PULL_ENV_FILE:-${XDG_CONFIG_HOME:-$HOME/.config}/chesstrainer/backup-pull.env}"
if [[ -r "$CONFIG" ]]; then
# shellcheck disable=SC1090
source "$CONFIG"
fi
DEST="${DEST:-$HOME/chesstrainer-backups}"
AGE_KEY="${AGE_KEY:-${XDG_CONFIG_HOME:-$HOME/.config}/chesstrainer/age.key}"
EXPECTED_ROLES="${EXPECTED_ROLES:-chesstrainer chesstrainer_ro}"
DRILL_IMAGE="${DRILL_IMAGE:-postgres:18.6}"
DRILL_DB="${DRILL_DB:-chesstrainer_restore}"
DRILL_LOG="${DRILL_LOG:-$DEST/drills.log}"
DRILL_CONTAINER="${DRILL_CONTAINER:-chesstrainer-drill-$$}"
START_SECONDS=$SECONDS
FAILURE=""
TMPDIR_DRILL=""
log_event() {
local event="$1"
local extra="${2:-}"
printf '{"timestamp":"%s","event":"%s"%s}\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$event" "$extra"
}
record() {
local line="$1"
printf '%s\n' "$line"
printf '%s\n' "$line" >>"$DRILL_LOG"
}
fail() {
FAILURE="$*"
exit 1
}
cleanup() {
local status=$?
docker rm -f "$DRILL_CONTAINER" >/dev/null 2>&1 || true
if [[ -n "$TMPDIR_DRILL" ]]; then
rm -rf "$TMPDIR_DRILL"
fi
if ((status != 0)); then
if [[ -d "$DEST" ]]; then
record "$(log_event drill.failed ",\"reason\":\"${FAILURE:-exit $status}\"")"
else
log_event drill.failed ",\"reason\":\"${FAILURE:-exit $status}\""
fi
fi
exit "$status"
}
trap cleanup EXIT
trap 'exit 143' TERM INT
[[ -d "$DEST" ]] || fail "archive directory does not exist: $DEST"
[[ -r "$AGE_KEY" ]] || fail "age identity not readable: $AGE_KEY"
for cmd in docker age tar sha256sum; do
command -v "$cmd" >/dev/null 2>&1 || fail "missing command: $cmd"
done
if [[ $# -gt 0 ]]; then
case "$1" in
/*) archive="$1" ;;
*) archive="$DEST/$1" ;;
esac
else
archive="$(find "$DEST" -maxdepth 1 -type f -name '*.tar.age' -printf '%p\n' | sort | tail -n 1)"
[[ -n "$archive" ]] || fail "no archives in $DEST"
fi
[[ -f "$archive" ]] || fail "archive not found: $archive"
name="${archive##*/}"
[[ "$name" =~ ^[0-9]{8}T[0-9]{6}Z(-[a-z0-9]+)?\.tar\.age$ ]] ||
fail "unexpected archive name: $name"
prefix="${name%%.*}"
TMPDIR_DRILL="$(mktemp -d "${TMPDIR:-/tmp}/chesstrainer-drill.XXXXXX")"
echo "backup-drill: decrypting $name" >&2
age --decrypt --identity "$AGE_KEY" --output "$TMPDIR_DRILL/$prefix.tar" "$archive" ||
fail "could not decrypt $name"
tar -xf "$TMPDIR_DRILL/$prefix.tar" -C "$TMPDIR_DRILL" ||
fail "archive does not contain a readable tar file"
(
cd "$TMPDIR_DRILL"
sha256sum --check --strict --quiet "$prefix.sha256"
) || fail "checksum verification failed for $name"
echo "backup-drill: starting $DRILL_IMAGE" >&2
docker image inspect "$DRILL_IMAGE" >/dev/null 2>&1 ||
docker pull "$DRILL_IMAGE" >/dev/null ||
fail "could not pull $DRILL_IMAGE"
docker run --rm --detach \
--name "$DRILL_CONTAINER" \
--env POSTGRES_USER=chesstrainer \
--env POSTGRES_PASSWORD=drill \
--env POSTGRES_HOST_AUTH_METHOD=trust \
"$DRILL_IMAGE" >/dev/null || fail "could not start the drill container"
ready=0
for _ in $(seq 1 60); do
if docker exec "$DRILL_CONTAINER" pg_isready -U chesstrainer -d postgres >/dev/null 2>&1; then
ready=1
break
fi
sleep 1
done
((ready == 1)) || fail "postgres did not become ready"
# Recreating the cluster roles is half of disaster recovery. The scratch
# cluster uses the same superuser name as production (`chesstrainer`), because
# the globals dump ends with grants issued "GRANTED BY chesstrainer". The dump
# always repeats the cluster's own superuser role, so "already exists" is
# expected; anything else is a real failure.
echo "backup-drill: applying globals" >&2
docker exec -i "$DRILL_CONTAINER" psql -U chesstrainer -d postgres \
-q -v ON_ERROR_STOP=0 -f - \
<"$TMPDIR_DRILL/$prefix.globals.sql" >/dev/null 2>"$TMPDIR_DRILL/globals.err" ||
fail "applying the globals dump failed"
globals_errors="$(grep -v 'already exists' "$TMPDIR_DRILL/globals.err" | sed '/^$/d' || true)"
if [[ -n "$globals_errors" ]]; then
fail "globals restore reported errors: $(printf '%s' "$globals_errors" | head -n 1)"
fi
for role in $EXPECTED_ROLES; do
found="$(docker exec "$DRILL_CONTAINER" psql -U chesstrainer -d postgres -Atc \
"select 1 from pg_roles where rolname = '$role'")"
[[ "$found" == "1" ]] || fail "globals did not recreate role $role"
done
owner="${EXPECTED_ROLES%% *}"
docker exec "$DRILL_CONTAINER" psql -U chesstrainer -d postgres \
-q -v ON_ERROR_STOP=1 -c "create database $DRILL_DB owner $owner" ||
fail "could not create $DRILL_DB"
echo "backup-drill: restoring into $DRILL_DB" >&2
docker exec -i "$DRILL_CONTAINER" pg_restore -U chesstrainer -d "$DRILL_DB" \
--single-transaction --exit-on-error <"$TMPDIR_DRILL/$prefix.dump" ||
fail "pg_restore failed"
restored_counts=""
for table in users endgames attempts; do
expected="$(awk -F= -v key="$table" '$1 == key { print $2 }' "$TMPDIR_DRILL/$prefix.counts")"
[[ "$expected" =~ ^[0-9]+$ ]] || fail "counts file has no value for $table"
actual="$(docker exec "$DRILL_CONTAINER" psql -U chesstrainer -d "$DRILL_DB" -Atc \
"select count(*) from $table")"
[[ "$actual" =~ ^[0-9]+$ ]] || fail "could not count $table"
if ((actual < expected)); then
fail "restored $table=$actual is below the recorded $expected"
fi
echo "backup-drill: $table restored=$actual recorded=$expected drift=$((actual - expected))" >&2
restored_counts+="${restored_counts:+,}$table=$actual"
done
record "$(log_event drill.completed ",\"archive\":\"$name\",\"result\":\"pass\",\"counts\":\"$restored_counts\",\"duration_s\":$((SECONDS - START_SECONDS))")"
+248
View File
@@ -0,0 +1,248 @@
#!/usr/bin/env bash
#
# Pull the encrypted database archives from the VPS, verify them end to end,
# and apply the 7 daily / 4 weekly / 6 monthly retention policy.
#
# Runs on the workstation, never on the server. Install as
# ~/.local/bin/chesstrainer-backup-pull and enable
# chesstrainer-backup-pull.timer as a user unit.
#
# Configuration: ~/.config/chesstrainer/backup-pull.env (0600). See
# deploy/README.md §Backups.
set -euo pipefail
umask 077
CONFIG="${PULL_ENV_FILE:-${XDG_CONFIG_HOME:-$HOME/.config}/chesstrainer/backup-pull.env}"
if [[ -r "$CONFIG" ]]; then
# shellcheck disable=SC1090
source "$CONFIG"
fi
VPS_HOST="${VPS_HOST:-}"
REMOTE_DIR="${REMOTE_DIR:-/var/backups/chesstrainer/offsite}"
DEST="${DEST:-$HOME/chesstrainer-backups}"
AGE_KEY="${AGE_KEY:-${XDG_CONFIG_HOME:-$HOME/.config}/chesstrainer/age.key}"
MAX_STALENESS_HOURS="${MAX_STALENESS_HOURS:-48}"
KEEP_DAILY_DAYS="${KEEP_DAILY_DAYS:-7}"
KEEP_WEEKLY_WEEKS="${KEEP_WEEKLY_WEEKS:-4}"
KEEP_MONTHLY_MONTHS="${KEEP_MONTHLY_MONTHS:-6}"
PULL_HEALTHCHECK_URL="${PULL_HEALTHCHECK_URL:-}"
SSH_OPTIONS="${SSH_OPTIONS:--o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=15}"
RSYNC_ATTEMPTS="${RSYNC_ATTEMPTS:-3}"
START_SECONDS=$SECONDS
FAILURE=""
VERIFIED=0
log_event() {
local event="$1"
local extra="${2:-}"
printf '{"timestamp":"%s","event":"%s"%s}\n' \
"$(date -u +%Y-%m-%dT%H:%M:%SZ)" "$event" "$extra"
}
heartbeat() {
local outcome="$1"
[[ -n "$PULL_HEALTHCHECK_URL" ]] || return 0
local url="${PULL_HEALTHCHECK_URL%/}"
[[ "$outcome" == "fail" ]] && url="$url/fail"
if ! curl --fail --silent --show-error \
--max-time 10 --retry 2 --retry-delay 2 \
--output /dev/null "$url"; then
echo "backup-pull: heartbeat ping failed (run result is unaffected)" >&2
fi
}
fail() {
FAILURE="$*"
exit 1
}
cleanup() {
local status=$?
if [[ -d "$DEST" ]]; then
find "$DEST" -maxdepth 1 -name '.verify.*' -type d -exec rm -rf {} + 2>/dev/null || true
fi
if ((status != 0)); then
log_event pull.failed ",\"reason\":\"${FAILURE:-exit $status}\""
heartbeat fail
fi
exit "$status"
}
trap cleanup EXIT
trap 'exit 143' TERM INT
[[ -n "$VPS_HOST" ]] || fail "VPS_HOST is not set"
[[ -r "$AGE_KEY" ]] || fail "age identity not readable: $AGE_KEY"
[[ "$MAX_STALENESS_HOURS" =~ ^[0-9]+$ ]] || fail "MAX_STALENESS_HOURS must be an integer"
[[ "$KEEP_DAILY_DAYS" =~ ^[0-9]+$ ]] || fail "KEEP_DAILY_DAYS must be an integer"
[[ "$KEEP_WEEKLY_WEEKS" =~ ^[0-9]+$ ]] || fail "KEEP_WEEKLY_WEEKS must be an integer"
[[ "$KEEP_MONTHLY_MONTHS" =~ ^[0-9]+$ ]] || fail "KEEP_MONTHLY_MONTHS must be an integer"
[[ "$RSYNC_ATTEMPTS" =~ ^[0-9]+$ ]] || fail "RSYNC_ATTEMPTS must be an integer"
for cmd in rsync ssh age tar sha256sum curl flock; do
command -v "$cmd" >/dev/null 2>&1 || fail "missing command: $cmd"
done
# Never create DEST on the root filesystem when the backup disk is unmounted.
[[ -d "$(dirname "$DEST")" ]] ||
fail "parent directory of $DEST does not exist (is the backup disk mounted?)"
install -d -m 0700 "$DEST"
install -d -m 0700 "$DEST/.verified"
exec 9>"$DEST/.pull.lock"
if ! flock -n 9; then
# A manual run overlapping the timer is not an error; the other run reports.
log_event pull.skipped ',"reason":"another pull is running"'
exit 0
fi
archive_epoch() {
local name="$1"
local ts="${name:0:16}"
[[ "$ts" =~ ^[0-9]{8}T[0-9]{6}Z$ ]] || return 1
date -u -d "${ts:0:4}-${ts:4:2}-${ts:6:2} ${ts:9:2}:${ts:11:2}:${ts:13:2}Z" +%s
}
verify_archive() {
local archive="$1"
local name="${archive##*/}"
local marker="$DEST/.verified/$name"
local sum tmp
sum="$(sha256sum "$archive" | awk '{ print $1 }')"
if [[ -f "$marker" && "$(cat "$marker")" == "$sum" ]]; then
return 0
fi
tmp="$(mktemp -d "$DEST/.verify.XXXXXX")"
if ! age --decrypt --identity "$AGE_KEY" --output "$tmp/$name.tar" "$archive"; then
rm -rf "$tmp"
echo "backup-pull: $name failed to decrypt" >&2
return 1
fi
if ! tar -xf "$tmp/$name.tar" -C "$tmp"; then
rm -rf "$tmp"
echo "backup-pull: $name did not contain a readable tar archive" >&2
return 1
fi
if ! (cd "$tmp" && sha256sum --check --strict --quiet ./*.sha256); then
rm -rf "$tmp"
echo "backup-pull: $name failed its checksum verification" >&2
return 1
fi
rm -rf "$tmp"
printf '%s\n' "$sum" >"$marker.tmp"
mv "$marker.tmp" "$marker"
VERIFIED=$((VERIFIED + 1))
}
# ---------------------------------------------------------------------------
# Copy
# ---------------------------------------------------------------------------
attempt=1
while true; do
if rsync --archive --partial --compress --timeout=120 \
--include='*.tar.age' --exclude='*' \
--rsh "ssh $SSH_OPTIONS" \
"$VPS_HOST:$REMOTE_DIR/" "$DEST/"; then
break
fi
if ((attempt >= RSYNC_ATTEMPTS)); then
fail "rsync from $VPS_HOST failed after $attempt attempts"
fi
echo "backup-pull: rsync attempt $attempt failed, retrying" >&2
attempt=$((attempt + 1))
sleep 20
done
mapfile -t archives < <(
find "$DEST" -maxdepth 1 -type f -name '*.tar.age' -printf '%f\n' | sort
)
((${#archives[@]} > 0)) || fail "no archives in $DEST after the pull"
for name in "${archives[@]}"; do
[[ "$name" =~ ^[0-9]{8}T[0-9]{6}Z(-[a-z0-9]+)?\.tar\.age$ ]] ||
fail "unexpected file in $DEST: $name"
done
newest="${archives[${#archives[@]} - 1]}"
newest_epoch="$(archive_epoch "$newest")" || fail "cannot parse a timestamp from $newest"
age_seconds=$(($(date -u +%s) - newest_epoch))
if ((age_seconds > MAX_STALENESS_HOURS * 3600)); then
fail "newest archive $newest is $((age_seconds / 3600))h old (limit ${MAX_STALENESS_HOURS}h): VPS backups may have stopped"
fi
# ---------------------------------------------------------------------------
# Verify every archive once; unchanged ciphertext is only re-hashed.
# ---------------------------------------------------------------------------
for name in "${archives[@]}"; do
verify_archive "$DEST/$name" || fail "$name failed verification"
done
# ---------------------------------------------------------------------------
# Retention: 7 daily, then one per ISO week for 4 weeks, then one per calendar
# month for 6 months. Archives outside all three windows are deleted.
# ---------------------------------------------------------------------------
now="$(date -u +%s)"
pruned=0
declare -A kept_week=()
declare -A kept_month=()
mapfile -t newest_first < <(
find "$DEST" -maxdepth 1 -type f -name '*.tar.age' -printf '%f\n' | sort -r
)
for name in "${newest_first[@]}"; do
epoch="$(archive_epoch "$name")" || continue
age_days=$(((now - epoch) / 86400))
if ((age_days < KEEP_DAILY_DAYS)); then
continue
fi
week="$(date -u -d "@$epoch" +%G-W%V)"
if ((age_days < KEEP_WEEKLY_WEEKS * 7)) && [[ -z "${kept_week[$week]:-}" ]]; then
kept_week[$week]=1
continue
fi
month="$(date -u -d "@$epoch" +%Y-%m)"
if ((age_days < KEEP_MONTHLY_MONTHS * 31)) && [[ -z "${kept_month[$month]:-}" ]]; then
kept_month[$month]=1
continue
fi
echo "backup-pull: pruning $name" >&2
rm -f -- "$DEST/$name" "$DEST/.verified/$name"
pruned=$((pruned + 1))
done
log_event pull.completed ",\"newest\":\"$newest\",\"archives\":$(( ${#archives[@]} - pruned )),\"verified\":$VERIFIED,\"pruned\":$pruned,\"duration_s\":$((SECONDS - START_SECONDS))"
heartbeat ok
@@ -0,0 +1,37 @@
# ~/.config/chesstrainer/backup-pull.env -- mode 0600.
#
# Sourced by ~/.local/bin/chesstrainer-backup-pull. Values below are the
# defaults; VPS_HOST and AGE_KEY must be right. Quote anything containing
# spaces.
VPS_HOST=owen@159.69.21.225
REMOTE_DIR=/var/backups/chesstrainer/offsite
DEST="/mnt/Mint Data/chesstrainer-backups"
# Private half of the age key. Back this file up somewhere safe: without it
# every archive is unreadable.
AGE_KEY="$HOME/.config/chesstrainer/age.key"
# Fail the pull when the newest archive from the VPS is older than this, which
# means the VPS backup timer has stopped.
MAX_STALENESS_HOURS=48
# Keep every archive from the last 7 days, then one per ISO week for 4 weeks,
# then one per calendar month for 6 months.
KEEP_DAILY_DAYS=7
KEEP_WEEKLY_WEEKS=4
KEEP_MONTHLY_MONTHS=6
# Restore drill. It runs in a throwaway container matching the production
# Postgres major and appends results to DRILL_LOG.
# DRILL_IMAGE=postgres:18.6
# DRILL_DB=chesstrainer_restore
# DRILL_LOG="$DEST/drills.log"
EXPECTED_ROLES="chesstrainer chesstrainer_ro"
# Optional second heartbeat check with a long period (for example 72h), so you
# hear about it when the workstation stops pulling. Leave empty to disable.
# PULL_HEALTHCHECK_URL=https://hc-ping.com/00000000-0000-0000-0000-000000000000
# Extra ssh options, space separated.
# SSH_OPTIONS="-o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=15"
@@ -0,0 +1,7 @@
[Unit]
Description=Report a failed Inner Square Chess backup unit
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Service]
Type=oneshot
ExecStart=/usr/bin/logger --tag chesstrainer-backup --priority user.err --stderr backup.unit-failed: %i failed, see journalctl --user -u %i
@@ -0,0 +1,13 @@
[Unit]
Description=Monthly restore drill for Inner Square Chess backups
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
OnFailure=chesstrainer-backup-alert@%N.service
[Service]
Type=oneshot
ExecStart=%h/.local/bin/chesstrainer-backup-drill
WorkingDirectory=%h
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
Nice=10
TimeoutStartSec=20min
SyslogIdentifier=chesstrainer-backup-drill
@@ -0,0 +1,13 @@
[Unit]
Description=Monthly restore drill for Inner Square Chess backups
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Timer]
OnCalendar=*-*-01 09:00:00
RandomizedDelaySec=30m
AccuracySec=5m
Persistent=true
Unit=chesstrainer-backup-drill.service
[Install]
WantedBy=timers.target
@@ -0,0 +1,15 @@
[Unit]
Description=Pull encrypted Inner Square Chess backups from the VPS
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
After=network-online.target
Wants=network-online.target
OnFailure=chesstrainer-backup-alert@%N.service
[Service]
Type=oneshot
ExecStart=%h/.local/bin/chesstrainer-backup-pull
WorkingDirectory=%h
Environment=PATH=%h/.local/bin:/usr/local/bin:/usr/bin:/bin
Nice=10
TimeoutStartSec=15min
SyslogIdentifier=chesstrainer-backup-pull
@@ -0,0 +1,14 @@
[Unit]
Description=Daily pull of encrypted Inner Square Chess backups
Documentation=https://github.com/TheRealOwenRees/chess-endgame-trainer/blob/main/deploy/README.md
[Timer]
OnCalendar=*-*-* 12:00:00
OnBootSec=10m
RandomizedDelaySec=10m
AccuracySec=1m
Persistent=true
Unit=chesstrainer-backup-pull.service
[Install]
WantedBy=timers.target
+1 -1
View File
@@ -1,7 +1,7 @@
services:
db:
container_name: chesstrainer_dev-db
image: postgres:18.0
image: postgres:18.6
restart: unless-stopped
environment:
- POSTGRES_USER=postgres
@@ -0,0 +1,65 @@
# Launch observability is the probe, honest error states, and the runbook
_Status: accepted._
At launch, observability means three things and no more: an external check that
the public app answers, error states that are honest and recoverable, and a
written runbook for when either fails. Everything else is deferred with a named
trigger, so the gaps are explicit rather than ambient.
## The launch bar
- **Probe.** A healthchecks.io check with a two-minute period and grace, fed by
an on-box prober with off-box alerting (#160, #161). It curls the public
`/health` through Cloudflare, so DNS, TLS, Caddy, the origin allowlist,
Phoenix and one Postgres query are covered. The loopback cross-check in a
failure body is evidence only. The prober shares a host with the app, so host
death is caught by silence, not by a ping.
- **Error states.** The audit (#162) and its fixes (#163), verified by #164.
Every failure mode has copy and a retry or a way home; exception details and
raw error terms do not reach the page.
- **Runbook.** `deploy/README.md` §Monitoring and alerting: the check, install,
what `/health` proves and does not, Beszel's blind spot, the drills, and the
dated drill log.
## Deferred, with triggers
- **Error tracking (#109, GlitchTip/Sentry).** Deferred because JSON logs
already carry the crash reason and stacktrace per request, and there is no
traffic to aggregate over. Revisit when the first production 500 cannot be
diagnosed from its journal line (missing or truncated stacktrace), or a user
reports an error without a request id, or unexplained errors exceed roughly
50 a day and per-line grep stops being practical.
- **Metrics and LiveDashboard (#111).** Deferred because Beszel covers host
resources and the probe covers the HTTP contract. Revisit when a capacity
question needs a number neither can answer (database pool saturation, p95
latency, queue depth), or daily active users pass 100, or a performance
incident takes more than an hour to localise.
- **Off-box log shipping and error-rate alerts (#140).** Deferred because
journald is persistent on the host and the probe alerts on downness. Revisit
when an alert must fire on a log pattern (error rate, authentication
failures), or the journal retention budget cannot cover a 30-day
investigation, or the host is rebuilt and local logs would be lost in the same
incident.
## Why journald and backups are enough at launch
Persistent journald (`Storage=persistent`, `SystemMaxUse`) holds one JSON object
per line: crashes carry a reason and stacktrace, access lines carry status and
duration, and token-shaped paths, emails and credentials are redacted. Off-box
encrypted backups cover the data.
The accepted risk: losing the host loses the logs with it, and there is no
aggregate error rate. At launch that is acceptable — one host, one operator,
low traffic, and an incident is diagnosed from the journal on the box or from
the probe's alert body. The triggers above are the point at which that risk
stops being acceptable.
## Consequences
- Investigation starts with `journalctl -u chesstrainer -o cat | jq`, not a
dashboard.
- Error tracking, metrics and log shipping stay explicit backlog items with
triggers rather than ambient gaps.
- The probe is an on-box prober with off-box alerting; it is not external
uptime monitoring and the runbook says so.
+93
View File
@@ -0,0 +1,93 @@
# Analytics
We use a self-hosted Matomo instance for privacy-conscious analytics on public
pages and the guest trainer.
## What is collected
- Page views on anonymous public pages and the guest trainer.
- Standard request data Matomo needs to count a visit, with IP anonymisation.
We do **not**:
- set Matomo cookies,
- use user IDs,
- track signed-in account, profile, or admin pages,
- enable cross-site or advertising features,
- share analytics data with third parties.
## Configuration
The app reads these environment variables at boot:
```sh
MATOMO_URL=https://analytics.owenrees.eu/
MATOMO_SITE_ID=6
```
They are configured in `config/runtime.exs` for production only. If either is
missing, no analytics config is rendered and no tracker is loaded.
The root layout renders a hidden `#matomo-config` element only when the visitor
is anonymous. `assets/js/analytics.js` initialises Matomo cookieless from that
element. Signed-in users never receive the element.
## Matomo settings
In the Matomo administration UI:
1. **Administration → Websites → Manage**
- URL: `https://innersquare.app`
- Site ID: `6`
- Timezone: match the site
2. **Administration → Privacy → Anonymize data**
- Enable IP anonymisation (at least the last byte; 2 bytes is safer)
- Disable tracking cookies
- Respect Do Not Track
- Do not use user IDs
- Set raw data retention to **180 days**
3. **Administration → System check / trusted hosts**
- Add `innersquare.app` and `www.innersquare.app` if host validation is on.
4. Do not enable ecommerce, advertising, or cross-domain tracking.
The JavaScript also calls:
```js
_paq.push(["disableCookies"]);
_paq.push(["setDoNotTrack", true]);
```
## Opt-out
The privacy page has an **Analytics** section with an opt-out control. The
preference is stored in `localStorage["matomo_optout"]`, not a cookie. When set,
the tracker is never loaded and LiveView page views are skipped.
The preference is local to the browser. Clearing site data resets it. Users can
also object by emailing `support@innersquare.app`.
## Verification
On an anonymous public page:
```sh
curl -s https://innersquare.app/ | grep -c matomo-config
```
should return `1`.
In the browser:
- `matomo.js` and `matomo.php` load once.
- Matomo Real-time shows the page view.
- No `_pk_*` cookies are created.
- Opting out sets `matomo_optout=1` in localStorage and stops further requests.
- Signed-in pages produce no Matomo config or requests.
- A DNT browser setting suppresses tracking.
## Legal basis
Analytics runs on the basis of legitimate interests in improving the service.
The privacy policy discloses it, explains the data, and provides the opt-out.
This document is an engineering configuration guide, not legal advice; keep a
short legitimate-interest assessment on file.
+84
View File
@@ -0,0 +1,84 @@
# Asset bundle sizes
What the browser downloads, measured rather than guessed. Numbers below are
from the last production build (`mix assets.deploy`, minified and digested) and
were read with `mix assets.sizes`.
Re-measure after any asset change:
```sh
mix assets.deploy
mix assets.sizes
```
`mix assets.sizes` prints raw, gzip and brotli sizes for every built JS and CSS
file. Brotli shows as `-` when the `brotli` CLI is not installed.
## Current bundles
| File | Raw | Gzip |
| --- | ---: | ---: |
| `assets/js/app.js` (LiveView entry) | 219.7 KB | 69.2 KB |
| `assets/js/marketing.js` (controller pages) | 4.8 KB | 1.9 KB |
| `assets/css/app.css` | 94.2 KB | 17.3 KB |
Cached font files, served only when used: DM Sans variable 62.5 KB, DM Serif
Display 24.5 KB, DM Serif Display italic 24.4 KB, DM Sans italic 14.6 KB
(woff2, already compressed).
## What is in each bundle
`app.js` is a single entry loaded by every LiveView page. It contains:
| Part | Raw | Gzip |
| --- | ---: | ---: |
| `phoenix`, `phoenix_live_view`, `phoenix_html` | — | ~30 KB |
| `chessground` (`dist/chessground.min.js`) | 30.0 KB | 11.0 KB |
| `chess.js` (`dist/esm/chess.js`) | 107.1 KB | 23.9 KB |
| `topbar` | 4.3 KB | 1.5 KB |
| `nav`, `analytics`, hooks | ~8 KB | ~3 KB |
The library figures are the packages' own builds; esbuild's minification and
tree shaking mean the bundle total is smaller than the naive sum.
`marketing.js` is deliberately tiny: `phoenix_html`, the nav toggle and the
cookieless analytics loader. It has no LiveView, socket, hooks or topbar.
Controller pages (landing page, legal pages, 404) load it instead of `app.js`.
`app.css` is one Tailwind build for the whole site, including the three
chessground stylesheets (`chessground.base.css` 3.3 KB, `chessground.brown.css`
2.8 KB, `chessground.cburnett.css` 11.5 KB raw, ~4.7 KB gzipped together).
## Findings
1. **Board code is about half of `app.js` and most pages do not use it.**
chessground and chess.js are ~35 KB of the 69 KB gzip payload. They are
needed only by pages that render `ChessBoard`: guest training, play, review.
Profile, settings, the endgame list and every admin screen pay for them and
never instantiate a board.
2. **The marketing/public split is already right.** Public pages do not load
the LiveView runtime at all.
3. **Board CSS is in the global stylesheet.** ~4.7 KB gzipped of chess piece
and board styling reaches every page, including the landing page.
4. **Stale digested bundles accumulate.** `priv/static/assets` currently holds
three generations of `app-*.js` and `app-*.css`. They are not linked but do
bloat the release. `mix phx.digest.clean --age 0` (or deploying from a clean
build) removes them.
## Recommendation (not applied)
Split the board libraries out of the LiveView entry:
- Load `chessground` and `chess.js` with a dynamic `import()` inside
`assets/js/hooks/chessBoard.js` and build with esbuild `--splitting
--format=esm`. Pages without a board then never fetch the chunk; board pages
fetch it once, in parallel with the hook mounting.
- Expected result: `app.js` drops from ~69 KB to ~35 KB gzip on most
authenticated pages, with a separate ~35 KB board chunk fetched only where
needed.
- Move the chessground stylesheets into the board chunk's CSS (or a second CSS
entry loaded only on board pages) to take ~4.7 KB off every page.
- Set a budget in CI once the split lands: `app.js` ≤ 40 KB gzip, board chunk
≤ 40 KB gzip, `marketing.js` ≤ 2 KB gzip, `app.css` ≤ 20 KB gzip.
No build configuration was changed as part of this measurement.
+61
View File
@@ -0,0 +1,61 @@
# Error-state verification
The #162 checklist, walked on 2026-11-13 against a local production-like build.
Failures were filed as #171 and fixed in the follow-up for that issue; this page
records the verification run, not the current state. It is linked from the
audit.
## Method
- **Build:** `MIX_ENV=prod` `mix phx.server` on `127.0.0.1:4010`, commit
`021e412` plus this branch's documentation.
- **Database:** a scratch `postgres:18.6` on port 55432. Empty at first, then
one confirmed user and one 8+ piece endgame (inserted directly, because the
admin changeset rejects positions beyond seven pieces).
- **Configuration:** `PRELAUNCH=false`, `MAILING_LIST_ENABLED=true`,
`TABLEBASE_PATH` pointing at a missing directory, dummy SES credentials.
- **Forced failures:** Postgres stopped, missing tablebase directory, empty
puzzle pool, expired reset and confirmation tokens (backdated
`users_tokens.inserted_at`), stale and invalid mailing-list forms, guest
budget exhausted, unknown public play code.
- **Observation:** `curl` for controller-rendered pages, headless Chrome over
the DevTools Protocol for LiveView-connected pages, and `mix test` for the
interactive states that need a click. Each row names its evidence.
- **Not forced:** a real Lichess 429 (the cooldown and classifier paths were
exercised by the tests), a crash after connect, and the two admin-only import
leaks (code inspection and tests). The first run rejected the socket origin
because `PHX_HOST` defaulted to `example.com`; setting `PHX_HOST=127.0.0.1`
fixed it. That was local configuration, not a product finding.
## Results
| Checklist row | Result | Evidence |
|---|---|---|
| T1 cooldown | **pass** | LiveView test: mount with a cooldown shows "Tablebase cooling down"; Retry re-fetches and returns to play. |
| T2 429 | **pass** | LiveView test: classifier maps 429 to "Tablebase rate-limited"; HTML carries no `429`, `too_many_requests` or upstream body. |
| T3 not covered | **pass** | Prod run: guest page with a 12-piece endgame shows "Position not covered… can't be graded", no `not_covered` in the DOM, Next puzzle or back available. |
| T4 generic | **pass** | LiveView test: classifier returns "Tablebase unavailable"; the reason is logged and never rendered. |
| T5/T6 load and reply failure | **pass** | T5 covered by the cooldown-at-mount test and Retry. T6 shares the blocked panel and `reset/1` path; not separately forced. |
| T8 invalid FEN | **fail** | Existing test: the flash still contains the client message and the raw FEN. #171. |
| S1/S2/S3/S5 empty pools | **pass** | S1 prod: Medium picker shows the in-page empty state and Retry. S5 prod: guest shows "No endgames are available yet" and Retry. S2/S3 tests: exhausted state, Retry and Change difficulty. |
| S4 guest limit | **pass** | Prod run: five visits exhaust the budget; the wall shows the reset time, Sign up free and Log in. |
| A1 reset token | **pass** | Prod run: an expired token flashes "Reset password link is invalid or it has expired." on the log-in page, with Forgot your password available. |
| A2 confirmation token | **fail** | Prod run: an expired token flashes "User not found or token is invalid." and lands on registration, not log in. #171. |
| A3/A4 login | **pass** | Tests: invalid credentials use one message; the throttle reports the remaining minutes. |
| M1–M5 mailing list | **pass** | Prod run: invalid confirmation link, removed address, stale form, invalid email and an SES send failure each show their specific copy with the form reachable. |
| W1/W2 404 and 500 | **pass** | Prod run: styled 404 for an unknown path; with Postgres stopped, `/` returns the styled 500 with no exception or stacktrace. |
| W3 crash | **fail** | The server-error banner has no reload action; a repeating crash has no manual escape. Not separately forced; same banner as W4. #171. |
| W4 disconnect | **pass** | Observed "Something went wrong! Attempting to reconnect" while the socket was rejected, with automatic retries; the banner hides on reconnect. |
| W5 database down | **pass** | Prod run: `/health` returns 503 `db:down`; `/` returns the 500 page. Note the loop: the home link also needs the database, so it 500s too. |
| D1/D2 export | **fail** | Prod run: an export with the database stopped returns the 500 page (no export-specific copy); `/users/profile/export/xml` returns plain text "Unknown export format". #171. |
| H1 empty-database home | **fail** | Prod run: the fallback board renders, but "Try today's puzzle" points at the auth-gated `/endgames`. #171. |
| X1 unknown play code | **pass** | Prod run: `/endgames/nope/play` returns the styled 404 page. This corrects the audit's earlier claim that it 500ed. |
| X2/X3 admin leaks | **fail** | Code inspection and tests: both importer messages still interpolate `inspect(reason)`. Not forced. #171. |
## Tally
- 14 checklist rows pass, 6 fail (8 individual regressions, because D1/D2 and
X2/X3 share a row).
- Every failure row is a state that was already listed as "improve" in the
audit and was outside #163; no new regression came from the #163 changes.
- The regressions are filed together in #171 rather than fixed silently.
+152
View File
@@ -0,0 +1,152 @@
# User-facing error states
What a player sees when something fails, with a verdict for every state and the
concrete change each one needs. This is the audit required by #162; #163
implements the tablebase and empty-pool items, and #164 walks the sign-off
checklist on a production-like build.
Verdicts:
- **keep** — the state is honest, recoverable and leak-free as it stands
- **improve** — a state exists but needs different copy, a recovery action, or
both
- **add** — there is no user-facing state today
"Internal detail" means an exception term, an `inspect/1` result, a raw HTTP
status body, a stacktrace, or a raw FEN appearing in rendered HTML.
**Status:** #163 implements T1–T6, S1–S3 and S5. The rows below describe the
state before that change. #164 walked this checklist on a local prod build:
see [error-states-verification.md](error-states-verification.md).
## Play and tablebase
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| T1 | Cooldown | A previous 429 put Lichess in cooldown; `Tablebase.new/1` returns `{:cooldown, ms}` (`play_core.ex:386`) | Panel headed **Tablebase unavailable**, body "The tablebase is rate-limited. Try again in about Ns."; move hint "The tablebase is unavailable, so moves cannot be entered."; **Reset** | improve | Heading per failure class ("Tablebase cooling down"), keep the countdown, and relabel Reset to **Retry** while blocked. Fold into #163. |
| T2 | Lichess 429 | Lichess returns 429; the parser records a cooldown (`tablebase/parser.ex:69`) | Same panel; "The tablebase is rate-limited. Try again in a minute." | improve | Same class as T1, with the real countdown once known. Never show `429` or the response body. Fold into #163. |
| T3 | Position not covered | More than seven pieces, Lichess 404, or `:not_covered` (`play_core.ex:394-401`) | Panel headed **Tablebase unavailable**, body "This position is not covered by the tablebase."; **Reset** | improve | Say the puzzle cannot be graded, and offer **Try another puzzle** (session) or **Browse endgames** (single). Retry is futile here, so do not present it as the primary action. Fold into #163. |
| T4 | Generic tablebase failure | 5xx, transport error, malformed response (`play_core.ex:403`) | **"The tablebase is unavailable (#{inspect(reason)})."** | improve | Replace with "The tablebase is unavailable right now. Try again in a moment." and log the reason. This is the leak #163 calls out. Also applies to the review panel's `review_blocked` copy. |
| T5 | Load failure at session start | `Tablebase.new/1` fails in `PlayCore.init/2` → `load_attempt/1` | Board non-interactive; blocked panel and reason; **Reset** | improve | Class-correct copy plus **Retry**; `reset/1` already re-fetches, so this is a label and copy change. Fold into #163. |
| T6 | Fetch failure for the opponent's reply | `start_opponent_reply/2` cannot fetch the new position (`play_core.ex:457`) | Play stops; blocked panel; the move already played is still on the board; **Reset** | improve | Explain that the puzzle is paused and **Retry** resumes from the current position. Fold into #163. |
| T7 | Move while blocked | A move event arrives while `status == :blocked` (`play_core.ex:76`) | Flash "The tablebase is unavailable, so this move cannot be graded." | keep | Defensive guard; the board should already be non-interactive. #164 asserts that. |
| T8 | Invalid FEN from the board hook | `chess_fen_invalid` (`play_core.ex:184`) | Flash **"Endgame FEN is invalid and the board cannot be loaded: #{message} (#{fen})"** | improve | Generic copy ("The board couldn't load this position. Reset to try again."), log the details, and keep **Reset** visible. Leak: client message and raw FEN. |
## Sessions and puzzle pools
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| S1 | No puzzles available | `Puzzles.next_endgame/3` returns `nil` on start (`train.ex:201`) | Flash error "No puzzles are available right now."; the difficulty picker stays behind it | improve | Replace the flash with an in-page state inside the picker: what happened, **Retry**, and a way to pick another difficulty. Fold into #163. |
| S2 | No more puzzles at this difficulty | `next_endgame` returns `nil` with `exclude_ids` (`train.ex:232`) | Flash info "No more puzzles at this difficulty."; the finished puzzle and **Next puzzle** remain | improve | In-page end-of-run panel: "You've finished every puzzle at this difficulty" with **Retry**, **Change difficulty** (stop session) and the existing Stop session. Hide or disable Next. Fold into #163. |
| S3 | Guest: no more puzzles | Guest `next_puzzle` finds nothing (`guest_train.ex:137`) | Flash info "No more puzzles are available right now." | improve | In-page state with **Retry** and the sign-up/log-in actions, matching the guest-limit panel's tone. Fold into #163. |
| S4 | Guest limit reached | `GuestLimits.take/1` returns `{:limit_reached, ms}` (`guest_train.ex:45-70`) | In-page panel: used N free puzzles, reset time, **Sign up free**, **Log in** | keep | This is the reference state for tone and recovery. |
| S5 | Guest pool empty on load | Random endgame is `nil` (`guest_train.ex:98`) | In-page "No endgames are available yet. Please check back soon." | improve | Add a **Retry** action so the state is not a dead end. Fold into #163. |
## Accounts and email
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| A1 | Reset token invalid or expired | `get_user_by_reset_password_token/1` returns `nil` (`reset_password.ex:66`) | Flash "Reset password link is invalid or it has expired." then the log-in page, where **Forgot your password?** is available | keep | Honest and recoverable in two clicks. |
| A2 | Confirmation token invalid or expired | `Accounts.confirm_user/1` returns `:error` (`user_confirmation_controller.ex:17`) | Flash **"User not found or token is invalid."** then the registration page | improve | Say "That confirmation link is invalid or has expired." and send the user to log in, where an unconfirmed account triggers a fresh confirmation email. No "user not found" phrasing. |
| A3 | Invalid credentials | `get_user_by_login_and_password/2` returns `nil` | Flash "Invalid email, username or password"; email is prefilled | keep | Deliberately identical for unknown and wrong-password logins, so it does not enumerate accounts. |
| A4 | Login throttle | 5 failures per login or 10 per address in 15 minutes (`LoginThrottle`) | Flash "Too many attempts. Try again in N minutes." | keep | Accurate countdown, no account information. |
## Mailing list
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| M1 | Confirmation link invalid or expired | Token fails verification (`mailing_list_controller.ex:36`) | Flash "That confirmation link is invalid or has expired." → `/#mailing-list` | keep | The signup form is on the destination page. |
| M2 | Confirmed address no longer subscribed | `MailingList.confirm/1` returns `:not_found` (`:52`) | Flash "That address is no longer on the mailing list. Please sign up again." → `/#mailing-list` | keep | Actionable and specific. |
| M3 | Stale signup form | `MailingListFormToken.verify/1` fails (`:126`) | Flash "Please refresh the page and try again." → `/#mailing-list` | keep | The form is on the page; refresh is the fix. |
| M4 | Invalid email | Missing or invalid address (`:132`) | Flash "Enter a valid email address." | keep | Specific and actionable. |
| M5 | Confirmation email send failure | `Notifier.deliver_confirmation_instructions/2` returns an error (`:111`) | Flash "We couldn't send the confirmation email. Please try again." | improve | Keep the copy, add "If it keeps happening, email …" from `Branding.support_email/0`, and log the reason — the controller currently discards it. |
| M6 | List closed / honeypot / already subscribed | Feature flag, honeypot, or existing address | "The mailing list isn't open yet." / success copy / "You're already on the mailing list." | keep | Closed and honeypot are deliberate; the existing-address message is honest. |
## Site-level
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| W1 | 404 | Unknown route (`ErrorHTML`, catch-all route) | Styled page: "This page isn't on the board", **Back to home**, plus **Browse puzzles** for premium users | keep | Uses the shared `error_page/1`. |
| W2 | 500 | Controller or render crash | Styled page: "Something went wrong", **Back to home**, **Browse puzzles**, support email | keep | Honest, no exception detail. |
| W3 | LiveView crash | Raise in `mount` or `handle_event` | Mount crash → the 500 page. A crash after connect → the **"Something went wrong!"** banner, automatic reconnect, no manual action | improve | Add a **Reload** action (and keep home) to the server-error banner so a crash that repeats on reconnect has an escape. The banner lives in `layouts.ex:274`. |
| W4 | Disconnect | Socket or network loss | **"We can't find the internet"** banner with a spinner; hides on reconnect | keep | Automatic recovery, no action needed. |
| W5 | Database unavailable | Postgres stopped or pool exhausted | DB-backed pages and LiveView mounts raise → the 500 page; `/health` returns 503 | keep | The 500 page is the right state, but note the loop: the home page also needs the database, so "Back to home" fails too. The probe is the operational signal. No app change proposed here. |
## Data and landing
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| D1 | Export failure | `Attempts.list_attempts_for_user/1` raises in `UserDataController.export/2` | The 500 page, with no export-specific explanation | improve | Rescue, log, and redirect to `/users/profile/data` with "We couldn't build your export. Try again; if it keeps failing, email …". |
| D2 | Unknown export format | `/users/profile/export/<anything else>` | Plain text `404 "Unknown export format"` with no chrome, links, or home | improve | Return the styled 404 page instead. |
| D3 | Export of an empty account | No attempts | CSV with the header and an empty row; JSON with an empty list | keep | Deliberate and documented by the shape. |
| H1 | Home page with an empty database | No endgames (`PageController.home/2`) | Fallback KRK board, "Featured position", "0 players training", and a **Try today's puzzle** button pointing at `/endgames` | improve | When `active_endgame` is `nil`, do not send the visitor to an auth-gated page with no puzzles: point the call to action at `/guest-train` (which has its own empty state) or disable it with "New puzzles are coming". |
## Admin surfaces (extra)
| ID | State | Trigger | What the user sees today | Verdict | Action |
|---|---|---|---|---|---|
| X1 | Unknown public play code | `/endgames/:code/play` with a code that does not exist (`play.ex:79`) | The styled 404 page: `Ecto.NoResultsError` maps to 404 through `Plug.Exception` | keep | Verified by #164; no change. |
| X2 | Bulk import lookup crash | `handle_async` exits (`import.ex:271`) | Flash **"Could not look up the FENs: #{inspect(reason)}"** | improve | Generic copy plus a logged reason. Admin-only, but still an internal leak. |
| X3 | Bulk import tablebase load failure | `Local.check/0` returns an unexpected error (`import.ex:287`) | **"Local tablebase failed to load: #{inspect(reason)}"** | improve | Generic copy plus a logged reason. Admin-only, but still an internal leak. |
## Internal-detail leaks
These are the only places where an exception term, a raw HTTP status or a raw
FEN can reach rendered HTML. T4 is the one #162 calls out; the rest are smaller
but real.
| Where | Leak | Fix |
|---|---|---|
| `play_core.ex:404` | `inspect(reason)` in the blocked panel | T4 |
| `play_core.ex:189` | client message and raw FEN in a flash | T8 |
| `import.ex:271` | `inspect(reason)` in a flash | X2 |
| `import.ex:287` | `inspect(reason)` in the tablebase status | X3 |
| `user_data_controller.ex:21` | plain-text "Unknown export format" | D2 |
Server logs already carry the real reasons, so none of these fixes lose
diagnostic information.
## Sign-off checklist
For #164 to walk against a production-like build. Every row passes only if the
state offers **retry or a way home** and rendered HTML contains no exception,
stacktrace, raw error term, or raw FEN.
- [ ] **T1 cooldown** — force a cooldown: class-correct heading, countdown, Retry re-fetches.
- [ ] **T2 429** — make Lichess return 429: rate-limit copy, no `429` or response body.
- [ ] **T3 not covered** — play a position with more than seven pieces: explanation, another puzzle or home, no futile Retry.
- [ ] **T4 generic** — make Lichess fail (network off or 5xx): generic copy, Retry works when it recovers, no `inspect`.
- [ ] **T5/T6 load and reply failure** — start a puzzle and lose the tablebase mid-game: paused explanation, Retry resumes.
- [ ] **T8 invalid FEN** — force `chess_fen_invalid`: no client message or raw FEN, Reset visible.
- [ ] **S1/S2/S3/S5 empty pools** — empty the pool: in-page states on train and guest, Retry and change-difficulty reachable.
- [ ] **S4 guest limit** — exhaust the guest allowance: panel, reset time, sign-up and log-in reachable.
- [ ] **A1 reset token** — use an expired link: message, log-in page, forgot-password reachable.
- [ ] **A2 confirmation token** — use an expired link: message, log-in page, fresh confirmation email on next login.
- [ ] **A3/A4 login** — wrong password and throttled login: no account enumeration, countdown.
- [ ] **M1-M5 mailing list** — expired confirmation, stale form, invalid address, send failure: specific copy and the form reachable.
- [ ] **W1/W2 404 and 500** — unknown path and forced crash: styled page, home and browse reachable, no exception.
- [ ] **W3 crash** — raise in a `handle_event`: reload action reachable.
- [ ] **W4 disconnect** — drop the socket: reconnect banner and automatic recovery.
- [ ] **W5 database down** — stop Postgres: 500 pages, `/health` 503, no stacktrace; note that home is also down.
- [ ] **D1/D2 export** — force an export error and an unknown format: flash or 404 page, home reachable.
- [ ] **H1 empty database** — empty the pool: home renders, call to action is not an auth-gated dead end.
- [ ] **X1 unknown play code** — open a stale link: 404 page, not a 500.
- [ ] **X2/X3 admin leaks** — force an import crash and a tablebase error: no `inspect` output.
## Fix list
Fold into **#163** (tablebase and empty-pool recoverability): T1, T2, T3, T4,
T5, T6, S1, S2, S3, S5.
Separate changes, each independently testable:
- **T8** — generic invalid-FEN flash; log the details.
- **A2** — confirmation-token copy and destination.
- **M5** — support fallback on send failure; log the reason.
- **W3** — reload action in the server-error banner.
- **D1** — rescue export errors into a flash on the data tab.
- **D2** — styled 404 for unknown export formats.
- **H1** — empty-database call to action.
- **X2/X3** — generic admin import copy; log the details.
No code changes are part of this audit.
+223
View File
@@ -0,0 +1,223 @@
# Logging
Production writes one JSON object per line to standard output, which systemd
captures in journald. Development and test keep the readable
`[level] message` formatter.
## Configuration
`config/prod.exs` swaps the default handler's formatter for
`Chesstrainer.JSONLogFormatter`; nothing else changes per environment. The
formatter adds no runtime dependency beyond `Jason`, which the app already uses
for Phoenix JSON.
## Line shape
```json
{
"timestamp": "2026-11-10T21:36:28.489000Z",
"level": "error",
"message": "GET /endgames 500 in 12.5ms",
"request_id": "F7x...",
"method": "GET",
"path": "/endgames",
"status": 500,
"duration_ms": 12.5,
"error": {
"kind": "RuntimeError",
"reason": "bad thing",
"stacktrace": ["lib/foo.ex:10: Foo.bar/1"]
}
}
```
`timestamp`, `level` and `message` are always present. Metadata keys are
flattened into the object; reserved internal keys (`time`, `gl`, `report_cb`,
`error_logger`, `exception`, `stacktrace`, `crash_reason`, `reason`, `kind`)
are either unpacked into the line or omitted. Fixed fields win over metadata
with the same name.
| Field | When | Meaning |
|---|---|---|
| `timestamp` | always | ISO-8601 UTC, microsecond precision |
| `level` | always | `debug`, `info`, `notice`, `warning`, `error`, … |
| `message` | always | Rendered log message, truncated to 8 KiB |
| `request_id` | request-scoped logs | `Plug.RequestId` value, including LiveView processes |
| `method`, `path`, `status`, `duration_ms` | access lines | One HTTP request; no query string or body |
| `error.kind` | exceptions/crashes | Exception module, or the crash reason's kind |
| `error.reason` | exceptions/crashes | `Exception.message/1` or an inspected reason |
| `error.stacktrace` | exceptions/crashes | Array of formatted frames, capped at 50 |
| everything else | as supplied | Flattened atom metadata, sanitised and redacted |
Exceptions (`Logger.error(..., exception: ..., stacktrace: ...)`) and OTP crash
reports (`meta.crash_reason`, including Bandit request crashes and GenServer
terminations) become the `error` object. Stacktrace frames are an array of
strings so `jq -r '.error.stacktrace[]'` prints them readably.
## Redaction
The formatter redacts:
- metadata keys named `email`, `*_email`, `email_address`, `contact_email` or
`recipient`;
- any email-shaped string anywhere in metadata, nested `params`, or the rendered
message;
- credentials in `password`, `secret`, `token`, `authorization`, `cookie`,
`api_key`, `private_key` and `credential` keys;
- `token=...`/`password=...` assignments in messages.
Path segments of 20 or more URL-safe characters (reset/confirmation tokens,
UUIDs) are replaced with `[REDACTED]` in access lines. Query parameters and
request bodies are never logged.
## Access lines
`ChesstrainerWeb.RequestLogger` listens to `[:phoenix, :endpoint, :stop]` and
emits one `:info` line per HTTP request that reaches the endpoint, including a
LiveView's initial request. Phoenix's own endpoint start/stop pair is disabled
with `log: false` in `ChesstrainerWeb.Endpoint` so there is exactly one line.
`ChesstrainerWeb.Plugs.PutRequestId` copies `Plug.RequestId`'s id into the
session, and `UserAuth.mount_current_scope/2` puts it into `Logger.metadata/1`,
so logs from the LiveView process keep the id after the HTTP request ends.
## Writing logs
Normal `Logger` calls need no changes. Atom metadata keys are flattened into the
JSON object:
```elixir
require Logger
Logger.info("tablebase cache miss", table: :tablebase, key: key)
Logger.warning("tablebase fetch failed", status: 503, reason: reason)
```
For a caught exception, pass the exception and stacktrace so the formatter can
build the `error` object:
```elixir
Logger.error("cache backup failed", exception: exception, stacktrace: __STACKTRACE__)
```
For background work, wrap the body so `{:error, reason}` returns, throws, exits
and crashes all produce a log line:
```elixir
Task.Supervisor.start_child(Chesstrainer.Cache.BackupSupervisor, fn ->
Chesstrainer.Background.run("send digest", [user_id: user.id], fn ->
send_digest(user)
end)
end)
```
Prefer identifiers such as `user_id` or `table` over emails, and never log
params or request bodies. The formatter is a safety net, not a licence to log
PII.
## Authentication events
`ChesstrainerWeb.UserSessionController` emits warning lines consumed by
host-level tooling such as fail2ban:
| Message | Metadata | Meaning |
|---|---|---|
| `auth.login.failed` | `reason` (`invalid_credentials` / `unconfirmed`), `ip` | A password login failed. |
| `auth.login.throttled` | `reason` (`ip` / `login`), `ip` | The address or login bucket blocked the attempt before bcrypt. |
`ip` is a boot-scoped HMAC of the client address, not the address itself. The
raw login identifier and password are never included. The login throttle is
configured in `config/config.exs` and defaults to five failures per login and
ten per address in a fifteen-minute window.
## Querying logs
`journalctl` prints the raw line only with `-o cat`; the default output wraps it
in journald fields. Install `jq` once on the VPS with
`sudo apt-get install -y jq`, then:
```sh
# Pretty-print recent lines
sudo journalctl -u chesstrainer -o cat -n 50 --no-pager | jq .
# Errors only
sudo journalctl -u chesstrainer -o cat --since "1 hour ago" \
| jq 'select(.level == "error")'
# Everything from one request id
sudo journalctl -u chesstrainer -o cat \
| jq 'select(.request_id == "REQUEST_ID")'
# Crash reason and stacktrace
sudo journalctl -u chesstrainer -o cat \
| jq -r 'select(.error) | "\(.timestamp) \(.error.kind): \(.error.reason)\n\((.error.stacktrace // []) | join("\n"))"'
# Slow requests
sudo journalctl -u chesstrainer -o cat \
| jq 'select(.duration_ms > 1000) | {timestamp, method, path, status, duration_ms}'
# Most common error kinds in the current boot
sudo journalctl -u chesstrainer -o cat -b \
| jq -r 'select(.error.kind) | .error.kind' | sort | uniq -c | sort -rn
```
`Plug.RequestId` also returns the id in the `x-request-id` response header, so a
user can report the id from a failed request and you can filter straight to it.
## Local checks
The formatter tests run without a production release:
```sh
mix test test/chesstrainer/json_log_formatter_test.exs \
test/chesstrainer/background_test.exs \
test/chesstrainer_web/request_logger_test.exs
```
To render one event without touching the Logger configuration:
```sh
mix run --no-start -e '
event = %{
level: :error,
msg: {:string, "boom"},
meta: %{
time: System.system_time(:microsecond),
request_id: "req-1",
email: "user@example.com",
exception: %RuntimeError{message: "bad"},
stacktrace: [{Foo, :bar, 1, [file: ~c"lib/foo.ex", line: 10]}]
}
}
IO.puts(Chesstrainer.JSONLogFormatter.format(event, %{}))
'
```
That prints one JSON line with the email redacted and the exception unpacked
into `error`.
## Background work audit (#107)
Checked:
- `Chesstrainer.Cache` scheduled backup: `Task.Supervisor.start_child` ignored
the task's return value and `Persist.backup/1` returns `{:error, reason}`
without logging. Now wrapped in `Chesstrainer.Background.run/3`, which logs
`{:error, reason}` returns and crashes (with exception, reason and
stacktrace). A failure to start the task is logged too.
- `Chesstrainer.Cache.Persist.restore/1`: an unreadable backup was silently
skipped. It now logs a warning with the reason and starts with an empty cache.
- `Chesstrainer.Endgames.Tablebase.Parser`: Lichess 5xx and network failures
were returned to the caller (which shows a flash) but never logged. They now
log a warning with the status or reason. 429 cooldowns stay quiet because they
are expected.
- `Mix.Tasks.Tablebase.Fetch`: already aborts loudly with `Mix.raise` on HTTP or
network failure; no change.
- Email delivery: sends are synchronous and their error is returned to the
controller, so nothing is silent today. Future background sends should use
`Chesstrainer.Background.run/3`.
## Reading logs on the VPS
See the "Reading production logs" and "Keep the journal" sections in
[`deploy/README.md`](../deploy/README.md).
+191
View File
@@ -0,0 +1,191 @@
# Login and edge security
The login surface is protected in layers. The application throttle is the
primary control; Cloudflare is the edge backstop for volume. There is no
origin-level fail2ban for HTTP logins, because it would require storing raw IP
addresses and would ban Cloudflare edge addresses on this deployment.
## Current production configuration
- Caddy accepts only Cloudflare's published ranges and forwards
`CF-Connecting-IP` as `X-Forwarded-For`. The ranges are refreshed hourly by
`chesstrainer-cloudflare-ranges.timer`.
- `TRUST_FORWARDED_FOR=true`, so the app throttles by the real visitor address.
- Cloudflare Bot Fight Mode is off. The Caddy origin allowlist above stays in
force; re-enabling is tracked in #153.
- The free-plan login flood rule allows 10 login POSTs per 10 seconds per IP and
blocks for 10 seconds.
The short Cloudflare block is rate smoothing, not a credential lockout. The
application's 5-per-login and 10-per-address failures in a 15-minute window are
the real control.
## 1. Application login throttle
`ChesstrainerWeb.LoginThrottle` counts failures in two buckets:
| Bucket | Limit | Window |
|---|---|---|
| Normalised login (email or username) | 5 failures | 15 minutes |
| Client address | 10 failures | 15 minutes |
Blocked attempts are rejected before the database lookup and bcrypt, so they do
not consume password-hashing CPU. A successful login clears the login bucket
only, keeping the address bucket in place so one address cannot spray many
accounts.
The bucket keys are boot-scoped HMACs. Raw addresses and raw login identifiers
are never stored in ETS or written to the application logs. The login form
returns the same generic error for unknown accounts, bad passwords and
unconfirmed accounts.
Configured in `config/config.exs`:
```elixir
config :chesstrainer, ChesstrainerWeb.LoginThrottle,
window_ms: :timer.minutes(15),
max_per_login: 5,
max_per_ip: 10,
confirmation_cooldown_ms: :timer.minutes(15)
```
`auth.login.failed` and `auth.login.throttled` are documented in
`docs/logging.md`.
## 2. Real client IPs behind Cloudflare and Caddy
The production chain is:
```text
Internet
└─ Cloudflare
└─ Caddy :443
└─ Phoenix 127.0.0.1:4100
```
Caddy ignores incoming `X-Forwarded-*` values by default and replaces them with
the immediate peer address. Behind Cloudflare that peer is a Cloudflare edge
node, so without configuration the app would throttle whole Cloudflare POPs
rather than individual visitors.
`deploy/Caddyfile` fixes this by:
1. accepting only Cloudflare's published ranges, and
2. setting `X-Forwarded-For` from Cloudflare's single-value `CF-Connecting-IP`
header.
That keeps `TRUST_FORWARDED_FOR=true` safe: direct clients cannot reach the app
through Caddy, so they cannot forge the header.
`deploy/Caddyfile` imports `cloudflare-ranges.caddy`. The file is generated by
`deploy/update-cloudflare-ranges.sh`; do not edit it by hand.
The script is run hourly by `chesstrainer-cloudflare-ranges.timer`. It:
- downloads <https://www.cloudflare.com/ips-v4> and
<https://www.cloudflare.com/ips-v6>,
- rejects empty or malformed responses,
- validates the candidate Caddyfile,
- reloads Caddy only when the ranges changed.
If the download, validation or Caddy reload fails, the previous ranges stay in
place.
Install and run it:
```sh
sudo install -m 0755 /opt/chesstrainer/src/deploy/update-cloudflare-ranges.sh \
/usr/local/sbin/chesstrainer-update-cloudflare-ranges
sudo install -m 0644 /opt/chesstrainer/src/deploy/cloudflare-ranges.caddy \
/etc/caddy/cloudflare-ranges.caddy
sudo install -m 0644 /opt/chesstrainer/src/deploy/chesstrainer-cloudflare-ranges.service \
/etc/systemd/system/chesstrainer-cloudflare-ranges.service
sudo install -m 0644 /opt/chesstrainer/src/deploy/chesstrainer-cloudflare-ranges.timer \
/etc/systemd/system/chesstrainer-cloudflare-ranges.timer
sudo systemctl daemon-reload
sudo systemctl enable --now chesstrainer-cloudflare-ranges.timer
sudo systemctl start chesstrainer-cloudflare-ranges.service
```
If `/opt/chesstrainer/src/deploy` is not present on the VPS, create the same
four files directly with `sudo tee` from the canonical contents in `deploy/`.
The timer only uses the installed copies.
Check the timer and last run:
```sh
systemctl list-timers chesstrainer-cloudflare-ranges.timer
systemctl status chesstrainer-cloudflare-ranges.service
journalctl -u chesstrainer-cloudflare-ranges.service --since "24 hours ago"
```
Apply the site block by hand on the shared Caddy host, then validate and
reload:
```sh
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
```
Direct requests to the origin with a spoofed `CF-Connecting-IP` must receive
`403 Access Denied`; only Cloudflare's ranges should reach the Phoenix app. A
host firewall allowlist for Cloudflare on ports 80 and 443 is a useful
defence-in-depth addition.
## 3. Cloudflare edge rate limiting
This is for connection and request floods, not credential guessing. The
application already stops password attempts cheaply.
The production rule is the free-plan version:
| Setting | Value |
|---|---|
| Name | Login POST flood |
| Expression | `(http.request.method eq "POST" and http.request.uri.path in {"/admin/log-in" "/users/log-in"})` |
| Characteristic | IP |
| Period | 10 seconds |
| Requests | 10 |
| Action | Block |
| Duration | 10 seconds |
Because the free plan only offers a 10-second period and a 10-second block, this
is a burst limiter rather than a lasting ban. An attacker can retry after ten
seconds, but the application still stops that login after five failures and that
address after ten failures within fifteen minutes. A slow attacker staying under
10 requests per 10 seconds never gets to make useful guesses because of the app
throttle.
Bot Fight Mode is off. On the free plan it cannot be skipped for CI or for the
on-box health probe, so a datacenter `curl` gets a 403 while the site itself is
healthy; #153 covers the gate and probe changes needed before it goes back on.
If the plan later gains longer rate-limit windows or managed WAF rules, raise
the block duration and consider a broader site-wide rule, such as 100 requests
per 10 seconds per IP with a managed challenge. Use Under Attack Mode during an
active incident.
### Registration cannot be limited this way
`/users/register` is a LiveView. The form submit is a LiveView event sent over
the shared `/live/websocket` connection, not a `POST /users/register` request.
Cloudflare therefore cannot count account creations with a rule on the
registration path.
A Cloudflare rule on `GET /users/register` only limits page opens; a bot can
open one page and submit many registrations over the socket. If registration
spam becomes a problem, add an application-level registration throttle keyed by
`ChesstrainerWeb.ClientAddress.from_socket/1`, and/or add Cloudflare Turnstile
to the form.
While `PRELAUNCH=true`, registration is blocked entirely by the prelaunch plug
and LiveView mount redirect.
## 4. Why not fail2ban for HTTP?
fail2ban needs the raw client address to build a firewall rule. The application
deliberately logs only a boot-scoped HMAC, and this deployment sits behind
Cloudflare. Banning the address that reaches the origin would ban Cloudflare
edges, not attackers.
fail2ban remains useful for services that terminate connections directly on the
VPS, such as SSH. It is not part of the HTTP login defence.
+19 -2
View File
@@ -23,10 +23,27 @@ machine and a VPS will point at different copies.
export TABLEBASE_PATH=/home/you/Downloads/tablebase
mix phx.server
# Production (release)
TABLEBASE_PATH=/data/syzygy/3-4-5 bin/chesstrainer start
# Production (release), behind systemd
TABLEBASE_PATH=/opt/chesstrainer/tablebases bin/chesstrainer start
```
On the production VPS the directory is `/opt/chesstrainer/tablebases`, owned by
the `chesstrainer` user. Set `TABLEBASE_PATH` in `/etc/chesstrainer/env` rather
than an interactive shell, then restart `chesstrainer.service` — the value is
read at boot.
```sh
sudo chown -R chesstrainer:chesstrainer /opt/chesstrainer/tablebases
sudo chmod -R u=rwX,g=rX,o= /opt/chesstrainer/tablebases
sudo systemctl restart chesstrainer
curl -s http://127.0.0.1:4100/health
```
Healthy local tablebases report `tablebase: "local"` and `status: "ok"`. A
missing, empty, or unreadable directory reports `tablebase: "fallback"` or
`"not_configured"` and `status: "degraded"`, still with HTTP 200 because the
Lichess fallback is available.
The value must reach the process. A bare `TABLEBASE_PATH=...` line in bash
only sets a shell variable and is **not** exported to `mix` or the release —
use `export`, or prefix the command. For a release, systemd unit or container,
+318 -1
View File
@@ -4,11 +4,14 @@ defmodule Chesstrainer.Accounts do
"""
import Ecto.Query, warn: false
require Logger
alias Chesstrainer.Repo
alias Chesstrainer.Accounts.{User, UserToken, UserNotifier}
alias Chesstrainer.Accounts.{Policy, Role, Scope, User, UserToken, UserNotifier}
alias Chesstrainer.MailingList
@admin_users_per_page 25
## Database getters
@doc """
@@ -165,6 +168,320 @@ defmodule Chesstrainer.Accounts do
|> Repo.update()
end
@doc """
Updates a user's subscription plan.
Plans are programmatic values; registration never casts `plan`, so a user
cannot upgrade themselves.
"""
def update_user_plan(%User{} = user, plan) do
user
|> User.plan_changeset(%{plan: plan})
|> Repo.update()
end
## Admin user management
@doc """
Returns a page of users the scope may administer, newest first.
Options:
* `:search` - case-insensitive match on email or username
* `:page` - 1-based page number (defaults to 1)
* `:per_page` - page size (defaults to 25, capped at 100)
Admins only see members and moderators; super admins see every role.
Returns `{:error, :unauthorized}` when the scope lacks user management.
"""
def list_users_for_admin(scope, opts \\ []) do
with :ok <- ensure_manage_users(scope) do
page = normalize_page(Keyword.get(opts, :page, 1))
per_page = normalize_per_page(Keyword.get(opts, :per_page, @admin_users_per_page))
offset = (page - 1) * per_page
users =
scope
|> admin_users_query(opts)
|> order_by([u], desc: u.inserted_at, desc: u.id)
|> limit(^per_page)
|> offset(^offset)
|> Repo.all()
{:ok, users}
end
end
@doc """
Counts the users visible to the scope, using the same filters as
`list_users_for_admin/2`.
"""
def count_users_for_admin(scope, opts \\ []) do
with :ok <- ensure_manage_users(scope) do
count =
scope
|> admin_users_query(opts)
|> select([u], count(u.id))
|> Repo.one()
{:ok, count}
end
end
@doc """
Fetches a user for the admin detail page.
Returns `{:error, :unauthorized}` when the scope may not view the target and
`{:error, :not_found}` for an unknown id.
"""
def get_user_for_admin(scope, id) do
with :ok <- ensure_manage_users(scope) do
case fetch_user(id) do
nil ->
{:error, :not_found}
%User{} = user ->
if Policy.can_view_user?(scope, user) do
{:ok, user}
else
{:error, :unauthorized}
end
end
end
end
@doc """
Returns an `%Ecto.Changeset{}` for the admin-editable fields (role and plan).
"""
def change_user_as_admin(%User{} = user, attrs \\ %{}) do
User.admin_changeset(user, attrs)
end
@doc """
Updates a user's role and plan after enforcing the admin capability matrix.
The last-super-admin check runs inside the update transaction with a row lock,
so concurrent demotions cannot remove the final super admin.
Returns `{:error, :unauthorized}`, `{:error, :own_role}`,
`{:error, :last_super_admin}` or `{:error, %Ecto.Changeset{}}` instead of
raising.
"""
def update_user_as_admin(scope, %User{} = user, attrs) do
changeset = User.admin_changeset(user, attrs)
role_change = Ecto.Changeset.get_change(changeset, :role)
with :ok <- ensure_manage_users(scope),
:ok <- ensure_not_own_role_change(scope, user, role_change),
:ok <- ensure_can_manage_user(scope, user),
:ok <- ensure_can_assign_role(scope, role_change),
{:ok, updated} <- persist_user_changes(user, changeset) do
log_user_update(scope, user, changeset)
{:ok, updated}
end
end
@doc """
Creates an invitation and emails the recipient a link to choose a password.
The account is confirmed but has no password until the invitee follows the
link. `invite_url_fun` receives the encoded token and must return a URL.
"""
def invite_user_as_admin(scope, attrs, invite_url_fun)
when is_function(invite_url_fun, 1) do
role = normalize_role(role_param(attrs) || :member)
with :ok <- ensure_manage_users(scope),
:ok <- ensure_can_assign_role(scope, role) do
changeset =
%User{}
|> User.invite_changeset(attrs)
|> User.admin_changeset(attrs)
case Repo.insert(changeset) do
{:ok, user} ->
Logger.info("admin.user.invited",
actor_id: scope.user.id,
target_id: user.id,
fields: [:invite]
)
case deliver_invite_instructions(user, invite_url_fun) do
{:ok, _email} -> {:ok, user}
{:error, reason} -> {:error, reason}
end
{:error, changeset} ->
{:error, changeset}
end
end
end
@doc """
Sends a password-reset email on behalf of an administrator.
Uses the same policy as the editable user screen: an admin cannot trigger a
reset for another admin or a super admin.
"""
def send_user_reset_password_instructions_as_admin(scope, %User{} = user, reset_url_fun)
when is_function(reset_url_fun, 1) do
with :ok <- ensure_manage_users(scope),
:ok <- ensure_can_manage_user(scope, user) do
case deliver_user_reset_password_instructions(user, reset_url_fun) do
{:ok, email} ->
Logger.info("admin.user.password_reset_sent",
actor_id: scope.user.id,
target_id: user.id
)
{:ok, email}
error ->
error
end
end
end
@doc """
Resends the account-confirmation email on behalf of an administrator.
"""
def resend_user_confirmation_instructions_as_admin(scope, %User{} = user, confirmation_url_fun)
when is_function(confirmation_url_fun, 1) do
with :ok <- ensure_manage_users(scope),
:ok <- ensure_can_manage_user(scope, user) do
case deliver_user_confirmation_instructions(user, confirmation_url_fun) do
{:ok, email} ->
Logger.info("admin.user.confirmation_resent",
actor_id: scope.user.id,
target_id: user.id
)
{:ok, email}
error ->
error
end
end
end
defp admin_users_query(scope, opts) do
roles = Policy.visible_roles(scope)
search = opts |> Keyword.get(:search, "") |> to_string() |> String.trim()
query = from(u in User, where: u.role in ^roles)
if search == "" do
query
else
pattern = "%#{search}%"
where(
query,
[u],
ilike(u.email, ^pattern) or ilike(u.username, ^pattern)
)
end
end
defp persist_user_changes(user, changeset) do
Repo.transact(fn ->
with :ok <- ensure_not_last_super_admin(user, changeset),
{:ok, updated} <- Repo.update(changeset) do
{:ok, updated}
end
end)
end
defp ensure_not_last_super_admin(%User{role: :super_admin}, changeset) do
case Ecto.Changeset.get_change(changeset, :role) do
role when role in [nil, :super_admin] ->
:ok
_role ->
super_admins =
Repo.all(from(u in User, where: u.role == :super_admin, lock: "FOR UPDATE"))
if length(super_admins) <= 1 do
{:error, :last_super_admin}
else
:ok
end
end
end
defp ensure_not_last_super_admin(_user, _changeset), do: :ok
defp log_user_update(scope, user, changeset) do
fields = changeset.changes |> Map.keys() |> Enum.sort()
if fields != [] do
Logger.info("admin.user.updated",
actor_id: scope.user.id,
target_id: user.id,
fields: fields
)
end
end
defp deliver_invite_instructions(user, invite_url_fun) do
{encoded_token, user_token} = UserToken.build_email_token(user, "reset_password")
Repo.insert!(user_token)
UserNotifier.deliver_invite_instructions(user, invite_url_fun.(encoded_token))
end
defp ensure_manage_users(scope) do
if Policy.can?(scope, :manage_users), do: :ok, else: {:error, :unauthorized}
end
defp ensure_can_manage_user(scope, user) do
if Policy.can_manage_user?(scope, user), do: :ok, else: {:error, :unauthorized}
end
defp ensure_can_assign_role(_scope, nil), do: :ok
defp ensure_can_assign_role(scope, role) do
if Policy.can_assign_role?(scope, role), do: :ok, else: {:error, :unauthorized}
end
defp ensure_not_own_role_change(%Scope{user: %User{id: id}}, %User{id: id}, role)
when not is_nil(role),
do: {:error, :own_role}
defp ensure_not_own_role_change(_scope, _user, _role), do: :ok
defp fetch_user(id) do
Repo.get(User, id)
rescue
Ecto.Query.CastError -> nil
end
defp role_param(attrs), do: Map.get(attrs, "role") || Map.get(attrs, :role)
defp normalize_role(role) do
cond do
role in Role.values() -> role
is_binary(role) -> Enum.find(Role.values(), &(Atom.to_string(&1) == role))
true -> nil
end
end
defp normalize_page(page) when is_integer(page) and page > 0, do: page
defp normalize_page(page) when is_binary(page) do
case Integer.parse(page) do
{number, ""} when number > 0 -> number
_ -> 1
end
end
defp normalize_page(_page), do: 1
defp normalize_per_page(per_page) when is_integer(per_page) and per_page > 0 do
min(per_page, 100)
end
defp normalize_per_page(_per_page), do: @admin_users_per_page
## Settings
@doc """
+100
View File
@@ -0,0 +1,100 @@
defmodule Chesstrainer.Accounts.Policy do
@moduledoc """
The single source of truth for administrator capabilities.
Roles are ordered by `Chesstrainer.Accounts.Role`. An administrator may only
manage users below their own rank; a `super_admin` may also manage admins and
other super admins, but never changes their own role.
The router uses `can?/2` to gate the admin area, and every mutating admin
LiveView calls back into this module or into the scoped `Accounts` functions
so hidden buttons are never the only protection.
"""
alias Chesstrainer.Accounts.{Role, Scope, User}
@capabilities %{
manage_endgames: [:admin, :super_admin],
manage_themes: [:admin, :super_admin],
manage_users: [:admin, :super_admin]
}
@doc "All admin capabilities."
@spec capabilities() :: [atom()]
def capabilities, do: Map.keys(@capabilities)
@doc """
Returns true when the scope may perform the given admin capability.
A nil scope or a member/moderator never satisfies an admin capability.
"""
@spec can?(Scope.t() | nil, atom()) :: boolean()
def can?(%Scope{user: %User{role: role}}, capability) when is_atom(capability) do
role in Map.get(@capabilities, capability, [])
end
def can?(_scope, _capability), do: false
@doc """
Returns true when the scope may edit the target user's role and plan.
An actor may only modify a user whose role rank is strictly lower, except a
`super_admin`, who may also modify admins and other super admins. Nobody may
modify themselves through the admin area.
"""
@spec can_manage_user?(Scope.t() | nil, User.t()) :: boolean()
def can_manage_user?(%Scope{user: %User{} = actor} = scope, %User{} = target) do
cond do
not can?(scope, :manage_users) -> false
actor.id == target.id -> false
actor.role == :super_admin -> true
Role.rank(actor.role) > Role.rank(target.role) -> true
true -> false
end
end
def can_manage_user?(_scope, _target), do: false
@doc """
Returns true when the scope may view the target user in the admin area.
Admins can see themselves and lower-ranked users read-only; super admins can
see everyone. This is deliberately wider than `can_manage_user?/2`, which
controls the editable form.
"""
@spec can_view_user?(Scope.t() | nil, User.t()) :: boolean()
def can_view_user?(%Scope{user: %User{} = actor} = scope, %User{} = target) do
can?(scope, :manage_users) and
(actor.id == target.id or actor.role == :super_admin or
Role.rank(actor.role) > Role.rank(target.role))
end
def can_view_user?(_scope, _target), do: false
@doc """
Returns true when the scope may assign the given role.
Admins can only assign member or moderator. Super admins can assign any role.
"""
@spec can_assign_role?(Scope.t() | nil, Role.value()) :: boolean()
def can_assign_role?(%Scope{user: %User{role: :super_admin}}, role) do
role in Role.values()
end
def can_assign_role?(%Scope{user: %User{role: actor_role}}, role) do
role in Role.values() and Role.rank(actor_role) > Role.rank(role)
end
def can_assign_role?(_scope, _role), do: false
@doc """
Returns the roles whose users the scope may see in the admin user list.
Admins only see members and moderators; super admins see every role.
"""
@spec visible_roles(Scope.t() | nil) :: [Role.value()]
def visible_roles(%Scope{user: %User{role: :super_admin}}), do: Role.values()
def visible_roles(%Scope{user: %User{role: :admin}}), do: [:member, :moderator]
def visible_roles(_scope), do: []
end
+2
View File
@@ -6,6 +6,8 @@ defmodule Chesstrainer.Accounts.Role do
should ask for the minimum tier they need via `at_least?/2`.
"""
@type value :: :member | :moderator | :admin | :super_admin
@values [:member, :moderator, :admin, :super_admin]
@ranks %{
+2
View File
@@ -20,6 +20,8 @@ defmodule Chesstrainer.Accounts.Scope do
defstruct user: nil
@type t :: %__MODULE__{user: User.t() | nil}
@doc """
Creates a scope for the given user.
+39
View File
@@ -20,6 +20,8 @@ defmodule Chesstrainer.Accounts.User do
timestamps(type: :utc_datetime)
end
@type t :: %__MODULE__{}
@doc """
A user changeset for registration.
@@ -53,6 +55,43 @@ defmodule Chesstrainer.Accounts.User do
|> validate_required([:role])
end
@doc """
A user changeset for changing the plan.
The plan is programmatic and must never be cast from user-supplied params.
"""
def plan_changeset(user, attrs) do
user
|> cast(attrs, [:plan])
|> validate_required([:plan])
end
@doc """
A user changeset for an admin-created invitation.
The account is created without a password and marked confirmed, so the
recipient can choose a password from the emailed invitation link and log in
immediately afterwards. Role and plan are applied separately by
`admin_changeset/2` after the caller has checked the policy.
"""
def invite_changeset(user, attrs) do
user
|> cast(attrs, [:email, :username])
|> validate_email([])
|> validate_username([])
|> put_change(:confirmed_at, DateTime.utc_now(:second))
end
@doc """
A user changeset for the fields an administrator may edit.
These values are programmatic, so this changeset is only used by the scoped
admin functions in `Chesstrainer.Accounts`.
"""
def admin_changeset(user, attrs) do
cast(user, attrs, [:role, :plan])
end
@doc """
A user changeset for registering or changing the email.
+31 -11
View File
@@ -2,20 +2,15 @@ defmodule Chesstrainer.Accounts.UserNotifier do
import Swoosh.Email
alias Chesstrainer.Branding
alias Chesstrainer.Mailer
alias Chesstrainer.Mail
# Delivers the email using the application mailer.
defp deliver(recipient, subject, body) do
email =
new()
|> to(recipient)
|> from({Branding.name(), Branding.mail_from()})
|> subject(subject)
|> text_body(body)
with {:ok, _metadata} <- Mailer.deliver(email) do
{:ok, email}
end
new()
|> to(recipient)
|> subject(subject)
|> text_body(body)
|> Mail.deliver()
end
@doc """
@@ -38,6 +33,31 @@ defmodule Chesstrainer.Accounts.UserNotifier do
""")
end
@doc """
Deliver an invitation to choose a password.
Admins create the account without a password; the invitation link uses the
same reset-password token flow so the recipient can set one.
"""
def deliver_invite_instructions(user, url) do
deliver(user.email, "You're invited to #{Branding.name()}", """
==============================
Hi #{user.username},
An administrator has created an account for you on #{Branding.name()}.
Choose your password by visiting the URL below:
#{url}
If you weren't expecting this invitation, please ignore this email.
==============================
""")
end
@doc """
Deliver instructions to reset a user password.
"""
+1
View File
@@ -17,6 +17,7 @@ defmodule Chesstrainer.Application do
# Start a worker by calling: Chesstrainer.Worker.start_link(arg)
# {Chesstrainer.Worker, arg},
Chesstrainer.GuestLimits,
ChesstrainerWeb.LoginThrottle,
# Start to serve requests, typically the last entry
ChesstrainerWeb.Endpoint,
{Registry, keys: :unique, name: Chesstrainer.CacheRegistry},
+2 -2
View File
@@ -106,8 +106,8 @@ defmodule Chesstrainer.Attempts do
@doc """
The distinct endgame ids `user_id` has attempted in the last `days` days.
Used by puzzle selection to prefer fresh puzzles; a retry still counts as an
attempt, even though the rating window leaves it unrated.
Used by puzzle selection to skip puzzles inside the repeat window; a retry
still counts as an attempt, even though the rating window leaves it unrated.
"""
def recent_endgame_ids(user_id, days \\ 30) do
cutoff = DateTime.add(DateTime.utc_now(), -days, :day)
+63
View File
@@ -0,0 +1,63 @@
defmodule Chesstrainer.Background do
@moduledoc """
Runs background work and logs any failure.
Background failures otherwise disappear: a task exits, the supervisor keeps
the rest of the system running, and nobody sees why the work did not happen.
This wrapper turns crashes, throws, exits and `{:error, reason}` returns into
one structured error line with the reason and stacktrace.
The label is a short description of the work; metadata is added to the log
line unchanged (minus the formatter's own redaction).
"""
require Logger
@type result :: term()
@doc """
Runs `fun` and logs a failure. Returns the function's value, or `:error` when
it crashed or returned an error tuple.
"""
@spec run(String.t(), (-> result)) :: result() | :error
def run(label, fun), do: run(label, [], fun)
@doc """
Like `run/2`, with extra metadata for the error line.
"""
@spec run(String.t(), keyword(), (-> result)) :: result() | :error
def run(label, metadata, fun)
when is_binary(label) and is_list(metadata) and is_function(fun, 0) do
case fun.() do
{:error, reason} ->
Logger.error(
"#{label} failed: #{format_term(reason)}",
Keyword.merge(metadata, reason: reason)
)
:error
result ->
result
end
rescue
exception ->
Logger.error(
"#{label} crashed: #{Exception.message(exception)}",
Keyword.merge(metadata, exception: exception, stacktrace: __STACKTRACE__)
)
:error
catch
kind, reason ->
Logger.error(
"#{label} crashed: #{format_term(reason)}",
Keyword.merge(metadata, kind: kind, reason: reason, stacktrace: __STACKTRACE__)
)
:error
end
defp format_term(term) when is_binary(term), do: term
defp format_term(term), do: inspect(term, limit: 10, printable_limit: 500)
end
+22 -1
View File
@@ -12,7 +12,8 @@ defmodule Chesstrainer.Branding do
wordmark: "INNERSQUARE",
tagline: "Endgame Trainer",
support_email: "support@innersquare.app",
mail_from: "no-reply@innersquare.app"
mail_from: "no-reply@mail.innersquare.app",
discord_invite: "https://discord.gg/Z2NfkG7thV"
]
@doc "The display name, e.g. `\"Lucid Chess\"`."
@@ -30,6 +31,26 @@ defmodule Chesstrainer.Branding do
@doc "The From address used for outgoing mail."
def mail_from, do: get(:mail_from)
@doc """
The Discord invite URL, or `nil` when no invite is configured.
Accepts either a bare invite code (`"abc123"`) or a full URL; a bare code is
expanded to `https://discord.gg/<code>`.
"""
def discord_invite_url do
case get(:discord_invite) do
value when is_binary(value) ->
case String.trim(value) do
"" -> nil
"http" <> _ = url -> url
code -> "https://discord.gg/#{code}"
end
_ ->
nil
end
end
@doc "The home-page title, e.g. `\"Lucid Chess — Endgame Trainer\"`."
def home_title, do: "#{name()} — #{tagline()}"
+16 -2
View File
@@ -11,7 +11,8 @@ defmodule Chesstrainer.Cache do
that were used heavily once but have not been used since eventually age out.
A daily backup runs off the cache process at a configurable UTC time, so reads
and writes stay responsive while the snapshot is written.
and writes stay responsive while the snapshot is written. Failures are logged
rather than lost.
## Examples
@@ -19,7 +20,9 @@ defmodule Chesstrainer.Cache do
"""
use GenServer
require Logger
alias Chesstrainer.Background
alias Chesstrainer.Cache.BackupSchedule
alias Chesstrainer.Cache.Persist
@@ -121,7 +124,18 @@ defmodule Chesstrainer.Cache do
table = state.table
backup_fun = state.backup_fun
Task.Supervisor.start_child(Chesstrainer.Cache.BackupSupervisor, fn -> backup_fun.(table) end)
task = fn ->
Background.run("cache backup", [table: table], fn -> backup_fun.(table) end)
end
case Task.Supervisor.start_child(Chesstrainer.Cache.BackupSupervisor, task) do
{:ok, _pid} ->
:ok
{:error, reason} ->
Logger.error("cache backup could not start", table: table, reason: reason)
:ok
end
end
defp schedule_backup(state) do
+7 -1
View File
@@ -5,8 +5,13 @@ defmodule Chesstrainer.Cache.Persist do
A backup is written to a temporary DETS file in the same directory and then
atomically renamed into place. A crash during the write therefore leaves the
previous backup untouched instead of a truncated file that fails to restore.
A backup that cannot be opened at boot is logged and skipped, so a damaged
file does not stop the application from starting with an empty cache.
"""
require Logger
@backup_path "priv/static/backups"
@format_version "v2"
@@ -54,7 +59,8 @@ defmodule Chesstrainer.Cache.Persist do
:dets.close(table)
{:error, _} ->
{:error, reason} ->
Logger.warning("cache backup restore failed", table: table, reason: reason)
:ok
end
end
+44 -4
View File
@@ -111,8 +111,13 @@ defmodule Chesstrainer.Endgames do
@doc """
Returns `{key, count}` groups for endgames matching the filters, sorted by key.
Filters is a map with optional `:themes` (a list of theme ids; an endgame must
carry any one of them) and `:key` (an exact Key).
Filters is a map with optional:
* `:themes` - a list of theme ids; an endgame must carry any one of them
* `:key` - an exact Key
* `:with_theme` - `{theme_id, source}`; only endgames linked to the theme
with that source
* `:without_theme` - a theme id; only endgames not linked to the theme at all
"""
def list_key_groups(filters \\ %{}) do
Endgame
@@ -125,20 +130,31 @@ defmodule Chesstrainer.Endgames do
@doc """
Returns the endgames for one Key, matching the filters, with themes preloaded.
Accepts `:limit` and `:offset` options for paginating large Key groups.
"""
def list_endgames_for_key(key, filters \\ %{}) do
def list_endgames_for_key(key, filters \\ %{}, opts \\ []) do
skip = Keyword.get(opts, :offset, 0)
Endgame
|> apply_filters(filters)
|> where([e], e.key == ^key)
|> preload(:themes)
|> order_by([e], asc: e.fen)
|> order_by([e], asc: e.fen, asc: e.id)
|> limit_query(Keyword.get(opts, :limit))
|> offset(^skip)
|> Repo.all()
end
defp limit_query(query, nil), do: query
defp limit_query(query, limit), do: limit(query, ^limit)
defp apply_filters(query, filters) do
query
|> filter_themes(Map.get(filters, :themes, []))
|> filter_key(Map.get(filters, :key))
|> filter_with_theme(Map.get(filters, :with_theme))
|> filter_without_theme(Map.get(filters, :without_theme))
end
defp filter_themes(query, []), do: query
@@ -156,6 +172,30 @@ defmodule Chesstrainer.Endgames do
defp filter_key(query, key) when key in [nil, ""], do: query
defp filter_key(query, key), do: where(query, [e], e.key == ^key)
defp filter_with_theme(query, nil), do: query
defp filter_with_theme(query, {theme_id, source}) do
endgame_ids =
from(t in "endgames_themes",
where: t.theme_id == ^theme_id and t.source == ^to_string(source),
select: t.endgame_id
)
where(query, [e], e.id in subquery(endgame_ids))
end
defp filter_without_theme(query, nil), do: query
defp filter_without_theme(query, theme_id) do
endgame_ids =
from(t in "endgames_themes",
where: t.theme_id == ^theme_id,
select: t.endgame_id
)
where(query, [e], e.id not in subquery(endgame_ids))
end
@doc """
Gets a single endgame.
+218
View File
@@ -0,0 +1,218 @@
defmodule Chesstrainer.Endgames.BulkImport do
@moduledoc """
Classifies pasted FENs for the admin bulk importer and inserts the positions
the local Syzygy tablebase can answer.
Results always come from `Chesstrainer.Endgames.Tablebase.probe_local_result/1`,
so a bulk import never consults the remote (Lichess) backend.
"""
import Ecto.Query, warn: false
alias Chesstrainer.Endgames.Endgame
alias Chesstrainer.Endgames.Tablebase
alias Chesstrainer.{FEN, Key, Repo}
@max_fens 1000
@max_pieces 5
@default_rating 1500.0
@type status ::
:ready
| :duplicate
| :invalid_fen
| :too_many_pieces
| :illegal
| :terminal
| :unsupported
@type entry :: %{
line: pos_integer(),
fen: String.t(),
key: String.t() | nil,
color: :white | :black | nil,
result: Tablebase.result() | nil,
status: status(),
reason: String.t() | nil
}
@doc """
The most FENs a single import will consider.
"""
@spec max_fens() :: pos_integer()
def max_fens, do: @max_fens
@doc """
Parses one FEN per line, skipping blank lines and lines beginning with `#`.
Returns entries with a status explaining whether the line can be imported,
and `too_many?` when the input exceeded `max_fens/0` (only the first
`max_fens/0` lines are considered).
FENs already in the database and duplicates within the batch are reported as
duplicates without probing the tablebase.
"""
@spec preview(String.t()) :: %{entries: [entry()], too_many?: boolean()}
def preview(text) when is_binary(text) do
lines = parse_lines(text)
{lines, rest} = Enum.split(lines, @max_fens)
fens = Enum.map(lines, fn {_line, fen} -> FEN.normalize(fen) end)
existing = existing_fens(fens)
{entries, _seen} =
Enum.map_reduce(lines, %{}, fn {line, raw_fen}, seen ->
classify(line, FEN.normalize(raw_fen), seen, existing)
end)
%{entries: entries, too_many?: rest != []}
end
@doc """
Inserts every `:ready` entry, attaching `themes` and `rating` to each.
Rows that collide with an existing FEN are skipped. Returns the number
imported and the number of entries that were not ready or were skipped.
"""
@spec commit([entry()], [Chesstrainer.Themes.Theme.t()], number()) ::
%{imported: non_neg_integer(), skipped: non_neg_integer()}
def commit(entries, themes \\ [], rating \\ @default_rating) do
ready = Enum.filter(entries, &(&1.status == :ready))
now = DateTime.utc_now() |> DateTime.truncate(:second)
rows =
Enum.map(ready, fn entry ->
%{
id: Ecto.UUID.generate(),
public_code: Endgame.generate_public_code(),
fen: entry.fen,
color: entry.color,
key: entry.key,
result: entry.result,
rating: (rating || @default_rating) * 1.0,
rating_deviation: 350.0,
times_attempted: 0,
times_solved: 0,
inserted_at: now,
updated_at: now
}
end)
{imported, inserted_rows} =
Repo.insert_all(Endgame, rows, on_conflict: :nothing, returning: [:id])
join_rows =
for %Endgame{id: id} <- inserted_rows, theme <- themes do
%{
endgame_id: Ecto.UUID.dump!(id),
theme_id: theme.id
}
end
if join_rows != [] do
Repo.insert_all("endgames_themes", join_rows, on_conflict: :nothing)
end
%{imported: imported, skipped: length(entries) - imported}
end
defp parse_lines(text) do
text
|> String.split(~r/\r?\n/)
|> Enum.with_index(1)
|> Enum.reduce([], fn {raw, index}, acc ->
trimmed = String.trim(raw)
if trimmed == "" or String.starts_with?(trimmed, "#") do
acc
else
[{index, trimmed} | acc]
end
end)
|> Enum.reverse()
end
defp existing_fens(fens) do
fens
|> Enum.uniq()
|> then(fn fens -> Repo.all(from e in Endgame, where: e.fen in ^fens, select: e.fen) end)
|> Map.new(&{&1, true})
end
defp classify(line, fen, seen, existing) do
cond do
Map.has_key?(seen, fen) ->
{entry(line, fen, :duplicate, "Duplicate FEN in this batch"), seen}
Map.has_key?(existing, fen) ->
{entry(line, fen, :duplicate, "FEN already exists"), seen}
true ->
{classify_new(line, fen), Map.put(seen, fen, true)}
end
end
defp classify_new(line, fen) do
issues = Endgame.fen_issues(fen)
pieces = FEN.piece_count(fen)
cond do
issues != [] ->
entry(line, fen, :invalid_fen, Enum.join(issues, "; "))
is_integer(pieces) and pieces > @max_pieces ->
entry(
line,
fen,
:too_many_pieces,
"Only positions with #{@max_pieces} or fewer pieces are supported"
)
true ->
classify_probe(line, fen)
end
end
defp classify_probe(line, fen) do
case Tablebase.probe_local_result(fen) do
{:ok, result} ->
entry(line, fen, :ready, nil) |> Map.put(:result, result)
{:error, :terminal} ->
entry(line, fen, :terminal, "Checkmate, stalemate, or no legal moves")
{:error, :illegal} ->
entry(line, fen, :illegal, "The tablebase rejected this position")
{:error, :not_configured} ->
entry(
line,
fen,
:unsupported,
"Local tablebase is not configured (set TABLEBASE_PATH)"
)
{:error, :unsupported} ->
entry(line, fen, :unsupported, "The local tablebase cannot answer this position")
end
end
defp entry(line, fen, status, reason) do
%{
line: line,
fen: fen,
key: key_for(fen),
color: FEN.color_from_fen(fen),
result: nil,
status: status,
reason: reason
}
end
defp key_for(fen) do
case Key.from_fen(fen) do
{:ok, key} -> key
_ -> nil
end
end
end
+9 -4
View File
@@ -90,10 +90,15 @@ defmodule Chesstrainer.Endgames.Endgame do
defp normalize_attrs(attrs), do: attrs
# Strict structural validation. Mirrors chess.js rules so the FEN survives
# both the server-side parser (Chex, permissive) and the client-side parser
# (chess.js, strict).
defp fen_issues(fen) do
@doc """
Returns the structural problems with a FEN, or `[]` when it is well formed.
Strict structural validation. Mirrors chess.js rules so the FEN survives
both the server-side parser (Chex, permissive) and the client-side parser
(chess.js, strict). Used by the admin bulk importer to explain why a line
was rejected.
"""
def fen_issues(fen) do
case String.split(fen, " ") do
[board, active, _castling, _en_passant, halfmove, fullmove] ->
board_valid? = valid_board?(board)
@@ -0,0 +1,215 @@
defmodule Chesstrainer.Endgames.MaterialThemes do
@moduledoc """
Derives each endgame's material family from its canonical Key.
Every endgame belongs to exactly one family, so the themes behave as a
partition: selecting several in a filter produces their union, never an
ambiguous intersection. A lone king against heavy or pawn material is split
out because those positions teach a specific technique — basic mate or
promotion — rather than a general material class.
Families are derived, never judged. They are stored with source `derived`, so
a refresh replaces them without touching curated or community themes.
Positions with no legal content (`K v K`) and rows without a Key are skipped.
"""
import Ecto.Query, warn: false
alias Chesstrainer.Endgames.Endgame
alias Chesstrainer.Repo
alias Chesstrainer.Themes
@families [
basic_mate: %{
name: "basic mate",
description:
"A lone king against the queen or a rook, with no pawns: the puzzle is about delivering mate."
},
king_and_pawn: %{
name: "king and pawn",
description:
"A lone king against king and pawns: the puzzle is about promotion, or holding the draw."
},
bare_king_other: %{
name: "bare king other",
description:
"A lone king against minor pieces, or against pawns and pieces: usually a technique exercise with little counterplay."
},
queen_and_pawn: %{
name: "queen and pawn",
description: "Queens and pawns on the board."
},
queen_endgame: %{
name: "queen endgame",
description: "Queens on the board, with no pawns."
},
rook_and_pawn: %{
name: "rook and pawn",
description: "Rooks and pawns, with no queens."
},
rook_endgame: %{
name: "rook endgame",
description: "Rooks, with no queens and no pawns."
},
minor_piece_and_pawn: %{
name: "minor piece and pawn",
description: "Bishops and knights with pawns, with no queens or rooks."
},
minor_piece_endgame: %{
name: "minor piece endgame",
description: "Bishops and knights, with no queens, rooks or pawns."
},
pawn_endgame: %{
name: "pawn endgame",
description: "Kings and pawns only."
}
]
@type family ::
:basic_mate
| :king_and_pawn
| :bare_king_other
| :queen_and_pawn
| :queen_endgame
| :rook_and_pawn
| :rook_endgame
| :minor_piece_and_pawn
| :minor_piece_endgame
| :pawn_endgame
@doc "The material families, in a stable order."
def families, do: @families
@doc """
Returns the material family for a Key.
Returns `:kings_only` for `"K v K"` and `:unknown` when the Key is missing or
not shaped like `"<side> v <side>"`.
"""
@spec family(String.t() | nil) :: family() | :kings_only | :unknown
def family(key) when is_binary(key) do
case String.split(key, " v ") do
[a, b] ->
cond do
bare?(a) and bare?(b) -> :kings_only
bare?(a) -> bare_king_family(counts(b))
bare?(b) -> bare_king_family(counts(a))
true -> material_family(merge(counts(a), counts(b)))
end
_ ->
:unknown
end
end
def family(_key), do: :unknown
@doc """
Creates or corrects the material themes, keyed by family.
An existing theme with the same name is reused and its kind and description
are corrected, so a theme seeded as a technique becomes a material theme
without losing its existing links.
"""
@spec ensure_themes() :: %{family() => Chesstrainer.Themes.Theme.t()}
def ensure_themes do
Map.new(@families, fn {family, attrs} ->
{:ok, theme} = Themes.get_or_create(attrs.name, "endgame", kind: :material)
{family, ensure_material_theme(theme, attrs)}
end)
end
@doc """
Refreshes every endgame's derived material theme.
Returns the number of endgames tagged, the number skipped (kings only or no
Key) and the number of material themes. Re-running is idempotent.
"""
@spec derive() :: %{
tagged: non_neg_integer(),
skipped: non_neg_integer(),
themes: non_neg_integer()
}
def derive do
themes = ensure_themes()
material_ids = Enum.map(themes, fn {_family, theme} -> theme.id end)
{links, skipped} =
Endgame
|> select([e], {e.id, e.key})
|> Repo.all()
|> Enum.reduce({[], 0}, fn {id, key}, {links, skipped} ->
case family(key) do
family when family in [:kings_only, :unknown] ->
{links, skipped + 1}
family ->
{[{id, Map.fetch!(themes, family).id} | links], skipped}
end
end)
:ok = Themes.replace_theme_links(material_ids, links)
%{tagged: length(links), skipped: skipped, themes: map_size(themes)}
end
defp ensure_material_theme(theme, attrs) do
if theme.kind == :material and (theme.description || "") == attrs.description do
theme
else
{:ok, updated} =
Themes.update_theme(theme, %{kind: :material, description: attrs.description})
updated
end
end
defp bare?(side), do: side == "K"
defp bare_king_family(counts) do
cond do
count(counts, "P") == 0 and (count(counts, "Q") > 0 or count(counts, "R") > 0) ->
:basic_mate
count(counts, "P") > 0 and count(counts, "Q") == 0 and count(counts, "R") == 0 ->
:king_and_pawn
true ->
:bare_king_other
end
end
defp material_family(counts) do
cond do
count(counts, "Q") > 0 and count(counts, "P") > 0 ->
:queen_and_pawn
count(counts, "Q") > 0 ->
:queen_endgame
count(counts, "R") > 0 and count(counts, "P") > 0 ->
:rook_and_pawn
count(counts, "R") > 0 ->
:rook_endgame
count(counts, "B") + count(counts, "N") > 0 and count(counts, "P") > 0 ->
:minor_piece_and_pawn
count(counts, "B") + count(counts, "N") > 0 ->
:minor_piece_endgame
count(counts, "P") > 0 ->
:pawn_endgame
true ->
:kings_only
end
end
defp counts(side), do: Enum.frequencies(String.graphemes(side))
defp merge(left, right), do: Map.merge(left, right, fn _piece, a, b -> a + b end)
defp count(counts, piece), do: Map.get(counts, piece, 0)
end
+198
View File
@@ -0,0 +1,198 @@
defmodule Chesstrainer.Endgames.MotifThemes do
@moduledoc """
Derives objective motif themes by probing each endgame's position.
Motifs describe the kind of problem, independent of the material family: an
endgame can be a rook endgame and an only-move puzzle at the same time. Every
motif is proved from the local Syzygy tables — one probe returns the root WDL,
the DTZ and every legal move with its own WDL — so nothing here is a guess and
nothing calls the remote backend.
Motif links are recorded as `derived` and refreshed as a whole. Material
families, curated links and community links are untouched because the refresh
is scoped to the motif themes.
Loss endgames are skipped: only-move is undefined when every move loses, and
the library no longer contains them.
"""
import Ecto.Query, warn: false
alias Chesstrainer.Endgames.Endgame
alias Chesstrainer.Endgames.Tablebase
alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend
alias Chesstrainer.Repo
alias Chesstrainer.Themes
@motifs [
only_move: %{
name: "only move",
description:
"Exactly one legal move keeps the result, so the puzzle is about finding the single accurate move."
},
underpromotion: %{
name: "underpromotion",
description:
"The result can only be preserved by promoting to a rook, bishop or knight; promoting to a queen does not work."
},
fifty_move_draw: %{
name: "50-move draw",
description:
"The result turns on the fifty-move rule: the win needs more moves than the halfmove clock allows, so the defender can claim a draw."
}
]
@type motif :: :only_move | :underpromotion | :fifty_move_draw
@doc "The motif themes, in a stable order."
def motifs, do: @motifs
@doc """
Returns the motifs for one probed position.
`moves` are Fathom move tuples `{wdl, from, to, promotes, ep, dtz}` and carry
the mover's perspective, so they are compared with the root WDL directly.
`halfmove_clock` comes from the FEN; the probe itself runs with `rule50 = 0`.
"""
@spec motifs_for(atom(), integer() | nil, [tuple()], non_neg_integer()) :: [motif()]
def motifs_for(wdl, dtz, moves, halfmove_clock) do
outcome = Tablebase.normalize_wdl(wdl)
preserving =
Enum.filter(moves, fn {move_wdl, _from, _to, _promotes, _ep, _dtz} ->
Tablebase.normalize_wdl(move_wdl) == outcome
end)
[]
|> maybe_only_move(outcome, moves, preserving)
|> maybe_underpromotion(preserving)
|> maybe_fifty_move(wdl, dtz, halfmove_clock)
end
@doc """
Creates or corrects the motif themes, keyed by motif.
An existing theme with the same name is reused and its kind and description
are corrected, so a theme seeded as a technique becomes a motif without
losing its existing links.
"""
@spec ensure_themes() :: %{motif() => Chesstrainer.Themes.Theme.t()}
def ensure_themes do
Map.new(@motifs, fn {motif, attrs} ->
{:ok, theme} = Themes.get_or_create(attrs.name, "endgame", kind: :motif)
{motif, ensure_motif_theme(theme, attrs)}
end)
end
@doc """
Refreshes every endgame's derived motif links.
Returns the number of links written, the number of endgames skipped because
the local tables could not answer them, and a count per motif. Re-running is
idempotent.
"""
@spec derive() :: %{
links: non_neg_integer(),
skipped: non_neg_integer(),
by_motif: %{motif() => non_neg_integer()},
themes: non_neg_integer()
}
def derive do
themes = ensure_themes()
motif_ids = Enum.map(themes, fn {_motif, theme} -> theme.id end)
initial_counts = Map.new(@motifs, fn {motif, _attrs} -> {motif, 0} end)
{links, skipped, by_motif} =
Endgame
|> where([e], e.result in [:win, :draw])
|> select([e], {e.id, e.fen})
|> Repo.all()
|> Enum.reduce({[], 0, initial_counts}, fn {id, fen}, {links, skipped, counts} ->
case probe(fen) do
{:ok, %{wdl: wdl, dtz: dtz, moves: moves}} ->
motifs = motifs_for(wdl, dtz, moves, halfmove_clock(fen))
links =
Enum.reduce(motifs, links, fn motif, acc ->
[{id, Map.fetch!(themes, motif).id} | acc]
end)
counts =
Enum.reduce(motifs, counts, fn motif, acc ->
Map.update!(acc, motif, &(&1 + 1))
end)
{links, skipped, counts}
{:error, _reason} ->
{links, skipped + 1, counts}
end
end)
:ok = Themes.replace_theme_links(motif_ids, links)
%{links: length(links), skipped: skipped, by_motif: by_motif, themes: map_size(themes)}
end
defp ensure_motif_theme(theme, attrs) do
if theme.kind == :motif and (theme.description || "") == attrs.description do
theme
else
{:ok, updated} =
Themes.update_theme(theme, %{kind: :motif, description: attrs.description})
updated
end
end
defp probe(fen), do: probe_module().probe_local_detail(fen)
defp probe_module do
Application.get_env(:chesstrainer, :motif_probe, FathomBackend)
end
defp maybe_only_move(acc, outcome, moves, preserving) do
if outcome in [:win, :draw] and length(moves) > 1 and length(preserving) == 1 do
[:only_move | acc]
else
acc
end
end
defp maybe_underpromotion(acc, preserving) do
underpromotes? =
Enum.any?(preserving, fn {_wdl, _from, _to, promotes, _ep, _dtz} ->
promotes in [2, 3, 4]
end)
queen_promotes? =
Enum.any?(preserving, fn {_wdl, _from, _to, promotes, _ep, _dtz} ->
promotes == 1
end)
if underpromotes? and not queen_promotes?, do: [:underpromotion | acc], else: acc
end
defp maybe_fifty_move(acc, wdl, dtz, halfmove_clock) do
table_draw? = wdl in [:cursed_win, :blessed_loss]
clock_exhausted? =
wdl == :win and is_integer(dtz) and dtz > 100 - halfmove_clock
if table_draw? or clock_exhausted?, do: [:fifty_move_draw | acc], else: acc
end
defp halfmove_clock(fen) do
case String.split(fen, " ") do
[_board, _active, _castling, _ep, clock, _fullmove] ->
case Integer.parse(clock) do
{value, _rest} -> value
:error -> 0
end
_ ->
0
end
end
end
+14
View File
@@ -12,6 +12,7 @@ defmodule Chesstrainer.Endgames.Tablebase do
"""
alias Chesstrainer.Endgames.Tablebase
alias Chesstrainer.Endgames.Tablebase.Backend.Fathom, as: FathomBackend
alias Chesstrainer.FEN
@type result :: :win | :draw | :loss | :unknown
@@ -67,6 +68,19 @@ defmodule Chesstrainer.Endgames.Tablebase do
def flip(:draw), do: :draw
def flip(_outcome), do: :unknown
@doc """
Probes a FEN using only the local Syzygy tablebase and returns the result
from the side-to-move's perspective.
Unlike `new/1` this never falls back to the remote backend and never reads or
writes the cache. It is the primitive behind the admin bulk importer, so an
imported result always comes from our own tablebases.
"""
@spec probe_local_result(String.t()) ::
{:ok, result()}
| {:error, :not_configured | :illegal | :terminal | :unsupported}
def probe_local_result(fen), do: FathomBackend.probe_result_local(fen)
@spec new(String.t()) ::
{:ok, t()}
| {:cooldown, non_neg_integer()}
@@ -18,6 +18,7 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do
alias Chesstrainer.Endgames.Tablebase.Local
alias Chesstrainer.Endgames.Tablebase.Move
alias Chesstrainer.Endgames.Tablebase.San
alias Chesstrainer.FEN
@impl true
def probe(fen) do
@@ -32,6 +33,85 @@ defmodule Chesstrainer.Endgames.Tablebase.Backend.Fathom do
end
end
@doc """
Probes the local tablebase without the remote fallback and returns only the
position's result.
Used by the admin bulk importer, which must never import a result from
Lichess. The result is from the side-to-move's perspective, matching the
`category` on `Chesstrainer.Endgames.Tablebase`.
Returns `{:error, :terminal}` for checkmate, stalemate, and positions with no
legal moves, because they cannot be played as puzzles.
"""
@spec probe_result_local(String.t()) ::
{:ok, Tablebase.result()}
| {:error, :not_configured | :illegal | :terminal | :unsupported}
def probe_result_local(fen) do
with {:ok, largest} <- Local.check(),
pieces when is_integer(pieces) <- FEN.piece_count(fen),
true <- pieces <= largest || {:error, :unsupported},
{:ok, {root, moves}} <- Nif.probe(fen) do
case root do
:failed ->
{:error, :illegal}
:checkmate ->
{:error, :terminal}
:stalemate ->
{:error, :terminal}
{wdl, _from, _to, _promotes, _ep, _dtz} ->
if moves == [] do
{:error, :terminal}
else
case Tablebase.normalize_wdl(wdl) do
:unknown -> {:error, :unsupported}
category -> {:ok, category}
end
end
end
else
{:error, :not_configured} = error -> error
{:error, :unsupported} = error -> error
{:error, _reason} -> {:error, :unsupported}
nil -> {:error, :unsupported}
end
end
@doc """
Probes the local tablebase and returns the raw root outcome and move list.
Unlike `probe_result_local/1`, this keeps the per-move tuples and the raw WDL
atom, including `:cursed_win` and `:blessed_loss`, which the motif derivation
needs. It never falls back to the remote backend or consults the cache.
Returns `{:error, :unsupported}` when the local files cannot answer the
position, including a partial tablebase set where Fathom reports `:failed`.
"""
@spec probe_local_detail(String.t()) ::
{:ok, %{wdl: atom(), dtz: integer(), moves: [tuple()]}}
| {:error, :not_configured | :terminal | :unsupported}
def probe_local_detail(fen) do
with {:ok, largest} <- Local.check(),
pieces when is_integer(pieces) <- FEN.piece_count(fen),
true <- pieces <= largest || {:error, :unsupported},
{:ok, {root, moves}} <- Nif.probe(fen) do
case root do
:failed -> {:error, :unsupported}
:checkmate -> {:error, :terminal}
:stalemate -> {:error, :terminal}
{wdl, _from, _to, _promotes, _ep, dtz} -> {:ok, %{wdl: wdl, dtz: dtz, moves: moves}}
end
else
{:error, :not_configured} = error -> error
{:error, :unsupported} = error -> error
{:error, _reason} -> {:error, :unsupported}
nil -> {:error, :unsupported}
end
end
defp fallback(fen) do
(Application.get_env(:chesstrainer, :tablebase_fallback) || Lichess).probe(fen)
end
@@ -11,6 +11,8 @@ defmodule Chesstrainer.Endgames.Tablebase.Parser do
import Chesstrainer.Ratelimiters
alias Chesstrainer.Endgames.Tablebase
require Logger
@lichess_tablebase_url "https://tablebase.lichess.ovh/standard?fen="
@spec from_fen(String.t()) ::
@@ -74,6 +76,7 @@ defmodule Chesstrainer.Endgames.Tablebase.Parser do
# Server errors
{:ok, %Req.Response{status: status, body: body}} when status in 500..599 ->
Logger.warning("tablebase fetch failed with HTTP #{status}", status: status)
{:error, {:server_error, status, body}}
# Catch‑all for other status codes
@@ -82,6 +85,7 @@ defmodule Chesstrainer.Endgames.Tablebase.Parser do
# Network / client‑side failure
{:error, reason} ->
Logger.warning("tablebase fetch failed: #{inspect(reason)}", reason: reason)
{:error, reason}
end
end
+27
View File
@@ -40,6 +40,18 @@ defmodule Chesstrainer.GuestLimits do
@doc "Clears every budget. Intended for tests."
def reset, do: GenServer.call(__MODULE__, :reset)
@doc """
Returns the puzzles left today without consuming one.
Mirrors `take/2`'s result shape so a caller can show the wall before doing
work that would otherwise spend a puzzle.
"""
@spec remaining(address, Date.t()) ::
{:ok, non_neg_integer | nil} | {:limit_reached, non_neg_integer}
def remaining(address, today \\ Date.utc_today()) do
GenServer.call(__MODULE__, {:remaining, address, today})
end
@doc "The daily puzzle allowance for a guest."
def limit, do: config() |> Keyword.get(:limit, @default_limit)
@@ -67,6 +79,21 @@ defmodule Chesstrainer.GuestLimits do
@impl true
def handle_call({:take, nil, _today}, _from, state), do: {:reply, {:ok, nil}, state}
def handle_call({:remaining, nil, _today}, _from, state), do: {:reply, {:ok, nil}, state}
def handle_call({:remaining, address, today}, _from, state) do
day = Date.to_gregorian_days(today)
key = key(state.secret, day, address)
case count(key, day) do
used when used >= state.limit ->
{:reply, {:limit_reached, ms_until_utc_midnight()}, state}
used ->
{:reply, {:ok, state.limit - used}, state}
end
end
def handle_call({:take, address, today}, _from, state) do
day = Date.to_gregorian_days(today)
key = key(state.secret, day, address)
+307
View File
@@ -0,0 +1,307 @@
defmodule Chesstrainer.JSONLogFormatter do
@moduledoc """
An OTP logger formatter that emits one JSON object per log line.
Production uses this formatter (see `config/prod.exs`), while development and
test keep `Logger.Formatter`'s readable output. Every line carries a
timestamp, level and message, plus a request id when one is in the logger
metadata. Access lines add `method`, `path`, `status` and `duration_ms`;
exceptions and OTP crash reports add an `error` object with `kind`, `reason`
and `stacktrace`.
The formatter is defensive. Metadata is sanitised into JSON-safe values, and
an event that cannot be encoded still produces a single JSON line instead of
taking the logger down. Email addresses and credentials found in metadata,
params or the rendered message are replaced with `[REDACTED]`.
"""
@max_message_bytes 8_096
@max_stacktrace_entries 50
@redacted "[REDACTED]"
@email_regex ~r/[A-Za-z0-9.!#$%&'*+\/=?^_`{|}~-]+@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+/
@secret_assignment_regex ~r/\b(token|password|secret|api[_-]?key|authorization)=([^&\s"']+)/i
@sensitive_key_fragments ~w(password secret token authorization cookie api_key private_key credential)
@sensitive_email_keys ~w(email email_address user_email contact_email recipient)
# These are unpacked into the line itself rather than copied as metadata.
@internal_keys [
:time,
:gl,
:report_cb,
:error_logger,
:exception,
:stacktrace,
:crash_reason,
:reason,
:kind,
:conn,
:socket
]
# Fixed fields always win over a metadata key with the same name.
@reserved_keys [
:timestamp,
:level,
:message,
:error,
:request_id,
:method,
:path,
:status,
:duration_ms
]
@doc """
Formats a `:logger` event as a newline-terminated JSON object.
"""
@spec format(:logger.log_event(), :logger.formatter_config()) :: iodata()
def format(event, _config) do
event
|> build()
|> Jason.encode!()
|> then(&[&1, ?\n])
rescue
exception -> fallback(exception)
catch
kind, reason -> fallback({kind, reason})
end
defp build(event) do
meta = event.meta || %{}
%{
"timestamp" => timestamp(meta),
"level" => to_string(event.level),
"message" => message(event)
}
|> put_access(meta)
|> put_metadata(meta)
|> put_error(meta)
end
defp timestamp(%{time: time}) when is_integer(time) do
time
|> DateTime.from_unix!(:microsecond)
|> DateTime.to_iso8601()
end
defp timestamp(_meta), do: DateTime.utc_now() |> DateTime.to_iso8601()
defp message(event) do
event
|> Logger.Formatter.format_event(@max_message_bytes)
|> Logger.Formatter.prune()
|> IO.iodata_to_binary()
|> redact_text()
rescue
_exception ->
event.msg
|> inspect(limit: 20, printable_limit: @max_message_bytes)
|> redact_text()
catch
_kind, reason ->
{event.msg, reason}
|> inspect(limit: 20, printable_limit: @max_message_bytes)
|> redact_text()
end
defp put_access(entry, meta) do
entry
|> put_if_present("request_id", meta[:request_id])
|> put_if_present("method", meta[:method])
|> put_if_present("path", meta[:path])
|> put_if_present("status", meta[:status])
|> put_if_present("duration_ms", meta[:duration_ms])
end
defp put_if_present(entry, _key, nil), do: entry
defp put_if_present(entry, key, value) do
Map.put(entry, key, sanitize(value, key))
end
defp put_metadata(entry, meta) do
Enum.reduce(meta, entry, fn
{key, _value}, acc when key in @internal_keys ->
acc
{key, _value}, acc when key in @reserved_keys ->
acc
{key, value}, acc ->
Map.put(acc, key |> key_string() |> redact_text(), metadata_value(key, value))
end)
end
defp metadata_value(:mfa, {module, function, arity})
when is_atom(module) and is_atom(function) and is_integer(arity) do
Exception.format_mfa(module, function, arity)
end
defp metadata_value(key, value), do: sanitize(value, key)
# Only the first exception/reason source is rendered. OTP crash reports carry
# `crash_reason`, while Logger.error(..., exception: ..., stacktrace: ...)
# carries the two keys directly.
defp put_error(entry, meta) do
case error(meta) do
nil -> entry
error when map_size(error) == 0 -> entry
error -> Map.put(entry, "error", error)
end
end
defp error(%{exception: %{__exception__: true} = exception} = meta) do
%{
"kind" => inspect(exception.__struct__),
"reason" => Exception.message(exception),
"stacktrace" => stacktrace(meta[:stacktrace])
}
|> drop_nil()
end
defp error(%{crash_reason: crash_reason} = meta) do
{reason, trace} = split_crash_reason(crash_reason, meta[:stacktrace])
%{
"kind" => error_kind(reason),
"reason" => error_reason(reason),
"stacktrace" => stacktrace(trace)
}
|> drop_nil()
end
defp error(meta) do
if meta[:reason] || meta[:stacktrace] do
%{
"kind" => meta[:kind] && to_string(meta[:kind]),
"reason" => error_reason(meta[:reason]),
"stacktrace" => stacktrace(meta[:stacktrace])
}
|> drop_nil()
end
end
defp split_crash_reason({reason, trace}, _fallback) when is_list(trace), do: {reason, trace}
defp split_crash_reason(reason, fallback), do: {reason, fallback}
defp error_kind(%{__exception__: true} = exception), do: inspect(exception.__struct__)
defp error_kind(reason) when is_atom(reason), do: Atom.to_string(reason)
defp error_kind(reason) when is_tuple(reason), do: reason |> elem(0) |> error_kind()
defp error_kind(_reason), do: nil
defp error_reason(nil), do: nil
defp error_reason(%{__exception__: true} = exception), do: Exception.message(exception)
defp error_reason(reason) when is_binary(reason), do: redact_text(reason)
defp error_reason(reason) do
reason
|> inspect(limit: 30, printable_limit: 2_000)
|> redact_text()
end
defp stacktrace(stacktrace) when is_list(stacktrace) and stacktrace != [] do
stacktrace
|> Enum.take(@max_stacktrace_entries)
|> Enum.map(&format_stacktrace_entry/1)
|> Enum.map(&redact_text/1)
end
defp stacktrace(_stacktrace), do: nil
defp format_stacktrace_entry(entry) do
Exception.format_stacktrace_entry(entry)
rescue
_exception -> inspect(entry, limit: 10, printable_limit: 1_000)
end
defp drop_nil(map), do: Map.reject(map, fn {_key, value} -> is_nil(value) end)
defp key_string(key) when is_atom(key), do: Atom.to_string(key)
defp key_string(key) when is_binary(key), do: key
defp key_string(key), do: inspect(key)
defp sanitize(nil, _key), do: nil
defp sanitize(value, _key) when is_boolean(value), do: value
defp sanitize(value, _key) when is_integer(value) or is_float(value), do: value
defp sanitize(value, key) when is_binary(value) do
cond do
sensitive_key?(key) -> @redacted
String.valid?(value) -> redact_text(value)
true -> inspect(value)
end
end
defp sanitize(value, _key) when is_atom(value), do: Atom.to_string(value)
defp sanitize(value, _key) when is_struct(value) do
value
|> inspect(limit: 20, printable_limit: 2_000)
|> redact_text()
end
defp sanitize(value, key) when is_list(value) do
cond do
sensitive_key?(key) -> @redacted
value != [] and List.ascii_printable?(value) -> value |> List.to_string() |> redact_text()
true -> Enum.map(value, &sanitize(&1, nil))
end
end
defp sanitize(value, _key) when is_tuple(value) do
value
|> Tuple.to_list()
|> Enum.map(&sanitize(&1, nil))
end
defp sanitize(value, _key) when is_map(value) do
Enum.into(value, %{}, fn {key, nested} ->
{key |> key_string() |> redact_text(), sanitize(nested, key)}
end)
end
defp sanitize(value, _key) do
value
|> inspect(limit: 20, printable_limit: 2_000)
|> redact_text()
end
defp sensitive_key?(nil), do: false
defp sensitive_key?(key) do
key = key |> key_string() |> String.downcase()
key in @sensitive_email_keys or String.ends_with?(key, "_email") or
Enum.any?(@sensitive_key_fragments, &String.contains?(key, &1))
end
defp redact_text(text) when is_binary(text) do
text = if String.valid?(text), do: text, else: inspect(text)
text
|> then(&Regex.replace(@email_regex, &1, @redacted))
|> then(&Regex.replace(@secret_assignment_regex, &1, "\\1=#{@redacted}"))
end
defp fallback(reason) do
entry = %{
"timestamp" => DateTime.utc_now() |> DateTime.to_iso8601(),
"level" => "error",
"message" => "could not format log event",
"error" => %{
"reason" => reason |> inspect(limit: 10, printable_limit: 1_000) |> redact_text()
}
}
json =
case Jason.encode(entry) do
{:ok, json} -> json
{:error, _reason} -> ~s({"level":"error","message":"could not format log event"})
end
[json, ?\n]
end
end
+82
View File
@@ -0,0 +1,82 @@
defmodule Chesstrainer.Mail do
@moduledoc """
House rules for every outgoing email.
Notifiers build the message body and hand it here, so the sender identity,
reply-to address, SES configuration set and the test redirect are applied in
exactly one place and no sender can forget them.
The From address lives on the `mail.` subdomain so transactional mail is
distinct from the addresses that receive mail on the apex domain. SES
verification of the parent domain covers the subdomain, so no separate
identity is required for the From header to be accepted.
"""
alias Chesstrainer.Branding
alias Chesstrainer.Mailer
@default_configuration_set "my-first-configuration-set"
@doc """
Applies the house rules and delivers the email.
Returns `{:ok, email}` so notifiers can report the message they sent.
"""
def deliver(%Swoosh.Email{} = email) do
email = prepare(email)
with {:ok, _metadata} <- Mailer.deliver(email) do
{:ok, email}
end
end
@doc """
Applies the house rules without delivering.
Exposed so tooling (such as `mix mail.check`) can inspect or send the exact
message the application would send.
"""
def prepare(%Swoosh.Email{} = email) do
email
|> Swoosh.Email.from({Branding.name(), Branding.mail_from()})
|> Swoosh.Email.reply_to(Branding.support_email())
|> Swoosh.Email.put_provider_option(:configuration_set_name, configuration_set())
|> redirect()
end
defp configuration_set do
Application.get_env(:chesstrainer, :ses_configuration_set, @default_configuration_set)
end
# Rewrites every recipient to one address so a staging or production smoke
# test can send through real SES without reaching users. The original
# recipients stay in the subject and in an `X-Original-To` header so the
# redirected message explains itself.
defp redirect(email) do
case Application.get_env(:chesstrainer, :mail_redirect_to) do
address when is_binary(address) and address != "" ->
originals = recipients(email)
require Logger
Logger.warning("mail redirect: #{Enum.join(originals, ", ")} -> #{address}")
%{email | to: [{"", address}], cc: [], bcc: []}
|> Swoosh.Email.header("X-Original-To", Enum.join(originals, ", "))
|> Swoosh.Email.subject("[→ #{Enum.join(originals, ", ")}] #{email.subject}")
_unset ->
email
end
end
defp recipients(email) do
[email.to, email.cc, email.bcc]
|> List.flatten()
|> Enum.reject(&is_nil/1)
|> Enum.map(fn
{_name, address} -> address
address when is_binary(address) -> address
end)
end
end
+6 -12
View File
@@ -6,7 +6,7 @@ defmodule Chesstrainer.MailingList.Notifier do
import Swoosh.Email
alias Chesstrainer.Branding
alias Chesstrainer.Mailer
alias Chesstrainer.Mail
@doc """
Delivers the confirmation email for a mailing-list subscription.
@@ -30,16 +30,10 @@ defmodule Chesstrainer.MailingList.Notifier do
end
defp deliver(recipient, subject, body) do
email =
new()
|> to(recipient)
|> from({Branding.name(), Branding.mail_from()})
|> reply_to(Branding.support_email())
|> subject(subject)
|> text_body(body)
with {:ok, _metadata} <- Mailer.deliver(email) do
{:ok, email}
end
new()
|> to(recipient)
|> subject(subject)
|> text_body(body)
|> Mail.deliver()
end
end
+85 -58
View File
@@ -2,14 +2,21 @@ defmodule Chesstrainer.Puzzles do
@moduledoc """
Selects endgames to serve as puzzles.
A puzzle is played at one of three difficulties — `:easy`, `:medium` or
`:hard` — defined relative to the current user's rating: `:medium` is within
a configurable band of the user's rating, `:easy` below it and `:hard` above
it. The same endgame is therefore easy for one player and hard for another.
Difficulty is a bias, not a filter. Every endgame is weighted by how close its
rating is to a target derived from the user's rating — the user's own rating
for `:medium`, below it for `:easy` and above it for `:hard` — and one
candidate is drawn from that weighted distribution. Nearby endgames are much
more likely, but the whole library stays reachable, so a thin region around
the user's rating can never leave the pool empty.
Selection prefers endgames the user has not attempted in the last 30 days.
When that pool is empty it falls back to any endgame in the band; the rating
window keeps a recent replay unrated until it expires.
Endgames the user has attempted inside the repeat window are skipped, as is
anything passed in `:exclude_ids` (the puzzles already served in a session).
Only when every candidate is excluded does selection fall back to the least
recently attempted endgame, so the repeat is the most overdue one rather than
an arbitrary one.
The same endgame is therefore easy for one player and hard for another: a
rating is what makes the two comparable.
"""
import Ecto.Query, warn: false
@@ -17,95 +24,115 @@ defmodule Chesstrainer.Puzzles do
alias Chesstrainer.Repo
alias Chesstrainer.Accounts.User
alias Chesstrainer.Attempts
alias Chesstrainer.Attempts.Attempt
alias Chesstrainer.Endgames.Endgame
@default_band_width 100
@default_spread 150
@default_repeat_window_days 30
@default_targets [easy: -200, medium: 0, hard: 200]
@difficulties [:easy, :medium, :hard]
@doc "The difficulties a session can be played at."
def difficulties, do: @difficulties
@doc """
The half-width of the medium band, in rating points.
How far, in rating points, a puzzle's likelihood falls off from the target.
Configured under `:chesstrainer, :puzzles, :band_width`.
A larger spread draws more widely around the target. Configured under
`:chesstrainer, :puzzles, :spread`.
"""
def band_width do
:chesstrainer
|> Application.get_env(:puzzles, [])
|> Keyword.get(:band_width, @default_band_width)
end
def spread, do: setting(:spread, @default_spread)
@doc """
The `{min, max}` rating range for `difficulty` relative to `rating`.
The minimum gap, in days, before the same endgame may be served again.
A `nil` bound is open-ended.
Configured under `:chesstrainer, :puzzles, :repeat_window_days`.
"""
def difficulty_range(rating, difficulty) when difficulty in @difficulties do
width = band_width()
def repeat_window_days, do: setting(:repeat_window_days, @default_repeat_window_days)
case difficulty do
:easy -> {nil, rating - width}
:medium -> {rating - width, rating + width}
:hard -> {rating + width, nil}
end
@doc """
The rating `difficulty` aims at, given the player's `rating`.
The offsets are configured under `:chesstrainer, :puzzles, :targets`.
"""
def difficulty_target(rating, difficulty) when difficulty in @difficulties do
rating + Keyword.fetch!(setting(:targets, @default_targets), difficulty)
end
@doc """
Picks the next puzzle for `user` at `difficulty`, using `user.rating` as the
baseline.
`:exclude_ids` (default `[]`) skips endgames by id — used to avoid repeating
the puzzle just played. Returns `nil` when no endgame exists at all.
`:exclude_ids` (default `[]`) skips endgames by id — used for the puzzles
already served in this session. Returns `nil` when no endgame exists at all.
"""
def next_endgame(%User{} = user, difficulty, opts \\ [])
when difficulty in @difficulties do
exclude_ids = Keyword.get(opts, :exclude_ids, [])
band = difficulty_range(user.rating, difficulty)
recent_ids = Attempts.recent_endgame_ids(user.id)
recent_ids = Attempts.recent_endgame_ids(user.id, repeat_window_days())
target = difficulty_target(user.rating, difficulty)
fresh =
Endgame
|> in_band(band)
|> skip_ids(exclude_ids)
|> skip_ids(recent_ids)
|> random_one()
fresh || fallback(user.rating, band, exclude_ids)
end
defp fallback(rating, band, exclude_ids) do
Endgame
|> in_band(band)
|> skip_ids(exclude_ids)
|> random_one()
|> on_side_of(user.rating, difficulty)
|> skip_ids(exclude_ids ++ recent_ids)
|> weighted_one(target)
|> case do
nil -> nearest(rating, exclude_ids)
nil -> least_recently_attempted(user.id, exclude_ids)
endgame -> endgame
end
end
defp nearest(rating, exclude_ids) do
# Keep the labels honest: "easy" never serves above the user's rating plus the
# spread, and "hard" never below it minus the spread. "medium" is open, which
# is what lets it reach the rest of the library.
defp on_side_of(query, _rating, :medium), do: query
defp on_side_of(query, rating, :easy),
do: where(query, [e], e.rating <= ^(rating + spread()))
defp on_side_of(query, rating, :hard),
do: where(query, [e], e.rating >= ^(rating - spread()))
# Draw one row with probability proportional to
# `exp(-|rating - target| / spread)`: an exponential race, where the row with
# the smallest `-ln(U) / weight` wins.
defp weighted_one(query, target) do
spread = spread() * 1.0
target = target * 1.0
query
|> order_by(
[e],
fragment("-ln(1 - random()) * exp(abs(? - ?) / ?)", e.rating, ^target, ^spread)
)
|> limit(1)
|> Repo.one()
end
# Every candidate is excluded, so the repeat window is overruled: serve
# whatever the user has waited longest to see again.
defp least_recently_attempted(user_id, exclude_ids) do
attempted =
Attempt
|> where([a], a.user_id == ^user_id)
|> group_by([a], a.endgame_id)
|> select([a], %{endgame_id: a.endgame_id, last_at: max(a.inserted_at)})
Endgame
|> skip_ids(exclude_ids)
|> order_by([e], asc: fragment("ABS(? - ?)", e.rating, ^rating))
|> join(:left, [e], a in subquery(attempted), on: a.endgame_id == e.id)
|> order_by([_e, a], asc_nulls_first: a.last_at)
|> order_by([e], fragment("random()"))
|> limit(1)
|> Repo.one()
end
defp random_one(query) do
query
|> order_by([e], fragment("RANDOM()"))
|> limit(1)
|> Repo.one()
end
defp in_band(query, {nil, max}), do: where(query, [e], e.rating <= ^max)
defp in_band(query, {min, nil}), do: where(query, [e], e.rating >= ^min)
defp in_band(query, {min, max}),
do: where(query, [e], e.rating >= ^min and e.rating <= ^max)
defp skip_ids(query, []), do: query
defp skip_ids(query, ids), do: where(query, [e], e.id not in ^ids)
defp setting(key, default) do
:chesstrainer
|> Application.get_env(:puzzles, [])
|> Keyword.get(key, default)
end
end
+22
View File
@@ -18,6 +18,28 @@ defmodule Chesstrainer.Release do
{:ok, _, _} = Ecto.Migrator.with_repo(repo, &Ecto.Migrator.run(&1, :down, to: version))
end
@doc """
Derives material family themes for the whole library.
Runs in the release without starting the web application: `with_repo/2`
starts just the repository, which is all the derivation needs.
"""
def derive_material, do: with_repo(&Chesstrainer.Endgames.MaterialThemes.derive/0)
@doc """
Derives motif themes from the local tablebase for the whole library.
"""
def derive_motifs, do: with_repo(&Chesstrainer.Endgames.MotifThemes.derive/0)
defp with_repo(fun) do
load_app()
for repo <- repos() do
{:ok, result, _} = Ecto.Migrator.with_repo(repo, fn _repo -> fun.() end)
result
end
end
defp repos do
Application.fetch_env!(@app, :ecto_repos)
end
+230 -3
View File
@@ -4,6 +4,8 @@ defmodule Chesstrainer.Themes do
"""
import Ecto.Query, warn: false
alias Chesstrainer.Accounts.Policy
alias Chesstrainer.Accounts.Scope
alias Chesstrainer.Repo
alias Chesstrainer.Themes.Theme
@@ -21,6 +23,43 @@ defmodule Chesstrainer.Themes do
Repo.all(Theme)
end
@doc """
Lists themes for the admin index with their endgame usage count.
Options:
* `:search` - case-insensitive match on the theme name
* `:category` - one of `:endgame`, `:opening`, `:tactic`, or blank for all
Returns `{theme, usage_count}` tuples sorted by name.
"""
def list_themes_for_admin(opts \\ []) do
search = opts |> Keyword.get(:search, "") |> to_string() |> String.trim()
category = normalize_category(Keyword.get(opts, :category, ""))
query = from(t in Theme, order_by: [asc: t.name])
query =
if search == "" do
query
else
where(query, [t], ilike(t.name, ^"%#{search}%"))
end
query =
if category do
where(query, [t], t.category == ^category)
else
query
end
query
|> join(:left, [t], j in "endgames_themes", on: j.theme_id == t.id)
|> group_by([t], t.id)
|> select([t, j], {t, count(j.endgame_id)})
|> Repo.all()
end
@doc """
Gets a single theme.
@@ -37,9 +76,26 @@ defmodule Chesstrainer.Themes do
"""
def get_theme!(id), do: Repo.get!(Theme, id)
@doc """
Gets a single endgame theme by its slug.
Returns `nil` when no endgame theme has that slug.
"""
def get_theme_by_slug(slug) when is_binary(slug) do
Repo.one(
from t in Theme,
where: t.slug == ^slug and t.category == :endgame,
limit: 1
)
end
@doc """
Creates a theme.
This is the unscoped path used by internal callers such as seeds, fixtures and
the admin picker, which are already behind an authorization check. Prefer
`create_theme/2` wherever a scope is available.
## Examples
iex> create_theme(%{field: value})
@@ -55,6 +111,21 @@ defmodule Chesstrainer.Themes do
|> Repo.insert()
end
@doc """
Creates a theme on behalf of an administrator.
Members cannot introduce new theme names; their contribution path is a
suggestion, which a moderator reviews. Returns `{:error, :unauthorized}`
for a scope that cannot manage themes.
"""
def create_theme(%Scope{} = scope, attrs) do
if Policy.can?(scope, :manage_themes) do
create_theme(attrs)
else
{:error, :unauthorized}
end
end
@doc """
Updates a theme.
@@ -123,20 +194,167 @@ defmodule Chesstrainer.Themes do
@doc """
Finds a theme by name (trimmed and case-insensitive) for a category, creating it
if it does not exist.
Options:
* `:kind` - the kind for a newly created theme; defaults to `:technique`
This is the picker's helper and is expected to run behind an admin check.
"""
def get_or_create(name, category) when is_binary(name) do
def get_or_create(name, category, opts \\ []) when is_binary(name) do
name = String.trim(name)
if name == "" do
{:error, :blank_name}
else
case find_by_name(name, category) do
nil -> create_theme(%{name: name, category: category})
theme -> {:ok, theme}
nil ->
create_theme(%{
name: name,
category: category,
kind: Keyword.get(opts, :kind, :technique)
})
theme ->
{:ok, theme}
end
end
end
@doc """
Replaces every link to `scoped_theme_ids` with the derived links in `links`.
This is for themes that are objectively derived: the pass owns its themes
entirely, so a link's previous source is irrelevant and every link is
rewritten as `derived`. Links to themes outside `scoped_theme_ids` — curated
or community — are untouched.
The operation is a full refresh for the given themes, so it can move an
endgame between families when a rule changes. `links` is a list of
`{endgame_id, theme_id}` pairs.
"""
@spec replace_theme_links([term()], [{Ecto.UUID.t(), term()}]) :: :ok
def replace_theme_links(scoped_theme_ids, links) when is_list(links) do
now = DateTime.utc_now() |> DateTime.truncate(:second)
Repo.transaction(fn ->
if scoped_theme_ids != [] do
Repo.delete_all(
from l in "endgames_themes",
where: l.theme_id in ^scoped_theme_ids
)
end
links
|> Enum.map(fn {endgame_id, theme_id} ->
%{
endgame_id: Ecto.UUID.dump!(endgame_id),
theme_id: theme_id,
source: "derived",
inserted_at: now
}
end)
|> Enum.chunk_every(5_000)
|> Enum.each(fn rows ->
Repo.insert_all("endgames_themes", rows, on_conflict: :nothing)
end)
end)
:ok
end
@link_sources [:curated, :community]
@doc """
Links `theme` to many endgames at once with the given source.
Defaults to `:curated`, which is what the admin tagging workspace writes.
Existing links are left alone, so re-applying is safe. Returns the number of
endgames the link was attempted for.
"""
@spec tag_endgames(Theme.t(), [Ecto.UUID.t()], :curated | :community) ::
{:ok, non_neg_integer()}
def tag_endgames(%Theme{id: theme_id}, endgame_ids, source \\ :curated)
when is_list(endgame_ids) and source in @link_sources do
now = DateTime.utc_now() |> DateTime.truncate(:second)
endgame_ids
|> Enum.uniq()
|> Enum.map(fn endgame_id ->
%{
endgame_id: Ecto.UUID.dump!(endgame_id),
theme_id: theme_id,
source: to_string(source),
inserted_at: now
}
end)
|> Enum.chunk_every(5_000)
|> Enum.each(fn rows ->
Repo.insert_all("endgames_themes", rows, on_conflict: :nothing)
end)
{:ok, length(Enum.uniq(endgame_ids))}
end
@doc """
Removes a link from `theme` to one endgame, but only if it has the given
source.
The tagging workspace removes `:curated` links only, so a derived or
community link can never be deleted by hand. Returns the number removed.
"""
@spec untag_endgame(Theme.t(), Ecto.UUID.t(), :curated | :community) ::
{:ok, non_neg_integer()}
def untag_endgame(%Theme{id: theme_id}, endgame_id, source \\ :curated)
when source in @link_sources do
{count, _} =
Repo.delete_all(
from l in "endgames_themes",
where:
l.theme_id == ^theme_id and l.endgame_id == type(^endgame_id, :binary_id) and
l.source == ^to_string(source)
)
{:ok, count}
end
@doc """
Replaces the derived theme links for one endgame.
Only links whose source is `derived` are removed, so curated and
community-approved links survive every derivation pass. Links that are
already present are left alone, which makes the operation idempotent.
"""
@spec sync_derived_themes(Ecto.UUID.t(), [term()]) :: :ok
def sync_derived_themes(endgame_id, theme_ids) do
now = DateTime.utc_now() |> DateTime.truncate(:second)
Repo.transaction(fn ->
Repo.delete_all(
from l in "endgames_themes",
where: l.endgame_id == type(^endgame_id, :binary_id) and l.source == "derived"
)
rows =
theme_ids
|> Enum.uniq()
|> Enum.map(fn theme_id ->
%{
endgame_id: Ecto.UUID.dump!(endgame_id),
theme_id: theme_id,
source: "derived",
inserted_at: now
}
end)
if rows != [] do
Repo.insert_all("endgames_themes", rows, on_conflict: :nothing)
end
end)
:ok
end
defp find_by_name(name, category) do
downcased = String.downcase(name)
@@ -153,4 +371,13 @@ defmodule Chesstrainer.Themes do
def names(themes) when is_list(themes) do
themes |> Enum.map(& &1.name) |> Enum.sort()
end
defp normalize_category(category) when category in [:endgame, :opening, :tactic],
do: category
defp normalize_category(category) when is_binary(category) do
Enum.find([:endgame, :opening, :tactic], &(Atom.to_string(&1) == category))
end
defp normalize_category(_category), do: nil
end
+85 -6
View File
@@ -1,27 +1,106 @@
defmodule Chesstrainer.Themes.Theme do
@moduledoc """
A label describing an endgame's technique or goal.
A theme has a stable `slug` for URLs, a `kind` saying where the label comes
from — `material`, `motif` or `technique` — and an optional description. The
slug is generated from the name when the theme is first created and is then
left alone, so renaming a theme never breaks a link to it.
"""
use Ecto.Schema
import Ecto.Changeset
@type t :: %__MODULE__{}
@kinds [material: "material", motif: "motif", technique: "technique"]
schema "themes" do
field :name, :string
field :slug, :string
field :description, :string
field :kind, Ecto.Enum, values: @kinds, default: :technique
field :category, Ecto.Enum, values: [endgame: "endgame", opening: "opening", tactic: "tactic"]
timestamps(type: :utc_datetime)
end
@doc "The kinds a theme can have."
def kinds, do: Keyword.keys(@kinds)
@doc """
Turns a theme name into a URL-safe slug.
Lowercase letters, digits and single hyphens; accents are folded, runs of
other characters collapse to one hyphen, and a blank result becomes
`"theme"`.
"""
@spec slugify(String.t() | nil) :: String.t()
def slugify(name) do
slug =
name
|> to_string()
|> :unicode.characters_to_nfd_binary()
|> String.replace(~r/[\x{0300}-\x{036F}]/u, "")
|> String.downcase()
|> String.replace(~r/[^a-z0-9]+/u, "-")
|> String.trim("-")
if slug == "", do: "theme", else: slug
end
@doc false
def changeset(theme, attrs) do
theme
|> cast(attrs, [:name, :category])
|> update_change(:name, fn
name when is_binary(name) -> String.trim(name)
name -> name
end)
|> validate_required([:name, :category])
|> cast(attrs, [:name, :slug, :description, :kind, :category])
|> update_change(:name, &trim/1)
|> update_change(:description, &trim/1)
|> put_slug()
|> validate_required([:name, :slug, :kind, :category])
|> validate_length(:name, min: 1, max: 60)
|> validate_length(:slug, min: 1, max: 80)
|> validate_length(:description, max: 500)
|> validate_format(:slug, ~r/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/,
message: "must be lowercase letters, numbers and single hyphens"
)
|> unique_constraint(:name,
name: :themes_name_category_lower_index,
message: "already exists"
)
|> unique_constraint(:slug, message: "is already taken")
|> check_constraint(:kind, name: :themes_kind_in_allowed)
end
defp put_slug(changeset) do
case get_field(changeset, :slug) do
slug when is_binary(slug) ->
if String.trim(slug) == "" do
generate_slug(changeset)
else
put_change(changeset, :slug, slugify(slug))
end
nil ->
generate_slug(changeset)
end
end
# A new theme starts without a name, so generating a slug from it would only
# produce the fallback. Wait until there is a name to derive from.
defp generate_slug(changeset) do
case get_field(changeset, :name) do
name when is_binary(name) ->
if String.trim(name) == "" do
changeset
else
put_change(changeset, :slug, slugify(name))
end
_ ->
changeset
end
end
defp trim(value) when is_binary(value), do: String.trim(value)
defp trim(value), do: value
end
+6 -1
View File
@@ -17,7 +17,11 @@ defmodule ChesstrainerWeb do
those modules here.
"""
def static_paths, do: ~w(assets fonts images favicon.ico)
def static_paths do
~w(assets fonts images favicon.ico favicon.svg favicon-16x16.png favicon-32x32.png
apple-touch-icon.png android-chrome-192x192.png android-chrome-512x512.png
site.webmanifest)
end
@doc "Whether the app is gated behind the prelaunch page."
def prelaunch?, do: Application.get_env(:chesstrainer, :prelaunch, false)
@@ -103,6 +107,7 @@ defmodule ChesstrainerWeb do
alias Phoenix.LiveView.JS
alias Chesstrainer.Branding
alias ChesstrainerWeb.Layouts
alias ChesstrainerWeb.SEO
# Routes generation with the ~p sigil
unquote(verified_routes())
+84
View File
@@ -0,0 +1,84 @@
defmodule ChesstrainerWeb.ClientAddress do
@moduledoc """
Resolves the client's IP address from either a controller connection or a
LiveView socket.
`X-Forwarded-For` is only read when
`Chesstrainer.GuestLimits.trust_forwarded_for?/0` is enabled. In that case the
rightmost entry is used, because that is the value our own proxy appended.
Invalid or missing headers fall back to the peer address.
Production is Cloudflare -> Caddy -> Phoenix. `deploy/Caddyfile` makes Caddy
overwrite `X-Forwarded-For` with Cloudflare's `CF-Connecting-IP` and rejects
direct-to-origin requests, so the rightmost value is the real visitor rather
than a Cloudflare edge address.
"""
alias Chesstrainer.GuestLimits
@typedoc "An IPv4/IPv6 address, or `nil` when no peer data is available."
@type address :: :inet.ip_address() | nil
@doc "Returns the client address for a controller connection."
@spec from_conn(Plug.Conn.t()) :: address()
def from_conn(conn) do
if GuestLimits.trust_forwarded_for?() do
conn
|> Plug.Conn.get_req_header("x-forwarded-for")
|> parse_forwarded_header()
|> fallback(conn.remote_ip)
else
conn.remote_ip
end
end
@doc "Returns the client address for a connected LiveView socket."
@spec from_socket(Phoenix.LiveView.Socket.t()) :: address()
def from_socket(socket) do
if GuestLimits.trust_forwarded_for?() do
socket
|> Phoenix.LiveView.get_connect_info(:x_headers)
|> parse_x_headers()
|> fallback(peer_address(socket))
else
peer_address(socket)
end
end
defp peer_address(socket) do
case Phoenix.LiveView.get_connect_info(socket, :peer_data) do
%{address: address} -> address
_ -> nil
end
end
defp parse_forwarded_header([value | _]) when is_binary(value), do: parse_address(value)
defp parse_forwarded_header(_headers), do: nil
defp parse_x_headers(headers) when is_list(headers) do
case List.keyfind(headers, "x-forwarded-for", 0) do
{_, value} when is_binary(value) -> parse_address(value)
_ -> nil
end
end
defp parse_x_headers(_headers), do: nil
# The rightmost entry is the one our own proxy appended.
defp parse_address(value) do
value
|> String.split(",")
|> List.last()
|> to_string()
|> String.trim()
|> String.to_charlist()
|> :inet.parse_address()
|> case do
{:ok, address} -> address
{:error, _} -> nil
end
end
defp fallback(nil, fallback), do: fallback
defp fallback(address, _fallback), do: address
end
@@ -65,7 +65,7 @@ defmodule ChesstrainerWeb.CoreComponents do
attr :id, :string, doc: "the optional id of flash container"
attr :flash, :map, default: %{}, doc: "the map of flash messages to display"
attr :title, :string, default: nil
attr :kind, :atom, values: [:info, :error], doc: "used for styling and flash lookup"
attr :kind, :atom, values: [:info, :success, :error], doc: "used for styling and flash lookup"
attr :rest, :global, doc: "the arbitrary HTML attributes to add to the flash container"
slot :inner_block, doc: "the optional inner block that renders the flash message"
@@ -86,9 +86,11 @@ defmodule ChesstrainerWeb.CoreComponents do
<div class={[
"flex w-full items-start gap-3 rounded-lg border px-4 py-3 text-sm text-wrap shadow-lg",
@kind == :info && "border-info bg-info text-info-content",
@kind == :success && "border-accent bg-accent text-accent-content",
@kind == :error && "border-error bg-error text-error-content"
]}>
<.icon :if={@kind == :info} name="hero-information-circle" class="size-5 shrink-0" />
<.icon :if={@kind == :success} name="hero-check-circle" class="size-5 shrink-0" />
<.icon :if={@kind == :error} name="hero-exclamation-circle" class="size-5 shrink-0" />
<div>
<p :if={@title} class="font-semibold">{@title}</p>
@@ -356,10 +358,10 @@ defmodule ChesstrainerWeb.CoreComponents do
~H"""
<header class={[@actions != [] && "flex items-center justify-between gap-6", "pb-4"]}>
<div>
<h1 class="text-lg font-semibold leading-8">
<h1 class="settings-header">
{render_slot(@inner_block)}
</h1>
<p :if={@subtitle != []} class="text-sm text-base-content/70 mt-4">
<p :if={@subtitle != []} class="settings-subtitle">
{render_slot(@subtitle)}
</p>
</div>
+134 -1
View File
@@ -5,6 +5,7 @@ defmodule ChesstrainerWeb.Layouts do
"""
use ChesstrainerWeb, :html
alias Chesstrainer.Accounts.Policy
alias Chesstrainer.Accounts.Role
alias Chesstrainer.Accounts.Scope
@@ -125,14 +126,57 @@ defmodule ChesstrainerWeb.Layouts do
Start training <.icon_arrow />
</.pill_button>
<% end %>
<div class="nav-menu-tools">
<.colour_mode_toggle />
<.discord_link />
</div>
</div>
<% end %>
<.discord_link />
</div>
</nav>
</header>
"""
end
@doc """
Renders the shared sub-navigation for admin pages.
Items are filtered by capability, so the same component is safe to render on
every admin screen.
"""
attr :current_scope, :map, default: nil
def admin_nav(assigns) do
links =
for {capability, label, href} <- [
{:manage_endgames, "Endgames", ~p"/admin/endgames"},
{:manage_themes, "Themes", ~p"/admin/themes"},
{:manage_users, "Users", ~p"/admin/users"}
],
Policy.can?(assigns.current_scope, capability),
do: %{label: label, href: href}
assigns = assign(assigns, :links, links)
~H"""
<nav
aria-label="Admin"
class="mb-6 flex flex-wrap items-center gap-1 border-b border-base-200 pb-3 text-sm font-semibold"
>
<.link
:for={link <- @links}
navigate={link.href}
class="rounded-md px-3 py-1.5 text-base-content/70 hover:bg-base-200 hover:text-base-content"
>
{link.label}
</.link>
</nav>
"""
end
defp nav_links(scope) do
marketing =
if Scope.premium?(scope) do
@@ -186,6 +230,9 @@ defmodule ChesstrainerWeb.Layouts do
<nav class="footer-links" aria-label="Footer">
<a href="/privacy">Privacy Policy</a>
<a href="/terms-conditions">Terms & Conditions</a>
<a href="/mentions-legales">Mentions légales</a>
<a href="/sitemap.xml">Sitemap</a>
<.discord_link />
</nav>
<small>© {@year} {Branding.name()}</small>
@@ -193,6 +240,35 @@ defmodule ChesstrainerWeb.Layouts do
"""
end
@doc """
Renders the Discord invite as an icon-only link.
The glyph is decorative; the `aria-label` carries the link's purpose for
screen readers. Renders nothing when no invite is configured, so environments
without one never show a dead link.
"""
def discord_link(assigns) do
assigns = assign(assigns, :href, Branding.discord_invite_url())
~H"""
<a
:if={@href}
class="discord-link"
href={@href}
target="_blank"
rel="noopener noreferrer"
aria-label={"Join the #{Branding.name()} Discord"}
>
<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
<path
fill="currentColor"
d="M20.317 4.3698a19.7913 19.7913 0 0 0-4.8851-1.5152.0741.0741 0 0 0-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 0 0-.0785-.037 19.7363 19.7363 0 0 0-4.8852 1.515.0699.0699 0 0 0-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 0 0 .0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 0 0 .0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 0 0-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 0 1-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 0 1 .0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 0 1 .0785.0105c.1202.0991.246.1971.3728.2914a.077.077 0 0 1-.0066.1277c-.5986.3428-1.2201.6447-1.8739.8923a.0766.0766 0 0 0-.0407.1057c.36.699.7715 1.3647 1.225 1.9942a.076.076 0 0 0 .0843.0276c1.9608-.6066 3.9493-1.5218 6.0021-3.0294a.077.077 0 0 0 .0322-.0561c.5008-5.1763-.8398-9.6746-3.5543-13.6607a.061.061 0 0 0-.0312-.0286zM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z"
/>
</svg>
</a>
"""
end
@doc """
Shows the flash group with standard titles and content.
@@ -208,9 +284,10 @@ defmodule ChesstrainerWeb.Layouts do
<div
id={@id}
aria-live="polite"
class="pointer-events-none fixed right-4 top-4 z-50 flex w-80 max-w-80 flex-col gap-2 sm:w-96 sm:max-w-96"
class="pointer-events-none fixed left-4 top-4 z-50 flex w-80 max-w-80 flex-col gap-2 sm:w-96 sm:max-w-96"
>
<.flash kind={:info} flash={@flash} />
<.flash kind={:success} flash={@flash} />
<.flash kind={:error} flash={@flash} />
<.flash
@@ -242,6 +319,17 @@ defmodule ChesstrainerWeb.Layouts do
{gettext("Attempting to reconnect")}
<.icon name="hero-arrow-path" class="ml-1 size-3 motion-safe:animate-spin" />
</.flash>
<div
id="connection-actions"
hidden
phx-disconnected={show("#connection-actions")}
phx-connected={hide("#connection-actions")}
class="pointer-events-auto flex items-center gap-3 rounded-lg border border-base-300 bg-base-100 px-4 py-2 text-sm shadow-lg"
>
<a href="" class="font-semibold text-primary-text hover:underline">Reload</a>
<.link href={~p"/"} class="text-muted hover:underline">Home</.link>
</div>
</div>
"""
end
@@ -296,4 +384,49 @@ defmodule ChesstrainerWeb.Layouts do
</div>
"""
end
@doc """
Renders the Matomo configuration for anonymous public pages.
The actual tracker is initialised by `assets/js/analytics.js`. Signed-in
visitors never get the config element, so account and admin pages are not
tracked.
"""
attr :current_scope, :map, default: nil
def analytics(assigns) do
config = Application.get_env(:chesstrainer, :matomo, [])
url = normalize_matomo_url(config[:url])
site_id = config[:site_id]
user = Map.get(assigns, :current_scope) && assigns.current_scope.user
assigns =
assign(assigns,
matomo_url: url,
matomo_site_id: site_id && to_string(site_id),
analytics_enabled:
is_binary(url) and byte_size(url) > 0 and is_binary(site_id) and byte_size(site_id) > 0 and
is_nil(user)
)
~H"""
<div
:if={@analytics_enabled}
id="matomo-config"
data-url={@matomo_url}
data-site-id={@matomo_site_id}
hidden
>
</div>
"""
end
defp normalize_matomo_url(url) when is_binary(url) do
case String.trim(url) do
"" -> nil
url -> String.trim_trailing(url, "/") <> "/"
end
end
defp normalize_matomo_url(_url), do: nil
end
@@ -1,9 +1,9 @@
<!DOCTYPE html>
<html lang="en">
<html lang={assigns[:lang] || "en"}>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta :if={assigns[:noindex]} name="robots" content="noindex" />
<meta :if={assigns[:noindex]} name="robots" content="noindex, nofollow" />
<meta name="csrf-token" content={get_csrf_token()} />
<.live_title
@@ -30,7 +30,24 @@
content={assigns[:meta_description]}
/>
<meta :if={assigns[:canonical_url]} property="og:url" content={assigns[:canonical_url]} />
<meta :if={assigns[:meta_description]} name="twitter:card" content="summary" />
<meta
:if={assigns[:meta_description]}
property="og:image"
content={assigns[:og_image_url] || SEO.og_image_url()}
/>
<meta :if={assigns[:meta_description]} property="og:image:width" content="1200" />
<meta :if={assigns[:meta_description]} property="og:image:height" content="630" />
<meta
:if={assigns[:meta_description]}
property="og:image:alt"
content={"#{Branding.name()} — #{Branding.tagline()}"}
/>
<meta :if={assigns[:meta_description]} name="twitter:card" content="summary_large_image" />
<meta
:if={assigns[:meta_description]}
name="twitter:image"
content={assigns[:og_image_url] || SEO.og_image_url()}
/>
<meta
:if={assigns[:meta_description]}
name="twitter:title"
@@ -41,6 +58,14 @@
name="twitter:description"
content={assigns[:meta_description]}
/>
<link rel="icon" href="/favicon.ico" sizes="48x48" />
<link rel="icon" href="/favicon.svg" type="image/svg+xml" />
<link rel="icon" href="/favicon-32x32.png" type="image/png" sizes="32x32" />
<link rel="icon" href="/favicon-16x16.png" type="image/png" sizes="16x16" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<link rel="manifest" href="/site.webmanifest" />
<meta name="theme-color" content="#17352d" />
<link phx-track-static rel="stylesheet" href={~p"/assets/css/app.css"} />
<link
rel="preload"
@@ -65,6 +90,9 @@
>
</script>
<Layouts.theme_script />
<script :if={assigns[:json_ld]} type="application/ld+json">
<%= raw(assigns[:json_ld]) %>
</script>
</head>
<body>
<a
@@ -76,5 +104,6 @@
<Layouts.navbar current_scope={@current_scope} />
{@inner_content}
<Layouts.footer />
<Layouts.analytics current_scope={@current_scope} />
</body>
</html>
@@ -65,7 +65,10 @@
if (event.key !== "ArrowLeft" && event.key !== "ArrowRight") return;
event.preventDefault();
const buttons = Array.from(document.querySelectorAll("[data-phx-theme]"));
// Each breakpoint renders its own copy of the switch, so only the visible
// group takes part in arrow-key navigation.
const buttons = Array.from(document.querySelectorAll("[data-phx-theme]"))
.filter((button) => button.offsetParent !== null);
const offset = event.key === "ArrowRight" ? 1 : -1;
const index = (buttons.indexOf(button) + offset + buttons.length) % buttons.length;
const next = buttons[index];
@@ -14,14 +14,14 @@ defmodule ChesstrainerWeb.PlayComponents do
attr :endgame, :any, required: true
attr :fen, :string, default: nil
attr :status, :atom, required: true
attr :blocked_reason, :string, default: nil
attr :blocked, :map, default: nil
attr :best_move, :string, default: nil
attr :plies, :list, required: true
attr :line, :list, required: true
attr :reviewing, :boolean, required: true
attr :review_index, :integer, required: true
attr :review_tablebase, :any, default: nil
attr :review_blocked, :string, default: nil
attr :review_blocked, :map, default: nil
attr :awaiting_reply, :boolean, required: true
attr :last_grade, :atom, default: nil
attr :awaiting_best_line, :boolean, default: false
@@ -30,6 +30,8 @@ defmodule ChesstrainerWeb.PlayComponents do
attr :move_input_error, :string, default: nil
attr :last_check, :boolean, default: false
attr :last_checkmate, :boolean, default: false
attr :rating, :any, default: nil
attr :rating_delta, :any, default: nil
def play_surface(assigns) do
assigns =
@@ -167,7 +169,23 @@ defmodule ChesstrainerWeb.PlayComponents do
>
<.icon name="hero-eye" /> Review
</.button>
<.button phx-click="reset" variant="primary">
<.button
:if={@status == :blocked && @blocked && @blocked.retry}
id="retry-blocked"
phx-click="reset"
variant="primary"
>
<.icon name="hero-arrow-path" /> Retry
</.button>
<.button
:if={@status == :blocked && @blocked && !@blocked.retry && @session}
id="next-after-blocked"
phx-click="next_puzzle"
variant="primary"
>
Next puzzle
</.button>
<.button :if={@status != :blocked} phx-click="reset" variant="primary">
<.icon name="hero-arrow-path" />
{if @status in [:solved, :failed], do: "Try again", else: "Reset"}
</.button>
@@ -192,7 +210,7 @@ defmodule ChesstrainerWeb.PlayComponents do
<%= cond do %>
<% @review_blocked -> %>
<p class="text-muted">Best move unavailable here</p>
<p class="text-muted">{@review_blocked}</p>
<p class="text-muted">{@review_blocked.message}</p>
<% @review_tablebase -> %>
<p class="text-muted font-semibold mb-1">Best move:</p>
<p class="text-success-text">{PlayCore.best_move_text(@review_tablebase) || "—"}</p>
@@ -209,9 +227,9 @@ defmodule ChesstrainerWeb.PlayComponents do
<%= cond do %>
<% @status == :loading -> %>
<p class="text-muted">Loading tablebase…</p>
<% @status == :blocked -> %>
<p class="font-semibold text-error-text">Tablebase unavailable</p>
<p class="text-error-text">{@blocked_reason}</p>
<% @status == :blocked && @blocked -> %>
<p class="font-semibold text-error-text">{@blocked.title}</p>
<p class="text-error-text">{@blocked.message}</p>
<% @status == :solved -> %>
<p class="font-semibold text-success-text">
{if @endgame.result == :draw, do: "Draw held!", else: "Solved!"}
@@ -250,9 +268,17 @@ defmodule ChesstrainerWeb.PlayComponents do
<p class="text-muted font-bold">Make a move.</p>
<p class="text-muted">You play {colour_name(@endgame.color)}</p>
<% end %>
<p :if={@status in [:solved, :failed]} class="mt-1 text-xs text-muted">
Puzzle rating: {round(@endgame.rating)}
</p>
<div
:if={@status in [:solved, :failed]}
class="mt-1 flex flex-wrap items-center gap-x-3 gap-y-1 text-xs"
>
<span class="text-muted">Puzzle rating: {round(@endgame.rating)}</span>
<span :if={@rating} id="your-rating" class="flex items-center gap-1.5 text-muted">
Your rating
<span class="font-mono font-semibold text-base-content">{round(@rating)}</span>
<.rating_change :if={@rating_delta} id="rating-change" delta={@rating_delta} />
</span>
</div>
</div>
<div
@@ -411,8 +437,7 @@ defmodule ChesstrainerWeb.PlayComponents do
|> Enum.with_index(1)
end
defp display_plies(true, line, _plies), do: line
defp display_plies(false, _line, plies), do: plies
defp display_plies(reviewing, line, plies), do: if(reviewing, do: line, else: plies)
defp colour_name(:white), do: "White"
defp colour_name(:black), do: "Black"
@@ -450,8 +475,7 @@ defmodule ChesstrainerWeb.PlayComponents do
defp move_hint(:loading, _awaiting), do: "Loading the tablebase…"
defp move_hint(:blocked, _awaiting),
do: "The tablebase is unavailable, so moves cannot be entered."
defp move_hint(:blocked, _awaiting), do: "Moves are paused."
defp move_hint(status, _awaiting) when status in [:solved, :failed],
do: "This puzzle is finished. Reset or try again."
@@ -478,7 +502,10 @@ defmodule ChesstrainerWeb.PlayComponents do
"Loading the tablebase."
assigns.status == :blocked ->
"Tablebase unavailable. #{assigns.blocked_reason || "Moves cannot be graded."}"
case assigns.blocked do
%{title: title, message: message} -> "#{title}. #{message}"
_ -> "Tablebase unavailable."
end
assigns.reviewing ->
review_announcement(assigns)
@@ -10,6 +10,8 @@ defmodule ChesstrainerWeb.RatingComponents do
use Phoenix.Component
import ChesstrainerWeb.CoreComponents, only: [icon: 1]
# Glicko ratings are conventionally shown on a 0–3000 scale. The default
# rating is 1500 and the deviation is capped at 350, so 500–3000 keeps the
# useful range readable without letting a stray value push the marker off.
@@ -78,6 +80,56 @@ defmodule ChesstrainerWeb.RatingComponents do
"""
end
@doc """
Renders a signed rating change as a compact, colour-coded pill.
A gain is green with an upward trend, a loss is red with a downward trend,
and no change is neutral.
"""
attr :delta, :any, required: true
attr :id, :string, default: nil
attr :class, :any, default: nil
def rating_change(assigns) do
~H"""
<span
id={@id}
class={[
"inline-flex items-center gap-0.5 rounded-full px-1.5 py-0.5 font-mono text-xs font-semibold",
change_class(@delta),
@class
]}
>
<.icon name={change_icon(@delta)} class="size-3.5" />
{format_delta(@delta)}
</span>
"""
end
@doc "Formats a rating change with an explicit sign, e.g. `+12`, `-8` or `0`."
def format_delta(nil), do: "—"
def format_delta(delta) when is_number(delta) do
rounded = round(delta)
cond do
rounded > 0 -> "+#{rounded}"
true -> Integer.to_string(rounded)
end
end
defp change_class(delta) when is_number(delta) and delta > 0,
do: "bg-success/15 text-success-text"
defp change_class(delta) when is_number(delta) and delta < 0,
do: "bg-error/15 text-error-text"
defp change_class(_delta), do: "bg-base-200 text-muted"
defp change_icon(delta) when is_number(delta) and delta > 0, do: "hero-arrow-trending-up"
defp change_icon(delta) when is_number(delta) and delta < 0, do: "hero-arrow-trending-down"
defp change_icon(_delta), do: "hero-minus"
# Position on the gauge as a percentage, clamped to the drawn scale.
defp pct(value) do
clamped = value |> max(@scale_min) |> min(@scale_max)
@@ -0,0 +1,136 @@
defmodule ChesstrainerWeb.ThemePicker do
@moduledoc """
Search-and-select control shared by the endgame form and bulk importer.
The parent LiveView owns the assignments and handles the events:
`search_themes`, `add_theme`, `create_theme` and `remove_theme`.
The control renders no `<form>` of its own. It is embedded in the endgame
form, where a nested form would be dropped by the HTML parser and take its
bindings with it, and it is used standalone on the bulk importer. Binding
`phx-change` on the search input keeps both call sites working.
"""
use ChesstrainerWeb, :html
alias Chesstrainer.Themes
attr :selected_themes, :list, required: true
attr :theme_query, :string, required: true
attr :theme_results, :list, required: true
attr :can_create, :boolean, required: true
def theme_picker(assigns) do
~H"""
<div class="mb-6">
<span class="mb-1 block text-sm font-medium text-base-content">Themes</span>
<div class="flex flex-wrap gap-2 mb-2">
<.badge :for={theme <- @selected_themes} color="primary">
{theme.name}
<button
type="button"
phx-click="remove_theme"
phx-value-id={theme.id}
aria-label={"Remove #{theme.name}"}
>
×
</button>
</.badge>
</div>
<div id="theme-picker">
<.input
name="theme_search"
value={@theme_query}
phx-change="search_themes"
phx-debounce="200"
autocomplete="off"
placeholder="Search or create a theme…"
/>
<ul>
<li :for={theme <- @theme_results}>
<button
type="button"
phx-click="add_theme"
phx-value-id={theme.id}
class="block w-full rounded px-3 py-2 text-left text-sm hover:bg-base-200"
>
{theme.name}
</button>
</li>
<li :if={@can_create}>
<button
type="button"
phx-click="create_theme"
phx-value-name={@theme_query}
class="block w-full rounded px-3 py-2 text-left text-sm hover:bg-base-200"
>
Create theme "{String.trim(@theme_query)}"
</button>
</li>
</ul>
</div>
</div>
"""
end
@doc """
Updates the search query, matching endgame themes and whether the query can be
created as a new theme.
"""
def assign_search(socket, query) do
trimmed = String.trim(query)
results = Themes.search(query, "endgame")
can_create =
trimmed != "" and
not Enum.any?(results, &(String.downcase(&1.name) == String.downcase(trimmed)))
socket
|> assign(:theme_query, query)
|> assign(:theme_results, results)
|> assign(:can_create, can_create)
end
@doc """
Creates a theme from the search box (or selects the existing match) and adds
it to the selected themes.
"""
def create_theme(socket, name) do
if String.trim(name) == "" do
socket
else
case Themes.get_or_create(name, "endgame") do
{:ok, theme} ->
socket |> add_selected_theme(theme) |> clear_search()
{:error, _reason} ->
Phoenix.LiveView.put_flash(socket, :error, "Could not create that theme.")
end
end
end
@doc """
Clears the theme search results.
"""
def clear_search(socket) do
socket
|> assign(:theme_query, "")
|> assign(:theme_results, [])
|> assign(:can_create, false)
end
@doc """
Adds a theme to the selected themes, ignoring duplicates.
"""
def add_selected_theme(socket, theme) do
if Enum.any?(socket.assigns.selected_themes, &(&1.id == theme.id)) do
socket
else
assign(socket, :selected_themes, socket.assigns.selected_themes ++ [theme])
end
end
end
@@ -6,6 +6,14 @@
<meta name="robots" content="noindex" />
<title>{Branding.title("Page not found")}</title>
<link rel="icon" href="/favicon.ico" sizes="48x48" />
<link rel="icon" href="/favicon.svg" type="image/svg+xml" />
<link rel="icon" href="/favicon-32x32.png" type="image/png" sizes="32x32" />
<link rel="icon" href="/favicon-16x16.png" type="image/png" sizes="16x16" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<link rel="manifest" href="/site.webmanifest" />
<meta name="theme-color" content="#17352d" />
<link phx-track-static rel="stylesheet" href={~p"/assets/css/app.css"} />
<link
rel="preload"
@@ -6,6 +6,14 @@
<meta name="robots" content="noindex" />
<title>{Branding.title("Something went wrong")}</title>
<link rel="icon" href="/favicon.ico" sizes="48x48" />
<link rel="icon" href="/favicon.svg" type="image/svg+xml" />
<link rel="icon" href="/favicon-32x32.png" type="image/png" sizes="32x32" />
<link rel="icon" href="/favicon-16x16.png" type="image/png" sizes="16x16" />
<link rel="apple-touch-icon" sizes="180x180" href="/apple-touch-icon.png" />
<link rel="manifest" href="/site.webmanifest" />
<meta name="theme-color" content="#17352d" />
<link phx-track-static rel="stylesheet" href={~p"/assets/css/app.css"} />
<link
rel="preload"
@@ -10,7 +10,7 @@ defmodule ChesstrainerWeb.HealthController do
status = if health.status == "down", do: :service_unavailable, else: :ok
conn
|> put_resp_header("x-robots-tag", "noindex")
|> put_resp_header("x-robots-tag", "noindex, nofollow")
|> put_status(status)
|> json(health)
end
@@ -6,6 +6,7 @@ defmodule ChesstrainerWeb.PageController do
alias Chesstrainer.Branding
alias Chesstrainer.DailyPuzzles
alias Chesstrainer.Endgames
alias ChesstrainerWeb.SEO
@description "Short, focused endgame puzzles against tablebase-perfect defence. " <>
"Learn to see the winning move and make the endgame your strongest phase."
@@ -15,13 +16,15 @@ defmodule ChesstrainerWeb.PageController do
render_coming_soon(conn)
else
endgames = Endgames.curated_endgames()
canonical_url = SEO.canonical_url(conn)
conn
|> assign(:js_entry, ~p"/assets/js/marketing.js")
|> assign(:page_title, Branding.home_title())
|> assign(:title_suffix, "")
|> assign(:meta_description, @description)
|> assign(:canonical_url, current_url(conn))
|> assign(:canonical_url, canonical_url)
|> assign(:json_ld, SEO.json_ld(canonical_url))
|> assign(:mailing_list_enabled, mailing_list_enabled?())
|> render(:home,
endgames: endgames,
@@ -43,7 +46,7 @@ defmodule ChesstrainerWeb.PageController do
:meta_description,
"How #{Branding.name()} collects, uses, and protects your personal data."
)
|> assign(:canonical_url, current_url(conn))
|> assign(:canonical_url, SEO.canonical_url(conn))
|> render(:privacy)
end
@@ -53,10 +56,24 @@ defmodule ChesstrainerWeb.PageController do
|> assign(:page_title, Branding.title("Terms & Conditions"))
|> assign(:title_suffix, "")
|> assign(:meta_description, "The terms that apply when you use #{Branding.name()}.")
|> assign(:canonical_url, current_url(conn))
|> assign(:canonical_url, SEO.canonical_url(conn))
|> render(:terms_conditions)
end
def mentions_legales(conn, _params) do
conn
|> assign(:js_entry, ~p"/assets/js/marketing.js")
|> assign(:page_title, Branding.title("Mentions légales"))
|> assign(:title_suffix, "")
|> assign(
:meta_description,
"Éditeur, hébergeur et informations légales de #{Branding.name()}."
)
|> assign(:canonical_url, SEO.canonical_url(conn))
|> assign(:lang, "fr")
|> render(:mentions_legales)
end
def not_found(conn, _params) do
conn
|> put_status(:not_found)
@@ -73,7 +90,7 @@ defmodule ChesstrainerWeb.PageController do
|> assign(:page_title, Branding.home_title())
|> assign(:title_suffix, "")
|> assign(:meta_description, @description)
|> assign(:canonical_url, current_url(conn))
|> assign(:canonical_url, SEO.canonical_url(conn))
|> assign(:noindex, true)
|> assign(:mailing_list_enabled, mailing_list_enabled?())
|> render(:coming_soon)
@@ -8,6 +8,6 @@ defmodule ChesstrainerWeb.PageHTML do
embed_templates "page_html/*"
defp play_path(nil), do: ~p"/endgames"
defp play_path(nil), do: ~p"/guest-train"
defp play_path(%{public_code: public_code}), do: ~p"/endgames/#{public_code}/play"
end
@@ -12,9 +12,15 @@
Train your intuition to find the winning moves under pressure. Puzzle sessions focused purely on technical execution.
</p>
<div class="hero-actions">
<.pill_button variant={:primary} navigate={play_path(@active_endgame)}>
Try today's puzzle <.icon_arrow />
</.pill_button>
<%= if @active_endgame do %>
<.pill_button variant={:primary} navigate={play_path(@active_endgame)}>
Try today's puzzle <.icon_arrow />
</.pill_button>
<% else %>
<.pill_button variant={:primary} navigate={play_path(nil)}>
Start training <.icon_arrow />
</.pill_button>
<% end %>
<div class="rating-note">
<span class="avatar-stack">
<i>♟</i>
@@ -34,8 +40,11 @@
</div>
</section>
<%!-- <section class="learning-strip" id="method">
<p>Built for the part of chess that decides everything.</p>
<section class="learning-strip" id="method">
<figure class="learning-quote">
<blockquote>“The hardest game to win is a won game.”</blockquote>
<figcaption>— Emmanuel Lasker</figcaption>
</figure>
<div class="stat">
<strong>{count_label(@puzzle_count)}</strong>
<span>puzzles</span>
@@ -44,9 +53,9 @@
<strong>{@user_count}</strong>
<span>Players improving their endgame</span>
</div>
</section> --%>
</section>
<%!-- <section class="puzzle-section" id="puzzles">
<section class="puzzle-section" id="puzzles">
<div class="section-heading">
<div>
<span class="section-kicker">Choose your lesson</span>
@@ -59,16 +68,16 @@
that you’ll recognise over the board.
</p>
</div>
<div class="puzzle-grid">
<%= for {endgame, index} <- Enum.with_index(@endgames) do %>
<.puzzle_card
endgame={endgame}
index={index}
active={@active_endgame && endgame.id == @active_endgame.id}
/>
<% end %>
<div class="puzzle-coming-soon">
<div class="eyebrow">
<.icon_spark /> Coming soon
</div>
<strong>The lesson library is on its way.</strong>
<p>
A growing set of positions, each teaching one idea. Today’s puzzle is already live.
</p>
</div>
</section> --%>
</section>
<.mailing_list_signup :if={@mailing_list_enabled} />

Some files were not shown because too many files have changed in this diff Show More