@checkstack/backend 0.0.2

package/src/services/keystore.ts

@@ -0,0 +1,136 @@
+import { generateKeyPair, exportJWK, importJWK } from "jose";
+import { db } from "../db";
+import { jwtKeys } from "../schema";
+import { eq, and, isNull, desc, lt } from "drizzle-orm";
+import { rootLogger } from "../logger";
+
+const logger = rootLogger.child({ service: "KeyStore" });
+
+const ALG = "RS256";
+const ROTATION_INTERVAL_MS = 1000 * 60 * 60; // 1 hour
+const ROTATION_GRACE_PERIOD_MS = 1000 * 60 * 60 * 24; // 24 hours
+
+export class KeyStore {
+  /**
+   * Generates a new key pair and stores it
+   */
+  async generateKey() {
+    logger.info("Generating new JWKS key pair...");
+    const { publicKey, privateKey } = await generateKeyPair(ALG, {
+      extractable: true,
+    });
+    const publicJwk = await exportJWK(publicKey);
+    const privateJwk = await exportJWK(privateKey);
+
+    const kid = crypto.randomUUID();
+    publicJwk.kid = kid;
+    publicJwk.use = "sig";
+    publicJwk.alg = ALG;
+
+    privateJwk.kid = kid;
+    privateJwk.use = "sig";
+    privateJwk.alg = ALG;
+
+    const now = new Date(); // Use Date object for timestamp
+
+    await db.insert(jwtKeys).values({
+      id: kid,
+      publicKey: JSON.stringify(publicJwk),
+      privateKey: JSON.stringify(privateJwk),
+      algorithm: ALG,
+      createdAt: now.toISOString(),
+      expiresAt: undefined,
+      revokedAt: undefined,
+    });
+
+    return { kid, publicKey, privateKey };
+  }
+
+  /**
+   * Gets the current signing key, rotating if necessary
+   */
+  async getSigningKey() {
+    const validKeys = await db
+      .select()
+      .from(jwtKeys)
+      .where(and(isNull(jwtKeys.revokedAt), isNull(jwtKeys.expiresAt)))
+      .orderBy(desc(jwtKeys.createdAt))
+      .limit(1);
+
+    let activeKey = validKeys[0];
+    const now = Date.now();
+    let shouldRotate = false;
+
+    if (activeKey) {
+      const created = new Date(activeKey.createdAt).getTime();
+      if (now - created > ROTATION_INTERVAL_MS) {
+        shouldRotate = true;
+      }
+    } else {
+      shouldRotate = true;
+    }
+
+    if (shouldRotate) {
+      if (activeKey) {
+        // Set expiry on old key
+        const expiresAt = new Date(Date.now() + ROTATION_GRACE_PERIOD_MS);
+        logger.info(
+          `Rotating key ${
+            activeKey.id
+          }, setting expiry to ${expiresAt.toISOString()}`
+        );
+        await db
+          .update(jwtKeys)
+          .set({ expiresAt: expiresAt.toISOString() })
+          .where(eq(jwtKeys.id, activeKey.id));
+      }
+
+      const { kid } = await this.generateKey();
+      const newKeys = await db
+        .select()
+        .from(jwtKeys)
+        .where(eq(jwtKeys.id, kid));
+      activeKey = newKeys[0];
+
+      // Clean up old keys on rotation
+      await this.cleanupKeys();
+    }
+
+    if (!activeKey) {
+      throw new Error("Failed to get signing key");
+    }
+
+    const privateJwk = JSON.parse(activeKey.privateKey);
+    const privateKey = await importJWK(privateJwk, ALG);
+    return { kid: activeKey.id, key: privateKey };
+  }
+
+  /**
+   * Returns public keys in JWKS format
+   */
+  async getPublicJWKS() {
+    const validKeys = await db
+      .select({
+        publicKey: jwtKeys.publicKey,
+      })
+      .from(jwtKeys)
+      .where(isNull(jwtKeys.revokedAt)); // Return all non-revoked keys (even if old, for grace period)
+
+    const keys = validKeys.map((k) => JSON.parse(k.publicKey));
+    return { keys };
+  }
+
+  /**
+   * Cleans up expired keys that are past their grace period
+   */
+  async cleanupKeys() {
+    const now = new Date().toISOString();
+    logger.info("Cleaning up expired JWKS keys...");
+
+    // We only delete keys that have an expiresAt set AND that date is in the past.
+    // Since we set expiresAt to now + grace_period, we can just check if expiresAt < now.
+    await db.delete(jwtKeys).where(lt(jwtKeys.expiresAt, now));
+  }
+}
+
+export const keyStore = new KeyStore();

package/src/services/plugin-installer.test.ts

@@ -0,0 +1,90 @@
+import { describe, it, expect, mock, beforeEach } from "bun:test";
+
+// 1. Mock child_process and fs BEFORE importing the target module
+const mockExec = mock((_cmd: string, cb: any) => {
+  cb(null, { stdout: "mocked" }, { stderr: "" });
+});
+
+const mockExistsSync = mock(() => true);
+const mockMkdirSync = mock();
+const mockReadFileSync = mock(() => JSON.stringify({ name: "mock-plugin" }));
+
+mock.module("node:util", () => ({
+  promisify: (fn: any) => {
+    return async (...args: any[]) => {
+      // Return a promise that resolves with what our mock would return
+      // We can just call mockExec and return its "result"
+      return new Promise((resolve) => {
+        fn(...args, (err: any, stdout: any, stderr: any) =>
+          resolve({ stdout, stderr })
+        );
+      });
+    };
+  },
+}));
+
+mock.module("node:child_process", () => ({
+  exec: mockExec,
+}));
+
+mock.module("node:fs", () => {
+  const exports = {
+    existsSync: mockExistsSync,
+    mkdirSync: mockMkdirSync,
+    readFileSync: mockReadFileSync,
+  };
+  return {
+    ...exports,
+    default: exports,
+  };
+});
+
+// 2. Now import the module under test
+import { PluginLocalInstaller } from "./plugin-installer";
+import fs from "node:fs";
+import path from "node:path";
+
+describe("PluginLocalInstaller", () => {
+  const runtimeDir = "/tmp/runtime_plugins";
+  let installer: PluginLocalInstaller;
+  let customExec: any;
+
+  beforeEach(() => {
+    customExec = mock(() => Promise.resolve({ stdout: "mocked", stderr: "" }));
+    installer = new PluginLocalInstaller(runtimeDir, customExec);
+    mockExistsSync.mockClear();
+    mockExistsSync.mockReturnValue(true);
+  });
+
+  it("should install a package using bun", async () => {
+    const result = await installer.install("my-plugin");
+
+    expect(customExec).toHaveBeenCalled();
+    const command = customExec.mock.calls[0][0];
+    expect(command).toContain("bun install my-plugin");
+    expect(command).toContain(`--cwd ${path.resolve(runtimeDir)}`);
+    expect(command).toContain("--no-save");
+
+    expect(result.name).toBe("mock-plugin");
+  });
+
+  it("should handle scoped packages correctly", async () => {
+    const result = await installer.install("@scope/plugin");
+
+    expect(customExec).toHaveBeenCalled();
+    const command = customExec.mock.calls[0][0];
+    expect(command).toContain("bun install @scope/plugin");
+
+    expect(result.name).toBe("mock-plugin");
+  });
+
+  it("should throw error if package.json is missing after install", async () => {
+    // The constructor was already called in beforeEach.
+    // The next call to existsSync will be inside the install method for the pkgJsonPath.
+    mockExistsSync.mockReturnValueOnce(false);
+
+    await expect(installer.install("failing-plugin")).rejects.toThrow(
+      "not found"
+    );
+  });
+});

package/src/services/plugin-installer.ts

@@ -0,0 +1,70 @@
+import { PluginInstaller } from "@checkstack/backend-api";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+import path from "node:path";
+import fs from "node:fs";
+
+export class PluginLocalInstaller implements PluginInstaller {
+  private runtimeDir: string;
+  private execAsync: (
+    command: string
+  ) => Promise<{ stdout: string; stderr: string }>;
+
+  constructor(
+    runtimeDir: string,
+    customExec?: (
+      command: string
+    ) => Promise<{ stdout: string; stderr: string }>
+  ) {
+    this.runtimeDir = path.resolve(runtimeDir);
+    this.execAsync = customExec || promisify(exec);
+    if (!fs.existsSync(this.runtimeDir)) {
+      fs.mkdirSync(this.runtimeDir, { recursive: true });
+    }
+  }
+
+  async install(packageName: string): Promise<{ name: string; path: string }> {
+    try {
+      console.log(
+        `🔌 Installing plugin: ${packageName} into ${this.runtimeDir}`
+      );
+
+      // Use bun install with --no-save to avoid creating/modifying lockfiles
+      // in the runtime directory. This keeps plugins isolated from the main app.
+      await this.execAsync(
+        `bun install ${packageName} --cwd ${this.runtimeDir} --no-save`
+      );
+
+      // Extract the actual package name (packageName could be a URL or @org/name@version)
+      // For now, we assume it's a simple package name for the path lookup,
+      // or we can parse it better.
+      // A safer way is to check the recently changed folders in node_modules?
+      // Or just assume the input packageName (stripped of @version) matches the folder.
+      let folderName = packageName;
+      if (packageName.includes("@") && !packageName.startsWith("@")) {
+        folderName = packageName.split("@")[0];
+      } else if (packageName.startsWith("@") && packageName.includes("@", 1)) {
+        folderName = "@" + packageName.split("@")[1];
+      }
+
+      const pkgPath = path.join(this.runtimeDir, "node_modules", folderName);
+      const pkgJsonPath = path.join(pkgPath, "package.json");
+
+      if (!fs.existsSync(pkgJsonPath)) {
+        throw new Error(
+          `Package folder ${folderName} not found at ${pkgPath} after installation`
+        );
+      }
+
+      const pkgJson = JSON.parse(fs.readFileSync(pkgJsonPath, "utf8"));
+
+      return {
+        name: pkgJson.name,
+        path: pkgPath,
+      };
+    } catch (error) {
+      console.error(`❌ Failed to install plugin ${packageName}:`, error);
+      throw error;
+    }
+  }
+}

package/src/services/queue-manager.ts

@@ -0,0 +1,382 @@
+import type {
+  Queue,
+  QueueManager,
+  SwitchResult,
+  RecurringJobInfo,
+} from "@checkstack/queue-api";
+import type { QueuePluginRegistryImpl } from "./queue-plugin-registry";
+import type { Logger, ConfigService } from "@checkstack/backend-api";
+import { z } from "zod";
+import { QueueProxy } from "./queue-proxy";
+
+// Schema for active plugin pointer with version for multi-instance coordination
+const activePluginPointerSchema = z.object({
+  activePluginId: z.string(),
+  version: z.number(),
+});
+
+type ActivePluginPointer = z.infer<typeof activePluginPointerSchema>;
+
+/**
+ * QueueManagerImpl handles queue creation, backend switching, and multi-instance coordination.
+ *
+ * Features:
+ * - Returns stable QueueProxy instances that survive backend switches
+ * - Polls config for changes to support multi-instance coordination
+ * - Handles graceful migration of recurring jobs when switching backends
+ */
+export class QueueManagerImpl implements QueueManager {
+  private activePluginId: string = "memory"; // Default
+  private activeConfig: unknown = { concurrency: 10, maxQueueSize: 10_000 };
+  private configVersion: number = 0;
+
+  // Stable queue proxies - survive backend switches
+  private queueProxies = new Map<string, QueueProxy<unknown>>();
+
+  // Polling
+  private pollingInterval: ReturnType<typeof setInterval> | undefined =
+    undefined;
+
+  constructor(
+    private registry: QueuePluginRegistryImpl,
+    private configService: ConfigService,
+    private logger: Logger
+  ) {}
+
+  async loadConfiguration(): Promise<void> {
+    try {
+      // Load active plugin pointer
+      const pointer = await this.configService.get<ActivePluginPointer>(
+        "queue:active",
+        activePluginPointerSchema,
+        1
+      );
+
+      if (pointer) {
+        this.activePluginId = pointer.activePluginId;
+        this.configVersion = pointer.version;
+
+        // Load the actual config for this plugin
+        const plugin = this.registry.getPlugin(this.activePluginId);
+        if (plugin) {
+          const config = await this.configService.get(
+            this.activePluginId,
+            plugin.configSchema,
+            plugin.configVersion
+          );
+
+          if (config) {
+            this.activeConfig = config;
+          }
+        }
+
+        this.logger.info(
+          `📋 Loaded queue configuration: plugin=${this.activePluginId}, version=${this.configVersion}`
+        );
+      } else {
+        this.logger.info(
+          `📋 No queue configuration found, using default: plugin=${this.activePluginId}`
+        );
+      }
+    } catch (error) {
+      this.logger.error("Failed to load queue configuration", error);
+      // Continue with defaults
+    }
+  }
+
+  getQueue<T>(name: string): Queue<T> {
+    let proxy = this.queueProxies.get(name) as QueueProxy<T> | undefined;
+
+    if (!proxy) {
+      proxy = new QueueProxy<T>(name);
+      this.queueProxies.set(name, proxy as QueueProxy<unknown>);
+
+      // If we already have config loaded, create delegate immediately
+      if (this.configVersion > 0 || this.activePluginId === "memory") {
+        this.initializeQueueProxy(proxy, name);
+      }
+    }
+
+    return proxy;
+  }
+
+  private initializeQueueProxy<T>(proxy: QueueProxy<T>, name: string): void {
+    const plugin = this.registry.getPlugin(this.activePluginId);
+    if (!plugin) {
+      this.logger.warn(
+        `Queue plugin '${this.activePluginId}' not found, deferring queue creation`
+      );
+      return;
+    }
+
+    const queue = plugin.createQueue<T>(name, this.activeConfig);
+    proxy.switchDelegate(queue).catch((error) => {
+      this.logger.error(`Failed to initialize queue '${name}'`, error);
+    });
+  }
+
+  getActivePlugin(): string {
+    return this.activePluginId;
+  }
+
+  getActiveConfig(): unknown {
+    return this.activeConfig;
+  }
+
+  async setActiveBackend(
+    pluginId: string,
+    config: unknown
+  ): Promise<SwitchResult> {
+    const warnings: string[] = [];
+
+    // 1. Validate plugin exists
+    const newPlugin = this.registry.getPlugin(pluginId);
+    if (!newPlugin) {
+      throw new Error(`Plugin '${pluginId}' not found`);
+    }
+
+    // 2. Validate config against schema
+    newPlugin.configSchema.parse(config);
+
+    // 3. Test connection
+    this.logger.info("🔍 Testing queue connection...");
+    try {
+      const testQueue = newPlugin.createQueue("__connection_test__", config);
+      await testQueue.testConnection();
+      await testQueue.stop();
+      this.logger.info("✅ Connection test successful");
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.logger.error(`❌ Connection test failed: ${message}`);
+      throw new Error(`Failed to connect to queue: ${message}`);
+    }
+
+    // 4. Check for in-flight jobs and warn
+    const inFlightCount = await this.getInFlightJobCount();
+    if (inFlightCount > 0) {
+      warnings.push(
+        `${inFlightCount} jobs are currently in-flight and may be disrupted`
+      );
+      this.logger.warn(
+        `⚠️ ${inFlightCount} in-flight jobs detected during backend switch`
+      );
+    }
+
+    // 5. Collect recurring jobs for migration
+    const oldPlugin = this.registry.getPlugin(this.activePluginId);
+    const recurringJobs = await this.listAllRecurringJobs();
+    let migratedRecurringJobs = 0;
+
+    // 6. Stop all current queues gracefully
+    this.logger.info("🛑 Stopping current queues...");
+    for (const [name, proxy] of this.queueProxies.entries()) {
+      this.logger.debug(`Stopping queue: ${name}`);
+      await proxy.stop().catch((error) => {
+        this.logger.error(`Failed to stop queue ${name}`, error);
+      });
+    }
+
+    // 7. Update internal state
+    const oldPluginId = this.activePluginId;
+    this.activePluginId = pluginId;
+    this.activeConfig = config;
+    this.configVersion++;
+
+    // 8. Create new queues and switch delegates
+    this.logger.info("🔄 Switching to new backend...");
+    for (const [name, proxy] of this.queueProxies.entries()) {
+      const newQueue = newPlugin.createQueue(name, config);
+      await proxy.switchDelegate(newQueue);
+    }
+
+    // 9. Migrate recurring jobs
+    if (recurringJobs.length > 0 && oldPlugin && pluginId !== oldPluginId) {
+      this.logger.info(
+        `📦 Migrating ${recurringJobs.length} recurring jobs...`
+      );
+
+      for (const job of recurringJobs) {
+        try {
+          // Get the proxy for this queue
+          const proxy = this.queueProxies.get(job.queueName);
+          if (proxy) {
+            // Get details from old implementation (via proxy's old delegate before switch)
+            // Since we already switched, we need to get this from the collected info
+            const details = await proxy.getRecurringJobDetails(job.jobId);
+            if (details) {
+              await proxy.scheduleRecurring(details.data as unknown, {
+                jobId: details.jobId,
+                intervalSeconds: details.intervalSeconds,
+                priority: details.priority,
+              });
+              migratedRecurringJobs++;
+            }
+          }
+        } catch (error) {
+          this.logger.error(
+            `Failed to migrate recurring job ${job.jobId}`,
+            error
+          );
+          warnings.push(`Failed to migrate recurring job: ${job.jobId}`);
+        }
+      }
+    }
+
+    // 10. Save configuration
+    await this.configService.set(
+      pluginId,
+      newPlugin.configSchema,
+      newPlugin.configVersion,
+      config
+    );
+
+    await this.configService.set("queue:active", activePluginPointerSchema, 1, {
+      activePluginId: pluginId,
+      version: this.configVersion,
+    });
+
+    this.logger.info(`✅ Queue backend switched: ${oldPluginId} → ${pluginId}`);
+
+    return {
+      success: true,
+      migratedRecurringJobs,
+      warnings,
+    };
+  }
+
+  async getInFlightJobCount(): Promise<number> {
+    let total = 0;
+    for (const proxy of this.queueProxies.values()) {
+      try {
+        const delegate = proxy.getDelegate();
+        if (delegate) {
+          total += await delegate.getInFlightCount();
+        }
+      } catch {
+        // Queue may not be initialized yet
+      }
+    }
+    return total;
+  }
+
+  async listAllRecurringJobs(): Promise<RecurringJobInfo[]> {
+    const jobs: RecurringJobInfo[] = [];
+
+    for (const [queueName, proxy] of this.queueProxies.entries()) {
+      try {
+        const delegate = proxy.getDelegate();
+        if (delegate) {
+          const jobIds = await delegate.listRecurringJobs();
+          for (const jobId of jobIds) {
+            const details = await delegate.getRecurringJobDetails(jobId);
+            if (details) {
+              jobs.push({
+                queueName,
+                jobId,
+                intervalSeconds: details.intervalSeconds,
+                nextRunAt: details.nextRunAt,
+              });
+            }
+          }
+        }
+      } catch {
+        // Queue may not be initialized yet
+      }
+    }
+
+    return jobs;
+  }
+
+  startPolling(intervalMs: number = 5000): void {
+    if (this.pollingInterval) {
+      return; // Already polling
+    }
+
+    this.logger.debug(`Starting queue config polling every ${intervalMs}ms`);
+
+    this.pollingInterval = setInterval(async () => {
+      try {
+        const pointer = await this.configService.get<ActivePluginPointer>(
+          "queue:active",
+          activePluginPointerSchema,
+          1
+        );
+
+        if (pointer && pointer.version !== this.configVersion) {
+          this.logger.info(
+            `🔄 Queue configuration changed (v${this.configVersion} → v${pointer.version}), reloading...`
+          );
+          await this.reloadConfiguration(pointer);
+        }
+      } catch (error) {
+        this.logger.error("Error polling queue config", error);
+      }
+    }, intervalMs);
+  }
+
+  private async reloadConfiguration(
+    pointer: ActivePluginPointer
+  ): Promise<void> {
+    // Load new plugin config
+    const plugin = this.registry.getPlugin(pointer.activePluginId);
+    if (!plugin) {
+      this.logger.error(
+        `Queue plugin '${pointer.activePluginId}' not found during reload`
+      );
+      return;
+    }
+
+    const config = await this.configService.get(
+      pointer.activePluginId,
+      plugin.configSchema,
+      plugin.configVersion
+    );
+
+    if (!config) {
+      this.logger.error(
+        `Failed to load config for plugin '${pointer.activePluginId}'`
+      );
+      return;
+    }
+
+    // Stop and switch all queues
+    for (const [name, proxy] of this.queueProxies.entries()) {
+      try {
+        const newQueue = plugin.createQueue(name, config);
+        await proxy.switchDelegate(newQueue);
+      } catch (error) {
+        this.logger.error(`Failed to switch queue '${name}'`, error);
+      }
+    }
+
+    // Update state
+    this.activePluginId = pointer.activePluginId;
+    this.activeConfig = config;
+    this.configVersion = pointer.version;
+
+    this.logger.info(
+      `✅ Queue configuration reloaded: plugin=${this.activePluginId}`
+    );
+  }
+
+  async shutdown(): Promise<void> {
+    // Stop polling
+    if (this.pollingInterval) {
+      clearInterval(this.pollingInterval);
+      this.pollingInterval = undefined;
+    }
+
+    // Stop all queues
+    this.logger.info("🛑 Shutting down all queues...");
+    for (const [name, proxy] of this.queueProxies.entries()) {
+      try {
+        await proxy.stop();
+        this.logger.debug(`Stopped queue: ${name}`);
+      } catch (error) {
+        this.logger.error(`Failed to stop queue ${name}`, error);
+      }
+    }
+
+    this.logger.info("✅ All queues shut down");
+  }
+}

package/src/services/queue-plugin-registry.ts

@@ -0,0 +1,17 @@
+import { QueuePlugin, QueuePluginRegistry } from "@checkstack/queue-api";
+
+export class QueuePluginRegistryImpl implements QueuePluginRegistry {
+  private plugins = new Map<string, QueuePlugin<unknown>>();
+
+  register(plugin: QueuePlugin<unknown>): void {
+    this.plugins.set(plugin.id, plugin);
+  }
+
+  getPlugin(id: string): QueuePlugin<unknown> | undefined {
+    return this.plugins.get(id);
+  }
+
+  getPlugins(): QueuePlugin<unknown>[] {
+    return [...this.plugins.values()];
+  }
+}