@checkstack/backend 0.10.2 → 0.10.4

package/CHANGELOG.md

@@ -1,5 +1,92 @@
 # @checkstack/backend
 
+## 0.10.4
+
+### Patch Changes
+
+- @checkstack/backend-api@0.17.1
+- @checkstack/cache-api@0.3.5
+- @checkstack/queue-api@0.3.5
+- @checkstack/signal-backend@0.2.9
+
+## 0.10.3
+
+### Patch Changes
+
+- f23f3c9: Add `correlationMiddleware` to `@checkstack/backend-api` and apply it
+  to every plugin/core router so each request carries a stable
+  `x-correlation-id` (read from the inbound header, or freshly minted
+  via `crypto.randomUUID()` when absent) and an auto-injected child
+  logger bound with `{ correlationId, pluginId, userId? }`. The ID is
+  echoed back on the response header so the caller can correlate their
+  client-side trace to the server logs.
+
+  The `Logger` interface in `@checkstack/backend-api` now formally
+  documents the structured-metadata convention (`logger.info("msg",
+{ ...meta })`) alongside the long-standing varargs shape. Winston's
+  splat handling already routes both shapes through the same vararg
+  slot, so existing call sites are unaffected. A new optional
+  `Logger.child(meta)` method captures the metadata-binding contract the
+  new middleware relies on; production loggers always implement it,
+  minimal test mocks may omit it (the middleware falls back gracefully).
+
+  `RpcContext` grew two optional `Headers` bags, `requestHeaders` and
+  `responseHeaders`, populated by the outer Hono `/api/*` and `/rest/*`
+  handlers in `@checkstack/backend`. They are write-through observation
+  points for middleware; an `RpcContext` constructed without them (S2S
+  clients, tests) keeps working — the echo is a silent no-op and the ID
+  is still bound onto the child logger for server-side correlation.
+
+  The scaffolding template in `@checkstack/scripts` was updated so any
+  new plugin generated via `bun run create` wires the middleware in the
+  expected `.use(correlationMiddleware).use(autoAuthMiddleware)` order
+  out of the box.
+
+- f23f3c9: Phase 9 of the v1 polishing plan: tighten the plugin loader's boot-time
+  hook policy and backfill notification-router test coverage.
+
+  `@checkstack/backend` adopts an explicit per-hook policy for the two
+  boot-time hooks the plugin loader emits. `pluginInitialized` now
+  **halts the boot** if a subscriber throws — a failing subscriber here
+  means a downstream never wired itself against the freshly initialised
+  plugin, and continuing past that would leave the platform serving
+  traffic in a half-wired state. `accessRulesRegistered` keeps its
+  log-and-continue behaviour but escalates to `error` level and emits a
+  summary count if any subscriber failed; boot-blocking this hook would
+  let one misbehaving plugin DOS every other plugin on the same
+  instance. The policy is documented inline at each emit site and in a
+  new `docs/src/content/docs/backend/plugin-hook-policy.md` page.
+  **BREAKING CHANGE**: subscribers to `pluginInitialized` that
+  previously threw silently (logged and swallowed) now halt platform
+  boot. Audit subscribers and ensure they handle their own internal
+  errors before throwing.
+
+  `@checkstack/notification-backend` ships a real
+  `core/notification-backend/src/router.test.ts` covering the dispatch
+  fan-out (`notifyForSubscription`: zero subscribers, multi-recipient
+  insert, `excludeUserIds`, plus NOT_FOUND/FORBIDDEN guard rails), the
+  canonical paginated read on `getNotifications` (envelope shape,
+  `unreadOnly` filter propagation, null→undefined column mapping), the
+  service-only `createGroup` upsert behaviour (happy path + idempotent
+  re-create), and the multi-strategy `sendTransactional` path with a
+  focused fallback-style assertion: when one strategy throws, the
+  dispatch loop continues to the next and surfaces the failure as a
+  per-strategy `success: false` row instead of short-circuiting. No
+  runtime changes to the notification router.
+
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+- Updated dependencies [f23f3c9]
+  - @checkstack/common@0.11.0
+  - @checkstack/backend-api@0.17.0
+  - @checkstack/api-docs-common@0.1.14
+  - @checkstack/auth-common@0.7.1
+  - @checkstack/pluginmanager-common@0.2.3
+  - @checkstack/signal-backend@0.2.8
+  - @checkstack/signal-common@0.2.4
+  - @checkstack/cache-api@0.3.4
+  - @checkstack/queue-api@0.3.4
+
 ## 0.10.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.10.2",
+  "version": "0.10.4",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "backend"
@@ -14,16 +14,16 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/api-docs-common": "0.1.13",
-    "@checkstack/auth-common": "0.7.0",
-    "@checkstack/backend-api": "0.15.3",
-    "@checkstack/common": "0.10.0",
+    "@checkstack/api-docs-common": "0.1.14",
+    "@checkstack/auth-common": "0.7.1",
+    "@checkstack/backend-api": "0.17.0",
+    "@checkstack/common": "0.11.0",
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/cache-api": "0.3.2",
-    "@checkstack/queue-api": "0.3.2",
-    "@checkstack/signal-backend": "0.2.6",
-    "@checkstack/signal-common": "0.2.3",
-    "@checkstack/pluginmanager-common": "0.2.2",
+    "@checkstack/cache-api": "0.3.4",
+    "@checkstack/queue-api": "0.3.4",
+    "@checkstack/signal-backend": "0.2.8",
+    "@checkstack/signal-common": "0.2.4",
+    "@checkstack/pluginmanager-common": "0.2.3",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
@@ -45,8 +45,8 @@
     "@types/bun": "latest",
     "@types/semver": "^7.5.0",
     "@checkstack/tsconfig": "0.0.7",
-    "@checkstack/scripts": "0.3.2",
-    "@checkstack/test-utils-backend": "0.1.27",
+    "@checkstack/scripts": "0.3.3",
+    "@checkstack/test-utils-backend": "0.1.29",
     "drizzle-kit": "^0.31.10"
   }
 }

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

@@ -492,6 +492,23 @@ export async function loadPlugins({
   const eventBus = await deps.registry.get(coreServices.eventBus, {
     pluginId: "core",
   });
+  /**
+   * Boot-time hook policy for `pluginInitialized`: HALT on subscriber
+   * failure.
+   *
+   * Rationale: `pluginInitialized` fires immediately after a plugin's
+   * Phase 2 `init()` resolves. A throwing subscriber here means a
+   * structural problem with that plugin's startup (a downstream
+   * consumer never got the chance to wire itself against the freshly
+   * initialized plugin). Continuing past such a failure would leave
+   * the platform running in a half-wired state — surfacing it during
+   * boot is safer than discovering the missing wiring at request time.
+   *
+   * Matches the `afterPluginsReady` failure handling below (log +
+   * rethrow with a clearer message naming the failing plugin).
+   *
+   * See `docs/src/content/docs/backend/plugin-hook-policy.md`.
+   */
   for (const p of pendingInits) {
     try {
       await eventBus.emit(coreHooks.pluginInitialized, {
@@ -499,9 +516,13 @@ export async function loadPlugins({
       });
     } catch (error) {
       rootLogger.error(
-        `Failed to emit pluginInitialized hook for ${p.metadata.pluginId}:`,
+        `❌ pluginInitialized hook subscriber threw for ${p.metadata.pluginId}; halting boot to avoid an inconsistent platform state:`,
         error,
       );
+      throw new Error(
+        `Failed pluginInitialized hook for plugin ${p.metadata.pluginId}`,
+        { cause: error },
+      );
     }
   }
 
@@ -546,6 +567,27 @@ export async function loadPlugins({
     }
     accessRulesByPlugin.get(pluginId)!.push(rule);
   }
+  /**
+   * Boot-time hook policy for `accessRulesRegistered`: CONTINUE on
+   * subscriber failure, escalate the log to `error`.
+   *
+   * Rationale: this hook drives downstream consumers that mirror
+   * access-rule registrations into their own stores (e.g. an
+   * access-rule sync worker that hydrates a DB cache). A single
+   * misbehaving subscriber here MUST NOT be allowed to block the
+   * entire platform from booting — that would let one buggy plugin
+   * DOS every other plugin on the same instance.
+   *
+   * We deliberately diverge from the `pluginInitialized` policy
+   * because the failure mode is operational (a downstream's cache is
+   * stale until it recovers), not structural (the platform itself is
+   * fully wired even if a subscriber threw). Boot continues, the
+   * loud `error` log surfaces the breakage to operators, and the
+   * subscriber's owning plugin can implement its own retry / repair.
+   *
+   * See `docs/src/content/docs/backend/plugin-hook-policy.md`.
+   */
+  let accessRulesHookFailures = 0;
   for (const [pluginId, accessRules] of accessRulesByPlugin) {
     try {
       await eventBus.emit(coreHooks.accessRulesRegistered, {
@@ -553,12 +595,18 @@ export async function loadPlugins({
         accessRules,
       });
     } catch (error) {
+      accessRulesHookFailures += 1;
       rootLogger.error(
-        `Failed to emit accessRulesRegistered hook for ${pluginId}:`,
+        `❌ accessRulesRegistered hook subscriber threw for ${pluginId}; continuing boot (a single misbehaving plugin must not block the platform). Downstream consumers may have a stale view of this plugin's access rules until they recover:`,
         error,
       );
     }
   }
+  if (accessRulesHookFailures > 0) {
+    rootLogger.error(
+      `❌ ${accessRulesHookFailures} accessRulesRegistered hook subscriber(s) failed during boot. Platform continued but downstream access-rule consumers may be stale.`,
+    );
+  }
   // Run afterPluginsReady in topologically-sorted order, matching Phase
   // 2 init order. Iterating `pendingInits` directly would use registration
   // order, which races dependency chains: e.g. catalog's

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

@@ -2,6 +2,7 @@ import { implement, ORPCError } from "@orpc/server";
 import { desc } from "drizzle-orm";
 import {
   autoAuthMiddleware,
+  correlationMiddleware,
   coreServices,
   type RpcContext,
   type SafeDatabase,
@@ -109,6 +110,7 @@ export function createPluginManagerRouter({
 
   const impl = implement(pluginManagerContract)
     .$context<RpcContext>()
+    .use(correlationMiddleware)
     .use(autoAuthMiddleware);
 
   return impl.router({