@loadmap/providers 0.0.0-stage → 0.32.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaime Rojas
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @loadmap/providers
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reads measured data from the metrics stores a team already runs into a **snapshot**: the file a loadmap model reads
+(`fromSnapshot` in `@loadmap/core/measure`). Nothing in a definition or a shared link fetches anything; a pull is an
+explicit action, and the address and the credentials come from the environment, never from the text.
+
+`loadmap pull x.loadmap` (in `@loadmap/cli`) is the usual way in. In code:
+
+```ts
+import { compile } from '@loadmap/dsl'
+import { providersFromEnv, pull } from '@loadmap/providers'
+
+const { measures } = compile(source)
+const snapshot = await pull(measures, {
+  from: '2026-11-01T00:00:00Z',
+  to: '2026-11-08T00:00:00Z',
+  step: 300,
+  fetched: new Date().toISOString(),
+  providers: providersFromEnv(process.env), // LOADMAP_PROMETHEUS_URL, LOADMAP_ELASTICSEARCH_URL, …
+})
+```
+
+A provider is one adapter, `{ id, read({ query, from, to, step }) }`, that answers with the points or with why not:
+an error is data, so one failing query leaves that measurement missing and the model on the definition's own value.
+`prometheus({ url, token })` reads `/api/v1/query_range`; a query must give one series. `elasticsearch({ url, apiKey
+})` reads an index as a date histogram at the step (documents per second or per step, or the avg, sum, min or max of
+a field), and answers OpenSearch's clusters too. A user and password written in an address go in the header, and no
+error repeats the address or a credential. MIT.

package/dist/index.d.ts

@@ -0,0 +1,96 @@
+import { Snapshot, Stat, TimeSeries } from "@loadmap/core";
+/** What a provider is asked: a query over a window, at a step. Instants are ISO 8601, the step in seconds. */
+interface ProviderQuery {
+  query: string;
+  from: string;
+  to: string;
+  step: number;
+}
+/** A provider answers with the points, or says why not: an error is data, never a throw. */
+type ProviderResult = {
+  points: TimeSeries;
+} | {
+  error: string;
+};
+/** One metrics store: a query in, normalized points out. */
+interface Provider {
+  /** "prometheus": the name a metric's block gives it. */
+  id: string;
+  read(q: ProviderQuery): Promise<ProviderResult>;
+}
+/** A measurement to read: a definition's `measure` with its query filled in (`compile(…).measures`). */
+interface PullRequest {
+  id: string;
+  metric?: string;
+  label?: string;
+  provider: string;
+  query: string;
+  stat?: Stat;
+  min?: number;
+  unit: string;
+}
+interface PullOptions {
+  /** The window, ISO 8601: every measurement reads the same one. */
+  from: string;
+  to: string;
+  /** Seconds between points. */
+  step: number;
+  /** When the pull ran, ISO 8601: the snapshot's date. */
+  fetched: string;
+  providers: Readonly<Partial<Record<string, Provider>>>;
+}
+/**
+ * Reads every measurement and writes the snapshot: the value over the window by its stat (mean by default), the
+ * points, and where they came from. What fails is missing, with why; a window with fewer samples than its `min`
+ * counts as missing too, and the model then uses the definition's own value.
+ */
+export declare function pull(requests: readonly PullRequest[], o: PullOptions): Promise<Snapshot>;
+interface ElasticsearchOptions {
+  /** The cluster's address: "https://search.example:9200", or a path behind a proxy. */
+  url: string;
+  /** Sent as `ApiKey …`. */
+  apiKey?: string;
+  /** Basic auth, when there is no API key. */
+  user?: string;
+  password?: string;
+  /** For tests and proxies; the global `fetch` by default. */
+  fetch?: typeof fetch;
+}
+/**
+ * Reads an index over a range as a date histogram at the step: documents per second (`rate`), per step (`count`),
+ * or the avg, sum, min or max of a field. OpenSearch answers the same request. A window where no document matches is
+ * an error, not a series of zeros: a wrong query must not read as no traffic. Errors never carry the address or the
+ * credentials.
+ */
+export declare function elasticsearch(o: ElasticsearchOptions): Provider;
+interface PrometheusOptions {
+  /** The server's address: "https://prometheus.example:9090", or a path behind a proxy. */
+  url: string;
+  /** Sent as a bearer token. */
+  token?: string;
+  /** Basic auth, when there is no token. */
+  user?: string;
+  password?: string;
+  /** For tests and proxies; the global `fetch` by default. */
+  fetch?: typeof fetch;
+}
+/**
+ * Reads a PromQL query over a range (`/api/v1/query_range`). The query must give one series: several are an error
+ * that says to sum them. Points Prometheus writes as NaN or ±Inf are left out. Errors never carry the address or the
+ * credentials, so a snapshot or a log can be shared.
+ */
+export declare function prometheus(o: PrometheusOptions): Provider;
+/**
+ * The providers the environment configures: `LOADMAP_PROMETHEUS_URL`, with `LOADMAP_PROMETHEUS_TOKEN` or a user and
+ * password; `LOADMAP_ELASTICSEARCH_URL`, with `LOADMAP_ELASTICSEARCH_API_KEY` or a user and password. A definition
+ * never names an address or a credential.
+ */
+export declare function providersFromEnv(env: Readonly<Record<string, string | undefined>>,
+/** `only`: the providers to build, so an address set for another one cannot fail this pull. */
+o?: {
+  fetch?: typeof fetch;
+  only?: readonly string[];
+}): Record<string, Provider>;
+/** What a provider needs to be configured, as a line to print. */
+export declare const PROVIDER_ENV: Readonly<Record<string, string>>;
+export type { ElasticsearchOptions, PrometheusOptions, Provider, ProviderQuery, ProviderResult, PullOptions, PullRequest };

package/dist/index.js

@@ -0,0 +1,292 @@
+import { parseSnapshot, summarize } from "@loadmap/core/measure";
+// src/http.ts
+/**
+* A provider's address, ready to ask: a user and password written in it move into the header (fetch refuses them in a
+* URL, and repeats the URL saying so). The text is never repeated in an error: it may hold a password.
+*/
+function endpoint(name, url, auth) {
+	let base;
+	try {
+		base = new URL(url.endsWith("/") ? url : `${url}/`);
+	} catch {
+		throw new Error(`loadmap: the ${name} address is not a URL`);
+	}
+	const user = auth.user ?? (base.username ? decodeURIComponent(base.username) : void 0);
+	const password = auth.password ?? decodeURIComponent(base.password);
+	base.username = "";
+	base.password = "";
+	const headers = { accept: "application/json" };
+	if (auth.header) headers.authorization = auth.header;
+	else if (user != null) headers.authorization = `Basic ${btoa(`${user}:${password}`)}`;
+	return {
+		base,
+		headers
+	};
+}
+/** Why a request did not reach the server: the network error's code, never its message, which may name the host. */
+function unreachable(name, err) {
+	const code = err?.cause?.code;
+	return { error: `${name} cannot be reached${typeof code === "string" ? ` (${code})` : ""}` };
+}
+// src/elasticsearch.ts
+/** What a metric's `elasticsearch` block asks, as `compile` writes it into the query. */
+/** What it counts or aggregates at each step: the values a metric's `agg` takes. */
+const AGGS = [
+	"rate",
+	"count",
+	"avg",
+	"sum",
+	"min",
+	"max"
+];
+/**
+* Reads an index over a range as a date histogram at the step: documents per second (`rate`), per step (`count`),
+* or the avg, sum, min or max of a field. OpenSearch answers the same request. A window where no document matches is
+* an error, not a series of zeros: a wrong query must not read as no traffic. Errors never carry the address or the
+* credentials.
+*/
+function elasticsearch(o) {
+	const get = o.fetch ?? fetch;
+	const { base, headers } = endpoint("Elasticsearch", o.url, {
+		...o.user != null && { user: o.user },
+		...o.password != null && { password: o.password },
+		...o.apiKey && { header: `ApiKey ${o.apiKey}` }
+	});
+	headers["content-type"] = "application/json";
+	return {
+		id: "elasticsearch",
+		async read(q) {
+			const spec = specOf(q.query);
+			if (!spec) return { error: "the query is not an Elasticsearch request loadmap wrote" };
+			if (spec.index.split(",").some((p) => !p || p === "." || p === ".." || /[\s/?#]/.test(p))) return { error: "the index is not a name or a pattern" };
+			const from = Date.parse(q.from);
+			const to = Date.parse(q.to);
+			if (!(to - from >= q.step * 1e3)) return { error: "the window is shorter than a step" };
+			const body = {
+				size: 0,
+				track_total_hits: false,
+				query: { bool: { filter: [{ range: { [spec.time]: {
+					gte: from,
+					lt: to,
+					format: "epoch_millis"
+				} } }, ...spec.query ? [spec.query] : []] } },
+				aggs: { t: {
+					date_histogram: {
+						field: spec.time,
+						fixed_interval: `${q.step}s`,
+						min_doc_count: 0,
+						offset: `${from / 1e3 % q.step}s`,
+						extended_bounds: {
+							min: from,
+							max: to - q.step * 1e3
+						}
+					},
+					...spec.field && { aggs: { v: { [spec.agg]: { field: spec.field } } } }
+				} }
+			};
+			const url = new URL(base);
+			url.pathname = `${base.pathname}${encodeURIComponent(spec.index).replace(/%2C/g, ",").replace(/%3A/g, ":")}/_search`;
+			let res;
+			try {
+				res = await get(url, {
+					method: "POST",
+					headers,
+					body: JSON.stringify(body)
+				});
+			} catch (err) {
+				return unreachable("Elasticsearch", err);
+			}
+			let r;
+			try {
+				r = await res.json();
+			} catch {
+				r = void 0;
+			}
+			if (!res.ok || !r || r.error) {
+				const e = r?.error;
+				const why = typeof e === "string" ? e : [e?.type, e?.reason].filter(Boolean).join(": ");
+				return { error: `Elasticsearch answered ${res.status}${why ? `: ${why}` : ""}` };
+			}
+			const failed = r._shards?.failed ?? 0;
+			if (failed) return { error: `${failed} of ${r._shards?.total ?? "?"} shards failed` };
+			if (r.timed_out) return { error: "the search timed out" };
+			const buckets = r.aggregations?.t?.buckets ?? [];
+			if (!buckets.some((b) => (b.doc_count ?? 0) > 0)) return { error: "no document matches the query in the window" };
+			const points = [];
+			for (const b of buckets) {
+				const n = b.doc_count ?? 0;
+				const v = spec.agg === "count" ? n : spec.agg === "rate" ? n / q.step : b.v?.value;
+				if (typeof b.key === "number" && typeof v === "number" && Number.isFinite(v)) points.push([Math.round(b.key / 1e3), v]);
+			}
+			return { points };
+		}
+	};
+}
+function specOf(text) {
+	let s;
+	try {
+		s = JSON.parse(text);
+	} catch {
+		return;
+	}
+	if (typeof s !== "object" || s === null) return void 0;
+	const { index, time, agg, field, query } = s;
+	if (typeof index !== "string" || typeof time !== "string" || typeof agg !== "string" || !AGGS.includes(agg)) return void 0;
+	if (field !== void 0 && typeof field !== "string") return void 0;
+	if (query !== void 0 && (typeof query !== "object" || query === null || Array.isArray(query))) return void 0;
+	return s;
+}
+// src/prometheus.ts
+/**
+* Reads a PromQL query over a range (`/api/v1/query_range`). The query must give one series: several are an error
+* that says to sum them. Points Prometheus writes as NaN or ±Inf are left out. Errors never carry the address or the
+* credentials, so a snapshot or a log can be shared.
+*/
+function prometheus(o) {
+	const get = o.fetch ?? fetch;
+	const { base, headers } = endpoint("Prometheus", o.url, {
+		...o.user != null && { user: o.user },
+		...o.password != null && { password: o.password },
+		...o.token && { header: `Bearer ${o.token}` }
+	});
+	return {
+		id: "prometheus",
+		async read(q) {
+			const url = new URL("api/v1/query_range", base);
+			url.search = new URLSearchParams({
+				query: q.query,
+				start: q.from,
+				end: q.to,
+				step: String(q.step)
+			}).toString();
+			let res;
+			try {
+				res = await get(url, { headers });
+			} catch (err) {
+				return unreachable("Prometheus", err);
+			}
+			let body;
+			try {
+				body = await res.json();
+			} catch {
+				body = void 0;
+			}
+			if (!res.ok || body?.status !== "success") {
+				const why = body?.error ? `: ${body.error}` : "";
+				return { error: `Prometheus answered ${res.status}${why}` };
+			}
+			const result = body.data?.result ?? [];
+			if (body.data?.resultType !== "matrix") return { error: `the query gave a ${body.data?.resultType}, not a range` };
+			if (!result.length) return { error: "the query returned no series" };
+			if (result.length > 1) return { error: `the query returned ${result.length} series: sum them into one` };
+			const points = [];
+			for (const [t, v] of result[0].values ?? []) {
+				const n = Number(v);
+				if (Number.isFinite(t) && Number.isFinite(n)) points.push([t, n]);
+			}
+			return { points };
+		}
+	};
+}
+// src/pull.ts
+/**
+* Reads every measurement and writes the snapshot: the value over the window by its stat (mean by default), the
+* points, and where they came from. What fails is missing, with why; a window with fewer samples than its `min`
+* counts as missing too, and the model then uses the definition's own value.
+*/
+async function pull(requests, o) {
+	const read = await Promise.all(requests.map(async (r) => {
+		const provider = Object.hasOwn(o.providers, r.provider) ? o.providers[r.provider] : void 0;
+		const result = provider ? await provider.read({
+			query: r.query,
+			from: o.from,
+			to: o.to,
+			step: o.step
+		}).catch((err) => ({ error: `${r.provider} failed (${err?.name ?? "error"})` })) : { error: `no ${r.provider} is configured` };
+		const points = "points" in result ? result.points : [];
+		const origin = {
+			provider: r.provider,
+			query: r.query,
+			...r.metric != null && { metric: r.metric },
+			from: o.from,
+			to: o.to,
+			step: o.step,
+			fetched: o.fetched,
+			samples: points.length,
+			...r.min != null && { min: r.min },
+			...r.stat != null && { stat: r.stat }
+		};
+		const label = r.label != null ? { label: r.label } : {};
+		if ("error" in result) return [r.id, {
+			...label,
+			unit: r.unit,
+			missing: result.error,
+			origin
+		}];
+		if (!points.length) return [r.id, {
+			...label,
+			unit: r.unit,
+			missing: "no samples in the window",
+			origin
+		}];
+		const value = summarize(points, r.stat ?? "mean");
+		return [r.id, {
+			...label,
+			unit: r.unit,
+			value,
+			series: points,
+			origin
+		}];
+	}));
+	return parseSnapshot({
+		format: "loadmap-snapshot",
+		version: 1,
+		fetched: o.fetched,
+		from: o.from,
+		to: o.to,
+		measurements: Object.fromEntries(read)
+	});
+}
+// src/index.ts
+/**
+* The providers the environment configures: `LOADMAP_PROMETHEUS_URL`, with `LOADMAP_PROMETHEUS_TOKEN` or a user and
+* password; `LOADMAP_ELASTICSEARCH_URL`, with `LOADMAP_ELASTICSEARCH_API_KEY` or a user and password. A definition
+* never names an address or a credential.
+*/
+function providersFromEnv(env, o = {}) {
+	const out = {};
+	const wanted = (id) => !o.only || o.only.includes(id);
+	const url = env.LOADMAP_PROMETHEUS_URL;
+	if (url && wanted("prometheus")) {
+		const p = {
+			url,
+			...o.fetch && { fetch: o.fetch }
+		};
+		if (env.LOADMAP_PROMETHEUS_TOKEN) p.token = env.LOADMAP_PROMETHEUS_TOKEN;
+		else if (env.LOADMAP_PROMETHEUS_USER) {
+			p.user = env.LOADMAP_PROMETHEUS_USER;
+			p.password = env.LOADMAP_PROMETHEUS_PASSWORD ?? "";
+		}
+		out.prometheus = prometheus(p);
+	}
+	const es = env.LOADMAP_ELASTICSEARCH_URL;
+	if (es && wanted("elasticsearch")) {
+		const e = {
+			url: es,
+			...o.fetch && { fetch: o.fetch }
+		};
+		if (env.LOADMAP_ELASTICSEARCH_API_KEY) e.apiKey = env.LOADMAP_ELASTICSEARCH_API_KEY;
+		else if (env.LOADMAP_ELASTICSEARCH_USER) {
+			e.user = env.LOADMAP_ELASTICSEARCH_USER;
+			e.password = env.LOADMAP_ELASTICSEARCH_PASSWORD ?? "";
+		}
+		out.elasticsearch = elasticsearch(e);
+	}
+	return out;
+}
+/** What a provider needs to be configured, as a line to print. */
+const PROVIDER_ENV = {
+	prometheus: "LOADMAP_PROMETHEUS_URL (and LOADMAP_PROMETHEUS_TOKEN, or LOADMAP_PROMETHEUS_USER and _PASSWORD)",
+	elasticsearch: "LOADMAP_ELASTICSEARCH_URL (and LOADMAP_ELASTICSEARCH_API_KEY, or LOADMAP_ELASTICSEARCH_USER and _PASSWORD)"
+};
+export { PROVIDER_ENV, elasticsearch, prometheus, providersFromEnv, pull };

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@loadmap/providers",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.32.0",
+  "description": "Data providers for loadmap: read measured data from Prometheus and Elasticsearch into a snapshot a model reads, on an explicit pull, with the address and the credentials from the environment.",
+  "keywords": [
+    "loadmap",
+    "prometheus",
+    "elasticsearch",
+    "opensearch",
+    "metrics",
+    "capacity-planning"
+  ],
+  "license": "MIT",
+  "author": "Jaime Rojas",
+  "homepage": "https://jaim3r0jas.github.io/loadmap/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jaim3r0jas/loadmap.git",
+    "directory": "packages/providers"
+  },
+  "bugs": "https://github.com/jaim3r0jas/loadmap/issues",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@loadmap/core": "0.32.0"
+  },
+  "peerDependencies": {},
+  "scripts": {
+    "build": "tsdown"
+  }
 }