Check a value, not just "is it up": JSON value checks on web endpoints

A web check can read a value out of a JSON answer (power.now, state,
data.result[0].value[1]) and judge it: below, above, equal to, contains, is there.
The value read is shown on the Endpoints page, charted under History, exported as
homelab_endpoint_value and in the read API. A check can also send one header (a
token), stored encrypted, never returned, and not forwarded to another host on a
redirect.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
bobbanandClaude Sonnet 5.5 committed 2026-10-21 21:13:44 +02:00
1 parent e114567d64
commit 3cb3e4988f
21 files changed
+6804 -47

No files matched your search

+140
View File
@@ -0,0 +1,140 @@
/**
* Judging a value in an answer: "the power is under 5 000 W", "the status is playing", "the Prometheus query returned something". The answer is JSON; a path says
* where the value is in it, and one comparison says whether it is fine. Everything here is pure — the asking is in endpointChecks.ts.
*
* A path is the dots and brackets people already write: `power.now`, `data.result[0].value[1]`, `items[2].name`, and `["a.b"]` for a name with a dot in it.
* A leading `$.` is allowed and means nothing.
*/
export const VALUE_OPS = ["<", "<=", ">", ">=", "=", "!=", "contains", "exists"] as const;
export type ValueOp = (typeof VALUE_OPS)[number];
const NUMERIC_OPS: readonly ValueOp[] = ["<", "<=", ">", ">="];
export const isValueOp = (op: string): op is ValueOp => (VALUE_OPS as readonly string[]).includes(op);
type Step = string | number;
/** A path into its steps, or null when it can't be read. */
export function parsePath(path: string): Step[] | null {
let p = path.trim();
if (p.startsWith("$")) p = p.slice(1);
if (p.startsWith(".")) p = p.slice(1);
const steps: Step[] = [];
let i = 0;
while (i < p.length) {
const c = p[i];
if (c === ".") {
i++;
if (i >= p.length || p[i] === "." || p[i] === "[") return null;
} else if (c === "[") {
const close = p.indexOf("]", i);
if (close < 0) return null;
const inner = p.slice(i + 1, close).trim();
i = close + 1;
if (/^\d+$/.test(inner)) steps.push(Number(inner));
else if (/^(".*"|'.*')$/.test(inner) && inner.length >= 2) steps.push(inner.slice(1, -1));
else return null;
} else {
const m = /^[^.[\]]+/.exec(p.slice(i));
if (!m) return null;
steps.push(m[0]);
i += m[0].length;
}
}
return steps.length > 0 ? steps : null;
}
export const isValuePath = (path: string) => parsePath(path) !== null;
export type Read = { found: true; value: unknown } | { found: false; at: string };
/** What is at a path in a parsed answer. `at` says how far it got when it isn't there. */
export function readPath(json: unknown, path: string): Read {
const steps = parsePath(path);
if (!steps) return { found: false, at: path };
let here: unknown = json;
const walked: string[] = [];
for (const step of steps) {
walked.push(typeof step === "number" ? `[${step}]` : walked.length === 0 ? step : `.${step}`);
if (typeof step === "number") {
if (!Array.isArray(here) || step >= here.length) return { found: false, at: walked.join("") };
here = here[step];
} else {
if (here === null || typeof here !== "object" || Array.isArray(here) || !Object.prototype.hasOwnProperty.call(here, step)) return { found: false, at: walked.join("") };
here = (here as Record<string, unknown>)[step];
}
}
return { found: true, value: here };
}
/** A value as a number when it is one, or text that is one ("12.5": Prometheus gives its numbers as text); otherwise null. */
export function asNumber(value: unknown): number | null {
if (typeof value === "number") return Number.isFinite(value) ? value : null;
if (typeof value === "string" && value.trim() !== "" && Number.isFinite(Number(value))) return Number(value);
return null;
}
/** A value as text, short enough to keep and show. */
export function showValue(value: unknown): string {
const text = typeof value === "string" ? value : typeof value === "number" || typeof value === "boolean" || value === null ? String(value) : JSON.stringify(value);
return text.length > 120 ? `${text.slice(0, 117)}…` : text;
}
export interface Verdict {
ok: boolean;
/** What was read, as text, to show and to remember. */
shown: string;
/** The number, when it is one. */
number: number | null;
message: string;
}
const WORDS: Record<ValueOp, string> = { "<": "below", "<=": "at most", ">": "above", ">=": "at least", "=": "equal to", "!=": "anything but", contains: "containing", exists: "there" };
/** How a limit reads: "below 5000 W". */
export function describeLimit(op: ValueOp, expected: string | null, unit: string | null): string {
if (op === "exists") return "there";
const n = asNumber(expected);
const quoted = NUMERIC_OPS.includes(op) || n !== null ? String(expected) : `“${expected}”`;
return `${WORDS[op]} ${quoted}${unit && (NUMERIC_OPS.includes(op) || n !== null) ? ` ${unit}` : ""}`;
}
/** Whether what was read meets the limit, and what to say about it. `read` is what readPath found. */
export function judgeValue(read: Read, path: string, op: ValueOp, expected: string | null, unit: string | null): Verdict {
if (!read.found) {
// "exists" is satisfied by the value being there, so its absence is the thing to say; the others cannot be judged without it.
return { ok: false, shown: "", number: null, message: `there is no “${path}” in the answer (it stops at ${read.at})` };
}
const number = asNumber(read.value);
const shown = showValue(read.value);
const withUnit = number !== null && unit ? `${shown} ${unit}` : shown;
const limit = describeLimit(op, expected, unit);
if (op === "exists") return { ok: true, shown, number, message: `${path} is ${withUnit}` };
let ok: boolean;
if (NUMERIC_OPS.includes(op)) {
const want = asNumber(expected);
if (number === null) return { ok: false, shown, number, message: `${path} is “${shown}”, which isn't a number, so it can't be compared with ${expected}` };
if (want === null) return { ok: false, shown, number, message: `the limit “${expected}” isn't a number` };
ok = op === "<" ? number < want : op === "<=" ? number <= want : op === ">" ? number > want : number >= want;
} else if (op === "contains") {
ok = shown.includes(expected ?? "");
} else {
// Numbers are equal as numbers ("5" and 5.0), anything else as the same text.
const want = asNumber(expected);
const same = number !== null && want !== null ? number === want : shown === (expected ?? "");
ok = op === "=" ? same : !same;
}
return { ok, shown, number, message: ok ? `${path} is ${withUnit} (should be ${limit})` : `${path} is ${withUnit}, but should be ${limit}` };
}
/** Whether a saved check's value settings make sense together: the reason why not, or null. */
export function valueProblem(path: string | null, op: string | null, expected: string | null): string | null {
if (!path && !op && !expected) return null;
if (!path) return "Say where in the answer the value is, e.g. data.result[0].value[1].";
if (!isValuePath(path)) return "That isn't a path I can read. Use names separated by dots, and [0] for a place in a list, like data.result[0].value[1].";
if (!op || !isValueOp(op)) return "Say how the value should compare.";
if (op !== "exists" && (expected === null || expected.trim() === "")) return "Say what to compare it with.";
if (NUMERIC_OPS.includes(op) && asNumber(expected) === null) return "A limit to be above or below has to be a number.";
return null;
}