@wopr-network/platform-core 1.68.0 → 1.70.0

package/src/server/__tests__/lifecycle.test.ts

@@ -0,0 +1,106 @@
+import { describe, expect, it, vi } from "vitest";
+import { gracefulShutdown, startBackgroundServices } from "../lifecycle.js";
+import { createTestContainer } from "../test-container.js";
+
+describe("startBackgroundServices", () => {
+  it("returns a BackgroundHandles object", async () => {
+    const container = createTestContainer();
+    const handles = await startBackgroundServices(container);
+    expect(handles).toHaveProperty("intervals");
+    expect(handles).toHaveProperty("unsubscribes");
+    expect(Array.isArray(handles.intervals)).toBe(true);
+    expect(Array.isArray(handles.unsubscribes)).toBe(true);
+  });
+
+  it("calls proxy.start when fleet is enabled", async () => {
+    const startFn = vi.fn().mockResolvedValue(undefined);
+    const container = createTestContainer({
+      fleet: {
+        manager: {} as never,
+        docker: {} as never,
+        proxy: {
+          start: startFn,
+          addRoute: async () => {},
+          removeRoute: () => {},
+          getRoutes: () => [],
+        } as never,
+        profileStore: { list: async () => [] } as never,
+        serviceKeyRepo: {} as never,
+      },
+    });
+    await startBackgroundServices(container);
+    expect(startFn).toHaveBeenCalledOnce();
+  });
+
+  it("does not throw when proxy.start fails", async () => {
+    const container = createTestContainer({
+      fleet: {
+        manager: {} as never,
+        docker: {} as never,
+        proxy: {
+          start: async () => {
+            throw new Error("proxy start failed");
+          },
+          addRoute: async () => {},
+          removeRoute: () => {},
+          getRoutes: () => [],
+        } as never,
+        profileStore: { list: async () => [] } as never,
+        serviceKeyRepo: {} as never,
+      },
+    });
+    // Should not throw
+    const handles = await startBackgroundServices(container);
+    expect(handles).toBeDefined();
+  });
+});
+
+describe("gracefulShutdown", () => {
+  it("clears all intervals", async () => {
+    const container = createTestContainer();
+    const clearSpy = vi.spyOn(global, "clearInterval");
+
+    const interval1 = setInterval(() => {}, 10000);
+    const interval2 = setInterval(() => {}, 10000);
+
+    const handles = {
+      intervals: [interval1, interval2],
+      unsubscribes: [],
+    };
+
+    await gracefulShutdown(container, handles);
+
+    expect(clearSpy).toHaveBeenCalledWith(interval1);
+    expect(clearSpy).toHaveBeenCalledWith(interval2);
+    clearSpy.mockRestore();
+  });
+
+  it("calls all unsubscribe functions", async () => {
+    const container = createTestContainer();
+    const unsub1 = vi.fn();
+    const unsub2 = vi.fn();
+
+    const handles = {
+      intervals: [],
+      unsubscribes: [unsub1, unsub2],
+    };
+
+    await gracefulShutdown(container, handles);
+
+    expect(unsub1).toHaveBeenCalledOnce();
+    expect(unsub2).toHaveBeenCalledOnce();
+  });
+
+  it("calls pool.end()", async () => {
+    const endFn = vi.fn().mockResolvedValue(undefined);
+    const container = createTestContainer({
+      pool: { end: endFn } as never,
+    });
+
+    const handles = { intervals: [], unsubscribes: [] };
+
+    await gracefulShutdown(container, handles);
+
+    expect(endFn).toHaveBeenCalledOnce();
+  });
+});

package/src/server/__tests__/mount-routes.test.ts

@@ -0,0 +1,169 @@
+import { Hono } from "hono";
+import { describe, expect, it } from "vitest";
+import type { PlatformContainer } from "../container.js";
+import { mountRoutes } from "../mount-routes.js";
+import { createTestContainer } from "../test-container.js";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function defaultMountConfig() {
+  return {
+    provisionSecret: "test-secret",
+    cryptoServiceKey: "test-crypto-key",
+    platformDomain: "example.com",
+  };
+}
+
+function makeApp(container: PlatformContainer) {
+  const app = new Hono();
+  mountRoutes(app, container, defaultMountConfig());
+  return app;
+}
+
+async function req(app: Hono, method: string, path: string, opts?: RequestInit) {
+  const request = new Request(`http://localhost${path}`, { method, ...opts });
+  return app.request(request);
+}
+
+// ---------------------------------------------------------------------------
+// Minimal stubs for feature sub-containers
+// ---------------------------------------------------------------------------
+
+function stubCrypto(): PlatformContainer["crypto"] {
+  return {
+    chargeRepo: {} as never,
+    webhookSeenRepo: {} as never,
+  };
+}
+
+function stubStripe(): PlatformContainer["stripe"] {
+  return {
+    stripe: {} as never,
+    webhookSecret: "whsec_test",
+    customerRepo: {} as never,
+    processor: {
+      handleWebhook: async () => ({ ok: true }),
+    },
+  };
+}
+
+function stubFleet(): PlatformContainer["fleet"] {
+  return {
+    manager: {} as never,
+    docker: {} as never,
+    proxy: {
+      start: async () => {},
+      addRoute: async () => {},
+      removeRoute: () => {},
+      getRoutes: () => [],
+    } as never,
+    profileStore: { list: async () => [] } as never,
+    serviceKeyRepo: {} as never,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe("mountRoutes", () => {
+  // 1. Health endpoint always available
+  it("mounts /health endpoint", async () => {
+    const app = makeApp(createTestContainer());
+    const res = await req(app, "GET", "/health");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ ok: true });
+  });
+
+  // 2. Crypto webhook mounted when crypto enabled
+  it("mounts crypto webhook when crypto enabled", async () => {
+    const container = createTestContainer({ crypto: stubCrypto() });
+    const app = makeApp(container);
+    const res = await req(app, "POST", "/api/webhooks/crypto", {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    // Should return 401 (no auth), NOT 404 (not found)
+    expect(res.status).toBe(401);
+  });
+
+  // 3. Crypto webhook NOT mounted when crypto disabled
+  it("does not mount crypto webhook when crypto disabled", async () => {
+    const container = createTestContainer({ crypto: null });
+    const app = makeApp(container);
+    const res = await req(app, "POST", "/api/webhooks/crypto", {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  // 4. Stripe webhook mounted when stripe enabled
+  it("mounts stripe webhook when stripe enabled", async () => {
+    const container = createTestContainer({ stripe: stubStripe() });
+    const app = makeApp(container);
+    const res = await req(app, "POST", "/api/webhooks/stripe", {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    // Should return 400 (missing stripe-signature), NOT 404
+    expect(res.status).toBe(400);
+  });
+
+  // 5. Stripe webhook NOT mounted when stripe disabled
+  it("does not mount stripe webhook when stripe disabled", async () => {
+    const container = createTestContainer({ stripe: null });
+    const app = makeApp(container);
+    const res = await req(app, "POST", "/api/webhooks/stripe", {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  // 6. Provision webhook mounted when fleet enabled
+  it("mounts provision webhook when fleet enabled", async () => {
+    const container = createTestContainer({ fleet: stubFleet() });
+    const app = makeApp(container);
+    const res = await req(app, "POST", "/api/provision/create", {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    // Should return 401 (no auth), NOT 404
+    expect(res.status).toBe(401);
+  });
+
+  // 7. Provision webhook NOT mounted when fleet disabled
+  it("does not mount provision webhook when fleet disabled", async () => {
+    const container = createTestContainer({ fleet: null });
+    const app = makeApp(container);
+    const res = await req(app, "POST", "/api/provision/create", {
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({}),
+    });
+    expect(res.status).toBe(404);
+  });
+
+  // 8. Product-specific route plugins
+  it("mounts product-specific route plugins", async () => {
+    const container = createTestContainer();
+    const app = new Hono();
+    mountRoutes(app, container, defaultMountConfig(), [
+      {
+        path: "/api/custom",
+        handler: () => {
+          const sub = new Hono();
+          sub.get("/ping", (c) => c.json({ pong: true }));
+          return sub;
+        },
+      },
+    ]);
+    const res = await req(app, "GET", "/api/custom/ping");
+    expect(res.status).toBe(200);
+    const body = await res.json();
+    expect(body).toEqual({ pong: true });
+  });
+});

package/src/server/boot-config.ts

@@ -0,0 +1,84 @@
+/**
+ * BootConfig — declarative configuration for platformBoot().
+ *
+ * Products pass a BootConfig describing which features to enable and
+ * receive back a fully-wired Hono app + PlatformContainer.
+ */
+
+import type { Hono } from "hono";
+import type { PlatformContainer } from "./container.js";
+
+// ---------------------------------------------------------------------------
+// Feature flags
+// ---------------------------------------------------------------------------
+
+export interface FeatureFlags {
+  fleet: boolean;
+  crypto: boolean;
+  stripe: boolean;
+  gateway: boolean;
+  hotPool: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Route plugins
+// ---------------------------------------------------------------------------
+
+export interface RoutePlugin {
+  path: string;
+  handler: (container: PlatformContainer) => Hono;
+}
+
+// ---------------------------------------------------------------------------
+// Boot config
+// ---------------------------------------------------------------------------
+
+export interface BootConfig {
+  /** Short product identifier (e.g. "paperclip", "wopr", "holyship"). */
+  slug: string;
+
+  /** PostgreSQL connection string. */
+  databaseUrl: string;
+
+  /** Bind host (default "0.0.0.0"). */
+  host?: string;
+
+  /** Bind port (default 3001). */
+  port?: number;
+
+  /** Which optional feature slices to wire up. */
+  features: FeatureFlags;
+
+  /** Additional Hono sub-apps mounted after core routes. */
+  routes?: RoutePlugin[];
+
+  /** Required when features.stripe is true. */
+  stripeSecretKey?: string;
+
+  /** Required when features.stripe is true. */
+  stripeWebhookSecret?: string;
+
+  /** Service key for the crypto chain server webhook endpoint. */
+  cryptoServiceKey?: string;
+
+  /** Shared secret used to authenticate provision requests. */
+  provisionSecret: string;
+}
+
+// ---------------------------------------------------------------------------
+// Boot result
+// ---------------------------------------------------------------------------
+
+export interface BootResult {
+  /** The fully-wired Hono application. */
+  app: Hono;
+
+  /** The assembled DI container — useful for tests and ad-hoc access. */
+  container: PlatformContainer;
+
+  /** Start listening. Uses BootConfig.port unless overridden. */
+  start: (port?: number) => Promise<void>;
+
+  /** Graceful shutdown: drain connections, close pool. */
+  stop: () => Promise<void>;
+}

package/src/server/container.ts

@@ -0,0 +1,264 @@
+/**
+ * PlatformContainer — the central DI container for platform-core.
+ *
+ * Products compose a container at boot time, enabling only the feature
+ * slices they need. Nullable sub-containers (fleet, crypto, stripe,
+ * gateway, hotPool) let each product opt in without pulling unused deps.
+ */
+
+import type Docker from "dockerode";
+import type { Pool } from "pg";
+import type Stripe from "stripe";
+import type { IUserRoleRepository } from "../auth/user-role-repository.js";
+import type { ICryptoChargeRepository } from "../billing/crypto/charge-store.js";
+import type { IWebhookSeenRepository } from "../billing/webhook-seen-repository.js";
+import type { ILedger } from "../credits/ledger.js";
+import type { ITenantCustomerRepository } from "../credits/tenant-customer-repository.js";
+import type { DrizzleDb } from "../db/index.js";
+import type { FleetManager } from "../fleet/fleet-manager.js";
+import type { IProfileStore } from "../fleet/profile-store.js";
+import type { IServiceKeyRepository } from "../gateway/service-key-repository.js";
+import type { ProductConfig } from "../product-config/repository-types.js";
+import type { ProxyManagerInterface } from "../proxy/types.js";
+import type { IOrgMemberRepository } from "../tenancy/org-member-repository.js";
+import type { OrgService } from "../tenancy/org-service.js";
+import type { BootConfig } from "./boot-config.js";
+
+// ---------------------------------------------------------------------------
+// Feature sub-containers
+// ---------------------------------------------------------------------------
+
+export interface FleetServices {
+  manager: FleetManager;
+  docker: Docker;
+  proxy: ProxyManagerInterface;
+  profileStore: IProfileStore;
+  serviceKeyRepo: IServiceKeyRepository;
+}
+
+export interface CryptoServices {
+  chargeRepo: ICryptoChargeRepository;
+  webhookSeenRepo: IWebhookSeenRepository;
+}
+
+export interface StripeServices {
+  stripe: Stripe;
+  webhookSecret: string;
+  customerRepo: ITenantCustomerRepository;
+  processor: { handleWebhook(payload: Buffer, signature: string): Promise<unknown> };
+}
+
+export interface GatewayServices {
+  serviceKeyRepo: IServiceKeyRepository;
+}
+
+export interface HotPoolServices {
+  /** Start the pool manager (replenish loop + cleanup). */
+  start: () => Promise<{ stop: () => void }>;
+  /** Claim a warm instance from the pool. Returns null if empty. */
+  claim: (
+    name: string,
+    tenantId: string,
+    adminUser: { id: string; email: string; name: string },
+  ) => Promise<{ id: string; name: string; subdomain: string } | null>;
+  /** Get current pool size from DB. */
+  getPoolSize: () => Promise<number>;
+  /** Set pool size in DB. */
+  setPoolSize: (size: number) => Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Main container
+// ---------------------------------------------------------------------------
+
+export interface PlatformContainer {
+  db: DrizzleDb;
+  pool: Pool;
+  productConfig: ProductConfig;
+  creditLedger: ILedger;
+  orgMemberRepo: IOrgMemberRepository;
+  orgService: OrgService;
+  userRoleRepo: IUserRoleRepository;
+
+  /** Null when the product does not use fleet management. */
+  fleet: FleetServices | null;
+  /** Null when the product does not accept crypto payments. */
+  crypto: CryptoServices | null;
+  /** Null when the product does not use Stripe billing. */
+  stripe: StripeServices | null;
+  /** Null when the product does not expose a metered inference gateway. */
+  gateway: GatewayServices | null;
+  /** Null when the product does not use a hot-pool of pre-provisioned instances. */
+  hotPool: HotPoolServices | null;
+}
+
+// ---------------------------------------------------------------------------
+// buildContainer — construct a PlatformContainer from a BootConfig
+// ---------------------------------------------------------------------------
+
+/**
+ * Build a fully-wired PlatformContainer from a declarative BootConfig.
+ *
+ * Construction order mirrors the proven boot sequence from product index.ts
+ * files: DB pool -> Drizzle -> migrations -> productConfig -> credit ledger
+ * -> org repos -> org service -> user role repo -> feature services.
+ *
+ * Feature sub-containers (fleet, crypto, stripe, gateway) are only
+ * constructed when their corresponding feature flag is enabled in
+ * `bootConfig.features`. Disabled features yield `null`.
+ */
+export async function buildContainer(bootConfig: BootConfig): Promise<PlatformContainer> {
+  if (!bootConfig.databaseUrl) {
+    throw new Error("buildContainer: databaseUrl is required");
+  }
+
+  // 1. Database pool
+  const { Pool: PgPool } = await import("pg");
+  const pool: Pool = new PgPool({ connectionString: bootConfig.databaseUrl });
+
+  // 2. Drizzle ORM instance
+  const { createDb } = await import("../db/index.js");
+  const db = createDb(pool);
+
+  // 3. Run Drizzle migrations
+  const { migrate } = await import("drizzle-orm/node-postgres/migrator");
+  const path = await import("node:path");
+  const migrationsFolder = path.resolve(path.dirname(new URL(import.meta.url).pathname), "../../drizzle");
+  await migrate(db as never, { migrationsFolder });
+
+  // 4. Bootstrap product config from DB (auto-seeds from presets if needed)
+  const { platformBoot } = await import("../product-config/boot.js");
+  const { config: productConfig } = await platformBoot({ slug: bootConfig.slug, db });
+
+  // 5. Credit ledger
+  const { DrizzleLedger } = await import("../credits/ledger.js");
+  const creditLedger: ILedger = new DrizzleLedger(db as never);
+  await creditLedger.seedSystemAccounts();
+
+  // 6. Org repositories + OrgService
+  const { DrizzleOrgMemberRepository } = await import("../tenancy/org-member-repository.js");
+  const { DrizzleOrgRepository } = await import("../tenancy/drizzle-org-repository.js");
+  const { OrgService: OrgServiceClass } = await import("../tenancy/org-service.js");
+  const { BetterAuthUserRepository } = await import("../db/auth-user-repository.js");
+
+  const orgMemberRepo: IOrgMemberRepository = new DrizzleOrgMemberRepository(db as never);
+  const orgRepo = new DrizzleOrgRepository(db as never);
+  const authUserRepo = new BetterAuthUserRepository(pool);
+  const orgService = new OrgServiceClass(orgRepo, orgMemberRepo, db as never, {
+    userRepo: authUserRepo,
+  });
+
+  // 7. User role repository
+  const { DrizzleUserRoleRepository } = await import("../auth/user-role-repository.js");
+  const userRoleRepo: IUserRoleRepository = new DrizzleUserRoleRepository(db as never);
+
+  // 8. Fleet services (when enabled)
+  let fleet: FleetServices | null = null;
+  if (bootConfig.features.fleet) {
+    const { FleetManager: FleetManagerClass } = await import("../fleet/fleet-manager.js");
+    const { ProfileStore } = await import("../fleet/profile-store.js");
+    const { ProxyManager } = await import("../proxy/manager.js");
+    const { DrizzleServiceKeyRepository } = await import("../gateway/service-key-repository.js");
+    const DockerModule = await import("dockerode");
+    const DockerClass = DockerModule.default ?? DockerModule;
+
+    const docker: Docker = new (DockerClass as new () => Docker)();
+    const fleetDataDir = productConfig.fleet?.fleetDataDir ?? "/data/fleet";
+    const profileStore: IProfileStore = new ProfileStore(fleetDataDir);
+    const proxy: ProxyManagerInterface = new ProxyManager();
+    const serviceKeyRepo: IServiceKeyRepository = new DrizzleServiceKeyRepository(db as never);
+    const manager: FleetManager = new FleetManagerClass(
+      docker,
+      profileStore,
+      undefined, // platformDiscovery
+      undefined, // networkPolicy
+      proxy,
+    );
+
+    fleet = { manager, docker, proxy, profileStore, serviceKeyRepo };
+  }
+
+  // 9. Crypto services (when enabled)
+  let crypto: CryptoServices | null = null;
+  if (bootConfig.features.crypto) {
+    const { DrizzleCryptoChargeRepository } = await import("../billing/crypto/charge-store.js");
+    const { DrizzleWebhookSeenRepository } = await import("../billing/drizzle-webhook-seen-repository.js");
+
+    const chargeRepo: ICryptoChargeRepository = new DrizzleCryptoChargeRepository(db as never);
+    const webhookSeenRepo: IWebhookSeenRepository = new DrizzleWebhookSeenRepository(db as never);
+
+    crypto = { chargeRepo, webhookSeenRepo };
+  }
+
+  // 10. Stripe services (when enabled)
+  let stripe: StripeServices | null = null;
+  if (bootConfig.features.stripe && bootConfig.stripeSecretKey) {
+    const StripeModule = await import("stripe");
+    const StripeClass = StripeModule.default;
+    const stripeClient: Stripe = new StripeClass(bootConfig.stripeSecretKey);
+
+    const { DrizzleTenantCustomerRepository } = await import("../billing/stripe/tenant-store.js");
+    const { loadCreditPriceMap } = await import("../billing/stripe/credit-prices.js");
+    const { StripePaymentProcessor } = await import("../billing/stripe/stripe-payment-processor.js");
+
+    const customerRepo = new DrizzleTenantCustomerRepository(db as never);
+    const priceMap = loadCreditPriceMap();
+    const processor = new StripePaymentProcessor({
+      stripe: stripeClient,
+      tenantRepo: customerRepo,
+      webhookSecret: bootConfig.stripeWebhookSecret ?? "",
+      priceMap,
+      creditLedger,
+    });
+
+    stripe = {
+      stripe: stripeClient,
+      webhookSecret: bootConfig.stripeWebhookSecret ?? "",
+      customerRepo,
+      processor,
+    };
+  }
+
+  // 11. Gateway services (when enabled)
+  let gateway: GatewayServices | null = null;
+  if (bootConfig.features.gateway) {
+    const { DrizzleServiceKeyRepository } = await import("../gateway/service-key-repository.js");
+    const serviceKeyRepo: IServiceKeyRepository = new DrizzleServiceKeyRepository(db as never);
+    gateway = { serviceKeyRepo };
+  }
+
+  // 12. Build the container (hotPool bound after construction)
+  const result: PlatformContainer = {
+    db,
+    pool,
+    productConfig,
+    creditLedger,
+    orgMemberRepo,
+    orgService,
+    userRoleRepo,
+    fleet,
+    crypto,
+    stripe,
+    gateway,
+    hotPool: null,
+  };
+
+  // Bind hot pool after container construction (closures need the full container)
+  if (bootConfig.features.hotPool && fleet) {
+    const { startHotPool, setPoolSize: setSize, getPoolSize: getSize } = await import("./services/hot-pool.js");
+    const { claimPoolInstance } = await import("./services/hot-pool-claim.js");
+    const { DrizzlePoolRepository } = await import("./services/pool-repository.js");
+    const poolRepo = new DrizzlePoolRepository(pool);
+
+    const hotPoolConfig = { provisionSecret: bootConfig.provisionSecret };
+    result.hotPool = {
+      start: () => startHotPool(result, poolRepo, hotPoolConfig),
+      claim: (name, tenantId, adminUser) =>
+        claimPoolInstance(result, poolRepo, name, tenantId, adminUser, hotPoolConfig),
+      getPoolSize: () => getSize(poolRepo),
+      setPoolSize: (size) => setSize(poolRepo, size),
+    };
+  }
+
+  return result;
+}