monitor.maintenance-window

export function activeMaintenance(windows: readonly MaintenanceWindow[], at: number): MaintenanceWindow | null

/** A scheduled period when a target is expected to be down. */
export interface MaintenanceWindow {
  readonly name: string;
  /** Unix seconds, the first second included */
  readonly start: number;
  /** Unix seconds, the first second excluded */
  readonly end: number;
}

import { activeMaintenance } from "#fune/monitor.maintenance-window@^1";

import { type MaintenanceWindow } from "./monitor_maintenance_window_types.ts";

/**
 * The window with start <= at < end. Half-open, so a window ending at 02:00
 * and the next starting at 02:00 never both apply. When several overlap, the
 * one that started first wins (ties: the first in the list), so the answer
 * does not depend on how the caller happened to sort them. Every window is
 * checked, not only the active ones: a backwards window is a config error
 * that would otherwise silently never apply.
 */
export function activeMaintenance(windows: readonly MaintenanceWindow[], at: number): MaintenanceWindow | null {
  if (!Number.isSafeInteger(at)) throw new RangeError(`at must be a whole second, received ${at}`);
  let best: MaintenanceWindow | null = null;
  for (const w of windows) {
    if (w.end <= w.start) {
      throw new RangeError(`maintenance window "${w.name}" must end after it starts: start ${w.start}, end ${w.end}`);
    }
    if (w.start <= at && at < w.end && (best === null || w.start < best.start)) best = w;
  }
  return best === null ? null : { name: best.name, start: best.start, end: best.end };
}

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.maintenance-window

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

The whole function, every language, is one file too: monitor.maintenance-window-1.0.0.fune, 10,867 bytes, sha256 2be593f1b02aa7c8f811132adb9151be5f7527287fc2fb9fb90100f77531e111. It installs into a project of any language.

// fune: before monitor.maintenance-window

// fune: after monitor.maintenance-window

// fune: step monitor.maintenance-window after <n|label>

More from the author

- **Half-open**: a window covers `start <= at < end`. A window ending at 02:00 and the next starting at 02:00 never both apply, and the end second itself is outside. - **Overlaps**: when several windows are active, the one that **started first** is returned (on a tie, the first in the list). The answer then does not depend on how the caller sorted the list, and the name shown is the maintenance that caused the outage in the first place. - **Every window is checked**, not only the active one: a window that does not end after it starts is a typo that would silently never apply, so it is an error wherever it sits in the list. - Returns `null` when nothing is active; returns a copy, never the caller's object.

## Errors

- `maintenance window "NAME" must end after it starts: start S, end E` - `at must be a whole second, received X`

Files