@jant/core 0.6.16 → 0.7.1

package/src/services/site.ts

@@ -1,4 +1,4 @@
-import { and, asc, eq, isNull } from "drizzle-orm";
+import { and, asc, eq, isNull, or } from "drizzle-orm";
 import type { Database } from "../db/index.js";
 import {
   sqliteSchemaBundle,
@@ -17,8 +17,18 @@ export interface SiteLookupResult {
   domain: SiteDomain | null;
 }
 
+/**
+ * Where a single-site install's row and domain come from. Every field applies
+ * only when the site is created; an existing site keeps its own.
+ */
 export interface EnsureSingleSiteOptions {
   host?: string | null;
+  /**
+   * The id to create the site with, instead of a random one. A deployment
+   * that restores a snapshot on every start gives the site the snapshot's id,
+   * so media URLs — which carry the site id — stay the same across rebuilds.
+   */
+  id?: string;
   key?: string;
   pathPrefix?: string | null;
 }
@@ -27,14 +37,76 @@ export interface ResolveSingleSiteOptions extends EnsureSingleSiteOptions {
   createIfMissing?: boolean;
 }
 
+/**
+ * Site lookups.
+ *
+ * `getOnlySite`, `resolveSingleSite` and `ensureSingleSite` belong to
+ * single-site mode. They answer "which site is this instance?", which has no
+ * answer on a hosted database, and once a second site exists they throw a
+ * `ConfigurationError` telling the operator to restore
+ * `SITE_RESOLUTION_MODE=host-based`. A host-based caller names its site
+ * instead — by host (`resolveByHost`), or by id or key (`getByIdOrKey`) — and
+ * never reaches those three.
+ */
 export interface SiteService {
   list(): Promise<Site[]>;
   getById(id: string): Promise<Site | null>;
+  /**
+   * Find the site an operator named by id or by key.
+   *
+   * Both columns are unique, and a managed key cannot contain the `_` every id
+   * carries, so at most one site answers in practice. If a hand-edited key
+   * ever equals another site's id, the id match wins.
+   *
+   * @param idOrKey - A site id (`sit_…`) or key
+   * @returns The site, or null when neither column matches
+   * @example
+   * ```ts
+   * await siteService.getByIdOrKey("demo");
+   * ```
+   */
+  getByIdOrKey(idOrKey: string): Promise<Site | null>;
   getPrimaryDomainForSite(siteId: string): Promise<SiteDomain | null>;
+  /**
+   * The instance's one site. Single-site mode only.
+   *
+   * @returns The site, or null before setup has created it
+   * @throws {ConfigurationError} When the database holds more than one site,
+   *   which in single-site mode means it belongs to a host-based install
+   * @example
+   * ```ts
+   * await siteService.getOnlySite();
+   * ```
+   */
   getOnlySite(): Promise<Site | null>;
+  /**
+   * The instance's one site and its domain, or the transient placeholder
+   * before setup has created it. Single-site mode only.
+   *
+   * @param options - Where a new site's row and domain come from, and whether
+   *   to create them when missing
+   * @returns The site and its domain
+   * @throws {ConfigurationError} When the database holds more than one site
+   * @example
+   * ```ts
+   * await siteService.resolveSingleSite({ createIfMissing: false });
+   * ```
+   */
   resolveSingleSite(
     options?: ResolveSingleSiteOptions,
   ): Promise<SiteLookupResult>;
+  /**
+   * `resolveSingleSite` that creates the site when it is missing. Single-site
+   * mode only.
+   *
+   * @param options - Where the new site's row and domain come from
+   * @returns The site and its domain
+   * @throws {ConfigurationError} When the database holds more than one site
+   * @example
+   * ```ts
+   * await siteService.ensureSingleSite({ host: "example.com" });
+   * ```
+   */
   ensureSingleSite(
     options?: EnsureSingleSiteOptions,
   ): Promise<SiteLookupResult>;
@@ -69,6 +141,9 @@ function toSiteDomain(row: typeof _sqliteSiteDomains.$inferSelect): SiteDomain {
 
 export const TRANSIENT_SINGLE_SITE_ID = "sit_pending";
 
+/** Joined-row ceiling for the single-site read — see `loadSingleSiteWithDomain`. */
+const SINGLE_SITE_JOIN_SCAN_LIMIT = 25;
+
 export function createTransientSite(key = "default"): Site {
   return {
     id: TRANSIENT_SINGLE_SITE_ID,
@@ -95,6 +170,10 @@ export function createSiteService(
 ): SiteService {
   const { siteDomains, sites } = databaseSchema;
 
+  /**
+   * Its error assumes single-site mode, which is the only mode that may reach
+   * it — see `SiteService`.
+   */
   async function loadSingleSiteRow() {
     const rows = await db
       .select()
@@ -109,6 +188,49 @@ export function createSiteService(
     return rows[0];
   }
 
+  /**
+   * The instance's one site together with its oldest domain, in one read.
+   *
+   * Every request resolves the site before it can do anything else, so the two
+   * reads this replaces sat at the head of the chain, one waiting on the other.
+   * Joining them keeps the domain ordering the separate read had — oldest
+   * first — and the multi-site guard that read carried.
+   *
+   * The limit bounds the scan, but it now bounds *joined* rows rather than
+   * sites, so one site with many domains could in principle fill the window and
+   * hide a second site from the guard. That case falls back to
+   * {@link loadSingleSiteRow}, which bounds sites; a single-site install has a
+   * handful of domains, so it is not reached in practice.
+   */
+  async function loadSingleSiteWithDomain(): Promise<{
+    site: typeof sites.$inferSelect | undefined;
+    domain: typeof siteDomains.$inferSelect | undefined;
+  }> {
+    const rows = await db
+      .select({ site: sites, domain: siteDomains })
+      .from(sites)
+      .leftJoin(siteDomains, eq(siteDomains.siteId, sites.id))
+      .orderBy(asc(sites.createdAt), asc(siteDomains.createdAt))
+      .limit(SINGLE_SITE_JOIN_SCAN_LIMIT);
+
+    const distinctSites = new Map<string, typeof sites.$inferSelect>();
+    for (const row of rows) {
+      distinctSites.set(row.site.id, row.site);
+    }
+    if (distinctSites.size > 1) {
+      throw createSingleSiteModeConfigurationError([...distinctSites.values()]);
+    }
+
+    // Only one site is in play, so the first non-null domain is its oldest.
+    const domain = rows.find((row) => row.domain)?.domain ?? undefined;
+
+    if (rows.length === SINGLE_SITE_JOIN_SCAN_LIMIT) {
+      return { site: await loadSingleSiteRow(), domain };
+    }
+
+    return { site: rows[0]?.site, domain };
+  }
+
   return {
     async list() {
       const rows = await db.select().from(sites).orderBy(asc(sites.createdAt));
@@ -124,6 +246,16 @@ export function createSiteService(
       return rows[0] ? toSite(rows[0]) : null;
     },
 
+    async getByIdOrKey(idOrKey) {
+      const rows = await db
+        .select()
+        .from(sites)
+        .where(or(eq(sites.id, idOrKey), eq(sites.key, idOrKey)))
+        .limit(2);
+      const row = rows.find((candidate) => candidate.id === idOrKey) ?? rows[0];
+      return row ? toSite(row) : null;
+    },
+
     async getPrimaryDomainForSite(siteId) {
       const rows = await db
         .select()
@@ -147,7 +279,12 @@ export function createSiteService(
 
     async resolveSingleSite(options = {}) {
       const shouldCreateIfMissing = options.createIfMissing ?? false;
-      const existingRow = await loadSingleSiteRow();
+      // The domain is only read when the caller names a host, so only that
+      // path pays for the join.
+      const loaded = options.host
+        ? await loadSingleSiteWithDomain()
+        : { site: await loadSingleSiteRow(), domain: undefined };
+      const existingRow = loaded.site;
       const timestamp = now();
       const created = existingRow
         ? existingRow
@@ -156,7 +293,7 @@ export function createSiteService(
               await db
                 .insert(sites)
                 .values({
-                  id: createEntityId("site"),
+                  id: options.id ?? createEntityId("site"),
                   key: options.key?.trim() || "default",
                   status: "active",
                   createdAt: timestamp,
@@ -173,35 +310,26 @@ export function createSiteService(
         };
       }
 
-      let domainRow: typeof siteDomains.$inferSelect | undefined;
-
-      if (options.host) {
-        const domainRows = await db
-          .select()
-          .from(siteDomains)
-          .where(eq(siteDomains.siteId, created.id))
-          .orderBy(asc(siteDomains.createdAt))
-          .limit(1);
-
-        domainRow = domainRows[0];
-
-        if (!domainRow && shouldCreateIfMissing) {
-          domainRow = (
-            await db
-              .insert(siteDomains)
-              .values({
-                id: createEntityId("siteDomain"),
-                siteId: created.id,
-                host: options.host,
-                pathPrefix: options.pathPrefix?.trim() || null,
-                kind: "primary",
-                redirectToPrimary: true,
-                createdAt: timestamp,
-                updatedAt: timestamp,
-              })
-              .returning()
-          )[0];
-        }
+      // A site that was just inserted has no domains yet, whatever the read
+      // above returned.
+      let domainRow = existingRow ? loaded.domain : undefined;
+
+      if (options.host && !domainRow && shouldCreateIfMissing) {
+        domainRow = (
+          await db
+            .insert(siteDomains)
+            .values({
+              id: createEntityId("siteDomain"),
+              siteId: created.id,
+              host: options.host,
+              pathPrefix: options.pathPrefix?.trim() || null,
+              kind: "primary",
+              redirectToPrimary: true,
+              createdAt: timestamp,
+              updatedAt: timestamp,
+            })
+            .returning()
+        )[0];
       }
 
       return {