@checkstack/signal-backend 0.2.12 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,56 @@
 # @checkstack/signal-backend
 
+## 0.3.0
+
+### Minor Changes
+
+- 9dcc848: Stop the spurious "Plugin unknown is not using new API. Skipping." startup warning.
+
+  `@checkstack/signal-backend` is a host-consumed library (the backend imports `SignalServiceImpl` and `createWebSocketHandler` directly), but its `package.json` declared `checkstack.type: "backend"`, so plugin discovery inserted it as a runtime backend plugin and the loader tried to read a default `register()` export it does not have - logging the offending package as the literal `unknown`.
+
+  - Reclassify `@checkstack/signal-backend` to `checkstack.type: "tooling"` (like `@checkstack/backend-api`), so it is no longer discovered or registered as a backend plugin. No runtime behavior change - the SignalService and WebSocket handler are still instantiated and registered directly by the host backend.
+  - Harden the loader's skip diagnostic so it can never render `unknown`: it resolves the offending plugin by its database-row package name (falling back to the on-disk path) and tells operators to set `checkstack.type` to `"tooling"` for host-consumed libraries.
+
+  This is a beta minor.
+
+### Patch Changes
+
+- 9dcc848: Write-path hardening: post-commit side effects can no longer fail a committed write, multi-row mutations are now atomic, and retry-duplication is blocked at the database.
+
+  **Platform-level (automatic for all current and future plugins):**
+
+  - signal-backend: `SignalService` (broadcast / sendToUser / sendToUsers / sendToAuthorizedUsers) is now resilient by construction - a transient event-bus/queue failure is caught and logged instead of thrown. Real-time signals are best-effort UI nudges; the authoritative data is already committed by the time a mutation broadcasts, so a signal-transport blip must never turn a successful write into a client-visible error. Every plugin's broadcasts inherit this without per-call-site `try/catch` (which would inevitably be forgotten and regress). This mirrors `createCachedScope`, which already makes cache invalidation non-throwing - so the cache + signal halves of the "post-commit side effect fails the response" class are both closed at the platform seam. Durable side effects (events/hooks that drive automations, queue jobs) intentionally still surface failures. Documented in `developer-guide/backend/signals.md`.
+
+  **Atomic multi-write mutations (each previously committed row-by-row in autocommit, so a mid-sequence failure left partial/orphaned state):**
+
+  - slo-backend: `createObjective` now inserts the objective and its 1:1 streak row in one transaction; the post-create reconcile/status/notify steps are best-effort and can no longer fail the (committed) create.
+  - incident-backend: `createIncident`, `updateIncident`, `addUpdate`, and `resolveIncident` wrap their row + system-link + timeline writes in a transaction (no more wiped system associations on a failed re-insert, or status flips with no matching timeline entry).
+  - maintenance-backend: same for `createMaintenance`, `updateMaintenance`, `addUpdate`, `closeMaintenance`.
+  - automation-backend: `cancelRun` marks the run cancelled and tears down its wait locks + durable state in one transaction - previously a failure after the status update could leave a wait lock behind, letting a later trigger event resume an already-cancelled run.
+  - healthcheck-backend: `ingestSatelliteResult` commits the run row and its hourly-aggregate increment together (no orphaned run, no aggregate without a backing run). NOTE: this guarantees run/aggregate consistency but does not yet make a _duplicate satellite delivery_ idempotent - that needs a dedupe key on the high-volume runs table and is tracked as a follow-up.
+
+  **Retry-duplication blocked at the DB (paired with the SQLSTATE 23505 -> 409 mapping shipped separately):**
+
+  - catalog-backend: new unique indexes on `groups.name`, `environments.name` (consistent with `systems.name`), on `system_links (system_id, url)`, and on `system_contacts (system_id, user_id)` + `(system_id, email)` (NULLs are distinct, so user vs mailbox contacts don't interfere). Name uniqueness is CASE-INSENSITIVE: the three name indexes are functional `lower(name)` indexes (the existing `systems.name` index is rebuilt this way too), so "Api" and "api" collide while the stored value keeps its original casing. The systems pre-write name check (`getSystemByName`) is case-folded to match. Migration `0005` de-dupes any pre-existing rows first - names are preserved by suffixing later case-insensitive duplicates (" (2)", " (3)", ...), redundant contact/link rows are removed keeping the earliest. (Link URLs stay case-sensitive - URL paths are; contact emails are deduped exact-match.)
+  - incident-backend / maintenance-backend: unique index on `incident_links (incident_id, url)` / `maintenance_links (maintenance_id, url)`, with a de-dupe step in the migration.
+
+    **Behavior change:** creating a group/environment with a duplicate name, or attaching a duplicate contact/link, now returns `409 Conflict` instead of silently creating a duplicate. The migrations resolve existing duplicates on upgrade.
+
+  This is a beta patch.
+
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+- Updated dependencies [9dcc848]
+  - @checkstack/backend-api@0.21.0
+  - @checkstack/common@0.13.0
+  - @checkstack/signal-common@0.2.6
+
 ## 0.2.12
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/signal-backend",
-  "version": "0.2.12",
+  "version": "0.3.0",
   "license": "Elastic-2.0",
   "type": "module",
   "exports": {
@@ -11,7 +11,7 @@
   "dependencies": {
     "@checkstack/common": "0.12.0",
     "@checkstack/signal-common": "0.2.5",
-    "@checkstack/backend-api": "0.18.0"
+    "@checkstack/backend-api": "0.20.0"
   },
   "devDependencies": {
     "@types/bun": "latest",
@@ -26,6 +26,6 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "checkstack": {
-    "type": "backend"
+    "type": "tooling"
   }
 }

package/src/signal-service-impl.test.ts

@@ -161,6 +161,79 @@ describe("SignalServiceImpl", () => {
   });
 });
 
+describe("resilience: a signal failure never fails the caller's committed write", () => {
+  let throwingService: SignalServiceImpl;
+  let throwingLogger: Logger;
+  let warnCalls: number;
+
+  beforeEach(() => {
+    warnCalls = 0;
+    const throwingEventBus = {
+      // Simulate a transient event-bus/queue outage on emit.
+      emit: mock(async () => {
+        throw new Error("event bus unavailable");
+      }),
+      subscribe: mock(async () => {}),
+      shutdown: mock(async () => {}),
+    } as unknown as EventBus;
+    throwingLogger = {
+      debug: mock(() => {}),
+      info: mock(() => {}),
+      warn: mock(() => {
+        warnCalls += 1;
+      }),
+      error: mock(() => {}),
+      child: mock(() => throwingLogger),
+    } as unknown as Logger;
+    throwingService = new SignalServiceImpl(throwingEventBus, throwingLogger);
+  });
+
+  it("broadcast resolves (does not throw) when the event bus emit fails, and logs a warning", async () => {
+    await expect(
+      throwingService.broadcast(TEST_BROADCAST_SIGNAL, { message: "hi" }),
+    ).resolves.toBeUndefined();
+    expect(warnCalls).toBe(1);
+  });
+
+  it("sendToUser resolves when the event bus emit fails", async () => {
+    await expect(
+      throwingService.sendToUser(TEST_USER_SIGNAL, "u1", {
+        notification: "n",
+        count: 1,
+      }),
+    ).resolves.toBeUndefined();
+    expect(warnCalls).toBe(1);
+  });
+
+  it("sendToUsers resolves when every per-user emit fails", async () => {
+    await expect(
+      throwingService.sendToUsers(TEST_USER_SIGNAL, ["u1", "u2"], {
+        notification: "n",
+        count: 1,
+      }),
+    ).resolves.toBeUndefined();
+    expect(warnCalls).toBe(2);
+  });
+
+  it("sendToAuthorizedUsers resolves when the auth-filter RPC fails", async () => {
+    throwingService.setAuthClient({
+      filterUsersByAccessRule: mock(async () => {
+        throw new Error("auth rpc down");
+      }),
+    });
+    await expect(
+      throwingService.sendToAuthorizedUsers(
+        TEST_USER_SIGNAL,
+        ["u1"],
+        { notification: "n", count: 1 },
+        testPluginMetadata,
+        { id: "thing.read" },
+      ),
+    ).resolves.toBeUndefined();
+    expect(warnCalls).toBe(1);
+  });
+});
+
 describe("Signal Hooks", () => {
   it("should have correct hook IDs", () => {
     expect(SIGNAL_BROADCAST_HOOK.id).toBe("signal.internal.broadcast");

package/src/signal-service-impl.ts

@@ -37,6 +37,34 @@ export class SignalServiceImpl implements SignalService {
     this.authClient = client;
   }
 
+  /**
+   * Real-time signals are BEST-EFFORT, by platform contract. They are a UI
+   * convenience (a live push so a client refreshes sooner); the authoritative
+   * data is already committed to the database by the time a mutation broadcasts.
+   * A transient event-bus/queue failure must therefore NEVER turn a successful,
+   * committed write into a client-visible error. Every signal-send routes
+   * through here so that guarantee holds for ALL callers - including future
+   * plugins - without each call site needing its own try/catch (which would
+   * inevitably be forgotten and regress). The mirror of `createCachedScope`,
+   * which already makes cache invalidation non-throwing the same way.
+   *
+   * If a send fails, the client simply misses one live nudge and picks up the
+   * (already-persisted) state on its next fetch/refetch.
+   */
+  private async safeSend(
+    description: string,
+    send: () => Promise<void>,
+  ): Promise<void> {
+    try {
+      await send();
+    } catch (error) {
+      this.logger.warn(
+        `Signal delivery failed (${description}) - the write succeeded; clients will reconcile on next fetch.`,
+        { error },
+      );
+    }
+  }
+
   async broadcast<T>(signal: Signal<T>, payload: T): Promise<void> {
     const message: SignalMessage<T> = {
       signalId: signal.id,
@@ -48,7 +76,9 @@ export class SignalServiceImpl implements SignalService {
     this.logger.debug(`Broadcasting signal: ${signal.id}`);
 
     // Emit to EventBus - all backend instances receive and push to their WebSocket clients
-    await this.eventBus.emit(SIGNAL_BROADCAST_HOOK, message);
+    await this.safeSend(`broadcast ${signal.id}`, () =>
+      this.eventBus.emit(SIGNAL_BROADCAST_HOOK, message),
+    );
   }
 
   async sendToUser<T>(
@@ -65,7 +95,9 @@ export class SignalServiceImpl implements SignalService {
 
     this.logger.debug(`Sending signal ${signal.id} to user ${userId}`);
 
-    await this.eventBus.emit(SIGNAL_USER_HOOK, { userId, message });
+    await this.safeSend(`${signal.id} -> user ${userId}`, () =>
+      this.eventBus.emit(SIGNAL_USER_HOOK, { userId, message }),
+    );
   }
 
   async sendToUsers<T>(
@@ -97,11 +129,22 @@ export class SignalServiceImpl implements SignalService {
     // Construct fully-qualified access rule ID: ${pluginMetadata.pluginId}.${accessRule.id}
     const qualifiedAccessRule = qualifyAccessRuleId(pluginMetadata, accessRule);
 
-    // Filter users via auth RPC
-    const authorizedIds = await this.authClient.filterUsersByAccessRule({
-      userIds,
-      accessRule: qualifiedAccessRule,
-    });
+    // Filter users via auth RPC. Best-effort like the send itself: if the auth
+    // lookup transiently fails, skip the live nudge rather than fail the caller's
+    // already-committed write.
+    let authorizedIds: string[];
+    try {
+      authorizedIds = await this.authClient.filterUsersByAccessRule({
+        userIds,
+        accessRule: qualifiedAccessRule,
+      });
+    } catch (error) {
+      this.logger.warn(
+        `Signal delivery failed (authz filter for ${signal.id}) - the write succeeded; clients will reconcile on next fetch.`,
+        { error },
+      );
+      return;
+    }
 
     if (authorizedIds.length === 0) {
       this.logger.debug(