nodefony 7.0.2 → 10.0.0-alpha.2

package/dist/node/syslog/drivers/ClusterFileLogDriver.js

@@ -0,0 +1,114 @@
+import { filterPdus } from "./filterPdus.js";
+import { scanJsonlTail } from "./FileLogDriver.js";
+import { join } from "node:path";
+import { readdir, stat } from "node:fs/promises";
+//#region src/syslog/drivers/ClusterFileLogDriver.ts
+/** Préfixe des fichiers JSONL par worker (cf `Kernel.initializeLog`). */
+const DEFAULT_PREFIX = "nodefony-";
+/** Suffixe des fichiers JSONL queryables. */
+const DEFAULT_SUFFIX = ".jsonl";
+/**
+* Plafond du NOMBRE de fichiers scannés par query (garde-fou anti-OOM). Le coût
+* mémoire d'une query = `maxFiles × maxScanBytes` au pire → borné explicitement.
+* Au-delà, on garde les `maxFiles` fichiers les plus RÉCENTS (mtime) — un cluster
+* sain a ≤ N workers (≈ cœurs), ce plafond ne mord qu'en cas de logs orphelins
+* (workers morts non nettoyés) ou d'un dossier pollué.
+*/
+const DEFAULT_MAX_FILES = 64;
+/**
+* Driver `cluster-file` du Log Backplane (LB.5) — **vue cluster unifiée** des
+* logs. En cluster, chaque worker écrit SON propre `nodefony-<pid>.jsonl` (fd par
+* worker = pas de lock d'inode partagé, cf LB.W) → une `query` sur le driver
+* `file` (LB.2) ne voit que le fichier du worker courant. Ce driver **globbe le
+* dossier** : il scanne tous les `nodefony-*.jsonl`, fusionne leurs Pdu et les
+* trie chronologiquement pour reconstituer le flux de logs de TOUT le cluster.
+*
+* La `query` est un chemin **FROID** (admin/debug), `async`, **JAMAIS** dans le
+* pipeline requête. Anti-OOM à deux niveaux : `maxScanBytes` borne la lecture par
+* fichier (à la queue, les logs récents) et `maxFiles` borne le nombre de fichiers
+* (les plus récents par mtime si dépassement). Chaque fichier est réhydraté par
+* la brique partagée {@link scanJsonlTail} (même format/robustesse que le driver
+* `file`), puis le filtrage final délègue à {@link filterPdus} — une logique, N
+* façades.
+*
+* **Tri inter-worker** : l'`uid` d'un Pdu est un compteur monotone PAR PROCESS →
+* il N'EST PAS comparable entre workers (chaque process repart de zéro). La fusion
+* trie donc par `timeStamp` (epoch ms, horloge partagée), puis départage par `pid`
+* (groupe stable par worker) et enfin par `uid` (chronologie exacte INTRA-worker,
+* y compris à `timeStamp` égal). À `timeStamp` égal entre deux workers, l'ordre
+* relatif est indéterminable (pas de séquence globale) mais reste **stable**.
+*
+* @param options - dossier + motif des fichiers + plafonds anti-OOM.
+* @returns un `ILogDriver` `cluster-file` queryable (Node-only).
+*/
+function createClusterFileLogDriver(options) {
+	const dir = options.dir;
+	const prefix = options.prefix ?? DEFAULT_PREFIX;
+	const suffix = options.suffix ?? DEFAULT_SUFFIX;
+	const maxScanBytes = options.maxScanBytes ?? 8388608;
+	const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+	return {
+		name: "cluster-file",
+		capabilities: {
+			write: true,
+			query: true,
+			stream: false
+		},
+		query: async (criteria) => {
+			const files = await listLogFiles(dir, prefix, suffix, maxFiles);
+			if (files.length === 0) return {
+				rows: [],
+				total: 0,
+				truncated: false
+			};
+			const perFile = await Promise.all(files.map((f) => scanJsonlTail(f, maxScanBytes)));
+			const merged = [];
+			for (const records of perFile) for (const rec of records) merged.push(rec);
+			merged.sort(byChrono);
+			return filterPdus(merged, criteria);
+		}
+	};
+}
+/**
+* Liste les fichiers de logs du dossier qui matchent `prefix`/`suffix`, bornée à
+* `maxFiles` (les plus récents par mtime si dépassement). Dossier absent/illisible
+* → tableau vide (un viewer ne crashe jamais).
+*/
+async function listLogFiles(dir, prefix, suffix, maxFiles) {
+	let names;
+	try {
+		names = await readdir(dir);
+	} catch {
+		return [];
+	}
+	const matches = names.filter((n) => n.startsWith(prefix) && n.endsWith(suffix));
+	if (matches.length <= maxFiles) return matches.map((n) => join(dir, n));
+	const withMtime = await Promise.all(matches.map(async (n) => {
+		const full = join(dir, n);
+		try {
+			return {
+				full,
+				mtime: (await stat(full)).mtimeMs
+			};
+		} catch {
+			return {
+				full,
+				mtime: 0
+			};
+		}
+	}));
+	withMtime.sort((a, b) => b.mtime - a.mtime);
+	return withMtime.slice(0, maxFiles).map((e) => e.full);
+}
+/**
+* Comparateur chronologique inter-worker (ordre ANCIEN → RÉCENT). `timeStamp`
+* (epoch ms partagé) prime ; à égalité, `pid` groupe par worker puis `uid` rétablit
+* la chronologie exacte intra-worker (compteur monotone par process).
+*/
+function byChrono(a, b) {
+	if (a.timeStamp !== b.timeStamp) return a.timeStamp - b.timeStamp;
+	if (a.pid !== b.pid) return a.pid - b.pid;
+	return a.uid - b.uid;
+}
+//#endregion
+export { createClusterFileLogDriver };

package/dist/node/syslog/drivers/FileLogDriver.js

@@ -0,0 +1,127 @@
+import { filterPdus } from "./filterPdus.js";
+import { open } from "node:fs/promises";
+//#region src/syslog/drivers/FileLogDriver.ts
+/** Octets max relus depuis la FIN du fichier à chaque query (anti-OOM). Défaut 8 MiB. */
+const DEFAULT_MAX_SCAN_BYTES = 8388608;
+/**
+* Driver `file` du Log Backplane (LB.2) — destination de logs **JSONL queryable**
+* (persistante, dev/VPS). Chaque ligne est un Pdu sérialisé en forme wire plate
+* (`JSON.stringify`), produit côté WRITE par un transport file `format:"json"` ;
+* ce format plat est aussi celui qu'ingèrent Promtail (Loki) / Filebeat (OpenSearch)
+* sans transformation → le driver file est le tremplin testable vers les drivers
+* prod (LB.4).
+*
+* La `query` RELIT le fichier — chemin **FROID** (admin/debug), `async`, **JAMAIS**
+* dans le pipeline requête. Elle borne la lecture aux derniers `maxScanBytes` octets
+* (anti-OOM), réhydrate chaque ligne en {@link IPduLike} (SANS instancier un `Pdu`,
+* donc 0 effet de bord uid/provider), puis délègue le filtrage à {@link filterPdus}
+* (même logique que le driver `memory` — une logique, N façades).
+*
+* Robustesse : fichier absent / illisible → résultat vide (un viewer ne doit pas
+* crasher) ; lignes vides ou JSON corrompu (write tronqué par un crash) → ignorées.
+*
+* @param options - chemin du JSONL + plafond de scan optionnel.
+* @returns un `ILogDriver` `file` queryable (Node-only).
+*/
+function createFileLogDriver(options) {
+	const path = options.path;
+	const maxScanBytes = options.maxScanBytes ?? 8388608;
+	return {
+		name: "file",
+		capabilities: {
+			write: true,
+			query: true,
+			stream: false
+		},
+		query: async (criteria) => {
+			const records = await scanJsonlTail(path, maxScanBytes);
+			return filterPdus(records, criteria);
+		}
+	};
+}
+/**
+* Relit la QUEUE d'un fichier JSONL (bornée à `maxScanBytes` octets depuis la
+* FIN, anti-OOM) et la réhydrate en {@link IPduLike}[] — SANS instancier de
+* `Pdu` (0 effet de bord uid/provider). Brique de scan **PARTAGÉE** par le
+* driver `file` (LB.2, un seul fichier) et le driver `cluster-file` (LB.5, qui
+* scanne les `nodefony-<pid>.jsonl` de tous les workers). Fichier absent /
+* illisible → tableau vide (jamais throw). Lignes vides ou JSON corrompu (write
+* tronqué par un crash) → ignorées.
+*
+* @param path - chemin du fichier JSONL.
+* @param maxScanBytes - plafond d'octets relus depuis la fin du fichier.
+* @returns enregistrements dans l'ordre du fichier (FIFO, ancien → récent).
+*/
+async function scanJsonlTail(path, maxScanBytes) {
+	const text = await readTail(path, maxScanBytes);
+	if (text.length === 0) return [];
+	const records = [];
+	for (const line of text.split("\n")) {
+		if (line.length === 0) continue;
+		const rec = parseLine(line);
+		if (rec) records.push(rec);
+	}
+	return records;
+}
+/**
+* Lit les derniers `maxBytes` octets du fichier (borne anti-OOM). Si le fichier
+* dépasse, on jette le 1ᵉʳ fragment de ligne partielle (lecture démarrée au milieu
+* d'une ligne). Fichier absent / illisible → string vide (jamais throw côté query).
+*/
+async function readTail(path, maxBytes) {
+	let opened;
+	try {
+		opened = await open(path, "r");
+	} catch {
+		return "";
+	}
+	await using fh = opened;
+	const { size } = await fh.stat();
+	if (size === 0) return "";
+	const start = size > maxBytes ? size - maxBytes : 0;
+	const length = size - start;
+	const buf = Buffer.allocUnsafe(length);
+	await fh.read(buf, 0, length, start);
+	let text = buf.toString("utf8");
+	if (start > 0) {
+		const nl = text.indexOf("\n");
+		text = nl === -1 ? "" : text.slice(nl + 1);
+	}
+	return text;
+}
+/** Parse une ligne JSONL en {@link IPduLike}, ou `null` si corrompue / non-Pdu. */
+function parseLine(line) {
+	let raw;
+	try {
+		raw = JSON.parse(line);
+	} catch {
+		return null;
+	}
+	return coerceRecord(raw);
+}
+/**
+* Narrowing SÛR d'un objet JSON relu (entrée externe = disque) vers {@link IPduLike}.
+* Rejette ce qui n'est pas un enregistrement de log (les 3 champs discriminants
+* `severityName`/`moduleName`/`timeStamp` manquent ou de mauvais type) ; complète
+* les champs accessoires avec des défauts sûrs. 0 `any`, 0 instanciation de Pdu.
+*/
+function coerceRecord(raw) {
+	if (typeof raw !== "object" || raw === null) return null;
+	const o = raw;
+	if (typeof o.severityName !== "string" || typeof o.moduleName !== "string" || typeof o.timeStamp !== "number") return null;
+	const rec = {
+		uid: typeof o.uid === "number" ? o.uid : 0,
+		severity: typeof o.severity === "number" ? o.severity : 7,
+		severityName: o.severityName,
+		moduleName: o.moduleName,
+		msgid: typeof o.msgid === "string" ? o.msgid : "",
+		msg: typeof o.msg === "string" ? o.msg : "",
+		timeStamp: o.timeStamp,
+		pid: typeof o.pid === "number" ? o.pid : 0,
+		payload: o.payload
+	};
+	if (typeof o.requestId === "string") rec.requestId = o.requestId;
+	return rec;
+}
+//#endregion
+export { DEFAULT_MAX_SCAN_BYTES, coerceRecord, createFileLogDriver, scanJsonlTail };

package/dist/node/syslog/drivers/ILogDriver.js

@@ -0,0 +1,26 @@
+//#region src/syslog/drivers/ILogDriver.ts
+/**
+* Sérialise un Pdu en {@link ILogRecord} (forme wire). Source unique de la
+* projection Pdu→wire : réutilisée par {@link filterPdus} (driver memory) ET par
+* le producteur data-plane `syslog` (framework) — pas de shape dupliqué qui dérive.
+*
+* @param pdu - Pdu (instance ou objet structurellement compatible — {@link IPduLike}).
+* @returns enregistrement plat sérialisable. `requestId` omis si absent.
+*/
+function pduToRecord(pdu) {
+	const rec = {
+		uid: pdu.uid,
+		severity: pdu.severity,
+		severityName: pdu.severityName,
+		moduleName: pdu.moduleName,
+		msgid: pdu.msgid,
+		msg: pdu.msg,
+		timeStamp: pdu.timeStamp,
+		pid: pdu.pid,
+		payload: pdu.payload
+	};
+	if (pdu.requestId !== void 0) rec.requestId = pdu.requestId;
+	return rec;
+}
+//#endregion
+export { pduToRecord };

package/dist/node/syslog/drivers/LokiLogDriver.js

@@ -0,0 +1,144 @@
+import { escapeRegExp, stripTrailingSlashes } from "../../Tools.js";
+import { fetchWithTimeout, resolveFetch } from "../httpFetch.js";
+import { filterPdus } from "./filterPdus.js";
+import { coerceRecord } from "./FileLogDriver.js";
+//#region src/syslog/drivers/LokiLogDriver.ts
+/** Échappe une chaîne pour une string literal LogQL `"..."` (Go-style). */
+function escapeLogQLString(s) {
+	return s.replace(/\\/g, "\\\\").replace(/"/g, "\\\"");
+}
+/** Échappe les métacaractères regex (pour un line filter `|~`). */
+const escapeRegex = escapeRegExp;
+/**
+* Extrait les lignes de log d'une réponse `query_range` Loki (`data.result[].values[][1]`),
+* en narrowing SÛR (réponse réseau = entrée externe, 0 `any`).
+*/
+function extractLokiLines(json) {
+	if (typeof json !== "object" || json === null) return [];
+	const data = json.data;
+	if (typeof data !== "object" || data === null) return [];
+	const result = data.result;
+	if (!Array.isArray(result)) return [];
+	const lines = [];
+	for (const stream of result) {
+		if (typeof stream !== "object" || stream === null) continue;
+		const values = stream.values;
+		if (!Array.isArray(values)) continue;
+		for (const v of values) if (Array.isArray(v) && typeof v[1] === "string") lines.push(v[1]);
+	}
+	return lines;
+}
+/**
+* Driver `loki` du Log Backplane (LB.4) — relit les logs dans **Grafana Loki** via
+* LogQL (`GET /loki/api/v1/query_range`). **Adaptateur, pas moteur** : Loki BORNE le
+* rapatriement (sélecteur de labels + fenêtre temporelle + grep + budget de lignes),
+* puis {@link filterPdus} est l'**autorité finale** sur le sous-ensemble rapatrié →
+* sémantique EXACTEMENT identique aux drivers `memory`/`file` (inclusion insensible à
+* la casse, ordering `uid`, pagination). Une logique, N façades.
+*
+* Chaque ligne Loki est le record wire JSON écrit par {@link LokiTransport} → `JSON.parse`
+* + {@link coerceRecord} (lignes corrompues ignorées). Chemin **FROID** (admin/debug),
+* jamais dans le pipeline requête. Loki injoignable / requête invalide → `throw` explicite
+* (≠ `file` absent : une infra de logs prod en panne DOIT être visible, pas masquée).
+*
+* @param options - URL Loki + labels + budgets.
+* @returns un `ILogDriver` `loki` queryable (Node-only).
+*/
+function createLokiLogDriver(options) {
+	const base = stripTrailingSlashes(options.url);
+	const baseLabels = options.labels ?? { app: "nodefony" };
+	const maxScanLines = options.maxScanLines ?? 1e3;
+	const defaultLookbackMs = options.defaultLookbackMs ?? 864e5;
+	const timeoutMs = options.timeoutMs ?? 8e3;
+	const headers = {
+		...options.tenantId ? { "X-Scope-OrgID": options.tenantId } : {},
+		...options.headers
+	};
+	const fetchImpl = resolveFetch(options.fetchImpl);
+	const buildQuery = (criteria) => {
+		const sel = Object.entries(baseLabels).map(([k, v]) => `${k}="${escapeLogQLString(v)}"`);
+		if (criteria.severity !== void 0) {
+			const sevs = (Array.isArray(criteria.severity) ? criteria.severity : [criteria.severity]).map((s) => escapeLogQLString(s.toUpperCase()));
+			sel.push(`severity=~"${sevs.join("|")}"`);
+		}
+		let q = `{${sel.join(",")}}`;
+		if (criteria.requestId !== void 0) q += ` |= "${escapeLogQLString(criteria.requestId)}"`;
+		if (criteria.text !== void 0) q += ` |~ "${escapeLogQLString("(?i)" + escapeRegex(criteria.text))}"`;
+		return q;
+	};
+	return {
+		name: "loki",
+		capabilities: {
+			write: true,
+			query: true,
+			stream: false
+		},
+		query: async (criteria) => {
+			const now = Date.now();
+			const fromMs = criteria.from ?? now - defaultLookbackMs;
+			const toMs = criteria.to ?? now;
+			const params = new URLSearchParams({
+				query: buildQuery(criteria),
+				start: `${fromMs}000000`,
+				end: `${toMs}000000`,
+				limit: String(maxScanLines),
+				direction: "backward"
+			});
+			const url = `${base}/loki/api/v1/query_range?${params.toString()}`;
+			const res = await fetchWithTimeout(fetchImpl, url, {
+				method: "GET",
+				headers
+			}, timeoutMs);
+			if (!res.ok) throw new Error(`LokiLogDriver: query HTTP ${res.status}`);
+			const lines = extractLokiLines(await res.json());
+			const records = [];
+			for (const line of lines) {
+				let raw;
+				try {
+					raw = JSON.parse(line);
+				} catch {
+					continue;
+				}
+				const rec = coerceRecord(raw);
+				if (rec) records.push(rec);
+			}
+			records.sort((a, b) => a.timeStamp - b.timeStamp || a.uid - b.uid);
+			return filterPdus(records, criteria);
+		},
+		probe: async () => {
+			const t0 = Date.now();
+			try {
+				const res = await fetchWithTimeout(fetchImpl, `${base}/ready`, {
+					method: "GET",
+					headers
+				}, timeoutMs);
+				const latencyMs = Date.now() - t0;
+				const text = (await res.text()).trim();
+				const ready = res.ok && text.toLowerCase().startsWith("ready");
+				const info = {
+					endpoint: base,
+					httpStatus: res.status
+				};
+				return ready ? {
+					ok: true,
+					latencyMs,
+					info
+				} : {
+					ok: false,
+					latencyMs,
+					detail: `Loki /ready → HTTP ${res.status}${text ? ` (${text.slice(0, 60)})` : ""}`,
+					info
+				};
+			} catch (e) {
+				return {
+					ok: false,
+					latencyMs: Date.now() - t0,
+					detail: e instanceof Error ? e.message : "unreachable",
+					info: { endpoint: base }
+				};
+			}
+		}
+	};
+}
+//#endregion
+export { createLokiLogDriver };

package/dist/node/syslog/drivers/MemoryLogDriver.js

@@ -0,0 +1,33 @@
+import { filterPdus } from "./filterPdus.js";
+//#region src/syslog/drivers/MemoryLogDriver.ts
+/**
+* Driver `memory` (LB.1) — le **ring buffer du Syslog EST le stockage**. Aucun
+* write dédié : le ring est alimenté par `Syslog.pushStack` sur le hot path. Le
+* driver n'ajoute que la **relecture** (`query`) = {@link filterPdus} sur un
+* snapshot du ring.
+*
+* Défaut en développement : volatile (perdu au restart), borné (`maxStack`), mais
+* **0 dépendance, isomorphe** (pas de `node:*` → utilisable côté navigateur plus
+* tard pour un Log Backplane front). Pour persister/agréger en prod → drivers
+* `file` (LB.2) / `elastic`-`loki` (LB.4).
+*
+* La **source** est injectée (provider `() => IPduLike[]`, comme `Pdu.requestIdProvider`)
+* → le driver ne dépend pas de `Syslog` ni du `Kernel` (le wiring fournit
+* `() => kernel.syslog.ringStack`). Découplé + testable avec un tableau en dur.
+*
+* @param source - fournit le snapshot courant des Pdu (ex. `() => syslog.ringStack`).
+* @returns un `ILogDriver` `memory` queryable.
+*/
+function createMemoryLogDriver(source) {
+	return {
+		name: "memory",
+		capabilities: {
+			write: false,
+			query: true,
+			stream: true
+		},
+		query: (criteria) => Promise.resolve(filterPdus(source(), criteria))
+	};
+}
+//#endregion
+export { createMemoryLogDriver };

package/dist/node/syslog/drivers/OpenSearchLogDriver.js

@@ -0,0 +1,159 @@
+import { stripTrailingSlashes } from "../../Tools.js";
+import { fetchWithTimeout, resolveFetch } from "../httpFetch.js";
+import { basicAuthHeader } from "./opensearchShared.js";
+import { filterPdus } from "./filterPdus.js";
+import { coerceRecord } from "./FileLogDriver.js";
+//#region src/syslog/drivers/OpenSearchLogDriver.ts
+/**
+* Extrait les `_source` d'une réponse `_search` OpenSearch (`hits.hits[]._source`),
+* narrowing SÛR (0 `any`).
+*/
+function extractSources(json) {
+	if (typeof json !== "object" || json === null) return [];
+	const hits = json.hits;
+	if (typeof hits !== "object" || hits === null) return [];
+	const arr = hits.hits;
+	if (!Array.isArray(arr)) return [];
+	const out = [];
+	for (const h of arr) if (typeof h === "object" && h !== null) out.push(h._source);
+	return out;
+}
+/** Lit une string à `key` dans un objet inconnu (narrowing sûr). */
+function pickStr(o, key) {
+	if (typeof o !== "object" || o === null) return void 0;
+	const v = o[key];
+	return typeof v === "string" ? v : void 0;
+}
+/** Lit un nombre à `key` dans un objet inconnu (narrowing sûr). */
+function pickNum(o, key) {
+	if (typeof o !== "object" || o === null) return void 0;
+	const v = o[key];
+	return typeof v === "number" ? v : void 0;
+}
+/** Lit la sous-valeur objet à `key` (pour `root.version.number`). */
+function pickObj(o, key) {
+	if (typeof o !== "object" || o === null) return void 0;
+	return o[key];
+}
+/**
+* Driver `opensearch` du Log Backplane (LB.4) — relit les logs dans **OpenSearch**
+* via `POST /{index}/_search` (Query DSL). **Adaptateur, pas moteur** : OpenSearch
+* borne le rapatriement (range sur `timeStamp` + `sort` desc + budget `size`), puis
+* {@link filterPdus} est l'**autorité finale** sur le sous-ensemble → sémantique
+* identique aux drivers `memory`/`file`. Une logique, N façades.
+*
+* Chaque `_source` est le record wire indexé par {@link OpenSearchTransport} →
+* {@link coerceRecord} (documents non conformes ignorés). Chemin **FROID** (admin/debug).
+* Index encore absent (404 `index_not_found`) → résultat VIDE (normal : aucun log
+* indexé). Vraie panne (réseau, 5xx) → `throw` explicite (infra de logs prod visible).
+*
+* @param options - URL OpenSearch + index + budget.
+* @returns un `ILogDriver` `opensearch` queryable (Node-only).
+*/
+function createOpenSearchLogDriver(options) {
+	const base = stripTrailingSlashes(options.url);
+	const index = options.index ?? "nodefony-logs";
+	const maxHits = options.maxHits ?? 1e3;
+	const timeoutMs = options.timeoutMs ?? 8e3;
+	const headers = {
+		"content-type": "application/json",
+		...basicAuthHeader(options.username, options.password),
+		...options.headers
+	};
+	const fetchImpl = resolveFetch(options.fetchImpl);
+	return {
+		name: "opensearch",
+		capabilities: {
+			write: true,
+			query: true,
+			stream: false
+		},
+		query: async (criteria) => {
+			const filter = [];
+			if (criteria.from !== void 0 || criteria.to !== void 0) {
+				const range = {};
+				if (criteria.from !== void 0) range.gte = criteria.from;
+				if (criteria.to !== void 0) range.lte = criteria.to;
+				filter.push({ range: { timeStamp: range } });
+			}
+			const body = JSON.stringify({
+				size: maxHits,
+				track_total_hits: true,
+				sort: [{ timeStamp: { order: "desc" } }],
+				query: filter.length > 0 ? { bool: { filter } } : { match_all: {} }
+			});
+			const url = `${base}/${encodeURIComponent(index)}/_search`;
+			const res = await fetchWithTimeout(fetchImpl, url, {
+				method: "POST",
+				headers,
+				body
+			}, timeoutMs);
+			if (res.status === 404) return {
+				rows: [],
+				total: 0,
+				truncated: false
+			};
+			if (!res.ok) throw new Error(`OpenSearchLogDriver: search HTTP ${res.status}`);
+			const sources = extractSources(await res.json());
+			const records = [];
+			for (const src of sources) {
+				const rec = coerceRecord(src);
+				if (rec) records.push(rec);
+			}
+			records.reverse();
+			return filterPdus(records, criteria);
+		},
+		probe: async () => {
+			const t0 = Date.now();
+			try {
+				const res = await fetchWithTimeout(fetchImpl, `${base}/`, {
+					method: "GET",
+					headers
+				}, timeoutMs);
+				const latencyMs = Date.now() - t0;
+				if (!res.ok) return {
+					ok: false,
+					latencyMs,
+					detail: `OpenSearch / → HTTP ${res.status}`,
+					info: {
+						endpoint: base,
+						httpStatus: res.status
+					}
+				};
+				const root = await res.json();
+				const info = {
+					endpoint: base,
+					index
+				};
+				const version = pickStr(pickObj(root, "version"), "number");
+				if (version) info.version = version;
+				const cluster = pickStr(root, "cluster_name");
+				if (cluster) info.cluster = cluster;
+				try {
+					const cres = await fetchWithTimeout(fetchImpl, `${base}/${encodeURIComponent(index)}/_count`, {
+						method: "GET",
+						headers
+					}, timeoutMs);
+					if (cres.ok) {
+						const count = pickNum(await cres.json(), "count");
+						if (count !== void 0) info.docs = count;
+					} else if (cres.status === 404) info.docs = 0;
+				} catch {}
+				return {
+					ok: true,
+					latencyMs,
+					info
+				};
+			} catch (e) {
+				return {
+					ok: false,
+					latencyMs: Date.now() - t0,
+					detail: e instanceof Error ? e.message : "unreachable",
+					info: { endpoint: base }
+				};
+			}
+		}
+	};
+}
+//#endregion
+export { createOpenSearchLogDriver };