@xemahq/biome-database-nest 0.12.1 → 0.12.2

package/src/lib/config.ts

@@ -1,183 +0,0 @@
-import { DEFAULT_BIOME_DB_KEY } from './schema-name';
-
-/**
- * Fully-resolved connection facts for one biome database. Mirrors the standard
- * `DB_*` env contract but carries the inline CA option so a biome running on
- * its own runner needs no pre-mounted certificate file.
- */
-export interface BiomeDatabaseConfig {
-  readonly host: string;
-  readonly port: number;
-  readonly database: string;
-  /** Per-biome schema; `undefined` means a dedicated DB / the `public` schema. */
-  readonly schema?: string;
-  readonly username: string;
-  readonly password: string;
-  /** Monotonic credential generation returned by external provisioning. */
-  /** Pre-formed SSL query params, e.g. `sslmode=verify-full&sslrootcert=/path`. */
-  readonly sslParams?: string;
-  /** Inline CA PEM; the bootstrap writes it to a temp file and points sslrootcert at it. */
-  readonly caCertPem?: string;
-  readonly poolMax?: number;
-  /**
-   * When set, the STEADY-STATE runtime connection is routed through this
-   * transaction pooler (e.g. PgBouncer) at `poolerHost[:poolerPort]`, while
-   * schema-create and `prisma migrate deploy` still go DIRECT to `host:port`.
-   *
-   * A transaction pooler multiplexes many short-lived app connections onto a
-   * small set of server connections — the fix for connection-fan-out across
-   * many replicas × many biomes. It MUST NOT carry migrations: `migrate deploy`
-   * needs session-level state (advisory locks, DDL, prepared-statement lifetime)
-   * that transaction pooling breaks. Hence the direct-vs-pooled split.
-   *
-   * Absent → the runtime uses the direct `host` (current behavior; local dev,
-   * or any cluster without a pooler deployed). Opt-in, per-deployment.
-   */
-  readonly poolerHost?: string;
-  /** Pooler port; defaults to `port` when a `poolerHost` is set without one. */
-  readonly poolerPort?: number;
-  /**
-   * SSL params for the app→pooler leg. The pooler→Postgres leg terminates the
-   * managed-TLS in the pooler's OWN config, so the in-cluster app→pooler hop is
-   * normally plaintext. Defaults to `sslmode=disable` when a `poolerHost` is set.
-   */
-  readonly poolerSslParams?: string;
-}
-
-/** Per-dbKey env-var suffix, e.g. `analytics` → `_ANALYTICS`; primary → ''. */
-function envSuffixForKey(dbKey: string | undefined): string {
-  if (dbKey === undefined || dbKey === '' || dbKey === DEFAULT_BIOME_DB_KEY) {
-    return '';
-  }
-  return `_${dbKey.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
-}
-
-/**
- * Read a `DB_<NAME>` var, preferring the dbKey-suffixed variant and falling
- * back to the unsuffixed base. `fallbackToBase=false` reads ONLY the suffixed
- * variant (used for fields that must not be shared across keys, e.g. DB_NAME).
- */
-function readDbVar(
-  env: NodeJS.ProcessEnv,
-  base: string,
-  suffix: string,
-  fallbackToBase: boolean,
-): string | undefined {
-  const suffixed = env[`${base}${suffix}`];
-  if (suffixed !== undefined && suffixed !== '') {
-    return suffixed;
-  }
-  if (!fallbackToBase || suffix === '') {
-    return undefined;
-  }
-  const baseVal = env[base];
-  return baseVal !== undefined && baseVal !== '' ? baseVal : undefined;
-}
-
-/**
- * Resolve a {@link BiomeDatabaseConfig} from the standard `DB_*` env contract.
- *
- * This is the LOCAL-DEV OVERRIDE path. For a non-default `dbKey`, identity
- * fields (`DB_NAME`, `DB_SCHEMA`) are read from the suffixed variant ONLY,
- * while shared connection fields (host/port/user/password/ssl/pool) fall back
- * to the base var when the suffixed one is absent.
- *
- * Returns `null` when `DB_HOST` is absent entirely — the caller treats that as
- * "no local override → use the control plane". If `DB_HOST` IS set but a
- * mandatory field (port/user/password/database) is missing, this THROWS: a
- * partial override is a misconfiguration that must be loud, never silently
- * ignored.
- */
-export function resolveBiomeDatabaseConfigFromEnv(
-  env: NodeJS.ProcessEnv = process.env,
-  dbKey?: string,
-): BiomeDatabaseConfig | null {
-  const suffix = envSuffixForKey(dbKey);
-
-  const host = readDbVar(env, 'DB_HOST', suffix, true);
-  if (host === undefined) {
-    return null;
-  }
-
-  const portRaw = readDbVar(env, 'DB_PORT', suffix, true);
-  const username = readDbVar(env, 'DB_USER', suffix, true);
-  const password = readDbVar(env, 'DB_PASSWORD', suffix, true);
-  // Identity fields are per-key — never inherit the base name/schema for a
-  // non-default key, or two keys would alias the same database.
-  const database = readDbVar(env, 'DB_NAME', suffix, suffix === '');
-  const schema = readDbVar(env, 'DB_SCHEMA', suffix, suffix === '');
-  const missing: string[] = [];
-  if (portRaw === undefined) {
-    missing.push(`DB_PORT${suffix}`);
-  }
-  if (username === undefined) {
-    missing.push(`DB_USER${suffix}`);
-  }
-  if (password === undefined) {
-    missing.push(`DB_PASSWORD${suffix}`);
-  }
-  if (database === undefined) {
-    missing.push(`DB_NAME${suffix}`);
-  }
-  if (missing.length > 0) {
-    throw new Error(
-      `Partial biome database config for dbKey "${dbKey ?? DEFAULT_BIOME_DB_KEY}": ` +
-        `DB_HOST${suffix} is set but the following are missing: ${missing.join(', ')}. ` +
-        `Provide all of them or none.`,
-    );
-  }
-
-  const port = Number.parseInt(portRaw as string, 10);
-  if (!Number.isInteger(port) || port <= 0) {
-    throw new Error(
-      `Invalid DB_PORT${suffix} value "${portRaw}" — expected a positive integer.`,
-    );
-  }
-
-  const sslParams = readDbVar(env, 'DB_SSL_PARAMS', suffix, true);
-
-  // Optional transaction-pooler override for the RUNTIME leg (migrations stay
-  // direct). All three are optional; a `DB_POOLER_HOST` with no port defaults
-  // to the direct port at compose time.
-  const poolerHost = readDbVar(env, 'DB_POOLER_HOST', suffix, true);
-  const poolerPortRaw = readDbVar(env, 'DB_POOLER_PORT', suffix, true);
-  const poolerPort =
-    poolerPortRaw !== undefined
-      ? Number.parseInt(poolerPortRaw, 10)
-      : undefined;
-  if (
-    poolerPortRaw !== undefined &&
-    (!Number.isInteger(poolerPort) || poolerPort! <= 0)
-  ) {
-    throw new Error(
-      `Invalid DB_POOLER_PORT${suffix} value "${poolerPortRaw}" — expected a positive integer.`,
-    );
-  }
-  const poolerSslParams = readDbVar(env, 'DB_POOLER_SSL_PARAMS', suffix, true);
-
-  const poolMaxRaw = readDbVar(env, 'DB_POOL_MAX', suffix, true);
-  const poolMax =
-    poolMaxRaw !== undefined ? Number.parseInt(poolMaxRaw, 10) : undefined;
-  if (
-    poolMaxRaw !== undefined &&
-    (!Number.isInteger(poolMax) || poolMax! <= 0)
-  ) {
-    throw new Error(
-      `Invalid DB_POOL_MAX${suffix} value "${poolMaxRaw}" — expected a positive integer.`,
-    );
-  }
-
-  return {
-    host,
-    port,
-    database: database as string,
-    username: username as string,
-    password: password as string,
-    ...(schema !== undefined ? { schema } : {}),
-    ...(sslParams !== undefined ? { sslParams } : {}),
-    ...(poolMax !== undefined ? { poolMax } : {}),
-    ...(poolerHost !== undefined ? { poolerHost } : {}),
-    ...(poolerPort !== undefined ? { poolerPort } : {}),
-    ...(poolerSslParams !== undefined ? { poolerSslParams } : {}),
-  };
-}

package/src/lib/control-plane-client.ts

@@ -1,124 +0,0 @@
-/**
- * Control-plane contract for biome database provisioning config.
- *
- * The control plane is `org-database-pool-api`. The endpoint author MUST
- * implement this exact request/response shape:
- *
- *   POST {base}/system-databases/config
- *   Authorization: Bearer <serviceToken>
- *   Content-Type: application/json
- *   Body (SystemDatabaseConfigRequest):
- *     { "biomeId": string, "dbKey"?: string }
- *
- *   200 Response (BiomeDatabaseConfig, JSON):
- *     {
- *       "host": string,
- *       "port": number,
- *       "database": string,
- *       "schema"?: string,
- *       "username": string,
- *       "password": string,
- *       "sslParams"?: string,
- *       "caCertPem"?: string,
- *       "poolMax"?: number
- *     }
- *
- *   Non-2xx → this client throws (fail-fast, no silent fallback).
- *
- * The control-plane ADDRESS is discovered from the Xema service registry — see
- * `resolveControlPlaneBaseUrl` in `./control-plane-discovery`. This module owns
- * only the request/response contract against a resolved base URL; it carries no
- * knowledge of how the address is obtained.
- */
-import { unwrapPlatformResponseEnvelope } from '@xemahq/platform-common';
-
-import type { BiomeDatabaseConfig } from './config';
-
-export interface SystemDatabaseConfigRequest {
-  readonly biomeId: string;
-  readonly dbKey?: string;
-}
-
-/**
- * Fetch a biome's fully-resolved database config from the control plane.
- *
- * POSTs `{ biomeId, dbKey }` to `{base}/system-databases/config` with a
- * service bearer. `base` is the control-plane address (see
- * {@link resolveControlPlaneBaseUrl}).
- *
- * @throws on a non-2xx response (carries status + body) — never returns a
- *   partial or defaulted config.
- */
-export async function fetchSystemDatabaseConfig(
-  baseUrl: string,
-  serviceToken: string,
-  req: SystemDatabaseConfigRequest,
-): Promise<BiomeDatabaseConfig> {
-  const url = `${baseUrl.replace(/\/$/, '')}/system-databases/config`;
-
-  const response = await fetch(url, {
-    method: 'POST',
-    headers: {
-      authorization: `Bearer ${serviceToken}`,
-      'content-type': 'application/json',
-    },
-    body: JSON.stringify({
-      biomeId: req.biomeId,
-      ...(req.dbKey !== undefined ? { dbKey: req.dbKey } : {}),
-    }),
-  });
-
-  if (!response.ok) {
-    const body = await response.text().catch(() => '<unreadable body>');
-    throw new Error(
-      `fetchSystemDatabaseConfig: ${url} responded ${response.status} ${response.statusText}: ${body}`,
-    );
-  }
-
-  const payload = await response.json();
-  const config: unknown = unwrapPlatformResponseEnvelope<unknown>(
-    payload,
-    `fetchSystemDatabaseConfig: ${url}`,
-  );
-  assertCompleteConfig(config, url);
-  return config;
-}
-
-const REQUIRED_CONFIG_FIELDS = [
-  'host',
-  'port',
-  'username',
-  'password',
-  'database',
-] as const;
-
-/**
- * Fail-fast if the resolved config cannot form a connection — a missing/empty
- * connection field (or a malformed envelope) is a control-plane contract
- * violation, never a silently-defaulted partial. The error names the missing
- * fields and the keys actually present, to distinguish "control plane returned
- * a partial config" from "response envelope was not unwrapped".
- */
-function assertCompleteConfig(
-  config: unknown,
-  url: string,
-): asserts config is BiomeDatabaseConfig {
-  // A null / non-object body coerces to `{}`, so every required field reads as
-  // missing and the diagnostic below fires with "Present keys: []".
-  const record: Record<string, unknown> =
-    config !== null && typeof config === 'object'
-      ? Object.fromEntries(Object.entries(config))
-      : {};
-  const missing = REQUIRED_CONFIG_FIELDS.filter((field) => {
-    const value = record[field];
-    return value === undefined || value === null || value === '';
-  });
-  if (missing.length > 0) {
-    throw new Error(
-      `fetchSystemDatabaseConfig: ${url} returned a config missing required ` +
-        `field(s): ${missing.join(', ')}. Present keys: ` +
-        `[${Object.keys(record).join(', ')}]. (If the keys look nested, the ` +
-        `{ data } response envelope was not unwrapped.)`,
-    );
-  }
-}

package/src/lib/control-plane-discovery.ts

@@ -1,42 +0,0 @@
-/**
- * Discovery of the `org-database-pool-api` control plane via the Xema service
- * registry (KernelState / etcd) — replacing the former `ORG_DATABASE_POOL_API_URL`
- * env var. `org-database-pool-api` self-registers into the registry at boot (it
- * uses `XemaServiceModule.forBiome`), so its address is authoritative there.
- *
- * The DB bootstrap resolves the pool INSIDE the Nest DI instantiation phase
- * (the `BIOME_DATABASE_READY` factory runs before any `onModuleInit`), so it uses
- * the shared {@link resolveHttpUrlEagerly} helper — which drives a private,
- * hydrated `KernelStateServiceRegistry` off the app's injected `KernelState`
- * (`KERNEL_STATE_TOKEN`) with bounded retry, because the app-wide registry is not
- * yet hydrated at factory time. See that helper for the full rationale.
- */
-import {
-  resolveHttpUrlEagerly,
-  type EagerResolveOptions,
-} from '@xemahq/service-registry-nest';
-
-import type { KernelState } from '@xemahq/kernel-contracts/kernel-state';
-
-/** Registry name under which `org-database-pool-api` self-registers. */
-export const ORG_DATABASE_POOL_SERVICE_NAME = 'org-database-pool-api';
-
-/** Bounded-backoff tuning for control-plane discovery (alias of the shared shape). */
-export type ControlPlaneDiscoveryOptions = EagerResolveOptions;
-
-/**
- * Resolve the `org-database-pool-api` control-plane base URL from the service
- * registry, retrying with bounded backoff while the pool is not yet registered
- * (a legitimate boot-order race). Fail-fast after the deadline — no silent
- * fallback, no unbounded wait.
- */
-export function resolveControlPlaneBaseUrl(
-  kernelState: KernelState,
-  options?: ControlPlaneDiscoveryOptions,
-): Promise<string> {
-  return resolveHttpUrlEagerly(
-    kernelState,
-    ORG_DATABASE_POOL_SERVICE_NAME,
-    options,
-  );
-}

package/src/lib/identifier.ts

@@ -1,177 +0,0 @@
-import { createHash } from 'node:crypto';
-
-/**
- * Postgres identifier derivation — the SINGLE implementation.
- *
- * Several independent producers derive Postgres identifiers from free-form
- * input: the org database pool derives access-role names from a schema name,
- * biome-host derives an org database name and a per-biome schema name, and the
- * webapp studio derives per-app database/schema names. They MUST agree, because
- * one side creates the object and another side connects to it. Historically each
- * re-implemented the same algorithm inline, and they drifted — which is exactly
- * how a grant gets created for one role while the connection asks for another.
- *
- * Everything below is a primitive; the naming CONVENTIONS that use them live
- * with their owners (`./role-names` for `_rw`/`_ro`, `./schema-name` for
- * `biome_<id>`). The primitives are deliberately parameterised rather than
- * flattened into one function, because the callers genuinely differ:
- *
- * - the length budget differs (a role base must leave room for its `_rw`
- *   suffix; a schema name may use the full 63 bytes);
- * - the character mapping differs (deriving from an already-well-formed
- *   identifier must NOT collapse `_` runs, or two distinct schemas would share
- *   one role; composing from free-form segments must collapse, or a `--` in a
- *   slug would collide with the `__` separator convention);
- * - the hash input differs (it is always taken over the RAW, pre-sanitisation
- *   input, but "the raw input" is a single string for some callers and a
- *   `:`-joined tuple for others).
- *
- * Each of those is an explicit argument, so no caller can silently derive an
- * identifier another caller disagrees with.
- */
-
-/**
- * PostgreSQL caps identifiers at `NAMEDATALEN - 1` = 63 bytes. Beyond that the
- * SERVER truncates silently, which is how two distinct logical names become one
- * physical object. Every identifier is therefore fitted to an explicit budget by
- * {@link fitIdentifier} rather than left to server-side truncation.
- */
-export const POSTGRES_MAX_IDENTIFIER_LENGTH = 63;
-
-/**
- * Hex characters of the SHA-256 digest spliced into an over-budget identifier.
- * 12 hex chars = 48 bits, so accidental collisions between distinct inputs are
- * negligible while most of the budget stays human-readable.
- */
-export const IDENTIFIER_HASH_LENGTH = 12;
-
-/** A composed prefix must already be a bare, lowercase identifier fragment. */
-const IDENTIFIER_PREFIX_PATTERN = /^[a-z][a-z0-9_]*$/;
-
-/**
- * Lowercase, and map every rune outside `[a-z0-9_]` to `_`.
- *
- * RAW character mapping only: runs of `_` are preserved and leading/trailing `_`
- * are kept. This is the correct mapping when deriving an identifier from an
- * ALREADY-well-formed identifier (e.g. a role name from a schema name) —
- * collapsing there would make the distinct schemas `a__b` and `a_b` share one
- * role.
- */
-export function sanitizeIdentifierChars(value: string): string {
-  return value.toLowerCase().replace(/[^a-z0-9_]/g, '_');
-}
-
-/**
- * {@link sanitizeIdentifierChars}, then collapse runs of `_` and trim
- * leading/trailing `_`.
- *
- * This is the correct mapping for a single free-form SEGMENT (a biome id, an app
- * slug, an org id) that is about to be joined to other segments with `_`.
- * Returns `''` when nothing survives; the caller decides whether that is fatal.
- */
-export function sanitizeIdentifierSegment(value: string): string {
-  return sanitizeIdentifierChars(value)
-    .replace(/_+/g, '_')
-    .replace(/^_+|_+$/g, '');
-}
-
-export interface FitIdentifierInput {
-  /** The already-composed, already-sanitized identifier. */
-  readonly candidate: string;
-  /**
-   * Maximum length `candidate` may occupy. A caller that appends its own suffix
-   * afterwards (e.g. `_rw`) MUST pass a budget that already excludes it — see
-   * `SCHEMA_ROLE_BASE_MAX_LENGTH` in `./role-names`.
-   */
-  readonly maxLength: number;
-  /**
-   * The string hashed to disambiguate over-budget identifiers. Deliberately a
-   * SEPARATE input from `candidate`: it is hashed over the RAW
-   * (pre-sanitisation) input, so two inputs whose sanitized forms share a
-   * prefix still derive different identifiers.
-   */
-  readonly hashInput: string;
-  /** Defaults to {@link IDENTIFIER_HASH_LENGTH}. */
-  readonly hashLength?: number;
-}
-
-/**
- * Fit `candidate` into `maxLength`, splicing in a deterministic hash of
- * `hashInput` when it does not fit.
- *
- * Under the budget the candidate is returned VERBATIM — that is what keeps
- * every already-provisioned database, schema, and role name stable. Over the
- * budget the result is `<truncated-prefix>_<hash>`, where the prefix is
- * right-trimmed of `_` so the separator is never doubled.
- */
-export function fitIdentifier({
-  candidate,
-  maxLength,
-  hashInput,
-  hashLength = IDENTIFIER_HASH_LENGTH,
-}: FitIdentifierInput): string {
-  if (!Number.isInteger(maxLength) || maxLength <= hashLength + 1) {
-    throw new Error(
-      `fitIdentifier: maxLength must be an integer greater than ${
-        hashLength + 1
-      } (hashLength + 1) to leave room for the disambiguating hash; received ${maxLength}`,
-    );
-  }
-
-  if (candidate.length <= maxLength) {
-    return candidate;
-  }
-
-  const hash = createHash('sha256')
-    .update(hashInput)
-    .digest('hex')
-    .slice(0, hashLength);
-  const prefix = candidate
-    .slice(0, maxLength - hashLength - 1)
-    .replace(/_+$/g, '');
-  return `${prefix}_${hash}`;
-}
-
-export interface ComposeIdentifierInput {
-  /**
-   * Literal namespace prefix (e.g. `app`, `biome`). It is NOT sanitized — it
-   * must already be a bare lowercase identifier fragment — and it is NOT part
-   * of the disambiguating hash input, because it is a constant per producer.
-   */
-  readonly prefix: string;
-  /** Free-form segments; each is sanitized, and empty results are dropped. */
-  readonly parts: readonly string[];
-  /** Defaults to {@link POSTGRES_MAX_IDENTIFIER_LENGTH}. */
-  readonly maxLength?: number;
-}
-
-/**
- * Compose `<prefix>_<segment>_<segment>…`, fitted to the budget.
- *
- * The disambiguating hash is taken over the RAW `parts` joined by `:` — the
- * separator cannot occur in a Postgres identifier, so the tuple is unambiguous
- * and `['a_b']` can never hash the same as `['a', 'b']`.
- */
-export function composeIdentifier({
-  prefix,
-  parts,
-  maxLength = POSTGRES_MAX_IDENTIFIER_LENGTH,
-}: ComposeIdentifierInput): string {
-  if (!IDENTIFIER_PREFIX_PATTERN.test(prefix)) {
-    throw new Error(
-      `composeIdentifier: prefix "${prefix}" is not a bare lowercase identifier fragment (${String(
-        IDENTIFIER_PREFIX_PATTERN,
-      )})`,
-    );
-  }
-
-  const segments = parts
-    .map((part) => sanitizeIdentifierSegment(part))
-    .filter((part) => part.length > 0);
-
-  return fitIdentifier({
-    candidate: [prefix, ...segments].join('_'),
-    maxLength,
-    hashInput: parts.join(':'),
-  });
-}

package/src/lib/migration-mode.ts

@@ -1,25 +0,0 @@
-/**
- * Who owns schema creation, extension installation, and Prisma migrations.
- *
- * This is deliberately required at every bootstrap call. Database ownership
- * must never change because an option was omitted or an environment variable
- * was misspelled.
- *
- * There is exactly ONE mode. `ExternallyManaged` was removed with the plane it
- * named: a runtime-only credential, per-schema `xema_runtime_*` roles, and a
- * verifier that proved a service's role could not alter its own schema. None of
- * it was ever provisioned — the roles were never created, and the workflows
- * that would have created them require a runner label no runner carries and a
- * privileged environment this org's GitHub plan cannot express. Every one of
- * the 31 shared-biome consumers is `application-managed`.
- *
- * The VALUE is gone rather than merely unimplemented, deliberately. Leaving it
- * in the enum with nothing behind it would let a service declare a mode that
- * silently did nothing — a degradation path disguised as configuration. Now
- * declaring it is a compile error, which is the honest answer while the plane
- * does not exist. If externally-managed migrations are ever built for real,
- * this member returns with the implementation, not before it.
- */
-export enum BiomeDatabaseMigrationMode {
-  ApplicationManaged = 'application-managed',
-}