@checkstack/backend 0.0.2

package/src/plugin-manager/core-services.ts

@@ -0,0 +1,312 @@
+import { Pool } from "pg";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { createORPCClient } from "@orpc/client";
+import { RPCLink } from "@orpc/client/fetch";
+import {
+  coreServices,
+  AuthService,
+  authenticationStrategyServiceRef,
+  RpcService,
+  RpcClient,
+  EventBus as IEventBus,
+  AuthenticationStrategy,
+} from "@checkstack/backend-api";
+import { AuthApi } from "@checkstack/auth-common";
+import type { ServiceRegistry } from "../services/service-registry";
+import { rootLogger } from "../logger";
+import { db } from "../db";
+import { jwtService } from "../services/jwt";
+import { CoreHealthCheckRegistry } from "../services/health-check-registry";
+import { EventBus } from "../services/event-bus.js";
+import { getPluginSchemaName } from "@checkstack/drizzle-helper";
+
+/**
+ * Check if a PostgreSQL schema exists.
+ */
+async function schemaExists(pool: Pool, schemaName: string): Promise<boolean> {
+  const result = await pool.query(
+    "SELECT 1 FROM information_schema.schemata WHERE schema_name = $1",
+    [schemaName]
+  );
+  return result.rows.length > 0;
+}
+
+/**
+ * Registers all core services with the service registry.
+ * Extracted from PluginManager for better organization.
+ */
+export function registerCoreServices({
+  registry,
+  adminPool,
+  pluginRpcRouters,
+  pluginHttpHandlers,
+  pluginContractRegistry,
+}: {
+  registry: ServiceRegistry;
+  adminPool: Pool;
+  pluginRpcRouters: Map<string, unknown>;
+  pluginHttpHandlers: Map<string, (req: Request) => Promise<Response>>;
+  pluginContractRegistry: Map<string, unknown>;
+}) {
+  // 1. Database Factory (Scoped)
+  registry.registerFactory(coreServices.database, async (metadata) => {
+    const { pluginId, previousPluginIds } = metadata;
+    const assignedSchema = getPluginSchemaName(pluginId);
+
+    // Pre-flight: Check if this is a schema rename scenario
+    if (previousPluginIds && previousPluginIds.length > 0) {
+      for (const oldId of previousPluginIds) {
+        const oldSchema = getPluginSchemaName(oldId);
+        const oldExists = await schemaExists(adminPool, oldSchema);
+        const newExists = await schemaExists(adminPool, assignedSchema);
+
+        if (oldExists && !newExists) {
+          rootLogger.info(
+            `🔄 Renaming schema ${oldSchema} → ${assignedSchema} for plugin ${pluginId}`
+          );
+          await adminPool.query(
+            `ALTER SCHEMA "${oldSchema}" RENAME TO "${assignedSchema}"`
+          );
+          break; // Only one rename needed
+        }
+      }
+    }
+
+    // Ensure Schema Exists (creates if not already renamed/created)
+    await adminPool.query(`CREATE SCHEMA IF NOT EXISTS "${assignedSchema}"`);
+
+    // Create Scoped Connection
+    const baseUrl = process.env.DATABASE_URL;
+    if (!baseUrl) throw new Error("DATABASE_URL is not defined");
+
+    const connector = baseUrl.includes("?") ? "&" : "?";
+    const scopedUrl = `${baseUrl}${connector}options=-c%20search_path%3D${assignedSchema}`;
+
+    const pluginPool = new Pool({ connectionString: scopedUrl });
+    return drizzle(pluginPool);
+  });
+
+  // 2. Logger Factory
+  registry.registerFactory(coreServices.logger, (metadata) => {
+    return rootLogger.child({ plugin: metadata.pluginId });
+  });
+
+  // 3. Auth Factory (Scoped)
+  // Cache for anonymous permissions to avoid repeated DB queries
+  let anonymousPermissionsCache: string[] | undefined;
+  let anonymousCacheTime = 0;
+  const CACHE_TTL_MS = 60_000; // 1 minute cache
+
+  registry.registerFactory(coreServices.auth, (metadata) => {
+    const { pluginId } = metadata;
+    const authService: AuthService = {
+      authenticate: async (request: Request) => {
+        const authHeader = request.headers.get("Authorization");
+        const token = authHeader?.replace("Bearer ", "");
+
+        // Strategy A: Service Token (backend-to-backend)
+        if (token) {
+          const payload = await jwtService.verify(token);
+          if (payload && payload.service) {
+            // Service tokens return ServiceUser type
+            return {
+              type: "service" as const,
+              pluginId: payload.service as string,
+            };
+          }
+        }
+
+        // Strategy B: User Token (via registered strategy)
+        try {
+          const authStrategy = await registry.get(
+            authenticationStrategyServiceRef,
+            metadata
+          );
+          if (authStrategy) {
+            // AuthenticationStrategy.validate() returns RealUser | undefined
+            return await (authStrategy as AuthenticationStrategy).validate(
+              request
+            );
+          }
+        } catch {
+          // No strategy registered yet
+        }
+      },
+
+      getCredentials: async () => {
+        const token = await jwtService.sign({ service: pluginId }, "5m");
+        return { headers: { Authorization: `Bearer ${token}` } };
+      },
+
+      getAnonymousPermissions: async (): Promise<string[]> => {
+        const now = Date.now();
+        // Return cached value if still valid
+        if (
+          anonymousPermissionsCache !== undefined &&
+          now - anonymousCacheTime < CACHE_TTL_MS
+        ) {
+          return anonymousPermissionsCache;
+        }
+
+        // Use RPC client to call auth-backend's getAnonymousPermissions endpoint
+        try {
+          const rpcClient = await registry.get(coreServices.rpcClient, {
+            pluginId: "core",
+          });
+          const authClient = rpcClient.forPlugin(AuthApi);
+          const permissions = await authClient.getAnonymousPermissions();
+
+          // Update cache
+          anonymousPermissionsCache = permissions;
+          anonymousCacheTime = now;
+
+          return permissions;
+        } catch (error) {
+          // RPC client not available yet (during startup), return empty
+          rootLogger.warn(
+            `[auth] getAnonymousPermissions: RPC failed, returning empty array. Error: ${error}`
+          );
+          return [];
+        }
+      },
+    };
+    return authService;
+  });
+
+  // 4. Fetch Factory (Scoped)
+  registry.registerFactory(coreServices.fetch, async (metadata) => {
+    const auth = await registry.get(coreServices.auth, metadata);
+    const apiBaseUrl = process.env.INTERNAL_URL || "http://localhost:3000";
+
+    const fetchWithAuth = async (
+      input: RequestInfo | URL,
+      init?: RequestInit
+    ) => {
+      const { headers: authHeaders } = await auth.getCredentials();
+      const mergedHeaders = new Headers(init?.headers);
+      for (const [k, v] of Object.entries(authHeaders)) {
+        mergedHeaders.set(k, v);
+      }
+      return fetch(input, { ...init, headers: mergedHeaders });
+    };
+
+    const forPlugin = (targetPluginId: string) => {
+      const pluginBaseUrl = `${apiBaseUrl}/api/${targetPluginId}`;
+
+      const pluginFetch = async (path: string, init?: RequestInit) => {
+        const url = `${pluginBaseUrl}${path.startsWith("/") ? "" : "/"}${path}`;
+        return fetchWithAuth(url, init);
+      };
+
+      return {
+        fetch: pluginFetch,
+        get: (path: string, init?: RequestInit) =>
+          pluginFetch(path, { ...init, method: "GET" }),
+        post: (path: string, body?: unknown, init?: RequestInit) =>
+          pluginFetch(path, {
+            ...init,
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...init?.headers },
+            body: body ? JSON.stringify(body) : undefined,
+          }),
+        put: (path: string, body?: unknown, init?: RequestInit) =>
+          pluginFetch(path, {
+            ...init,
+            method: "PUT",
+            headers: { "Content-Type": "application/json", ...init?.headers },
+            body: body ? JSON.stringify(body) : undefined,
+          }),
+        patch: (path: string, body?: unknown, init?: RequestInit) =>
+          pluginFetch(path, {
+            ...init,
+            method: "PATCH",
+            headers: { "Content-Type": "application/json", ...init?.headers },
+            body: body ? JSON.stringify(body) : undefined,
+          }),
+        delete: (path: string, init?: RequestInit) =>
+          pluginFetch(path, { ...init, method: "DELETE" }),
+      };
+    };
+
+    return {
+      fetch: fetchWithAuth,
+      forPlugin,
+    };
+  });
+
+  // 5. RPC Client Factory (Scoped, Typed)
+  registry.registerFactory(coreServices.rpcClient, async (metadata) => {
+    const fetchService = await registry.get(coreServices.fetch, metadata);
+    const apiBaseUrl = process.env.INTERNAL_URL || "http://localhost:3000";
+
+    // Create RPC Link using the fetch service (already has auth)
+    const link = new RPCLink({
+      url: `${apiBaseUrl}/api`,
+      fetch: fetchService.fetch,
+    });
+
+    const client = createORPCClient(link);
+
+    const rpcClient: RpcClient = {
+      forPlugin(def) {
+        // Type safety is provided by the RpcClient interface - InferClient<T>
+        // extracts the typed client from the ClientDefinition passed in
+        return (client as Record<string, unknown>)[def.pluginId] as never;
+      },
+    };
+
+    return rpcClient;
+  });
+
+  // 6. Health Check Registry (Global Singleton)
+  const healthCheckRegistry = new CoreHealthCheckRegistry();
+  registry.registerFactory(
+    coreServices.healthCheckRegistry,
+    () => healthCheckRegistry
+  );
+
+  // 7. RPC Service (Scoped Factory - uses pluginId for path derivation)
+  registry.registerFactory(coreServices.rpc, (metadata) => {
+    const { pluginId } = metadata;
+    return {
+      registerRouter: (router: unknown, contract: unknown): void => {
+        pluginRpcRouters.set(pluginId, router);
+        pluginContractRegistry.set(pluginId, contract);
+        rootLogger.debug(
+          `   -> Registered oRPC router and contract for '${pluginId}' at '/api/${pluginId}'`
+        );
+      },
+      registerHttpHandler: (
+        handler: (req: Request) => Promise<Response>,
+        path = "/"
+      ): void => {
+        const fullPath = `/api/${pluginId}${path === "/" ? "" : path}`;
+        pluginHttpHandlers.set(fullPath, handler);
+        rootLogger.debug(
+          `   -> Registered HTTP handler for '${pluginId}' at '${fullPath}'`
+        );
+      },
+    } satisfies RpcService;
+  });
+
+  // 8. Config Service (Scoped Factory)
+  registry.registerFactory(coreServices.config, async (metadata) => {
+    const { ConfigServiceImpl } = await import("../services/config-service.js");
+    return new ConfigServiceImpl(metadata.pluginId, db);
+  });
+
+  // 9. EventBus (Global Singleton)
+  let eventBusInstance: IEventBus | undefined;
+  registry.registerFactory(coreServices.eventBus, async () => {
+    if (!eventBusInstance) {
+      const queueManager = await registry.get(coreServices.queueManager, {
+        pluginId: "core",
+      });
+      const logger = await registry.get(coreServices.logger, {
+        pluginId: "core",
+      });
+      eventBusInstance = new EventBus(queueManager, logger);
+    }
+    return eventBusInstance;
+  });
+}

package/src/plugin-manager/dependency-sorter.ts

@@ -0,0 +1,103 @@
+import type { ServiceRef, Logger } from "@checkstack/backend-api";
+import type { PluginMetadata } from "@checkstack/common";
+import { coreServices } from "@checkstack/backend-api";
+
+/**
+ * Topologically sorts plugins based on their dependencies.
+ * Pure function - no class dependencies.
+ */
+export function sortPlugins({
+  pendingInits,
+  providedBy,
+  logger,
+}: {
+  pendingInits: {
+    metadata: PluginMetadata;
+    deps: Record<string, ServiceRef<unknown>>;
+  }[];
+  providedBy: Map<string, string>;
+  logger: Logger;
+}): string[] {
+  logger.debug("🔄 Calculating initialization order...");
+
+  const inDegree = new Map<string, number>();
+  const graph = new Map<string, string[]>();
+
+  for (const p of pendingInits) {
+    inDegree.set(p.metadata.pluginId, 0);
+    graph.set(p.metadata.pluginId, []);
+  }
+
+  // Track queue plugin providers (plugins that depend on queuePluginRegistry)
+  const queuePluginProviders = new Set<string>();
+  for (const p of pendingInits) {
+    for (const [, ref] of Object.entries(p.deps)) {
+      if (ref.id === coreServices.queuePluginRegistry.id) {
+        queuePluginProviders.add(p.metadata.pluginId);
+      }
+    }
+  }
+
+  // Build dependency graph
+  for (const p of pendingInits) {
+    const consumerId = p.metadata.pluginId;
+    for (const [, ref] of Object.entries(p.deps)) {
+      const serviceId = ref.id;
+      const providerId = providedBy.get(serviceId);
+
+      if (providerId && providerId !== consumerId) {
+        if (!graph.has(providerId)) {
+          graph.set(providerId, []);
+        }
+        graph.get(providerId)!.push(consumerId);
+        inDegree.set(consumerId, (inDegree.get(consumerId) || 0) + 1);
+      }
+    }
+
+    // Special handling: if this plugin uses queueManager, it must wait for all queue plugin providers
+    const usesQueueManager = Object.values(p.deps).some(
+      (ref) => ref.id === coreServices.queueManager.id
+    );
+    if (usesQueueManager) {
+      for (const qpp of queuePluginProviders) {
+        if (qpp !== consumerId) {
+          if (!graph.has(qpp)) {
+            graph.set(qpp, []);
+          }
+          // Add edge: queue plugin provider -> queue consumer
+          if (!graph.get(qpp)!.includes(consumerId)) {
+            graph.get(qpp)!.push(consumerId);
+            inDegree.set(consumerId, (inDegree.get(consumerId) || 0) + 1);
+          }
+        }
+      }
+    }
+  }
+
+  const queue: string[] = [];
+  for (const [id, count] of inDegree.entries()) {
+    if (count === 0) {
+      queue.push(id);
+    }
+  }
+
+  const sortedIds: string[] = [];
+  while (queue.length > 0) {
+    const u = queue.shift()!;
+    sortedIds.push(u);
+
+    const dependents = graph.get(u) || [];
+    for (const v of dependents) {
+      inDegree.set(v, inDegree.get(v)! - 1);
+      if (inDegree.get(v) === 0) {
+        queue.push(v);
+      }
+    }
+  }
+
+  if (sortedIds.length !== pendingInits.length) {
+    throw new Error("Circular dependency detected");
+  }
+
+  return sortedIds;
+}

package/src/plugin-manager/deregistration-guard.ts

@@ -0,0 +1,41 @@
+import { eq } from "drizzle-orm";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { ORPCError } from "@orpc/server";
+import { plugins } from "../schema";
+
+/**
+ * Validates that a plugin can be deregistered.
+ * throws ORPCError if the plugin is not uninstallable or has dependents.
+ */
+export async function assertCanDeregister({
+  pluginId,
+  db,
+}: {
+  pluginId: string;
+  db: NodePgDatabase<Record<string, unknown>>;
+}): Promise<void> {
+  // 1. Check if plugin exists
+  const pluginRows = await db
+    .select()
+    .from(plugins)
+    .where(eq(plugins.name, pluginId));
+
+  if (pluginRows.length === 0) {
+    throw new ORPCError("NOT_FOUND", {
+      message: `Plugin "${pluginId}" not found`,
+    });
+  }
+
+  const plugin = pluginRows[0];
+
+  // 2. Check isUninstallable flag
+  if (!plugin.isUninstallable) {
+    throw new ORPCError("FORBIDDEN", {
+      message: `Plugin "${pluginId}" is a core platform component and cannot be uninstalled`,
+    });
+  }
+
+  // 3. TODO: Check for dependent plugins (consumers of this plugin's services)
+  // This would require tracking service dependencies at runtime
+  // For now, we skip this check and let the deregistration proceed
+}

package/src/plugin-manager/extension-points.ts

@@ -0,0 +1,85 @@
+import type { ExtensionPoint } from "@checkstack/backend-api";
+import { rootLogger } from "../logger";
+
+/**
+ * Creates an extension point manager that handles proxy creation and buffering.
+ */
+export function createExtensionPointManager() {
+  const extensionPointProxies = new Map<string, unknown>();
+
+  /**
+   * Get or create a proxy for an extension point.
+   * Buffers calls until implementation is set.
+   */
+  function getExtensionPointProxy<T>(ref: ExtensionPoint<T>): T {
+    let proxy = extensionPointProxies.get(ref.id) as T | undefined;
+    if (!proxy) {
+      const buffer: { method: string | symbol; args: unknown[] }[] = [];
+      let implementation: T | undefined;
+
+      proxy = new Proxy(
+        {},
+        {
+          get: (target, prop) => {
+            if (prop === "$$setImplementation") {
+              return (impl: T) => {
+                implementation = impl;
+                for (const call of buffer) {
+                  (
+                    implementation as Record<
+                      string | symbol,
+                      (...args: unknown[]) => unknown
+                    >
+                  )[call.method](...call.args);
+                }
+                buffer.length = 0;
+              };
+            }
+            return (...args: unknown[]) => {
+              if (implementation) {
+                return (
+                  implementation as Record<
+                    string | symbol,
+                    (...args: unknown[]) => unknown
+                  >
+                )[prop](...args);
+              } else {
+                buffer.push({ method: prop, args });
+              }
+            };
+          },
+        }
+      ) as T;
+      extensionPointProxies.set(ref.id, proxy);
+    }
+    return proxy;
+  }
+
+  /**
+   * Register an extension point implementation.
+   */
+  function registerExtensionPoint<T>(ref: ExtensionPoint<T>, impl: T) {
+    const proxy = getExtensionPointProxy(ref);
+    (proxy as Record<string, (...args: unknown[]) => unknown>)[
+      "$$setImplementation"
+    ](impl);
+    rootLogger.debug(`   -> Registered extension point '${ref.id}'`);
+  }
+
+  /**
+   * Get an extension point (returns the proxy).
+   */
+  function getExtensionPoint<T>(ref: ExtensionPoint<T>): T {
+    return getExtensionPointProxy(ref);
+  }
+
+  return {
+    getExtensionPointProxy,
+    registerExtensionPoint,
+    getExtensionPoint,
+  };
+}
+
+export type ExtensionPointManager = ReturnType<
+  typeof createExtensionPointManager
+>;

package/src/plugin-manager/index.ts

@@ -0,0 +1,13 @@
+export { type InitCallback, type PendingInit } from "./types";
+export { registerCoreServices } from "./core-services";
+export { createApiRouteHandler, registerApiRoute } from "./api-router";
+export { sortPlugins } from "./dependency-sorter";
+export {
+  createExtensionPointManager,
+  type ExtensionPointManager,
+} from "./extension-points";
+export {
+  loadPlugins,
+  registerPlugin,
+  type PluginLoaderDeps,
+} from "./plugin-loader";

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

@@ -0,0 +1,89 @@
+import { implement } from "@orpc/server";
+import {
+  autoAuthMiddleware,
+  type RpcContext,
+} from "@checkstack/backend-api";
+import { pluginAdminContract } from "@checkstack/backend-api";
+import type { PluginManager } from "../plugin-manager";
+import type { PluginInstaller } from "@checkstack/backend-api";
+import { db } from "../db";
+import { plugins } from "../schema";
+import { eq } from "drizzle-orm";
+import { rootLogger } from "../logger";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Router Factory
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function createPluginAdminRouter({
+  pluginManager,
+  installer,
+}: {
+  pluginManager: PluginManager;
+  installer: PluginInstaller;
+}) {
+  const impl = implement(pluginAdminContract)
+    .$context<RpcContext>()
+    .use(autoAuthMiddleware);
+
+  return impl.router({
+    install: impl.install.handler(async ({ input }) => {
+      const { packageName } = input;
+      rootLogger.info(`📦 Installing plugin: ${packageName}`);
+
+      // 1. npm install to filesystem
+      const result = await installer.install(packageName);
+
+      // 2. Insert/update in DB with isUninstallable=true (remote plugin)
+      await db
+        .insert(plugins)
+        .values({
+          name: result.name,
+          path: result.path,
+          enabled: true,
+          isUninstallable: true, // Remote plugins can be uninstalled
+          type: "backend",
+        })
+        .onConflictDoUpdate({
+          target: [plugins.name],
+          set: { path: result.path, enabled: true },
+        });
+
+      // 3. Broadcast to all instances to load the plugin
+      await pluginManager.requestInstallation(result.name, result.path);
+
+      return {
+        success: true,
+        pluginId: result.name,
+        path: result.path,
+      };
+    }),
+
+    deregister: impl.deregister.handler(async ({ input }) => {
+      const { pluginId, deleteSchema } = input;
+      rootLogger.info(`🗑️ Deregistering plugin: ${pluginId}`);
+
+      // Check if plugin exists and is uninstallable
+      const existing = await db
+        .select()
+        .from(plugins)
+        .where(eq(plugins.name, pluginId))
+        .limit(1);
+
+      if (existing.length === 0) {
+        throw new Error(`Plugin ${pluginId} not found`);
+      }
+
+      if (!existing[0].isUninstallable) {
+        throw new Error(
+          `Plugin ${pluginId} is a core plugin and cannot be deregistered`
+        );
+      }
+
+      // Broadcast to all instances to deregister
+      await pluginManager.requestDeregistration(pluginId, { deleteSchema });
+
+      return { success: true };
+    }),
+  });
+}