Ekklesia/apps/api/tests/lifecycle.test.ts

import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
import { tmpdir } from "node:os";
import path from "node:path";
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";

const poolConstructor = vi.hoisted(() => vi.fn());
const betterAuthMock = vi.hoisted(() => vi.fn());
const drizzleAdapterMock = vi.hoisted(() => vi.fn());
const serveMock = vi.hoisted(() => vi.fn());
const processOnSpy = vi.hoisted(() => vi.fn());

vi.mock("pg", () => ({ Pool: poolConstructor }));
vi.mock("better-auth", () => ({ betterAuth: betterAuthMock }));
vi.mock("better-auth/adapters/drizzle", () => ({ drizzleAdapter: drizzleAdapterMock }));
vi.mock("@hono/node-server", () => ({ serve: serveMock }));

import { parseModuleManifest } from "@ekklesia/contracts";
import {
  type DiscoveredModule,
  ModuleDiscoveryError,
  ModulePermissionCompositionError,
} from "@ekklesia/core/modules";
import { PermissionRegistryError } from "@ekklesia/core/authorization";
import { createApiRuntimeConfig } from "../src/config.js";
import { installShutdownSignalHandlers, startApi } from "../src/server.js";

function validConfig() {
  return createApiRuntimeConfig(
    {
      databaseUrl: "postgresql://ekklesia:[email protected]:5432/ekklesia",
      host: "127.0.0.1",
      identity: {
        baseUrl: "https://identity.example.test",
        secret: "correct-horse-battery-staple-0123456789",
        trustedOrigins: ["https://identity.example.test"],
      },
      port: 0,
    },
    { environment: "production" },
  );
}

const temporaryDirectories: string[] = [];

async function createTemporaryModulesDirectory(): Promise<string> {
  const directory = await mkdtemp(path.join(tmpdir(), "ekklesia-api-modules-"));
  temporaryDirectories.push(directory);
  return directory;
}

/** Writes a minimal, structurally valid module fixture (package.json + ekklesia.module.json +
 * server entrypoint) directly to disk — real discovery, not a hand-built double. The server
 * entrypoint throws immediately if ever imported, so a test that reaches a successful assertion
 * without that throw firing is direct evidence permission composition never executed it. */
async function createFixtureModule(
  modulesDirectory: string,
  id: string,
  manifestOverrides: Record<string, unknown> = {},
): Promise<void> {
  const moduleDirectory = path.join(modulesDirectory, id);
  const manifest = {
    manifestVersion: 3,
    id,
    name: `${id} module`,
    version: "0.1.0",
    compatibility: { platform: "^0.1.0", moduleSdk: "^0.1.0" },
    permissions: [],
    entrypoints: { server: "./dist/server/index.js" },
    ...manifestOverrides,
  };
  await mkdir(path.join(moduleDirectory, "dist/server"), { recursive: true });
  await Promise.all([
    writeFile(
      path.join(moduleDirectory, "package.json"),
      JSON.stringify({
        ekklesia: { layer: "module" },
        name: `@test/module-${id}`,
        type: "module",
        version: "0.1.0",
      }),
    ),
    writeFile(path.join(moduleDirectory, "ekklesia.module.json"), JSON.stringify(manifest)),
    writeFile(
      path.join(moduleDirectory, "dist/server/index.js"),
      'throw new Error("permission composition must never execute a module server entrypoint");',
    ),
  ]);
}

/** A minimal, in-memory `DiscoveredModule` double built from a real, validated manifest — used
 * only to reach `composePlatformPermissionRegistry`'s own duplicate-detection failure, which is
 * unreachable through real filesystem discovery (module ids are unique and every permission id is
 * namespaced by its own module's id, so no two genuinely discovered modules can ever collide). */
function fakeDiscoveredModule(
  id: string,
  permissions: ReadonlyArray<{
    id: string;
    baseline: "public" | "authenticated" | "restricted";
    description: string;
  }>,
): DiscoveredModule {
  const manifest = parseModuleManifest({
    capabilities: [],
    compatibility: { moduleSdk: "^0.1.0", platform: "^0.1.0" },
    entrypoints: { server: "./dist/does-not-exist/index.js" },
    id,
    manifestVersion: 3,
    name: `${id} module`,
    permissions,
    version: "0.1.0",
  });
  return {
    directory: `/modules/${id}`,
    entrypoints: { server: `/modules/${id}/dist/does-not-exist/index.js` },
    manifest,
    manifestPath: `/modules/${id}/ekklesia.module.json`,
    packageName: `@test/${id}`,
  };
}

/** A minimal fake `ServerType`: enough of Node's `http.Server` shape for `bindServer`/`shutdown`
 * to drive without a real socket. `close` and `once` are spies so tests can assert call counts;
 * `triggerError` simulates the server's own `'error'` event (e.g. a bind failure). */
function fakeServer() {
  let errorHandler: ((error: Error) => void) | undefined;
  const server = {
    address: () => ({ address: "127.0.0.1", family: "IPv4", port: 4_000 }),
    close: vi.fn((callback?: () => void) => {
      callback?.();
      return server;
    }),
    listening: true,
    once: vi.fn((event: string, handler: (error: Error) => void) => {
      if (event === "error") {
        errorHandler = handler;
      }
      return server;
    }),
  };
  return {
    server,
    triggerError: (error: Error) => errorHandler?.(error),
  };
}

/** Resolves the listening callback asynchronously, matching real `@hono/node-server` behavior
 * (the callback fires on the `listening` event, after `serve()` itself has already returned) —
 * resolving synchronously would reference `bindServer`'s own `server` const before it is
 * initialized. */
function mockSuccessfulServe() {
  const { server, triggerError } = fakeServer();
  serveMock.mockImplementation((_options: unknown, listeningListener?: () => void) => {
    queueMicrotask(() => listeningListener?.());
    return server;
  });
  return { server, triggerError };
}

function mockFailingServe(error: Error) {
  const { server, triggerError } = fakeServer();
  serveMock.mockImplementation(() => {
    queueMicrotask(() => triggerError(error));
    return server;
  });
  return server;
}

/** Captures signal handlers registered via `process.on` without ever installing a real one, so a
 * test can trigger "SIGINT"/"SIGTERM" by calling the captured function directly. */
function mockProcessOn(): { handlers: Record<string, () => void>; restore: () => void } {
  const handlers: Record<string, () => void> = {};
  const fake = vi.fn((event: string, handler: () => void) => {
    handlers[event] = handler;
    return process;
  });
  const onSpy = vi.spyOn(process, "on").mockImplementation(fake as unknown as typeof process.on);
  return { handlers, restore: () => onSpy.mockRestore() };
}

describe("Ekklesia API import safety", () => {
  const originalEnv = { ...process.env };
  const originalProcessOn = process.on.bind(process);

  beforeEach(() => {
    poolConstructor.mockClear();
    betterAuthMock.mockClear();
    drizzleAdapterMock.mockClear();
    serveMock.mockClear();
    processOnSpy.mockClear();
    for (const key of Object.keys(process.env)) {
      if (!(key in originalEnv)) {
        delete process.env[key];
      }
    }
    process.env = { ...originalEnv };
    process.on = originalProcessOn;
  });

  it("does not construct a database pool, Better Auth, or an HTTP server merely by importing the app factory", async () => {
    await import("../src/app.js");

    expect(poolConstructor).not.toHaveBeenCalled();
    expect(betterAuthMock).not.toHaveBeenCalled();
    expect(serveMock).not.toHaveBeenCalled();
  });

  it("does not construct a database pool, Better Auth, or an HTTP server merely by importing configuration", async () => {
    await import("../src/config.js");

    expect(poolConstructor).not.toHaveBeenCalled();
    expect(betterAuthMock).not.toHaveBeenCalled();
    expect(serveMock).not.toHaveBeenCalled();
  });

  it("does not read environment variables, connect to PostgreSQL, construct Better Auth, start a server, or install signal handlers merely by importing the executable server module", async () => {
    // Deliberately leave every runtime-required environment variable unset. If importing this
    // module performed any runtime composition, missing configuration would throw here.
    delete process.env.DATABASE_URL;
    delete process.env.EKKLESIA_IDENTITY_SECRET;
    delete process.env.EKKLESIA_IDENTITY_BASE_URL;
    delete process.env.EKKLESIA_IDENTITY_TRUSTED_ORIGINS;
    const onSpy = vi.spyOn(process, "on").mockImplementation(processOnSpy);

    await expect(import("../src/server.js")).resolves.toBeDefined();

    expect(poolConstructor).not.toHaveBeenCalled();
    expect(betterAuthMock).not.toHaveBeenCalled();
    expect(drizzleAdapterMock).not.toHaveBeenCalled();
    expect(serveMock).not.toHaveBeenCalled();
    expect(processOnSpy).not.toHaveBeenCalled();
    onSpy.mockRestore();
  });

  it("exposes startApi and main as explicit functions without invoking them at import time", async () => {
    const module = await import("../src/server.js");

    expect(typeof module.startApi).toBe("function");
    expect(typeof module.main).toBe("function");
    expect(serveMock).not.toHaveBeenCalled();
  });
});

describe("Ekklesia API shutdown lifecycle", () => {
  beforeEach(() => {
    poolConstructor.mockReset();
    betterAuthMock.mockReset();
    drizzleAdapterMock.mockClear();
    serveMock.mockReset();
  });

  it("makes every concurrent shutdown caller await the exact same server-close and pool-close, each exactly once", async () => {
    const poolEnd = vi.fn().mockResolvedValue(undefined);
    poolConstructor.mockImplementation(function fakePool() {
      return { end: poolEnd, on: vi.fn() };
    });
    betterAuthMock.mockReturnValue({ api: { getSession: vi.fn() }, handler: vi.fn() });
    const { server } = mockSuccessfulServe();

    const running = await startApi(validConfig());

    await Promise.all([running.shutdown(), running.shutdown(), running.shutdown()]);

    expect(server.close).toHaveBeenCalledTimes(1);
    expect(poolEnd).toHaveBeenCalledTimes(1);
  });

  it("constructs exactly one physical PostgreSQL pool for both the identity and authorization views, and closes only that one pool on shutdown", async () => {
    const poolEnd = vi.fn().mockResolvedValue(undefined);
    poolConstructor.mockImplementation(function fakePool() {
      return { end: poolEnd, on: vi.fn() };
    });
    betterAuthMock.mockReturnValue({ api: { getSession: vi.fn() }, handler: vi.fn() });
    mockSuccessfulServe();

    const running = await startApi(validConfig());

    // Identity (via Better Auth's Drizzle adapter) and authorization both read from the same
    // running API, yet only one `new Pool(...)` call is ever made — proving the shared-pool
    // composition in apps/api/src/database.ts never falls back to a second, independent pool.
    expect(poolConstructor).toHaveBeenCalledTimes(1);

    await running.shutdown();

    expect(poolEnd).toHaveBeenCalledTimes(1);
  });

  it("keeps shutdown idempotent for calls made after the first has already resolved", async () => {
    const poolEnd = vi.fn().mockResolvedValue(undefined);
    poolConstructor.mockImplementation(function fakePool() {
      return { end: poolEnd, on: vi.fn() };
    });
    betterAuthMock.mockReturnValue({ api: { getSession: vi.fn() }, handler: vi.fn() });
    const { server } = mockSuccessfulServe();

    const running = await startApi(validConfig());
    await running.shutdown();
    await running.shutdown();

    expect(server.close).toHaveBeenCalledTimes(1);
    expect(poolEnd).toHaveBeenCalledTimes(1);
  });

  it("closes an already-created database pool when identity construction fails during startup", async () => {
    const poolEnd = vi.fn().mockResolvedValue(undefined);
    poolConstructor.mockImplementation(function fakePool() {
      return { end: poolEnd, on: vi.fn() };
    });
    betterAuthMock.mockImplementation(() => {
      throw new Error("postgresql://admin:[email protected]/x");
    });

    await expect(startApi(validConfig())).rejects.toMatchObject({
      code: "IDENTITY_CONSTRUCTION_FAILED",
    });

    expect(poolConstructor).toHaveBeenCalledTimes(1);
    expect(poolEnd).toHaveBeenCalledTimes(1);
    expect(serveMock).not.toHaveBeenCalled();
  });

  it("closes an already-created database pool when the server fails to bind its listen address", async () => {
    const poolEnd = vi.fn().mockResolvedValue(undefined);
    poolConstructor.mockImplementation(function fakePool() {
      return { end: poolEnd, on: vi.fn() };
    });
    betterAuthMock.mockReturnValue({ api: { getSession: vi.fn() }, handler: vi.fn() });
    mockFailingServe(new Error("EADDRINUSE"));

    await expect(startApi(validConfig())).rejects.toThrow();

    expect(poolConstructor).toHaveBeenCalledTimes(1);
    expect(poolEnd).toHaveBeenCalledTimes(1);
  });

  it("wires SIGINT/SIGTERM to the same shutdown lifecycle and only calls the injected exit, never the real process.exit", async () => {
    const { handlers, restore } = mockProcessOn();
    const shutdown = vi.fn().mockResolvedValue(undefined);
    const exit = vi.fn();

    installShutdownSignalHandlers({ shutdown }, exit);

    expect(handlers.SIGINT).toEqual(expect.any(Function));
    expect(handlers.SIGTERM).toEqual(expect.any(Function));

    handlers.SIGINT?.();
    await Promise.resolve();
    await Promise.resolve();

    expect(shutdown).toHaveBeenCalledTimes(1);
    expect(exit).toHaveBeenCalledWith(0);

    // A second signal after the first must not trigger a second shutdown.
    handlers.SIGTERM?.();
    await Promise.resolve();
    expect(shutdown).toHaveBeenCalledTimes(1);
    expect(exit).toHaveBeenCalledTimes(1);

    restore();
  });

  it("exits with a failure code, without throwing, when signal-triggered shutdown itself fails", async () => {
    const { handlers, restore } = mockProcessOn();
    const shutdown = vi.fn().mockRejectedValue(new Error("pool close failed"));
    const exit = vi.fn();

    installShutdownSignalHandlers({ shutdown }, exit);
    handlers.SIGTERM?.();
    await Promise.resolve();
    await Promise.resolve();

    expect(exit).toHaveBeenCalledWith(1);

    restore();
  });
});

describe("Ekklesia API module permission composition at startup", () => {
  afterEach(async () => {
    await Promise.all(
      temporaryDirectories.splice(0).map((directory) => rm(directory, { recursive: true })),
    );
  });

  beforeEach(() => {
    poolConstructor.mockReset();
    betterAuthMock.mockReset();
    drizzleAdapterMock.mockClear();
    serveMock.mockReset();
  });

  it("discovers and composes permissions before constructing the database pool, Better Auth, or the HTTP server", async () => {
    const modulesDirectory = await createTemporaryModulesDirectory();
    // An incompatible platform version fails discovery itself (MODULE_PLATFORM_INCOMPATIBLE),
    // before permission composition — and, since composition runs before any pool exists, before
    // any pool, Better Auth instance, or HTTP server could ever be constructed.
    await createFixtureModule(modulesDirectory, "incompatible", {
      compatibility: { moduleSdk: "^0.1.0", platform: ">=99.0.0" },
    });

    await expect(
      startApi(validConfig(), { modulesDirectoryOverride: modulesDirectory }),
    ).rejects.toBeInstanceOf(ModuleDiscoveryError);

    expect(poolConstructor).not.toHaveBeenCalled();
    expect(betterAuthMock).not.toHaveBeenCalled();
    expect(serveMock).not.toHaveBeenCalled();
  });

  it("fails startup when a module claims the reserved core.* permission namespace, creating no pool, Better Auth instance, or server", async () => {
    const modulesDirectory = await createTemporaryModulesDirectory();
    // Only a module whose own id is literally "core" can produce a "core."-prefixed permission
    // that still passes the manifest's own module-namespace check.
    await createFixtureModule(modulesDirectory, "core", {
      permissions: [
        { baseline: "restricted", description: "Not really Core's.", id: "core.rogue.permission" },
      ],
    });

    let captured: unknown;
    try {
      await startApi(validConfig(), { modulesDirectoryOverride: modulesDirectory });
    } catch (error) {
      captured = error;
    }

    expect(captured).toBeInstanceOf(ModulePermissionCompositionError);
    expect(captured).toMatchObject({ code: "MODULE_PERMISSION_RESERVED_NAMESPACE" });
    expect(poolConstructor).not.toHaveBeenCalled();
    expect(betterAuthMock).not.toHaveBeenCalled();
    expect(serveMock).not.toHaveBeenCalled();
  });

  it("fails startup on a duplicate permission declaration, creating no pool, Better Auth instance, or server", async () => {
    const first = fakeDiscoveredModule("calendar", [
      { baseline: "restricted", description: "Read events.", id: "calendar.events.read" },
    ]);
    const second = fakeDiscoveredModule("calendar", [
      { baseline: "public", description: "Also read events.", id: "calendar.events.read" },
    ]);

    let captured: unknown;
    try {
      await startApi(validConfig(), { discoveredModulesOverride: [first, second] });
    } catch (error) {
      captured = error;
    }

    expect(captured).toBeInstanceOf(PermissionRegistryError);
    expect(captured).toMatchObject({ code: "PERMISSION_REGISTRY_DUPLICATE_DECLARATION" });
    expect(poolConstructor).not.toHaveBeenCalled();
    expect(betterAuthMock).not.toHaveBeenCalled();
    expect(serveMock).not.toHaveBeenCalled();
  });

  it("keeps a reserved-namespace failure and a generic duplicate-declaration failure distinguishable", async () => {
    const modulesDirectory = await createTemporaryModulesDirectory();
    await createFixtureModule(modulesDirectory, "core", {
      permissions: [
        {
          baseline: "restricted",
          description: "Attempting to shadow Core's own permission.",
          id: "core.authorization.grants.manage",
        },
      ],
    });

    let reservedNamespaceError: unknown;
    try {
      await startApi(validConfig(), { modulesDirectoryOverride: modulesDirectory });
    } catch (error) {
      reservedNamespaceError = error;
    }

    const duplicateModule = fakeDiscoveredModule("calendar", [
      { baseline: "restricted", description: "Read events.", id: "calendar.events.read" },
    ]);
    const duplicateModuleAgain = fakeDiscoveredModule("calendar", [
      { baseline: "restricted", description: "Read events, again.", id: "calendar.events.read" },
    ]);
    let duplicateError: unknown;
    try {
      await startApi(validConfig(), {
        discoveredModulesOverride: [duplicateModule, duplicateModuleAgain],
      });
    } catch (error) {
      duplicateError = error;
    }

    // Even though the first scenario's module attempted to exactly collide with an existing
    // Core-owned permission id, it is reported as a reserved-namespace violation, never as a
    // generic duplicate — the two failure families never overlap.
    expect(reservedNamespaceError).toBeInstanceOf(ModulePermissionCompositionError);
    expect(reservedNamespaceError).not.toBeInstanceOf(PermissionRegistryError);
    expect(duplicateError).toBeInstanceOf(PermissionRegistryError);
    expect(duplicateError).not.toBeInstanceOf(ModulePermissionCompositionError);
  });

  it("still constructs exactly one pool and succeeds when zero modules are installed", async () => {
    const modulesDirectory = await createTemporaryModulesDirectory();
    const poolEnd = vi.fn().mockResolvedValue(undefined);
    poolConstructor.mockImplementation(function fakePool() {
      return { end: poolEnd, on: vi.fn() };
    });
    betterAuthMock.mockReturnValue({ api: { getSession: vi.fn() }, handler: vi.fn() });
    mockSuccessfulServe();

    const running = await startApi(validConfig(), { modulesDirectoryOverride: modulesDirectory });

    expect(poolConstructor).toHaveBeenCalledTimes(1);
    await running.shutdown();
    expect(poolEnd).toHaveBeenCalledTimes(1);
  });

  it("does not perform module discovery merely by importing the platform-permissions module", async () => {
    const module = await import("../src/platform-permissions.js");

    expect(typeof module.composeStartupPermissionRegistry).toBe("function");
    expect(poolConstructor).not.toHaveBeenCalled();
  });
});