@intentius/chant-lexicon-prometheus 0.124.31 → 0.124.33

package/dist/alertmanager.js

@@ -0,0 +1,61 @@
+/**
+ * Alertmanager entities: `Route`, `Receiver`, `InhibitRule`, `TimeInterval`
+ * and `AlertmanagerSettings`, which together serialize to `alertmanager.yml`.
+ *
+ * A route names its receiver and its time intervals either by the declared
+ * entity, which keeps the reference checked by TypeScript, or by name string
+ * for one declared somewhere chant can't see. PROM201 and PROM204 catch a
+ * string that names nothing declared.
+ *
+ * The routing tree is built from `Route`s: the root is the one route no other
+ * route lists as a child. Child routes may be `Route` entities or plain
+ * objects.
+ */
+import { createResource } from "@intentius/chant/runtime";
+export const RECEIVER_TYPE = "Prometheus::Alertmanager::Receiver";
+export const ROUTE_TYPE = "Prometheus::Alertmanager::Route";
+export const INHIBIT_RULE_TYPE = "Prometheus::Alertmanager::InhibitRule";
+export const TIME_INTERVAL_TYPE = "Prometheus::Alertmanager::TimeInterval";
+export const SETTINGS_TYPE = "Prometheus::Alertmanager::Settings";
+function entityClass(entityType, className, extra) {
+    const Base = createResource(entityType, "prometheus", {});
+    const Cls = function (props) {
+        Base.call(this, (props ?? {}));
+        extra?.(this, props);
+    };
+    Object.defineProperty(Cls, "name", { value: className });
+    return Cls;
+}
+/**
+ * A notification receiver: webhook, email, Slack and PagerDuty integrations.
+ *
+ * Credentials (Slack `api_url`, PagerDuty `routing_key`, SMTP passwords)
+ * belong in the `*_file` fields; Alertmanager does not expand environment
+ * variables in its config, and PROM001 flags a literal.
+ */
+export const Receiver = entityClass(RECEIVER_TYPE, "Receiver", (self, props) => {
+    Object.defineProperty(self, "receiverName", { value: props?.name, enumerable: false });
+});
+/** A named set of time periods a route can mute or activate on. */
+export const TimeInterval = entityClass(TIME_INTERVAL_TYPE, "TimeInterval", (self, props) => {
+    Object.defineProperty(self, "intervalName", { value: props?.name, enumerable: false });
+});
+/** A node in the routing tree. Declare one root route; nest the rest under `routes`. */
+export const Route = entityClass(ROUTE_TYPE, "Route");
+/** Mutes alerts matching `target_matchers` while an alert matching `source_matchers` fires. */
+export const InhibitRule = entityClass(INHIBIT_RULE_TYPE, "InhibitRule");
+/** The `global:` block, `templates:` list and `tracing:` block. Optional; declare at most one. */
+export const AlertmanagerSettings = entityClass(SETTINGS_TYPE, "AlertmanagerSettings");
+// ── Guards ──────────────────────────────────────────────────────────
+function isType(type) {
+    return (value) => typeof value === "object" && value !== null && value.entityType === type;
+}
+export const isReceiver = isType(RECEIVER_TYPE);
+export const isRoute = isType(ROUTE_TYPE);
+export const isInhibitRule = isType(INHIBIT_RULE_TYPE);
+export const isTimeInterval = isType(TIME_INTERVAL_TYPE);
+export const isAlertmanagerSettings = isType(SETTINGS_TYPE);
+/** True for any of the Alertmanager entity kinds. */
+export function isAlertmanagerEntity(value) {
+    return isReceiver(value) || isRoute(value) || isInhibitRule(value) || isTimeInterval(value) || isAlertmanagerSettings(value);
+}

package/dist/api/alertmanager.js

@@ -0,0 +1,98 @@
+/**
+ * The Alertmanager config APIs (#3371).
+ *
+ * | Kind | Config | Health |
+ * |---|---|---|
+ * | `alertmanager` | `/api/v2/status` `config.original` | the same answer: `cluster.status`, `versionInfo.version` |
+ * | `mimir`, `cortex` | `/api/v1/alerts` (YAML: `alertmanager_config`, `template_files`) | `<prefix>/api/v2/status`, best effort |
+ *
+ * A plain Alertmanager's `config.original` is not the file it loaded. It is
+ * the loaded config marshalled again (`Config.String()` in Alertmanager's
+ * `config/config.go`): secrets read `<secret>`, the global defaults are
+ * written out, and every receiver carries the settings it inherited from
+ * `global:`. ../import/alertmanager-live.ts takes those back out. Mimir and
+ * Cortex return the config as the tenant uploaded it.
+ *
+ * `setConfig` is for the ruler apply target (#3372): `POST /api/v1/alerts`,
+ * which Mimir and Cortex serve with `-alertmanager.enable-api`. A plain
+ * Alertmanager has no config write API.
+ */
+import { dump } from "js-yaml";
+import { loadPrometheusYaml } from "../import/parser.js";
+import { PromApiError } from "./client.js";
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** A bound Alertmanager: the transport and the target it reaches. */
+export class AlertmanagerApi {
+    constructor(client, target) {
+        this.client = client;
+        this.target = target;
+    }
+    /** Where `/api/v2/status` is served. */
+    get statusPath() {
+        return this.target.kind === "alertmanager" ? "/api/v2/status" : `${this.target.alertmanagerPrefix}/api/v2/status`;
+    }
+    /** The status answer, read once per client; undefined on 404. */
+    status() {
+        return this.client.once("status", () => this.client.getJson(this.statusPath));
+    }
+    /** The loaded config; undefined when there is none (Mimir answers 404 for a tenant with no config). */
+    async readConfig() {
+        return this.client.once("config", async () => {
+            if (this.target.kind === "alertmanager") {
+                const status = await this.status();
+                if (status === undefined)
+                    return undefined;
+                const original = isObject(status.config) ? status.config.original : undefined;
+                if (typeof original !== "string")
+                    throw new PromApiError(502, "GET", this.statusPath, "the status has no config.original");
+                return { text: original, address: this.statusPath, remarshalled: true };
+            }
+            const path = "/api/v1/alerts";
+            const text = await this.client.getText(path);
+            if (text === undefined)
+                return undefined;
+            const doc = loadPrometheusYaml(text);
+            if (!isObject(doc) || typeof doc.alertmanager_config !== "string") {
+                throw new PromApiError(502, "GET", path, "the answer has no alertmanager_config");
+            }
+            const templateFiles = isObject(doc.template_files)
+                ? Object.fromEntries(Object.entries(doc.template_files).map(([k, v]) => [k, String(v)]))
+                : undefined;
+            return {
+                text: doc.alertmanager_config,
+                address: path,
+                remarshalled: false,
+                ...(templateFiles && Object.keys(templateFiles).length > 0 ? { templateFiles } : {}),
+            };
+        });
+    }
+    /** Cluster status and version. Never throws: a failed read is no health, since health is an attribute, not presence. */
+    async health() {
+        let status;
+        try {
+            status = await this.status();
+        }
+        catch {
+            return undefined;
+        }
+        if (!status)
+            return undefined;
+        const cluster = isObject(status.cluster) ? status.cluster : {};
+        const version = isObject(status.versionInfo) ? status.versionInfo.version : undefined;
+        return {
+            ...(typeof cluster.status === "string" ? { cluster: cluster.status } : {}),
+            ...(Array.isArray(cluster.peers) ? { peers: cluster.peers.length } : {}),
+            ...(typeof version === "string" ? { version } : {}),
+        };
+    }
+    /** Upload a config (Mimir and Cortex, `POST /api/v1/alerts`, 201). */
+    async setConfig(config, templateFiles = {}) {
+        if (this.target.kind === "alertmanager") {
+            throw new Error(`a plain Alertmanager (${this.target.source}) has no config API; it reads alertmanager.yml from disk`);
+        }
+        const body = dump({ template_files: templateFiles, alertmanager_config: config }, { lineWidth: -1, noRefs: true });
+        await this.client.send("POST", "/api/v1/alerts", { text: body, contentType: "application/yaml" });
+    }
+}

package/dist/api/apply.js

@@ -0,0 +1,306 @@
+/**
+ * The ruler apply target (#3372): `nativeApply`'s `ruler` target, reached
+ * through `@intentius/chant-lexicon-prometheus/api/apply` the way core
+ * reaches the grafana and sql appliers. Core imports no lexicon; it loads
+ * this module by name at call time.
+ *
+ * One transport with observe and export ({@link bindEndpoints}), so the
+ * tenant (`X-Scope-OrgID`) and the Mimir, Cortex and Loki path variants are
+ * the profile's: `prometheus.profiles.<env>.ruler`.
+ *
+ * The ownership boundary is {@link declaredNamespaces}. The plan reads only
+ * those namespaces, a group is written only into the namespace
+ * {@link namespaceOfGroup} gives it, and an owned-only delete removes a
+ * group the ruler has and the project does not declare, one group at a
+ * time, only inside those namespaces. A namespace the project does not
+ * declare is never listed, read, written or deleted. This is the difference
+ * from `mimirtool rules sync`, which deletes every remote namespace missing
+ * from the local files unless `--namespaces` is set.
+ *
+ * Rollback re-applies the previous group set. Before the first write an
+ * apply saves, beside the build file, what each changed or pruned group
+ * looked like (and which groups it creates); {@link rulerRollback} puts the
+ * first back and deletes the second.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { applyResult, } from "@intentius/chant/apply";
+import { loadPrometheusYaml } from "../import/parser.js";
+import { declaredNamespaces, isUnresolvedTarget, namespaceOfGroup } from "../config.js";
+import { bindEndpoints, classifyPromFailure } from "./bind.js";
+import { PromApiError } from "./client.js";
+function isObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Read the build: the rule groups, and an Alertmanager config (the primary itself, or `alertmanager.yml` beside it). */
+export function readBuilt(buildPath) {
+    const text = readFileSync(buildPath, "utf8");
+    const doc = loadPrometheusYaml(text);
+    const out = { groups: [] };
+    if (isObject(doc) && Array.isArray(doc.groups)) {
+        out.groups = doc.groups.filter((g) => isObject(g) && typeof g.name === "string");
+    }
+    else if (isObject(doc) && ("route" in doc || "receivers" in doc)) {
+        out.alertmanager = text;
+    }
+    const sibling = join(dirname(buildPath), "alertmanager.yml");
+    if (out.alertmanager === undefined && basename(buildPath) !== "alertmanager.yml" && existsSync(sibling)) {
+        out.alertmanager = readFileSync(sibling, "utf8");
+    }
+    return out;
+}
+/**
+ * True when every key the declared value carries is in the live one with an
+ * equal value. A ruler adds fields of its own to a group it returns
+ * (`source_tenants`, say), and those are not a difference.
+ */
+export function covers(declared, live) {
+    if (Array.isArray(declared)) {
+        return Array.isArray(live) && declared.length === live.length && declared.every((d, i) => covers(d, live[i]));
+    }
+    if (isObject(declared)) {
+        return isObject(live) && Object.entries(declared).every(([k, v]) => covers(v, live[k]));
+    }
+    return declared === live;
+}
+/** The snapshot file an apply to `environment` writes beside the build file. */
+export function snapshotPath(buildPath, environment) {
+    return join(dirname(buildPath), `.chant-ruler-previous.${environment.replace(/[^A-Za-z0-9_.-]/g, "_")}.json`);
+}
+async function planGroups(ruler, built, prune) {
+    const target = ruler.target;
+    const plan = { entries: [], writes: [], deletes: [], notAttempted: [] };
+    const declaredNs = declaredNamespaces(target);
+    // Read only the declared namespaces. A namespace the project does not
+    // declare is never listed, so nothing below can reach it.
+    const live = new Map();
+    for (const ns of declaredNs)
+        live.set(ns, (await ruler.readNamespace(ns)) ?? []);
+    const declaredByNs = new Map();
+    for (const group of built.groups) {
+        const ns = namespaceOfGroup(target, group.name);
+        if (ns === undefined || !declaredNs.includes(ns)) {
+            plan.notAttempted.push({
+                kind: "RuleGroup",
+                name: group.name,
+                reason: "no-binding",
+                detail: `no ruler namespace is declared for group "${group.name}": set prometheus.profiles.<env>.ruler.namespace or groupNamespaces`,
+            });
+            continue;
+        }
+        (declaredByNs.get(ns) ?? declaredByNs.set(ns, new Set()).get(ns)).add(group.name);
+        const previous = live.get(ns)?.find((g) => g.name === group.name);
+        const name = `${ns}/${group.name}`;
+        if (previous === undefined) {
+            plan.writes.push({ namespace: ns, group, action: "create" });
+            plan.entries.push({ kind: "RuleGroup", name, namespace: ns, group: group.name, action: "create" });
+        }
+        else if (!covers(group, previous)) {
+            plan.writes.push({ namespace: ns, group, action: "update", previous });
+            plan.entries.push({ kind: "RuleGroup", name, namespace: ns, group: group.name, action: "update" });
+        }
+        else {
+            plan.entries.push({ kind: "RuleGroup", name, namespace: ns, group: group.name, action: "unchanged" });
+        }
+    }
+    if (prune) {
+        for (const ns of declaredNs) {
+            for (const g of live.get(ns) ?? []) {
+                if (declaredByNs.get(ns)?.has(g.name))
+                    continue;
+                plan.deletes.push({ namespace: ns, group: g });
+                plan.entries.push({ kind: "RuleGroup", name: `${ns}/${g.name}`, namespace: ns, group: g.name, action: "delete" });
+            }
+        }
+    }
+    return plan;
+}
+async function planAlertmanager(am, declared) {
+    const name = am.target.tenant ?? "alertmanager";
+    const current = await am.readConfig();
+    if (current === undefined)
+        return { entry: { kind: "AlertmanagerConfig", name, action: "create" } };
+    const same = JSON.stringify(loadPrometheusYaml(current.text)) === JSON.stringify(loadPrometheusYaml(declared));
+    return {
+        entry: { kind: "AlertmanagerConfig", name, action: same ? "unchanged" : "update" },
+        previous: { text: current.text, ...(current.templateFiles ? { templateFiles: current.templateFiles } : {}) },
+    };
+}
+/** What an apply would do, per declared namespace. Reads the ruler; writes nothing. */
+export async function planRuler(args, deps = {}) {
+    const bound = await bindEndpoints({ ...deps, environment: args.environment });
+    if (isUnresolvedTarget(bound.ruler))
+        throw new Error(bound.ruler.detail);
+    const built = readBuilt(args.buildPath);
+    const plan = await planGroups(bound.ruler, built, args.prune ?? false);
+    const entries = [...plan.entries];
+    if (built.alertmanager !== undefined && !isUnresolvedTarget(bound.alertmanager) && bound.alertmanager.target.kind !== "alertmanager") {
+        entries.push((await planAlertmanager(bound.alertmanager, built.alertmanager)).entry);
+    }
+    return entries;
+}
+function allNotAttempted(built, reason, detail) {
+    return {
+        applied: [],
+        pruned: [],
+        notAttempted: [
+            ...built.groups.map((g) => ({ kind: "RuleGroup", name: g.name, reason, detail })),
+            ...(built.alertmanager !== undefined ? [{ kind: "AlertmanagerConfig", name: "alertmanager", reason, detail }] : []),
+        ],
+    };
+}
+/** Apply the build to the environment's ruler (and Alertmanager). */
+export async function rulerApply(args, deps = {}) {
+    const environment = args.environment ?? "default";
+    const built = readBuilt(args.buildPath);
+    const bound = await bindEndpoints({ ...deps, environment: args.environment });
+    const out = { applied: [], pruned: [], notAttempted: [] };
+    let snapshot = { environment, restore: [], remove: [] };
+    let writeSnapshot = false;
+    if (built.groups.length > 0 || args.prune) {
+        if (isUnresolvedTarget(bound.ruler)) {
+            const failed = allNotAttempted({ groups: built.groups }, bound.ruler.reason, bound.ruler.detail);
+            out.notAttempted.push(...failed.notAttempted);
+        }
+        else if (bound.ruler.target.kind === "prometheus") {
+            const failed = allNotAttempted({ groups: built.groups }, "unsupported-kind", `a plain Prometheus (${bound.ruler.target.source}) has no rule group API`);
+            out.notAttempted.push(...failed.notAttempted);
+        }
+        else {
+            const ruler = bound.ruler;
+            try {
+                const plan = await planGroups(ruler, built, args.prune ?? false);
+                out.notAttempted.push(...plan.notAttempted);
+                snapshot.restore = [
+                    ...plan.writes.filter((w) => w.previous).map((w) => ({ namespace: w.namespace, group: w.previous })),
+                    ...plan.deletes.map((d) => ({ namespace: d.namespace, group: d.group })),
+                ];
+                snapshot.remove = plan.writes.filter((w) => w.action === "create").map((w) => ({ namespace: w.namespace, name: w.group.name }));
+                writeSnapshot = plan.writes.length > 0 || plan.deletes.length > 0;
+                if (writeSnapshot)
+                    saveSnapshot(args.buildPath, snapshot);
+                for (const e of plan.entries) {
+                    if (e.action === "unchanged")
+                        out.applied.push({ kind: e.kind, name: e.name, action: "unchanged" });
+                }
+                for (const w of plan.writes) {
+                    const name = `${w.namespace}/${w.group.name}`;
+                    try {
+                        await ruler.setGroup(w.namespace, w.group);
+                        out.applied.push({ kind: "RuleGroup", name, action: w.action === "create" ? "created" : "updated" });
+                    }
+                    catch (err) {
+                        out.notAttempted.push({ kind: "RuleGroup", name, ...failure(err) });
+                    }
+                }
+                for (const d of plan.deletes) {
+                    const name = `${d.namespace}/${d.group.name}`;
+                    try {
+                        await ruler.deleteGroup(d.namespace, d.group.name);
+                        out.pruned.push({ kind: "RuleGroup", name, deleted: true });
+                    }
+                    catch (err) {
+                        if (err instanceof PromApiError && err.status === 404)
+                            out.pruned.push({ kind: "RuleGroup", name, deleted: false });
+                        else
+                            out.notAttempted.push({ kind: "RuleGroup", name, ...failure(err) });
+                    }
+                }
+            }
+            catch (err) {
+                const f = failure(err);
+                out.notAttempted.push(...built.groups.map((g) => ({ kind: "RuleGroup", name: g.name, ...f })));
+            }
+        }
+    }
+    if (built.alertmanager !== undefined) {
+        const amName = isUnresolvedTarget(bound.alertmanager) ? "alertmanager" : (bound.alertmanager.target.tenant ?? "alertmanager");
+        if (isUnresolvedTarget(bound.alertmanager)) {
+            out.notAttempted.push({ kind: "AlertmanagerConfig", name: amName, reason: bound.alertmanager.reason, detail: bound.alertmanager.detail });
+        }
+        else if (bound.alertmanager.target.kind === "alertmanager") {
+            out.notAttempted.push({
+                kind: "AlertmanagerConfig",
+                name: amName,
+                reason: "unsupported-kind",
+                detail: `a plain Alertmanager (${bound.alertmanager.target.source}) has no config API; only Mimir and Cortex take an upload`,
+            });
+        }
+        else {
+            try {
+                const { entry, previous } = await planAlertmanager(bound.alertmanager, built.alertmanager);
+                if (entry.action === "unchanged") {
+                    out.applied.push({ kind: entry.kind, name: entry.name, action: "unchanged" });
+                }
+                else {
+                    if (previous) {
+                        snapshot = { ...snapshot, alertmanager: previous };
+                    }
+                    saveSnapshot(args.buildPath, snapshot);
+                    await bound.alertmanager.setConfig(built.alertmanager);
+                    out.applied.push({ kind: entry.kind, name: entry.name, action: entry.action === "create" ? "created" : "updated" });
+                }
+            }
+            catch (err) {
+                out.notAttempted.push({ kind: "AlertmanagerConfig", name: amName, ...failure(err) });
+            }
+        }
+    }
+    return out;
+}
+function failure(err) {
+    const { reason, detail } = classifyPromFailure(err);
+    return { reason: reason === "no-credentials" || reason === "no-binding" ? reason : "dependency-failed", detail };
+}
+function saveSnapshot(buildPath, snapshot) {
+    const path = snapshotPath(buildPath, snapshot.environment);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(snapshot, null, 2));
+}
+/**
+ * Re-apply the previous group set: put back every group the last apply
+ * replaced or deleted, and delete the ones it created. Touches only the
+ * groups the snapshot names, so a namespace the project does not declare is
+ * as untouched here as in the apply.
+ */
+export async function rulerRollback(args, deps = {}) {
+    const environment = args.environment ?? "default";
+    const path = snapshotPath(args.buildPath, environment);
+    const outcome = { restored: 0, removed: 0, alertmanagerRestored: false, hadSnapshot: existsSync(path) };
+    if (!outcome.hadSnapshot)
+        return outcome;
+    const snapshot = JSON.parse(readFileSync(path, "utf8"));
+    const bound = await bindEndpoints({ ...deps, environment: args.environment });
+    if (snapshot.restore.length > 0 || snapshot.remove.length > 0) {
+        if (isUnresolvedTarget(bound.ruler))
+            throw new Error(bound.ruler.detail);
+        const declared = declaredNamespaces(bound.ruler.target);
+        for (const r of snapshot.restore) {
+            if (!declared.includes(r.namespace))
+                continue;
+            await bound.ruler.setGroup(r.namespace, r.group);
+            outcome.restored++;
+        }
+        for (const r of snapshot.remove) {
+            if (!declared.includes(r.namespace))
+                continue;
+            try {
+                await bound.ruler.deleteGroup(r.namespace, r.name);
+                outcome.removed++;
+            }
+            catch (err) {
+                if (!(err instanceof PromApiError && err.status === 404))
+                    throw err;
+            }
+        }
+    }
+    if (snapshot.alertmanager !== undefined && !isUnresolvedTarget(bound.alertmanager) && bound.alertmanager.target.kind !== "alertmanager") {
+        await bound.alertmanager.setConfig(snapshot.alertmanager.text, snapshot.alertmanager.templateFiles ?? {});
+        outcome.alertmanagerRestored = true;
+    }
+    return outcome;
+}
+/** The outcome as core's apply envelope (#1446). */
+export function toApplyResult(outcome) {
+    return applyResult(outcome.applied.map((a) => ({ kind: a.kind, name: a.name, action: a.action })), outcome.pruned, outcome.notAttempted);
+}

package/dist/api/bind.js

@@ -0,0 +1,66 @@
+/**
+ * Binding the ruler and the Alertmanager for one environment: the config
+ * lookup, the targets, the transports. Shared by observe, live export and
+ * the ruler apply target (#3372), so all three reach the same endpoints.
+ *
+ * The two bind independently. A project that declares only rule groups has
+ * no Alertmanager to bind, and that must not make its groups unobservable.
+ */
+import { PromApiError, PromClient, promHttp } from "./client.js";
+import { AlertmanagerApi } from "./alertmanager.js";
+import { RulerApi } from "./ruler.js";
+import { isUnresolvedTarget, resolveAlertmanagerTarget, resolveRulerTarget } from "../config.js";
+/** A target that could not be resolved. */
+export class PromBindingError extends Error {
+    constructor(unresolved) {
+        super(unresolved.detail);
+        this.unresolved = unresolved;
+        this.name = "PromBindingError";
+    }
+}
+async function loadConfig(cwd) {
+    try {
+        const { loadChantConfig } = await import("@intentius/chant/config");
+        return (await loadChantConfig(cwd)).config;
+    }
+    catch {
+        // No project config (an ad-hoc import): the environment variables still bind.
+        return undefined;
+    }
+}
+/** Resolve both endpoints for an environment. Never throws for a missing binding; each side says why it is unbound. */
+export async function bindEndpoints(options = {}) {
+    const config = options.config ?? (await loadConfig(options.cwd ?? process.cwd()));
+    const input = { environment: options.environment, config, env: options.env };
+    const r = resolveRulerTarget(input);
+    const a = resolveAlertmanagerTarget(input);
+    return {
+        ruler: isUnresolvedTarget(r) ? r : new RulerApi(new PromClient(options.http?.ruler ?? promHttp(r), r), r),
+        alertmanager: isUnresolvedTarget(a) ? a : new AlertmanagerApi(new PromClient(options.http?.alertmanager ?? promHttp(a), a), a),
+    };
+}
+/** The ruler alone, for a caller (the apply target) that needs it bound. Throws {@link PromBindingError} when there is none. */
+export async function bindRuler(options = {}) {
+    const { ruler } = await bindEndpoints(options);
+    if (isUnresolvedTarget(ruler))
+        throw new PromBindingError(ruler);
+    return ruler;
+}
+/** The Alertmanager alone. Throws {@link PromBindingError} when there is none. */
+export async function bindAlertmanager(options = {}) {
+    const { alertmanager } = await bindEndpoints(options);
+    if (isUnresolvedTarget(alertmanager))
+        throw new PromBindingError(alertmanager);
+    return alertmanager;
+}
+/** What a failed bind or read means, in the observation vocabulary. */
+export function classifyPromFailure(err) {
+    if (err instanceof PromBindingError)
+        return { reason: err.unresolved.reason, detail: err.unresolved.detail };
+    if (err instanceof PromApiError) {
+        return err.verdict === "refused"
+            ? { reason: "no-credentials", detail: `${err.message} (the credentials were refused)` }
+            : { reason: "read-failed", detail: err.message };
+    }
+    return { reason: "read-failed", detail: err instanceof Error ? err.message.split("\n")[0] : String(err) };
+}

package/dist/api/client.js

@@ -0,0 +1,110 @@
+/**
+ * The HTTP transport for the ruler and Alertmanager APIs (#3371): one client
+ * for observe and live export here, and for the ruler apply target (#3372),
+ * so every path reaches the same endpoint with the same tenant and
+ * credentials.
+ *
+ * `PromHttp` is the seam. The default is `fetch` against a resolved target;
+ * a test hands in a function, or points the target at a local fake server
+ * (./fake-servers.ts).
+ *
+ * Bodies are text. The ruler's config API speaks YAML both ways, the
+ * Prometheus-compatible APIs answer JSON, and Mimir's Alertmanager config
+ * API answers YAML, so the caller decides how to read a body.
+ *
+ * Status mapping is in one place ({@link statusVerdict}): a 404 is the only
+ * answer that means "not there", 401 and 403 mean the credentials were
+ * refused, anything else that is not a 2xx is a failed read.
+ */
+function authHeader(auth) {
+    if (!auth)
+        return {};
+    if ("token" in auth)
+        return { authorization: `Bearer ${auth.token}` };
+    return { authorization: `Basic ${Buffer.from(`${auth.user}:${auth.password}`).toString("base64")}` };
+}
+/** The default transport: `fetch` against the target, with the tenant header and credentials on every request. */
+export function promHttp(target, fetchImpl = fetch) {
+    const base = target.url.replace(/\/+$/, "");
+    const headers = {
+        accept: "application/json, application/yaml;q=0.9, */*;q=0.1",
+        ...authHeader(target.auth),
+        ...(target.tenant ? { "x-scope-orgid": target.tenant } : {}),
+    };
+    return async (method, path, body) => {
+        const res = await fetchImpl(`${base}${path}`, {
+            method,
+            headers: body === undefined ? headers : { ...headers, "content-type": body.contentType },
+            ...(body === undefined ? {} : { body: body.text }),
+        });
+        return { status: res.status, text: await res.text() };
+    };
+}
+export function statusVerdict(status) {
+    if (status >= 200 && status < 300)
+        return "ok";
+    if (status === 404)
+        return "not-found";
+    if (status === 401 || status === 403)
+        return "refused";
+    return "failed";
+}
+/** A non-2xx answer, with enough to classify it and to say where it came from. */
+export class PromApiError extends Error {
+    constructor(status, method, path, body) {
+        const detail = body.trim().split("\n")[0].slice(0, 200);
+        super(`${method} ${path} returned ${status}${detail ? `: ${detail}` : ""}`);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.name = "PromApiError";
+        this.verdict = statusVerdict(status);
+    }
+}
+/** A bound client: the transport, the target it reaches, and a per-client memo so N reads share one lookup. */
+export class PromClient {
+    constructor(http, target) {
+        this.http = http;
+        this.target = target;
+        this.memo = new Map();
+    }
+    /** GET, returning the body text; undefined on 404; throws {@link PromApiError} on any other non-2xx. */
+    async getText(path) {
+        const res = await this.http("GET", path);
+        const verdict = statusVerdict(res.status);
+        if (verdict === "ok")
+            return res.text;
+        if (verdict === "not-found")
+            return undefined;
+        throw new PromApiError(res.status, "GET", path, res.text);
+    }
+    /** GET a JSON body; undefined on 404. A 2xx body that is not JSON is a failed read. */
+    async getJson(path) {
+        const text = await this.getText(path);
+        if (text === undefined)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new PromApiError(502, "GET", path, `the answer is not JSON: ${text.slice(0, 80)}`);
+        }
+    }
+    /** A write. Resolves on a 2xx; throws {@link PromApiError} otherwise, a 404 included. */
+    async send(method, path, body) {
+        const res = await this.http(method, path, body);
+        if (statusVerdict(res.status) !== "ok")
+            throw new PromApiError(res.status, method, path, res.text);
+        return res;
+    }
+    /** Run `fn` once per key for this client's lifetime; concurrent callers share the promise. A failure is not cached. */
+    once(key, fn) {
+        let p = this.memo.get(key);
+        if (!p) {
+            p = fn();
+            this.memo.set(key, p);
+            p.catch(() => this.memo.delete(key));
+        }
+        return p;
+    }
+}