@intentius/chant-lexicon-grafana 0.97.0 → 0.99.0

package/src/api/bind.ts

@@ -0,0 +1,58 @@
+/**
+ * Binding a client for one environment: the config lookup, the target, the
+ * transport. Shared by observe, export and (#2948) apply, so all three read
+ * and write the same Grafana.
+ */
+
+import type { ChantConfig } from "@intentius/chant/config";
+import type { UnobservedReason } from "@intentius/chant/observation";
+import { GrafanaApiError, GrafanaClient, grafanaHttp, type GrafanaHttp } from "./client";
+import { isUnresolvedTarget, resolveGrafanaTarget, type UnresolvedTarget } from "../config";
+
+/** What callers may inject: tests pass `http` (and usually `config`), 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, "grafana">;
+  cwd?: string;
+  env?: Record<string, string | undefined>;
+  /** Transport override. The target is still resolved, so a test exercises the binding too. */
+  http?: GrafanaHttp;
+}
+
+/** A target that could not be resolved, thrown by {@link bindGrafana} and classified by {@link classifyGrafanaFailure}. */
+export class GrafanaBindingError extends Error {
+  constructor(readonly unresolved: UnresolvedTarget) {
+    super(unresolved.detail);
+    this.name = "GrafanaBindingError";
+  }
+}
+
+async function loadConfig(cwd: string): Promise<Pick<ChantConfig, "grafana"> | undefined> {
+  try {
+    const { loadChantConfig } = await import("@intentius/chant/config");
+    return (await loadChantConfig(cwd)).config;
+  } catch {
+    // No project config (an ad-hoc export): the environment variables still bind.
+    return undefined;
+  }
+}
+
+/** Resolve the environment's target and return a client for it. Throws {@link GrafanaBindingError} when there is none. */
+export async function bindGrafana(options: BindOptions = {}): Promise<GrafanaClient> {
+  const config = options.config ?? (await loadConfig(options.cwd ?? process.cwd()));
+  const target = resolveGrafanaTarget({ environment: options.environment, config, env: options.env });
+  if (isUnresolvedTarget(target)) throw new GrafanaBindingError(target);
+  return new GrafanaClient(options.http ?? grafanaHttp(target), target);
+}
+
+/** What a failed bind or read means, in the observation vocabulary. */
+export function classifyGrafanaFailure(err: unknown): { reason: UnobservedReason; detail: string } {
+  if (err instanceof GrafanaBindingError) return { reason: err.unresolved.reason, detail: err.unresolved.detail };
+  if (err instanceof GrafanaApiError) {
+    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,148 @@
+/**
+ * The Grafana HTTP transport (#2946): one client for observe, export and,
+ * later, the API applier (#2948), so all three reach the same instance with
+ * the same credentials.
+ *
+ * `GrafanaHttp` is the seam. The default is `fetch` against a resolved
+ * target (./target.ts); a test hands in a function that answers by path, so
+ * nothing needs a module mock.
+ *
+ * Status mapping is in one place ({@link statusVerdict}): a 404 is the only
+ * answer that means "not there", 401/403 mean the credentials were refused,
+ * and anything else that is not a 2xx is a failed read. A reader that turned
+ * a 500 or a refused token into "absent" would have `chant lifecycle plan`
+ * propose creating a dashboard that is running.
+ */
+
+/** How the client authenticates. A service account token is the usual form; basic auth suits a local instance. */
+export type GrafanaAuth = { readonly token: string } | { readonly user: string; readonly password: string };
+
+/** A resolved Grafana instance: where, as whom, which organisation, and where that came from. */
+export interface GrafanaTarget {
+  /** Base URL, without a trailing slash: `https://grafana.example.com`. */
+  readonly url: string;
+  readonly auth?: GrafanaAuth;
+  /** Organisation id; 1 when not set. Selects the `X-Grafana-Org-Id` header and the API namespace. */
+  readonly orgId?: number;
+  /**
+   * The `dashboard.grafana.app` namespace. Defaults to `default` for org 1
+   * and `org-<id>` otherwise; Grafana Cloud stacks use `stacks-<id>`.
+   */
+  readonly namespace?: string;
+  /** Where the binding came from, in the project's vocabulary: `grafana.profiles.prod`, `env GRAFANA_URL`. */
+  readonly source: string;
+}
+
+export interface GrafanaResponse {
+  readonly status: number;
+  /** The parsed body, or undefined when it was empty or not JSON. */
+  readonly json: unknown;
+}
+
+/** One request. `path` starts with `/` and is relative to the target's URL. */
+export type GrafanaHttp = (method: string, path: string, body?: unknown) => Promise<GrafanaResponse>;
+
+/** The API namespace for a target (see {@link GrafanaTarget.namespace}). */
+export function namespaceOf(target: Pick<GrafanaTarget, "orgId" | "namespace">): string {
+  if (target.namespace) return target.namespace;
+  const org = target.orgId ?? 1;
+  return org === 1 ? "default" : `org-${org}`;
+}
+
+function authHeader(auth: GrafanaAuth | 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, JSON in and out. */
+export function grafanaHttp(target: GrafanaTarget, fetchImpl: typeof fetch = fetch): GrafanaHttp {
+  const base = target.url.replace(/\/+$/, "");
+  const headers: Record<string, string> = {
+    accept: "application/json",
+    ...authHeader(target.auth),
+    ...(target.orgId !== undefined ? { "x-grafana-org-id": String(target.orgId) } : {}),
+  };
+  return async (method, path, body) => {
+    const res = await fetchImpl(`${base}${path}`, {
+      method,
+      headers: body === undefined ? headers : { ...headers, "content-type": "application/json" },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+    });
+    const text = await res.text();
+    let json: unknown;
+    if (text !== "") {
+      try {
+        json = JSON.parse(text);
+      } catch {
+        json = undefined;
+      }
+    }
+    return { status: res.status, json };
+  };
+}
+
+/** 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 GrafanaApiError extends Error {
+  readonly verdict: StatusVerdict;
+  constructor(
+    readonly status: number,
+    readonly method: string,
+    readonly path: string,
+    body: unknown,
+  ) {
+    const message = body && typeof body === "object" && typeof (body as { message?: unknown }).message === "string" ? (body as { message: string }).message : "";
+    super(`${method} ${path} returned ${status}${message ? `: ${message}` : ""}`);
+    this.name = "GrafanaApiError";
+    this.verdict = statusVerdict(status);
+  }
+}
+
+/**
+ * A bound client: the transport, the target it reaches, and per-client
+ * caches (the API version a server serves, folder titles) so N reads do not
+ * repeat the same lookup.
+ */
+export class GrafanaClient {
+  private readonly memo = new Map<string, Promise<unknown>>();
+
+  constructor(
+    readonly http: GrafanaHttp,
+    readonly target: GrafanaTarget,
+  ) {}
+
+  get namespace(): string {
+    return namespaceOf(this.target);
+  }
+
+  /** GET, returning the body; undefined on 404; throws {@link GrafanaApiError} on any other non-2xx. */
+  async get<T = unknown>(path: string): Promise<T | undefined> {
+    const res = await this.http("GET", path);
+    const verdict = statusVerdict(res.status);
+    if (verdict === "ok") return res.json as T;
+    if (verdict === "not-found") return undefined;
+    throw new GrafanaApiError(res.status, "GET", path, res.json);
+  }
+
+  /** Run `fn` once per key for this client's lifetime; concurrent callers share the promise. */
+  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);
+      // A failed lookup is not cached: the next caller asks again.
+      p.catch(() => this.memo.delete(key));
+    }
+    return p;
+  }
+}

package/src/api/converge.ts

@@ -0,0 +1,63 @@
+/**
+ * Whether what Grafana holds already is what the applier would write
+ * (#2948), so a re-apply reports `unchanged` and writes nothing.
+ *
+ * Grafana does not answer this itself: a `PUT` of identical content still
+ * bumps `generation` and `resourceVersion` (measured on 12.4.11 and 13.2.2),
+ * so a no-op cannot be told from an update after the fact. And the stored
+ * dashboard is not the one sent: Grafana fills in defaults
+ * (`fiscalYearStartMonth: 0`, `links: []`, `timepicker: {}`, ...), adds the
+ * built-in annotation, drops `null`s and empty `options`, and may migrate
+ * `schemaVersion`.
+ *
+ * So the test is one-sided: every value the applier would send must be in
+ * the live object, equal, and anything Grafana added on top is ignored. An
+ * array must match element for element, since a panel added in the UI is a
+ * change. The noise is the same list the drift hooks carry (#2946):
+ *
+ * - `null` and empty objects sent are satisfied by an absent key;
+ * - the built-in "Annotations & Alerts" annotation is ignored on both sides;
+ * - `id`, `version` and `uid` at the top level are identity, not content, and
+ *   `schemaVersion` is Grafana's to migrate.
+ */
+
+type Json = Record<string, unknown>;
+
+function isObject(v: unknown): v is Json {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Top-level dashboard keys that are identity or Grafana-managed, never content. */
+export const IDENTITY_KEYS: readonly string[] = ["id", "uid", "version", "schemaVersion"];
+
+function isBuiltInAnnotation(v: unknown): boolean {
+  return isObject(v) && (v.builtIn === 1 || v.builtIn === true);
+}
+
+function covers(want: unknown, live: unknown, path: string[]): boolean {
+  if (want === null || want === undefined) return live === null || live === undefined;
+  if (Array.isArray(want)) {
+    if (!Array.isArray(live)) return want.length === 0 && live === undefined;
+    const annotations = path[path.length - 1] === "list" && path[path.length - 2] === "annotations";
+    const w = annotations ? want.filter((a) => !isBuiltInAnnotation(a)) : want;
+    const l = annotations ? live.filter((a) => !isBuiltInAnnotation(a)) : live;
+    return w.length === l.length && w.every((x, i) => covers(x, l[i], [...path, String(i)]));
+  }
+  if (isObject(want)) {
+    if (live === undefined || live === null) return Object.values(want).every((v) => covers(v, undefined, path));
+    if (!isObject(live)) return false;
+    return Object.entries(want).every(([k, v]) => covers(v, live[k], [...path, k]));
+  }
+  return want === live;
+}
+
+/**
+ * True when `live` already holds everything in `want`. For a dashboard,
+ * the top-level identity keys ({@link IDENTITY_KEYS}) are left out of the
+ * comparison.
+ */
+export function converged(want: unknown, live: unknown, opts: { dashboard?: boolean } = {}): boolean {
+  if (!opts.dashboard || !isObject(want)) return covers(want, live, []);
+  const content = Object.fromEntries(Object.entries(want).filter(([k]) => !IDENTITY_KEYS.includes(k)));
+  return covers(content, live, []);
+}

package/src/api/dashboards.ts

@@ -0,0 +1,247 @@
+/**
+ * Reading dashboards (#2946).
+ *
+ * Grafana 12 and 13 serve dashboards as Kubernetes-style resources under
+ * `/apis/dashboard.grafana.app/<version>/namespaces/<ns>/dashboards/<uid>`:
+ * the classic dashboard JSON in `spec`, and who manages it in
+ * `metadata.annotations` and `metadata.labels` (./../ownership.ts). The
+ * version is discovered once per client from the API group, preferring the
+ * newest classic (v1-family) version the server serves: `v1` on 13.x,
+ * `v1beta1` on 12.x. A server without the group (Grafana 11) is read over
+ * `GET /api/dashboards/uid/<uid>`, which has the same JSON and no metadata
+ * channel.
+ *
+ * ## The version branch is one place
+ *
+ * {@link classicDashboardOf} decides how a stored dashboard is read as
+ * classic JSON. Everything downstream (observe, deep observe, export) only
+ * ever sees its answer. A dashboard Grafana stores as v2 (the layout-and-
+ * elements schema) is not read through Grafana's own v2-to-v1 conversion,
+ * which drops what v1 cannot hold with nothing to show it (the importer
+ * refuses that read too, `lossyV1Read`). Instead {@link readDashboard} and
+ * {@link listDashboards} read it again at the newest v2 version the server
+ * serves (`v2` on 13.x, `v2beta1` on 12.x), and `classicDashboardOf`
+ * converts that with the importer's v2 reader (./../import/v2.ts), which
+ * names everything v2 holds that the classic model cannot (#2947). Only a
+ * v2-stored dashboard the server cannot serve at v2, or whose conversion
+ * failed, is reported as not readable.
+ */
+
+import { looksLikeV2Dashboard } from "../detect";
+import { lossyV1Read, readV2Dashboard } from "../import/v2";
+import type { GrafanaClient } from "./client";
+
+type Json = Record<string, unknown>;
+
+function isObject(v: unknown): v is Json {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+function stringMap(v: unknown): Record<string, string> {
+  if (!isObject(v)) return {};
+  return Object.fromEntries(Object.entries(v).filter(([, x]) => typeof x === "string")) as Record<string, string>;
+}
+
+export const DASHBOARD_GROUP = "dashboard.grafana.app";
+
+/** Classic-schema versions of the dashboard API, newest first. */
+export const CLASSIC_DASHBOARD_VERSIONS: readonly string[] = ["v1", "v1beta1", "v0alpha1"];
+
+/** v2-schema versions of the dashboard API the v2 reader understands, newest first. */
+export const V2_DASHBOARD_VERSIONS: readonly string[] = ["v2", "v2beta1"];
+
+/**
+ * How this server serves dashboards: the classic version it is read at,
+ * and the v2 version a dashboard stored as v2 is read at instead (#2947).
+ */
+export type DashboardApi = { readonly kind: "apis"; readonly version: string; readonly v2Version?: string } | { readonly kind: "legacy" };
+
+/** The dashboard API the server behind `client` serves, discovered once per client. */
+export function dashboardApi(client: GrafanaClient): Promise<DashboardApi> {
+  return client.once("dashboard-api", async () => {
+    const group = await client.get<{ versions?: Array<{ version?: string }> }>(`/apis/${DASHBOARD_GROUP}`);
+    const served = new Set((group?.versions ?? []).map((v) => v.version).filter((v): v is string => typeof v === "string"));
+    const version = CLASSIC_DASHBOARD_VERSIONS.find((v) => served.has(v));
+    const v2Version = V2_DASHBOARD_VERSIONS.find((v) => served.has(v));
+    return version ? { kind: "apis", version, ...(v2Version ? { v2Version } : {}) } : { kind: "legacy" };
+  });
+}
+
+/** One dashboard as Grafana holds it. */
+export interface LiveDashboard {
+  readonly uid: string;
+  /**
+   * The stored resource as it came back: a `dashboard.grafana.app` resource
+   * (`{ metadata, spec, status }`) or, on the legacy API, `{ dashboard, meta }`.
+   * Read it through {@link classicDashboardOf}.
+   */
+  readonly raw: Json;
+  readonly via: "apis" | "legacy";
+  /** `metadata.labels`. Empty on the legacy API, which has no labels. */
+  readonly labels: Readonly<Record<string, string>>;
+  /** `metadata.annotations`. Empty on the legacy API. */
+  readonly annotations: Readonly<Record<string, string>>;
+  /** The folder's uid, when it is in one. */
+  readonly folderUid?: string;
+  /** The folder's title, when the read returned it (the legacy API does). */
+  readonly folderTitle?: string;
+  /** The request path it was read from. */
+  readonly address: string;
+}
+
+/** A dashboard read: there, not there (404), or there but not readable as classic JSON. */
+export type DashboardRead =
+  | { readonly present: LiveDashboard }
+  | { readonly absent: true; readonly address: string };
+
+/** The request path for one dashboard on this API (at `version` instead of the classic one, when given). */
+export function dashboardPath(api: DashboardApi, namespace: string, uid: string, version?: string): string {
+  const id = encodeURIComponent(uid);
+  return api.kind === "apis"
+    ? `/apis/${DASHBOARD_GROUP}/${version ?? api.version}/namespaces/${encodeURIComponent(namespace)}/dashboards/${id}`
+    : `/api/dashboards/uid/${id}`;
+}
+
+/**
+ * A classic read of a dashboard Grafana stores as v2 is a lossy
+ * down-conversion: read it again at v2, where it is whole. Anything else,
+ * and a v2-stored dashboard on a server with no v2 version the reader knows,
+ * comes back as it was (and `classicDashboardOf` says why it cannot be read).
+ */
+async function atStoredVersion(client: GrafanaClient, api: DashboardApi, live: LiveDashboard): Promise<LiveDashboard> {
+  if (api.kind !== "apis" || !api.v2Version) return live;
+  const lossy = lossyV1Read(live.raw);
+  if (!lossy || lossy.failed || !lossy.storedVersion.startsWith("v2")) return live;
+  const address = dashboardPath(api, client.namespace, live.uid, api.v2Version);
+  const body = await client.get<Json>(address);
+  return body === undefined ? live : fromResource(body, address);
+}
+
+function fromResource(resource: Json, address: string): LiveDashboard {
+  const metadata = isObject(resource.metadata) ? resource.metadata : {};
+  const annotations = stringMap(metadata.annotations);
+  const folderUid = annotations["grafana.app/folder"];
+  return {
+    uid: typeof metadata.name === "string" ? metadata.name : "",
+    raw: resource,
+    via: "apis",
+    labels: stringMap(metadata.labels),
+    annotations,
+    ...(folderUid ? { folderUid } : {}),
+    address,
+  };
+}
+
+function fromLegacy(body: Json, address: string): LiveDashboard {
+  const dashboard = isObject(body.dashboard) ? body.dashboard : {};
+  const meta = isObject(body.meta) ? body.meta : {};
+  return {
+    uid: typeof dashboard.uid === "string" ? dashboard.uid : "",
+    raw: body,
+    via: "legacy",
+    labels: {},
+    annotations: {},
+    ...(typeof meta.folderUid === "string" && meta.folderUid !== "" ? { folderUid: meta.folderUid } : {}),
+    ...(typeof meta.folderTitle === "string" && meta.folderTitle !== "" && meta.folderUid ? { folderTitle: meta.folderTitle } : {}),
+    address,
+  };
+}
+
+/** Read one dashboard by uid. Throws `GrafanaApiError` for anything but a 2xx or a 404. */
+export async function readDashboard(client: GrafanaClient, uid: string): Promise<DashboardRead> {
+  const api = await dashboardApi(client);
+  const address = dashboardPath(api, client.namespace, uid);
+  const body = await client.get<Json>(address);
+  if (body === undefined) return { absent: true, address };
+  if (api.kind !== "apis") return { present: fromLegacy(body, address) };
+  return { present: await atStoredVersion(client, api, fromResource(body, address)) };
+}
+
+/** Every dashboard in the organisation, paged. */
+export async function listDashboards(client: GrafanaClient): Promise<LiveDashboard[]> {
+  const api = await dashboardApi(client);
+  const out: LiveDashboard[] = [];
+  if (api.kind === "apis") {
+    const base = `/apis/${DASHBOARD_GROUP}/${api.version}/namespaces/${encodeURIComponent(client.namespace)}/dashboards`;
+    let next: string | undefined;
+    do {
+      const page = await client.get<{ items?: unknown[]; metadata?: { continue?: string } }>(
+        `${base}?limit=500${next ? `&continue=${encodeURIComponent(next)}` : ""}`,
+      );
+      for (const item of page?.items ?? []) {
+        if (!isObject(item)) continue;
+        const d = fromResource(item, `${base}/${encodeURIComponent(String((item.metadata as Json | undefined)?.name ?? ""))}`);
+        if (d.uid) out.push(await atStoredVersion(client, api, d));
+      }
+      next = page?.metadata?.continue || undefined;
+    } while (next);
+    return out;
+  }
+  for (let page = 1; ; page++) {
+    const hits = (await client.get<Array<{ uid?: string }>>(`/api/search?type=dash-db&limit=1000&page=${page}`)) ?? [];
+    for (const hit of hits) {
+      if (typeof hit.uid !== "string") continue;
+      const read = await readDashboard(client, hit.uid);
+      if ("present" in read) out.push(read.present);
+    }
+    if (hits.length < 1000) break;
+  }
+  return out;
+}
+
+/** A v2 dashboard (a resource, or a bare v2 spec) as classic JSON with the uid, and what the classic form cannot hold. */
+function fromV2(v2: Json, uid: string): { json: Json; warnings: string[] } | { unsupported: string } {
+  try {
+    const { dashboard, warnings } = readV2Dashboard(v2);
+    return { json: { ...dashboard, uid: uid || dashboard.uid }, warnings };
+  } catch (err) {
+    return { unsupported: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/**
+ * The stored dashboard as classic JSON, with its uid, or why it cannot be
+ * read as one. The only place the dashboard schema version branches. A v2
+ * dashboard is converted by the importer's v2 reader; `warnings` then names
+ * what v2 holds that the classic JSON does not (tabs, auto grids,
+ * conditional rendering), and is absent for a classic dashboard.
+ */
+export function classicDashboardOf(dashboard: LiveDashboard): { json: Json; warnings?: string[] } | { unsupported: string } {
+  if (dashboard.via === "legacy") {
+    const json = isObject(dashboard.raw.dashboard) ? dashboard.raw.dashboard : {};
+    if (looksLikeV2Dashboard(json)) return fromV2(json, dashboard.uid);
+    return { json };
+  }
+  if (looksLikeV2Dashboard(dashboard.raw)) return fromV2(dashboard.raw, dashboard.uid);
+  // The importer's own test for a v1 read of a v2-stored dashboard, so import
+  // and observe refuse the same lossy down-conversion. readDashboard has
+  // already tried the v2 read; this is a server that could not give it.
+  const lossy = lossyV1Read(dashboard.raw);
+  if (lossy?.failed) return { unsupported: `Grafana could not convert it from ${lossy.storedVersion || "the version it is stored at"} to the classic schema` };
+  if (lossy) {
+    return {
+      unsupported:
+        `it is stored as a ${lossy.storedVersion} dashboard and the server did not serve it at ${V2_DASHBOARD_VERSIONS.join(" or ")}; ` +
+        `its ${lossy.apiVersion} copy is a lossy down-conversion, so it is not read`,
+    };
+  }
+  const spec = isObject(dashboard.raw.spec) ? dashboard.raw.spec : undefined;
+  if (!spec) return { unsupported: "the resource has no spec" };
+  if (looksLikeV2Dashboard(spec)) return fromV2(spec, dashboard.uid);
+  // The resource's name is the dashboard's uid; the spec does not repeat it.
+  return { json: { ...spec, uid: dashboard.uid } };
+}
+
+/**
+ * The title of the folder a dashboard is in, or undefined for the General
+ * folder. One `GET /api/folders/<uid>` per folder per client.
+ */
+export async function folderTitleOf(client: GrafanaClient, dashboard: LiveDashboard): Promise<string | undefined> {
+  if (!dashboard.folderUid) return undefined;
+  if (dashboard.folderTitle) return dashboard.folderTitle;
+  const uid = dashboard.folderUid;
+  return client.once(`folder:${uid}`, async () => {
+    const folder = await client.get<{ title?: string }>(`/api/folders/${encodeURIComponent(uid)}`);
+    return typeof folder?.title === "string" ? folder.title : undefined;
+  });
+}

package/src/api/datasources.ts

@@ -0,0 +1,33 @@
+/**
+ * Reading datasources (#2946), over `GET /api/datasources/uid/<uid>` and
+ * `GET /api/datasources`. Grafana 12.4 and 13.2 serve no general
+ * datasource resource under `/apis`, so this is the one datasource API both
+ * have, and it carries no labels or annotations: a datasource's ownership
+ * cannot be read (see ../ownership.ts).
+ *
+ * The API never returns secret values. `secureJsonFields` says which
+ * secrets are set, and that is all this reads of them.
+ */
+
+import type { GrafanaClient } from "./client";
+
+type Json = Record<string, unknown>;
+
+export type DatasourceRead = { readonly present: Json; readonly address: string } | { readonly absent: true; readonly address: string };
+
+export function datasourcePath(uid: string): string {
+  return `/api/datasources/uid/${encodeURIComponent(uid)}`;
+}
+
+/** Read one datasource by uid. Throws `GrafanaApiError` for anything but a 2xx or a 404. */
+export async function readDatasource(client: GrafanaClient, uid: string): Promise<DatasourceRead> {
+  const address = datasourcePath(uid);
+  const body = await client.get<Json>(address);
+  return body === undefined ? { absent: true, address } : { present: body, address };
+}
+
+/** Every datasource in the organisation. */
+export async function listDatasources(client: GrafanaClient): Promise<Json[]> {
+  const list = await client.get<unknown[]>("/api/datasources");
+  return (list ?? []).filter((d): d is Json => typeof d === "object" && d !== null && !Array.isArray(d));
+}