From 37e0ac8e56d7de999e2f34a102be36d185d7b5a4 Mon Sep 17 00:00:00 2001 From: Owen Rees Date: Tue, 17 Nov 2026 10:29:45 +0100 Subject: [PATCH] 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. --- .env.example | 4 + config/config.exs | 2 +- config/runtime.exs | 18 ++++ deploy/README.md | 42 ++++++++ docs/assets.md | 84 +++++++++++++++ lib/chesstrainer/accounts/user_notifier.ex | 17 ++- lib/chesstrainer/branding.ex | 2 +- lib/chesstrainer/mail.ex | 82 ++++++++++++++ lib/chesstrainer/mailing_list/notifier.ex | 18 ++-- lib/chesstrainer_web.ex | 1 + lib/chesstrainer_web/components/layouts.ex | 3 +- .../components/layouts/root.html.heex | 24 ++++- .../controllers/page_controller.ex | 14 ++- .../controllers/sitemap_controller.ex | 27 +++-- lib/chesstrainer_web/router.ex | 4 +- lib/chesstrainer_web/seo.ex | 49 +++++++++ lib/mix/tasks/assets.sizes.ex | 101 ++++++++++++++++++ lib/mix/tasks/mail.check.ex | 84 +++++++++++++++ priv/static/images/og.png | Bin 0 -> 34859 bytes test/chesstrainer/mail_test.exs | 72 +++++++++++++ .../controllers/page_controller_test.exs | 37 ++++++- .../controllers/sitemap_controller_test.exs | 7 ++ .../live/endgame_live/guest_train_test.exs | 9 ++ .../live/endgame_live/play_test.exs | 9 ++ 24 files changed, 666 insertions(+), 44 deletions(-) create mode 100644 docs/assets.md create mode 100644 lib/chesstrainer/mail.ex create mode 100644 lib/chesstrainer_web/seo.ex create mode 100644 lib/mix/tasks/assets.sizes.ex create mode 100644 lib/mix/tasks/mail.check.ex create mode 100644 priv/static/images/og.png create mode 100644 test/chesstrainer/mail_test.exs diff --git a/.env.example b/.env.example index 84acf5f..e4ef019 100644 --- a/.env.example +++ b/.env.example @@ -7,6 +7,10 @@ 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 TABLEBASE_PATH= MATOMO_URL=https://analytics.owenrees.eu/ diff --git a/config/config.exs b/config/config.exs index feea72e..9991f63 100644 --- a/config/config.exs +++ b/config/config.exs @@ -15,7 +15,7 @@ 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" # Prelaunch gating. Production sets these from PRELAUNCH and # MAILING_LIST_ENABLED; dev and test use these defaults. diff --git a/config/runtime.exs b/config/runtime.exs index 70d8b59..25f0990 100644 --- a/config/runtime.exs +++ b/config/runtime.exs @@ -28,6 +28,24 @@ 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. diff --git a/deploy/README.md b/deploy/README.md index 110bff7..6921717 100644 --- a/deploy/README.md +++ b/deploy/README.md @@ -141,6 +141,7 @@ 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 MATOMO_URL=https://analytics.owenrees.eu/ MATOMO_SITE_ID=6 @@ -162,6 +163,47 @@ pages and the guest trainer. Signed-in account and admin pages are excluded. The privacy controls, Matomo server settings, retention, and opt-out behaviour are documented in `docs/analytics.md`. +## Transactional email + +Every outgoing email goes through `Chesstrainer.Mail`, which applies the same +house rules everywhere: + +- **From**: `Inner Square Chess `. The address + lives on the `mail.` subdomain; SES verifies the parent domain, and subdomains + inherit that verification, so the subdomain does not need its own identity. +- **Reply-To**: `support@innersquare.app`. Replies reach a monitored inbox even + though the sender says `no-reply`. +- **SES configuration set**: `SES_CONFIGURATION_SET`, default + `my-first-configuration-set`. The set is what links a message to its SNS + bounce and complaint notifications. It must exist in `SES_REGION`. + +Optional overrides: + +```sh +MAIL_FROM=no-reply@mail.innersquare.app # try another sender without a rebuild +MAIL_REDIRECT_TO=you@example.com # rewrite every recipient (staging/smoke tests) +``` + +`MAIL_REDIRECT_TO` rewrites `to`, `cc` and `bcc` to one address, prefixes the +subject with the original recipients and adds an `X-Original-To` header, so a +redirected message explains itself. Leave it unset in normal operation. + +Check delivery from the release environment: + +```sh +bin/chesstrainer eval 'Mix.Task.run("mail.check", ["--to", "you@example.com"])' +``` + +or, in a checkout configured with the production SES variables, +`mix mail.check --to you@example.com`. The task sends to the given address plus +the SES mailbox simulators (`success@`, `bounce@`, `complaint@simulator... +amazonses.com`) so the configuration set's bounce and complaint path can be +exercised without touching a real inbox. Use `--no-simulators` to skip them. + +DNS: the apex publishes DMARC (`p=quarantine`) with aggregate reports sent to +`dmarc@innersquare.app`, and `mail.innersquare.app` carries the custom MAIL FROM +SPF record and the SES feedback MX. + Generate the two secrets: ```sh diff --git a/docs/assets.md b/docs/assets.md new file mode 100644 index 0000000..451dc44 --- /dev/null +++ b/docs/assets.md @@ -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. diff --git a/lib/chesstrainer/accounts/user_notifier.ex b/lib/chesstrainer/accounts/user_notifier.ex index 83d3bcb..69cbe25 100644 --- a/lib/chesstrainer/accounts/user_notifier.ex +++ b/lib/chesstrainer/accounts/user_notifier.ex @@ -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 """ diff --git a/lib/chesstrainer/branding.ex b/lib/chesstrainer/branding.ex index 539a839..76d5c59 100644 --- a/lib/chesstrainer/branding.ex +++ b/lib/chesstrainer/branding.ex @@ -12,7 +12,7 @@ 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" ] @doc "The display name, e.g. `\"Lucid Chess\"`." diff --git a/lib/chesstrainer/mail.ex b/lib/chesstrainer/mail.ex new file mode 100644 index 0000000..f28ef19 --- /dev/null +++ b/lib/chesstrainer/mail.ex @@ -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 diff --git a/lib/chesstrainer/mailing_list/notifier.ex b/lib/chesstrainer/mailing_list/notifier.ex index c8dc5be..b87317e 100644 --- a/lib/chesstrainer/mailing_list/notifier.ex +++ b/lib/chesstrainer/mailing_list/notifier.ex @@ -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 diff --git a/lib/chesstrainer_web.ex b/lib/chesstrainer_web.ex index c6751d9..163a822 100644 --- a/lib/chesstrainer_web.ex +++ b/lib/chesstrainer_web.ex @@ -107,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()) diff --git a/lib/chesstrainer_web/components/layouts.ex b/lib/chesstrainer_web/components/layouts.ex index 9cf38bb..13d0460 100644 --- a/lib/chesstrainer_web/components/layouts.ex +++ b/lib/chesstrainer_web/components/layouts.ex @@ -368,7 +368,8 @@ defmodule ChesstrainerWeb.Layouts do matomo_url: url, matomo_site_id: site_id && to_string(site_id), analytics_enabled: - is_binary(url) and url != "" and site_id not in [nil, ""] and is_nil(user) + is_binary(url) and byte_size(url) > 0 and is_binary(site_id) and byte_size(site_id) > 0 and + is_nil(user) ) ~H""" diff --git a/lib/chesstrainer_web/components/layouts/root.html.heex b/lib/chesstrainer_web/components/layouts/root.html.heex index edab3a3..a865155 100644 --- a/lib/chesstrainer_web/components/layouts/root.html.heex +++ b/lib/chesstrainer_web/components/layouts/root.html.heex @@ -1,5 +1,5 @@ - + @@ -30,7 +30,24 @@ content={assigns[:meta_description]} /> - + + + + + + + "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,7 +56,7 @@ 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 @@ -66,7 +69,8 @@ defmodule ChesstrainerWeb.PageController do :meta_description, "Éditeur, hébergeur et informations légales de #{Branding.name()}." ) - |> assign(:canonical_url, current_url(conn)) + |> assign(:canonical_url, SEO.canonical_url(conn)) + |> assign(:lang, "fr") |> render(:mentions_legales) end @@ -86,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) diff --git a/lib/chesstrainer_web/controllers/sitemap_controller.ex b/lib/chesstrainer_web/controllers/sitemap_controller.ex index 1cea4b4..b77459f 100644 --- a/lib/chesstrainer_web/controllers/sitemap_controller.ex +++ b/lib/chesstrainer_web/controllers/sitemap_controller.ex @@ -11,28 +11,37 @@ defmodule ChesstrainerWeb.SitemapController do use ChesstrainerWeb, :controller def index(conn, _params) do - urls = [ - url(conn, ~p"/"), - url(conn, ~p"/privacy"), - url(conn, ~p"/terms-conditions"), - url(conn, ~p"/mentions-legales") + # The landing page changes every day (daily puzzle, counts), so its + # lastmod is honest. The legal pages have no stored modification time, and + # an invented lastmod is worse than none. + entries = [ + {url(conn, ~p"/"), Date.utc_today()}, + {url(conn, ~p"/privacy"), nil}, + {url(conn, ~p"/terms-conditions"), nil}, + {url(conn, ~p"/mentions-legales"), nil} ] conn |> put_resp_content_type("application/xml") - |> send_resp(200, render_sitemap(urls)) + |> send_resp(200, render_sitemap(entries)) end - defp render_sitemap(urls) do - entries = Enum.map_join(urls, &" #{escape(&1)}\n") + defp render_sitemap(entries) do + urls = + Enum.map_join(entries, fn {loc, lastmod} -> + " #{escape(loc)}#{lastmod_entry(lastmod)}\n" + end) """ - #{entries} + #{urls} """ end + defp lastmod_entry(nil), do: "" + defp lastmod_entry(%Date{} = date), do: "#{Date.to_iso8601(date)}" + # Templates escape automatically; this response is built as a plain string, # so XML-significant characters must be escaped here. defp escape(value) do diff --git a/lib/chesstrainer_web/router.ex b/lib/chesstrainer_web/router.ex index 6a41f48..66af034 100644 --- a/lib/chesstrainer_web/router.ex +++ b/lib/chesstrainer_web/router.ex @@ -111,7 +111,9 @@ defmodule ChesstrainerWeb.Router do end scope "/", ChesstrainerWeb do - pipe_through [:browser] + # App surface: play pages, auth forms and guest training are reachable + # without a session but must never appear in search results. + pipe_through [:browser, :noindex] live_session :current_user, on_mount: [ diff --git a/lib/chesstrainer_web/seo.ex b/lib/chesstrainer_web/seo.ex new file mode 100644 index 0000000..1c31aeb --- /dev/null +++ b/lib/chesstrainer_web/seo.ex @@ -0,0 +1,49 @@ +defmodule ChesstrainerWeb.SEO do + @moduledoc """ + Absolute URLs and crawler metadata for controller-rendered pages. + + Search engines need absolute URLs, so these helpers read the endpoint's + configured host rather than the request host (which is a proxy address). + + Canonical URLs deliberately drop the query string: campaign parameters such + as `?utm_source=...` must not become canonical pages of their own. + """ + + alias Chesstrainer.Branding + alias ChesstrainerWeb.Endpoint + + @og_image "/images/og.png" + @logo "/apple-touch-icon.png" + + @doc "The request path as an absolute canonical URL, without any query string." + def canonical_url(conn) do + Phoenix.VerifiedRoutes.unverified_url(conn, conn.request_path) + end + + @doc "Absolute URL of the social share image." + def og_image_url, do: Endpoint.url() <> @og_image + + @doc """ + JSON-LD for the site, encoded as a string ready for a + `