@checkstack/backend 0.4.3 → 0.4.5

package/CHANGELOG.md

@@ -1,5 +1,50 @@
 # @checkstack/backend
 
+## 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
+
+- 18fa8e3: Add notification suppression toggle for maintenance windows
+
+  **New Feature:** When creating or editing a maintenance window, you can now enable "Suppress health notifications" to prevent health status change notifications from being sent for affected systems while the maintenance is active (in_progress status). This is useful for planned downtime where health alerts are expected and would otherwise create noise.
+
+  **Changes:**
+
+  - Added `suppressNotifications` field to maintenance schema
+  - Added new service-to-service API `hasActiveMaintenanceWithSuppression`
+  - Healthcheck queue executor now checks for suppression before sending notifications
+  - MaintenanceEditor UI includes new toggle checkbox
+
+  **Bug Fix:** Fixed migration system to correctly set PostgreSQL search_path when running plugin migrations. Previously, migrations could fail with "relation does not exist" errors because the schema context wasn't properly set.
+
+- db9b37c: Fixed 500 errors on healthcheck `getHistory` and `getDetailedHistory` endpoints caused by the scoped database proxy not handling Drizzle's `$count()` utility method.
+
+  **Root Cause:** The `$count()` method returns a Promise directly (not a query builder), bypassing the chain-replay mechanism used for schema isolation. This caused queries to run without the proper `search_path`, resulting in database errors.
+
+  **Changes:**
+
+  - Added explicit `$count` method handling in `scoped-db.ts` to wrap count operations in transactions with proper schema isolation
+  - Wrapped `$count` return values with `Number()` in healthcheck service to handle BigInt serialization
+
 ## 0.4.3
 
 ### Patch Changes

package/package.json

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

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

@@ -2,7 +2,7 @@ import { migrate } from "drizzle-orm/node-postgres/migrator";
 import path from "node:path";
 import fs from "node:fs";
 import type { Hono } from "hono";
-import { eq, and } from "drizzle-orm";
+import { eq, and, sql } from "drizzle-orm";
 import type { NodePgDatabase } from "drizzle-orm/node-postgres";
 import {
   coreServices,
@@ -77,7 +77,7 @@ export function registerPlugin({
     rootLogger.warn(
       `Plugin ${
         backendPlugin?.metadata?.pluginId || "unknown"
-      } is not using new API. Skipping.`
+      } is not using new API. Skipping.`,
     );
     return;
   }
@@ -91,13 +91,13 @@ export function registerPlugin({
   backendPlugin.register({
     registerInit: <
       D extends Deps,
-      S extends Record<string, unknown> | undefined = undefined
+      S extends Record<string, unknown> | undefined = undefined,
     >(args: {
       deps: D;
       schema?: S;
       init: (deps: ResolvedDeps<D> & DatabaseDeps<S>) => Promise<void>;
       afterPluginsReady?: (
-        deps: ResolvedDeps<D> & DatabaseDeps<S> & AfterPluginsReadyContext
+        deps: ResolvedDeps<D> & DatabaseDeps<S> & AfterPluginsReadyContext,
       ) => Promise<void>;
     }) => {
       pendingInits.push({
@@ -129,12 +129,12 @@ export function registerPlugin({
       }));
       deps.registeredAccessRules.push(...prefixed);
       rootLogger.debug(
-        `   -> Registered ${prefixed.length} access rules for ${pluginId}`
+        `   -> Registered ${prefixed.length} access rules for ${pluginId}`,
       );
     },
     registerRouter: (
       router: Router<AnyContractRouter, RpcContext>,
-      contract: AnyContractRouter
+      contract: AnyContractRouter,
     ) => {
       deps.pluginRpcRouters.set(pluginId, router);
       deps.pluginContractRegistry.set(pluginId, contract);
@@ -184,7 +184,7 @@ export async function loadPlugins({
     });
 
     rootLogger.debug(
-      `   -> Found ${localPlugins.length} local backend plugin(s) in workspace`
+      `   -> Found ${localPlugins.length} local backend plugin(s) in workspace`,
     );
     rootLogger.debug("   -> Discovered plugins:");
     for (const p of localPlugins) {
@@ -201,7 +201,7 @@ export async function loadPlugins({
       .where(and(eq(plugins.enabled, true), eq(plugins.type, "backend")));
 
     rootLogger.debug(
-      `   -> ${allPlugins.length} enabled backend plugins in database:`
+      `   -> ${allPlugins.length} enabled backend plugins in database:`,
     );
     for (const p of allPlugins) {
       rootLogger.debug(`      • ${p.name}`);
@@ -226,7 +226,7 @@ export async function loadPlugins({
         pluginModule = await import(plugin.name);
       } catch {
         rootLogger.debug(
-          `   -> Package name import failed, trying path: ${plugin.path}`
+          `   -> Package name import failed, trying path: ${plugin.path}`,
         );
         pluginModule = await import(plugin.path);
       }
@@ -278,10 +278,58 @@ export async function loadPlugins({
     rootLogger.info(`🚀 Initializing ${p.metadata.pluginId}...`);
 
     try {
-      const pluginDb = await deps.registry.get(
-        coreServices.database,
-        p.metadata
-      );
+      /**
+       * =======================================================================
+       * PLUGIN MIGRATIONS WITH SCHEMA ISOLATION
+       * =======================================================================
+       *
+       * Each plugin's database objects live in a dedicated PostgreSQL schema
+       * (e.g., "plugin_maintenance", "plugin_healthcheck"). This isolation is
+       * achieved through PostgreSQL's `search_path` mechanism.
+       *
+       * ## Why SET search_path is Required for Migrations
+       *
+       * Drizzle's `migrate()` function reads SQL files and executes them directly.
+       * These SQL files contain unqualified table names like:
+       *
+       *   ALTER TABLE "maintenances" ADD COLUMN "foo" boolean;
+       *
+       * Without setting search_path, PostgreSQL defaults to the `public` schema,
+       * causing "relation does not exist" errors since the tables are actually in
+       * the plugin's schema (e.g., `plugin_maintenance.maintenances`).
+       *
+       * ## Session-Level vs Transaction-Level search_path
+       *
+       * We use **session-level** `SET search_path` (not `SET LOCAL`) here because:
+       * - `migrate()` runs multiple statements and may manage its own transactions
+       * - `SET LOCAL` only persists within a single transaction
+       * - Session-level SET persists until explicitly changed or session ends
+       *
+       * ## Why This Doesn't Affect Runtime Queries
+       *
+       * After migrations complete, plugins receive their database via
+       * `createScopedDb()` which wraps every query in a transaction with
+       * `SET LOCAL search_path`. This ensures runtime queries always use the
+       * correct schema, regardless of the session-level search_path.
+       *
+       * ## Potential Hazards
+       *
+       * 1. **Error During Migration**: If a migration fails, the search_path may
+       *    remain set to that plugin's schema. The next plugin's migration would
+       *    fail visibly (wrong schema), which is better than silent data corruption.
+       *
+       * 2. **Parallel Migration Execution**: This code assumes sequential plugin
+       *    initialization (which is enforced by the topologically-sorted loop).
+       *    If migrations ever run in parallel, search_path conflicts would occur.
+       *
+       * 3. **Connection Pool Pollution**: `SET` without `LOCAL` affects the entire
+       *    session. However, we reset to `public` after each plugin's migrations,
+       *    and runtime queries use `SET LOCAL` anyway, so this is safe.
+       *
+       * @see createScopedDb in ../utils/scoped-db.ts for runtime query isolation
+       * @see getPluginSchemaName in @checkstack/drizzle-helper for schema naming
+       * =======================================================================
+       */
 
       // Run Migrations
       const migrationsFolder = path.join(p.pluginPath, "drizzle");
@@ -291,13 +339,24 @@ export async function loadPlugins({
           // Strip "public". schema references from migration SQL at runtime
           stripPublicSchemaFromMigrations(migrationsFolder);
           rootLogger.debug(
-            `   -> Running migrations for ${p.metadata.pluginId} from ${migrationsFolder}`
+            `   -> Running migrations for ${p.metadata.pluginId} from ${migrationsFolder}`,
+          );
+
+          // Set search_path to plugin schema before running migrations.
+          // Uses session-level SET (not SET LOCAL) because migrate() may run
+          // multiple statements across transaction boundaries.
+          await deps.db.execute(
+            sql.raw(`SET search_path = "${migrationsSchema}", public`),
           );
-          await migrate(pluginDb, { migrationsFolder, migrationsSchema });
+          await migrate(deps.db, { migrationsFolder, migrationsSchema });
+
+          // Reset search_path to public after migrations complete.
+          // This prevents search_path leaking into subsequent plugin migrations.
+          await deps.db.execute(sql.raw(`SET search_path = public`));
         } catch (error) {
           rootLogger.error(
             `❌ Failed migration of plugin ${p.metadata.pluginId}:`,
-            error
+            error,
           );
           throw new Error(`Failed to migrate plugin ${p.metadata.pluginId}`, {
             cause: error,
@@ -305,7 +364,7 @@ export async function loadPlugins({
         }
       } else {
         rootLogger.debug(
-          `   -> No migrations found for ${p.metadata.pluginId} (skipping)`
+          `   -> No migrations found for ${p.metadata.pluginId} (skipping)`,
         );
       }
 
@@ -314,7 +373,7 @@ export async function loadPlugins({
       for (const [key, ref] of Object.entries(p.deps)) {
         resolvedDeps[key] = await deps.registry.get(
           ref as ServiceRef<unknown>,
-          p.metadata
+          p.metadata,
         );
       }
 
@@ -330,7 +389,7 @@ export async function loadPlugins({
       } catch (error) {
         rootLogger.error(
           `❌ Failed to initialize ${p.metadata.pluginId}:`,
-          error
+          error,
         );
         throw new Error(`Failed to initialize plugin ${p.metadata.pluginId}`, {
           cause: error,
@@ -339,7 +398,7 @@ export async function loadPlugins({
     } catch (error) {
       rootLogger.error(
         `❌ Critical error loading plugin ${p.metadata.pluginId}:`,
-        error
+        error,
       );
       throw new Error(`Critical error loading plugin ${p.metadata.pluginId}`, {
         cause: error,
@@ -360,11 +419,40 @@ export async function loadPlugins({
     } catch (error) {
       rootLogger.error(
         `Failed to emit pluginInitialized hook for ${p.metadata.pluginId}:`,
-        error
+        error,
       );
     }
   }
 
+  // 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...");
 
@@ -386,7 +474,7 @@ export async function loadPlugins({
     } catch (error) {
       rootLogger.error(
         `Failed to emit accessRulesRegistered hook for ${pluginId}:`,
-        error
+        error,
       );
     }
   }
@@ -397,7 +485,7 @@ export async function loadPlugins({
         for (const [key, ref] of Object.entries(p.deps)) {
           resolvedDeps[key] = await deps.registry.get(
             ref as ServiceRef<unknown>,
-            p.metadata
+            p.metadata,
           );
         }
 
@@ -412,39 +500,78 @@ export async function loadPlugins({
         resolvedDeps["onHook"] = <T>(
           hook: { id: string },
           listener: (payload: T) => Promise<void>,
-          options?: HookSubscribeOptions
+          options?: HookSubscribeOptions,
         ) => {
           return eventBus.subscribe(
             p.metadata.pluginId,
             hook,
             listener,
-            options
+            options,
           );
         };
         resolvedDeps["emitHook"] = async <T>(
           hook: { id: string },
-          payload: T
+          payload: T,
         ) => {
           await eventBus.emit(hook, payload);
         };
 
         await p.afterPluginsReady(resolvedDeps);
         rootLogger.debug(
-          `   -> ${p.metadata.pluginId} afterPluginsReady complete`
+          `   -> ${p.metadata.pluginId} afterPluginsReady complete`,
         );
       } catch (error) {
         rootLogger.error(
           `❌ Failed afterPluginsReady for ${p.metadata.pluginId}:`,
-          error
+          error,
         );
         throw new Error(
           `Failed afterPluginsReady for plugin ${p.metadata.pluginId}`,
           {
             cause: error,
-          }
+          },
         );
       }
     }
   }
   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/utils/scoped-db.ts

@@ -183,7 +183,7 @@ export type ScopedDatabase<TSchema extends Record<string, unknown>> = Omit<
  */
 export function createScopedDb<TSchema extends Record<string, unknown>>(
   baseDb: NodePgDatabase<Record<string, unknown>>,
-  schemaName: string
+  schemaName: string,
 ): ScopedDatabase<TSchema> {
   const wrappedDb = baseDb as NodePgDatabase<TSchema>;
 
@@ -225,7 +225,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
     builder: T,
     initialMethod: string,
     initialArgs: unknown[],
-    chain: Array<{ method: string; args: unknown[] }> = []
+    chain: Array<{ method: string; args: unknown[] }> = [],
   ): T {
     // Store chain info for this builder instance
     pendingChains.set(builder, {
@@ -253,7 +253,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
         if (prop === "then" && typeof value === "function") {
           return (
             onFulfilled?: (value: unknown) => unknown,
-            onRejected?: (reason: unknown) => unknown
+            onRejected?: (reason: unknown) => unknown,
           ) => {
             const chainInfo = pendingChains.get(builder);
             if (!chainInfo) {
@@ -262,7 +262,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
               return (value as Function).call(
                 builderTarget,
                 onFulfilled,
-                onRejected
+                onRejected,
               );
             }
 
@@ -271,7 +271,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
               // Set the schema search_path for this transaction
               // SET LOCAL ensures it only affects this transaction
               await tx.execute(
-                sql.raw(`SET LOCAL search_path = "${schemaName}", public`)
+                sql.raw(`SET LOCAL search_path = "${schemaName}", public`),
               );
 
               // Rebuild the query on the transaction connection
@@ -284,7 +284,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
               // Replay all the chained method calls (from, where, orderBy, etc.)
               for (const call of chainInfo.chain) {
                 txQuery = (txQuery as Record<string, TxMethod>)[call.method](
-                  ...call.args
+                  ...call.args,
                 );
               }
 
@@ -310,13 +310,13 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
             if (!chainInfo) {
               return (value as (...a: unknown[]) => Promise<unknown>).apply(
                 builderTarget,
-                args
+                args,
               );
             }
 
             return baseDb.transaction(async (tx) => {
               await tx.execute(
-                sql.raw(`SET LOCAL search_path = "${schemaName}", public`)
+                sql.raw(`SET LOCAL search_path = "${schemaName}", public`),
               );
 
               type TxMethod = (...args: unknown[]) => unknown;
@@ -326,7 +326,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
 
               for (const call of chainInfo.chain) {
                 txQuery = (txQuery as Record<string, TxMethod>)[call.method](
-                  ...call.args
+                  ...call.args,
                 );
               }
 
@@ -352,7 +352,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
             // Call the original method
             const result = (value as (...a: unknown[]) => unknown).apply(
               builderTarget,
-              args
+              args,
             );
 
             // If it returns an object (likely another builder), wrap it
@@ -367,7 +367,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
                 result as object,
                 chainInfo?.method || initialMethod,
                 chainInfo?.args || initialArgs,
-                newChain
+                newChain,
               );
             }
             return result;
@@ -410,7 +410,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
             `isolation. Use the standard query builder API instead:\n` +
             `  - db.select().from(table) instead of db.query.table.findMany()\n` +
             `  - db.select().from(table).where(...).limit(1) instead of db.query.table.findFirst()\n` +
-            `Current schema: "${schemaName}"`
+            `Current schema: "${schemaName}"`,
         );
       }
 
@@ -424,12 +424,12 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
        */
       if (prop === "transaction") {
         return async <T>(
-          callback: (tx: ScopedDatabase<TSchema>) => Promise<T>
+          callback: (tx: ScopedDatabase<TSchema>) => Promise<T>,
         ): Promise<T> => {
           return target.transaction(async (tx) => {
             // Set search_path once at transaction start
             await tx.execute(
-              sql.raw(`SET LOCAL search_path = "${schemaName}", public`)
+              sql.raw(`SET LOCAL search_path = "${schemaName}", public`),
             );
             // User's callback runs with the correct schema
             return callback(tx as ScopedDatabase<TSchema>);
@@ -446,11 +446,33 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
         return async (...args: unknown[]) => {
           return target.transaction(async (tx) => {
             await tx.execute(
-              sql.raw(`SET LOCAL search_path = "${schemaName}", public`)
+              sql.raw(`SET LOCAL search_path = "${schemaName}", public`),
             );
             return (tx.execute as (...a: unknown[]) => Promise<unknown>).apply(
               tx,
-              args
+              args,
+            );
+          });
+        };
+      }
+
+      /**
+       * Handle db.$count() calls.
+       *
+       * The $count utility is a newer Drizzle method that returns a Promise
+       * directly (not a query builder), so it's not caught by the entityKind
+       * detection for query builders. We need to explicitly wrap it in a
+       * transaction with the search_path set.
+       */
+      if (prop === "$count" && typeof value === "function") {
+        return async (...args: unknown[]) => {
+          return target.transaction(async (tx) => {
+            await tx.execute(
+              sql.raw(`SET LOCAL search_path = "${schemaName}", public`),
+            );
+            return (tx.$count as (...a: unknown[]) => Promise<unknown>).apply(
+              tx,
+              args,
             );
           });
         };
@@ -470,7 +492,7 @@ export function createScopedDb<TSchema extends Record<string, unknown>>(
         return (...args: unknown[]) => {
           const result = (value as (...a: unknown[]) => unknown).apply(
             target,
-            args
+            args,
           );
 
           // Check if the result is a query builder that needs wrapping