monitor.heartbeat

export function heartbeatStatus(lastPingAt: number | null, now: number, intervalSeconds: number, graceSeconds: number): HeartbeatStatus

export type HeartbeatState = "new" | "up" | "late" | "down";

/** Where a heartbeat stands and when it changes next. */
export interface HeartbeatStatus {
  readonly state: HeartbeatState;
  /** when the next ping is due: lastPingAt + intervalSeconds; null when new */
  readonly dueAt: number | null;
  /** the last second it counts as late: dueAt + graceSeconds; null when new */
  readonly downAt: number | null;
  /** now - dueAt when late or down, else 0 */
  readonly overdueSeconds: number;
}

import { heartbeatStatus } from "#fune/monitor.heartbeat@^1";

import { type HeartbeatStatus } from "./monitor_heartbeat_types.ts";

function whole(name: string, v: number): void {
  if (!Number.isSafeInteger(v)) throw new RangeError(`${name} must be whole seconds, received ${v}`);
}

/**
 * New, up, late or down, as healthchecks.io names them. Up through the due
 * second itself, late through the last second of the grace time, down after.
 * A ping stamped in the future (clock skew between the job and the monitor)
 * is simply up: its due time is later still.
 */
export function heartbeatStatus(lastPingAt: number | null, now: number, intervalSeconds: number, graceSeconds: number): HeartbeatStatus {
  if (lastPingAt !== null) whole("lastPingAt", lastPingAt);
  whole("now", now);
  whole("intervalSeconds", intervalSeconds);
  whole("graceSeconds", graceSeconds);
  if (intervalSeconds < 1) throw new RangeError(`intervalSeconds must be at least 1, received ${intervalSeconds}`);
  if (graceSeconds < 0) throw new RangeError(`graceSeconds must not be negative, received ${graceSeconds}`);
  if (lastPingAt === null) return { state: "new", dueAt: null, downAt: null, overdueSeconds: 0 };
  const dueAt = lastPingAt + intervalSeconds;
  const downAt = dueAt + graceSeconds;
  if (now <= dueAt) return { state: "up", dueAt, downAt, overdueSeconds: 0 };
  return { state: now <= downAt ? "late" : "down", dueAt, downAt, overdueSeconds: now - dueAt };
}

Install

fune build

With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add monitor.heartbeat

The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./monitor.heartbeat-1.0.0-typescript.fune, or fetch it from a terminal with fune pull monitor.heartbeat@1.0.0:typescript.

The whole function, every language, is one file too: monitor.heartbeat-1.0.0.fune, 12,774 bytes, sha256 670066e850a8ae45f319f6644290afddae8eaec2c718edba53e6b8a7a51a80f3. It installs into a project of any language.

// fune: before monitor.heartbeat

// fune: after monitor.heartbeat

// fune: step monitor.heartbeat after <n|label>

More from the author

where `dueAt = lastPingAt + intervalSeconds` and `downAt = dueAt + graceSeconds`. The due second itself is still up, and the last second of the grace time is still late; the state changes the second after. With no grace time a check goes straight from up to down.

`overdueSeconds` is `now - dueAt` when late or down (how long past due, for "late by 2m" in an alert), and 0 otherwise. `dueAt` and `downAt` are returned so the caller can schedule its next evaluation instead of polling.

## Edge cases

- A ping stamped after `now` (the job's clock is ahead of the monitor's) is `up`, overdue 0: its due time is later still. It is not an error, because clock skew is normal and refusing it would hide a healthy job. - `paused` is not a state here: pausing is the caller's decision, not something the ping times say. - Only simple period schedules are covered; a cron-expression schedule gives `dueAt` from the expression instead.

## Errors

- `intervalSeconds must be at least 1, received X` - `graceSeconds must not be negative, received X` - `NAME must be whole seconds, received X` for a fractional time

## Sources

- healthchecks.io documentation, "Check states" and "Period and Grace Time": https://healthchecks.io/docs/ and https://healthchecks.io/docs/configuring_checks/

Files