feat: expose core identity transport

apps/api/src/server.ts

@@ -0,0 +1,168 @@
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import {
+  createIdentityDrizzleDatabase,
+  createIdentityRuntime,
+  type IdentityDatabaseHandle,
+  type IdentityRateLimitOverride,
+} from "@ekklesia/core/identity";
+import { serve, type ServerType } from "@hono/node-server";
+import type { Hono } from "hono";
+import { createApiApp } from "./app.js";
+import { type ApiRuntimeConfig, createApiRuntimeConfig } from "./config.js";
+
+const connectionTimeoutMs = 10_000;
+
+export interface RunningApi {
+  readonly app: Hono;
+  readonly server: ServerType;
+  shutdown(): Promise<void>;
+}
+
+export interface StartApiOptions {
+  /** Test-only escape hatch: never set by the executable entry point. See
+   * `IdentityRateLimitOverride` for why production must leave this unset. */
+  readonly rateLimitOverride?: IdentityRateLimitOverride;
+}
+
+async function safeCloseDatabase(handle: IdentityDatabaseHandle): Promise<void> {
+  try {
+    await handle.close();
+  } catch {
+    // Cleanup failures are swallowed here deliberately: they must never mask a startup failure
+    // that is already propagating, and there is no raw driver detail safe to surface.
+  }
+}
+
+function bindServer(app: Hono, host: string, port: number): Promise<ServerType> {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    const server = serve({ fetch: app.fetch, hostname: host, port }, () => {
+      if (!settled) {
+        settled = true;
+        resolve(server);
+      }
+    });
+    server.once("error", () => {
+      if (!settled) {
+        settled = true;
+        reject(new Error("The API server failed to start listening."));
+      }
+    });
+  });
+}
+
+/**
+ * Explicit runtime composition: constructs the PostgreSQL pool and Drizzle database, the Core
+ * identity runtime, and the Hono application, then starts the Node HTTP server. Returns a handle
+ * with an idempotent `shutdown()` so both the executable entry point and tests can stop the
+ * server and close the database pool deterministically. Never applies migrations or generates
+ * schema — the database must already be migrated through `pnpm migrations:apply`.
+ */
+export async function startApi(
+  config: ApiRuntimeConfig,
+  options: StartApiOptions = {},
+): Promise<RunningApi> {
+  const databaseHandle = createIdentityDrizzleDatabase(config.databaseUrl, {
+    connectionTimeoutMs,
+  });
+
+  let runtime: ReturnType<typeof createIdentityRuntime>;
+  try {
+    runtime = createIdentityRuntime({
+      config: config.identity,
+      db: databaseHandle.db,
+      ...(options.rateLimitOverride ? { rateLimitOverride: options.rateLimitOverride } : {}),
+    });
+  } catch (error) {
+    await safeCloseDatabase(databaseHandle);
+    throw error;
+  }
+
+  const app = createApiApp({ runtime, trustedOrigins: config.identity.trustedOrigins });
+
+  let server: ServerType;
+  try {
+    server = await bindServer(app, config.host, config.port);
+  } catch (error) {
+    await safeCloseDatabase(databaseHandle);
+    throw error;
+  }
+
+  let shuttingDown = false;
+  const shutdown = async (): Promise<void> => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    await new Promise<void>((resolve) => {
+      server.close(() => resolve());
+    });
+    await safeCloseDatabase(databaseHandle);
+  };
+
+  return Object.freeze({ app, server, shutdown });
+}
+
+function readConfigFromEnvironment(): {
+  readonly input: Parameters<typeof createApiRuntimeConfig>[0];
+  readonly environment: "development" | "production";
+} {
+  const trustedOriginsValue = process.env.EKKLESIA_IDENTITY_TRUSTED_ORIGINS;
+  const trustedOrigins = trustedOriginsValue
+    ?.split(",")
+    .map((origin) => origin.trim())
+    .filter((origin) => origin.length > 0);
+
+  return {
+    environment: process.env.NODE_ENV === "development" ? "development" : "production",
+    input: {
+      databaseUrl: process.env.DATABASE_URL,
+      host: process.env.EKKLESIA_API_HOST,
+      identity: {
+        baseUrl: process.env.EKKLESIA_IDENTITY_BASE_URL,
+        secret: process.env.EKKLESIA_IDENTITY_SECRET,
+        trustedOrigins,
+      },
+      port: process.env.EKKLESIA_API_PORT,
+    },
+  };
+}
+
+export async function main(): Promise<void> {
+  const { environment, input } = readConfigFromEnvironment();
+  const config = createApiRuntimeConfig(input, { environment });
+  const running = await startApi(config);
+
+  const address = running.server.address();
+  const boundPort = address && typeof address === "object" ? address.port : config.port;
+  console.log(`Ekklesia API listening on ${config.host}:${boundPort}`);
+
+  let signalReceived = false;
+  const handleSignal = (): void => {
+    if (signalReceived) {
+      return;
+    }
+    signalReceived = true;
+    running
+      .shutdown()
+      .then(() => process.exit(0))
+      .catch(() => process.exit(1));
+  };
+  process.on("SIGINT", handleSignal);
+  process.on("SIGTERM", handleSignal);
+}
+
+function isDirectExecution(): boolean {
+  const entrypoint = process.argv[1];
+  return (
+    entrypoint !== undefined && import.meta.url === pathToFileURL(path.resolve(entrypoint)).href
+  );
+}
+
+if (isDirectExecution()) {
+  main().catch(() => {
+    console.error("Ekklesia API failed to start.");
+    process.exitCode = 1;
+  });
+}