@checkstack/backend 0.9.0 → 0.10.0

package/src/plugin-manager/api-router.ts

@@ -1,6 +1,7 @@
 import type { Hono, Context } from "hono";
 import type { SafeDatabase } from "@checkstack/backend-api";
 import { RPCHandler } from "@orpc/server/fetch";
+import { OpenAPIHandler } from "@orpc/openapi/fetch";
 import {
   coreServices,
   AuthService,
@@ -23,9 +24,182 @@ import type { PluginMetadata } from "@checkstack/common";
 import { rootLogger } from "../logger";
 import { extractErrorMessage } from "@checkstack/common";
 
+interface RouteHandlerDeps {
+  registry: ServiceRegistry;
+  pluginRpcRouters: Map<string, unknown>;
+  pluginMetadataRegistry: Map<string, PluginMetadata>;
+}
+
+interface ResolvedRequestContext {
+  context: RpcContext;
+  logger: Logger;
+}
+
+type ContextResult =
+  | { ok: true; resolved: ResolvedRequestContext }
+  | { ok: false; response: Response };
+
+function createServiceGetter(registry: ServiceRegistry) {
+  return async function getService<T>(ref: {
+    id: string;
+    T: T;
+  }): Promise<T | undefined> {
+    try {
+      return await registry.get(ref, { pluginId: "core" });
+    } catch {
+      return undefined;
+    }
+  };
+}
+
+/**
+ * Resolve auth + core services and build the per-request RpcContext.
+ * Shared between the oRPC `/api/*` handler and the REST `/rest/*` handler.
+ */
+async function resolveRequestContext({
+  c,
+  pluginId,
+  deps,
+}: {
+  c: Context;
+  pluginId: string;
+  deps: RouteHandlerDeps;
+}): Promise<ContextResult> {
+  const getService = createServiceGetter(deps.registry);
+  const pathname = new URL(c.req.raw.url).pathname;
+
+  const logger = await getService(coreServices.logger);
+  const auth = await getService(coreServices.auth);
+  const db = await getService(coreServices.database);
+  const fetch = await getService(coreServices.fetch);
+  const healthCheckRegistry = await getService(
+    coreServices.healthCheckRegistry,
+  );
+  const collectorRegistry = await getService(coreServices.collectorRegistry);
+  const queuePluginRegistry = await getService(
+    coreServices.queuePluginRegistry,
+  );
+  const queueManager = await getService(coreServices.queueManager);
+  const cachePluginRegistry = await getService(
+    coreServices.cachePluginRegistry,
+  );
+  const cacheManager = await getService(coreServices.cacheManager);
+  const eventBus = await getService(coreServices.eventBus);
+
+  if (
+    !auth ||
+    !logger ||
+    !db ||
+    !fetch ||
+    !healthCheckRegistry ||
+    !collectorRegistry ||
+    !queuePluginRegistry ||
+    !queueManager ||
+    !cachePluginRegistry ||
+    !cacheManager ||
+    !eventBus
+  ) {
+    const missing = [
+      !auth && "auth",
+      !logger && "logger",
+      !db && "db",
+      !fetch && "fetch",
+      !healthCheckRegistry && "healthCheckRegistry",
+      !collectorRegistry && "collectorRegistry",
+      !queuePluginRegistry && "queuePluginRegistry",
+      !queueManager && "queueManager",
+      !cachePluginRegistry && "cachePluginRegistry",
+      !cacheManager && "cacheManager",
+      !eventBus && "eventBus",
+    ]
+      .filter(Boolean)
+      .join(", ");
+    (logger ?? rootLogger).error(
+      `${pathname}: core services not initialized — missing: ${missing}`,
+    );
+    return {
+      ok: false,
+      response: c.json({ error: "Core services not initialized" }, 500),
+    };
+  }
+
+  const user = await (auth as AuthService).authenticate(c.req.raw);
+
+  const emitHook: EmitHookFn = async <T>(hook: Hook<T>, payload: T) => {
+    await (eventBus as EventBus).emit(hook, payload);
+  };
+
+  const pluginMetadata: PluginMetadata | undefined =
+    deps.pluginMetadataRegistry.get(pluginId);
+
+  if (!pluginMetadata) {
+    (logger as Logger).error(
+      `${pathname}: no plugin metadata registered for pluginId='${pluginId}'. ` +
+        `Regular plugins populate this during register(); core routers must call ` +
+        `pluginManager.registerCorePluginMetadata().`,
+    );
+    return {
+      ok: false,
+      response: c.json({ error: "Plugin metadata not found in registry" }, 500),
+    };
+  }
+
+  const context: RpcContext = {
+    pluginMetadata,
+    auth: auth as AuthService,
+    logger: logger as Logger,
+    db: db as SafeDatabase<Record<string, unknown>>,
+    fetch: fetch as Fetch,
+    healthCheckRegistry: healthCheckRegistry as HealthCheckRegistry,
+    collectorRegistry: collectorRegistry as CollectorRegistry,
+    queuePluginRegistry: queuePluginRegistry as QueuePluginRegistry,
+    queueManager: queueManager as QueueManager,
+    cachePluginRegistry: cachePluginRegistry as CachePluginRegistry,
+    cacheManager: cacheManager as CacheManager,
+    user,
+    emitHook,
+  };
+
+  return { ok: true, resolved: { context, logger: logger as Logger } };
+}
+
+function buildRpcRouter(
+  pluginRpcRouters: Map<string, unknown>,
+): Record<string, unknown> {
+  const rootRpcRouter: Record<string, unknown> = {};
+  for (const [pluginId, router] of pluginRpcRouters.entries()) {
+    rootRpcRouter[pluginId] = router;
+  }
+  return rootRpcRouter;
+}
+
+function logHandlerError({
+  error,
+  pathname,
+  logger,
+  protocolLabel,
+}: {
+  error: unknown;
+  pathname: string;
+  logger: Logger | undefined;
+  protocolLabel: string;
+}) {
+  const target = (logger ?? rootLogger) as Logger;
+  target.error(
+    `${protocolLabel} ${pathname} failed: ${extractErrorMessage(error)}`,
+  );
+  const stack =
+    error !== null && typeof error === "object" && "stack" in error
+      ? (error as { stack: string }).stack
+      : undefined;
+  if (stack) {
+    target.error(`Stack trace: ${stack}`);
+  }
+}
+
 /**
  * Creates the API route handler for Hono.
- * Extracted from PluginManager for better organization.
+ * Serves oRPC's native RPC wire protocol at /api/:pluginId/*.
  */
 export function createApiRouteHandler({
   registry,
@@ -38,54 +212,36 @@ export function createApiRouteHandler({
   pluginHttpHandlers: Map<string, (req: Request) => Promise<Response>>;
   pluginMetadataRegistry: Map<string, PluginMetadata>;
 }) {
-  // Helper to get service from registry
-  async function getService<T>(ref: {
-    id: string;
-    T: T;
-  }): Promise<T | undefined> {
-    try {
-      return await registry.get(ref, { pluginId: "core" });
-    } catch {
-      return undefined;
-    }
-  }
+  const deps: RouteHandlerDeps = {
+    registry,
+    pluginRpcRouters,
+    pluginMetadataRegistry,
+  };
 
   return async function handleApiRequest(c: Context) {
-    // Extract pluginId from Hono path parameter (/api/:pluginId/*)
     const pluginId = c.req.param("pluginId") || "";
     const pathname = new URL(c.req.raw.url).pathname;
 
-    // Build RPC handler lazily at request time
-    // This ensures all plugins registered during init are included
-    const rootRpcRouter: Record<string, unknown> = {};
-    for (const [pluginId, router] of pluginRpcRouters.entries()) {
-      rootRpcRouter[pluginId] = router;
-    }
-
-    // Resolve logger first for use in interceptor
-    const logger = await getService(coreServices.logger);
+    const result = await resolveRequestContext({ c, pluginId, deps });
+    if (!result.ok) return result.response;
+    const { context, logger } = result.resolved;
 
     const rpcHandler = new RPCHandler(
-      rootRpcRouter as ConstructorParameters<typeof RPCHandler>[0],
+      buildRpcRouter(pluginRpcRouters) as ConstructorParameters<
+        typeof RPCHandler
+      >[0],
       {
         interceptors: [
           async ({ next, ...rest }) => {
             try {
               return await next(rest);
             } catch (error) {
-              const target = (logger ?? rootLogger) as Logger;
-              target.error(
-                `RPC ${pathname} failed: ${extractErrorMessage(error)}`,
-              );
-              const stack =
-                error !== null &&
-                typeof error === "object" &&
-                "stack" in error
-                  ? (error as { stack: string }).stack
-                  : undefined;
-              if (stack) {
-                target.error(`Stack trace: ${stack}`);
-              }
+              logHandlerError({
+                error,
+                pathname,
+                logger,
+                protocolLabel: "RPC",
+              });
               throw error;
             }
           },
@@ -93,93 +249,6 @@ export function createApiRouteHandler({
       },
     );
 
-    // Resolve core services for RPC context
-    const auth = await getService(coreServices.auth);
-    const db = await getService(coreServices.database);
-    const fetch = await getService(coreServices.fetch);
-    const healthCheckRegistry = await getService(
-      coreServices.healthCheckRegistry,
-    );
-    const collectorRegistry = await getService(coreServices.collectorRegistry);
-    const queuePluginRegistry = await getService(
-      coreServices.queuePluginRegistry,
-    );
-    const queueManager = await getService(coreServices.queueManager);
-    const cachePluginRegistry = await getService(
-      coreServices.cachePluginRegistry,
-    );
-    const cacheManager = await getService(coreServices.cacheManager);
-    const eventBus = await getService(coreServices.eventBus);
-
-    if (
-      !auth ||
-      !logger ||
-      !db ||
-      !fetch ||
-      !healthCheckRegistry ||
-      !collectorRegistry ||
-      !queuePluginRegistry ||
-      !queueManager ||
-      !cachePluginRegistry ||
-      !cacheManager ||
-      !eventBus
-    ) {
-      const missing = [
-        !auth && "auth",
-        !logger && "logger",
-        !db && "db",
-        !fetch && "fetch",
-        !healthCheckRegistry && "healthCheckRegistry",
-        !collectorRegistry && "collectorRegistry",
-        !queuePluginRegistry && "queuePluginRegistry",
-        !queueManager && "queueManager",
-        !cachePluginRegistry && "cachePluginRegistry",
-        !cacheManager && "cacheManager",
-        !eventBus && "eventBus",
-      ].filter(Boolean).join(", ");
-      (logger ?? rootLogger).error(
-        `${pathname}: core services not initialized — missing: ${missing}`,
-      );
-      return c.json({ error: "Core services not initialized" }, 500);
-    }
-
-    const user = await (auth as AuthService).authenticate(c.req.raw);
-
-    // Create emitHook function using eventBus
-    const emitHook: EmitHookFn = async <T>(hook: Hook<T>, payload: T) => {
-      await (eventBus as EventBus).emit(hook, payload);
-    };
-
-    // Lookup plugin metadata from registry
-    const pluginMetadata: PluginMetadata | undefined =
-      pluginMetadataRegistry.get(pluginId);
-
-    if (!pluginMetadata) {
-      (logger as Logger).error(
-        `${pathname}: no plugin metadata registered for pluginId='${pluginId}'. ` +
-          `Regular plugins populate this during register(); core routers must call ` +
-          `pluginManager.registerCorePluginMetadata().`,
-      );
-      return c.json({ error: "Plugin metadata not found in registry" }, 500);
-    }
-
-    const context: RpcContext = {
-      pluginMetadata,
-      auth: auth as AuthService,
-      logger: logger as Logger,
-      db: db as SafeDatabase<Record<string, unknown>>,
-      fetch: fetch as Fetch,
-      healthCheckRegistry: healthCheckRegistry as HealthCheckRegistry,
-      collectorRegistry: collectorRegistry as CollectorRegistry,
-      queuePluginRegistry: queuePluginRegistry as QueuePluginRegistry,
-      queueManager: queueManager as QueueManager,
-      cachePluginRegistry: cachePluginRegistry as CachePluginRegistry,
-      cacheManager: cacheManager as CacheManager,
-      user,
-      emitHook,
-    };
-
-    // 1. Try oRPC first
     const { matched, response } = await rpcHandler.handle(c.req.raw, {
       prefix: "/api",
       context,
@@ -191,8 +260,7 @@ export function createApiRouteHandler({
 
     logger.debug(`RPC mismatch for: ${c.req.method} ${pathname}`);
 
-    // 2. Try native handlers
-    // Sort by path length (descending) to ensure more specific paths are tried first
+    // Fall through to native plugin HTTP handlers (sorted longest-prefix first)
     const sortedHandlers = [...pluginHttpHandlers.entries()].toSorted(
       function (a, b) {
         return b[0].length - a[0].length;
@@ -209,6 +277,71 @@ export function createApiRouteHandler({
   };
 }
 
+/**
+ * Creates the REST route handler for Hono.
+ * Serves the REST/OpenAPI shape of the same oRPC contract at /rest/:pluginId/*.
+ * Standard JSON bodies / query params work here — matches /api/openapi.json.
+ */
+export function createRestRouteHandler({
+  registry,
+  pluginRpcRouters,
+  pluginMetadataRegistry,
+}: {
+  registry: ServiceRegistry;
+  pluginRpcRouters: Map<string, unknown>;
+  pluginMetadataRegistry: Map<string, PluginMetadata>;
+}) {
+  const deps: RouteHandlerDeps = {
+    registry,
+    pluginRpcRouters,
+    pluginMetadataRegistry,
+  };
+
+  return async function handleRestRequest(c: Context) {
+    const pluginId = c.req.param("pluginId") || "";
+    const pathname = new URL(c.req.raw.url).pathname;
+
+    const result = await resolveRequestContext({ c, pluginId, deps });
+    if (!result.ok) return result.response;
+    const { context, logger } = result.resolved;
+
+    const restHandler = new OpenAPIHandler(
+      buildRpcRouter(pluginRpcRouters) as ConstructorParameters<
+        typeof OpenAPIHandler
+      >[0],
+      {
+        interceptors: [
+          async ({ next, ...rest }) => {
+            try {
+              return await next(rest);
+            } catch (error) {
+              logHandlerError({
+                error,
+                pathname,
+                logger,
+                protocolLabel: "REST",
+              });
+              throw error;
+            }
+          },
+        ],
+      },
+    );
+
+    const { matched, response } = await restHandler.handle(c.req.raw, {
+      prefix: "/rest",
+      context,
+    });
+
+    if (matched) {
+      return c.newResponse(response.body, response);
+    }
+
+    logger.debug(`REST mismatch for: ${c.req.method} ${pathname}`);
+    return c.json({ error: "Not Found" }, 404);
+  };
+}
+
 /**
  * Registers the /api/:pluginId/* route with Hono.
  */
@@ -218,3 +351,13 @@ export function registerApiRoute(
 ) {
   rootRouter.all("/api/:pluginId/*", handler);
 }
+
+/**
+ * Registers the /rest/:pluginId/* route with Hono.
+ */
+export function registerRestRoute(
+  rootRouter: Hono,
+  handler: ReturnType<typeof createRestRouteHandler>,
+) {
+  rootRouter.all("/rest/:pluginId/*", handler);
+}

package/src/plugin-manager/plugin-loader.ts

@@ -29,7 +29,12 @@ import {
 } from "../utils/plugin-discovery";
 import type { InitCallback, PendingInit } from "./types";
 import { sortPlugins } from "./dependency-sorter";
-import { createApiRouteHandler, registerApiRoute } from "./api-router";
+import {
+  createApiRouteHandler,
+  createRestRouteHandler,
+  registerApiRoute,
+  registerRestRoute,
+} from "./api-router";
 import type { ExtensionPointManager } from "./extension-points";
 import { Router } from "@orpc/server";
 import { AnyContractRouter } from "@orpc/contract";
@@ -302,7 +307,10 @@ export async function loadPlugins({
   const sortedIds = sortPlugins({ pendingInits, providedBy, logger });
   rootLogger.debug(`✅ Initialization Order: ${sortedIds.join(" -> ")}`);
 
-  // Register /api/* route BEFORE plugin initialization
+  // Register /api/* (oRPC wire format) and /rest/* (REST/OpenAPI shape) routes
+  // BEFORE plugin initialization. Both routes share the same plugin RPC routers
+  // and per-request context; they differ only in how the handler decodes the
+  // request and matches it to a procedure.
   const apiHandler = createApiRouteHandler({
     registry: deps.registry,
     pluginRpcRouters: deps.pluginRpcRouters,
@@ -311,6 +319,13 @@ export async function loadPlugins({
   });
   registerApiRoute(rootRouter, apiHandler);
 
+  const restHandler = createRestRouteHandler({
+    registry: deps.registry,
+    pluginRpcRouters: deps.pluginRpcRouters,
+    pluginMetadataRegistry: deps.pluginMetadataRegistry,
+  });
+  registerRestRoute(rootRouter, restHandler);
+
   // Routes are now registered on the root router. Signal readiness so the
   // server can stop blocking incoming requests in `waitForInit()`. We open
   // the gate here (BEFORE Phase 2 / Phase 3) so that:

package/src/services/cache-manager.test.ts

@@ -0,0 +1,172 @@
+import { describe, it, expect, beforeEach } from "bun:test";
+import { z } from "zod";
+import { CacheManagerImpl } from "./cache-manager";
+import { CachePluginRegistryImpl } from "./cache-plugin-registry";
+import type { CachePlugin, CacheProvider, CacheStats } from "@checkstack/cache-api";
+import type { ConfigService, Logger } from "@checkstack/backend-api";
+import { createMockLogger } from "@checkstack/test-utils-backend";
+
+class FakeInMemoryCache implements CacheProvider {
+  store = new Map<string, unknown>();
+  hits = 0;
+  misses = 0;
+
+  async get<T>(key: string): Promise<T | undefined> {
+    if (this.store.has(key)) {
+      this.hits++;
+      return this.store.get(key) as T;
+    }
+    this.misses++;
+    return undefined;
+  }
+  async set<T>(key: string, value: T): Promise<void> {
+    this.store.set(key, value);
+  }
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+  async deleteByPrefix(): Promise<number> {
+    return 0;
+  }
+  async has(key: string): Promise<boolean> {
+    return this.store.has(key);
+  }
+  async getStats(): Promise<CacheStats> {
+    return {
+      keyCount: this.store.size,
+      sizeBytes: null,
+      hits: this.hits,
+      misses: this.misses,
+      scope: "instance",
+    };
+  }
+}
+
+const memoryConfigSchema = z.record(z.string(), z.unknown());
+
+const createMemoryPlugin = (
+  factory: () => FakeInMemoryCache,
+): CachePlugin<unknown> => ({
+  id: "memory",
+  displayName: "Memory",
+  configVersion: 1,
+  configSchema: memoryConfigSchema,
+  createProvider: () => factory(),
+});
+
+class StubConfigService implements ConfigService {
+  store = new Map<string, unknown>();
+  async set<T>(configId: string, _s: unknown, _v: number, data: T) {
+    this.store.set(configId, data);
+  }
+  async get<T>(configId: string): Promise<T | undefined> {
+    return this.store.get(configId) as T | undefined;
+  }
+  async getRedacted<T>(configId: string): Promise<Partial<T> | undefined> {
+    return this.store.get(configId) as Partial<T> | undefined;
+  }
+  async delete(configId: string): Promise<void> {
+    this.store.delete(configId);
+  }
+  async list(): Promise<string[]> {
+    return [...this.store.keys()];
+  }
+}
+
+describe("CacheManagerImpl provider proxy", () => {
+  let registry: CachePluginRegistryImpl;
+  let configService: StubConfigService;
+  let logger: Logger;
+  let manager: CacheManagerImpl;
+  let instances: FakeInMemoryCache[];
+
+  beforeEach(() => {
+    registry = new CachePluginRegistryImpl();
+    configService = new StubConfigService();
+    logger = createMockLogger() as unknown as Logger;
+    instances = [];
+    registry.register(
+      createMemoryPlugin(() => {
+        const inst = new FakeInMemoryCache();
+        instances.push(inst);
+        return inst;
+      }),
+    );
+    manager = new CacheManagerImpl(registry, configService, logger);
+  });
+
+  it("returns the same proxy reference across calls", async () => {
+    const a = manager.getProvider();
+    const b = manager.getProvider();
+    expect(a).toBe(b);
+  });
+
+  it("delegates writes to the active provider after loadConfiguration", async () => {
+    const provider = manager.getProvider();
+    await manager.loadConfiguration();
+    await provider.set("foo", "bar");
+    expect(instances[0].store.get("foo")).toBe("bar");
+  });
+
+  it("keeps a captured proxy reference live across setActiveBackend", async () => {
+    await manager.loadConfiguration();
+    const captured = manager.getProvider();
+    await captured.set("before", 1);
+
+    await manager.setActiveBackend("memory", {
+      maxEntries: 5000,
+      sweepIntervalMs: 30_000,
+    });
+
+    // The captured reference must now write to the NEW active provider,
+    // not the orphaned old one.
+    await captured.set("after", 2);
+
+    const oldInstance = instances[0];
+    const newInstance = instances.at(-1)!;
+    expect(oldInstance).not.toBe(newInstance);
+    expect(oldInstance.store.has("after")).toBe(false);
+    expect(newInstance.store.has("after")).toBe(true);
+  });
+
+  it("getStats reads from the currently active provider", async () => {
+    await manager.loadConfiguration();
+    const provider = manager.getProvider();
+    await provider.set("k1", "v1");
+    await provider.get("k1"); // hit
+    await provider.get("missing"); // miss
+
+    const stats = await provider.getStats!();
+    expect(stats.keyCount).toBe(1);
+    expect(stats.hits).toBe(1);
+    expect(stats.misses).toBe(1);
+  });
+
+  it("getStats returns all-null when active provider has no getStats impl", async () => {
+    // Plugin whose provider doesn't implement getStats.
+    const minimalPlugin: CachePlugin<unknown> = {
+      id: "noStats",
+      displayName: "No stats",
+      configVersion: 1,
+      configSchema: memoryConfigSchema,
+      createProvider: (): CacheProvider => ({
+        get: async () => undefined,
+        set: async () => {},
+        delete: async () => {},
+        deleteByPrefix: async () => 0,
+        has: async () => false,
+      }),
+    };
+    registry.register(minimalPlugin);
+
+    await manager.setActiveBackend("noStats", {});
+    const stats = await manager.getProvider().getStats!();
+    expect(stats).toEqual({
+      keyCount: null,
+      sizeBytes: null,
+      hits: null,
+      misses: null,
+      scope: "instance",
+    });
+  });
+});