@bygghammar/cms-platform 0.80.1 → 0.90.0-m7.10

package/src/site/locale-domains.ts

@@ -0,0 +1,500 @@
+/**
+ * Locale → domain mapping, as pure routing logic.
+ *
+ * Request matching, the public projection and the "which hostname serves the
+ * backoffice" question all live here rather than next to the database calls,
+ * because the backoffice screen needs the same answers as the server and must
+ * not pull server-only modules into the browser bundle to get them.
+ *
+ * Pure module — no database, no environment, no network.
+ */
+
+import {
+  canonicalDomainProblemMessage,
+  domainOrigin,
+  hostMatchKey,
+  hostsMatch,
+  isLoopbackHost,
+  isValidCanonicalDomain,
+  normalizeCanonicalDomain,
+  parseCanonicalDomain,
+} from "./host";
+
+export type LocaleDomainRecord = {
+  locale: string;
+  domain: string;
+  isDefault: boolean;
+  isAdminDomain: boolean;
+};
+
+/**
+ * What public routing and SEO are allowed to see.
+ *
+ * `isAdminDomain` names the hostname that serves the backoffice. Nothing on
+ * the public site needs it, and the migration that revoked anonymous reads of
+ * `locale_domains` exists precisely to keep it unpublished — so the public
+ * shape omits it rather than relying on every caller to remember.
+ */
+export type PublicLocaleDomain = {
+  locale: string;
+  domain: string;
+  isDefault: boolean;
+};
+
+/** Drop admin-only fields from one mapping. */
+export function toPublicLocaleDomain(record: LocaleDomainRecord): PublicLocaleDomain {
+  return { locale: record.locale, domain: record.domain, isDefault: record.isDefault };
+}
+
+/** Drop admin-only fields from a list of mappings. */
+export function toPublicLocaleDomains(records: LocaleDomainRecord[]): PublicLocaleDomain[] {
+  return records.map(toPublicLocaleDomain);
+}
+
+/** The canonical stored form of a domain. Preserves a configured `www.`. */
+export function normalizeDomain(domain: string): string {
+  return normalizeCanonicalDomain(domain);
+}
+
+/** The key a request host is matched on. Apex and one `www.` fold together. */
+export function normalizeHost(host: string): string {
+  return hostMatchKey(host);
+}
+
+/**
+ * The mapping whose domain serves `host`.
+ *
+ * Apex and exactly one leading `www.` are aliases, so `voyara.se`,
+ * `www.voyara.se` and `WWW.VOYARA.SE` all reach the same row — whichever form
+ * was configured. Generated URLs still use the stored canonical hostname.
+ *
+ * A row only becomes eligible once its domain passes the same validation the
+ * backoffice applies at the write. Comparing on the normalized value alone
+ * lets a legacy `ftp://example.com` win the request for `example.com`, because
+ * normalizing strips the scheme and leaves exactly the host being looked up.
+ * Everything downstream then treats that row as the answer — its locale, and
+ * its unusable domain wherever a URL gets built.
+ */
+export function matchDomain<T extends { domain: string }>(
+  domains: T[],
+  host: string,
+): T | undefined {
+  return domains.find((d) => isValidCanonicalDomain(d.domain) && hostsMatch(d.domain, host));
+}
+
+/**
+ * Resolve the active locale for a request host, falling back to the default
+ * mapping, then to the first mapping, then to a synthetic host-based record.
+ *
+ * Only rows whose domain is a usable hostname are eligible for the fallback.
+ * A table written before the backoffice validated its input can hold a row
+ * that no request will ever match; letting it win the fallback hands the whole
+ * site that row's language, and hands generated URLs its unusable host.
+ */
+export function resolveRequestLocale<
+  T extends { locale: string; domain: string; isDefault?: boolean },
+>(domains: T[], host: string, defaultLocale: string): { locale: string; domain: T } {
+  const match = matchDomain(domains, host);
+  if (match) return { locale: match.locale, domain: match };
+
+  const usable = domains.filter((d) => isValidCanonicalDomain(d.domain));
+  const fallback = (usable.find((d) => d.isDefault) ??
+    usable[0] ?? {
+      locale: defaultLocale,
+      domain: normalizeCanonicalDomain(host) || "localhost",
+      isDefault: true,
+    }) as T;
+  return { locale: fallback.locale, domain: fallback };
+}
+
+/**
+ * Absolute origin for a locale, or "" when the locale has no usable mapping.
+ *
+ * An unusable row is skipped and the scan continues rather than returning ""
+ * on the first match for that language: one bad row left over from before the
+ * write validation must not hide a good one beside it.
+ */
+export function resolveLocaleOrigin(
+  locale: string,
+  domains: { locale: string; domain: string }[],
+): string {
+  for (const d of domains) {
+    if (d.locale !== locale) continue;
+    const mapped = domainOrigin(d.domain);
+    if (mapped) return mapped;
+  }
+  return "";
+}
+
+export type AdminHostSource =
+  /** `SITE_URL` — authoritative on a self-hosted install. */
+  | "site-url"
+  /** The row explicitly flagged `is_admin_domain`. */
+  | "database"
+  /** Nothing designates one, so the request keeps the host it arrived on. */
+  | "request-host"
+  /** No request to fall back to, so the mapping flagged as default is used. */
+  | "default-mapping"
+  /** No request and no default, so the first usable mapping is used. */
+  | "first-mapping"
+  /** Nothing is configured and there is no request — a local build. */
+  | "localhost";
+
+export type EffectiveAdminHost = {
+  /** Canonical hostname the backoffice should be served from. */
+  host: string;
+  /** Where that hostname came from — what the UI needs to explain itself. */
+  source: AdminHostSource;
+  /** Locale of the mapping the hostname came from, when there was one. */
+  locale: string;
+  /** True when `SITE_URL` overrides the database flag for this install. */
+  siteUrlAuthoritative: boolean;
+  /** Hostname the flagged database row names, when a row is flagged. */
+  flaggedHost: string | null;
+};
+
+export type AdminHostOptions = {
+  /** `SITE_URL`'s hostname on a self-hosted install, when configured. */
+  forcedHost?: string | null;
+  /** Host of the request being served. */
+  requestHost?: string | null;
+  defaultLocale: string;
+};
+
+/**
+ * The canonical form of a host, or "" when it could never be reached.
+ *
+ * The value is validated before it is normalized, not after: normalizing
+ * strips the scheme, so `ftp://example.com` checked afterwards is the
+ * perfectly valid `example.com` and the rejection never happens.
+ */
+function usableHost(value: string | null | undefined): string {
+  if (!isValidCanonicalDomain(value)) return "";
+  return normalizeDomain(value ?? "");
+}
+
+/**
+ * Which hostname actually serves the backoffice, and why.
+ *
+ * The order matters more than any single rule in this file, because getting it
+ * wrong locks an administrator out of the only screen that could fix it:
+ *
+ *   1. `SITE_URL`, when the deployment sets one. It outranks the database on
+ *      purpose — an imported row from another install must never send the
+ *      backoffice to that other install's hostname, and this is the recovery
+ *      path back out of a bad row.
+ *   2. The row explicitly flagged as the admin domain, when its host is usable.
+ *   3. **The host the request actually arrived on.** Nothing designates a
+ *      hostname, so the honest answer is the one already working. Reaching past
+ *      a live request for `domains[0]` — a hostname chosen by nothing but sort
+ *      order, quite possibly not serving the backoffice at all — turns a
+ *      missing flag into a redirect away from a session that was fine.
+ *   4. Only with no request to speak of (a build step, a job) does the table
+ *      decide: the mapping flagged as default,
+ *   5. then the first usable mapping,
+ *   6. then `localhost`, so the answer is never empty.
+ */
+export function resolveEffectiveAdminHost(
+  domains: LocaleDomainRecord[],
+  options: AdminHostOptions,
+): EffectiveAdminHost {
+  /*
+   * More than one row can carry the flag, and the first of them may be a
+   * legacy value no request will ever match. Taking it and stopping there
+   * drops the whole `database` step — the backoffice then follows the request
+   * host, silently ignoring a perfectly good flagged row further down the
+   * table. The reported `flaggedHost` still falls back to the first flagged
+   * row when none is usable, so the banner can say the flag is unusable.
+   */
+  const flaggedRows = domains.filter((d) => d.isAdminDomain);
+  const flaggedRow = flaggedRows.find((d) => usableHost(d.domain)) ?? flaggedRows[0];
+  const flaggedHost = flaggedRow ? normalizeDomain(flaggedRow.domain) : null;
+
+  const forced = usableHost(options.forcedHost);
+  if (forced) {
+    return {
+      host: forced,
+      source: "site-url",
+      locale: flaggedRow?.locale ?? domains[0]?.locale ?? options.defaultLocale,
+      siteUrlAuthoritative: true,
+      flaggedHost,
+    };
+  }
+
+  const rest = { siteUrlAuthoritative: false, flaggedHost };
+
+  if (flaggedRow && usableHost(flaggedRow.domain)) {
+    return {
+      host: usableHost(flaggedRow.domain),
+      source: "database",
+      locale: flaggedRow.locale,
+      ...rest,
+    };
+  }
+
+  const requestHost = usableHost(options.requestHost);
+  if (requestHost) {
+    // Whatever language this hostname serves, if any — so the record stays
+    // coherent without letting the mapping override where the request is.
+    const match = matchDomain(domains, requestHost);
+    return {
+      host: requestHost,
+      source: "request-host",
+      locale: match?.locale ?? options.defaultLocale,
+      ...rest,
+    };
+  }
+
+  const configuredDefault = domains.find((d) => d.isDefault && usableHost(d.domain));
+  if (configuredDefault) {
+    return {
+      host: usableHost(configuredDefault.domain),
+      source: "default-mapping",
+      locale: configuredDefault.locale,
+      ...rest,
+    };
+  }
+
+  const first = domains.find((d) => usableHost(d.domain));
+  if (first) {
+    return {
+      host: usableHost(first.domain),
+      source: "first-mapping",
+      locale: first.locale,
+      ...rest,
+    };
+  }
+
+  return { host: "localhost", source: "localhost", locale: options.defaultLocale, ...rest };
+}
+
+/** The backoffice hostname as a mapping record, for existing callers. */
+export function resolveAdminDomain(
+  domains: LocaleDomainRecord[],
+  options: AdminHostOptions,
+): LocaleDomainRecord {
+  const effective = resolveEffectiveAdminHost(domains, options);
+  const source = domains.find((d) => d.locale === effective.locale);
+  return {
+    locale: effective.locale,
+    domain: effective.host,
+    isDefault: source?.isDefault ?? true,
+    isAdminDomain: true,
+  };
+}
+
+/**
+ * Narrow an untyped server result into an `EffectiveAdminHost`.
+ *
+ * The value crosses a server-function boundary the package does not own, and
+ * the screen states it to an administrator as fact. Anything that is not the
+ * full shape becomes `null` — the banner then says nothing, which is the point
+ * of it being optional.
+ */
+export function parseEffectiveAdminHost(value: unknown): EffectiveAdminHost | null {
+  if (!value || typeof value !== "object") return null;
+  const v = value as Record<string, unknown>;
+
+  // Normalizing is not validating. `normalizeDomain("not a host")` returns
+  // "not a host" — non-empty, and previously enough to pass — which the banner
+  // then states as the hostname to move to.
+  const host = typeof v.host === "string" ? usableHost(v.host) : "";
+  if (!host) return null;
+
+  const sources: AdminHostSource[] = [
+    "site-url",
+    "database",
+    "request-host",
+    "default-mapping",
+    "first-mapping",
+    "localhost",
+  ];
+  if (typeof v.source !== "string" || !sources.includes(v.source as AdminHostSource)) return null;
+  const source = v.source as AdminHostSource;
+
+  const locale = typeof v.locale === "string" ? v.locale : "";
+  if (!locale.trim()) return null;
+
+  // The two ways of saying "SITE_URL decides" must agree. A result claiming
+  // SITE_URL authority under any other source, or the `site-url` source
+  // without it, is not a shape this package produces, so it is not one the
+  // screen should explain to an administrator as fact.
+  const siteUrlAuthoritative = v.siteUrlAuthoritative === true;
+  if ((source === "site-url") !== siteUrlAuthoritative) return null;
+
+  // The flagged row is context, not a destination: an unusable one is reported
+  // as absent rather than sinking the whole result.
+  const flaggedHost = typeof v.flaggedHost === "string" ? usableHost(v.flaggedHost) || null : null;
+
+  return { host, source, locale, siteUrlAuthoritative, flaggedHost };
+}
+
+export type AdminDomainChange =
+  | {
+      kind: "save";
+      locale: string;
+      /** The domain as typed. Included because the impact depends on it. */
+      domain: string;
+      isDefault: boolean;
+      isAdminDomain: boolean;
+    }
+  | { kind: "delete"; locale: string };
+
+/**
+ * The mapping table as it would be after a change, mirroring what the server
+ * writes: one row upserted, and a set flag cleared everywhere else.
+ */
+export function applyDomainChange(
+  domains: LocaleDomainRecord[],
+  change: AdminDomainChange,
+): LocaleDomainRecord[] {
+  if (change.kind === "delete") return domains.filter((d) => d.locale !== change.locale);
+
+  const row: LocaleDomainRecord = {
+    locale: change.locale,
+    domain: normalizeDomain(change.domain),
+    isDefault: change.isDefault,
+    isAdminDomain: change.isAdminDomain,
+  };
+  const others = domains
+    .filter((d) => d.locale !== change.locale)
+    .map((d) => ({
+      ...d,
+      isDefault: change.isDefault ? false : d.isDefault,
+      isAdminDomain: change.isAdminDomain ? false : d.isAdminDomain,
+    }));
+  return domains.some((d) => d.locale === change.locale)
+    ? domains.map((d) => (d.locale === change.locale ? row : others.find((o) => o.locale === d.locale) ?? d))
+    : [...others, row];
+}
+
+export type DomainChangeProblemReason =
+  | "invalid-domain"
+  | "duplicate-host"
+  | "unroutable-admin-host"
+  | "lost-default";
+
+export type DomainChangeValidationOptions = {
+  /** True when `SITE_URL`, not the table, decides where the backoffice is. */
+  siteUrlAuthoritative?: boolean;
+};
+
+export type DomainChangeProblem = {
+  reason: DomainChangeProblemReason;
+  message: string;
+  /** The other locale involved, for a duplicate. */
+  locale?: string;
+};
+
+/**
+ * Why a change must be refused outright, or null when it may go ahead.
+ *
+ * These are the conditions the server also enforces, kept pure so the screen
+ * can say the same thing before spending a round trip. They are refusals, not
+ * warnings: nothing here is offered as a confirmable choice, because the write
+ * would fail anyway. Moving the backoffice to a different hostname is
+ * deliberately *not* on this list — that is a valid change the administrator
+ * confirms, and `adminHostImpact` is what describes it.
+ */
+export function validateDomainChange(
+  domains: LocaleDomainRecord[],
+  change: AdminDomainChange,
+  options: DomainChangeValidationOptions = {},
+): DomainChangeProblem | null {
+  if (change.kind === "save") {
+    const parsed = parseCanonicalDomain(change.domain);
+    if (!parsed.ok) {
+      return { reason: "invalid-domain", message: canonicalDomainProblemMessage(parsed.reason) };
+    }
+
+    // Apex and `www.` resolve to the same site, so handing them to two
+    // languages makes the request-to-locale answer depend on which row a query
+    // happened to return first.
+    const clash = domains.find((d) => d.locale !== change.locale && hostsMatch(d.domain, parsed.domain));
+    if (clash) {
+      return {
+        reason: "duplicate-host",
+        locale: clash.locale,
+        message: `"${normalizeDomain(clash.domain)}" is already mapped to ${clash.locale}, and a hostname can only serve one language. Apex and www. count as the same hostname.`,
+      };
+    }
+
+    // Only a lockout where the flag is what routes the backoffice. With
+    // `SITE_URL` set the column is inert metadata, so refusing would be
+    // pedantry rather than protection.
+    if (change.isAdminDomain && !options.siteUrlAuthoritative && isLoopbackHost(parsed.domain)) {
+      return {
+        reason: "unroutable-admin-host",
+        message: `"${parsed.domain}" only resolves on the server itself, so nobody could reach the backoffice there.`,
+      };
+    }
+  }
+
+  const after = applyDomainChange(domains, change);
+  if (domains.some((d) => d.isDefault) && after.length > 0 && !after.some((d) => d.isDefault)) {
+    return {
+      reason: "lost-default",
+      message:
+        "That would leave no default language. Mark another domain as the default first — the default is what x-default and unmatched hosts fall back to.",
+    };
+  }
+
+  return null;
+}
+
+/** Human-readable reason a change was refused. */
+export function domainChangeProblemMessage(problem: DomainChangeProblem): string {
+  return problem.message;
+}
+
+export type AdminHostImpact = {
+  /** Hostname serving the backoffice now. */
+  from: string;
+  fromSource: AdminHostSource;
+  /** Hostname that would serve it after the change. */
+  to: string;
+  toSource: AdminHostSource;
+};
+
+/**
+ * How a valid change would move the backoffice, or null when it would not.
+ *
+ * Computed by resolving the effective host on both sides of the change rather
+ * than by pattern-matching the edit, so every route to a moved backoffice is
+ * caught by construction: retyping the flagged row's domain, promoting another
+ * row, deleting or unflagging the current one, and — where the table is what
+ * decides — editing the mapping the fallback lands on.
+ *
+ * A deployment pinned by `SITE_URL` gets `null` for all of them, because none
+ * of those edits change where the backoffice is actually served.
+ */
+export function adminHostImpact(
+  domains: LocaleDomainRecord[],
+  change: AdminDomainChange,
+  options: AdminHostOptions,
+): AdminHostImpact | null {
+  const before = resolveEffectiveAdminHost(domains, options);
+  const after = resolveEffectiveAdminHost(applyDomainChange(domains, change), options);
+  if (before.host === after.host) return null;
+  return { from: before.host, fromSource: before.source, to: after.host, toSource: after.source };
+}
+
+/**
+ * The confirmation shown before the backoffice moves to another hostname.
+ *
+ * `authoritative` is false when the caller could not find out whether
+ * `SITE_URL` is set — a screen whose host has registered no way to ask. The
+ * move is then stated as a condition rather than as a fact, because a
+ * deployment pinned by `SITE_URL` would not move at all.
+ */
+export function adminHostImpactMessage(
+  impact: AdminHostImpact,
+  options: { authoritative?: boolean } = {},
+): string {
+  const move = `the backoffice will move from "${impact.from}" to "${impact.to}"`;
+  const lead =
+    options.authoritative === false
+      ? `Unless SITE_URL pins it on this deployment, ${move}.`
+      : `${move.charAt(0).toUpperCase()}${move.slice(1)}.`;
+  return `${lead} Open the backoffice on the new hostname after saving. Continue?`;
+}