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.
This commit is contained in:
2026-11-17 10:29:45 +01:00
committed by GitHub
parent b33c5e334a
commit 37e0ac8e56
24 changed files with 666 additions and 44 deletions
+6 -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 """
+1 -1
View File
@@ -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\"`."
+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
+1
View File
@@ -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())
+2 -1
View File
@@ -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"""
@@ -1,5 +1,5 @@
<!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" />
@@ -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"
@@ -73,6 +90,9 @@
>
</script>
<Layouts.theme_script />
<script :if={assigns[:json_ld]} type="application/ld+json">
<%= raw(assigns[:json_ld]) %>
</script>
</head>
<body>
<a
@@ -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,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)
@@ -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, &" <url><loc>#{escape(&1)}</loc></url>\n")
defp render_sitemap(entries) do
urls =
Enum.map_join(entries, fn {loc, lastmod} ->
" <url><loc>#{escape(loc)}</loc>#{lastmod_entry(lastmod)}</url>\n"
end)
"""
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
#{entries}</urlset>
#{urls}</urlset>
"""
end
defp lastmod_entry(nil), do: ""
defp lastmod_entry(%Date{} = date), do: "<lastmod>#{Date.to_iso8601(date)}</lastmod>"
# Templates escape automatically; this response is built as a plain string,
# so XML-significant characters must be escaped here.
defp escape(value) do
+3 -1
View File
@@ -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: [
+49
View File
@@ -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
`<script type="application/ld+json">` block.
"""
def json_ld(url) do
%{
"@context" => "https://schema.org",
"@graph" => [
%{
"@type" => "WebSite",
"name" => Branding.name(),
"url" => url
},
%{
"@type" => "Organization",
"name" => Branding.name(),
"url" => url,
"logo" => Endpoint.url() <> @logo
}
]
}
|> Jason.encode!()
end
end
+101
View File
@@ -0,0 +1,101 @@
defmodule Mix.Tasks.Assets.Sizes do
use Mix.Task
@shortdoc "Report raw, gzip and brotli sizes of built assets"
@moduledoc """
Prints the size of every built JavaScript and CSS file under
`priv/static/assets`, uncompressed and compressed, so bundle changes can be
measured rather than guessed.
mix assets.sizes
Run it after `mix assets.build` (development, unminified) or
`mix assets.deploy` (production, minified and digested). Production numbers
are the ones that matter: they are what the browser downloads.
Brotli sizes are shown as a dash when the `brotli` CLI is not installed.
"""
@assets_globs ["priv/static/assets/js/**/*.js", "priv/static/assets/css/**/*.css"]
@impl true
def run(_argv) do
files = @assets_globs |> Enum.flat_map(&Path.wildcard/1) |> Enum.sort()
if files == [] do
Mix.raise("no built assets found under priv/static/assets; run mix assets.build")
end
rows = Enum.map(files, &measure/1)
print(rows)
end
defp measure(path) do
contents = File.read!(path)
%{
path: Path.relative_to_cwd(path),
raw: byte_size(contents),
gzip: byte_size(:zlib.gzip(contents)),
brotli: brotli_size(path)
}
end
defp brotli_size(path) do
with executable when is_binary(executable) <- System.find_executable("brotli"),
{output, 0} <- System.cmd(executable, ["-q", "11", "-c", path], into: "") do
byte_size(output)
else
_unavailable -> nil
end
end
defp print(rows) do
widths = column_widths(rows)
header = [
pad("file", widths.path),
pad("raw", widths.raw, :right),
pad("gzip", widths.gzip, :right),
pad("brotli", widths.brotli, :right)
]
Mix.shell().info(Enum.join(header, " "))
Mix.shell().info(String.duplicate("-", Enum.sum(Map.values(widths)) + 6))
Enum.each(rows, &print_row(&1, widths))
end
defp print_row(row, widths) do
values = [
pad(row.path, widths.path),
pad(human(row.raw), widths.raw, :right),
pad(human(row.gzip), widths.gzip, :right),
pad(human(row.brotli), widths.brotli, :right)
]
Mix.shell().info(Enum.join(values, " "))
end
defp column_widths(rows) do
%{
path: rows |> Enum.map(&String.length(&1.path)) |> Enum.max(),
raw: rows |> Enum.map(&String.length(human(&1.raw))) |> Enum.max(),
gzip: rows |> Enum.map(&String.length(human(&1.gzip))) |> Enum.max(),
brotli: rows |> Enum.map(&String.length(human(&1.brotli))) |> Enum.max()
}
end
defp pad(value, width, align \\ :left) do
value = to_string(value)
case align do
:right -> String.pad_leading(value, width)
:left -> String.pad_trailing(value, width)
end
end
defp human(nil), do: "-"
defp human(bytes) when bytes < 1024, do: "#{bytes} B"
defp human(bytes), do: "#{Float.round(bytes / 1024, 1)} KB"
end
+84
View File
@@ -0,0 +1,84 @@
defmodule Mix.Tasks.Mail.Check do
use Mix.Task
@shortdoc "Send test email through the configured mailer and SES simulators"
@moduledoc """
Sends a test message through the application mailer, applying the same house
rules as real mail: From identity, Reply-To, and the SES configuration set.
mix mail.check --to you@example.com
By default it also sends to the SES mailbox simulator addresses so bounce and
complaint wiring can be exercised without touching a real inbox:
* `success@simulator.amazonses.com`
* `bounce@simulator.amazonses.com`
* `complaint@simulator.amazonses.com`
The simulators only do something when the mailer is the SES adapter. Pass
`--no-simulators` to send only to the given address.
If `MAIL_REDIRECT_TO` is set, every recipient is rewritten to that address
first (including the simulators), so this task cannot reach users even in
production.
"""
alias Chesstrainer.Mail
@simulators [
"success@simulator.amazonses.com",
"bounce@simulator.amazonses.com",
"complaint@simulator.amazonses.com"
]
@impl true
def run(argv) do
{opts, _args} = OptionParser.parse!(argv, strict: [to: :string, simulators: :boolean])
recipient =
opts[:to] ||
Mix.raise("pass the address to check: mix mail.check --to you@example.com")
Mix.Task.run("app.start")
targets = if opts[:simulators] == false, do: [recipient], else: [recipient | @simulators]
Mix.shell().info("adapter: #{inspect(adapter())}")
if redirect(), do: Mix.shell().info("redirect: every message goes to #{redirect()}")
Enum.each(targets, &send_message/1)
end
defp send_message(recipient) do
email =
Swoosh.Email.new()
|> Swoosh.Email.to(recipient)
|> Swoosh.Email.subject("Mail check #{DateTime.utc_now() |> DateTime.to_iso8601()}")
|> Swoosh.Email.text_body(
"This is a delivery check from the chess trainer. " <>
"If you can read it, the mailer, sender identity and configuration set are wired up."
)
|> Mail.prepare()
case Chesstrainer.Mailer.deliver(email) do
{:ok, metadata} ->
Mix.shell().info("sent #{recipient} #{format_metadata(metadata)}")
{:error, reason} ->
Mix.shell().error("failed #{recipient} #{inspect(reason)}")
end
end
defp format_metadata(%{id: id}) when is_binary(id), do: "(message id #{id})"
defp format_metadata(_metadata), do: ""
defp adapter do
:chesstrainer
|> Application.get_env(Chesstrainer.Mailer, [])
|> Keyword.get(:adapter)
end
defp redirect, do: Application.get_env(:chesstrainer, :mail_redirect_to)
end