@cronwatch/sdk 0.11.1 → 0.12.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
-import { C as CronwatchOptions, a as Cronwatch } from './client-CRMfhylq.cjs';
-export { b as CronWatch, c as CronWatchOptions, F as FetchHandler, H as HandlerFn, d as HandlerOptions, J as JobContext, e as JobFn, f as JobHandle, R as RecordRunOptions, g as Routes, h as RoutesOptions, i as RunHandle, j as RunOutcome, S as Source, k as SourceHost, l as StartOptions, m as consoleChannel, n as createRoutes, o as custom } from './client-CRMfhylq.cjs';
-import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-DLnlUie8.cjs';
-export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, h as JobDefinition, i as JobHealth, J as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as SendingAlert, n as StoredJob, T as TriageContext, o as TriageFn } from './types-DLnlUie8.cjs';
+import { C as CronwatchOptions, a as Cronwatch } from './client-BkPMRkDq.cjs';
+export { b as CronWatch, c as CronWatchOptions, F as FetchHandler, H as HandlerFn, d as HandlerOptions, J as JobContext, e as JobFn, f as JobHandle, R as RecordRunOptions, g as Routes, h as RoutesOptions, i as RunHandle, j as RunOutcome, S as Source, k as SourceHost, l as StartOptions, m as consoleChannel, n as createRoutes, o as custom } from './client-BkPMRkDq.cjs';
+import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-Bm972Uqj.cjs';
+export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, h as JobDefinition, i as JobHealth, J as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as SendingAlert, n as StoredJob, T as TriageContext, o as TriageFn } from './types-Bm972Uqj.cjs';
 
 /**
  * Keeps everything in process memory. The default when no store is given,
@@ -11,7 +11,7 @@ export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach
 declare function memory(): Store;
 
 /** This release of @cronwatch/sdk. scripts/release.mjs keeps it in step with package.json. */
-declare const VERSION = "0.11.1";
+declare const VERSION = "0.12.0";
 
 /**
  * "15m" -> 900000. Accepts a plain number of milliseconds, and compound

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { C as CronwatchOptions, a as Cronwatch } from './client-D2Xk2600.js';
-export { b as CronWatch, c as CronWatchOptions, F as FetchHandler, H as HandlerFn, d as HandlerOptions, J as JobContext, e as JobFn, f as JobHandle, R as RecordRunOptions, g as Routes, h as RoutesOptions, i as RunHandle, j as RunOutcome, S as Source, k as SourceHost, l as StartOptions, m as consoleChannel, n as createRoutes, o as custom } from './client-D2Xk2600.js';
-import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-DLnlUie8.js';
-export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, h as JobDefinition, i as JobHealth, J as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as SendingAlert, n as StoredJob, T as TriageContext, o as TriageFn } from './types-DLnlUie8.js';
+import { C as CronwatchOptions, a as Cronwatch } from './client-DySsV5T0.js';
+export { b as CronWatch, c as CronWatchOptions, F as FetchHandler, H as HandlerFn, d as HandlerOptions, J as JobContext, e as JobFn, f as JobHandle, R as RecordRunOptions, g as Routes, h as RoutesOptions, i as RunHandle, j as RunOutcome, S as Source, k as SourceHost, l as StartOptions, m as consoleChannel, n as createRoutes, o as custom } from './client-DySsV5T0.js';
+import { S as Store, D as Duration, b as AlertDraft, c as StoredJobDefinition, A as Alert } from './types-Bm972Uqj.js';
+export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach, C as ChannelContext, f as CheckResult, g as Condition, E as ExpectRule, h as JobDefinition, i as JobHealth, J as JobOptions, j as JobState, k as JobSummary, R as Run, l as RunStatus, m as SendingAlert, n as StoredJob, T as TriageContext, o as TriageFn } from './types-Bm972Uqj.js';
 
 /**
  * Keeps everything in process memory. The default when no store is given,
@@ -11,7 +11,7 @@ export { a as AlertChannel, d as AlertDetails, e as AlertType, B as BudgetBreach
 declare function memory(): Store;
 
 /** This release of @cronwatch/sdk. scripts/release.mjs keeps it in step with package.json. */
-declare const VERSION = "0.11.1";
+declare const VERSION = "0.12.0";
 
 /**
  * "15m" -> 900000. Accepts a plain number of milliseconds, and compound

package/dist/index.js

@@ -326,7 +326,7 @@ function isObject(value) {
 }
 function normalizeState(state, job) {
   if (!isObject(state)) return emptyState(job);
-  const { sending, ...rest } = state;
+  const { sending, underFloor, ...rest } = state;
   const open = isObject(state.open) ? Object.fromEntries(Object.entries(state.open).filter(([, at]) => typeof at === "number")) : {};
   const number = (value) => typeof value === "number" ? value : null;
   const list = (value) => Array.isArray(value) ? value : [];
@@ -339,7 +339,8 @@ function normalizeState(state, job) {
     lastAlertAt: number(state.lastAlertAt),
     pendingRecovery: list(state.pendingRecovery).filter((c) => typeof c === "string"),
     undelivered: list(state.undelivered).filter((alert) => isObject(alert)),
-    ...Array.isArray(sending) && sending.length > 0 ? { sending: [...sending] } : {}
+    ...Array.isArray(sending) && sending.length > 0 ? { sending: [...sending] } : {},
+    ...Array.isArray(underFloor) && underFloor.some((m) => typeof m === "string") ? { underFloor: underFloor.filter((m) => typeof m === "string") } : {}
   };
 }
 var MAX_UNDELIVERED = 20;
@@ -439,6 +440,26 @@ function budgetBreaches(def, run, history) {
   }
   return breaches;
 }
+function floorBreaches(def, run, history, previous = []) {
+  const breaches = [];
+  for (const [metric, value] of Object.entries(run.metrics)) {
+    const floor = def.floor?.[metric];
+    if (floor !== void 0) {
+      if (value < floor) breaches.push({ metric, value, limit: floor, basis: "floor" });
+      continue;
+    }
+    if (value > 0) continue;
+    if (previous.includes(metric)) {
+      breaches.push({ metric, value, limit: 0, basis: "0 or less on the run before too" });
+      continue;
+    }
+    const past = history.filter((r) => r.status === "ok" && typeof r.metrics[metric] === "number").slice(0, BASELINE_WINDOW).map((r) => r.metrics[metric]);
+    if (past.length < BASELINE_MIN_RUNS || !past.every((v) => v > 0)) continue;
+    const lowest = Math.min(...past);
+    breaches.push({ metric, value, limit: lowest, basis: `the last ${past.length} runs all reported more than 0, the lowest ${formatNumber(lowest)}` });
+  }
+  return breaches;
+}
 function hasFullBaseline(history) {
   return history.filter((r) => r.status === "ok").length >= BASELINE_WINDOW;
 }
@@ -476,6 +497,16 @@ function onRunFinish(def, run, state, history, now) {
     } else {
       closeCondition(next, "over_budget");
     }
+    const short = floorBreaches(def, run, history, next.underFloor);
+    if (short.length > 0) {
+      next.underFloor = short.map((b) => b.metric);
+      if (openCondition(next, "under_floor", now)) {
+        alerts.push({ type: "under_floor", run, details: { breaches: short } });
+      }
+    } else {
+      delete next.underFloor;
+      closeCondition(next, "under_floor");
+    }
     const pending = next.pendingRecovery ?? [];
     if (pending.length > 0 && openConditions(next).length === 0) {
       alerts.push({ type: "recovered", run, details: { after: [...pending] } });
@@ -660,6 +691,14 @@ ${out}`);
       if (run) lines.push(`Started ${when(run.startedAt, now)}.`);
       break;
     }
+    case "under_floor": {
+      title = `${name} fell short`;
+      for (const b of draft.details.breaches) {
+        lines.push(b.basis === "floor" ? `${b.metric}: ${formatNumber(b.value)}, below the floor of ${formatNumber(b.limit)}.` : `${b.metric}: ${formatNumber(b.value)} (${b.basis}).`);
+      }
+      if (run) lines.push(`Started ${when(run.startedAt, now)}.`);
+      break;
+    }
     case "recovered": {
       if (draft.details.reason === "unscheduled") {
         title = `${name} is no longer scheduled`;
@@ -1078,7 +1117,7 @@ function toneOf(run, job, now) {
   if (run.status === "failed") return "bad";
   if (run.status === "timeout") return "timeout";
   const latest = job.lastRun?.id === run.id;
-  return latest && (job.open.includes("over_budget") || job.open.includes("slow")) ? "warn" : "ok";
+  return latest && (job.open.includes("over_budget") || job.open.includes("under_floor") || job.open.includes("slow")) ? "warn" : "ok";
 }
 function timeoutText(job) {
   return safely(() => formatDuration(timeoutMs(job.definition)), "configured");
@@ -1088,13 +1127,17 @@ function describeRun(run, tone, job, now) {
   if (tone === "running") return `running since ${at}, ${formatDuration(now - run.startedAt)} so far`;
   if (tone === "stuck") return `running since ${at}, past its ${timeoutText(job)} timeout`;
   const took = run.durationMs !== null ? `, took ${formatDuration(run.durationMs)}` : "";
-  const extra = tone === "warn" ? job.open.includes("over_budget") ? ", over budget" : ", slow" : "";
+  const extra = tone === "warn" ? job.open.includes("over_budget") ? ", over budget" : job.open.includes("under_floor") ? ", under floor" : ", slow" : "";
   return `${run.status} at ${at}${took}${extra}`;
 }
 function overCeilings(job) {
   const metrics = job.lastRun?.metrics ?? {};
   return Object.entries(job.definition.budget ?? {}).filter(([k, limit]) => (metrics[k] ?? -Infinity) > limit).map(([k]) => k);
 }
+function underFloors(job) {
+  const floors = job.definition.floor ?? {};
+  return Object.entries(job.lastRun?.metrics ?? {}).filter(([k, v]) => floors[k] !== void 0 ? v < floors[k] : v <= 0).map(([k]) => k);
+}
 function laneNote(job, missed, now) {
   const last = job.lastRun;
   if (job.silencedUntil !== null && job.silencedUntil > now) return `silenced until ${when2(job.silencedUntil, now)}`;
@@ -1110,6 +1153,10 @@ function laneNote(job, missed, now) {
     const over = overCeilings(job);
     return `went over budget${over.length ? ` on ${over.join(" and ")}` : ""} at ${when2(last.startedAt, now)}`;
   }
+  if (job.open.includes("under_floor") && last) {
+    const under = underFloors(job);
+    return `fell short${under.length ? ` on ${under.join(" and ")}` : ""} at ${when2(last.startedAt, now)}`;
+  }
   if (job.open.includes("slow") && last?.durationMs != null) return `slow: took ${formatDuration(last.durationMs)}`;
   if (job.open.includes("failed")) return "failing";
   if (!last && job.nextExpectedAt !== null) return `no runs yet, first due ${when2(job.nextExpectedAt, now)}`;
@@ -1226,7 +1273,7 @@ function legend() {
     [box("run ok"), "ran"],
     [box("run bad"), "failed"],
     [box("run timeout"), "timed out"],
-    [box("run warn"), "over budget or slow"],
+    [box("run warn"), "over budget, under floor or slow"],
     [box("run running"), "running"],
     [box("missed"), "missed"]
   ];
@@ -1644,6 +1691,7 @@ function jobPage(job, runs, now, base, complete = true) {
   <dt>Timeout</dt><dd>${h(d.timeout ?? "1h")}</dd>
   ${d.maxDuration ? `<dt>Max duration</dt><dd>${h(d.maxDuration)}</dd>` : ""}
   ${d.budget ? `<dt>Budget</dt><dd>${h(Object.entries(d.budget).map(([k, v]) => `${k} \u2264 ${v}`).join(", "))}</dd>` : ""}
+  ${d.floor ? `<dt>Floor</dt><dd>${h(Object.entries(d.floor).map(([k, v]) => `${k} \u2265 ${v}`).join(", "))}</dd>` : ""}
   ${d.expect ? `<dt>Expect</dt><dd>${h(d.expect)}</dd>` : ""}
   ${d.failuresBeforeAlert && d.failuresBeforeAlert > 1 ? `<dt>Alert after</dt><dd>${h(d.failuresBeforeAlert)} consecutive failures</dd>` : ""}
   ${d.tags?.length ? `<dt>Tags</dt><dd>${d.tags.map((t) => h(t)).join(", ")}</dd>` : ""}
@@ -1661,7 +1709,7 @@ function messagePage(title, message, base, signIn = false) {
 }
 
 // src/version.ts
-var VERSION = "0.11.1";
+var VERSION = "0.12.0";
 var API_VERSION = 1;
 
 // src/routes/index.ts
@@ -2155,6 +2203,18 @@ function validateDefinition(def) {
       }
     }
   }
+  if (def.floor !== void 0) {
+    if (typeof def.floor !== "object" || def.floor === null) throw new Error(`job "${name}": floor must be an object of { metric: floor }`);
+    for (const [metric, floor] of Object.entries(def.floor)) {
+      if (typeof floor !== "number" || !Number.isFinite(floor)) {
+        throw new Error(`job "${name}": floor.${metric} must be a finite number (got ${String(floor)})`);
+      }
+      const ceiling = def.budget?.[metric];
+      if (ceiling !== void 0 && floor > ceiling) {
+        throw new Error(`job "${name}": floor.${metric} (${floor}) is above budget.${metric} (${ceiling}), so every run would alert`);
+      }
+    }
+  }
   if (def.expect !== void 0 && typeof def.expect !== "string" && !(def.expect instanceof RegExp) && typeof def.expect !== "function") {
     throw new Error(`job "${name}": expect must be a string, a RegExp or a function`);
   }