@classytic/arc 2.33.0 → 2.35.0

package/dist/pipeline/index.d.mts

@@ -1,5 +1,5 @@
 
-import { Ct as PipelineStep, Fn as IControllerResponse, St as PipelineContext, _t as Guard, bt as OperationFilter, vt as Interceptor, wt as Transform, xt as PipelineConfig, yt as NextFunction } from "../index-BcR2bFZQ.mjs";
+import { Ct as PipelineStep, Fn as IControllerResponse, St as PipelineContext, _t as Guard, bt as OperationFilter, vt as Interceptor, wt as Transform, xt as PipelineConfig, yt as NextFunction } from "../index-C5K78SXo.mjs";
 //#region src/pipeline/guard.d.ts
 interface GuardOptions {
   operations?: OperationFilter;

package/dist/pipeline/index.mjs

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-import { n as pipe, t as executePipeline } from "../pipe-BzzoEhHj.mjs";
+/*! @classytic/arc v2.35.0 | MIT | https://classytic.com */
+import { n as pipe, t as executePipeline } from "../pipe-DNOuCfAs.mjs";
 //#region src/pipeline/guard.ts
 /**
 * Create a named guard.

package/dist/plugins/index.d.mts

@@ -1,10 +1,10 @@
 
-import { t as AnyRecord } from "../base-Csjc2oF-.mjs";
-import { At as RouteDefinition, J as PresetHook, Q as MiddlewareConfig, et as RouteSchemaOptions } from "../index-BcR2bFZQ.mjs";
+import { t as AnyRecord } from "../base-GZU3LlzP.mjs";
+import { At as RouteDefinition, J as PresetHook, Q as MiddlewareConfig, et as RouteSchemaOptions } from "../index-C5K78SXo.mjs";
 import { i as errorHandlerPlugin, n as ErrorMapper, r as defaultIsDuplicateKeyError, t as ErrorHandlerOptions } from "../errorHandler-DI5AN2b5.mjs";
-import { _ as HealthCheck, b as healthPlugin, f as ScheduleDefinition, g as schedulesPlugin, h as _default$7, m as SchedulesPluginOptions, p as ScheduleStats, v as HealthOptions, y as _default$3 } from "../types-BcTumAz_.mjs";
-import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-DVsTAy6X.mjs";
-import { _ as CachingRule, a as MetricsCollector, c as metricsPlugin, d as _default$5, f as realtimePlugin, g as CachingOptions, h as ssePlugin, i as MetricEntry, l as ChangeOperation, m as _default$8, n as _default$9, o as MetricsOptions, p as SSEOptions, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as RealtimeOptions, v as _default$1, y as cachingPlugin } from "../versioning-DEs-_hFi.mjs";
+import { _ as HealthCheck, b as healthPlugin, f as ScheduleDefinition, g as schedulesPlugin, h as _default$8, m as SchedulesPluginOptions, p as ScheduleStats, v as HealthOptions, y as _default$3 } from "../types-DDD5RKTu.mjs";
+import { a as arcCorePlugin, i as _default, n as ArcCorePluginOptions, r as PluginMeta, t as ArcCore } from "../fastify-augmentation-CMMTL3cj.mjs";
+import { _ as CachingRule, a as MetricsCollector, c as metricsPlugin, d as _default$6, f as realtimePlugin, g as CachingOptions, h as ssePlugin, i as MetricEntry, l as ChangeOperation, m as _default$9, n as _default$10, o as MetricsOptions, p as SSEOptions, r as versioningPlugin, s as _default$4, t as VersioningOptions, u as RealtimeOptions, v as _default$1, y as cachingPlugin } from "../versioning-DEs-_hFi.mjs";
 import { t as TracingOptions } from "../tracing-Dro5eH6j.mjs";
 import { PaginatedResult } from "@classytic/repo-core/pagination";
 import { FastifyInstance, FastifyPluginAsync } from "fastify";
@@ -89,6 +89,91 @@ declare module "fastify" {
 }
 declare const _default$2: FastifyPluginAsync<GracefulShutdownOptions>;
 //#endregion
+//#region src/plugins/pressure.d.ts
+/**
+ * One measurable source of load, normalised by whoever owns it.
+ *
+ * A throwing `read()` reports 0, never 1 — a broken thermometer is not a fire.
+ * Logged once per signal, not per sample.
+ */
+interface PressureSignal {
+  /** Stable identity — appears in snapshots and logs. */
+  readonly name: string;
+  /** Saturation in [0, 1]. Values outside the range are clamped. */
+  read(): number | Promise<number>;
+}
+/** `ok` → serve · `degraded` → serve, shed what is optional · `saturated` → refuse. */
+type PressureState = "ok" | "degraded" | "saturated";
+interface PressureThresholds {
+  /** Enter `degraded` at or above this. Default 0.8. */
+  degraded?: number;
+  /** Enter `saturated` at or above this. Default 0.95. */
+  saturated?: number;
+}
+interface PressureSnapshot {
+  readonly state: PressureState;
+  /** Highest signal — the one that decided the state. */
+  readonly worst: {
+    name: string;
+    value: number;
+  } | undefined;
+  readonly signals: Readonly<Record<string, number>>;
+}
+interface PressureOptions {
+  /** Extra signals beyond the built-in ELU reader. */
+  signals?: PressureSignal[];
+  thresholds?: PressureThresholds;
+  /** Sampling cadence in ms. Default 1000. */
+  intervalMs?: number;
+  /** Include the built-in event-loop-utilisation signal. Default true. */
+  eventLoopUtilization?: boolean;
+  /** Fired when the state CHANGES — not on every sample. */
+  onStateChange?: (next: PressureState, snapshot: PressureSnapshot) => void;
+  /**
+   * Refuse with 503 while `saturated`. Default OFF — arc cannot know which
+   * routes are sheddable, and refusing a checkout because a dashboard drained
+   * the pool is worse than serving it slowly.
+   *
+   * `exclude` matches `request.url` by prefix. Health routes are ALWAYS exempt:
+   * a 503 on `/_health/ready` reads as "process dead", not "process full".
+   */
+  shed?: boolean | {
+    statusCode?: number;
+    retryAfterSeconds?: number;
+    exclude?: string[];
+  };
+}
+interface PressureApi {
+  state(): PressureState;
+  snapshot(): PressureSnapshot;
+  /** Register a signal after boot — for modules that resolve their source late. */
+  register(signal: PressureSignal): void;
+  /** True at `saturated`. The check a handler makes before admitting work. */
+  shouldShed(): boolean;
+  /**
+   * A readiness check for `healthPlugin({ checks })`. NOT auto-registered:
+   * flipping readiness pulls the instance from its load balancer — right in a
+   * fleet, a self-inflicted outage for a single instance. Unhealthy only at
+   * `saturated`; `degraded` still serves.
+   */
+  readinessCheck(options?: {
+    name?: string;
+    critical?: boolean;
+  }): HealthCheck;
+}
+declare module "fastify" {
+  interface FastifyInstance {
+    pressure: PressureApi;
+  }
+}
+declare const pressurePlugin: FastifyPluginAsync<PressureOptions>;
+/**
+ * `fp()`-wrapped so `fastify.pressure` is visible to the whole app rather than
+ * trapped in this plugin's encapsulation context — the named export above is
+ * the raw plugin, matching every other arc plugin entry.
+ */
+declare const _default$5: FastifyPluginAsync<PressureOptions>;
+//#endregion
 //#region src/plugins/replyHelpers.d.ts
 declare module "fastify" {
   interface FastifyReply {
@@ -166,6 +251,6 @@ declare function createRequestIdGenerator(opts?: Pick<RequestIdOptions, "header"
   headers: Record<string, string | string[] | undefined>;
 }) => string;
 declare const requestIdPlugin: FastifyPluginAsync<RequestIdOptions>;
-declare const _default$6: FastifyPluginAsync<RequestIdOptions>;
+declare const _default$7: FastifyPluginAsync<RequestIdOptions>;
 //#endregion
-export { type ArcCore, type ArcCorePluginOptions, type ArcPlugin, type CachingOptions, type CachingRule, type ChangeOperation, type CreatePluginDefinition, type ErrorHandlerOptions, type ErrorMapper, type GracefulShutdownOptions, type HealthCheck, type HealthOptions, type MetricEntry, type MetricsCollector, type MetricsOptions, type PluginMeta, type PluginResourceResult, type RealtimeOptions, type RequestIdOptions, type SSEOptions, type ScheduleDefinition, type ScheduleStats, type SchedulesPluginOptions, type TracingOptions, type VersioningOptions, _default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, _default$1 as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, createRequestIdGenerator, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, _default$2 as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, _default$3 as healthPlugin, healthPlugin as healthPluginFn, _default$4 as metricsPlugin, metricsPlugin as metricsPluginFn, _default$5 as realtimePlugin, realtimePlugin as realtimePluginFn, replyHelpersPlugin, _default$6 as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sanitizeRequestId, _default$7 as schedulesPlugin, schedulesPlugin as schedulesPluginFn, _default$8 as ssePlugin, ssePlugin as ssePluginFn, _default$9 as versioningPlugin, versioningPlugin as versioningPluginFn };
+export { type ArcCore, type ArcCorePluginOptions, type ArcPlugin, type CachingOptions, type CachingRule, type ChangeOperation, type CreatePluginDefinition, type ErrorHandlerOptions, type ErrorMapper, type GracefulShutdownOptions, type HealthCheck, type HealthOptions, type MetricEntry, type MetricsCollector, type MetricsOptions, type PluginMeta, type PluginResourceResult, type PressureApi, type PressureOptions, type PressureSignal, type PressureSnapshot, type PressureState, type PressureThresholds, type RealtimeOptions, type RequestIdOptions, type SSEOptions, type ScheduleDefinition, type ScheduleStats, type SchedulesPluginOptions, type TracingOptions, type VersioningOptions, _default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, _default$1 as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, createRequestIdGenerator, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, _default$2 as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, _default$3 as healthPlugin, healthPlugin as healthPluginFn, _default$4 as metricsPlugin, metricsPlugin as metricsPluginFn, _default$5 as pressurePlugin, pressurePlugin as pressurePluginFn, _default$6 as realtimePlugin, realtimePlugin as realtimePluginFn, replyHelpersPlugin, _default$7 as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sanitizeRequestId, _default$8 as schedulesPlugin, schedulesPlugin as schedulesPluginFn, _default$9 as ssePlugin, ssePlugin as ssePluginFn, _default$10 as versioningPlugin, versioningPlugin as versioningPluginFn };

package/dist/plugins/index.mjs

@@ -1,20 +1,22 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-import { p as MUTATION_OPERATIONS } from "../constants-BxCoxmiN.mjs";
-import { c as getOrgId } from "../types-CoqIRrkY.mjs";
-import { n as requestContext } from "../requestContext-uYE35JxI.mjs";
-import { t as hasEvents } from "../typeGuards-jjKJDN13.mjs";
-import { t as HookSystem } from "../HookSystem-DqXkMXkB.mjs";
-import { t as ResourceRegistry } from "../ResourceRegistry-DoALUlOO.mjs";
-import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-CasG2A28.mjs";
-import { n as caching_default, t as cachingPlugin } from "../caching-BcGmvnHh.mjs";
-import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-C7xBqHsI.mjs";
-import { n as metrics_default, t as metricsPlugin } from "../metrics-D7uchLjN.mjs";
-import { n as realtime_default, t as realtimePlugin } from "../realtime-CTkv3O59.mjs";
-import { t as replyHelpersPlugin } from "../replyHelpers-BSBVCwL3.mjs";
-import { n as schedules_default, t as schedulesPlugin } from "../schedules-CAcZgia0.mjs";
-import { n as sse_default, t as ssePlugin } from "../sse-Cf0jUHsh.mjs";
-import { n as versioning_default, t as versioningPlugin } from "../versioning-rZbyLVD-.mjs";
+/*! @classytic/arc v2.35.0 | MIT | https://classytic.com */
+import { p as MUTATION_OPERATIONS } from "../constants-BhzLXCfN.mjs";
+import { arcLog } from "../logger/index.mjs";
+import { c as getOrgId } from "../types-GY4kATJb.mjs";
+import { n as requestContext } from "../requestContext-DzOUGNdY.mjs";
+import { t as hasEvents } from "../typeGuards-B-_jqaMi.mjs";
+import { t as HookSystem } from "../HookSystem-LlPm3Anm.mjs";
+import { t as ResourceRegistry } from "../ResourceRegistry-yuD1Ra53.mjs";
+import { a as requestIdPlugin, i as createRequestIdGenerator, n as health_default, o as requestId_default, s as sanitizeRequestId, t as healthPlugin } from "../health-_Zs3R_Sb.mjs";
+import { n as caching_default, t as cachingPlugin } from "../caching-cN5X9VEL.mjs";
+import { n as errorHandlerPlugin, t as defaultIsDuplicateKeyError } from "../errorHandler-BbQ1nQdk.mjs";
+import { n as metrics_default, t as metricsPlugin } from "../metrics-5LNPvL3P.mjs";
+import { n as realtime_default, t as realtimePlugin } from "../realtime-Cfl2bVjj.mjs";
+import { t as replyHelpersPlugin } from "../replyHelpers-2jfmMnnV.mjs";
+import { n as schedules_default, t as schedulesPlugin } from "../schedules-BLpZLWGF.mjs";
+import { n as sse_default, t as ssePlugin } from "../sse-DUIP1XH6.mjs";
+import { n as versioning_default, t as versioningPlugin } from "../versioning-BbTs4pwM.mjs";
 import fp from "fastify-plugin";
+import { performance as performance$1 } from "node:perf_hooks";
 //#region src/core/arcCorePlugin.ts
 const arcCorePlugin = async (fastify, opts = {}) => {
 	const { emitEvents = true, hookSystem, registry } = opts;
@@ -205,4 +207,153 @@ var gracefulShutdown_default = fp(gracefulShutdownPlugin, {
 	fastify: "5.x"
 });
 //#endregion
-export { arcCorePlugin_default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, caching_default as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, createRequestIdGenerator, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, gracefulShutdown_default as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, health_default as healthPlugin, healthPlugin as healthPluginFn, metrics_default as metricsPlugin, metricsPlugin as metricsPluginFn, realtime_default as realtimePlugin, realtimePlugin as realtimePluginFn, replyHelpersPlugin, requestId_default as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sanitizeRequestId, schedules_default as schedulesPlugin, schedulesPlugin as schedulesPluginFn, sse_default as ssePlugin, ssePlugin as ssePluginFn, versioning_default as versioningPlugin, versioningPlugin as versioningPluginFn };
+//#region src/plugins/pressure.ts
+/**
+* Admission control — ONE place that decides "are we saturated?".
+*
+* Arc already sheds on event-loop lag (`@fastify/under-pressure`), but lag is
+* LATE: by the time the loop is behind, the work causing it is already
+* admitted. What actually saturates a backend — a drained pool, an undrained
+* queue, an outbox falling behind — is invisible to it. Rate limiting is a
+* different axis: it bounds request FREQUENCY, this bounds concurrent
+* EXPENSIVE WORK.
+*
+* Signals are REGISTERED, not enumerated, because only ELU has a source arc
+* can read today — no kit exposes pool stats, no queue exposes depth. Arc owns
+* the DECISION; signals come from whoever can produce them.
+*
+* `read()` returns SATURATION in [0,1]. Each signal normalises itself: 90% of
+* a pool is nearly fatal, 90% ELU is merely busy, and only the signal's author
+* knows which.
+*
+* @example
+* ```typescript
+* await app.register(pressurePlugin, {
+*   signals: [{ name: 'db-pool', read: () => pool.borrowed / pool.size }],
+*   shed: true,
+* });
+* ```
+*/
+const log = arcLog("pressure");
+/**
+* Event-loop utilisation as saturation — already a [0,1] ratio, and measured
+* ACROSS the interval rather than instantaneously: one lag reading is a spike,
+* utilisation over a second is load.
+*/
+function eluSignal() {
+	let previous = performance$1.eventLoopUtilization();
+	return {
+		name: "event-loop",
+		read() {
+			const current = performance$1.eventLoopUtilization();
+			const delta = performance$1.eventLoopUtilization(current, previous);
+			previous = current;
+			return delta.utilization;
+		}
+	};
+}
+const clamp = (n) => Number.isFinite(n) ? Math.min(1, Math.max(0, n)) : 0;
+const pressurePlugin = async (fastify, options) => {
+	const degradedAt = options.thresholds?.degraded ?? .8;
+	const saturatedAt = options.thresholds?.saturated ?? .95;
+	if (degradedAt > saturatedAt) throw new Error(`pressurePlugin: thresholds.degraded (${degradedAt}) is above thresholds.saturated (${saturatedAt}) — 'saturated' would be unreachable and the app would never shed.`);
+	const signals = [...options.eventLoopUtilization === false ? [] : [eluSignal()], ...options.signals ?? []];
+	/** Signals that threw. Logged once each — a broken reader must not spam. */
+	const broken = /* @__PURE__ */ new Set();
+	let snapshot = {
+		state: "ok",
+		worst: void 0,
+		signals: {}
+	};
+	async function sample() {
+		const values = {};
+		let worst;
+		for (const signal of signals) {
+			let value = 0;
+			try {
+				value = clamp(await signal.read());
+				broken.delete(signal.name);
+			} catch (error) {
+				if (!broken.has(signal.name)) {
+					broken.add(signal.name);
+					log.warn("pressure signal failed to read; treating as 0", {
+						signal: signal.name,
+						error
+					});
+				}
+			}
+			values[signal.name] = value;
+			if (!worst || value > worst.value) worst = {
+				name: signal.name,
+				value
+			};
+		}
+		const peak = worst?.value ?? 0;
+		const next = peak >= saturatedAt ? "saturated" : peak >= degradedAt ? "degraded" : "ok";
+		const previous = snapshot.state;
+		snapshot = {
+			state: next,
+			worst,
+			signals: values
+		};
+		if (next !== previous) {
+			log.info("pressure state changed", {
+				from: previous,
+				to: next,
+				worst
+			});
+			options.onStateChange?.(next, snapshot);
+		}
+	}
+	const timer = setInterval(() => {
+		sample();
+	}, options.intervalMs ?? 1e3);
+	timer.unref?.();
+	fastify.addHook("onClose", async () => clearInterval(timer));
+	fastify.decorate("pressure", {
+		state: () => snapshot.state,
+		snapshot: () => snapshot,
+		register: (signal) => {
+			signals.push(signal);
+		},
+		shouldShed: () => snapshot.state === "saturated",
+		readinessCheck: (checkOptions) => ({
+			name: checkOptions?.name ?? "pressure",
+			critical: checkOptions?.critical ?? true,
+			check: () => snapshot.state !== "saturated"
+		})
+	});
+	if (options.shed) {
+		const shedConfig = options.shed === true ? {} : options.shed;
+		const statusCode = shedConfig.statusCode ?? 503;
+		const retryAfter = shedConfig.retryAfterSeconds ?? 1;
+		const exempt = [
+			"/_health",
+			"/health",
+			...shedConfig.exclude ?? []
+		];
+		fastify.addHook("onRequest", async (request, reply) => {
+			if (snapshot.state !== "saturated") return;
+			const url = request.url;
+			if (exempt.some((prefix) => url.startsWith(prefix))) return;
+			reply.header("Retry-After", String(retryAfter));
+			return reply.code(statusCode).send({
+				code: "arc.unavailable",
+				message: "Server is at capacity — retry shortly.",
+				status: statusCode
+			});
+		});
+	}
+	await sample();
+};
+/**
+* `fp()`-wrapped so `fastify.pressure` is visible to the whole app rather than
+* trapped in this plugin's encapsulation context — the named export above is
+* the raw plugin, matching every other arc plugin entry.
+*/
+var pressure_default = fp(pressurePlugin, {
+	name: "arc-pressure",
+	fastify: "5.x"
+});
+//#endregion
+export { arcCorePlugin_default as arcCorePlugin, arcCorePlugin as arcCorePluginFn, caching_default as cachingPlugin, cachingPlugin as cachingPluginFn, createPlugin, createRequestIdGenerator, defaultIsDuplicateKeyError, errorHandlerPlugin, errorHandlerPlugin as errorHandlerPluginFn, gracefulShutdown_default as gracefulShutdownPlugin, gracefulShutdownPlugin as gracefulShutdownPluginFn, health_default as healthPlugin, healthPlugin as healthPluginFn, metrics_default as metricsPlugin, metricsPlugin as metricsPluginFn, pressure_default as pressurePlugin, pressurePlugin as pressurePluginFn, realtime_default as realtimePlugin, realtimePlugin as realtimePluginFn, replyHelpersPlugin, requestId_default as requestIdPlugin, requestIdPlugin as requestIdPluginFn, sanitizeRequestId, schedules_default as schedulesPlugin, schedulesPlugin as schedulesPluginFn, sse_default as ssePlugin, ssePlugin as ssePluginFn, versioning_default as versioningPlugin, versioningPlugin as versioningPluginFn };

package/dist/plugins/response-cache.mjs

@@ -1,5 +1,5 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
-import { t as hasEvents } from "../typeGuards-jjKJDN13.mjs";
+/*! @classytic/arc v2.35.0 | MIT | https://classytic.com */
+import { t as hasEvents } from "../typeGuards-B-_jqaMi.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/response-cache.ts
 /**

package/dist/plugins/tracing-entry.mjs

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.35.0 | MIT | https://classytic.com */
 import { createRequire } from "node:module";
 import fp from "fastify-plugin";
 //#region src/plugins/tracing.ts
@@ -59,7 +59,7 @@ try {
 function createTracerProvider(options) {
 	if (!isAvailable || !NodeTracerProvider || !BatchSpanProcessor || !OTLPTraceExporter) return null;
 	const { serviceName = "@classytic/arc", serviceVersion, exporterUrl = "http://localhost:4318/v1/traces" } = options;
-	const resolvedVersion = serviceVersion ?? "2.34.0";
+	const resolvedVersion = serviceVersion ?? "2.35.0";
 	const exporter = new OTLPTraceExporter({ url: exporterUrl });
 	const provider = new NodeTracerProvider({ resource: { attributes: {
 		"service.name": serviceName,

package/dist/{pluralize-B7xf8qZF.mjs → pluralize-DGAQQKL8.mjs}

@@ -1,4 +1,4 @@
-/*! @classytic/arc v2.34.0 | MIT | https://classytic.com */
+/*! @classytic/arc v2.35.0 | MIT | https://classytic.com */
 //#region src/utils/pluralize.ts
 /**
 * Lightweight English pluralization for the Arc CLI.