@checkstack/slo-backend 0.2.0

package/src/router.ts

@@ -0,0 +1,192 @@
+import { implement, ORPCError } from "@orpc/server";
+import {
+  sloContract,
+  SLO_STATUS_CHANGED,
+} from "@checkstack/slo-common";
+import {
+  autoAuthMiddleware,
+  type RpcContext,
+} from "@checkstack/backend-api";
+import type { SignalService } from "@checkstack/signal-common";
+import type { SloService } from "./service";
+import type { SloEngine } from "./slo-engine";
+
+export function createRouter({
+  service,
+  engine,
+  signalService,
+}: {
+  service: SloService;
+  engine: SloEngine;
+  signalService: SignalService;
+}) {
+  const os = implement(sloContract)
+    .$context<RpcContext>()
+    .use(autoAuthMiddleware);
+
+  return os.router({
+    // =========================================================================
+    // OBJECTIVES
+    // =========================================================================
+
+    listObjectives: os.listObjectives.handler(async () => {
+      const objectives = await service.listObjectives();
+      const results = await Promise.all(
+        objectives.map(async (objective) => ({
+          objective,
+          status: await engine.computeStatus({ objective }),
+        })),
+      );
+      return { objectives: results };
+    }),
+
+    getObjective: os.getObjective.handler(async ({ input }) => {
+      const objective = await service.getObjective({ id: input.id });
+      if (!objective) {
+        // eslint-disable-next-line unicorn/no-null -- oRPC contract requires null for missing values
+        return null;
+      }
+      const status = await engine.computeStatus({ objective });
+      return { objective, status };
+    }),
+
+    getObjectivesForSystem: os.getObjectivesForSystem.handler(
+      async ({ input }) => {
+        const objectives = await service.getObjectivesForSystem({
+          systemId: input.systemId,
+        });
+        return Promise.all(
+          objectives.map(async (objective) => ({
+            objective,
+            status: await engine.computeStatus({ objective }),
+          })),
+        );
+      },
+    ),
+
+    getBulkObjectivesForSystems: os.getBulkObjectivesForSystems.handler(
+      async ({ input }) => {
+        const systems: Record<
+          string,
+          Array<{
+            objective: Awaited<ReturnType<typeof service.getObjective>> & {};
+            status: Awaited<ReturnType<typeof engine.computeStatus>>;
+          }>
+        > = {};
+
+        await Promise.all(
+          input.systemIds.map(async (systemId) => {
+            const objectives = await service.getObjectivesForSystem({
+              systemId,
+            });
+            systems[systemId] = await Promise.all(
+              objectives.map(async (objective) => ({
+                objective,
+                status: await engine.computeStatus({ objective }),
+              })),
+            );
+          }),
+        );
+
+        return { systems };
+      },
+    ),
+
+    createObjective: os.createObjective.handler(
+      async ({ input }) => {
+        const objective = await service.createObjective({ input });
+
+        // Reconcile initial state: if system is already down,
+        // open an initial downtime event immediately
+        await engine.reconcileObjective({ objective });
+
+        const status = await engine.computeStatus({ objective });
+        await signalService.broadcast(SLO_STATUS_CHANGED, {
+          systemId: objective.systemId,
+          objectiveId: objective.id,
+          budgetRemainingPercent: status.errorBudgetRemainingPercent,
+          isBreaching: status.isBreaching,
+        });
+
+        return objective;
+      },
+    ),
+
+    updateObjective: os.updateObjective.handler(async ({ input }) => {
+      const objective = await service.updateObjective({ input });
+      if (!objective) {
+        throw new ORPCError("NOT_FOUND", {
+          message: "SLO objective not found",
+        });
+      }
+
+      // Reconcile: if system is currently down but no event exists
+      await engine.reconcileObjective({ objective });
+
+      const status = await engine.computeStatus({ objective });
+      await signalService.broadcast(SLO_STATUS_CHANGED, {
+        systemId: objective.systemId,
+        objectiveId: objective.id,
+        budgetRemainingPercent: status.errorBudgetRemainingPercent,
+        isBreaching: status.isBreaching,
+      });
+
+      return objective;
+    }),
+
+    deleteObjective: os.deleteObjective.handler(async ({ input }) => {
+      const success = await service.deleteObjective({ id: input.id });
+      return { success };
+    }),
+
+    // =========================================================================
+    // DOWNTIME EVENTS & SNAPSHOTS
+    // =========================================================================
+
+    getDowntimeEvents: os.getDowntimeEvents.handler(async ({ input }) => {
+      const events = await service.getRecentDowntimeEvents({
+        objectiveId: input.objectiveId,
+        limit: input.limit ?? 50,
+      });
+      return { events };
+    }),
+
+    getDailySnapshots: os.getDailySnapshots.handler(async ({ input }) => {
+      const snapshots = await service.getDailySnapshots({
+        objectiveId: input.objectiveId,
+        startDate: input.startDate,
+        endDate: input.endDate,
+      });
+      return { snapshots };
+    }),
+
+    // =========================================================================
+    // STREAKS & ACHIEVEMENTS
+    // =========================================================================
+
+    getStreaks: os.getStreaks.handler(async () => {
+      const streaks = await service.getAllStreaks();
+      return { streaks };
+    }),
+
+    getAchievements: os.getAchievements.handler(async ({ input }) => {
+      const achievements = await service.getAchievements({
+        systemId: input.systemId,
+      });
+      return { achievements };
+    }),
+
+    getRecentMilestones: os.getRecentMilestones.handler(async ({ input }) => {
+      const achievements = await service.getRecentMilestones({
+        limit: input.limit ?? 20,
+      });
+      return {
+        milestones: achievements.map((a) => ({
+          systemId: a.systemId,
+          achievement: a.achievement,
+          unlockedAt: a.unlockedAt,
+        })),
+      };
+    }),
+  });
+}

package/src/schema.ts

@@ -0,0 +1,120 @@
+import {
+  pgTable,
+  text,
+  timestamp,
+  doublePrecision,
+  integer,
+  json,
+} from "drizzle-orm/pg-core";
+
+// =============================================================================
+// SLO OBJECTIVES
+// =============================================================================
+
+/**
+ * SLO objective definitions.
+ * Multiple SLOs can exist per system. When healthCheckConfigurationId is null,
+ * the SLO covers the system's aggregate availability across all health checks.
+ */
+export const sloObjectives = pgTable("slo_objectives", {
+  id: text("id").primaryKey(),
+  systemId: text("system_id").notNull(),
+  healthCheckConfigurationId: text("health_check_configuration_id"),
+  target: doublePrecision("target").notNull(),
+  windowDays: integer("window_days").notNull(),
+  dependencyExclusion: text("dependency_exclusion").notNull().default("strict"),
+  excludedDependencyIds: json("excluded_dependency_ids").$type<string[]>(),
+  burnRateWarningPercent: doublePrecision("burn_rate_warning_percent")
+    .notNull()
+    .default(50),
+  burnRateCriticalPercent: doublePrecision("burn_rate_critical_percent")
+    .notNull()
+    .default(80),
+  burnRateFastBurnMultiplier: doublePrecision("burn_rate_fast_burn_multiplier")
+    .notNull()
+    .default(5),
+  createdAt: timestamp("created_at").defaultNow().notNull(),
+  updatedAt: timestamp("updated_at").defaultNow().notNull(),
+});
+
+// =============================================================================
+// DOWNTIME EVENTS (event-sourced)
+// =============================================================================
+
+/**
+ * Event-sourced downtime records, written in real-time on SYSTEM_STATUS_CHANGED.
+ *
+ * Events are IMMUTABLE after creation. When attribution changes mid-outage
+ * (e.g., upstream goes down after downstream), the open event is closed and a
+ * new one is created with the correct attribution (event splitting).
+ *
+ * endTime = null indicates an ongoing outage.
+ */
+export const sloDowntimeEvents = pgTable("slo_downtime_events", {
+  id: text("id").primaryKey(),
+  objectiveId: text("objective_id")
+    .notNull()
+    .references(() => sloObjectives.id, { onDelete: "cascade" }),
+  systemId: text("system_id").notNull(),
+  startTime: timestamp("start_time").notNull(),
+  endTime: timestamp("end_time"),
+  durationSeconds: doublePrecision("duration_seconds"),
+  attributionType: text("attribution_type").notNull(),
+  upstreamSystemId: text("upstream_system_id"),
+  upstreamSystemName: text("upstream_system_name"),
+});
+
+// =============================================================================
+// DAILY SNAPSHOTS
+// =============================================================================
+
+/**
+ * Daily SLO snapshots for trend charts.
+ * Persisted by a daily cron job at UTC midnight.
+ */
+export const sloDailySnapshots = pgTable("slo_daily_snapshots", {
+  id: text("id").primaryKey(),
+  objectiveId: text("objective_id")
+    .notNull()
+    .references(() => sloObjectives.id, { onDelete: "cascade" }),
+  date: timestamp("date").notNull(),
+  availabilityPercent: doublePrecision("availability_percent").notNull(),
+  budgetConsumedMinutes: doublePrecision("budget_consumed_minutes").notNull(),
+  budgetRemainingPercent: doublePrecision("budget_remaining_percent").notNull(),
+  burnRate: doublePrecision("burn_rate"),
+  streakDays: integer("streak_days").notNull().default(0),
+});
+
+// =============================================================================
+// STREAKS
+// =============================================================================
+
+/**
+ * Streak tracking per SLO objective (1:1 relationship).
+ * Updated daily by the streak calculator cron job.
+ */
+export const sloStreaks = pgTable("slo_streaks", {
+  objectiveId: text("objective_id")
+    .primaryKey()
+    .references(() => sloObjectives.id, { onDelete: "cascade" }),
+  systemId: text("system_id").notNull(),
+  currentStreak: integer("current_streak").notNull().default(0),
+  bestStreak: integer("best_streak").notNull().default(0),
+  streakStart: timestamp("streak_start"),
+  bestStreakEnd: timestamp("best_streak_end"),
+});
+
+// =============================================================================
+// ACHIEVEMENTS
+// =============================================================================
+
+/**
+ * Achievement log — system-level only, no user attribution.
+ * Idempotent: the achievement evaluator checks for existing entries before inserting.
+ */
+export const sloAchievements = pgTable("slo_achievements", {
+  id: text("id").primaryKey(),
+  systemId: text("system_id").notNull(),
+  achievement: text("achievement").notNull(),
+  unlockedAt: timestamp("unlocked_at").defaultNow().notNull(),
+});