@checkstack/backend-api 0.11.1 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,82 @@
 # @checkstack/backend-api
 
+## 0.13.0
+
+### Minor Changes
+
+- 8d1ef12: ## Infrastructure Configuration Shell & Cache System
+
+  ### New Packages
+
+  - **`@checkstack/cache-api`**: Core cache abstractions — `CacheProvider` interface, `createScopedCache` factory for plugin key isolation, `CachePlugin`/`CacheManager` lifecycle interfaces.
+  - **`@checkstack/cache-common`**: Shared cache types, RPC contract (`getPlugins`, `getConfiguration`, `updateConfiguration`), access rules, and plugin metadata.
+  - **`@checkstack/cache-backend`**: Cache settings RPC router — exposes plugin discovery, configuration read/write endpoints with access-gated authorization.
+  - **`@checkstack/cache-frontend`**: Cache configuration tab component for the Infrastructure Settings page.
+  - **`@checkstack/infrastructure-common`**: Infrastructure tab registry, routes, and shared types for the IDE-style configuration shell.
+  - **`@checkstack/infrastructure-frontend`**: Infrastructure Settings page with vertical tab bar, per-tab access control, and user menu integration.
+
+  ### Modified Packages
+
+  - **`@checkstack/backend-api`**: Added `cachePluginRegistry` and `cacheManager` to `RpcContext` and `coreServices`.
+  - **`@checkstack/backend`**: Registered cache services in boot sequence, added cache config loading, extended dependency sorter for cache plugin ordering.
+  - **`@checkstack/queue-frontend`**: Refactored from standalone `/queue/config` route to an infrastructure tab. Queue settings now live inside the Infrastructure Settings page.
+
+  ### Architecture
+
+  The former monolithic Queue Config page is replaced by a pluggable Infrastructure Settings shell (`/infrastructure/config`). Plugins register configuration tabs via `registerInfrastructureTab()` with their own access rules, icons, and components. The shell evaluates per-tab access and only renders tabs the user can see.
+
+### Patch Changes
+
+- Updated dependencies [8d1ef12]
+- Updated dependencies [8d1ef12]
+- Updated dependencies [8d1ef12]
+- Updated dependencies [8d1ef12]
+  - @checkstack/healthcheck-common@0.12.0
+  - @checkstack/common@0.7.0
+  - @checkstack/cache-api@0.2.0
+  - @checkstack/signal-common@0.1.10
+  - @checkstack/queue-api@0.2.14
+
+## 0.12.0
+
+### Minor Changes
+
+- 26d8bae: Distributed satellite health checks and Assignment IDE page
+
+  **Satellite System**
+
+  - New `satellite-backend`, `satellite-common`, `satellite-frontend`, and `satellite` agent packages for distributed health check execution
+  - WebSocket-based satellite connectivity with authentication, heartbeats, and live configuration push
+  - Satellite management UI with create dialog, status badges, and list page
+
+  **Live Configuration Updates**
+
+  - Added `assignmentChanged` hook to `healthcheck-backend` for cross-plugin communication
+  - `satellite-backend` subscribes to assignment changes and pushes config updates to connected satellites in real-time
+
+  **Assignment IDE Page**
+
+  - Replaced the 1028-line modal-based `SystemHealthCheckAssignment` component with a full-page IDE layout
+  - New modular components: `AssignmentTree`, `GeneralPanel`, `ThresholdsPanel`, `RetentionPanel`, `ExecutionPanel`
+  - Added unassign capability and sorted assignment lists for stable ordering
+
+  **Shared IDE Primitives**
+
+  - Extracted `IDETreeNode`, `IDETreeSection`, `IDEStatusBar`, `IDELayout` to `@checkstack/ui` for cross-plugin reuse
+  - Migrated existing health check IDE editor to use shared primitives
+
+  **Infrastructure**
+
+  - Added `Dockerfile.satellite` for containerized satellite deployment
+  - WebSocket route registry in `@checkstack/backend` and `@checkstack/backend-api`
+
+### Patch Changes
+
+- Updated dependencies [26d8bae]
+- Updated dependencies [26d8bae]
+  - @checkstack/healthcheck-common@0.11.0
+  - @checkstack/queue-api@0.2.13
+
 ## 0.11.1
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/backend-api",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {
@@ -9,10 +9,11 @@
     "lint:code": "eslint . --max-warnings 0"
   },
   "dependencies": {
-    "@checkstack/common": "0.6.4",
-    "@checkstack/healthcheck-common": "0.10.0",
-    "@checkstack/queue-api": "0.2.11",
-    "@checkstack/signal-common": "0.1.8",
+    "@checkstack/common": "0.6.5",
+    "@checkstack/healthcheck-common": "0.11.0",
+    "@checkstack/cache-api": "0.1.0",
+    "@checkstack/queue-api": "0.2.13",
+    "@checkstack/signal-common": "0.1.9",
     "@orpc/client": "^1.13.14",
     "@orpc/contract": "^1.13.14",
     "@orpc/openapi": "^1.13.2",

package/src/aggregated-result.test.ts

@@ -13,6 +13,7 @@ describe("aggregatedAverage", () => {
     const field = aggregatedAverage({
       "x-chart-type": "line",
       "x-chart-label": "Avg Response Time",
+      "x-anomaly-enabled": false,
     });
 
     expect(field.type).toBe("average");
@@ -39,6 +40,7 @@ describe("aggregatedRate", () => {
     const field = aggregatedRate({
       "x-chart-type": "gauge",
       "x-chart-label": "Success Rate",
+      "x-anomaly-enabled": false,
     });
 
     expect(field.type).toBe("rate");
@@ -65,6 +67,7 @@ describe("aggregatedCounter", () => {
   it("creates field with correct type", () => {
     const field = aggregatedCounter({
       "x-chart-type": "counter",
+      "x-anomaly-enabled": false,
     });
 
     expect(field.type).toBe("counter");
@@ -81,6 +84,7 @@ describe("aggregatedMinMax", () => {
   it("creates field with correct type", () => {
     const field = aggregatedMinMax({
       "x-chart-type": "line",
+      "x-anomaly-enabled": false,
     });
 
     expect(field.type).toBe("minmax");
@@ -202,6 +206,7 @@ describe("chart metadata registration", () => {
       "x-chart-type": "line",
       "x-chart-label": "Avg Response Time",
       "x-chart-unit": "ms",
+      "x-anomaly-enabled": false,
     });
 
     // The stateSchema should have metadata registered via healthResultRegistry
@@ -219,6 +224,7 @@ describe("chart metadata registration", () => {
       "x-chart-type": "gauge",
       "x-chart-label": "Success Rate",
       "x-chart-unit": "%",
+      "x-anomaly-enabled": false,
     });
 
     const meta = getHealthResultMeta(field.stateSchema);
@@ -232,6 +238,7 @@ describe("chart metadata registration", () => {
     const field = aggregatedCounter({
       "x-chart-type": "counter",
       "x-chart-label": "Error Count",
+      "x-anomaly-enabled": false,
     });
 
     const meta = getHealthResultMeta(field.stateSchema);
@@ -245,6 +252,7 @@ describe("chart metadata registration", () => {
     const field = aggregatedMinMax({
       "x-chart-type": "line",
       "x-chart-label": "Latency Range",
+      "x-anomaly-enabled": false,
     });
 
     const meta = getHealthResultMeta(field.stateSchema);
@@ -258,11 +266,13 @@ describe("chart metadata registration", () => {
     const field1 = aggregatedAverage({
       "x-chart-type": "line",
       "x-chart-label": "First Field",
+      "x-anomaly-enabled": false,
     });
 
     const field2 = aggregatedAverage({
       "x-chart-type": "gauge",
       "x-chart-label": "Second Field",
+      "x-anomaly-enabled": false,
     });
 
     const meta1 = getHealthResultMeta(field1.stateSchema);

package/src/aggregated-result.ts

@@ -40,7 +40,8 @@ export type AggregationType = "average" | "rate" | "counter" | "minmax";
 // =============================================================================
 
 /** Base metadata for chart annotations (excludes x-jsonpath) */
-type ChartMeta = Omit<HealthResultMeta, "x-jsonpath">;
+type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
+type ChartMeta = DistributiveOmit<HealthResultMeta, "x-jsonpath">;
 
 /**
  * Base interface for aggregated field definitions.
@@ -207,6 +208,7 @@ export function aggregatedRate(meta: ChartMeta): AggregatedRateField {
  *   errorCount: aggregatedCounter({
  *     "x-chart-type": "counter",
  *     "x-chart-label": "Errors",
+    "x-anomaly-direction": "lower-is-better",
  *   }),
  * };
  * ```

package/src/core-services.ts

@@ -3,6 +3,10 @@ import type { RpcService } from "./rpc";
 import type { HealthCheckRegistry } from "./health-check";
 import type { CollectorRegistry } from "./collector-registry";
 import type { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
+import type {
+  CachePluginRegistry,
+  CacheManager,
+} from "@checkstack/cache-api";
 import type { ConfigService } from "./config-service";
 import type { SignalService } from "@checkstack/signal-common";
 import { SafeDatabase } from "./plugin-system";
@@ -14,6 +18,7 @@ import {
   RpcClient,
 } from "./types";
 import type { EventBus } from "./event-bus-types";
+import type { WebSocketRouteRegistry } from "./ws-registry";
 
 export * from "./types";
 
@@ -43,4 +48,9 @@ export const coreServices = {
   config: createServiceRef<ConfigService>("core.config"),
   eventBus: createServiceRef<EventBus>("core.eventBus"),
   signalService: createServiceRef<SignalService>("core.signalService"),
+  wsRegistry: createServiceRef<WebSocketRouteRegistry>("core.wsRegistry"),
+  cachePluginRegistry: createServiceRef<CachePluginRegistry>(
+    "core.cachePluginRegistry",
+  ),
+  cacheManager: createServiceRef<CacheManager>("core.cacheManager"),
 };

package/src/index.ts

@@ -27,3 +27,4 @@ export * from "./collector-strategy";
 export * from "./collector-registry";
 export * from "./incremental-aggregation";
 export * from "./aggregated-result";
+export * from "./ws-registry";

package/src/rpc.ts

@@ -3,6 +3,10 @@ import { AnyContractRouter } from "@orpc/contract";
 import { HealthCheckRegistry } from "./health-check";
 import { CollectorRegistry } from "./collector-registry";
 import { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
+import {
+  CachePluginRegistry,
+  CacheManager,
+} from "@checkstack/cache-api";
 import {
   ProcedureMetadata,
   qualifyAccessRuleId,
@@ -45,6 +49,8 @@ export interface RpcContext {
   collectorRegistry: CollectorRegistry;
   queuePluginRegistry: QueuePluginRegistry;
   queueManager: QueueManager;
+  cachePluginRegistry: CachePluginRegistry;
+  cacheManager: CacheManager;
   /** Emit a hook event for cross-plugin communication */
   emitHook: EmitHookFn;
 }

package/src/test-utils.ts

@@ -4,6 +4,10 @@ import { SafeDatabase } from "./plugin-system";
 import { HealthCheckRegistry } from "./health-check";
 import { CollectorRegistry } from "./collector-registry";
 import { QueuePluginRegistry, QueueManager } from "@checkstack/queue-api";
+import {
+  CachePluginRegistry,
+  CacheManager,
+} from "@checkstack/cache-api";
 
 /**
  * Creates a mocked oRPC context for testing.
@@ -69,6 +73,18 @@ export function createMockRpcContext(
       startPolling: mock(),
       shutdown: mock(),
     } as unknown as QueueManager,
+    cachePluginRegistry: {
+      register: mock(),
+      getPlugin: mock(),
+      getPlugins: mock().mockReturnValue([]),
+    } as unknown as CachePluginRegistry,
+    cacheManager: {
+      getProvider: mock(),
+      getActivePlugin: mock().mockReturnValue("memory"),
+      getActiveConfig: mock(),
+      setActiveBackend: mock(),
+      shutdown: mock(),
+    } as unknown as CacheManager,
     // Default: authenticated user with wildcard access for testing
     user: { type: "user" as const, id: "test-user", accessRules: ["*"] },
     emitHook: mock() as unknown as EmitHookFn,

package/src/ws-registry.ts

@@ -0,0 +1,70 @@
+/**
+ * A generic interface for a WebSocket connection managed by the core server.
+ * Plugins interact with WebSocket clients through this adapter, insulating
+ * them from the underlying Bun WebSocket API.
+ */
+export interface WsConnection {
+  /** Send a string message to the client */
+  send(data: string): void;
+  /** Close the connection */
+  close(): void;
+}
+
+/**
+ * Per-connection handlers returned by a route handler's `onConnection` callback.
+ * These closures capture the connection's state (e.g., auth state, session data).
+ */
+export interface WsConnectionHandlers {
+  onMessage: (message: string) => void | Promise<void>;
+  onClose: () => void;
+}
+
+/**
+ * A WebSocket route handler registered by a plugin.
+ * The core server calls `onConnection` when a new WebSocket is opened on
+ * the handler's registered path, and the handler returns per-connection
+ * event callbacks.
+ */
+export interface WebSocketRouteHandler {
+  /**
+   * Called when a new WebSocket connection opens on this route.
+   * Return per-connection message/close handlers.
+   */
+  onConnection(ws: WsConnection): WsConnectionHandlers;
+}
+
+/**
+ * Scoped registry for plugin WebSocket route handlers.
+ * Each plugin receives a scoped instance (via factory) that auto-prefixes
+ * the pluginId — just like the RPC service.
+ *
+ * Plugins register handlers with a local path segment, and the core server
+ * makes them available under `/api/ws/{pluginId}{path}`.
+ *
+ * @example
+ * ```ts
+ * // In satellite-backend init (pluginId "satellite" is auto-prefixed):
+ * wsRegistry.register("/", handler);
+ * // → Available at /api/ws/satellite
+ *
+ * wsRegistry.register("/connect", handler);
+ * // → Available at /api/ws/satellite/connect
+ * ```
+ */
+export interface WebSocketRouteRegistry {
+  /**
+   * Register a WebSocket route handler at the given path.
+   * The pluginId prefix is applied automatically by the scoped factory.
+   */
+  register(path: string, handler: WebSocketRouteHandler): void;
+}
+
+/**
+ * Core-level store for all registered WS routes.
+ * The backend server uses this to look up handlers during WebSocket upgrade.
+ * Not exposed to plugins — they interact via the scoped `WebSocketRouteRegistry`.
+ */
+export interface WebSocketRouteStore {
+  /** Look up a handler by full path (e.g., "satellite" or "satellite/connect"). */
+  getHandler(fullPath: string): WebSocketRouteHandler | undefined;
+}