@unitninety/site-kit 0.0.0-stage → 1.6.2

package/src/languages/config.mjs

@@ -0,0 +1,53 @@
+/** A language's prefix as the platform allows one: `wire.ts`'s rule, which `config.test.ts` holds this file to. */
+const PREFIX = /^[a-z]{2,3}(-[a-z0-9]{2,8})*$/
+const isText = (value) => typeof value === 'string'
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value)
+const isPrefix = (value) => isText(value) && PREFIX.test(value)
+
+/**
+ * `/site`'s `languages` as the proxy reads them (`languagesSnapshotSchema` in `wire.ts`, which this file cannot import, as
+ * plain JS that a Next config loads): the fields the proxy reads and no others, or undefined when they would not parse.
+ * `config.test.ts` checks the two agree, case for case.
+ */
+const languagesOf = (value) => {
+  if (value === null) return null
+  if (!isRecord(value) || !isText(value.original) || !isText(value.default) || !Array.isArray(value.active) || !isRecord(value.countries)) return undefined
+  if (!value.active.every((l) => isRecord(l) && isText(l.id) && isPrefix(l.prefix) && isText(l.name))) return undefined
+  if (value.inactive !== undefined && !(Array.isArray(value.inactive) && value.inactive.every((l) => isRecord(l) && isText(l.id) && isPrefix(l.prefix)))) return undefined
+  if (!Object.values(value.countries).every(isText)) return undefined
+  return {
+    original: value.original,
+    default: value.default,
+    active: value.active.map(({ id, prefix, name }) => ({ id, prefix, name })),
+    ...(value.inactive === undefined ? {} : { inactive: value.inactive.map(({ id, prefix }) => ({ id, prefix })) }),
+    countries: { ...value.countries },
+  }
+}
+
+/**
+ * Bakes the site's languages into a build, so a fresh deploy applies them from its first request:
+ * `export default async () => withLanguagesSnapshot(await withRedirectsSnapshot(nextConfig))`, a form every config file type accepts.
+ * The languages are `/site`'s `languages`, read from the v1 read API with the site's key and handed to the proxy as
+ * `env.U90_LANGUAGES_SNAPSHOT`, as the proxy reads them (`languagesOf`). With no `PLATFORM_URL`, or a `/site` with none, the
+ * snapshot holds no languages. A platform that will not answer, takes more than 10 s, or answers languages the proxy could
+ * not read, stops the build.
+ */
+export async function withLanguagesSnapshot(config, { env = process.env, fetch: fetchImpl = globalThis.fetch } = {}) {
+  const base = env.PLATFORM_URL ? env.PLATFORM_URL.replace(/\/+$/, '') : ''
+  let snapshot = { languages: null }
+  if (base) {
+    // The timeout covers the body as well as the headers: a platform that stalls mid-reply stops the build the same way.
+    try {
+      const res = await fetchImpl(`${base}/api/u90/v1/site`, { headers: { authorization: `Bearer ${env.PAYLOAD_API_KEY ?? ''}` }, cache: 'no-store', signal: AbortSignal.timeout(10000) })
+      if (!res.ok) throw new Error(`The platform answered ${res.status} for the site's languages, so the build stops rather than deploy without them.`)
+      const reply = await res.json()
+      const languages = languagesOf(reply?.languages ?? null)
+      if (languages === undefined) throw new Error('The platform\'s languages did not parse, so the build stops rather than deploy a snapshot the proxy would throw away.')
+      snapshot = { languages }
+    } catch (err) {
+      if (err instanceof Error && err.name === 'TimeoutError') throw new Error('The platform timed out after 10 s on the site\'s languages, so the build stops rather than deploy without them.')
+      throw err
+    }
+  }
+  return { ...config, env: { ...(config.env ?? {}), U90_LANGUAGES_SNAPSHOT: JSON.stringify(snapshot) } }
+}

package/src/languages/decide.ts

@@ -0,0 +1,72 @@
+import { collapseSeparators } from '../redirects/location'
+import { DRAFT_COUNTRY_PARAM, type SiteLanguages } from './routing'
+
+/** What the proxy knows about one request. */
+export type LanguageRequest = {
+  pathname: string
+  /** The query, with its `?`, or empty. */
+  search: string
+  /** The `u90_lang` cookie's value. */
+  remembered: string | null
+  /** The host's country header's value. */
+  country: string | null
+  /** `u90-country` from the query, honoured only when `draft`. */
+  previewCountry: string | null
+  /** The request carries Next's draft-mode cookie. */
+  draft: boolean
+}
+/** A redirect, or none, and whether the answer varies on the country header. */
+export type LanguageDecision = { redirect: { status: 307 | 308; to: string } | null; vary: boolean }
+
+const PASS: LanguageDecision = { redirect: null, vary: false }
+const COUNTRY = /^[A-Z]{2}$/
+const countryOf = (value: string | null): string | null => {
+  const code = value?.trim().toUpperCase() ?? ''
+  return COUNTRY.test(code) ? code : null
+}
+/**
+ * A path's first segment as the page reads it, and the path after it. Next decodes each segment of a route with
+ * `decodeURIComponent` before the page sees it, so `/%65n/about` is `/en/about` there and `/en%2Fabout` is `/en/about` too. A
+ * segment that does not decode is kept as it is, and names no prefix. The rest stays as the request spelled it.
+ */
+const firstSegment = (pathname: string): { first: string; rest: string } => {
+  const [raw = '', ...others] = pathname.split('/').slice(1)
+  let decoded: string
+  try { decoded = decodeURIComponent(raw) } catch { return { first: raw, rest: `/${others.join('/')}` } }
+  const cut = decoded.indexOf('/')
+  if (cut === -1) return { first: decoded, rest: `/${others.join('/')}` }
+  // The raw segment holds no `/`, so its first `%2F` is the decoded segment's first `/`.
+  return { first: decoded.slice(0, cut), rest: `/${[raw.slice(raw.search(/%2F/i) + 3), ...others].join('/')}` }
+}
+const without = (search: string, name: string): string => {
+  const params = new URLSearchParams(search)
+  params.delete(name)
+  const rest = params.toString()
+  return rest ? `?${rest}` : ''
+}
+
+/**
+ * Spec §5. The default's own prefix is a 308 to the bare address, and an inactive prefix (a preparing language's included, R12)
+ * a 307 to it, so a page never answers at two addresses. Both are decided from the path alone, before the page renders, and from
+ * its first segment as the page decodes it (`firstSegment`), so an encoded prefix is redirected as the plain one is.
+ * Only `/` is ever chosen for. A public request goes to a remembered active language, else the country's rule, else stays on the
+ * default. A draft request is decided by a valid `u90-country` alone, the Canvas's country preview: the remembered choice and
+ * the editor's own country are ignored, since a Canvas screen's language is its own (R15). Every answer on `/` varies on the
+ * country header. Every run of `/` and `\` in a built path is collapsed, so no redirect can start `//host`.
+ */
+export function decideLanguage(languages: SiteLanguages | null, r: LanguageRequest): LanguageDecision {
+  if (!languages) return PASS
+  if (/^\/(?:_next|api|_u90)(?:\/|$)/.test(r.pathname)) return PASS
+  const segment = firstSegment(r.pathname)
+  const first = segment.first
+  const rest = collapseSeparators(segment.rest)
+  const fallback = languages.active.find((language) => language.id === languages.default)
+  if (first && fallback && first === fallback.prefix) return { redirect: { status: 308, to: rest + r.search }, vary: false }
+  if (first && (languages.inactive ?? []).some((language) => language.prefix === first)) return { redirect: { status: 307, to: rest + r.search }, vary: false }
+  if (r.pathname !== '/') return PASS
+  const active = (id: string | null | undefined) => (id ? languages.active.find((language) => language.id === id) : undefined)
+  const ruled = (country: string | null) => active(country ? languages.countries[country] : undefined)
+  const target = r.draft ? ruled(countryOf(r.previewCountry)) : (active(r.remembered) ?? ruled(countryOf(r.country)))
+  if (!target || target.id === languages.default) return { redirect: null, vary: true }
+  return { redirect: { status: 307, to: `/${target.prefix}${r.draft ? without(r.search, DRAFT_COUNTRY_PARAM) : r.search}` }, vary: true }
+}

package/src/languages/index.ts

@@ -0,0 +1,4 @@
+export * from './routing'
+export * from './decide'
+export * from './wire'
+export { languagesProxy } from './proxy'

package/src/languages/proxy.ts

@@ -0,0 +1,108 @@
+import { siteLocation } from '../redirects/location'
+import { decideLanguage } from './decide'
+import { COUNTRY_HEADER, DRAFT_COUNTRY_PARAM, LANGUAGE_COOKIE, type SiteLanguages } from './routing'
+import { languagesSnapshotSchema } from './wire'
+
+/** Next's draft-mode cookie. Its presence is all the proxy can see of draft mode, and all a country preview needs (R7). */
+const DRAFT_COOKIE = '__prerender_bypass'
+const cookieOf = (request: Request, name: string): string | null => {
+  for (const part of (request.headers.get('cookie') ?? '').split(';')) {
+    const at = part.indexOf('=')
+    if (at > 0 && part.slice(0, at).trim() === name) {
+      try { return decodeURIComponent(part.slice(at + 1).trim()) } catch { return null }
+    }
+  }
+  return null
+}
+
+type Options = {
+  /** The languages baked into the build (`env.U90_LANGUAGES_SNAPSHOT`), as JSON or parsed. Defaults to that variable. */
+  snapshot?: string | { languages: SiteLanguages | null } | null
+  /** Defaults to `process.env.PLATFORM_URL`. Without one the snapshot is all there is. */
+  platformUrl?: string
+  /** Defaults to `process.env.PAYLOAD_API_KEY`. */
+  apiKey?: string
+  fetch?: typeof fetch
+  now?: () => number
+  /** How long the languages stay fresh before the next request starts a refresh. Defaults to 60. */
+  refreshSeconds?: number
+  /** The request header the host puts the visitor's country in. Defaults to Vercel's (R4). */
+  countryHeader?: string
+}
+
+/**
+ * The language step of a site's `proxy.ts`, after the access gate and `redirectsProxy`:
+ * `return (await redirects(request)) ?? (await languages(request, () => NextResponse.next()))`.
+ * Languages start from the build's snapshot and refresh from `/api/u90/v1/site` without ever delaying a request; the last
+ * good ones survive a failed or malformed refresh. A site with no languages gets `next()`'s response exactly as it was.
+ * Every `Location` is made by the redirects proxy's `siteLocation`, so it is absolute and never leaves the site.
+ */
+export function languagesProxy(o: Options = {}): (request: Request, next: () => Response) => Promise<Response> {
+  const platformUrl = o.platformUrl ?? process.env.PLATFORM_URL ?? ''
+  const apiKey = o.apiKey ?? process.env.PAYLOAD_API_KEY
+  const fetchImpl = o.fetch ?? globalThis.fetch
+  const now = o.now ?? Date.now
+  const intervalMs = (o.refreshSeconds ?? 60) * 1000
+  const header = (o.countryHeader ?? COUNTRY_HEADER).toLowerCase()
+  const snapshot = o.snapshot === undefined ? process.env.U90_LANGUAGES_SNAPSHOT : o.snapshot
+
+  let languages: SiteLanguages | null = null
+  if (snapshot) {
+    try {
+      const parsed = languagesSnapshotSchema.safeParse(typeof snapshot === 'string' ? JSON.parse(snapshot) : snapshot)
+      if (parsed.success) languages = parsed.data.languages
+      else console.warn('U90_LANGUAGES_SNAPSHOT is not a valid set of languages, so the proxy starts with none until the platform answers.')
+    } catch {
+      console.warn('U90_LANGUAGES_SNAPSHOT is not readable JSON, so the proxy starts with no languages until the platform answers.')
+    }
+  }
+
+  let refreshedAt = 0
+  let inFlight = false
+  async function refresh() {
+    inFlight = true
+    refreshedAt = now()
+    try {
+      const res = await fetchImpl(`${platformUrl.replace(/\/+$/, '')}/api/u90/v1/site`, { headers: { authorization: `Bearer ${apiKey ?? ''}` }, cache: 'no-store', signal: AbortSignal.timeout(5000) })
+      if (!res.ok) { console.warn(`The platform answered ${res.status} for the site's languages, so the last good ones stay.`); return }
+      const body = (await res.json()) as { languages?: unknown } | null
+      const parsed = languagesSnapshotSchema.safeParse({ languages: body?.languages ?? null })
+      if (parsed.success) languages = parsed.data.languages
+      else console.warn('The platform\'s languages did not parse, so the last good ones stay.')
+    } catch (err) {
+      console.warn(`The site's languages could not be refreshed (${err instanceof Error ? err.message : String(err)}), so the last good ones stay.`)
+    } finally {
+      inFlight = false
+    }
+  }
+
+  let warnedUnsafe = false
+  return async (request, next) => {
+    const url = new URL(request.url)
+    if (url.pathname.startsWith('/_next/') || url.pathname.startsWith('/api/')) return next()
+    if (platformUrl && !inFlight && now() - refreshedAt >= intervalMs) void refresh()
+    const decision = decideLanguage(languages, {
+      pathname: url.pathname,
+      search: url.search,
+      remembered: cookieOf(request, LANGUAGE_COOKIE),
+      country: request.headers.get(header),
+      previewCountry: url.searchParams.get(DRAFT_COUNTRY_PARAM),
+      draft: cookieOf(request, DRAFT_COOKIE) !== null,
+    })
+    if (decision.redirect) {
+      const made = siteLocation(decision.redirect.to, url)
+      if ('location' in made && made.location.origin === url.origin) {
+        const headers = new Headers({ location: made.location.href })
+        if (decision.vary) { headers.set('cache-control', 'private, no-store'); headers.set('vary', header) }
+        return new Response(null, { status: decision.redirect.status, headers })
+      }
+      if (!warnedUnsafe) {
+        warnedUnsafe = true
+        console.warn(`A language redirect for ${url.pathname} would be under /_next/ or leave the site, so it passed through. Requests like this are not warned about again.`)
+      }
+    }
+    const response = next()
+    if (decision.vary) response.headers.append('vary', header)
+    return response
+  }
+}

package/src/languages/routing.ts

@@ -0,0 +1,93 @@
+import { prefixedRoute } from '../elements/prefix'
+import type { SiteReply } from '../site/wire'
+
+/** The languages `/site` answers for a site that has them. */
+export type SiteLanguages = NonNullable<SiteReply['languages']>
+/** The cookie the switcher sets and the proxy reads on `/`: the id of the language a visitor chose. */
+export const LANGUAGE_COOKIE = 'u90_lang'
+/** The site query parameter that previews `/` as a visitor from a country. The proxy honours it in draft mode only. */
+export const DRAFT_COUNTRY_PARAM = 'u90-country'
+/** Vercel's request header for the visitor's country, ISO 3166-1 alpha-2. Next 16 has no request geo of its own. */
+export const COUNTRY_HEADER = 'x-vercel-ip-country'
+
+/** Where an address sits: its language, the prefix it was found under (`/fr`, null for the default) and the page's path without it. */
+export type PathLanguage = { id: string; prefix: string | null; rest: string }
+
+/**
+ * The language an address is in. Null when the site has no languages, so the caller reads exactly as it did before them.
+ * An active language other than the default answers at its prefix. Every other address is the default's, the default's own
+ * prefix and an inactive prefix included: the proxy redirects those before they render, so a page never answers twice.
+ */
+export function languageOfPath(path: string, languages: SiteLanguages | null | undefined): PathLanguage | null {
+  if (!languages) return null
+  const segments = path.split('/').slice(1)
+  const first = segments[0] ?? ''
+  const found = first ? languages.active.find((language) => language.prefix === first && language.id !== languages.default) : undefined
+  return found ? { id: found.id, prefix: `/${found.prefix}`, rest: `/${segments.slice(1).join('/')}` } : { id: languages.default, prefix: null, rest: path }
+}
+
+/** The address of the page at `rest` in language `id`: the default's is `rest` itself, and an active language's carries its prefix. */
+export function addressIn(languages: SiteLanguages, id: string, rest: string): string {
+  const language = languages.active.find((candidate) => candidate.id === id)
+  return !language || id === languages.default ? rest : prefixedRoute(`/${language.prefix}`, rest)
+}
+
+/** What the switcher shows: the language the page is in, and the page's address in every active language, in the settings' order. */
+export type LanguageLinks = { current: string; links: { id: string; name: string; href: string }[] }
+export const languageLinks = (languages: SiteLanguages, rest: string, current: string): LanguageLinks => ({
+  current,
+  links: languages.active.map((language) => ({ id: language.id, name: language.name, href: addressIn(languages, language.id, rest) })),
+})
+
+/**
+ * Whether a value holds words a reader sees: some string leaf, however deep, with more than whitespace. A number, a boolean
+ * and an empty object or list are none. A rich-text node (an object with a string `type`) holds copy only in its `text` and
+ * its `children`: its `type`, `format` and a link's `fields` are the original's structure. The platform's translation health reads
+ * a value with this too, so a field is missing there exactly when it holds no copy here.
+ */
+export const holdsCopy = (value: unknown): boolean => {
+  if (typeof value === 'string') return value.trim() !== ''
+  if (Array.isArray(value)) return value.some(holdsCopy)
+  if (value === null || typeof value !== 'object') return false
+  const node = value as Record<string, unknown>
+  return typeof node.type === 'string' ? holdsCopy(node.text) || holdsCopy(node.children) : Object.values(node).some(holdsCopy)
+}
+/** Whether an overlay holds any translated copy: what makes a language's variant of a page worth indexing (ruling R2). */
+export const hasTranslatedCopy = (values: Record<string, unknown> | undefined): boolean => !!values && Object.values(values).some(holdsCopy)
+
+/** What a page's metadata says about its language: whether it is the default, its address in each listed language, the bare address for `x-default`, and whether it is offered to search. */
+export type LanguageAlternates = { id: string; isDefault: boolean; alternates: { id: string; path: string }[]; xDefault: string; indexable: boolean }
+/**
+ * A page's alternates in each language it is listed in: the default, the original, and each language in `translated` (the
+ * platform's list of languages with copy for this page). Without `translated`, every active language, as before. `indexable` is
+ * whether the page's own language is listed: an untranslated variant is served, but not offered to search (ruling R2).
+ */
+export const languageAlternates = (languages: SiteLanguages, language: PathLanguage, translated?: string[]): LanguageAlternates => {
+  const listed = (id: string) => translated === undefined || id === languages.default || id === languages.original || translated.includes(id)
+  return {
+    id: language.id,
+    isDefault: language.prefix === null,
+    alternates: languages.active.filter((l) => listed(l.id)).map((l) => ({ id: l.id, path: addressIn(languages, l.id, language.rest) })),
+    xDefault: language.rest,
+    indexable: listed(language.id),
+  }
+}
+
+/** Scripts written right to left, by their ISO 15924 code. */
+const RTL_SCRIPTS = new Set(['Adlm', 'Arab', 'Hebr', 'Mand', 'Mend', 'Nkoo', 'Rohg', 'Samr', 'Syrc', 'Thaa', 'Yezi'])
+/** Languages written right to left in their usual script, by their language subtag: read only when ICU's likely subtags give no script. */
+const RTL_LANGUAGES = new Set(['ar', 'he', 'fa', 'ur', 'yi', 'ps', 'sd', 'ug', 'dv', 'ckb'])
+/**
+ * `rtl` when the language's likely script is written right to left (`ar`, `he`, `fa`, `az-Arab`), else `ltr`. An id that does not parse is `ltr`.
+ * The script is the one ICU's likely subtags give, else the one the id names. A runtime whose ICU gives neither reads the language subtag instead.
+ */
+export function languageDirection(id: string): 'ltr' | 'rtl' {
+  try {
+    const locale = new Intl.Locale(id)
+    const script = locale.maximize().script ?? locale.script
+    if (script === undefined) return RTL_LANGUAGES.has(locale.language) ? 'rtl' : 'ltr'
+    return RTL_SCRIPTS.has(script) ? 'rtl' : 'ltr'
+  } catch {
+    return 'ltr'
+  }
+}

package/src/languages/wire.ts

@@ -0,0 +1,19 @@
+import { z } from 'zod'
+
+/**
+ * A language's prefix as the platform allows one (`PREFIX` in the platform's `src/content/languages/settings.ts`): lowercase
+ * letters, then optional `-` parts of letters and digits. An empty prefix is refused, since `/` would then be every
+ * language's address and the proxy would redirect it to itself.
+ */
+const prefix = z.string().regex(/^[a-z]{2,3}(-[a-z0-9]{2,8})*$/)
+
+/** `/site`'s `languages`, as the proxy accepts it. */
+export const siteLanguagesSchema = z.object({
+  original: z.string(),
+  default: z.string(),
+  active: z.array(z.object({ id: z.string(), prefix, name: z.string() })),
+  inactive: z.array(z.object({ id: z.string(), prefix })).optional(),
+  countries: z.record(z.string(), z.string()),
+})
+/** What `U90_LANGUAGES_SNAPSHOT` holds: the languages `/site` answered at build, or null for none. */
+export const languagesSnapshotSchema = z.object({ languages: siteLanguagesSchema.nullable() })