@unitninety/site-kit 0.0.0-stage → 1.6.1

package/src/legacy/redirects.ts

@@ -0,0 +1,474 @@
+/**
+ * URL continuity for a site that was rebuilt — the normaliser, the matcher, and the
+ * middleware that runs them on every request.
+ *
+ * **Its own entry point, and that is load-bearing.** This module is imported from a
+ * site's `src/middleware.ts`, which runs in the Edge runtime. The package's root barrel
+ * re-exports `content.ts` (which holds `PAYLOAD_API_KEY`), `richText.tsx` and
+ * `lexicalDom.ts` — so importing `@unitninety/site-kit` from middleware would drag React
+ * and the key-holding fetcher into the edge bundle. `/bridge`, `/draft` and `/shape` are
+ * split for the same reason. Import from `@unitninety/site-kit/redirects`.
+ *
+ * Nothing here imports Next, so the same code is used by the platform's own validator and
+ * CSV importer. That is deliberate: a normaliser with two implementations is a matcher
+ * that disagrees with the form that wrote the rule, and the disagreement only shows up on
+ * the URLs that needed a redirect most.
+ */
+
+/** What a rule can do when it matches. `410` means gone, and carries no destination. */
+export type RedirectStatus = 301 | 302 | 410
+
+export type RedirectMatchType = 'exact' | 'prefix' | 'pattern'
+
+/** One rule, as the platform serves it and the matcher consumes it. */
+export type RedirectRule = {
+  /** Already normalised by `normalisePath` when the platform stored it. */
+  source: string
+  /** Same-origin path, or an absolute URL for an off-site move. Empty for `410`. */
+  destination: string
+  status: RedirectStatus
+  matchType: RedirectMatchType
+  preserveQuery: boolean
+}
+
+/** What the platform's `GET /api/u90/redirects` returns, and what bakes into a snapshot. */
+export type RedirectSnapshot = {
+  rules: RedirectRule[]
+  /** When the platform generated it. Carried for diagnostics, never used for matching. */
+  generatedAt?: string
+}
+
+/**
+ * Normalise a path so both sides of a comparison agree.
+ *
+ * The order is fixed and the steps are not independent — decoding before NFC matters,
+ * because a percent-encoded `%CC%88` is a combining diaeresis that only becomes
+ * comparable once it is a character.
+ *
+ *   1. Percent-decode.
+ *   2. Unicode-normalise to NFC.
+ *   3. Strip the trailing slash, except at root.
+ *   4. Lowercase.
+ *
+ * **Why NFC is not pedantry.** `ä` has two valid encodings: precomposed `U+00E4`, or `a`
+ * followed by a combining diaeresis `U+0308`. They render identically and compare
+ * unequal. A CMS export, a browser address bar and a pasted link do not reliably agree on
+ * which they emit — so without NFC on both sides a rule for `/post/bygglov-i-järfälla`
+ * silently fails to match a request for what is visibly the same URL. It fails for exactly
+ * the migrations that need it most, because an ASCII-only site never exposes the bug.
+ *
+ * Case folding is unconditional in phase one. §11 Q2 leaves a per-tenant override open;
+ * nothing has needed it yet, and a flag nobody sets is a branch nobody tests.
+ */
+export const normalisePath = (input: string): string => {
+  let path = input
+
+  /*
+   * A malformed escape — a bare `%` or `%zz` — makes `decodeURIComponent` throw. That is a
+   * real thing to receive: old CMS exports contain them, and so do crawlers. Falling back
+   * to the raw string keeps the rule usable rather than failing the whole snapshot over one
+   * bad row.
+   */
+  try {
+    path = decodeURIComponent(path)
+  } catch {
+    // Left as-is, deliberately.
+  }
+
+  path = path.normalize('NFC')
+
+  if (path.length > 1 && path.endsWith('/')) path = path.replace(/\/+$/, '')
+  // An input of `/` or `//` collapses to nothing above; root has to stay root.
+  if (path === '') path = '/'
+
+  return path.toLowerCase()
+}
+
+/**
+ * Strip the trailing slash exactly as `normalisePath` does, and nothing else.
+ *
+ * The raw request path is what a destination is built from — see `matchRedirect` — so it has
+ * to be brought into the same *shape* as the normalised path without being decoded or
+ * lowercased, or the two cannot be walked segment by segment together.
+ */
+const trimTrailingSlash = (path: string): string => {
+  if (path.length > 1 && path.endsWith('/')) {
+    const trimmed = path.replace(/\/+$/, '')
+    return trimmed === '' ? '/' : trimmed
+  }
+  return path
+}
+
+/**
+ * Make a destination safe to put in a `Location` header.
+ *
+ * **A `Headers` value is a ByteString.** Anything above U+00FF throws outright, and so does a
+ * bare CR or LF — so a middleware that puts an un-encoded string here does not serve a bad
+ * redirect, it throws, and the whole request 500s. That turns any URL a visitor can craft into
+ * a way to take the middleware down, and it 500s genuine CJK and accented URLs as well: exactly
+ * the migrations the normaliser's NFC handling exists for.
+ *
+ * Only the bytes that cannot appear are touched. Everything printable-ASCII is left alone,
+ * `%` included, so a remainder that arrived already percent-encoded is not encoded twice.
+ * A lone surrogate — which `encodeURIComponent` refuses — is dropped rather than thrown over;
+ * it cannot have been part of a real address.
+ */
+export const encodeLocation = (destination: string): string =>
+  destination.replace(/[^\u0021-\u007E]+/gu, (run) => {
+    try {
+      return encodeURIComponent(run)
+    } catch {
+      return ''
+    }
+  })
+
+/** Split a request target into the path the matcher sees and the query it must carry. */
+export const splitQuery = (target: string): { path: string; query: string } => {
+  const mark = target.indexOf('?')
+  if (mark === -1) return { path: target, query: '' }
+  return { path: target.slice(0, mark), query: target.slice(mark) }
+}
+
+/** The `:param` and `*` segments a pattern declares, in the order they appear. */
+export const patternParams = (pattern: string): string[] => {
+  const found: string[] = []
+  for (const segment of pattern.split('/')) {
+    if (segment.startsWith(':') && segment.length > 1) found.push(segment.slice(1))
+    else if (segment === '*') found.push('*')
+  }
+  return found
+}
+
+/**
+ * Match one pattern against a normalised path, returning the captures by name.
+ *
+ * Segment-wise rather than by compiled regex: a pattern arrives from a CSV a person typed,
+ * and building a regex out of untrusted text is how a redirect table becomes a ReDoS. The
+ * segment walk has no backtracking to exploit.
+ *
+ * `*` is a trailing wildcard — it captures the rest of the path, so `/blog/*` matches
+ * `/blog/2019/some-post`. A `*` anywhere but last matches a single segment.
+ *
+ * **Matching reads the normalised path; captures come from `outputSegments`.** The two are
+ * the same string walked in step, and separating them is the whole point: normalisation is a
+ * comparison transform — it decodes and lowercases — so a capture taken from it is a decoded,
+ * case-folded string that must never be emitted. See `matchRedirect`.
+ */
+const matchPattern = (
+  pattern: string,
+  path: string,
+  outputSegments?: string[],
+): Record<string, string> | null => {
+  const patternSegments = pattern.split('/')
+  const pathSegments = path.split('/')
+  const emit = outputSegments ?? pathSegments
+  const captures: Record<string, string> = {}
+
+  for (let index = 0; index < patternSegments.length; index += 1) {
+    const expected = patternSegments[index] ?? ''
+
+    // Trailing wildcard: swallow whatever is left, including nothing.
+    if (expected === '*' && index === patternSegments.length - 1) {
+      captures['*'] = emit.slice(index).join('/')
+      return captures
+    }
+
+    const actual = pathSegments[index]
+    if (actual === undefined) return null
+
+    if (expected.startsWith(':') && expected.length > 1) {
+      // A named param never matches an empty segment — `/post/` must not satisfy
+      // `/post/:slug` and redirect to a destination with a hole in it.
+      if (actual === '') return null
+      captures[expected.slice(1)] = emit[index] ?? actual
+      continue
+    }
+
+    if (expected === '*') {
+      if (actual === '') return null
+      captures['*'] = emit[index] ?? actual
+      continue
+    }
+
+    if (expected !== actual) return null
+  }
+
+  // Anything left over means the path was longer than the pattern, and a pattern with no
+  // trailing wildcard does not match a deeper path.
+  return pathSegments.length === patternSegments.length ? captures : null
+}
+
+/** Substitute a pattern rule's captures into its destination. */
+export const applyCaptures = (destination: string, captures: Record<string, string>): string =>
+  destination
+    .split('/')
+    .map((segment) => {
+      if (segment === '*') return captures['*'] ?? ''
+      if (segment.startsWith(':') && segment.length > 1) {
+        return captures[segment.slice(1)] ?? segment
+      }
+      return segment
+    })
+    .join('/')
+
+/** What the matcher decided. `null` from `matchRedirect` means no rule applied. */
+export type RedirectMatch = {
+  destination: string
+  status: RedirectStatus
+  /** The rule that won, for logging and for the dashboard's "which rule fired" answer. */
+  rule: RedirectRule
+}
+
+/**
+ * A compiled rule set. Built once per snapshot, not per request.
+ *
+ * The exact map is what makes a 270-rule table free at the edge; the prefix list is sorted
+ * longest-first at compile time so `/blog/archive` beats `/blog` without the author having
+ * to think about ordering.
+ */
+export type CompiledRedirects = {
+  exact: Map<string, RedirectRule>
+  prefix: RedirectRule[]
+  pattern: RedirectRule[]
+}
+
+export const compileRedirects = (rules: RedirectRule[]): CompiledRedirects => {
+  const exact = new Map<string, RedirectRule>()
+  const prefix: RedirectRule[] = []
+  const pattern: RedirectRule[] = []
+
+  for (const rule of rules) {
+    // Normalised again here rather than trusted: a snapshot baked at build time may predate
+    // a change to this function, and a rule the matcher can never reach is worse than a
+    // cheap second pass over a few hundred strings.
+    const normalised: RedirectRule = { ...rule, source: normalisePath(rule.source) }
+    if (normalised.matchType === 'exact') exact.set(normalised.source, normalised)
+    else if (normalised.matchType === 'prefix') prefix.push(normalised)
+    else pattern.push(normalised)
+  }
+
+  // Longest source first. Ties broken by string order so the result is deterministic
+  // across snapshots — a matcher that depends on database row order is one that changes
+  // behaviour when somebody edits an unrelated rule.
+  prefix.sort((a, b) => b.source.length - a.source.length || a.source.localeCompare(b.source))
+  pattern.sort(
+    (a, b) =>
+      patternParams(a.source).length - patternParams(b.source).length ||
+      b.source.length - a.source.length ||
+      a.source.localeCompare(b.source),
+  )
+
+  return { exact, prefix, pattern }
+}
+
+/**
+ * Resolve one request target against a compiled rule set. First match wins.
+ *
+ * Exact before prefix before pattern is what lets a single `/post/:slug` rule cover 226
+ * URLs while a handful of exact rules carve out the exceptions — the author writes the
+ * general rule and the specific ones, and never reasons about which is checked first.
+ */
+export const matchRedirect = (
+  compiled: CompiledRedirects,
+  target: string,
+): RedirectMatch | null => {
+  const { path, query } = splitQuery(target)
+  const normalised = normalisePath(path)
+
+  /*
+   * **Matching uses the normalised path; the destination is built from the raw one.**
+   *
+   * `normalisePath` percent-decodes and lowercases, which is exactly right for deciding
+   * whether a rule applies and exactly wrong for producing an address. Taken as output it
+   * gives `/blog/%E6%97%A5%E6%9C%AC` back as literal CJK — which a `Location` header cannot
+   * hold at all — turns `%0D%0A` into a real CRLF, and folds `/News/Q3` to `/news/q3` on a
+   * case-sensitive route. The first two throw inside `new Response`, so any visitor could
+   * 500 the middleware on any prefix or pattern rule with a crafted URL.
+   *
+   * So the raw path is walked alongside the normalised one, trailing slash trimmed the same
+   * way so the two agree segment for segment. They only disagree when decoding introduces a
+   * separator — an encoded `%2F` — and then the raw side is abandoned for the normalised one
+   * rather than mis-aligned: `encodeLocation` below still makes that safe to emit.
+   */
+  const rawSegments = trimTrailingSlash(path).split('/')
+  const normalisedSegments = normalised.split('/')
+  const outputSegments =
+    rawSegments.length === normalisedSegments.length ? rawSegments : normalisedSegments
+
+  const carry = (rule: RedirectRule, destination: string): RedirectMatch => {
+    if (rule.status === 410) return { destination: '', status: 410, rule }
+    /*
+     * The query is re-appended unless the rule opted out. A destination that carries its
+     * own query wins the `?` and the request's own params are dropped — merging two query
+     * strings produces duplicate keys whose precedence is framework-specific, which is a
+     * worse outcome than the rule author's explicit choice.
+     */
+    const withQuery =
+      rule.preserveQuery && query && !destination.includes('?') ? destination + query : destination
+    /*
+     * Encoded last, once, over everything — the rule's own stored destination included. A
+     * destination is stored through `normalisePath` too, so `/nyheter/japan` spelled in
+     * Japanese reaches here decoded and would throw just as a capture would.
+     */
+    return { destination: encodeLocation(withQuery), status: rule.status, rule }
+  }
+
+  const exact = compiled.exact.get(normalised)
+  if (exact) return carry(exact, exact.destination)
+
+  for (const rule of compiled.prefix) {
+    // A prefix must end at a segment boundary: `/blog` must not swallow `/blogroll`.
+    if (normalised === rule.source || normalised.startsWith(`${rule.source}/`)) {
+      // Counted in segments rather than sliced by character length, because the raw path and
+      // the normalised one share a segment count but not a length.
+      const consumed = rule.source.split('/').length
+      const rest =
+        outputSegments.length > consumed ? `/${outputSegments.slice(consumed).join('/')}` : ''
+      const destination =
+        rule.destination.endsWith('/') && rest.startsWith('/')
+          ? rule.destination.slice(0, -1) + rest
+          : rule.destination + rest
+      return carry(rule, destination)
+    }
+  }
+
+  for (const rule of compiled.pattern) {
+    const captures = matchPattern(rule.source, normalised, outputSegments)
+    if (captures) return carry(rule, applyCaptures(rule.destination, captures))
+  }
+
+  return null
+}
+
+/**
+ * The default matcher config for a site's `src/middleware.ts`.
+ *
+ * Exported as a constant so a site's `export const config` and this module's own guard
+ * cannot drift apart. Middleware that runs on `/_next/static/*` adds latency to every
+ * asset on every page and can never usefully redirect one.
+ */
+export const REDIRECT_MATCHER = '/((?!_next/|api/|.*\\.[a-zA-Z0-9]+$).*)'
+
+/** Belt-and-braces for the matcher above — Next's config is declarative and easy to edit out. */
+const isExcluded = (pathname: string): boolean =>
+  pathname.startsWith('/_next/') || pathname.startsWith('/api/') || /\.[a-zA-Z0-9]+$/.test(pathname)
+
+type MinimalRequest = { url: string; nextUrl?: { pathname: string; search: string } }
+type MinimalResponse = Response | undefined
+
+/**
+ * `src/middleware.ts` — redirect a request before it reaches routing.
+ *
+ *   import { createRedirectMiddleware } from '@unitninety/site-kit/redirects'
+ *   import snapshot from './redirects.generated.json'
+ *
+ *   export const middleware = createRedirectMiddleware({ snapshot })
+ *   export const config = { matcher: [REDIRECT_MATCHER] }
+ *
+ * **Baked floor, refreshed in the background.** The snapshot compiles into the bundle, so
+ * the first request of a cold isolate is already correct and never blocks on the network.
+ * A module-scope cache then refreshes on a TTL, so a rule added in the dashboard is live
+ * within a minute with no deploy.
+ *
+ * **The TTL is the freshness mechanism, and the cache tag is not.** Next's Data Cache is
+ * not applied to `fetch` inside middleware, and the site's `/api/revalidate` handler runs
+ * in a different isolate from this one — so `revalidateTag('redirects')` cannot clear what
+ * is cached here. The platform still tags and pings, because that is correct the moment
+ * anything outside middleware reads the snapshot, but nothing in this file depends on it.
+ *
+ * **A failed refresh keeps serving the last good set.** Never falling through to no
+ * redirects is the whole point: a transient platform blip would otherwise 404 the entire
+ * migrated URL surface for as long as it lasted, which is the exact failure this feature
+ * exists to prevent.
+ */
+export const createRedirectMiddleware = ({
+  apiKey = process.env.PAYLOAD_API_KEY,
+  fetchImpl = globalThis.fetch,
+  now = () => Date.now(),
+  platformUrl = process.env.PLATFORM_URL,
+  snapshot,
+  ttlSeconds = 60,
+}: {
+  apiKey?: string
+  /** Injected for tests. Defaults to the platform fetch. */
+  fetchImpl?: typeof globalThis.fetch
+  now?: () => number
+  platformUrl?: string
+  /** The build-time snapshot. This is the floor the site never drops below. */
+  snapshot: RedirectSnapshot
+  ttlSeconds?: number
+}) => {
+  /*
+   * Module scope, so it survives between requests on a warm isolate and costs one compile
+   * per refresh rather than one per request. A cold isolate starts from the baked snapshot,
+   * which is why the site is correct before the first fetch ever completes.
+   */
+  let compiled = compileRedirects(snapshot.rules ?? [])
+  let refreshedAt = 0
+  let inFlight: Promise<void> | null = null
+
+  const refresh = async (): Promise<void> => {
+    if (!platformUrl || !apiKey || !fetchImpl) return
+    try {
+      const response = await fetchImpl(`${platformUrl.replace(/\/$/, '')}/api/u90/redirects`, {
+        headers: { Authorization: `users API-Key ${apiKey}` },
+        // Tagged for the sake of any non-middleware caller; see the docblock on why the
+        // TTL above is what actually keeps this fresh.
+        ...({ next: { tags: ['redirects'] } } as Record<string, unknown>),
+      })
+      if (!response.ok) return
+      const body = (await response.json()) as RedirectSnapshot
+      if (!Array.isArray(body?.rules)) return
+      compiled = compileRedirects(body.rules)
+      refreshedAt = now()
+    } catch {
+      /*
+       * Swallowed, and `refreshedAt` deliberately left alone so the next request retries
+       * rather than waiting out another full TTL. `compiled` still holds the last good set.
+       */
+    }
+  }
+
+  return async function middleware(request: MinimalRequest): Promise<MinimalResponse> {
+    const url = request.nextUrl
+      ? { pathname: request.nextUrl.pathname, search: request.nextUrl.search }
+      : (() => {
+          const parsed = new URL(request.url)
+          return { pathname: parsed.pathname, search: parsed.search }
+        })()
+
+    if (isExcluded(url.pathname)) return undefined
+
+    /*
+     * Refreshed without awaiting when the set is merely stale, so a visitor never pays for
+     * the platform round trip — they get the last good answer and the next visitor gets the
+     * new one. `inFlight` collapses the stampede a burst of traffic would otherwise cause
+     * against a cold cache.
+     */
+    if (now() - refreshedAt > ttlSeconds * 1000 && !inFlight) {
+      inFlight = refresh().finally(() => {
+        inFlight = null
+      })
+    }
+
+    const match = matchRedirect(compiled, url.pathname + url.search)
+    if (!match) return undefined
+
+    if (match.status === 410) {
+      /*
+       * A body, because a bare 410 renders as the browser's own error page. The status code
+       * is what search engines act on; §11 Q4 leaves a designed page open, and this is the
+       * honest minimum until it is answered.
+       */
+      return new Response('Gone', {
+        status: 410,
+        headers: { 'content-type': 'text/plain; charset=utf-8' },
+      })
+    }
+
+    return new Response(null, {
+      status: match.status,
+      headers: { location: match.destination },
+    })
+  }
+}

package/src/legacy/richText.tsx

@@ -0,0 +1,104 @@
+import React from 'react'
+
+import { FORMAT, type RichTextValue } from './lexical'
+
+/**
+ * A stored rich text document, as elements.
+ *
+ * The piece that was missing, and the reason `pageBody.body` is a textarea and the legal pages
+ * were twelve sections: until this existed a site could declare a `richText` field and had no
+ * way to draw one.
+ *
+ * **Unknown node types render their children.** A document authored by an editor that knows a
+ * node this reader does not must still read as prose. Rendering nothing would turn a client's
+ * published privacy policy into a blank page the first time the vocabulary grew, which is a
+ * worse outcome than an unstyled paragraph by any measure that matters.
+ *
+ * **The mark order is fixed and load-bearing.** `strong > em > s > u > code`, always, so the
+ * same bitfield always produces the same DOM — `lexicalDom.ts` inverts this exact nesting.
+ */
+
+/** Outermost first. `lexicalDom.ts` unwraps in this order; the two must not drift. */
+const MARKS: [number, keyof React.JSX.IntrinsicElements][] = [
+  [FORMAT.bold, 'strong'],
+  [FORMAT.italic, 'em'],
+  [FORMAT.strikethrough, 's'],
+  [FORMAT.underline, 'u'],
+  [FORMAT.code, 'code'],
+]
+
+type Node = Record<string, unknown>
+
+const children = (node: Node, key: string): React.ReactNode => {
+  const list = Array.isArray(node.children) ? (node.children as Node[]) : []
+  return list.map((child, index) => draw(child, `${key}.${index}`))
+}
+
+const draw = (node: Node, key: string): React.ReactNode => {
+  if (!node || typeof node !== 'object') return null
+
+  switch (node.type) {
+    case 'text': {
+      const format = typeof node.format === 'number' ? node.format : 0
+      // reduceRight: MARKS is outermost-first, so the last one applied (bold) must be the
+      // *first* processed if we walked left-to-right, or — equivalently and simpler — the
+      // *last* processed walking right-to-left, so it ends up as the outermost wrap.
+      return MARKS.reduceRight<React.ReactNode>(
+        (inner, [bit, Tag]) =>
+          format & bit ? React.createElement(Tag, { key }, inner) : inner,
+        typeof node.singleKey === 'string'
+          ? <span data-single-key={node.singleKey} contentEditable={false}>{String(node.text ?? '')}</span>
+          : String(node.text ?? ''),
+      )
+    }
+    case 'linebreak':
+      return <br key={key} />
+    case 'link': {
+      const url = (node.fields as { url?: unknown } | undefined)?.url
+      return (
+        <a href={typeof url === 'string' ? url : '#'} key={key}>
+          {children(node, key)}
+        </a>
+      )
+    }
+    case 'paragraph':
+      return <p key={key}>{children(node, key)}</p>
+    case 'heading':
+      /*
+       * `h1` is offered because a client asked for it. The page's own title is a separate
+       * element outside this field, so a document that opens with its own h1 is now the
+       * client's call rather than the platform's.
+       */
+      if (node.tag === 'h1') return <h1 key={key}>{children(node, key)}</h1>
+      if (node.tag === 'h3') return <h3 key={key}>{children(node, key)}</h3>
+      return <h2 key={key}>{children(node, key)}</h2>
+    case 'list':
+      return node.listType === 'number' ? (
+        <ol key={key}>{children(node, key)}</ol>
+      ) : (
+        <ul key={key}>{children(node, key)}</ul>
+      )
+    case 'listitem':
+      return <li key={key}>{children(node, key)}</li>
+    default:
+      // See the note above: prose, never a blank page.
+      return <React.Fragment key={key}>{children(node, key)}</React.Fragment>
+  }
+}
+
+export const RichText = ({
+  className,
+  value,
+}: {
+  className?: string
+  value: unknown
+}): React.ReactElement | null => {
+  const root = (value as RichTextValue | null)?.root
+  if (!root || !Array.isArray(root.children)) return null
+
+  const body = (root.children as unknown as Node[]).map((node, index) =>
+    draw(node, String(index)),
+  )
+
+  return className ? <div className={className}>{body}</div> : <>{body}</>
+}