@checkstack/backend 0.10.1 → 0.10.3

package/CHANGELOG.md

@@ -1,5 +1,119 @@
 # @checkstack/backend
 
+## 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
+
+- a06b899: Dead-code audit cleanup and a small platform of shared notification helpers.
+
+  **Removed (dead code)**
+
+  - `core/backend/src/plugin-manager/deregistration-guard.ts` deleted. The exported `assertCanDeregister()` was never called and was a less-complete version of the dependents+isUninstallable checks already done inline by `previewUninstallOriginator` / `uninstallOriginator` in `plugin-manager-orchestrator.ts`.
+  - `createMockQueueFactory` deprecated alias removed from `@checkstack/test-utils-backend`. Use `createMockQueueManager` directly.
+
+  **New shared helpers**
+
+  - `@checkstack/backend-api` now exports `requestTimeoutMs()` — a Zod field builder for outbound HTTP request timeouts (1s..60s, default 10s). Replaces hand-rolled `configNumber({}).min(1000).max(60_000).default(10_000)` in `integration-webhook-backend`, `integration-script-backend`, and `healthcheck-script-backend`'s inline collector.
+  - `@checkstack/notification-common` now exports `SubjectStatusSchema` / `SubjectStatus`, mirroring the existing `ImportanceSchema`.
+  - `@checkstack/notification-backend` now exports:
+    - `SUBJECT_STATUS_EMOJI` / `IMPORTANCE_EMOJI` — the shared status / importance emoji maps that Discord, Slack, Teams, Webex and Telegram previously each redefined inline.
+    - `postJson(opts)` — a timeout-bounded `fetch` wrapper that handles non-2xx logging and error mapping for webhook-style POSTs. Returns `{ ok: true, response } | { ok: false, error }`.
+
+  **Migrated to shared helpers**
+
+  - Discord, Slack, Gotify, Pushover notification backends now use `postJson`. Outer try/catch + per-plugin error mapping deleted (~140 LOC).
+  - Discord, Slack, Teams, Telegram, Webex notification backends now use `IMPORTANCE_EMOJI`. Discord, Slack, Teams use `SUBJECT_STATUS_EMOJI`.
+  - Teams, Webex, Backstage, Telegram kept their inline fetch/Bot logic: their error strings surface server response bodies to operators, or the transport isn't raw `fetch` (Telegram uses `grammy`'s `Bot`).
+
+  **API surface tightening**
+
+  - Per-plugin test-only re-exports in 6 notification backends (Pushover, Gotify, Backstage, Slack, Discord, Teams) and the `CertificateInfo` interface in `healthcheck-tls-backend/strategy.ts` are now JSDoc-tagged `@internal`. No behaviour change; signals that downstream consumers must not depend on them.
+
+- Updated dependencies [a06b899]
+- Updated dependencies [a06b899]
+  - @checkstack/backend-api@0.16.0
+  - @checkstack/cache-api@0.3.3
+  - @checkstack/queue-api@0.3.3
+  - @checkstack/signal-backend@0.2.7
+
 ## 0.10.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "license": "Elastic-2.0",
   "checkstack": {
     "type": "backend"
@@ -16,12 +16,12 @@
   "dependencies": {
     "@checkstack/api-docs-common": "0.1.13",
     "@checkstack/auth-common": "0.7.0",
-    "@checkstack/backend-api": "0.15.2",
+    "@checkstack/backend-api": "0.16.0",
     "@checkstack/common": "0.10.0",
     "@checkstack/drizzle-helper": "0.0.5",
-    "@checkstack/cache-api": "0.3.1",
-    "@checkstack/queue-api": "0.3.1",
-    "@checkstack/signal-backend": "0.2.5",
+    "@checkstack/cache-api": "0.3.3",
+    "@checkstack/queue-api": "0.3.3",
+    "@checkstack/signal-backend": "0.2.7",
     "@checkstack/signal-common": "0.2.3",
     "@checkstack/pluginmanager-common": "0.2.2",
     "@hono/zod-validator": "^0.7.6",
@@ -46,7 +46,7 @@
     "@types/semver": "^7.5.0",
     "@checkstack/tsconfig": "0.0.7",
     "@checkstack/scripts": "0.3.2",
-    "@checkstack/test-utils-backend": "0.1.26",
+    "@checkstack/test-utils-backend": "0.1.28",
     "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({

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

@@ -1,41 +0,0 @@
-import { eq } from "drizzle-orm";
-import { SafeDatabase } from "@checkstack/backend-api";
-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: SafeDatabase<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
-}