@checkstack/healthcheck-common 0.4.1 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @checkstack/healthcheck-common
 
+## 0.5.0
+
+### Minor Changes
+
+- ac3a4cf: ### Dynamic Bucket Sizing for Health Check Visualization
+
+  Implements industry-standard dynamic bucket sizing for health check data aggregation, following patterns from Grafana/VictoriaMetrics.
+
+  **What changed:**
+
+  - Replaced fixed `bucketSize: "hourly" | "daily" | "auto"` with dynamic `targetPoints` parameter (default: 500)
+  - Bucket interval is now calculated as `(endDate - startDate) / targetPoints` with a minimum of 1 second
+  - Added `bucketIntervalSeconds` to aggregated response and individual buckets
+  - Updated chart components to use dynamic time formatting based on bucket interval
+
+  **Why:**
+
+  - A 24-hour view with 1-second health checks previously returned 86,400+ data points, causing lag
+  - Now returns ~500 data points regardless of timeframe, ensuring consistent chart performance
+  - Charts still preserve visual fidelity through proper aggregation
+
+  **Breaking Change:**
+
+  - `bucketSize` parameter removed from `getAggregatedHistory` and `getDetailedAggregatedHistory` endpoints
+  - Use `targetPoints` instead (defaults to 500 if not specified)
+
+  ***
+
+  ### Collector Aggregated Charts Fix
+
+  Fixed issue where collector auto-charts (like HTTP request response time charts) were not showing in aggregated data mode.
+
+  **What changed:**
+
+  - Added `aggregatedResultSchema` to `CollectorDtoSchema`
+  - Backend now returns collector aggregated schemas via `getCollectors` endpoint
+  - Frontend `useStrategySchemas` hook now merges collector aggregated schemas
+  - Service now calls each collector's `aggregateResult()` when building buckets
+  - Aggregated collector data stored in `aggregatedResult.collectors[uuid]`
+
+  **Why:**
+
+  - Previously only strategy-level aggregated results were computed
+  - Collectors like HTTP Request Collector have their own `aggregateResult` method
+  - Without calling these, fields like `avgResponseTimeMs` and `successRate` were missing from aggregated buckets
+
+- db1f56f: Add ephemeral field stripping to reduce database storage for health checks
+
+  - Added `x-ephemeral` metadata flag to `HealthResultMeta` for marking fields that should not be persisted
+  - All health result factory functions (`healthResultString`, `healthResultNumber`, `healthResultBoolean`, `healthResultArray`, `healthResultJSONPath`) now accept `x-ephemeral`
+  - Added `stripEphemeralFields()` utility to remove ephemeral fields before database storage
+  - Integrated ephemeral field stripping into `queue-executor.ts` for all collector results
+  - HTTP Request collector now explicitly marks `body` as ephemeral
+
+  This significantly reduces database storage for health checks with large response bodies, while still allowing assertions to run against the full response at execution time.
+
+### Patch Changes
+
+- Updated dependencies [db1f56f]
+  - @checkstack/common@0.6.0
+  - @checkstack/signal-common@0.1.4
+
+## 0.4.2
+
+### Patch Changes
+
+- 8a87cd4: Updated access rules to use new `accessPair` interface
+
+  Migrated to the new `accessPair` interface with per-level options objects for cleaner access rule definitions.
+
+- Updated dependencies [8a87cd4]
+  - @checkstack/common@0.5.0
+  - @checkstack/signal-common@0.1.3
+
 ## 0.4.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-common",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "exports": {
     ".": {

package/src/access.ts

@@ -8,6 +8,9 @@ export const healthCheckAccess = {
    * Status-only access for viewing health check status.
    * Enabled by default for anonymous and authenticated users.
    * Uses system-level instance access for team-based filtering.
+   *
+   * Bulk endpoints should use the same access rule with instanceAccess
+   * override at the contract level.
    */
   status: access("healthcheck.status", "read", "View Health Check Status", {
     idParam: "systemId",
@@ -15,22 +18,12 @@ export const healthCheckAccess = {
     isPublic: true,
   }),
 
-  /**
-   * Bulk status access for viewing health check status for multiple systems.
-   * Uses recordKey for filtering the output record by accessible system IDs.
-   */
-  bulkStatus: access("healthcheck.status", "read", "View Health Check Status", {
-    recordKey: "statuses",
-    isDefault: true,
-    isPublic: true,
-  }),
-
   /**
    * Configuration access for viewing and managing health check configurations.
    */
   configuration: accessPair("healthcheck", {
-    read: "Read Health Check Configurations",
-    manage: "Full management of Health Check Configurations",
+    read: { description: "Read Health Check Configurations" },
+    manage: { description: "Full management of Health Check Configurations" },
   }),
 
   /**
@@ -40,7 +33,7 @@ export const healthCheckAccess = {
   details: access(
     "healthcheck.details",
     "read",
-    "View Detailed Health Check Run Data (Warning: This may expose sensitive data, depending on the health check strategy)"
+    "View Detailed Health Check Run Data (Warning: This may expose sensitive data, depending on the health check strategy)",
   ),
 };
 

package/src/rpc-contract.ts

@@ -67,7 +67,7 @@ export const healthCheckContract = {
     userType: "authenticated",
     access: [healthCheckAccess.configuration.read],
   }).output(
-    z.object({ configurations: z.array(HealthCheckConfigurationSchema) })
+    z.object({ configurations: z.array(HealthCheckConfigurationSchema) }),
   ),
 
   createConfiguration: proc({
@@ -87,7 +87,7 @@ export const healthCheckContract = {
       z.object({
         id: z.string(),
         body: UpdateHealthCheckConfigurationSchema,
-      })
+      }),
     )
     .output(HealthCheckConfigurationSchema),
 
@@ -124,8 +124,8 @@ export const healthCheckContract = {
           configurationName: z.string(),
           enabled: z.boolean(),
           stateThresholds: StateThresholdsSchema.optional(),
-        })
-      )
+        }),
+      ),
     ),
 
   associateSystem: proc({
@@ -137,7 +137,7 @@ export const healthCheckContract = {
       z.object({
         systemId: z.string(),
         body: AssociateHealthCheckSchema,
-      })
+      }),
     )
     .output(z.void()),
 
@@ -150,7 +150,7 @@ export const healthCheckContract = {
       z.object({
         systemId: z.string(),
         configId: z.string(),
-      })
+      }),
     )
     .output(z.void()),
 
@@ -167,12 +167,12 @@ export const healthCheckContract = {
       z.object({
         systemId: z.string(),
         configurationId: z.string(),
-      })
+      }),
     )
     .output(
       z.object({
         retentionConfig: RetentionConfigSchema.nullable(),
-      })
+      }),
     ),
 
   updateRetentionConfig: proc({
@@ -185,7 +185,7 @@ export const healthCheckContract = {
         systemId: z.string(),
         configurationId: z.string(),
         retentionConfig: RetentionConfigSchema.nullable(),
-      })
+      }),
     )
     .output(z.void()),
 
@@ -206,13 +206,13 @@ export const healthCheckContract = {
         endDate: z.date().optional(),
         limit: z.number().optional().default(10),
         offset: z.number().optional().default(0),
-      })
+      }),
     )
     .output(
       z.object({
         runs: z.array(HealthCheckRunPublicSchema),
         total: z.number(),
-      })
+      }),
     ),
 
   getDetailedHistory: proc({
@@ -228,13 +228,13 @@ export const healthCheckContract = {
         endDate: z.date().optional(),
         limit: z.number().optional().default(10),
         offset: z.number().optional().default(0),
-      })
+      }),
     )
     .output(
       z.object({
         runs: z.array(HealthCheckRunSchema),
         total: z.number(),
-      })
+      }),
     ),
 
   getAggregatedHistory: proc({
@@ -248,13 +248,16 @@ export const healthCheckContract = {
         configurationId: z.string(),
         startDate: z.date(),
         endDate: z.date(),
-        bucketSize: z.enum(["hourly", "daily", "auto"]),
-      })
+        /** Target number of data points (default: 500). Bucket interval is calculated as (endDate - startDate) / targetPoints */
+        targetPoints: z.number().min(10).max(2000).default(500),
+      }),
     )
     .output(
       z.object({
         buckets: z.array(AggregatedBucketBaseSchema),
-      })
+        /** The calculated bucket interval in seconds */
+        bucketIntervalSeconds: z.number(),
+      }),
     ),
 
   getDetailedAggregatedHistory: proc({
@@ -268,13 +271,16 @@ export const healthCheckContract = {
         configurationId: z.string(),
         startDate: z.date(),
         endDate: z.date(),
-        bucketSize: z.enum(["hourly", "daily", "auto"]),
-      })
+        /** Target number of data points (default: 500). Bucket interval is calculated as (endDate - startDate) / targetPoints */
+        targetPoints: z.number().min(10).max(2000).default(500),
+      }),
     )
     .output(
       z.object({
         buckets: z.array(AggregatedBucketSchema),
-      })
+        /** The calculated bucket interval in seconds */
+        bucketIntervalSeconds: z.number(),
+      }),
     ),
 
   getSystemHealthStatus: proc({
@@ -288,13 +294,14 @@ export const healthCheckContract = {
   getBulkSystemHealthStatus: proc({
     operationType: "query",
     userType: "public",
-    access: [healthCheckAccess.bulkStatus],
+    access: [healthCheckAccess.status],
+    instanceAccess: { recordKey: "statuses" },
   })
     .input(z.object({ systemIds: z.array(z.string()) }))
     .output(
       z.object({
         statuses: z.record(z.string(), SystemHealthStatusResponseSchema),
-      })
+      }),
     ),
 
   getSystemHealthOverview: proc({
@@ -320,11 +327,11 @@ export const healthCheckContract = {
                 id: z.string(),
                 status: HealthCheckStatusSchema,
                 timestamp: z.date(),
-              })
+              }),
             ),
-          })
+          }),
         ),
-      })
+      }),
     ),
 };
 
@@ -335,5 +342,5 @@ export type HealthCheckContract = typeof healthCheckContract;
 // Use: const client = rpcApi.forPlugin(HealthCheckApi);
 export const HealthCheckApi = createClientDefinition(
   healthCheckContract,
-  pluginMetadata
+  pluginMetadata,
 );

package/src/schemas.ts

@@ -32,6 +32,8 @@ export const CollectorDtoSchema = z.object({
   configSchema: z.record(z.string(), z.unknown()),
   /** JSON Schema for per-run result metadata (with chart annotations) */
   resultSchema: z.record(z.string(), z.unknown()),
+  /** JSON Schema for aggregated result metadata (with chart annotations) */
+  aggregatedResultSchema: z.record(z.string(), z.unknown()).optional(),
   /** Whether multiple instances of this collector are allowed per config */
   allowMultiple: z.boolean(),
 });
@@ -276,7 +278,10 @@ export const DEFAULT_RETENTION_CONFIG: RetentionConfig = {
  */
 export const AggregatedBucketBaseSchema = z.object({
   bucketStart: z.date(),
-  bucketSize: z.enum(["hourly", "daily"]),
+  /** @deprecated Use bucketIntervalSeconds instead. Kept for backward compatibility. */
+  bucketSize: z.enum(["hourly", "daily"]).optional(),
+  /** Bucket interval in seconds (e.g., 7 for 7-second buckets) */
+  bucketIntervalSeconds: z.number(),
   runCount: z.number(),
   healthyCount: z.number(),
   degradedCount: z.number(),

package/src/zod-health-result.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "bun:test";
+import { z } from "zod";
+import {
+  healthResultSchema,
+  healthResultNumber,
+  healthResultString,
+  healthResultJSONPath,
+  stripEphemeralFields,
+  getHealthResultMeta,
+} from "./zod-health-result";
+
+describe("stripEphemeralFields", () => {
+  it("should strip fields marked with x-ephemeral", () => {
+    const schema = healthResultSchema({
+      statusCode: healthResultNumber({ "x-chart-type": "counter" }),
+      body: healthResultJSONPath({ "x-ephemeral": true }), // Explicitly marked ephemeral
+    });
+
+    const result = {
+      statusCode: 200,
+      body: '{"large":"response body that should not be stored"}',
+    };
+
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual({ statusCode: 200 });
+    expect(stripped).not.toHaveProperty("body");
+  });
+
+  it("should preserve non-ephemeral fields", () => {
+    const schema = healthResultSchema({
+      responseTimeMs: healthResultNumber({ "x-chart-type": "line" }),
+      statusText: healthResultString({ "x-chart-type": "text" }),
+    });
+
+    const result = {
+      responseTimeMs: 150,
+      statusText: "OK",
+    };
+
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual(result);
+  });
+
+  it("should preserve unknown fields like _collectorId", () => {
+    const schema = healthResultSchema({
+      value: healthResultNumber({ "x-chart-type": "counter" }),
+      body: healthResultJSONPath({ "x-ephemeral": true }),
+    });
+
+    const result = {
+      _collectorId: "http.request",
+      _assertionFailed: undefined,
+      value: 42,
+      body: "large body content",
+    };
+
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual({
+      _collectorId: "http.request",
+      _assertionFailed: undefined,
+      value: 42,
+    });
+  });
+
+  it("should return original result for non-ZodObject schemas", () => {
+    const schema = z.string();
+    const result = { foo: "bar" };
+
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual(result);
+  });
+
+  it("should handle empty result objects", () => {
+    const schema = healthResultSchema({
+      body: healthResultJSONPath({ "x-ephemeral": true }),
+    });
+
+    const result = {};
+    const stripped = stripEphemeralFields(result, schema);
+
+    expect(stripped).toEqual({});
+  });
+});
+
+describe("healthResultJSONPath", () => {
+  it("should allow explicitly marking fields as ephemeral", () => {
+    const field = healthResultJSONPath({ "x-ephemeral": true });
+    const meta = getHealthResultMeta(field);
+
+    expect(meta?.["x-ephemeral"]).toBe(true);
+    expect(meta?.["x-jsonpath"]).toBe(true);
+  });
+
+  it("should not be ephemeral by default", () => {
+    const field = healthResultJSONPath({});
+    const meta = getHealthResultMeta(field);
+
+    expect(meta?.["x-ephemeral"]).toBeUndefined();
+    expect(meta?.["x-jsonpath"]).toBe(true);
+  });
+});

package/src/zod-health-result.ts

@@ -86,7 +86,7 @@ export type HealthResultShape = Record<string, HealthResultFieldType>;
  * ```
  */
 export function healthResultSchema<T extends HealthResultShape>(
-  shape: T
+  shape: T,
 ): z.ZodObject<T> {
   return z.object(shape);
 }
@@ -111,7 +111,7 @@ type ChartMeta = Omit<HealthResultMeta, "x-jsonpath">;
  * ```
  */
 export function healthResultString(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodString> {
   const schema = z.string();
   schema.register(healthResultRegistry, meta);
@@ -122,7 +122,7 @@ export function healthResultString(
  * Create a health result number field with typed chart metadata.
  */
 export function healthResultNumber(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodNumber> {
   const schema = z.number();
   schema.register(healthResultRegistry, meta);
@@ -133,7 +133,7 @@ export function healthResultNumber(
  * Create a health result boolean field with typed chart metadata.
  */
 export function healthResultBoolean(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodBoolean> {
   const schema = z.boolean();
   schema.register(healthResultRegistry, meta);
@@ -152,7 +152,7 @@ export function healthResultBoolean(
  * ```
  */
 export function healthResultArray(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodArray<z.ZodString>> {
   const schema = z.array(z.string());
   schema.register(healthResultRegistry, meta);
@@ -173,7 +173,7 @@ export function healthResultArray(
  * ```
  */
 export function healthResultJSONPath(
-  meta: ChartMeta
+  meta: ChartMeta,
 ): HealthResultField<z.ZodString> {
   const schema = z.string();
   schema.register(healthResultRegistry, { ...meta, "x-jsonpath": true });
@@ -213,7 +213,60 @@ function unwrapSchema(schema: z.ZodTypeAny): z.ZodTypeAny {
  * Automatically unwraps Optional/Default/Nullable wrappers.
  */
 export function getHealthResultMeta(
-  schema: z.ZodTypeAny
+  schema: z.ZodTypeAny,
 ): HealthResultMeta | undefined {
   return healthResultRegistry.get(unwrapSchema(schema));
 }
+
+// ============================================================================
+// EPHEMERAL FIELD STRIPPING - For storage optimization
+// ============================================================================
+
+/**
+ * Strip ephemeral fields from a result object before database storage.
+ *
+ * Ephemeral fields (marked with x-ephemeral: true) are used during health check
+ * execution for assertions but should not be persisted to save storage space.
+ * Common example: HTTP response bodies used for JSONPath assertions.
+ *
+ * @param result - The full result object from collector execution
+ * @param schema - The Zod schema with health result metadata
+ * @returns A new object with ephemeral fields removed
+ *
+ * @example
+ * ```typescript
+ * const stripped = stripEphemeralFields(collectorResult.result, collector.result.schema);
+ * // The 'body' field (marked with x-ephemeral) is removed before storage
+ * ```
+ */
+export function stripEphemeralFields<T extends Record<string, unknown>>(
+  result: T,
+  schema: z.ZodTypeAny,
+): Partial<T> {
+  // Handle ZodObject schemas
+  if (!(schema instanceof z.ZodObject)) {
+    return result;
+  }
+
+  const shape = schema.shape as Record<string, z.ZodTypeAny>;
+  const stripped: Record<string, unknown> = {};
+
+  for (const [key, value] of Object.entries(result)) {
+    const fieldSchema = shape[key];
+    if (!fieldSchema) {
+      // Keep unknown fields (e.g., _collectorId, _assertionFailed)
+      stripped[key] = value;
+      continue;
+    }
+
+    const meta = getHealthResultMeta(fieldSchema);
+    if (meta?.["x-ephemeral"]) {
+      // Skip ephemeral fields
+      continue;
+    }
+
+    stripped[key] = value;
+  }
+
+  return stripped as Partial<T>;
+}