chore: consolidate new foundation and archive v1 (#1495)

2026-09-07 12:32:57 -05:00
parent 9a5fbdbda7 5d27700026
commit 127a54fdff
3511 changed files with 727899 additions and 10 deletions
@@ -0,0 +1,71 @@
+import { describe, it, expect, vi } from 'vitest';
+
+// The module under test imports @mosaicstack/db at module scope; we replace only the
+// pieces DatabaseModule uses (partial mock — the real module also exports the
+// schema the storage adapter's import chain needs) so the test pins the #1392
+// contract (refuse to start on an incomplete schema) without a live database.
+vi.mock('@mosaicstack/db', async (importOriginal) => {
+  const actual: object = await importOriginal();
+  return {
+    ...actual,
+    createDb: vi.fn(),
+    createPgliteDb: vi.fn(),
+    getMigrationStatus: vi.fn(),
+    runPgliteMigrations: vi.fn(),
+  };
+});
+
+import { DatabaseModule } from './database.module.js';
+import { getMigrationStatus } from '@mosaicstack/db';
+import type { DbHandle } from '@mosaicstack/db';
+import type { StorageAdapter } from '@mosaicstack/storage';
+import type { MosaicConfig } from '@mosaicstack/config';
+
+function makeModule(storageType: 'postgres' | 'pglite', tier: string) {
+  const storageAdapter = {
+    name: storageType,
+    migrate: vi.fn(),
+    close: vi.fn(),
+  } as unknown as StorageAdapter;
+  const handle = { close: vi.fn() } as unknown as DbHandle;
+  const config = {
+    tier,
+    storage: { type: storageType, url: 'postgresql://x' },
+  } as unknown as MosaicConfig;
+  return {
+    mod: new DatabaseModule(handle, storageAdapter, config),
+    storageAdapter,
+  };
+}
+
+describe('DatabaseModule.onModuleInit — #1392 schema verification', () => {
+  it('refuses to start when the postgres schema is incomplete', async () => {
+    const { mod, storageAdapter } = makeModule('postgres', 'standalone');
+    vi.mocked(getMigrationStatus).mockResolvedValue({
+      appliedCount: 15,
+      expectedCount: 17,
+      expectedLastTag: '0016_salty_morlocks',
+      complete: false,
+    });
+    await expect(mod.onModuleInit()).rejects.toThrow('Database schema incomplete: 15/17');
+    expect(storageAdapter.migrate).toHaveBeenCalled(); // migrations attempted first
+  });
+
+  it('starts normally when the schema is complete', async () => {
+    const { mod } = makeModule('postgres', 'standalone');
+    vi.mocked(getMigrationStatus).mockResolvedValue({
+      appliedCount: 17,
+      expectedCount: 17,
+      expectedLastTag: '0016_salty_morlocks',
+      complete: true,
+    });
+    await expect(mod.onModuleInit()).resolves.toBeUndefined();
+  });
+
+  it('does not verify postgres status for the local tier (PGlite migrates itself)', async () => {
+    const { mod } = makeModule('pglite', 'local');
+    vi.mocked(getMigrationStatus).mockClear();
+    await expect(mod.onModuleInit()).resolves.toBeUndefined();
+    expect(getMigrationStatus).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,113 @@
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import {
+  Global,
+  Inject,
+  Logger,
+  Module,
+  type OnApplicationShutdown,
+  type OnModuleInit,
+} from '@nestjs/common';
+import {
+  createDb,
+  createPgliteDb,
+  getMigrationStatus,
+  runPgliteMigrations,
+  type Db,
+  type DbHandle,
+} from '@mosaicstack/db';
+import { createStorageAdapter, type StorageAdapter } from '@mosaicstack/storage';
+import type { MosaicConfig } from '@mosaicstack/config';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
+
+export const DB_HANDLE = 'DB_HANDLE';
+export const DB = 'DB';
+export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: DB_HANDLE,
+      useFactory: (config: MosaicConfig): DbHandle => {
+        if (config.tier === 'local') {
+          const dataDir = join(homedir(), '.config', 'mosaic', 'gateway', 'pglite');
+          mkdirSync(dataDir, { recursive: true });
+          return createPgliteDb(dataDir);
+        }
+        return createDb(config.storage.type === 'postgres' ? config.storage.url : undefined);
+      },
+      inject: [MOSAIC_CONFIG],
+    },
+    {
+      provide: DB,
+      useFactory: (handle: DbHandle): Db => handle.db,
+      inject: [DB_HANDLE],
+    },
+    {
+      provide: STORAGE_ADAPTER,
+      useFactory: (config: MosaicConfig): StorageAdapter => createStorageAdapter(config.storage),
+      inject: [MOSAIC_CONFIG],
+    },
+  ],
+  exports: [DB, STORAGE_ADAPTER],
+})
+export class DatabaseModule implements OnApplicationShutdown, OnModuleInit {
+  private readonly logger = new Logger(DatabaseModule.name);
+
+  constructor(
+    @Inject(DB_HANDLE) private readonly handle: DbHandle,
+    @Inject(STORAGE_ADAPTER) private readonly storageAdapter: StorageAdapter,
+    @Inject(MOSAIC_CONFIG) private readonly config: MosaicConfig,
+  ) {}
+
+  // Migrations must complete before any module that injects DB starts serving
+  // requests. NestJS awaits onModuleInit before app.listen(), and modules that
+  // inject DB are initialized after this one — so all DB-dependent code sees a
+  // populated schema before the first HTTP request lands.
+  //
+  // Local (PGlite) tier: we run gateway-DB migrations explicitly here. The
+  // storage adapter writes to a separate PGlite directory and only manages its
+  // own KV tables, so we still call its migrate() afterwards.
+  //
+  // Postgres tier: PostgresAdapter.migrate() already calls runMigrations() on
+  // the same DATABASE_URL, so a single call covers both the gateway DB and
+  // the storage tables. We deliberately do NOT call runMigrations() here to
+  // avoid opening a second short-lived connection and doubling startup cost.
+  //
+  // #1392: we DO verify afterwards (getMigrationStatus opens one short-lived
+  // connection) and refuse to start on an incomplete schema. A gateway that
+  // boots "healthy" on an empty or partial database is precisely the failure
+  // that shipped in the T63 batch: silent at startup, catastrophic later.
+  async onModuleInit(): Promise<void> {
+    if (this.config.tier === 'local') {
+      this.logger.log('Applying PGlite schema migrations...');
+      await runPgliteMigrations(this.handle);
+    }
+    this.logger.log(`Initializing storage adapter (${this.storageAdapter.name})...`);
+    await this.storageAdapter.migrate();
+
+    if (this.config.storage.type === 'postgres') {
+      const status = await getMigrationStatus(this.config.storage.url);
+      if (!status.complete) {
+        this.logger.error(
+          `Database schema incomplete: ${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations applied ` +
+            `(last expected: ${status.expectedLastTag}). ` +
+            'Refusing to start on a partial schema — see issues #1392/#1402. ' +
+            "Remediation: re-run 'mosaic gateway install' (it now verifies), or apply migrations manually.",
+        );
+        throw new Error(
+          `Database schema incomplete: ${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations applied`,
+        );
+      }
+      this.logger.log(
+        `Database schema verified: ${status.appliedCount.toString()}/${status.expectedCount.toString()} migrations applied.`,
+      );
+    }
+  }
+
+  async onApplicationShutdown(): Promise<void> {
+    await Promise.all([this.handle.close(), this.storageAdapter.close()]);
+  }
+}