@checkstack/maintenance-backend 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @checkstack/maintenance-backend
 
+## 0.4.0
+
+### Minor Changes
+
+- 65aa47e: Add automatic maintenance status transitions
+
+  Maintenances now automatically transition from `scheduled` to `in_progress` when their `startAt` time is reached, and from `in_progress` to `completed` when their `endAt` time is reached. A recurring queue job runs every minute to check and transition statuses. Integration hooks and real-time signals are emitted upon each transition.
+
+### Patch Changes
+
+- Updated dependencies [8a87cd4]
+- Updated dependencies [8a87cd4]
+- Updated dependencies [8a87cd4]
+- Updated dependencies [8a87cd4]
+  - @checkstack/backend-api@0.4.1
+  - @checkstack/catalog-common@1.2.3
+  - @checkstack/common@0.5.0
+  - @checkstack/maintenance-common@0.4.1
+  - @checkstack/command-backend@0.1.5
+  - @checkstack/integration-backend@0.1.5
+  - @checkstack/integration-common@0.2.2
+  - @checkstack/notification-common@0.2.2
+  - @checkstack/signal-common@0.1.3
+
 ## 0.3.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/maintenance-backend",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/index.ts

@@ -7,7 +7,9 @@ import {
   pluginMetadata,
   maintenanceContract,
   maintenanceRoutes,
+  MAINTENANCE_UPDATED,
 } from "@checkstack/maintenance-common";
+
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
 import { integrationEventExtensionPoint } from "@checkstack/integration-backend";
 import { MaintenanceService } from "./service";
@@ -42,6 +44,11 @@ const maintenanceUpdatedPayloadSchema = z.object({
   action: z.enum(["updated", "closed"]),
 });
 
+// Queue and job constants
+const STATUS_TRANSITION_QUEUE = "maintenance-status-transitions";
+const STATUS_TRANSITION_JOB_ID = "maintenance-status-transition-check";
+const WORKER_GROUP = "maintenance-status-worker";
+
 // =============================================================================
 // Plugin Definition
 // =============================================================================
@@ -53,7 +60,7 @@ export default createBackendPlugin({
 
     // Register hooks as integration events
     const integrationEvents = env.getExtensionPoint(
-      integrationEventExtensionPoint
+      integrationEventExtensionPoint,
     );
 
     integrationEvents.registerEvent(
@@ -64,7 +71,7 @@ export default createBackendPlugin({
         category: "Maintenance",
         payloadSchema: maintenanceCreatedPayloadSchema,
       },
-      pluginMetadata
+      pluginMetadata,
     );
 
     integrationEvents.registerEvent(
@@ -75,9 +82,12 @@ export default createBackendPlugin({
         category: "Maintenance",
         payloadSchema: maintenanceUpdatedPayloadSchema,
       },
-      pluginMetadata
+      pluginMetadata,
     );
 
+    // Store service reference for afterPluginsReady
+    let maintenanceService: MaintenanceService;
+
     env.registerInit({
       schema,
       deps: {
@@ -85,20 +95,21 @@ export default createBackendPlugin({
         rpc: coreServices.rpc,
         rpcClient: coreServices.rpcClient,
         signalService: coreServices.signalService,
+        queueManager: coreServices.queueManager,
       },
       init: async ({ logger, database, rpc, rpcClient, signalService }) => {
         logger.debug("🔧 Initializing Maintenance Backend...");
 
         const catalogClient = rpcClient.forPlugin(CatalogApi);
 
-        const service = new MaintenanceService(
-          database as NodePgDatabase<typeof schema>
+        maintenanceService = new MaintenanceService(
+          database as NodePgDatabase<typeof schema>,
         );
         const router = createRouter(
-          service,
+          maintenanceService,
           signalService,
           catalogClient,
-          logger
+          logger,
         );
         rpc.registerRouter(router, maintenanceContract);
 
@@ -130,6 +141,116 @@ export default createBackendPlugin({
 
         logger.debug("✅ Maintenance Backend initialized.");
       },
+      afterPluginsReady: async ({
+        queueManager,
+        emitHook,
+        logger,
+        signalService,
+      }) => {
+        // Schedule the recurring status transition check job
+        const queue = queueManager.getQueue<Record<string, never>>(
+          STATUS_TRANSITION_QUEUE,
+        );
+
+        // Subscribe to process status transition check jobs
+        await queue.consume(
+          async () => {
+            logger.debug("⏰ Checking maintenance status transitions...");
+
+            // Get maintenances that need to start
+            const toStart = await maintenanceService.getMaintenancesToStart();
+            for (const maintenance of toStart) {
+              const updated = await maintenanceService.transitionStatus(
+                maintenance.id,
+                "in_progress",
+                "Maintenance started automatically",
+              );
+
+              if (updated) {
+                logger.info(
+                  `Maintenance "${updated.title}" transitioned to in_progress`,
+                );
+
+                // Emit hook for integrations
+                await emitHook(maintenanceHooks.maintenanceUpdated, {
+                  maintenanceId: updated.id,
+                  systemIds: updated.systemIds,
+                  title: updated.title,
+                  description: updated.description,
+                  status: updated.status,
+                  startAt: updated.startAt.toISOString(),
+                  endAt: updated.endAt.toISOString(),
+                  action: "updated" as const,
+                });
+
+                // Send signal for real-time UI updates
+                await signalService.broadcast(MAINTENANCE_UPDATED, {
+                  maintenanceId: updated.id,
+                  systemIds: updated.systemIds,
+                  action: "updated",
+                });
+              }
+            }
+
+            // Get maintenances that need to complete
+            const toComplete =
+              await maintenanceService.getMaintenancesToComplete();
+            for (const maintenance of toComplete) {
+              const updated = await maintenanceService.transitionStatus(
+                maintenance.id,
+                "completed",
+                "Maintenance completed automatically",
+              );
+
+              if (updated) {
+                logger.info(
+                  `Maintenance "${updated.title}" transitioned to completed`,
+                );
+
+                // Emit hook for integrations
+                await emitHook(maintenanceHooks.maintenanceUpdated, {
+                  maintenanceId: updated.id,
+                  systemIds: updated.systemIds,
+                  title: updated.title,
+                  description: updated.description,
+                  status: updated.status,
+                  startAt: updated.startAt.toISOString(),
+                  endAt: updated.endAt.toISOString(),
+                  action: "closed" as const,
+                });
+
+                // Send signal for real-time UI updates
+                await signalService.broadcast(MAINTENANCE_UPDATED, {
+                  maintenanceId: updated.id,
+                  systemIds: updated.systemIds,
+                  action: "closed",
+                });
+              }
+            }
+
+            if (toStart.length > 0 || toComplete.length > 0) {
+              logger.debug(
+                `Status transitions: ${toStart.length} started, ${toComplete.length} completed`,
+              );
+            }
+          },
+          {
+            consumerGroup: WORKER_GROUP,
+            maxRetries: 0, // Status checks should not retry
+          },
+        );
+
+        // Schedule to run every minute (60 seconds)
+        await queue.scheduleRecurring(
+          {}, // Empty payload - the job just triggers a check
+          {
+            jobId: STATUS_TRANSITION_JOB_ID,
+            intervalSeconds: 60,
+          },
+        );
+
+        logger.debug("✅ Maintenance status transition job scheduled.");
+      },
     });
   },
 });

package/src/service.ts

@@ -362,4 +362,110 @@ export class MaintenanceService {
 
     return !!match;
   }
+
+  /**
+   * Get maintenances that should transition from 'scheduled' to 'in_progress'.
+   * These are maintenances where status = 'scheduled' AND startAt <= now.
+   */
+  async getMaintenancesToStart(): Promise<MaintenanceWithSystems[]> {
+    const now = new Date();
+
+    const rows = await this.db
+      .select()
+      .from(maintenances)
+      .where(
+        and(
+          eq(maintenances.status, "scheduled"),
+          // startAt is in the past or now
+          // Using SQL comparison - startAt <= now
+        ),
+      );
+
+    // Filter in JS since Drizzle SQL comparison can be tricky with dates
+    const startable = rows.filter((m) => m.startAt <= now);
+
+    // Fetch system IDs for each
+    const result: MaintenanceWithSystems[] = [];
+    for (const m of startable) {
+      const systems = await this.db
+        .select({ systemId: maintenanceSystems.systemId })
+        .from(maintenanceSystems)
+        .where(eq(maintenanceSystems.maintenanceId, m.id));
+
+      result.push({
+        ...m,
+        description: m.description ?? undefined,
+        systemIds: systems.map((s) => s.systemId),
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * Get maintenances that should transition from 'in_progress' to 'completed'.
+   * These are maintenances where status = 'in_progress' AND endAt <= now.
+   */
+  async getMaintenancesToComplete(): Promise<MaintenanceWithSystems[]> {
+    const now = new Date();
+
+    const rows = await this.db
+      .select()
+      .from(maintenances)
+      .where(eq(maintenances.status, "in_progress"));
+
+    // Filter in JS for those that have ended
+    const completable = rows.filter((m) => m.endAt <= now);
+
+    // Fetch system IDs for each
+    const result: MaintenanceWithSystems[] = [];
+    for (const m of completable) {
+      const systems = await this.db
+        .select({ systemId: maintenanceSystems.systemId })
+        .from(maintenanceSystems)
+        .where(eq(maintenanceSystems.maintenanceId, m.id));
+
+      result.push({
+        ...m,
+        description: m.description ?? undefined,
+        systemIds: systems.map((s) => s.systemId),
+      });
+    }
+
+    return result;
+  }
+
+  /**
+   * Transition a maintenance to a new status with an automatic update entry.
+   * Used by the scheduled job for automatic status transitions.
+   */
+  async transitionStatus(
+    id: string,
+    newStatus: MaintenanceStatus,
+    message: string,
+  ): Promise<MaintenanceWithSystems | undefined> {
+    const [existing] = await this.db
+      .select()
+      .from(maintenances)
+      .where(eq(maintenances.id, id));
+
+    if (!existing) return undefined;
+
+    // Update the maintenance status
+    await this.db
+      .update(maintenances)
+      .set({ status: newStatus, updatedAt: new Date() })
+      .where(eq(maintenances.id, id));
+
+    // Add update entry (no user - system-generated)
+    await this.db.insert(maintenanceUpdates).values({
+      id: generateId(),
+      maintenanceId: id,
+      message,
+      statusChange: newStatus,
+      createdBy: undefined, // System-generated, no user
+    });
+
+    return (await this.getMaintenance(id))!;
+  }
 }