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/lib/canonical-url.ts

@@ -13,6 +13,8 @@
  * @module
  */
 
+import { siteHostOf } from "../../shared/url.ts";
+
 const TRACKING_PARAMS = new Set([
   "fbclid",
   "gclid",
@@ -52,7 +54,7 @@ const YOUTUBE_HOSTS = new Set([
  * uses it too, so both agree on what a YouTube link is.
  */
 export function youtubeHost(u: URL): string | null {
-  const host = u.hostname.toLowerCase().replace(/^www\./, "");
+  const host = siteHostOf(u);
   return YOUTUBE_HOSTS.has(host) ? host : null;
 }
 
@@ -90,7 +92,7 @@ export function canonicalizeUrl(raw: string): string | null {
   }
   if (u.protocol !== "http:" && u.protocol !== "https:") return null;
 
-  const host = u.hostname.toLowerCase().replace(/^www\./, "");
+  const host = siteHostOf(u);
   if (!host) return null;
 
   const videoId = youtubeVideoId(host, u.pathname, u.searchParams);

api/lib/css-color.ts

@@ -0,0 +1,91 @@
+/**
+ * Reads the CSS colors the server meets: a dumped page's `theme-color`, which
+ * the generic link preview keeps as its tint (`normalizeCssColor`), and the
+ * theme stylesheets' tokens, which the emails resolve (`theme-tokens.ts`).
+ *
+ * @module
+ */
+
+/** An sRGB color with its alpha, each channel 0–255 and alpha 0–1. */
+export interface Rgba {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+
+/**
+ * The named colors sites actually put in `theme-color`, and `transparent`,
+ * which the themes write; the rest of CSS's names aren't worth carrying.
+ */
+const NAMED: Record<string, string> = {
+  transparent: "#00000000",
+  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",
+};
+
+/** Reads a channel of `rgb()`, a number or a percentage of 255. */
+function channel(text: string): number {
+  const n = parseFloat(text);
+  const value = text.endsWith("%") ? (n / 100) * 255 : n;
+  return Math.max(0, Math.min(255, value));
+}
+
+/** Reads the alpha of `rgba()`, a number or a percentage of 1. */
+function alpha(text: string): number {
+  const n = parseFloat(text);
+  return Math.max(0, Math.min(1, text.endsWith("%") ? n / 100 : n));
+}
+
+/**
+ * Returns the color `text` writes as a hex (3, 4, 6 or 8 digits), an `rgb()`
+ * or `rgba()` of numbers or percentages, or one of the common names; undefined
+ * for any other form. Channels out of range are clamped.
+ */
+export function parseCssColor(text: string): Rgba | undefined {
+  const value = text.trim().toLowerCase();
+  const hex = /^#([0-9a-f]{3,8})$/.exec(NAMED[value] ?? value)?.[1];
+  if (hex) {
+    if (hex.length === 5 || hex.length === 7) return undefined;
+    const full = hex.length <= 4 ? [...hex].map((c) => c + c).join("") : hex;
+    const byte = (i: number) => parseInt(full.slice(i * 2, i * 2 + 2), 16);
+    return {
+      r: byte(0),
+      g: byte(1),
+      b: byte(2),
+      a: full.length === 8 ? byte(3) / 255 : 1,
+    };
+  }
+  const args = /^rgba?\(([^)]+)\)$/.exec(value)?.[1];
+  if (!args) return undefined;
+  const parts = args.split(/[\s,/]+/).filter(Boolean);
+  if (parts.length !== 3 && parts.length !== 4) return undefined;
+  const [r, g, b] = parts.slice(0, 3).map(channel);
+  const a = parts[3] === undefined ? 1 : alpha(parts[3]);
+  return [r, g, b, a].some(Number.isNaN) ? undefined : { r, g, b, a };
+}
+
+/** Writes `color` as a lowercase `#rrggbb`, its alpha dropped. */
+export function hexOf({ r, g, b }: Rgba): string {
+  return `#${
+    [r, g, b].map((c) => Math.round(c).toString(16).padStart(2, "0")).join("")
+  }`;
+}

api/lib/slugify.ts

@@ -72,14 +72,15 @@ export function uniqueSlug(
 
 /**
  * Throws a 400 unless `slug` is a valid slug, lowercase words of letters and
- * digits joined by hyphens, at most `SLUG_MAX` long. Dump and playlist slugs
- * reserve no word: nothing else a user names lives beside them.
+ * digits joined by hyphens, at most `max` long. slug-service checks a dump's
+ * or a playlist's with it, and category-service a category's, with that
+ * kind's own limit.
  */
-export function validateSlug(slug: string): void {
-  if (!isValidSlug(slug)) {
+export function validateSlug(slug: string, max: number = SLUG_MAX): void {
+  if (!isValidSlug(slug, max)) {
     throw new APIException(
       400,
-      `Slug must be lowercase letters, numbers and hyphens, at most ${SLUG_MAX} characters`,
+      `Slug must be lowercase letters, numbers and hyphens, at most ${max} characters`,
     );
   }
 }

api/lib/ttl-cache.ts

@@ -0,0 +1,60 @@
+/**
+ * Keeps what the server fetched from another site for a while, by key, so a
+ * page or a feed asking again doesn't refetch it: Bandcamp tracklists, YouTube
+ * playlists, and link previews. Each holder sets how long an entry lives and
+ * how many are kept; past that count, the oldest written goes first.
+ *
+ * @module
+ */
+
+/**
+ * A map whose entries expire `ttlMs` after they are written, holding
+ * `maxEntries` at most.
+ *
+ * @example
+ * const playlists = new TtlCache<YouTubePlaylist>(6 * 3_600_000, 200);
+ * const hit = playlists.get(listId) ?? playlists.set(listId, await fetch());
+ */
+export class TtlCache<V> {
+  #entries = new Map<string, { value: V; at: number }>();
+
+  constructor(readonly ttlMs: number, readonly maxEntries: number) {}
+
+  /** Returns the value under `key` unless it is missing or expired. */
+  get(key: string): V | undefined {
+    const hit = this.#entries.get(key);
+    if (!hit) return undefined;
+    if (Date.now() - hit.at >= this.ttlMs) {
+      this.#entries.delete(key);
+      return undefined;
+    }
+    return hit.value;
+  }
+
+  /** Stores `value` under `key` from now on, and returns it. */
+  set(key: string, value: V): V {
+    this.#entries.delete(key);
+    // A Map keeps insertion order, so the first key is the oldest write.
+    if (this.#entries.size >= this.maxEntries) {
+      const oldest = this.#entries.keys().next().value;
+      if (oldest !== undefined) this.#entries.delete(oldest);
+    }
+    this.#entries.set(key, { value, at: Date.now() });
+    return value;
+  }
+
+  /**
+   * Removes `key`, or only when `value` is still what it holds, so a late
+   * failure can't remove the entry that replaced its own.
+   */
+  delete(key: string, value?: V): void {
+    if (value === undefined || this.#entries.get(key)?.value === value) {
+      this.#entries.delete(key);
+    }
+  }
+
+  /** Empties the cache, for the tests' reset between cases. */
+  clear(): void {
+    this.#entries.clear();
+  }
+}