@classytic/arc 2.22.0 → 2.25.0

package/dist/{utils-FhJ88TJE.mjs → utils-taUVD4p3.mjs}

@@ -1,358 +1,8 @@
-import { m as RESERVED_QUERY_PARAMS, t as CRUD_OPERATIONS } from "./constants-DNre0wRg.mjs";
+import { m as RESERVED_QUERY_PARAMS } from "./constants-DNre0wRg.mjs";
 import { arcLog } from "./logger/index.mjs";
 import { t as ArcError } from "./errors-DkO8Nk6-.mjs";
-import { r as getAvailablePresets } from "./presets-gw0ciIUD.mjs";
 import { errorContractSchema as errorContractSchema$1, errorDetailSchema as errorDetailSchema$1 } from "@classytic/repo-core/errors";
-//#region src/utils/simpleEqualityMatcher.ts
-/**
-* `simpleEqualityMatcher` — a minimal, dialect-agnostic flat-key equality
-* matcher for `DataAdapter.matchesFilter` / `BaseController({ matchesFilter })`.
-*
-* **What it does:** for each `[key, expected]` in the filter, compares
-* `item[key]` to `expected` via string coercion (so Mongo `ObjectId` values
-* match their string representation) and returns `true` only if every
-* filter entry matches. Array item values are matched implicitly (contains).
-*
-* **What it does NOT do:**
-* - No `$eq` / `$ne` / `$in` / `$nin` / `$gt` / `$lt` / `$regex` / `$exists`
-* - No `$and` / `$or`
-* - No dot-path traversal (`"owner.id"`)
-* - No schema-specific coercion
-*
-* **Why it exists:** 95%+ of arc's `_policyFilters` are produced by built-in
-* permission helpers and are shaped like `{ ownerId: "u1" }` or
-* `{ organizationId: "org_x" }` — flat equality. For that common shape,
-* this helper is a safe, tested, 15-line defense-in-depth matcher that
-* hosts using minimal repos (no `getOne(compoundFilter)` DB path) can opt
-* into without arc shipping a full Mongo-syntax engine.
-*
-* **When to use:**
-* - Your adapter/repo doesn't natively filter on `getOne(compoundFilter)`
-* - Your `_policyFilters` are flat equality (from arc's built-in permission helpers)
-* - You want defense-in-depth on `validateItemAccess` / `fetchDetailed`'s `getById` fallback
-*
-* **When NOT to use:**
-* - Your `_policyFilters` use operators (`$in`, `$ne`, etc.) — supply a
-*   native matcher (mongokit's repo does the filter at the DB layer; for
-*   custom repos, wrap the kit's own predicate engine).
-* - You're a mongokit / sqlitekit / Prisma user — the DB-level filter
-*   applied by `getOne(compoundFilter)` already covers this.
-*
-* @example
-* ```ts
-* import { simpleEqualityMatcher } from '@classytic/arc/utils';
-*
-* // On a custom adapter
-* const adapter: DataAdapter = {
-*   repository,
-*   type: 'custom',
-*   name: 'in-memory',
-*   matchesFilter: simpleEqualityMatcher,
-* };
-*
-* // Or directly on BaseController for ad-hoc controllers
-* new BaseController(repo, { matchesFilter: simpleEqualityMatcher });
-* ```
-*/
-function simpleEqualityMatcher(item, filters) {
-	if (!item || typeof item !== "object") return false;
-	const obj = item;
-	for (const [key, expected] of Object.entries(filters)) {
-		if (expected && typeof expected === "object" && !Array.isArray(expected) && Object.getPrototypeOf(expected) === Object.prototype && Object.keys(expected).some((k) => k.startsWith("$"))) return false;
-		const actual = obj[key];
-		if (Array.isArray(actual)) {
-			const expectedStr = String(expected);
-			if (!actual.some((v) => String(v) === expectedStr)) return false;
-			continue;
-		}
-		if (String(actual) !== String(expected)) return false;
-	}
-	return true;
-}
-//#endregion
-//#region src/core/validateResourceConfig.ts
-/**
-* Resource Configuration Validator
-*
-* Fail-fast validation at definition time.
-* Invalid configs throw immediately with clear, actionable errors.
-*
-* @example
-* const result = validateResourceConfig(config);
-* if (!result.valid) {
-*   console.error(formatValidationErrors(result.errors));
-* }
-*/
-/**
-* Validate a resource configuration
-*/
-function validateResourceConfig(config, options = {}) {
-	const errors = [];
-	const warnings = [];
-	if (!config.name) errors.push({
-		field: "name",
-		message: "Resource name is required",
-		suggestion: "Add a unique resource name (e.g., \"product\", \"user\")"
-	});
-	else if (!/^[a-z][a-z0-9-]*$/i.test(config.name)) errors.push({
-		field: "name",
-		message: `Invalid resource name "${config.name}"`,
-		suggestion: "Use alphanumeric characters and hyphens, starting with a letter"
-	});
-	const crudRoutes = CRUD_OPERATIONS;
-	const disabledRoutes = new Set(config.disabledRoutes ?? []);
-	const enabledCrudRoutes = crudRoutes.filter((route) => !disabledRoutes.has(route));
-	if (!config.disableDefaultRoutes && enabledCrudRoutes.length > 0) {
-		if (!config.adapter) errors.push({
-			field: "adapter",
-			message: "Data adapter is required when CRUD routes are enabled",
-			suggestion: "Provide an adapter: createMongooseAdapter({ model, repository })"
-		});
-		else if (!config.adapter.repository) errors.push({
-			field: "adapter.repository",
-			message: "Adapter must provide a repository",
-			suggestion: "Ensure your adapter returns a valid StandardRepo (see @classytic/repo-core)"
-		});
-	} else if (!config.adapter && !config.routes?.length) warnings.push({
-		field: "config",
-		message: "Resource has no adapter and no routes",
-		suggestion: "Provide either adapter for CRUD or routes for custom logic"
-	});
-	if (config.controller && !options.skipControllerCheck && !config.disableDefaultRoutes) {
-		const ctrl = config.controller;
-		const requiredMethods = CRUD_OPERATIONS;
-		for (const method of requiredMethods) if (typeof ctrl[method] !== "function") errors.push({
-			field: `controller.${method}`,
-			message: `Missing required CRUD method "${method}"`,
-			suggestion: "Extend BaseController which implements IController interface"
-		});
-	}
-	if (config.controller && config.routes) validateRouteHandlers(config.controller, config.routes, errors);
-	if (config.permissions) validatePermissionKeys(config, options, errors, warnings);
-	if (config.presets && !options.allowUnknownPresets) validatePresets(config.presets, errors, warnings);
-	if (config.prefix) {
-		if (!config.prefix.startsWith("/")) errors.push({
-			field: "prefix",
-			message: `Prefix must start with "/" (got "${config.prefix}")`,
-			suggestion: `Change to "/${config.prefix}"`
-		});
-		if (config.prefix.endsWith("/") && config.prefix !== "/") warnings.push({
-			field: "prefix",
-			message: `Prefix should not end with "/" (got "${config.prefix}")`,
-			suggestion: `Change to "${config.prefix.slice(0, -1)}"`
-		});
-	}
-	if (config.routes) {
-		validateRoutes(config.routes, errors);
-		validateRouteCrudCollisions(config, errors);
-	}
-	return {
-		valid: errors.length === 0,
-		errors,
-		warnings
-	};
-}
-function validateRouteHandlers(controller, routes, errors) {
-	const ctrl = controller;
-	for (const route of routes) if (typeof route.handler === "string") {
-		if (typeof ctrl[route.handler] !== "function") errors.push({
-			field: `routes[${route.method} ${route.path}]`,
-			message: `Handler "${route.handler}" not found on controller`,
-			suggestion: `Add method "${route.handler}" to controller or use a function handler`
-		});
-	}
-}
-function validatePermissionKeys(config, options, _errors, warnings) {
-	const validKeys = /* @__PURE__ */ new Set([...CRUD_OPERATIONS, ...options.additionalPermissionKeys ?? []]);
-	for (const route of config.routes ?? []) if (typeof route.handler === "string") validKeys.add(route.handler);
-	for (const preset of config.presets ?? []) {
-		const presetName = typeof preset === "string" ? preset : preset.name;
-		if (presetName === "softDelete") {
-			validKeys.add("deleted");
-			validKeys.add("restore");
-		}
-		if (presetName === "slugLookup") validKeys.add("getBySlug");
-		if (presetName === "tree") {
-			validKeys.add("tree");
-			validKeys.add("children");
-			validKeys.add("getTree");
-			validKeys.add("getChildren");
-		}
-	}
-	for (const key of Object.keys(config.permissions ?? {})) if (!validKeys.has(key)) warnings.push({
-		field: `permissions.${key}`,
-		message: `Unknown permission key "${key}"`,
-		suggestion: `Valid keys: ${Array.from(validKeys).join(", ")}`
-	});
-}
-function validatePresets(presets, errors, warnings) {
-	const availablePresets = getAvailablePresets();
-	for (const preset of presets) {
-		if (typeof preset === "object" && ("middlewares" in preset || "routes" in preset)) continue;
-		const presetName = typeof preset === "string" ? preset : preset.name;
-		if (!availablePresets.includes(presetName)) errors.push({
-			field: "presets",
-			message: `Unknown preset "${presetName}"`,
-			suggestion: `Available presets: ${availablePresets.join(", ")}`
-		});
-		if (typeof preset === "object") validatePresetOptions(preset, warnings);
-	}
-}
-function validatePresetOptions(preset, warnings) {
-	const validOptions = {
-		slugLookup: ["slugField"],
-		tree: ["parentField"],
-		softDelete: ["deletedField"],
-		ownedByUser: ["ownerField"],
-		multiTenant: ["tenantField", "allowPublic"]
-	}[preset.name] ?? [];
-	const providedOptions = Object.keys(preset).filter((k) => k !== "name");
-	for (const opt of providedOptions) if (!validOptions.includes(opt)) warnings.push({
-		field: `presets[${preset.name}].${opt}`,
-		message: `Unknown option "${opt}" for preset "${preset.name}"`,
-		suggestion: validOptions.length > 0 ? `Valid options: ${validOptions.join(", ")}` : `Preset "${preset.name}" has no configurable options`
-	});
-}
-/**
-* Detect collisions between user-declared `routes:` entries and the
-* auto-CRUD route table that `createCrudRouter` will register.
-*
-* Without this check, a custom `POST /` on the same prefix as auto-CRUD's
-* `create` boots fine through `defineResource()` and only blows up at
-* `app.register()` time with Fastify's opaque `FST_ERR_DUPLICATED_ROUTE`.
-* That error doesn't mention `disabledRoutes` and doesn't distinguish
-* "you collided with auto-CRUD" from "you collided with yourself" — so
-* the consumer has to grep arc's source to discover the fix.
-*
-* We surface the fix in the error message, naming the conflicting op
-* and the literal line to add.
-*
-* Honored config:
-*   - `disableDefaultRoutes: true` → no auto-CRUD, no collisions possible
-*   - `disabledRoutes: ['create']` → that op's path is free for custom use
-*   - `updateMethod: 'PUT' | 'both'` → update slot covers PUT/PATCH accordingly
-*/
-function validateRouteCrudCollisions(config, errors) {
-	if (config.disableDefaultRoutes) return;
-	if (!config.routes || config.routes.length === 0) return;
-	const updateMethod = config.updateMethod ?? "PATCH";
-	const updateMethods = updateMethod === "both" ? ["PUT", "PATCH"] : [updateMethod];
-	const disabled = new Set(config.disabledRoutes ?? []);
-	const crudTable = [
-		{
-			op: "list",
-			method: "GET",
-			path: "/"
-		},
-		{
-			op: "get",
-			method: "GET",
-			path: "/:id"
-		},
-		{
-			op: "create",
-			method: "POST",
-			path: "/"
-		},
-		...updateMethods.map((m) => ({
-			op: "update",
-			method: m,
-			path: "/:id"
-		})),
-		{
-			op: "delete",
-			method: "DELETE",
-			path: "/:id"
-		}
-	];
-	for (const [i, route] of config.routes.entries()) {
-		if (!route.method || !route.path) continue;
-		for (const crud of crudTable) {
-			if (disabled.has(crud.op)) continue;
-			if (route.method !== crud.method || route.path !== crud.path) continue;
-			errors.push({
-				field: `routes[${i}]`,
-				message: `Route ${route.method} ${route.path} collides with auto-CRUD "${crud.op}"`,
-				suggestion: `Add \`disabledRoutes: ['${crud.op}']\` to suppress the auto-CRUD route, or move your custom handler to a different path. Set \`disableDefaultRoutes: true\` to disable all auto-CRUD on this resource.`
-			});
-		}
-	}
-}
-function validateRoutes(routes, errors) {
-	const validMethods = [
-		"GET",
-		"POST",
-		"PUT",
-		"PATCH",
-		"DELETE",
-		"OPTIONS",
-		"HEAD"
-	];
-	const seenRoutes = /* @__PURE__ */ new Set();
-	for (const [i, route] of routes.entries()) {
-		if (!validMethods.includes(route.method)) errors.push({
-			field: `routes[${i}].method`,
-			message: `Invalid HTTP method "${route.method}"`,
-			suggestion: `Valid methods: ${validMethods.join(", ")}`
-		});
-		if (!route.path) errors.push({
-			field: `routes[${i}].path`,
-			message: "Route path is required"
-		});
-		else if (!route.path.startsWith("/")) errors.push({
-			field: `routes[${i}].path`,
-			message: `Route path must start with "/" (got "${route.path}")`,
-			suggestion: `Change to "/${route.path}"`
-		});
-		const routeWithRefs = route;
-		if (!route.handler && typeof routeWithRefs.controllerMethod !== "function") errors.push({
-			field: `routes[${i}].handler`,
-			message: "Route must declare either `handler` (string / function) or `controllerMethod`",
-			suggestion: "Prefer `controllerMethod: (c: MyController) => c.method` for typed handler refs."
-		});
-		const routeKey = `${route.method} ${route.path}`;
-		if (seenRoutes.has(routeKey)) errors.push({
-			field: `routes[${i}]`,
-			message: `Duplicate route "${routeKey}"`
-		});
-		seenRoutes.add(routeKey);
-	}
-}
-/**
-* Format validation errors for display
-*/
-function formatValidationErrors(resourceName, result) {
-	const lines = [];
-	if (result.errors.length > 0) {
-		lines.push(`Resource "${resourceName}" validation failed:`);
-		lines.push("");
-		lines.push("ERRORS:");
-		for (const err of result.errors) {
-			lines.push(`  ✗ ${err.field}: ${err.message}`);
-			if (err.suggestion) lines.push(`    → ${err.suggestion}`);
-		}
-	}
-	if (result.warnings.length > 0) {
-		if (lines.length > 0) lines.push("");
-		lines.push("WARNINGS:");
-		for (const warn of result.warnings) {
-			lines.push(`  ⚠ ${warn.field}: ${warn.message}`);
-			if (warn.suggestion) lines.push(`    → ${warn.suggestion}`);
-		}
-	}
-	return lines.join("\n");
-}
-/**
-* Validate and throw if invalid
-*/
-function assertValidConfig(config, options) {
-	const result = validateResourceConfig(config, options);
-	if (!result.valid) {
-		const errorMsg = formatValidationErrors(config.name ?? "unknown", result);
-		throw new Error(errorMsg);
-	}
-}
-//#endregion
+import { scheduleBackground } from "@classytic/repo-core/cache";
 //#region src/utils/circuitBreaker.ts
 /**
 * Circuit Breaker Pattern
@@ -404,10 +54,13 @@ var CircuitBreaker = class {
 	nextAttempt = 0;
 	lastCallAt = null;
 	openedAt = null;
+	halfOpenInFlight = 0;
 	failureThreshold;
 	resetTimeout;
 	timeout;
 	successThreshold;
+	halfOpenMaxProbes;
+	propagateAbort;
 	fallback;
 	onStateChange;
 	onError;
@@ -419,6 +72,8 @@ var CircuitBreaker = class {
 		this.resetTimeout = options.resetTimeout ?? 6e4;
 		this.timeout = options.timeout ?? 1e4;
 		this.successThreshold = options.successThreshold ?? 1;
+		this.halfOpenMaxProbes = options.halfOpenMaxProbes ?? 1;
+		this.propagateAbort = options.propagateAbort ?? false;
 		this.fallback = options.fallback;
 		this.onStateChange = options.onStateChange;
 		this.onError = options.onError;
@@ -438,6 +93,15 @@ var CircuitBreaker = class {
 			}
 			this.setState(CircuitState.HALF_OPEN);
 		}
+		let isProbe = false;
+		if (this.state === CircuitState.HALF_OPEN) {
+			if (this.halfOpenInFlight >= this.halfOpenMaxProbes) {
+				if (this.fallback) return this.fallback(...args);
+				throw new CircuitBreakerError(`Circuit breaker is HALF_OPEN for ${this.name} — probe slots full`, CircuitState.HALF_OPEN);
+			}
+			this.halfOpenInFlight++;
+			isProbe = true;
+		}
 		try {
 			const result = await this.executeWithTimeout(args);
 			this.onSuccess();
@@ -445,17 +109,24 @@ var CircuitBreaker = class {
 		} catch (err) {
 			this.onFailure(err instanceof Error ? err : new Error(String(err)));
 			throw err;
+		} finally {
+			if (isProbe) this.halfOpenInFlight--;
 		}
 	}
 	/**
-	* Execute function with timeout
+	* Execute function with timeout. With `propagateAbort`, the wrapped fn
+	* receives a trailing AbortSignal that fires on timeout — the breaker's
+	* timeout otherwise only rejects the CALLER while the underlying work
+	* keeps consuming sockets/pool slots to completion.
 	*/
 	async executeWithTimeout(args) {
+		const controller = this.propagateAbort ? new AbortController() : void 0;
 		return new Promise((resolve, reject) => {
 			const timeoutId = setTimeout(() => {
+				controller?.abort(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
 				reject(/* @__PURE__ */ new Error(`Request timeout after ${this.timeout}ms`));
 			}, this.timeout);
-			this.fn(...args).then((result) => {
+			(controller ? this.fn(...args, controller.signal) : this.fn(...args)).then((result) => {
 				clearTimeout(timeoutId);
 				resolve(result);
 			}).catch((error) => {
@@ -638,6 +309,21 @@ function createCircuitBreakerRegistry() {
 //#endregion
 //#region src/utils/compensation.ts
 /**
+* Observability hooks must never alter the transaction: a throwing metrics
+* sink must not fail a step that succeeded, trigger compensation, or become
+* an unhandled rejection from a detached fire-and-forget chain. Containment
+* is reported via `hooks.onHookError` so broken sinks stay visible.
+*/
+function safeHook(name, invoke, hooks) {
+	try {
+		invoke();
+	} catch (err) {
+		try {
+			hooks?.onHookError?.(name, err instanceof Error ? err : new Error(String(err)));
+		} catch {}
+	}
+}
+/**
 * Run steps in order with automatic compensation on failure.
 *
 * @typeParam TCtx - Context type shared across steps (defaults to Record<string, unknown>)
@@ -649,8 +335,7 @@ async function withCompensation(_name, steps, initialContext, hooks) {
 	const completed = [];
 	for (const step of steps) {
 		if (step.fireAndForget) {
-			completedSteps.push(step.name);
-			step.execute(ctx).then((result) => hooks?.onStepComplete?.(step.name, result), () => {});
+			step.execute(ctx).then((result) => safeHook("onStepComplete", () => hooks?.onStepComplete?.(step.name, result), hooks), (err) => safeHook("onStepFailed", () => hooks?.onStepFailed?.(step.name, err instanceof Error ? err : new Error(String(err))), hooks)).catch(() => {});
 			continue;
 		}
 		try {
@@ -661,10 +346,10 @@ async function withCompensation(_name, steps, initialContext, hooks) {
 				step,
 				result
 			});
-			hooks?.onStepComplete?.(step.name, result);
+			safeHook("onStepComplete", () => hooks?.onStepComplete?.(step.name, result), hooks);
 		} catch (err) {
 			const error = err instanceof Error ? err : new Error(String(err));
-			hooks?.onStepFailed?.(step.name, error);
+			safeHook("onStepFailed", () => hooks?.onStepFailed?.(step.name, error), hooks);
 			const compensationErrors = await rollback(ctx, completed, hooks);
 			return {
 				success: false,
@@ -690,7 +375,7 @@ async function rollback(ctx, completed, hooks) {
 		const compensateFn = entry.step.compensate;
 		try {
 			await compensateFn(ctx, entry.result);
-			hooks?.onCompensate?.(entry.step.name);
+			safeHook("onCompensate", () => hooks?.onCompensate?.(entry.step.name), hooks);
 		} catch (err) {
 			errors.push({
 				step: entry.step.name,
@@ -850,6 +535,8 @@ function handleRaw(handler, statusCode = 200) {
 * defineResource({ name: 'product', adapter: ... });
 *
 * // Use MongoKit's QueryParser (recommended for MongoDB - has $lookup, aggregations, etc.)
+* // Fail-closed by default (mongokit >=3.25): invalid/blocked query input
+* // becomes HTTP 400 instead of a silently broadened result set.
 * import { QueryParser } from '@classytic/mongokit';
 * defineResource({
 *   name: 'product',
@@ -1652,13 +1339,6 @@ function getDefaultCrudSchemas() {
 	});
 }
 //#endregion
-//#region src/utils/runtime.ts
-/**
-* Portable "run on next tick" scheduler. `setImmediate` is Node-only — not
-* available in Bun workers, Deno, Cloudflare Workers, or edge runtimes.
-*/
-const scheduleBackground = typeof setImmediate === "function" ? (cb) => void setImmediate(cb) : (cb) => queueMicrotask(cb);
-//#endregion
 //#region src/utils/stateMachine.ts
 /**
 * Create a state machine for validating transitions
@@ -1760,22 +1440,4 @@ function createStateMachine(name, transitions = {}, options = {}) {
 	};
 }
 //#endregion
-//#region src/utils/userHelpers.ts
-/**
-* Extract a user ID from a user object. Accepts `id` or `_id` — returns
-* `undefined` when neither is present. Used by arc's controllers to
-* populate `createdBy` / `updatedBy` fields and for cache scoping.
-*
-* @example
-* ```ts
-* import { getUserId } from '@classytic/arc/utils';
-* const uid = getUserId(request.user);
-* ```
-*/
-function getUserId(user) {
-	if (!user) return void 0;
-	const id = user.id ?? user._id;
-	return id ? String(id) : void 0;
-}
-//#endregion
-export { createCircuitBreaker as A, defineErrorMapper as C, CircuitBreakerError as D, CircuitBreaker as E, simpleEqualityMatcher as F, assertValidConfig as M, formatValidationErrors as N, CircuitBreakerRegistry as O, validateResourceConfig as P, defineGuard as S, withCompensation as T, ArcQueryParser as _, bareListResponse as a, MONGO_DIALECT as b, errorDetailSchema$1 as c, keysetListResponse as d, listResponse as f, responses as g, queryParams as h, aggregateListResponse as i, createCircuitBreakerRegistry as j, CircuitState as k, getDefaultCrudSchemas as l, paginationSchema as m, createStateMachine as n, deleteResponse as o, offsetListResponse as p, scheduleBackground as r, errorContractSchema$1 as s, getUserId as t, getListQueryParams as u, createQueryParser as v, defineCompensation as w, NEUTRAL_DIALECT as x, handleRaw as y };
+export { createCircuitBreakerRegistry as A, defineCompensation as C, CircuitBreakerRegistry as D, CircuitBreakerError as E, CircuitState as O, defineErrorMapper as S, CircuitBreaker as T, createQueryParser as _, deleteResponse as a, NEUTRAL_DIALECT as b, getDefaultCrudSchemas as c, listResponse as d, offsetListResponse as f, ArcQueryParser as g, responses as h, bareListResponse as i, createCircuitBreaker as k, getListQueryParams as l, queryParams as m, scheduleBackground as n, errorContractSchema$1 as o, paginationSchema as p, aggregateListResponse as r, errorDetailSchema$1 as s, createStateMachine as t, keysetListResponse as u, handleRaw as v, withCompensation as w, defineGuard as x, MONGO_DIALECT as y };

package/dist/{validate-C2mGgSXg.mjs → validate-Bk44F2yT.mjs}

@@ -123,7 +123,7 @@ function resolveLimitPolicy(config) {
 function resolveAggRequestLimit(normalized, query) {
 	const policy = normalized.compiled.limitPolicy;
 	if (!policy) return normalized.compiled.limit;
-	const raw = query["limit"];
+	const raw = query.limit;
 	if (raw === void 0 || raw === "") return policy.defaultLimit;
 	const parsed = typeof raw === "number" ? raw : Number.parseInt(String(raw), 10);
 	if (!Number.isFinite(parsed) || parsed <= 0) return policy.defaultLimit;

package/dist/{versioning-DLwklPlG.d.mts → versioning-DXgY5BUm.d.mts}

@@ -1,33 +1,5 @@
 import { n as DomainEvent } from "./EventTransport-QmY7A258.mjs";
 import { FastifyPluginAsync, FastifyRequest } from "fastify";
-//#region src/plugins/health.d.ts
-interface HealthCheck {
-  /** Name of the dependency */
-  name: string;
-  /** Function that returns true if healthy, false otherwise */
-  check: () => Promise<boolean> | boolean;
-  /** Optional timeout in ms (default: 5000) */
-  timeout?: number;
-  /** Whether this check is critical for readiness (default: true) */
-  critical?: boolean;
-}
-interface HealthOptions {
-  /** Route prefix (default: '/_health') */
-  prefix?: string;
-  /** Health check dependencies */
-  checks?: HealthCheck[];
-  /** Enable metrics endpoint (default: false) */
-  metrics?: boolean;
-  /** Custom metrics collector function */
-  metricsCollector?: () => Promise<string> | string;
-  /** Version info to include in responses */
-  version?: string;
-  /** Collect HTTP request metrics (default: true if metrics enabled) */
-  collectHttpMetrics?: boolean;
-}
-declare const healthPlugin: FastifyPluginAsync<HealthOptions>;
-declare const _default$4: FastifyPluginAsync<HealthOptions>;
-//#endregion
 //#region src/plugins/caching.d.ts
 interface CachingRule {
   /** Path prefix to match (e.g., '/api/products') */
@@ -54,7 +26,7 @@ interface CachingOptions {
   rules?: CachingRule[];
 }
 declare const cachingPlugin: FastifyPluginAsync<CachingOptions>;
-declare const _default$3: FastifyPluginAsync<CachingOptions>;
+declare const _default$4: FastifyPluginAsync<CachingOptions>;
 //#endregion
 //#region src/plugins/sse.d.ts
 interface SSEOptions {
@@ -79,7 +51,46 @@ interface SSEOptions {
   tokenQueryParam?: string | null;
 }
 declare const ssePlugin: FastifyPluginAsync<SSEOptions>;
-declare const _default$2: FastifyPluginAsync<SSEOptions>;
+declare const _default$3: FastifyPluginAsync<SSEOptions>;
+//#endregion
+//#region src/plugins/realtime.d.ts
+declare const CHANGE_OPERATIONS: readonly ["created", "updated", "deleted"];
+type ChangeOperation = (typeof CHANGE_OPERATIONS)[number];
+interface RealtimeOptions {
+  /**
+   * Route path — must contain `:resource` (default: `/realtime/:resource`).
+   */
+  path?: string;
+  /** Heartbeat interval in ms (default: 30000). */
+  heartbeat?: number;
+  /**
+   * Subscribable resources. Default: every registered resource — safe
+   * because each subscription runs that resource's own `list` permission;
+   * narrow it when only some resources should have a change feed at all.
+   */
+  resources?: readonly string[];
+  /** Operations streamed (default: created + updated + deleted). */
+  operations?: readonly ChangeOperation[];
+  /**
+   * Query parameter carrying the bearer token for browser `EventSource`
+   * clients (default `'token'`, matching the sse plugin / arc-next).
+   * Set `null` to disable promotion.
+   */
+  tokenQueryParam?: string | null;
+  /**
+   * Hard ceiling (ms) on any single connection's lifetime. Bounds
+   * permission STALENESS: the row filters are snapshotted at connect, so a
+   * caller whose permissions are revoked mid-connection keeps receiving
+   * their old view until they reconnect. Independently, arc ALWAYS closes
+   * the feed when the auth token's `exp` passes (forcing reconnect +
+   * re-authorization with fresh filters) — this option adds a cap for
+   * session/cookie auth that carries no `exp`, or to tighten below the
+   * token TTL. Omit for token-exp-only bounding.
+   */
+  maxConnectionMs?: number;
+}
+declare const realtimePlugin: FastifyPluginAsync<RealtimeOptions>;
+declare const _default$2: FastifyPluginAsync<RealtimeOptions>;
 //#endregion
 //#region src/plugins/metrics.d.ts
 interface MetricsOptions {
@@ -135,6 +146,16 @@ interface VersioningOptions {
   headerName?: string;
   /** Response header name (default: 'x-api-version') */
   responseHeader?: string;
+  /**
+   * Supported versions. When set, a request for any OTHER version is
+   * rejected with `400 arc.unsupported_api_version` (details list the
+   * supported set). When omitted, every requested version is accepted
+   * and merely annotated — detection-only mode.
+   *
+   * The `defaultVersion` must be in this list (boot-time check) so a
+   * versionless request can never be rejected by its own default.
+   */
+  versions?: string[];
   /** Deprecated versions — adds Deprecation + Sunset headers */
   deprecated?: string[];
   /** Sunset date for deprecated versions (ISO 8601) */
@@ -148,4 +169,4 @@ declare module "fastify" {
 declare const versioningPlugin: FastifyPluginAsync<VersioningOptions>;
 declare const _default: FastifyPluginAsync<VersioningOptions>;
 //#endregion
-export { HealthOptions as _, MetricsCollector as a, metricsPlugin as c, ssePlugin as d, CachingOptions as f, HealthCheck as g, cachingPlugin as h, MetricEntry as i, SSEOptions as l, _default$3 as m, _default as n, MetricsOptions as o, CachingRule as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, _default$2 as u, _default$4 as v, healthPlugin as y };
+export { CachingRule as _, MetricsCollector as a, metricsPlugin as c, _default$2 as d, realtimePlugin as f, CachingOptions as g, ssePlugin as h, MetricEntry as i, ChangeOperation as l, _default$3 as m, _default as n, MetricsOptions as o, SSEOptions as p, versioningPlugin as r, _default$1 as s, VersioningOptions as t, RealtimeOptions as u, _default$4 as v, cachingPlugin as y };

package/dist/{versioning-Dk-71iIz.mjs → versioning-gKWyryT3.mjs}

@@ -1,4 +1,5 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.mjs";
+import { d as createDomainError } from "./errors-DkO8Nk6-.mjs";
 import fp from "fastify-plugin";
 //#region src/plugins/versioning.ts
 var versioning_exports = /* @__PURE__ */ __exportAll({
@@ -7,8 +8,10 @@ var versioning_exports = /* @__PURE__ */ __exportAll({
 });
 const PREFIX_REGEX = /^\/v(\d+)\//;
 const versioningPlugin = async (fastify, opts) => {
-	const { type, defaultVersion = "1", headerName = "accept-version", responseHeader = "x-api-version", deprecated = [], sunset } = opts;
+	const { type, defaultVersion = "1", headerName = "accept-version", responseHeader = "x-api-version", versions, deprecated = [], sunset } = opts;
 	const deprecatedSet = new Set(deprecated);
+	const supportedSet = versions ? new Set(versions) : void 0;
+	if (supportedSet && !supportedSet.has(defaultVersion)) throw new Error(`versioningPlugin: defaultVersion '${defaultVersion}' is not in versions [${[...supportedSet].join(", ")}]`);
 	fastify.decorateRequest("apiVersion", defaultVersion);
 	fastify.addHook("onRequest", async (request, reply) => {
 		let version = defaultVersion;
@@ -19,6 +22,10 @@ const versioningPlugin = async (fastify, opts) => {
 			const match = request.url.match(PREFIX_REGEX);
 			if (match) version = match[1] ?? defaultVersion;
 		}
+		if (supportedSet && !supportedSet.has(version)) throw createDomainError("arc.unsupported_api_version", `API version '${version}' is not supported`, 400, {
+			requested: version,
+			supported: [...supportedSet]
+		});
 		request.apiVersion = version;
 		reply.header(responseHeader, version);
 		if (deprecatedSet.has(version)) {