v4: what the server and the client both state is declared once — several rules were written out in two or more files, some already drifting apart. A link's site name (its host without www.) was computed in five places, now shared/url.ts's siteHost; dumpFileVersion, which the frontend and the server had to keep equal by hand, is one function in shared/dump.ts; the Markdown flattening of the chat's reply previews and the digest's quotes is shared/markdown.ts's markdownToPlainText, so the digest also keeps an image's alt text; an attachment's URL and how to find one in a text are shared/attachment.ts, which the editor, Markdown and attachment-service read, its id pattern the new UUID_RE that the file and thumbnail routes check ids with. On the server, the Bandcamp, YouTube playlist and link preview caches use one TtlCache (api/lib/ttl-cache.ts) instead of three copies of the same expiry and eviction; the link previews' theme-color and the emails' theme tokens read colours with one parser (api/lib/css-color.ts), and a transparent theme-color now gives no tint; the WebSocket route sends through ws-service's send, the welcome included, so it is type-checked; fetch.ts strips an IPv6 literal's brackets with public-address's bareHostname; and a category's slug is checked by the same validateSlug as a dump's, with its own length. The migrations keep their frozen copies, as they document. 272 backend tests and 677 frontend tests pass, and deno check, tsc, eslint and doc:lint are clean.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

api/remote/bandcamp-streams.ts

@@ -9,19 +9,16 @@
  */
 
 import { APIException } from "../lib/api-exception.ts";
+import { TtlCache } from "../lib/ttl-cache.ts";
 import { fetchWithTimeout, isValidHttpUrl, readTextCapped } from "./fetch.ts";
 import { BANDCAMP_HOST_RE, parseTralbum } from "./bandcamp-tralbum.ts";
 import type { Tralbum } from "../../shared/player.ts";
 
 /**
- * Half the signatures' life, so a cached URL still has at least 12 hours left
- * when it is handed out.
+ * Lives half the signatures' life, so a cached URL still has at least 12
+ * hours left when it is handed out.
  */
-const TTL_MS = 12 * 60 * 60 * 1000;
-/** The oldest write goes first. */
-const MAX_ENTRIES = 200;
-
-const cache = new Map<string, Tralbum>();
+const cache = new TtlCache<Tralbum>(12 * 3_600_000, 200);
 
 /**
  * Returns `url` without its query, fragment and trailing slashes, and with its
@@ -38,25 +35,6 @@ function cacheKey(url: string): string {
   }
 }
 
-function readCache(key: string): Tralbum | null {
-  const hit = cache.get(key);
-  if (!hit) return null;
-  if (Date.now() - hit.resolvedAt > TTL_MS) {
-    cache.delete(key);
-    return null;
-  }
-  return hit;
-}
-
-function writeCache(key: string, value: Tralbum): void {
-  // Map preserves insertion order, so the first key is the oldest write.
-  if (cache.size >= MAX_ENTRIES) {
-    const oldest = cache.keys().next().value;
-    if (oldest !== undefined) cache.delete(oldest);
-  }
-  cache.set(key, value);
-}
-
 /**
  * Returns the tracklist of the Bandcamp page `pageUrl`, from the cache when it
  * was resolved in the last 12 hours. `force` skips the cache: the player sets
@@ -87,7 +65,7 @@ export async function resolveBandcamp(
 
   const key = cacheKey(pageUrl);
   if (!force) {
-    const hit = readCache(key);
+    const hit = cache.get(key);
     if (hit) return hit;
   }
 
@@ -115,6 +93,5 @@ export async function resolveBandcamp(
     throw new APIException(404, "No streamable tracks on this page");
   }
 
-  writeCache(key, parsed);
-  return parsed;
+  return cache.set(key, parsed);
 }

api/remote/fetch.ts

@@ -7,7 +7,11 @@
  * @module
  */
 
-import { isPrivateHostname, resolvePublicAddress } from "./public-address.ts";
+import {
+  bareHostname,
+  isPrivateHostname,
+  resolvePublicAddress,
+} from "./public-address.ts";
 import { isSelfUrl } from "../lib/self-url.ts";
 
 const FETCH_HEADERS = {
@@ -43,7 +47,7 @@ async function fetchViaCurl(
         "--proto",
         "=http,https",
         "--resolve",
-        `${url.hostname.replace(/^\[(.*)\]$/, "$1")}:${port}:${pinned}`,
+        `${bareHostname(url)}:${port}:${pinned}`,
         "--max-time",
         String(Math.ceil(timeoutMs / 1000)),
         // curl fails on a larger file rather than stopping at a cap, so this is

api/remote/html.ts

@@ -7,6 +7,8 @@
  * @module
  */
 
+import { hexOf, parseCssColor } from "../lib/css-color.ts";
+
 /**
  * Decodes the five XML entities and numeric ones in `str`. `&` goes first,
  * so `"` decodes twice; `bandcamp-tralbum.ts`, which decodes JSON,
@@ -118,74 +120,15 @@ export function extractMaskIconColor(html: string): string | undefined {
   return undefined;
 }
 
-/**
- * The named colors sites actually put in `theme-color`; the rest of CSS's names
- * aren't worth carrying.
- */
-const NAMED_COLORS: Record<string, string> = {
-  black: "#000000",
-  white: "#ffffff",
-  red: "#ff0000",
-  green: "#008000",
-  blue: "#0000ff",
-  yellow: "#ffff00",
-  orange: "#ffa500",
-  purple: "#800080",
-  gray: "#808080",
-  grey: "#808080",
-  silver: "#c0c0c0",
-  maroon: "#800000",
-  navy: "#000080",
-  teal: "#008080",
-  olive: "#808000",
-  lime: "#00ff00",
-  aqua: "#00ffff",
-  cyan: "#00ffff",
-  fuchsia: "#ff00ff",
-  magenta: "#ff00ff",
-};
-
-function clampByte(n: number): number {
-  return Math.max(0, Math.min(255, Math.round(n)));
-}
-
 /**
  * Returns `raw` as a lowercase `#rrggbb`, from a hex, `rgb()`, `rgba()` or
  * common named color; undefined for any other form. The generic provider
  * stores it as the preview's `accentColor`, a tint over the app's own surface,
- * so alpha is dropped.
+ * so alpha is dropped, and a fully transparent one is no color at all.
  */
 export function normalizeCssColor(raw: string | undefined): string | undefined {
-  if (!raw) return undefined;
-  const value = raw.trim().toLowerCase();
-
-  const named = NAMED_COLORS[value];
-  if (named) return named;
-
-  const hex = /^#([0-9a-f]{3,8})$/.exec(value)?.[1];
-  if (hex) {
-    if (hex.length === 3 || hex.length === 4) {
-      const [r, g, b] = [...hex.slice(0, 3)];
-      return `#${r}${r}${g}${g}${b}${b}`;
-    }
-    if (hex.length === 6 || hex.length === 8) return `#${hex.slice(0, 6)}`;
-    return undefined;
-  }
-
-  const rgb = /^rgba?\(([^)]+)\)$/.exec(value)?.[1];
-  if (rgb) {
-    const parts = rgb.split(/[\s,/]+/).filter(Boolean).slice(0, 3);
-    if (parts.length !== 3) return undefined;
-    const bytes = parts.map((p) => {
-      const n = parseFloat(p);
-      if (!Number.isFinite(n)) return NaN;
-      return clampByte(p.endsWith("%") ? (n / 100) * 255 : n);
-    });
-    if (bytes.some(Number.isNaN)) return undefined;
-    return `#${bytes.map((b) => b.toString(16).padStart(2, "0")).join("")}`;
-  }
-
-  return undefined;
+  const color = raw ? parseCssColor(raw) : undefined;
+  return color && color.a > 0 ? hexOf(color) : undefined;
 }
 
 /**

api/remote/providers/generic.ts

@@ -7,6 +7,7 @@
 
 import type { RichContent } from "../../../shared/dump.ts";
 import type { RichContentProvider } from "./provider.ts";
+import { siteHost } from "../../../shared/url.ts";
 import {
   extractBestIcon,
   extractFirstContentImage,
@@ -66,7 +67,7 @@ export const genericProvider: RichContentProvider = {
       extractPageTitle(html);
 
     const siteName = extractOgTag(html, "site_name") ??
-      new URL(url).hostname.replace(/^www\./, "");
+      siteHost(url);
 
     const description = extractOgTag(html, "description") ??
       extractMetaName(html, "twitter:description") ??

api/remote/providers/youtube.ts

@@ -11,12 +11,13 @@ import type { RichContentProvider } from "./provider.ts";
 import { extractOgTag } from "../html.ts";
 import { fetchWithTimeout, readTextCapped } from "../fetch.ts";
 import { youtubeHost, youtubeVideoId } from "../../lib/canonical-url.ts";
+import { siteHostOf } from "../../../shared/url.ts";
 
 /** Returns the id of the video `url` points at, in any shape YouTube uses. */
 function extractVideoId(url: string): string | null {
   try {
     const u = new URL(url);
-    const host = u.hostname.toLowerCase().replace(/^www\./, "");
+    const host = siteHostOf(u);
     return youtubeVideoId(host, u.pathname, u.searchParams);
   } catch {
     return null;

api/remote/public-address.ts

@@ -100,9 +100,10 @@ function isIpLiteral(host: string): boolean {
 
 /**
  * Returns `url`'s hostname without the brackets `URL.hostname` keeps around
- * an IPv6 literal.
+ * an IPv6 literal: the address checks here read it, and `fetch.ts` hands it
+ * to curl's `--resolve`.
  */
-function bareHostname(url: URL): string {
+export function bareHostname(url: URL): string {
   return url.hostname.replace(/^\[(.*)\]$/, "$1");
 }
 

api/remote/youtube-playlist.ts

@@ -13,6 +13,7 @@
  */
 
 import { APIException } from "../lib/api-exception.ts";
+import { TtlCache } from "../lib/ttl-cache.ts";
 import { readTextCapped } from "./fetch.ts";
 import type {
   YouTubePlaylist,
@@ -20,11 +21,7 @@ import type {
 } from "../../shared/player.ts";
 
 /** Titles and lengths rarely change, and a stale one only mislabels a row. */
-const TTL_MS = 6 * 60 * 60 * 1000;
-/** The oldest write goes first. */
-const MAX_ENTRIES = 200;
-
-const cache = new Map<string, { value: YouTubePlaylist; at: number }>();
+const cache = new TtlCache<YouTubePlaylist>(6 * 3_600_000, 200);
 
 /**
  * Admits every kind of list id (`PL…`, `OLAK5uy_…`, `RD…`) and nothing else.
@@ -167,8 +164,7 @@ export async function resolveYouTubePlaylist(
   }
 
   const hit = cache.get(listId);
-  if (hit && Date.now() - hit.at < TTL_MS) return hit.value;
-  if (hit) cache.delete(listId);
+  if (hit) return hit;
 
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), 8000);
@@ -198,10 +194,5 @@ export async function resolveYouTubePlaylist(
     throw new APIException(404, "No tracks on this playlist");
   }
 
-  if (cache.size >= MAX_ENTRIES) {
-    const oldest = cache.keys().next().value;
-    if (oldest !== undefined) cache.delete(oldest);
-  }
-  cache.set(listId, { value: parsed, at: Date.now() });
-  return parsed;
+  return cache.set(listId, parsed);
 }