@classytic/arc 2.41.1 → 2.43.0

package/dist/{health-ZRHeDHXH.mjs → health-DqbsG-_w.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
 import { randomUUID } from "node:crypto";
 import fp from "fastify-plugin";
 //#region src/plugins/requestId.ts
@@ -111,6 +111,115 @@ var requestId_default = fp(requestIdPlugin, {
 	fastify: "5.x"
 });
 //#endregion
+//#region src/utils/metricSeries.ts
+/** Retains a fixed number of label sets; excess observations share one overflow series. */
+var MetricSeries = class {
+	data = /* @__PURE__ */ new Map();
+	overflow;
+	limit;
+	constructor(limit = 1e3) {
+		if (!Number.isSafeInteger(limit) || limit < 1) throw new RangeError("metrics.maxSeries must be a positive safe integer");
+		this.limit = limit;
+	}
+	get(labels, init) {
+		const key = JSON.stringify(Object.entries(labels).sort(([a], [b]) => a.localeCompare(b)));
+		const existing = this.data.get(key);
+		if (existing) return existing.value;
+		if (this.data.size >= this.limit) {
+			this.overflow ??= {
+				labels: { overflow: "true" },
+				value: init()
+			};
+			return this.overflow.value;
+		}
+		const entry = {
+			labels: { ...labels },
+			value: init()
+		};
+		this.data.set(key, entry);
+		return entry.value;
+	}
+	entries() {
+		return [...this.data.values(), ...this.overflow ? [this.overflow] : []];
+	}
+	reset() {
+		this.data.clear();
+		this.overflow = void 0;
+	}
+};
+const DURATION_BUCKETS_SECONDS = [
+	.001,
+	.002,
+	.005,
+	.01,
+	.025,
+	.05,
+	.1,
+	.25,
+	.5,
+	1,
+	2.5,
+	5,
+	10
+];
+/** Stores disjoint bucket counts; exported buckets are cumulative and include +Inf. */
+var MetricHistogram = class {
+	series;
+	bounds;
+	constructor(bounds, maxSeries = 1e3) {
+		this.bounds = bounds;
+		this.series = new MetricSeries(maxSeries);
+	}
+	observe(labels, value) {
+		if (!Number.isFinite(value) || value < 0) return;
+		const state = this.series.get(labels, () => ({
+			buckets: new Array(this.bounds.length + 1).fill(0),
+			sum: 0,
+			count: 0
+		}));
+		const index = this.bounds.findIndex((bound) => value <= bound);
+		const bucket = index < 0 ? this.bounds.length : index;
+		state.buckets[bucket] = (state.buckets[bucket] ?? 0) + 1;
+		state.sum += value;
+		state.count++;
+	}
+	values() {
+		return this.series.entries().flatMap(({ labels, value }) => {
+			let cumulative = 0;
+			return [
+				...value.buckets.map((count, index) => {
+					cumulative += count;
+					return {
+						labels: {
+							...labels,
+							le: this.bounds[index]?.toString() ?? "+Inf"
+						},
+						value: cumulative,
+						suffix: "_bucket"
+					};
+				}),
+				{
+					labels: { ...labels },
+					value: value.sum,
+					suffix: "_sum"
+				},
+				{
+					labels: { ...labels },
+					value: value.count,
+					suffix: "_count"
+				}
+			];
+		});
+	}
+	reset() {
+		this.series.reset();
+	}
+};
+function renderMetricSample(name, sample) {
+	const labels = Object.entries(sample.labels).map(([key, value]) => `${key}="${value.replaceAll("\\", "\\\\").replaceAll("\n", "\\n").replaceAll("\"", "\\\"")}"`).join(",");
+	return `${name}${sample.suffix ?? ""}${labels ? `{${labels}}` : ""} ${sample.value}`;
+}
+//#endregion
 //#region src/plugins/health.ts
 /**
 * Merge health checks without losing ownership information.
@@ -130,47 +239,12 @@ function mergeHealthChecks(groups) {
 	}
 	return merged;
 }
-/**
-* Fixed histogram bucket upper bounds (ms). Recording is O(#buckets) per
-* request; the scrape derives quantile UPPER BOUNDS from cumulative counts
-* in O(#buckets) — no sample retention, no per-scrape sort (the previous
-* 10k-sample ring buffer copied + sorted on EVERY scrape), and bucket
-* counts aggregate correctly across instances.
-*/
-const DURATION_BUCKETS_MS = [
-	1,
-	2,
-	5,
-	10,
-	25,
-	50,
-	100,
-	250,
-	500,
-	1e3,
-	2500,
-	5e3,
-	1e4
-];
 function createHttpMetrics() {
 	return {
 		requestsTotal: {},
-		durationBuckets: new Array(DURATION_BUCKETS_MS.length + 1).fill(0),
-		durationCount: 0,
-		durationSumMs: 0,
-		startTime: Date.now()
+		duration: new MetricHistogram(DURATION_BUCKETS_SECONDS.map((seconds) => seconds * 1e3))
 	};
 }
-/** Smallest bucket upper bound whose cumulative count reaches `q × total`. */
-function bucketQuantile(metrics, q) {
-	const target = Math.ceil(metrics.durationCount * q);
-	let cumulative = 0;
-	for (let i = 0; i < metrics.durationBuckets.length; i++) {
-		cumulative += metrics.durationBuckets[i] ?? 0;
-		if (cumulative >= target) return DURATION_BUCKETS_MS[i] ?? DURATION_BUCKETS_MS[DURATION_BUCKETS_MS.length - 1] ?? 0;
-	}
-	return DURATION_BUCKETS_MS[DURATION_BUCKETS_MS.length - 1] ?? 0;
-}
 const healthPlugin = async (fastify, opts = {}) => {
 	const { prefix = "/_health", checks = [], metrics = false, metricsCollector, version, collectHttpMetrics = metrics } = opts;
 	const readinessChecks = mergeHealthChecks([{
@@ -315,12 +389,8 @@ const healthPlugin = async (fastify, opts = {}) => {
 			lines.push("# HELP http_requests_total Total HTTP requests by status code", "# TYPE http_requests_total counter");
 			for (const [status, count] of Object.entries(httpMetrics.requestsTotal)) lines.push(`http_requests_total{status="${status}"} ${count}`);
 			lines.push("");
-			if (httpMetrics.durationCount > 0) {
-				const p50 = bucketQuantile(httpMetrics, .5);
-				const p95 = bucketQuantile(httpMetrics, .95);
-				const p99 = bucketQuantile(httpMetrics, .99);
-				lines.push("# HELP http_request_duration_milliseconds HTTP request duration (bucket upper bounds)", "# TYPE http_request_duration_milliseconds summary", `http_request_duration_milliseconds{quantile="0.5"} ${p50.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.95"} ${p95.toFixed(2)}`, `http_request_duration_milliseconds{quantile="0.99"} ${p99.toFixed(2)}`, `http_request_duration_milliseconds_sum ${httpMetrics.durationSumMs.toFixed(2)}`, `http_request_duration_milliseconds_count ${httpMetrics.durationCount}`, "");
-			}
+			const samples = httpMetrics.duration.values();
+			if (samples.length > 0) lines.push("# HELP http_request_duration_milliseconds HTTP request duration in milliseconds", "# TYPE http_request_duration_milliseconds histogram", ...samples.map((sample) => renderMetricSample("http_request_duration_milliseconds", sample)), "");
 		}
 		return lines.join("\n");
 	});
@@ -328,17 +398,7 @@ const healthPlugin = async (fastify, opts = {}) => {
 		const duration = reply.elapsedTime;
 		const statusBucket = `${Math.floor(reply.statusCode / 100)}xx`;
 		httpMetrics.requestsTotal[statusBucket] = (httpMetrics.requestsTotal[statusBucket] || 0) + 1;
-		let bucket = DURATION_BUCKETS_MS.length;
-		for (let i = 0; i < DURATION_BUCKETS_MS.length; i++) {
-			const bound = DURATION_BUCKETS_MS[i];
-			if (bound !== void 0 && duration <= bound) {
-				bucket = i;
-				break;
-			}
-		}
-		httpMetrics.durationBuckets[bucket] = (httpMetrics.durationBuckets[bucket] ?? 0) + 1;
-		httpMetrics.durationCount++;
-		httpMetrics.durationSumMs += duration;
+		httpMetrics.duration.observe({}, duration);
 	});
 	fastify.log?.debug?.(`Health plugin registered at ${prefix} (alias), ${prefix}/live, ${prefix}/ready${metrics ? `, ${prefix}/metrics` : ""}`);
 };
@@ -383,4 +443,4 @@ var health_default = fp(healthPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { requestIdPlugin as a, createRequestIdGenerator as i, health_default as n, requestId_default as o, mergeHealthChecks as r, sanitizeRequestId as s, healthPlugin as t };
+export { MetricHistogram as a, createRequestIdGenerator as c, DURATION_BUCKETS_SECONDS as i, requestId_default as l, health_default as n, MetricSeries as o, mergeHealthChecks as r, renderMetricSample as s, healthPlugin as t, sanitizeRequestId as u };

package/dist/hooks/index.d.mts

@@ -1,3 +1,3 @@
 
-import { an as HookRegistration, cn as afterCreate, dn as beforeCreate, en as DefineHookOptions, fn as beforeDelete, hn as defineHook, in as HookPhase, ln as afterDelete, mn as createHookSystem, nn as HookHandler, on as HookSystem, pn as beforeUpdate, rn as HookOperation, sn as HookSystemOptions, tn as HookContext, un as afterUpdate } from "../index-DHbyPo5j.mjs";
-export { type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };
+import { $t as AroundHookHandler, an as HookRegistration, cn as afterCreate, dn as beforeCreate, en as DefineHookOptions, fn as beforeDelete, hn as defineHook, in as HookPhase, ln as afterDelete, mn as createHookSystem, nn as HookHandler, on as HookSystem, pn as beforeUpdate, rn as HookOperation, sn as HookSystemOptions, tn as HookContext, un as afterUpdate } from "../index-mqaqZNpe.mjs";
+export { type AroundHookHandler, type DefineHookOptions, type HookContext, type HookHandler, type HookOperation, type HookPhase, type HookRegistration, HookSystem, type HookSystemOptions, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/hooks/index.mjs

@@ -1,3 +1,3 @@
-/*! @classytic/arc v2.41.1 | MIT | https://classytic.com */
-import { a as beforeCreate, c as createHookSystem, i as afterUpdate, l as defineHook, n as afterCreate, o as beforeDelete, r as afterDelete, s as beforeUpdate, t as HookSystem } from "../HookSystem-CMF94SEA.mjs";
+/*! @classytic/arc v2.43.0 | MIT | https://classytic.com */
+import { a as beforeCreate, c as createHookSystem, i as afterUpdate, l as defineHook, n as afterCreate, o as beforeDelete, r as afterDelete, s as beforeUpdate, t as HookSystem } from "../HookSystem-B6UaKRbF.mjs";
 export { HookSystem, afterCreate, afterDelete, afterUpdate, beforeCreate, beforeDelete, beforeUpdate, createHookSystem, defineHook };

package/dist/idempotency/index.d.mts

@@ -1,6 +1,7 @@
 
-import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-DEWNOMza.mjs";
-import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-Bzi1y3F9.mjs";
+import { t as RouteIdempotencyConfig } from "../requirement-CbiLdQ1n.mjs";
+import { i as createIdempotencyResult, n as IdempotencyResult, r as IdempotencyStore, t as IdempotencyLock } from "../interface-C0395yUN.mjs";
+import { i as RedisIdempotencyStoreOptions, n as RedisClient } from "../redis-vLvtcGy_.mjs";
 import { FastifyPluginAsync } from "fastify";
 import { RepositoryLike } from "@classytic/repo-core/adapter";
 //#region src/idempotency/idempotencyPlugin.d.ts
@@ -13,7 +14,11 @@ interface IdempotencyPluginOptions {
   ttlMs?: number;
   /** Lock timeout in ms (default: 30000 = 30s) */
   lockTimeoutMs?: number;
-  /** HTTP methods to apply idempotency to (default: ['POST', 'PUT', 'PATCH']) */
+  /**
+   * HTTP methods a key is honoured on when the route does not declare `config.idempotency`
+   * (default: ['POST', 'PUT', 'PATCH']). A route declaring `required: true` is fenced whatever
+   * its method — DELETE included — and whatever `include` / `exclude` say.
+   */
   methods?: string[];
   /** URL patterns to include (regex). If set, only matching URLs use idempotency */
   include?: RegExp[];
@@ -63,6 +68,8 @@ interface IdempotencyPluginOptions {
    * remain as the runtime backstop.
    */
   selfCheck?: boolean;
+  /** Migration escape for legacy custom stores without atomic completion fencing; warns at boot. */
+  allowUnfencedCompletion?: boolean;
 }
 declare module "fastify" {
   interface FastifyRequest {
@@ -70,8 +77,20 @@ declare module "fastify" {
     idempotencyKey?: string;
     /** Whether this response was replayed from cache */
     idempotencyReplayed?: boolean;
-    /** @internal Full key with fingerprint for store lookups */
+    /** @internal The operation's storage key */
     _idempotencyFullKey?: string;
+    /** @internal `fingerprintRequest` of this request's body, stored with its response */
+    _idempotencyFingerprint?: string;
+  }
+  interface FastifyContextConfig {
+    /**
+     * Per-route idempotency. `required: true` (or, on an action route, `requiredActions`
+     * naming the `body.action` values) refuses a call with no idempotency key (400
+     * `arc.idempotency_key_required`) and dedupes a keyed one, on any method. Boot refuses the
+     * declaration when nothing would enforce it: the plugin disabled, or the route's
+     * `preHandler` lacking `fastify.idempotency.middleware`.
+     */
+    idempotency?: RouteIdempotencyConfig;
   }
   interface FastifyInstance {
     /** Idempotency utilities */
@@ -93,7 +112,7 @@ declare module "fastify" {
        * }, handler);
        * ```
        */
-      middleware: (request: FastifyRequest, reply: FastifyReply) => Promise<void>;
+      middleware: (request: FastifyRequest, reply: FastifyReply) => Promise<undefined | FastifyReply>;
       /**
        * The resolved backing store. Exposed so non-HTTP executors (MCP
        * tools via `mcpPlugin`'s execution wiring, jobs, workflows) can run
@@ -101,10 +120,13 @@ declare module "fastify" {
        * backend. `undefined` when the plugin is disabled.
        */
       store?: IdempotencyStore;
+      /** Explicit migration escape shared with non-HTTP executors. */
+      readonly allowUnfencedCompletion?: boolean;
+      readonly ttlMs?: number;
+      readonly lockTimeoutMs?: number;
     };
   }
 }
-declare const idempotencyPlugin: FastifyPluginAsync<IdempotencyPluginOptions>;
 declare const _default: FastifyPluginAsync<IdempotencyPluginOptions>;
 //#endregion
 //#region src/idempotency/repository-idempotency-adapter.d.ts
@@ -157,6 +179,8 @@ declare class MemoryIdempotencyStore implements IdempotencyStore {
   constructor(options?: MemoryIdempotencyStoreOptions);
   get(key: string): Promise<IdempotencyResult | undefined>;
   set(key: string, result: Omit<IdempotencyResult, "key">): Promise<void>;
+  private writeResult;
+  setIfLocked(key: string, requestId: string, result: Omit<IdempotencyResult, "key">): Promise<boolean>;
   tryLock(key: string, requestId: string, ttlMs: number): Promise<boolean>;
   unlock(key: string, requestId: string): Promise<void>;
   isLocked(key: string): Promise<boolean>;
@@ -173,4 +197,4 @@ declare class MemoryIdempotencyStore implements IdempotencyStore {
   private evictOldest;
 }
 //#endregion
-export { type IdempotencyLock, type IdempotencyPluginOptions, type IdempotencyResult, type IdempotencyStore, IdempotencyStoreMisconfiguredError, MemoryIdempotencyStore, type MemoryIdempotencyStoreOptions, type RedisClient, type RedisIdempotencyStoreOptions, createIdempotencyResult, _default as idempotencyPlugin, idempotencyPlugin as idempotencyPluginFn, repositoryAsIdempotencyStore };
+export { type IdempotencyLock, type IdempotencyPluginOptions, type IdempotencyResult, type IdempotencyStore, IdempotencyStoreMisconfiguredError, MemoryIdempotencyStore, type MemoryIdempotencyStoreOptions, type RedisClient, type RedisIdempotencyStoreOptions, createIdempotencyResult, _default as idempotencyPlugin, repositoryAsIdempotencyStore };