@xemahq/biome-database-nest 0.12.0 → 0.12.2

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

@@ -1,121 +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 = unwrapPlatformResponseEnvelope<BiomeDatabaseConfig>(
-    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: BiomeDatabaseConfig, url: string): void {
-  // A null / non-object body coerces to `{}`, so every required field reads as
-  // missing and the diagnostic below fires with "Present keys: []".
-  const record =
-    config !== null && typeof config === 'object'
-      ? (config as unknown as Record<string, unknown>)
-      : {};
-  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',
-}

package/src/lib/nest/biome-database.module.ts

@@ -1,175 +0,0 @@
-import { Module } from '@nestjs/common';
-import { IdentityBootstrapService } from '@xemahq/identity-client';
-import {
-  isOpenApiExtraction,
-  KERNEL_STATE_TOKEN,
-} from '@xemahq/service-registry-nest';
-
-import { bootstrapBiomeDatabases } from '../bootstrap';
-import { BiomeDatabaseMigrationMode } from '../migration-mode';
-
-import type {
-  BiomeDatabaseDeclaration,
-} from '../bootstrap';
-import type { DynamicModule } from '@nestjs/common';
-import type { KernelState } from '@xemahq/kernel-contracts/kernel-state';
-
-/**
- * DI-resolved sentinel that resolves to `true` once every declared biome
- * database has been schema-created, migrated, and exported into the env that
- * `createBiomePrismaAdapterFromEnv` reads.
- *
- * A consuming service MUST list this token in the `inject:[]` of its
- * `PrismaService` provider so Nest constructs the database connection ONLY
- * after the bootstrap has completed.
- */
-export const BIOME_DATABASE_READY = Symbol.for(
-  '@xemahq/biome-database-nest:ready',
-);
-
-interface BiomeDatabaseModuleCommonOptions {
-  /** The biome whose databases are being bootstrapped. */
-  readonly biomeId: string;
-}
-
-export interface ApplicationManagedBiomeDatabaseModuleOptions
-  extends BiomeDatabaseModuleCommonOptions {
-  readonly migrationMode: BiomeDatabaseMigrationMode.ApplicationManaged;
-  /**
-   * Explicit databases to bootstrap. Each declaration pins the credential
-   * generation independently of migration ownership.
-   */
-  readonly databases: readonly BiomeDatabaseDeclaration[];
-  /**
-   * Postgres extensions this biome needs (e.g. `['vector']`), ensured in the
-   * shared `public` schema BEFORE migrations run. Only declare extensions the
-   * biome actually uses. See `BootstrapBiomeDatabasesOptions.requiredExtensions`.
-   */
-  readonly requiredExtensions?: readonly string[];
-}
-
-
-/** Options for {@link BiomeDatabaseModule.forRoot}. */
-export type BiomeDatabaseModuleOptions =
-  ApplicationManagedBiomeDatabaseModuleOptions;
-
-/**
- * Global Nest dynamic module that bootstraps a biome's database using an
- * explicitly selected migration ownership mode.
- *
- * Application-managed mode retains env-first config resolution. Externally
- * managed declarations select environment or control plane explicitly, so a
- * stale env override can never silently replace the intended runtime
- * credential.
- *
- * `IdentityBootstrapService` (from `@xemahq/identity-client`) is provided
- * globally by the app's `XemaServiceModule.forBiome(...)` bootstrap, so it is
- * injectable at DI time and mints the service bearer for the control-plane
- * call. The control-plane ADDRESS is discovered from the Xema service registry:
- * this factory injects the app's `KernelState` backend via `KERNEL_STATE_TOKEN`
- * (exposed globally by `ServiceRegistryModule`, wired by
- * `XemaServiceModule.forBiome(...)`) and drives a private, short-lived
- * `KernelStateServiceRegistry` to `resolve('org-database-pool-api')` with
- * bounded retry — see `resolveControlPlaneBaseUrl` in `control-plane-discovery`.
- * The app-wide registry is NOT injected: it hydrates only in `onModuleInit`,
- * which cannot run until this instantiation-phase factory returns.
- *
- * REQUIRES the consuming app to provide `KERNEL_STATE_TOKEN` globally — every
- * biome service does via `XemaServiceModule.forBiome(...)` /
- * `ServiceRegistryModule`. No extra import in this module is needed because that
- * provider is global; if it is absent, Nest fails fast at DI resolution.
- *
- * Fail-fast: an absent/unknown mode or any boot error aborts Nest startup.
- *
- * @example Consumer wiring
- * ```ts
- * // app.module.ts (or prisma.module.ts):
- * imports: [BiomeDatabaseModule.forRoot({
- *   biomeId: '<biome-id>',
- * })],
- *
- * // prisma.module.ts — the PrismaService provider waits on the boot:
- * {
- *   provide: PrismaService,
- *   useFactory: () => new PrismaService(),
- *   inject: [BIOME_DATABASE_READY],
- * }
- * ```
- */
-@Module({})
-export class BiomeDatabaseModule {
-  static forRoot(opts: BiomeDatabaseModuleOptions): DynamicModule {
-    if (
-      opts.migrationMode !== BiomeDatabaseMigrationMode.ApplicationManaged
-    ) {
-      throw new Error(
-        '[biome-database] migrationMode is required and must be a BiomeDatabaseMigrationMode.',
-      );
-    }
-    if (opts.databases.length === 0) {
-      throw new Error(
-        '[biome-database] every migration mode requires at least one explicit database declaration.',
-      );
-    }
-    const databases:
-      | readonly BiomeDatabaseDeclaration[]
-      = opts.databases;
-
-    // Build-time OpenAPI extraction compiles the DI graph for decorator
-    // metadata only: it never calls `app.init()`, never issues a query, and
-    // stubs `PrismaService` outright. Running the real bootstrap there would
-    // connect to — and MIGRATE — a throwaway scratch database, which is both
-    // pointless and (under parallel extraction) mutually destructive. Resolve
-    // the sentinel to `true` without injecting anything.
-    if (isOpenApiExtraction()) {
-      return {
-        module: BiomeDatabaseModule,
-        global: true,
-        providers: [{ provide: BIOME_DATABASE_READY, useValue: true }],
-        exports: [BIOME_DATABASE_READY],
-      };
-    }
-
-    return {
-      module: BiomeDatabaseModule,
-      global: true,
-      providers: [
-        {
-          provide: BIOME_DATABASE_READY,
-          useFactory: async (
-            identityBootstrap: IdentityBootstrapService,
-            kernelState: KernelState,
-          ): Promise<true> => {
-            if (
-              opts.migrationMode ===
-              BiomeDatabaseMigrationMode.ApplicationManaged
-            ) {
-              await bootstrapBiomeDatabases({
-                biomeId: opts.biomeId,
-                migrationMode: opts.migrationMode,
-                databases: databases as readonly BiomeDatabaseDeclaration[],
-                ...(opts.requiredExtensions !== undefined
-                  ? { requiredExtensions: opts.requiredExtensions }
-                  : {}),
-                serviceToken: () => identityBootstrap.getAccessToken(),
-                kernelState,
-              });
-            } else {
-              await bootstrapBiomeDatabases({
-                biomeId: opts.biomeId,
-                migrationMode: opts.migrationMode,
-                databases:
-                  databases,
-                serviceToken: () => identityBootstrap.getAccessToken(),
-                kernelState,
-              });
-            }
-            return true;
-          },
-          inject: [IdentityBootstrapService, KERNEL_STATE_TOKEN],
-        },
-      ],
-      exports: [BIOME_DATABASE_READY],
-    };
-  }
-}