@checkstack/healthcheck-backend 1.21.2 → 1.21.3

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # @checkstack/healthcheck-backend
 
+## 1.21.3
+
+### Patch Changes
+
+- 6c8b36b: Promote the health-check run-queue contract and the observability window
+  math into `@checkstack/healthcheck-common`: `HEALTH_CHECK_QUEUE`,
+  `HealthCheckJobPayload`, `fastPathJobId` (per-plugin prefix) and
+  `computeWindowBounds`/`computeSecondsSinceLast` now have ONE definition
+  that the queue owner (healthcheck-backend) and every observability
+  strategy plugin import, replacing the per-plugin mirror copies that had
+  to be kept in lock-step by convention. Enqueued job ids and window
+  semantics are byte-identical; this is a drift-proofing refactor, not a
+  behavior change.
+- 6c8b36b: Run the config-secrets backfill in afterPluginsReady instead of init.
+  Health-check strategies contributed by other plugins register during THEIR
+  init, and plugin init order follows the service-ref graph, so running the
+  backfill during healthcheck's own init could scan configurations before a
+  contributor (e.g. logstream's health strategy) had registered - skipping
+  that strategy's config with a "strategy not registered" warning at boot.
+  Only afterPluginsReady guarantees a complete registry. The backfill is
+  idempotent, so any configuration skipped by an earlier boot is picked up
+  on the next one.
+- 6c8b36b: Promote the t-digest percentile helpers from healthcheck-backend into
+  backend-api (`createTDigest`, `serializeTDigest`, `deserializeTDigest`,
+  `mergeTDigestStates`, `percentileFromState`, ...), so any plugin can maintain
+  mergeable percentile sketches; tracestream's per-operation p95 buckets are the
+  first new consumer. healthcheck-backend now imports the shared module (the
+  local copy is removed, no behavior change).
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+- Updated dependencies [6c8b36b]
+  - @checkstack/ai-backend@0.11.3
+  - @checkstack/backend-api@0.34.0
+  - @checkstack/healthcheck-common@1.18.0
+  - @checkstack/catalog-common@2.8.0
+  - @checkstack/queue-api@0.4.0
+  - @checkstack/common@0.23.0
+  - @checkstack/catalog-backend@1.10.0
+  - @checkstack/status-page-backend@0.6.5
+  - @checkstack/automation-backend@0.11.7
+  - @checkstack/incident-backend@1.13.5
+  - @checkstack/script-packages-backend@0.4.5
+  - @checkstack/sdk@0.133.1
+  - @checkstack/command-backend@0.2.26
+  - @checkstack/gitops-backend@0.5.26
+  - @checkstack/satellite-backend@0.9.3
+  - @checkstack/secrets-backend@0.3.8
+  - @checkstack/incident-common@1.10.4
+  - @checkstack/maintenance-common@1.10.4
+  - @checkstack/status-page-common@0.6.4
+  - @checkstack/ai-common@0.6.7
+  - @checkstack/cache-api@0.3.20
+  - @checkstack/gitops-common@0.7.4
+  - @checkstack/notification-common@1.7.2
+  - @checkstack/secrets-common@0.3.3
+  - @checkstack/signal-common@0.3.1
+  - @checkstack/cache-utils@0.3.1
+
 ## 1.21.2
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-backend",
-  "version": "1.21.2",
+  "version": "1.21.3",
   "license": "Elastic-2.0",
   "type": "module",
   "main": "src/index.ts",
@@ -14,50 +14,48 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/ai-backend": "0.11.2",
-    "@checkstack/ai-common": "0.6.6",
-    "@checkstack/automation-backend": "0.11.6",
-    "@checkstack/backend-api": "0.33.0",
-    "@checkstack/cache-api": "0.3.19",
-    "@checkstack/cache-utils": "0.3.0",
-    "@checkstack/catalog-backend": "1.9.2",
-    "@checkstack/catalog-common": "2.7.3",
-    "@checkstack/command-backend": "0.2.25",
-    "@checkstack/common": "0.22.0",
-    "@checkstack/gitops-backend": "0.5.25",
-    "@checkstack/gitops-common": "0.7.3",
-    "@checkstack/healthcheck-common": "1.17.0",
-    "@checkstack/incident-backend": "1.13.4",
-    "@checkstack/incident-common": "1.10.3",
-    "@checkstack/maintenance-common": "1.10.3",
-    "@checkstack/notification-common": "1.7.1",
-    "@checkstack/queue-api": "0.3.19",
-    "@checkstack/satellite-backend": "0.9.2",
-    "@checkstack/script-packages-backend": "0.4.4",
-    "@checkstack/sdk": "0.132.0",
-    "@checkstack/secrets-backend": "0.3.7",
-    "@checkstack/secrets-common": "0.3.2",
-    "@checkstack/signal-common": "0.3.0",
-    "@checkstack/status-page-backend": "0.6.4",
-    "@checkstack/status-page-common": "0.6.3",
+    "@checkstack/ai-backend": "0.11.3",
+    "@checkstack/ai-common": "0.6.7",
+    "@checkstack/automation-backend": "0.11.7",
+    "@checkstack/backend-api": "0.34.0",
+    "@checkstack/cache-api": "0.3.20",
+    "@checkstack/cache-utils": "0.3.1",
+    "@checkstack/catalog-backend": "1.10.0",
+    "@checkstack/catalog-common": "2.8.0",
+    "@checkstack/command-backend": "0.2.26",
+    "@checkstack/common": "0.23.0",
+    "@checkstack/gitops-backend": "0.5.26",
+    "@checkstack/gitops-common": "0.7.4",
+    "@checkstack/healthcheck-common": "1.18.0",
+    "@checkstack/incident-backend": "1.13.5",
+    "@checkstack/incident-common": "1.10.4",
+    "@checkstack/maintenance-common": "1.10.4",
+    "@checkstack/notification-common": "1.7.2",
+    "@checkstack/queue-api": "0.4.0",
+    "@checkstack/satellite-backend": "0.9.3",
+    "@checkstack/script-packages-backend": "0.4.5",
+    "@checkstack/sdk": "0.133.1",
+    "@checkstack/secrets-backend": "0.3.8",
+    "@checkstack/secrets-common": "0.3.3",
+    "@checkstack/signal-common": "0.3.1",
+    "@checkstack/status-page-backend": "0.6.5",
+    "@checkstack/status-page-common": "0.6.4",
     "@hono/zod-validator": "^0.7.6",
     "@orpc/contract": "^1.14.4",
     "@orpc/server": "^1.14.4",
     "drizzle-orm": "^0.45.0",
     "hono": "^4.12.25",
     "jsonpath-plus": "^10.4.0",
-    "tdigest": "^0.1.2",
     "yaml": "^2.6.1",
     "zod": "^4.2.1"
   },
   "devDependencies": {
     "@checkstack/drizzle-helper": "0.0.6",
-    "@checkstack/scripts": "0.7.5",
-    "@checkstack/test-utils-backend": "0.1.59",
+    "@checkstack/scripts": "0.7.6",
+    "@checkstack/test-utils-backend": "0.1.60",
     "@checkstack/tsconfig": "0.0.7",
     "@types/bun": "^1.0.0",
     "@types/pg": "^8.20.0",
-    "@types/tdigest": "^0.1.5",
     "bullmq": "^5.66.4",
     "date-fns": "^4.4.0",
     "drizzle-kit": "^0.31.10",

package/src/index.ts

@@ -287,20 +287,12 @@ export default createBackendPlugin({
         };
         gitopsConfigSecrets = configSecrets;
 
-        // Move any pre-channel inline secrets out of stored rows (idempotent,
-        // advisory-locked, fail-open: a backfill failure must not block boot).
-        try {
-          await backfillConfigSecrets({
-            db: typedDb,
-            registry: healthCheckRegistry,
-            collectorRegistry,
-            internalSecrets,
-            advisoryLock,
-            logger,
-          });
-        } catch (error) {
-          logger.warn("Config-secrets backfill failed; continuing boot", error);
-        }
+        // NOTE: the config-secrets backfill runs in afterPluginsReady, NOT
+        // here. Strategies contributed by OTHER plugins (e.g. logstream's
+        // LogStreamHealthStrategy) register during THEIR init(), and init
+        // order follows the service-ref graph - it is NOT guaranteed that
+        // every contributor initialized before this plugin. Backfilling here
+        // would skip configs of not-yet-registered strategies with a warn.
 
         // Resolve/search health-check configurations by name for the Teams admin
         // UI (team grants are stored as opaque `<type>:<configId>` rows, where
@@ -644,6 +636,30 @@ export default createBackendPlugin({
         // Store emitHook for the queue worker (Closure-based Hook Getter pattern)
         storedEmitHook = emitHook;
 
+        // Move any pre-channel inline secrets out of stored rows (idempotent,
+        // advisory-locked, fail-open: a backfill failure must not block boot).
+        // Runs HERE - after every plugin's init() - because strategies are
+        // contributed by other plugins during their init (e.g. logstream's
+        // health strategy), and only afterPluginsReady guarantees the registry
+        // is complete; running in init raced contributor init order.
+        if (gitopsConfigSecrets && resolvedAdvisoryLock) {
+          try {
+            await backfillConfigSecrets({
+              db: database,
+              registry: healthCheckRegistry,
+              collectorRegistry,
+              internalSecrets: gitopsConfigSecrets.internalSecrets,
+              advisoryLock: resolvedAdvisoryLock,
+              logger,
+            });
+          } catch (error) {
+            logger.warn(
+              "Config-secrets backfill failed; continuing boot",
+              error,
+            );
+          }
+        }
+
         // No cross-pod status-cache broadcast: the status cache runs on the
         // platform CacheManager, so a distributed backend (Redis) makes every
         // eviction visible to all pods through the shared store. The prior

package/src/queue-executor.ts

@@ -32,6 +32,15 @@ import {
   ENVIRONMENT_RESOLUTION_FAILED,
   type HealthCheckStatus,
   stripEphemeralFields,
+  HEALTH_CHECK_QUEUE,
+  type HealthCheckJobPayload,
+} from "@checkstack/healthcheck-common";
+// The run-queue contract (queue name + payload) now lives in the common leaf so
+// every fast-path enqueuer shares one shape; re-exported from the owner here
+// because this file's many internal importers reference these names.
+export {
+  HEALTH_CHECK_QUEUE,
+  type HealthCheckJobPayload,
 } from "@checkstack/healthcheck-common";
 import {
   CatalogApi,
@@ -244,12 +253,6 @@ async function emitCheckCompletedHook({
  * The scheduling reconciler owns which (config, system, env) jobs exist; the
  * `run_now` action enqueues one job per effective environment.
  */
-export interface HealthCheckJobPayload {
-  configId: string;
-  systemId: string;
-  environmentId: string | null;
-}
-
 /** Prefix every health-check recurring jobId shares (used for orphan scans). */
 export const HEALTH_CHECK_JOB_PREFIX = "healthcheck:";
 
@@ -268,13 +271,6 @@ export function encodeHealthCheckJobId(props: {
   return environmentId === null ? base : `${base}:${environmentId}`;
 }
 
-/**
- * Queue name for health check execution. Exported so consumers like
- * the `healthcheck.run_now` automation action can enqueue a one-off
- * job without re-importing the recurring-job factory.
- */
-export const HEALTH_CHECK_QUEUE = "health-checks";
-
 /**
  * Worker group for health check execution (work-queue mode)
  */

package/src/realtime-aggregation.test.ts

@@ -1,12 +1,11 @@
 import { describe, it, expect, mock, beforeEach } from "bun:test";
+import { getHourBucketStart, incrementHourlyAggregate } from "./realtime-aggregation";
 import {
-  getHourBucketStart,
   serializeTDigest,
   deserializeTDigest,
-  incrementHourlyAggregate,
-} from "./realtime-aggregation";
+  createTDigest,
+} from "@checkstack/backend-api";
 import { computeAssertionKey } from "@checkstack/healthcheck-common";
-import { TDigest } from "tdigest";
 
 describe("getHourBucketStart", () => {
   it("floors timestamp to the hour", () => {
@@ -42,7 +41,7 @@ describe("getHourBucketStart", () => {
 
 describe("t-digest serialization", () => {
   it("serializes and deserializes empty t-digest", () => {
-    const original = new TDigest();
+    const original = createTDigest();
     const serialized = serializeTDigest(original);
     const restored = deserializeTDigest(serialized);
 
@@ -52,7 +51,7 @@ describe("t-digest serialization", () => {
   });
 
   it("serializes and deserializes t-digest with values", () => {
-    const original = new TDigest();
+    const original = createTDigest();
     original.push(100);
     original.push(200);
     original.push(300);
@@ -67,7 +66,7 @@ describe("t-digest serialization", () => {
   });
 
   it("preserves p95 accuracy after serialization", () => {
-    const original = new TDigest();
+    const original = createTDigest();
     // Add 100 values from 1 to 100
     for (let i = 1; i <= 100; i++) {
       original.push(i);
@@ -85,7 +84,7 @@ describe("t-digest serialization", () => {
 
   it("handles incremental updates correctly", () => {
     // First batch
-    const digest1 = new TDigest();
+    const digest1 = createTDigest();
     digest1.push(100);
     digest1.push(110);
 
@@ -254,7 +253,7 @@ describe("incrementHourlyAggregate", () => {
   it("updates min/max when existing aggregate has values", async () => {
     // Set up existing aggregate
     existingAggregate = {
-      tdigestState: serializeTDigest(new TDigest()),
+      tdigestState: serializeTDigest(createTDigest()),
       minLatencyMs: 100,
       maxLatencyMs: 200,
     };
@@ -309,7 +308,7 @@ describe("incrementHourlyAggregate", () => {
 
   it("updates max when new latency is higher", async () => {
     existingAggregate = {
-      tdigestState: serializeTDigest(new TDigest()),
+      tdigestState: serializeTDigest(createTDigest()),
       minLatencyMs: 100,
       maxLatencyMs: 200,
     };
@@ -361,7 +360,7 @@ describe("incrementHourlyAggregate", () => {
 
   it("accumulates t-digest state across multiple runs", async () => {
     // First run
-    const digest1 = new TDigest();
+    const digest1 = createTDigest();
     digest1.push(100);
     digest1.push(200);
     digest1.push(300);

package/src/realtime-aggregation.ts

@@ -2,6 +2,10 @@ import type {
   ScopedQueryRunner,
   CollectorRegistry,
 } from "@checkstack/backend-api";
+import {
+  pushValuesIntoState,
+  percentileFromState,
+} from "@checkstack/backend-api";
 import {
   ASSERTIONS_AGG_KEY,
   AssertionOutcomeSchema,
@@ -9,7 +13,6 @@ import {
   readAssertionStats,
   type AssertionOutcome,
 } from "@checkstack/healthcheck-common";
-import { TDigest } from "tdigest";
 import * as schema from "./schema";
 import { healthCheckAggregates } from "./schema";
 import { eq, and, sql } from "drizzle-orm";
@@ -30,46 +33,6 @@ export function getHourBucketStart(timestamp: Date): Date {
   return bucketStart;
 }
 
-/**
- * Serialize a t-digest to an array of numbers for storage.
- * Format: [centroid1_mean, centroid1_n, centroid2_mean, centroid2_n, ...]
- */
-export function serializeTDigest(digest: TDigest): number[] {
-  const centroids = digest.toArray();
-  const result: number[] = [];
-  for (const c of centroids) {
-    result.push(c.mean, c.n);
-  }
-  return result;
-}
-
-/**
- * Deserialize a t-digest from storage format.
- */
-export function deserializeTDigest(state: number[]): TDigest {
-  const digest = new TDigest();
-
-  if (state.length === 0) {
-    return digest;
-  }
-
-  // Reconstruct centroids from pairs of [mean, n]
-  const centroids: Array<{ mean: number; n: number }> = [];
-  for (let i = 0; i < state.length; i += 2) {
-    const mean = state[i];
-    const n = state[i + 1];
-    if (mean !== undefined && n !== undefined && n > 0) {
-      centroids.push({ mean, n });
-    }
-  }
-
-  if (centroids.length > 0) {
-    digest.push_centroid(centroids);
-  }
-
-  return digest;
-}
-
 interface IncrementHourlyAggregateParams {
   db: Db;
   systemId: string;
@@ -177,15 +140,14 @@ export async function incrementHourlyAggregate(
             max = latencyMs;
           }
 
-          // Update t-digest for p95 calculation
-          const digest =
-            existing?.tdigestState && existing.tdigestState.length > 0
-              ? deserializeTDigest(existing.tdigestState)
-              : new TDigest();
-
-          digest.push(latencyMs);
-          const tdigestState = serializeTDigest(digest);
-          const p95 = Math.round(digest.percentile(0.95));
+          // Update t-digest for p95 calculation (shared backend-api helper).
+          const tdigestState = pushValuesIntoState({
+            state: existing?.tdigestState ?? null,
+            values: [latencyMs],
+          });
+          const p95 = Math.round(
+            percentileFromState({ state: tdigestState, q: 0.95 }) ?? latencyMs,
+          );
 
           return { latencySumIncr, min, max, tdigestState, p95 };
         })();