@intentius/chant-lexicon-prometheus 0.106.4 → 0.108.0

package/src/api/bind.ts

@@ -0,0 +1,87 @@
+/**
+ * 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 type { ChantConfig } from "@intentius/chant/config";
+import type { UnobservedReason } from "@intentius/chant/observation";
+import { PromApiError, PromClient, promHttp, type PromHttp } from "./client";
+import { AlertmanagerApi } from "./alertmanager";
+import { RulerApi } from "./ruler";
+import { isUnresolvedTarget, resolveAlertmanagerTarget, resolveRulerTarget, type UnresolvedTarget } from "../config";
+
+/** What callers may inject: tests pass `http` or point the config at a fake server; the CLI passes nothing. */
+export interface BindOptions {
+  environment?: string;
+  /** The project's config. Loaded from `cwd` (default: the working directory) when omitted. */
+  config?: Pick<ChantConfig, "prometheus">;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  /** Transport overrides, per endpoint. The targets are still resolved, so a test exercises the binding too. */
+  http?: { ruler?: PromHttp; alertmanager?: PromHttp };
+}
+
+/** A target that could not be resolved. */
+export class PromBindingError extends Error {
+  constructor(readonly unresolved: UnresolvedTarget) {
+    super(unresolved.detail);
+    this.name = "PromBindingError";
+  }
+}
+
+/** Both endpoints, each bound or the reason it is not. */
+export interface BoundEndpoints {
+  ruler: RulerApi | UnresolvedTarget;
+  alertmanager: AlertmanagerApi | UnresolvedTarget;
+}
+
+async function loadConfig(cwd: string): Promise<Pick<ChantConfig, "prometheus"> | undefined> {
+  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: BindOptions = {}): Promise<BoundEndpoints> {
+  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: BindOptions = {}): Promise<RulerApi> {
+  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: BindOptions = {}): Promise<AlertmanagerApi> {
+  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: unknown): { reason: UnobservedReason; detail: string } {
+  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/src/api/client.ts

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+
+/** How the client authenticates. */
+export type PromAuth = { readonly token: string } | { readonly user: string; readonly password: string };
+
+/** A resolved endpoint: where, as which tenant, as whom, and where that came from. */
+export interface PromTarget {
+  /** Base URL, without a trailing slash. */
+  readonly url: string;
+  /** `X-Scope-OrgID`, for a multi-tenant Mimir, Cortex or Loki. */
+  readonly tenant?: string;
+  readonly auth?: PromAuth;
+  /** Where the binding came from: `prometheus.profiles.prod.ruler`, `env PROMETHEUS_RULER_URL`. */
+  readonly source: string;
+}
+
+export interface PromResponse {
+  readonly status: number;
+  readonly text: string;
+}
+
+/** One request. `path` starts with `/` and is relative to the target's URL. */
+export type PromHttp = (method: string, path: string, body?: { text: string; contentType: string }) => Promise<PromResponse>;
+
+function authHeader(auth: PromAuth | undefined): Record<string, string> {
+  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: PromTarget, fetchImpl: typeof fetch = fetch): PromHttp {
+  const base = target.url.replace(/\/+$/, "");
+  const headers: Record<string, string> = {
+    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() };
+  };
+}
+
+/** What a status means for a read. */
+export type StatusVerdict = "ok" | "not-found" | "refused" | "failed";
+
+export function statusVerdict(status: number): StatusVerdict {
+  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 {
+  readonly verdict: StatusVerdict;
+  constructor(
+    readonly status: number,
+    readonly method: string,
+    readonly path: string,
+    body: string,
+  ) {
+    const detail = body.trim().split("\n")[0].slice(0, 200);
+    super(`${method} ${path} returned ${status}${detail ? `: ${detail}` : ""}`);
+    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 {
+  private readonly memo = new Map<string, Promise<unknown>>();
+
+  constructor(
+    readonly http: PromHttp,
+    readonly target: PromTarget,
+  ) {}
+
+  /** GET, returning the body text; undefined on 404; throws {@link PromApiError} on any other non-2xx. */
+  async getText(path: string): Promise<string | undefined> {
+    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<T = unknown>(path: string): Promise<T | undefined> {
+    const text = await this.getText(path);
+    if (text === undefined) return undefined;
+    try {
+      return JSON.parse(text) as T;
+    } 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: "POST" | "PUT" | "DELETE", path: string, body?: { text: string; contentType: string }): Promise<PromResponse> {
+    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<T>(key: string, fn: () => Promise<T>): Promise<T> {
+    let p = this.memo.get(key) as Promise<T> | undefined;
+    if (!p) {
+      p = fn();
+      this.memo.set(key, p);
+      p.catch(() => this.memo.delete(key));
+    }
+    return p;
+  }
+}

package/src/api/evaluated.test.ts

@@ -0,0 +1,78 @@
+/** `/api/v1/rules` groups mapped to the rule-file shape and to a health summary (#3371). */
+
+import { describe, expect, test } from "vitest";
+import { evaluatedToRuleGroup, groupHealth } from "./evaluated";
+import type { EvaluatedGroup } from "./ruler";
+
+// The shape Prometheus 3.x answers `/api/v1/rules` with, one group.
+const api: EvaluatedGroup = {
+  name: "api",
+  file: "/etc/prometheus/rules/api.yml",
+  interval: 30,
+  limit: 0,
+  evaluationTime: 0.0012,
+  lastEvaluation: "2026-10-06T08:00:00Z",
+  rules: [
+    { type: "recording", name: "job:http_requests:rate5m", query: "sum by (job) (rate(http_requests_total[5m]))", labels: {}, health: "ok" },
+    {
+      type: "alerting",
+      name: "ApiHighErrorRate",
+      query: 'sum(rate(http_requests_total{code=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) > 0.05',
+      duration: 600,
+      keepFiringFor: 0,
+      labels: { severity: "page" },
+      annotations: { summary: "API 5xx ratio above 5%" },
+      health: "ok",
+      state: "firing",
+    },
+  ],
+};
+
+describe("evaluatedToRuleGroup", () => {
+  test("maps names, queries and second durations back to rule fields", () => {
+    expect(evaluatedToRuleGroup(api)).toEqual({
+      name: "api",
+      interval: "30s",
+      rules: [
+        { record: "job:http_requests:rate5m", expr: "sum by (job) (rate(http_requests_total[5m]))" },
+        {
+          alert: "ApiHighErrorRate",
+          expr: 'sum(rate(http_requests_total{code=~"5.."}[5m])) / sum(rate(http_requests_total[5m])) > 0.05',
+          for: "10m",
+          labels: { severity: "page" },
+          annotations: { summary: "API 5xx ratio above 5%" },
+        },
+      ],
+    });
+  });
+
+  test("a mixed duration and a keep_firing_for are written the way Prometheus writes them", () => {
+    const g = evaluatedToRuleGroup({ ...api, interval: 90, rules: [{ type: "alerting", name: "A", query: "up == 0", duration: 3600, keepFiringFor: 300 }] });
+    expect(g.interval).toBe("1m30s");
+    expect(g.rules[0]).toEqual({ alert: "A", expr: "up == 0", for: "1h", keep_firing_for: "5m" });
+  });
+
+  test("a positive limit is kept", () => {
+    expect(evaluatedToRuleGroup({ ...api, limit: 10 }).limit).toBe(10);
+  });
+});
+
+describe("groupHealth", () => {
+  test("every rule ok is ok, with firing and pending counted", () => {
+    expect(groupHealth(api)).toMatchObject({ health: "ok", failing: 0, firing: 1, pending: 0 });
+  });
+
+  test("one failing rule makes the group err and names the first error", () => {
+    const g = { ...api, rules: [{ ...api.rules[0], health: "err", lastError: "vector contains metrics with the same labelset" }, api.rules[1]] };
+    expect(groupHealth(g)).toMatchObject({
+      health: "err",
+      failing: 1,
+      lastError: "job:http_requests:rate5m: vector contains metrics with the same labelset",
+    });
+  });
+
+  test("a rule not yet evaluated, or an empty group, is unknown", () => {
+    expect(groupHealth({ ...api, rules: [{ ...api.rules[0], health: "unknown" }] }).health).toBe("unknown");
+    expect(groupHealth({ ...api, rules: [] }).health).toBe("unknown");
+  });
+});

package/src/api/evaluated.ts

@@ -0,0 +1,106 @@
+/**
+ * What `/api/v1/rules` says about a group, mapped two ways (#3371): to the
+ * group's health for `describeResources`, and, for a plain Prometheus,
+ * which has no rule group API, back to the rule-file shape for import.
+ *
+ * The second mapping is lossy, and says so. `/api/v1/rules` reports rules
+ * as Prometheus evaluates them, not as the file wrote them: `query` is the
+ * expression as PromQL prints it, durations are seconds, and a group's
+ * `interval` is the one it runs on, the global `evaluation_interval` when
+ * the group set none. A group's `labels` and `query_offset` are not
+ * reported at all.
+ */
+
+import { formatDuration } from "../duration";
+import type { RuleConfig, RuleGroupConfig } from "../model";
+import type { EvaluatedGroup } from "./ruler";
+
+/** A duration in seconds as Prometheus writes one; undefined for zero or a value that is not a number. */
+function seconds(v: unknown): string | undefined {
+  if (typeof v !== "number" || !Number.isFinite(v) || v <= 0) return undefined;
+  return formatDuration(Math.round(v * 1000));
+}
+
+function labelsOf(v: unknown): Record<string, string> | undefined {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return undefined;
+  const entries = Object.entries(v as Record<string, unknown>).map(([k, x]) => [k, String(x)] as const);
+  return entries.length > 0 ? Object.fromEntries(entries) : undefined;
+}
+
+/** What the import of evaluated groups leaves out, said once per export. */
+export const EVALUATED_IMPORT_WARNING =
+  "rule groups were read from /api/v1/rules, which reports them as Prometheus evaluates them: expressions are as PromQL prints them, " +
+  "a group's interval is the one it runs on (the global evaluation_interval when the group sets none), and group labels and query_offset are not reported";
+
+/** A group from `/api/v1/rules` in the rule-file shape. */
+export function evaluatedToRuleGroup(group: EvaluatedGroup): RuleGroupConfig {
+  const rules: RuleConfig[] = group.rules.map((r) => {
+    if (r.type === "recording") {
+      const labels = labelsOf(r.labels);
+      return { record: r.name, expr: r.query, ...(labels ? { labels } : {}) };
+    }
+    const labels = labelsOf(r.labels);
+    const annotations = labelsOf(r.annotations);
+    const forDuration = seconds(r.duration);
+    const keep = seconds(r.keepFiringFor);
+    return {
+      alert: r.name,
+      expr: r.query,
+      ...(forDuration ? { for: forDuration } : {}),
+      ...(keep ? { keep_firing_for: keep } : {}),
+      ...(labels ? { labels } : {}),
+      ...(annotations ? { annotations } : {}),
+    };
+  });
+  const interval = seconds(group.interval);
+  return {
+    name: group.name,
+    ...(interval ? { interval } : {}),
+    ...(typeof group.limit === "number" && group.limit > 0 ? { limit: group.limit } : {}),
+    rules,
+  };
+}
+
+/** A group's health, from its rules: `err` when any rule failed its last evaluation, `ok` when every rule passed, else `unknown`. */
+export interface GroupHealth {
+  health: "ok" | "err" | "unknown";
+  /** The first rule error, as `<rule>: <error>`. */
+  lastError?: string;
+  /** How many rules failed their last evaluation. */
+  failing: number;
+  /** Alerting rules by state. */
+  firing: number;
+  pending: number;
+  lastEvaluation?: string;
+  /** Seconds the last evaluation took. */
+  evaluationTime?: number;
+  /** Seconds. */
+  interval?: number;
+}
+
+export function groupHealth(group: EvaluatedGroup): GroupHealth {
+  let failing = 0;
+  let unknown = 0;
+  let firing = 0;
+  let pending = 0;
+  let lastError: string | undefined;
+  for (const r of group.rules) {
+    if (r.health === "err") {
+      failing++;
+      lastError ??= `${r.name}: ${r.lastError ?? "evaluation failed"}`;
+    } else if (r.health !== "ok") unknown++;
+    if (r.state === "firing") firing++;
+    else if (r.state === "pending") pending++;
+  }
+  const health = failing > 0 ? "err" : unknown > 0 || group.rules.length === 0 ? "unknown" : "ok";
+  return {
+    health,
+    ...(lastError ? { lastError } : {}),
+    failing,
+    firing,
+    pending,
+    ...(group.lastEvaluation ? { lastEvaluation: group.lastEvaluation } : {}),
+    ...(typeof group.evaluationTime === "number" ? { evaluationTime: group.evaluationTime } : {}),
+    ...(typeof group.interval === "number" ? { interval: group.interval } : {}),
+  };
+}

package/src/api/fake-servers.ts

@@ -0,0 +1,209 @@
+/**
+ * A ruler and an Alertmanager in memory, for the observe and export tests
+ * (#3371), and for the ruler apply target's (#3372).
+ *
+ * Each fake is a request handler over a state the test sets up. It answers
+ * the routes ./ruler.ts and ./alertmanager.ts use, in the shapes the
+ * projects document: the ruler config API's YAML (a mapping of namespace to
+ * groups; one group alone at `/{namespace}/{group}`; 404 for a namespace or
+ * group that is not there), `/api/v1/rules` JSON, Alertmanager's
+ * `/api/v2/status` and Mimir's `/api/v1/alerts`. With `tenant` set it
+ * answers 401 to a request without that `X-Scope-OrgID`, as Mimir does
+ * ("no org id").
+ *
+ * {@link serveFake} puts a handler behind a real HTTP server on localhost,
+ * so a test drives the default `fetch` transport, headers included.
+ * {@link fakeHttp} hands the same handler in as a {@link PromHttp}.
+ */
+
+import { createServer, type IncomingMessage } from "node:http";
+import type { AddressInfo } from "node:net";
+import { dump } from "js-yaml";
+import { loadPrometheusYaml } from "../import/parser";
+import type { RulerKind } from "../config";
+import type { PromHttp } from "./client";
+import type { EvaluatedGroup, RawRuleGroup } from "./ruler";
+
+export interface FakeRequest {
+  method: string;
+  path: string;
+  headers: Record<string, string | undefined>;
+  body?: string;
+}
+
+export interface FakeResponse {
+  status: number;
+  text: string;
+  contentType?: string;
+}
+
+export type FakeHandler = (req: FakeRequest) => FakeResponse;
+
+export interface FakeRulerState {
+  kind: RulerKind;
+  /** Groups by namespace (on a plain Prometheus, by rule file). */
+  namespaces: Record<string, RawRuleGroup[]>;
+  /** What `/api/v1/rules` reports. Defaults to every group, every rule healthy and inactive. */
+  evaluated?: EvaluatedGroup[];
+  /** Required `X-Scope-OrgID`. */
+  tenant?: string;
+  /** Answer every request with this status. */
+  status?: number;
+  /** Answer `/api/v1/rules` with this status (a ruler whose evaluation API is down). */
+  evaluatedStatus?: number;
+  prometheusPrefix?: string;
+}
+
+export interface FakeAlertmanagerState {
+  kind: "alertmanager" | "mimir" | "cortex";
+  /** `/api/v2/status` `config.original`. */
+  original?: string;
+  /** Mimir and Cortex: the uploaded config, absent for a tenant with none. */
+  uploaded?: { alertmanager_config: string; template_files?: Record<string, string> };
+  cluster?: string;
+  version?: string;
+  tenant?: string;
+  status?: number;
+}
+
+const yaml = (v: unknown) => dump(v, { lineWidth: -1, noRefs: true });
+const ok = (text: string, contentType = "application/yaml"): FakeResponse => ({ status: 200, text, contentType });
+const json = (v: unknown): FakeResponse => ({ status: 200, text: JSON.stringify(v), contentType: "application/json" });
+const notFound = (what: string): FakeResponse => ({ status: 404, text: what, contentType: "text/plain" });
+
+function tenantRefused(tenant: string | undefined, req: FakeRequest): FakeResponse | undefined {
+  if (tenant === undefined) return undefined;
+  return req.headers["x-scope-orgid"] === tenant ? undefined : { status: 401, text: "no org id", contentType: "text/plain" };
+}
+
+/** What `/api/v1/rules` reports for a group nobody set an evaluation for: every rule healthy. */
+export function evaluatedOf(file: string, group: RawRuleGroup): EvaluatedGroup {
+  const rules = Array.isArray(group.rules) ? (group.rules as Array<Record<string, unknown>>) : [];
+  return {
+    name: group.name,
+    file,
+    interval: 60,
+    rules: rules.map((r) =>
+      typeof r.alert === "string"
+        ? { type: "alerting", name: r.alert, query: String(r.expr), duration: 0, labels: (r.labels as Record<string, string>) ?? {}, annotations: (r.annotations as Record<string, string>) ?? {}, health: "ok", state: "inactive" }
+        : { type: "recording", name: String(r.record), query: String(r.expr), labels: (r.labels as Record<string, string>) ?? {}, health: "ok" },
+    ),
+  };
+}
+
+/** A ruler over `state`. Writes change `state`, so a test can read back what an apply did. */
+export function fakeRuler(state: FakeRulerState, calls: string[] = []): FakeHandler {
+  const prefix = state.prometheusPrefix ?? (state.kind === "prometheus" ? "" : "/prometheus");
+  const base = state.kind === "mimir" ? `${prefix}/config/v1/rules` : state.kind === "cortex" ? "/api/v1/rules" : state.kind === "loki" ? "/loki/api/v1/rules" : undefined;
+  return (req) => {
+    calls.push(`${req.method} ${req.path}`);
+    if (state.status !== undefined) return { status: state.status, text: "refused" };
+    const refused = tenantRefused(state.tenant, req);
+    if (refused) return refused;
+    const route = req.path.split("?")[0];
+
+    if (route === `${prefix}/api/v1/rules` && req.method === "GET") {
+      if (state.evaluatedStatus !== undefined) return { status: state.evaluatedStatus, text: "evaluation unavailable" };
+      const groups = state.evaluated ?? Object.entries(state.namespaces).flatMap(([ns, gs]) => gs.map((g) => evaluatedOf(ns, g)));
+      return json({ status: "success", data: { groups } });
+    }
+    if (base === undefined || (route !== base && !route.startsWith(`${base}/`))) return notFound("404 page not found");
+
+    const parts = route.slice(base.length).split("/").filter(Boolean).map(decodeURIComponent);
+    if (req.method === "GET") {
+      if (parts.length === 0) {
+        const nonEmpty = Object.fromEntries(Object.entries(state.namespaces).filter(([, gs]) => gs.length > 0));
+        return Object.keys(nonEmpty).length === 0 ? notFound("no rule groups found") : ok(yaml(nonEmpty));
+      }
+      const groups = state.namespaces[parts[0]];
+      if (!groups || groups.length === 0) return notFound("no rule groups found");
+      if (parts.length === 1) return ok(yaml({ [parts[0]]: groups }));
+      const g = groups.find((x) => x.name === parts[1]);
+      return g ? ok(yaml(g)) : notFound("group does not exist");
+    }
+    if (req.method === "POST" && parts.length === 1) {
+      const doc = loadPrometheusYaml(req.body ?? "") as RawRuleGroup;
+      const groups = (state.namespaces[parts[0]] ??= []);
+      const i = groups.findIndex((x) => x.name === doc.name);
+      if (i >= 0) groups[i] = doc;
+      else groups.push(doc);
+      return { status: 202, text: "" };
+    }
+    if (req.method === "DELETE" && parts.length === 2) {
+      const groups = state.namespaces[parts[0]];
+      const i = groups ? groups.findIndex((x) => x.name === parts[1]) : -1;
+      if (i < 0) return notFound("group does not exist");
+      groups.splice(i, 1);
+      return { status: 202, text: "" };
+    }
+    return { status: 405, text: "method not allowed" };
+  };
+}
+
+/** An Alertmanager over `state`: a plain one's `/api/v2/status`, or Mimir's and Cortex's `/api/v1/alerts` and per-tenant status. */
+export function fakeAlertmanager(state: FakeAlertmanagerState, calls: string[] = []): FakeHandler {
+  const statusPath = state.kind === "alertmanager" ? "/api/v2/status" : "/alertmanager/api/v2/status";
+  return (req) => {
+    calls.push(`${req.method} ${req.path}`);
+    if (state.status !== undefined) return { status: state.status, text: "refused" };
+    const refused = tenantRefused(state.tenant, req);
+    if (refused) return refused;
+    if (req.path === statusPath && req.method === "GET") {
+      const original = state.kind === "alertmanager" ? state.original : state.uploaded?.alertmanager_config;
+      if (original === undefined) return notFound("the Alertmanager is not configured");
+      return json({
+        cluster: { name: "01FAKE", peers: [{ address: "10.0.0.1:9094", name: "01FAKE" }], status: state.cluster ?? "ready" },
+        config: { original },
+        uptime: "2026-10-06T08:00:00.000Z",
+        versionInfo: { branch: "HEAD", buildDate: "20260101-00:00:00", buildUser: "root@fake", goVersion: "go1.25", revision: "fake", version: state.version ?? "0.34.1" },
+      });
+    }
+    if (req.path === "/api/v1/alerts" && state.kind !== "alertmanager") {
+      if (req.method === "GET") {
+        if (!state.uploaded) return notFound("alertmanager storage object not found");
+        return ok(yaml({ template_files: state.uploaded.template_files ?? {}, alertmanager_config: state.uploaded.alertmanager_config }));
+      }
+      if (req.method === "POST") {
+        const doc = loadPrometheusYaml(req.body ?? "") as { alertmanager_config: string; template_files?: Record<string, string> };
+        state.uploaded = { alertmanager_config: doc.alertmanager_config, template_files: doc.template_files ?? {} };
+        return { status: 201, text: "" };
+      }
+    }
+    return notFound("404 page not found");
+  };
+}
+
+/** A handler as a {@link PromHttp}, with no headers (a tenant-checking fake then refuses; use {@link serveFake} for those). */
+export function fakeHttp(handler: FakeHandler, headers: Record<string, string> = {}): PromHttp {
+  return async (method, path, body) => {
+    const res = handler({ method, path, headers, body: body?.text });
+    return { status: res.status, text: res.text };
+  };
+}
+
+function readBody(req: IncomingMessage): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = "";
+    req.setEncoding("utf8");
+    req.on("data", (c: string) => (data += c));
+    req.on("end", () => resolve(data));
+    req.on("error", reject);
+  });
+}
+
+/** A handler behind a real HTTP server on 127.0.0.1, on a free port. `close()` stops it. */
+export async function serveFake(handler: FakeHandler): Promise<{ url: string; close: () => Promise<void> }> {
+  const server = createServer(async (req, res) => {
+    const body = await readBody(req);
+    const headers = Object.fromEntries(Object.entries(req.headers).map(([k, v]) => [k, Array.isArray(v) ? v.join(",") : v]));
+    const out = handler({ method: req.method ?? "GET", path: req.url ?? "/", headers, ...(body ? { body } : {}) });
+    res.writeHead(out.status, { "content-type": out.contentType ?? "text/plain" });
+    res.end(out.text);
+  });
+  await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+  const { port } = server.address() as AddressInfo;
+  return {
+    url: `http://127.0.0.1:${port}`,
+    close: () => new Promise<void>((resolve, reject) => server.close((err) => (err ? reject(err) : resolve()))),
+  };
+}

package/src/api/index.ts

@@ -0,0 +1,29 @@
+/**
+ * The ruler and Alertmanager API clients (#3371), as
+ * `@intentius/chant-lexicon-prometheus/api`.
+ *
+ * One transport for observe, live export and the ruler apply target
+ * (#3372): bind with {@link bindEndpoints} (or {@link bindRuler} /
+ * {@link bindAlertmanager}), then read and write through {@link RulerApi}
+ * and {@link AlertmanagerApi}. The ownership boundary is
+ * {@link declaredNamespaces}: nothing outside it is read for import, and an
+ * apply must not write or delete outside it.
+ */
+
+export { PromApiError, PromClient, promHttp, statusVerdict, type PromAuth, type PromHttp, type PromResponse, type PromTarget, type StatusVerdict } from "./client";
+export { RulerApi, type EvaluatedGroup, type EvaluatedRule, type RawRuleGroup } from "./ruler";
+export { AlertmanagerApi, type AlertmanagerHealth, type LiveAlertmanagerConfig } from "./alertmanager";
+export { evaluatedToRuleGroup, groupHealth, type GroupHealth } from "./evaluated";
+export { bindAlertmanager, bindEndpoints, bindRuler, classifyPromFailure, PromBindingError, type BindOptions, type BoundEndpoints } from "./bind";
+export {
+  ALERTMANAGER_KINDS,
+  RULER_KINDS,
+  declaredNamespaces,
+  namespaceOfGroup,
+  resolveAlertmanagerTarget,
+  resolveRulerTarget,
+  type AlertmanagerKind,
+  type AlertmanagerTarget,
+  type RulerKind,
+  type RulerTarget,
+} from "../config";