@checkstack/backend 0.4.4 → 0.4.6

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # @checkstack/backend
 
+## 0.4.6
+
+### Patch Changes
+
+- 66a3963: Update plugin loader to use SafeDatabase type
+
+  - Updated `PluginLoaderDeps.db` type from `NodePgDatabase` to `SafeDatabase`
+  - Added type cast for drizzle `migrate()` function which still requires `NodePgDatabase`
+
+- Updated dependencies [2c0822d]
+- Updated dependencies [66a3963]
+  - @checkstack/queue-api@0.2.0
+  - @checkstack/backend-api@0.5.0
+  - @checkstack/signal-backend@0.1.6
+
+## 0.4.5
+
+### Patch Changes
+
+- 8a87cd4: Added startup validation for unregistered access rules
+
+  The backend now throws an error at startup if a procedure contract references an access rule that isn't registered with the plugin system. This prevents silent runtime failures.
+
+- Updated dependencies [8a87cd4]
+- Updated dependencies [8a87cd4]
+- Updated dependencies [8a87cd4]
+  - @checkstack/auth-common@0.5.2
+  - @checkstack/backend-api@0.4.1
+  - @checkstack/common@0.5.0
+  - @checkstack/queue-api@0.1.3
+  - @checkstack/signal-backend@0.1.5
+  - @checkstack/api-docs-common@0.1.3
+  - @checkstack/signal-common@0.1.3
+
 ## 0.4.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "type": "module",
   "scripts": {
     "dev": "bun --env-file=../../.env --watch src/index.ts",

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

@@ -1,5 +1,5 @@
 import type { Hono, Context } from "hono";
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { SafeDatabase } from "@checkstack/backend-api";
 import { RPCHandler } from "@orpc/server/fetch";
 import {
   coreServices,
@@ -108,7 +108,7 @@ export function createApiRouteHandler({
       pluginMetadata,
       auth: auth as AuthService,
       logger: logger as Logger,
-      db: db as NodePgDatabase<Record<string, unknown>>,
+      db: db as SafeDatabase<Record<string, unknown>>,
       fetch: fetch as Fetch,
       healthCheckRegistry: healthCheckRegistry as HealthCheckRegistry,
       collectorRegistry: collectorRegistry as CollectorRegistry,

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

@@ -1,5 +1,5 @@
 import { eq } from "drizzle-orm";
-import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { SafeDatabase } from "@checkstack/backend-api";
 import { ORPCError } from "@orpc/server";
 import { plugins } from "../schema";
 
@@ -12,7 +12,7 @@ export async function assertCanDeregister({
   db,
 }: {
   pluginId: string;
-  db: NodePgDatabase<Record<string, unknown>>;
+  db: SafeDatabase<Record<string, unknown>>;
 }): Promise<void> {
   // 1. Check if plugin exists
   const pluginRows = await db

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

@@ -1,9 +1,10 @@
 import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { NodePgDatabase } from "drizzle-orm/node-postgres";
 import path from "node:path";
 import fs from "node:fs";
 import type { Hono } from "hono";
 import { eq, and, sql } from "drizzle-orm";
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { SafeDatabase } from "@checkstack/backend-api";
 import {
   coreServices,
   BackendPlugin,
@@ -42,7 +43,7 @@ export interface PluginLoaderDeps {
   extensionPointManager: ExtensionPointManager;
   registeredAccessRules: (AccessRule & { pluginId: string })[];
   getAllAccessRules: () => AccessRule[];
-  db: NodePgDatabase<Record<string, unknown>>;
+  db: SafeDatabase<Record<string, unknown>>;
   /**
    * Map of pluginId -> PluginMetadata for request-time context injection.
    */
@@ -348,7 +349,11 @@ export async function loadPlugins({
           await deps.db.execute(
             sql.raw(`SET search_path = "${migrationsSchema}", public`),
           );
-          await migrate(deps.db, { migrationsFolder, migrationsSchema });
+          // Drizzle migrate() requires NodePgDatabase, cast from SafeDatabase
+          await migrate(deps.db as NodePgDatabase<Record<string, unknown>>, {
+            migrationsFolder,
+            migrationsSchema,
+          });
 
           // Reset search_path to public after migrations complete.
           // This prevents search_path leaking into subsequent plugin migrations.
@@ -424,6 +429,35 @@ export async function loadPlugins({
     }
   }
 
+  // Phase 2.5: Validate that all access rules used in contracts are registered
+  // This catches bugs where access rules are used in procedures but not added to
+  // the plugin's accessRules registration array.
+  rootLogger.debug("🔍 Validating access rules in contracts...");
+  const registeredRuleIds = new Set(
+    deps.registeredAccessRules.map((r) => r.id),
+  );
+  const validationErrors: string[] = [];
+
+  for (const [pluginId, contract] of deps.pluginContractRegistry) {
+    validateContractAccessRules({
+      pluginId,
+      contract,
+      registeredRuleIds,
+      validationErrors,
+    });
+  }
+
+  if (validationErrors.length > 0) {
+    rootLogger.error("❌ Unregistered access rules found in contracts:");
+    for (const error of validationErrors) {
+      rootLogger.error(`   • ${error}`);
+    }
+    throw new Error(
+      `Unregistered access rules in contracts:\n${validationErrors.join("\n")}`,
+    );
+  }
+  rootLogger.debug("✅ All access rules in contracts are registered");
+
   // Phase 3: Run afterPluginsReady callbacks
   rootLogger.debug("🔄 Running afterPluginsReady callbacks...");
 
@@ -507,3 +541,42 @@ export async function loadPlugins({
   }
   rootLogger.debug("✅ All afterPluginsReady callbacks complete");
 }
+
+/**
+ * Validate that all access rules used in a contract are registered with the plugin system.
+ * Recursively traverses the contract to find all procedures and their access metadata.
+ */
+function validateContractAccessRules({
+  pluginId,
+  contract,
+  registeredRuleIds,
+  validationErrors,
+}: {
+  pluginId: string;
+  contract: AnyContractRouter;
+  registeredRuleIds: Set<string>;
+  validationErrors: string[];
+}): void {
+  for (const [procedureName, procedure] of Object.entries(
+    contract as Record<string, unknown>,
+  )) {
+    if (!procedure || typeof procedure !== "object") continue;
+
+    // Check if this is a procedure with oRPC metadata
+    const orpcData = (procedure as Record<string, unknown>)["~orpc"] as
+      | { meta?: { access?: Array<{ id: string }> } }
+      | undefined;
+
+    if (orpcData?.meta?.access) {
+      for (const accessRule of orpcData.meta.access) {
+        const qualifiedId = `${pluginId}.${accessRule.id}`;
+        if (!registeredRuleIds.has(qualifiedId)) {
+          validationErrors.push(
+            `Plugin "${pluginId}" procedure "${procedureName}" uses unregistered access rule "${accessRule.id}" (qualified: "${qualifiedId}"). ` +
+              `Add it to the plugin's accessRules registration array.`,
+          );
+        }
+      }
+    }
+  }
+}

package/src/services/config-service.ts

@@ -1,4 +1,4 @@
-import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { SafeDatabase } from "@checkstack/backend-api";
 import { eq, and } from "drizzle-orm";
 import { z } from "zod";
 import {
@@ -20,7 +20,7 @@ import { pluginConfigs } from "../schema";
 export class ConfigServiceImpl implements ConfigService {
   constructor(
     private readonly pluginId: string,
-    private readonly db: NodePgDatabase<Record<string, unknown>>
+    private readonly db: SafeDatabase<Record<string, unknown>>
   ) {}
 
   /**

package/src/services/queue-manager.ts

@@ -41,7 +41,7 @@ export class QueueManagerImpl implements QueueManager {
   constructor(
     private registry: QueuePluginRegistryImpl,
     private configService: ConfigService,
-    private logger: Logger
+    private logger: Logger,
   ) {}
 
   async loadConfiguration(): Promise<void> {
@@ -50,7 +50,7 @@ export class QueueManagerImpl implements QueueManager {
       const pointer = await this.configService.get<ActivePluginPointer>(
         "queue:active",
         activePluginPointerSchema,
-        1
+        1,
       );
 
       if (pointer) {
@@ -63,7 +63,7 @@ export class QueueManagerImpl implements QueueManager {
           const config = await this.configService.get(
             this.activePluginId,
             plugin.configSchema,
-            plugin.configVersion
+            plugin.configVersion,
           );
 
           if (config) {
@@ -72,11 +72,11 @@ export class QueueManagerImpl implements QueueManager {
         }
 
         this.logger.info(
-          `📋 Loaded queue configuration: plugin=${this.activePluginId}, version=${this.configVersion}`
+          `📋 Loaded queue configuration: plugin=${this.activePluginId}, version=${this.configVersion}`,
         );
       } else {
         this.logger.info(
-          `📋 No queue configuration found, using default: plugin=${this.activePluginId}`
+          `📋 No queue configuration found, using default: plugin=${this.activePluginId}`,
         );
       }
     } catch (error) {
@@ -105,7 +105,7 @@ export class QueueManagerImpl implements QueueManager {
     const plugin = this.registry.getPlugin(this.activePluginId);
     if (!plugin) {
       this.logger.warn(
-        `Queue plugin '${this.activePluginId}' not found, deferring queue creation`
+        `Queue plugin '${this.activePluginId}' not found, deferring queue creation`,
       );
       return;
     }
@@ -126,7 +126,7 @@ export class QueueManagerImpl implements QueueManager {
 
   async setActiveBackend(
     pluginId: string,
-    config: unknown
+    config: unknown,
   ): Promise<SwitchResult> {
     const warnings: string[] = [];
 
@@ -145,7 +145,7 @@ export class QueueManagerImpl implements QueueManager {
       const testQueue = newPlugin.createQueue(
         "__connection_test__",
         config,
-        this.logger
+        this.logger,
       );
       await testQueue.testConnection();
       await testQueue.stop();
@@ -160,10 +160,10 @@ export class QueueManagerImpl implements QueueManager {
     const inFlightCount = await this.getInFlightJobCount();
     if (inFlightCount > 0) {
       warnings.push(
-        `${inFlightCount} jobs are currently in-flight and may be disrupted`
+        `${inFlightCount} jobs are currently in-flight and may be disrupted`,
       );
       this.logger.warn(
-        `⚠️ ${inFlightCount} in-flight jobs detected during backend switch`
+        `⚠️ ${inFlightCount} in-flight jobs detected during backend switch`,
       );
     }
 
@@ -197,7 +197,7 @@ export class QueueManagerImpl implements QueueManager {
     // 9. Migrate recurring jobs
     if (recurringJobs.length > 0 && oldPlugin && pluginId !== oldPluginId) {
       this.logger.info(
-        `📦 Migrating ${recurringJobs.length} recurring jobs...`
+        `📦 Migrating ${recurringJobs.length} recurring jobs...`,
       );
 
       for (const job of recurringJobs) {
@@ -209,18 +209,28 @@ export class QueueManagerImpl implements QueueManager {
             // 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,
-              });
+              // Use if/else to properly satisfy XOR type constraint
+              // eslint-disable-next-line unicorn/prefer-ternary
+              if ("cronPattern" in details && details.cronPattern) {
+                await proxy.scheduleRecurring(details.data as unknown, {
+                  jobId: details.jobId,
+                  priority: details.priority,
+                  cronPattern: details.cronPattern,
+                });
+              } else {
+                await proxy.scheduleRecurring(details.data as unknown, {
+                  jobId: details.jobId,
+                  priority: details.priority,
+                  intervalSeconds: details.intervalSeconds!,
+                });
+              }
               migratedRecurringJobs++;
             }
           }
         } catch (error) {
           this.logger.error(
             `Failed to migrate recurring job ${job.jobId}`,
-            error
+            error,
           );
           warnings.push(`Failed to migrate recurring job: ${job.jobId}`);
         }
@@ -232,7 +242,7 @@ export class QueueManagerImpl implements QueueManager {
       pluginId,
       newPlugin.configSchema,
       newPlugin.configVersion,
-      config
+      config,
     );
 
     await this.configService.set("queue:active", activePluginPointerSchema, 1, {
@@ -303,12 +313,18 @@ export class QueueManagerImpl implements QueueManager {
           for (const jobId of jobIds) {
             const details = await delegate.getRecurringJobDetails(jobId);
             if (details) {
+              // Extract schedule from details (XOR pattern - one must be defined)
+              const schedule =
+                "cronPattern" in details
+                  ? { cronPattern: details.cronPattern }
+                  : { intervalSeconds: details.intervalSeconds };
+
               jobs.push({
                 queueName,
                 jobId,
-                intervalSeconds: details.intervalSeconds,
                 nextRunAt: details.nextRunAt,
-              });
+                ...schedule,
+              } as RecurringJobInfo);
             }
           }
         }
@@ -332,12 +348,12 @@ export class QueueManagerImpl implements QueueManager {
         const pointer = await this.configService.get<ActivePluginPointer>(
           "queue:active",
           activePluginPointerSchema,
-          1
+          1,
         );
 
         if (pointer && pointer.version !== this.configVersion) {
           this.logger.info(
-            `🔄 Queue configuration changed (v${this.configVersion} → v${pointer.version}), reloading...`
+            `🔄 Queue configuration changed (v${this.configVersion} → v${pointer.version}), reloading...`,
           );
           await this.reloadConfiguration(pointer);
         }
@@ -348,13 +364,13 @@ export class QueueManagerImpl implements QueueManager {
   }
 
   private async reloadConfiguration(
-    pointer: ActivePluginPointer
+    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`
+        `Queue plugin '${pointer.activePluginId}' not found during reload`,
       );
       return;
     }
@@ -362,12 +378,12 @@ export class QueueManagerImpl implements QueueManager {
     const config = await this.configService.get(
       pointer.activePluginId,
       plugin.configSchema,
-      plugin.configVersion
+      plugin.configVersion,
     );
 
     if (!config) {
       this.logger.error(
-        `Failed to load config for plugin '${pointer.activePluginId}'`
+        `Failed to load config for plugin '${pointer.activePluginId}'`,
       );
       return;
     }
@@ -388,7 +404,7 @@ export class QueueManagerImpl implements QueueManager {
     this.configVersion = pointer.version;
 
     this.logger.info(
-      `✅ Queue configuration reloaded: plugin=${this.activePluginId}`
+      `✅ Queue configuration reloaded: plugin=${this.activePluginId}`,
     );
   }
 

package/src/services/queue-proxy.ts

@@ -4,6 +4,7 @@ import type {
   ConsumeOptions,
   QueueStats,
   RecurringJobDetails,
+  RecurringSchedule,
 } from "@checkstack/queue-api";
 import { rootLogger } from "../logger";
 
@@ -39,7 +40,7 @@ export class QueueProxy<T = unknown> implements Queue<T> {
     // Wait for pending operations to complete
     if (this.pendingOperations.length > 0) {
       rootLogger.debug(
-        `Waiting for ${this.pendingOperations.length} pending operations...`
+        `Waiting for ${this.pendingOperations.length} pending operations...`,
       );
       await Promise.allSettled(this.pendingOperations);
     }
@@ -56,7 +57,7 @@ export class QueueProxy<T = unknown> implements Queue<T> {
     // Re-apply all stored subscriptions
     for (const [group, { consumer, options }] of this.subscriptions) {
       rootLogger.debug(
-        `Re-applying subscription for group '${group}' on queue '${this.name}'`
+        `Re-applying subscription for group '${group}' on queue '${this.name}'`,
       );
       await this.delegate.consume(consumer, options);
     }
@@ -72,7 +73,7 @@ export class QueueProxy<T = unknown> implements Queue<T> {
   private ensureDelegate(): Queue<T> {
     if (!this.delegate) {
       throw new Error(
-        `Queue '${this.name}' not initialized. Ensure QueueManager.loadConfiguration() has been called.`
+        `Queue '${this.name}' not initialized. Ensure QueueManager.loadConfiguration() has been called.`,
       );
     }
     if (this.stopped) {
@@ -85,7 +86,7 @@ export class QueueProxy<T = unknown> implements Queue<T> {
     this.pendingOperations.push(operation);
     return operation.finally(() => {
       this.pendingOperations = this.pendingOperations.filter(
-        (p) => p !== operation
+        (p) => p !== operation,
       );
     });
   }
@@ -96,7 +97,7 @@ export class QueueProxy<T = unknown> implements Queue<T> {
       priority?: number;
       startDelay?: number;
       jobId?: string;
-    }
+    },
   ): Promise<string> {
     const delegate = this.ensureDelegate();
     return this.trackOperation(delegate.enqueue(data, options));
@@ -104,7 +105,7 @@ export class QueueProxy<T = unknown> implements Queue<T> {
 
   async consume(
     consumer: QueueConsumer<T>,
-    options: ConsumeOptions
+    options: ConsumeOptions,
   ): Promise<void> {
     // Store subscription for replay after backend switch
     this.subscriptions.set(options.consumerGroup, { consumer, options });
@@ -119,10 +120,9 @@ export class QueueProxy<T = unknown> implements Queue<T> {
     data: T,
     options: {
       jobId: string;
-      intervalSeconds: number;
       startDelay?: number;
       priority?: number;
-    }
+    } & RecurringSchedule,
   ): Promise<string> {
     const delegate = this.ensureDelegate();
     return this.trackOperation(delegate.scheduleRecurring(data, options));
@@ -139,7 +139,7 @@ export class QueueProxy<T = unknown> implements Queue<T> {
   }
 
   async getRecurringJobDetails(
-    jobId: string
+    jobId: string,
   ): Promise<RecurringJobDetails<T> | undefined> {
     const delegate = this.ensureDelegate();
     return delegate.getRecurringJobDetails(jobId);

package/src/utils/plugin-discovery.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import fs from "node:fs";
 import { eq, and } from "drizzle-orm";
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { SafeDatabase } from "@checkstack/backend-api";
 import { plugins } from "../schema";
 
 export interface PluginMetadata {
@@ -116,7 +116,7 @@ export async function syncPluginsToDatabase({
   db,
 }: {
   localPlugins: PluginMetadata[];
-  db: NodePgDatabase<Record<string, unknown>>;
+  db: SafeDatabase<Record<string, unknown>>;
 }): Promise<void> {
   for (const plugin of localPlugins) {
     // Check if plugin already exists

package/src/utils/scoped-db.ts

@@ -1,4 +1,4 @@
-import { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { SafeDatabase } from "@checkstack/backend-api";
 import { sql, entityKind } from "drizzle-orm";
 
 /**
@@ -147,7 +147,7 @@ function isWrappableBuilder(value: unknown): boolean {
 /**
  * A schema-scoped database type that excludes the relational query API.
  *
- * This type explicitly removes `query` from NodePgDatabase so that plugin
+ * This type explicitly removes `query` from SafeDatabase so that plugin
  * authors get compile-time errors when trying to use `db.query.*` instead
  * of runtime errors. This provides better DX and catches isolation bypasses
  * at development time.
@@ -156,7 +156,7 @@ function isWrappableBuilder(value: unknown): boolean {
  * execution path that bypasses our schema isolation mechanism.
  */
 export type ScopedDatabase<TSchema extends Record<string, unknown>> = Omit<
-  NodePgDatabase<TSchema>,
+  SafeDatabase<TSchema>,
   "query"
 >;
 
@@ -182,10 +182,10 @@ export type ScopedDatabase<TSchema extends Record<string, unknown>> = Omit<
  * ```
  */
 export function createScopedDb<TSchema extends Record<string, unknown>>(
-  baseDb: NodePgDatabase<Record<string, unknown>>,
+  baseDb: SafeDatabase<Record<string, unknown>>,
   schemaName: string,
 ): ScopedDatabase<TSchema> {
-  const wrappedDb = baseDb as NodePgDatabase<TSchema>;
+  const wrappedDb = baseDb as SafeDatabase<TSchema>;
 
   /**
    * WeakMap to track query chains for each builder instance.