@classytic/arc 2.25.0 → 2.30.0

package/dist/testing/outboxStoreContract.mjs

@@ -0,0 +1,247 @@
+import { OutboxOwnershipError } from "@classytic/primitives/outbox";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+//#region src/testing/outboxStoreContract.ts
+let seq = 0;
+/** A minimal well-formed event. Ids are unique per call. */
+function event(type = "test.event") {
+	seq += 1;
+	return {
+		type,
+		payload: { n: seq },
+		meta: {
+			id: `evt-${Date.now()}-${seq}`,
+			occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+		}
+	};
+}
+const idOf = (e) => e.meta.id;
+function runOutboxStoreContract(name, setup) {
+	describe(`OutboxStore contract: ${name}`, () => {
+		let store;
+		let teardown;
+		let reset;
+		beforeAll(async () => {
+			const result = await setup();
+			store = result.store;
+			teardown = result.teardown;
+			reset = result.reset;
+		});
+		afterAll(async () => {
+			if (teardown) await teardown();
+		});
+		/** Save n events, oldest first. */
+		async function seed(n, type) {
+			if (reset) await reset();
+			const events = [];
+			for (let i = 0; i < n; i++) {
+				const e = event(type);
+				await store.save(e);
+				events.push(e);
+			}
+			return events;
+		}
+		describe("save — rejects malformed events (invariant 1)", () => {
+			it("persists a well-formed event", async () => {
+				const [e] = await seed(1);
+				expect((await store.getPending(10)).map(idOf)).toContain(idOf(e));
+			});
+			it("THROWS rather than persisting an event with no `type`", async () => {
+				if (reset) await reset();
+				await expect(store.save({
+					payload: {},
+					meta: { id: "no-type" }
+				})).rejects.toThrow();
+				expect((await store.getPending(10)).length).toBe(0);
+			});
+			it("THROWS rather than persisting an event with no `meta.id`", async () => {
+				if (reset) await reset();
+				await expect(store.save({
+					type: "x",
+					payload: {},
+					meta: {}
+				})).rejects.toThrow();
+				expect((await store.getPending(10)).length).toBe(0);
+			});
+		});
+		describe("getPending", () => {
+			it("returns events FIFO (oldest first)", async () => {
+				const saved = await seed(3);
+				expect((await store.getPending(10)).slice(0, 3).map(idOf)).toEqual(saved.map(idOf));
+			});
+			it("honours the limit", async () => {
+				await seed(3);
+				expect((await store.getPending(2)).length).toBeLessThanOrEqual(2);
+			});
+			it("returns only well-formed events (invariant 6)", async () => {
+				await seed(2);
+				for (const e of await store.getPending(10)) {
+					expect(typeof e.type).toBe("string");
+					expect(e.type.length).toBeGreaterThan(0);
+					expect(idOf(e)).toBeTruthy();
+				}
+			});
+		});
+		describe("claimPending — exclusive lease (invariant 2)", () => {
+			it("claims pending events", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(2);
+				expect((await store.claimPending({
+					consumerId: "c1",
+					limit: 10
+				})).length).toBe(2);
+			});
+			it("two concurrent claimers NEVER receive the same event", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(6);
+				const [a, b] = await Promise.all([store.claimPending({
+					consumerId: "c1",
+					limit: 6
+				}), store.claimPending({
+					consumerId: "c2",
+					limit: 6
+				})]);
+				const idsA = a.map(idOf);
+				const idsB = b.map(idOf);
+				expect(idsA.filter((id) => idsB.includes(id))).toEqual([]);
+				expect(idsA.length + idsB.length).toBeLessThanOrEqual(6);
+			});
+			it("does not re-claim an event whose lease is still live", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(2);
+				await store.claimPending({
+					consumerId: "c1",
+					limit: 10,
+					leaseMs: 6e4
+				});
+				expect(await store.claimPending({
+					consumerId: "c2",
+					limit: 10
+				})).toEqual([]);
+			});
+			it("RECLAIMS an event whose lease expired (crashed worker)", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(1);
+				await store.claimPending({
+					consumerId: "dead",
+					limit: 10,
+					leaseMs: 0
+				});
+				expect((await store.claimPending({
+					consumerId: "c2",
+					limit: 10
+				})).length).toBe(1);
+			});
+			it("claims FIFO", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				const saved = await seed(3);
+				expect((await store.claimPending({
+					consumerId: "c1",
+					limit: 2
+				})).map(idOf)).toEqual(saved.slice(0, 2).map(idOf));
+			});
+		});
+		describe("acknowledge", () => {
+			it("removes the event from pending", async () => {
+				const [e] = await seed(1);
+				await store.acknowledge(idOf(e));
+				expect((await store.getPending(10)).map(idOf)).not.toContain(idOf(e));
+			});
+			it("is a NO-OP for an unknown id — never an ownership error (invariant 4)", async () => {
+				if (reset) await reset();
+				await expect(store.acknowledge("does-not-exist")).resolves.not.toThrow();
+			});
+			it("THROWS OutboxOwnershipError when consumerId is not the lease owner (invariant 3)", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "owner",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await expect(store.acknowledge(idOf(claimed), { consumerId: "impostor" })).rejects.toBeInstanceOf(OutboxOwnershipError);
+			});
+			it("succeeds for the rightful lease owner", async ({ skip }) => {
+				if (!store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "owner",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await expect(store.acknowledge(idOf(claimed), { consumerId: "owner" })).resolves.not.toThrow();
+			});
+		});
+		describe("fail — deterministic lease + visibility (invariant 5)", () => {
+			it("makes the event re-claimable again (lease cleared)", async ({ skip }) => {
+				if (!store.fail || !store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "c1",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await store.fail(idOf(claimed), { message: "boom" });
+				expect((await store.claimPending({
+					consumerId: "c2",
+					limit: 10
+				})).map(idOf)).toContain(idOf(claimed));
+			});
+			it("THROWS OutboxOwnershipError on a consumerId mismatch (invariant 3)", async ({ skip }) => {
+				if (!store.fail || !store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "owner",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await expect(store.fail(idOf(claimed), { message: "boom" }, { consumerId: "impostor" })).rejects.toBeInstanceOf(OutboxOwnershipError);
+			});
+			it("honours `retryAt` — the event is NOT immediately re-claimable", async ({ skip }) => {
+				if (!store.fail || !store.claimPending) return skip();
+				await seed(1);
+				const [claimed] = await store.claimPending({
+					consumerId: "c1",
+					limit: 1,
+					leaseMs: 6e4
+				});
+				if (!claimed) return skip();
+				await store.fail(idOf(claimed), { message: "boom" }, { retryAt: new Date(Date.now() + 6e4) });
+				expect((await store.claimPending({
+					consumerId: "c2",
+					limit: 10
+				})).map(idOf)).not.toContain(idOf(claimed));
+			});
+			it("`deadLetter: true` removes it from the pending stream", async ({ skip }) => {
+				if (!store.fail) return skip();
+				const [e] = await seed(1);
+				await store.fail(idOf(e), { message: "fatal" }, { deadLetter: true });
+				expect((await store.getPending(10)).map(idOf)).not.toContain(idOf(e));
+			});
+		});
+		describe("getDeadLettered", () => {
+			it("returns dead-lettered events with their failure metadata", async ({ skip }) => {
+				if (!store.fail || !store.getDeadLettered) return skip();
+				const [e] = await seed(1);
+				await store.fail(idOf(e), { message: "fatal" }, { deadLetter: true });
+				const row = (await store.getDeadLettered(10)).find((d) => idOf(d.event) === idOf(e));
+				expect(row).toBeDefined();
+				expect(row?.error).toBeDefined();
+				expect(typeof row?.attempts).toBe("number");
+			});
+		});
+		describe("purge", () => {
+			it("NEVER removes pending events — delivered-only scope", async ({ skip }) => {
+				if (!store.purge) return skip();
+				await seed(2);
+				await store.purge(0);
+				expect((await store.getPending(10)).length).toBe(2);
+			});
+		});
+	});
+}
+//#endregion
+export { runOutboxStoreContract };

package/dist/types/index.d.mts

@@ -1,5 +1,5 @@
-import { $ as OpenApiSchemas, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as AuthenticatorContext, H as CrudController, Ht as AuthHelpers, I as MiddlewareHandler, It as FastifyHandler, J as PresetHook, K as ResolvedTenantPurge, Kt as JwtContext, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as AuthPluginOptions, W as ResourcePermissions, Wt as Authenticator, X as CrudRouteKey, Y as PresetResult, Z as CrudSchemas, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kn as BaseControllerOptions, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, qt as TokenPair, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, zt as IRequestContext } from "../index-DPRH0Cme.mjs";
+import { $ as OpenApiSchemas, A as RequestIdOptions, At as RouteDefinition, Bt as RouteHandler, C as RequestContext, D as HealthCheck, Dt as ActionEntry, E as GracefulShutdownOptions, Et as ActionDefinition, F as FastifyWithDecorators, Ft as ControllerLike, G as OnTenantDeleteConfig, Gt as AuthenticatorContext, H as CrudController, Ht as AuthHelpers, I as MiddlewareHandler, It as FastifyHandler, J as PresetHook, K as ResolvedTenantPurge, Kt as JwtContext, L as RequestWithExtras, Lt as IController, M as EventsDecorator, Mt as RouteMethod, N as FastifyRequestExtras, Nt as RateLimitConfig, O as HealthOptions, Ot as ActionHandlerFn, P as FastifyWithAuth, Pt as ControllerHandler, Q as MiddlewareConfig, Rt as IControllerResponse, S as QueryParserInterface, T as CrudRouterOptions, Tt as ResourceCacheConfig, U as ResourceConfig, Ut as AuthPluginOptions, W as ResourcePermissions, Wt as Authenticator, X as CrudRouteKey, Y as PresetResult, Z as CrudSchemas, _ as ControllerQueryOptions, a as InferAdapterDoc, at as ResourceExtensions, b as ParsedQuery, c as TypedController, d as PaginationResult, et as RouteSchemaOptions, f as IntrospectionData, g as ArcInternalMetadata, h as ResourceMetadata, i as ValidationResult, it as ResourceHooks, j as ArcDecorator, jt as RouteMcpConfig, k as IntrospectionPluginOptions, kn as BaseControllerOptions, kt as ActionsMap, l as TypedRepository, m as RegistryStats, n as ConfigError, nt as FieldRule, o as InferDocType, ot as EventDefinition, p as RegistryEntry, q as PresetFunction, qt as TokenPair, r as ValidateOptions, rt as ResourceHookContext, s as InferResourceDoc, t as RouteHandlerMethod, tt as ArcFieldRule, u as TypedResourceConfig, v as LookupOption, w as ServiceContext, x as PopulateOption, y as OwnershipCheck, zt as IRequestContext } from "../index-Q5gzEIWY.mjs";
 import { i as RequestScope } from "../types-DjC-KUCz.mjs";
-import { c as AnyRecord, d as ObjectId, f as UserLike, i as UserBase, l as ArcRequest, n as PermissionContext, p as UserOrganization, r as PermissionResult, t as PermissionCheck, u as JWTPayload } from "../types-Dmw-6Qeo.mjs";
+import { a as UserBase, d as JWTPayload, f as ObjectId, i as PermissionContext, l as AnyRecord, m as UserOrganization, n as DataPolicy, p as UserLike, r as PermissionCheck, t as AuthorizationDecision, u as ArcRequest } from "../types-ChvvVNP8.mjs";
 import { n as ElevationOptions, t as ElevationEvent } from "../elevation-C9s5hFP_.mjs";
-export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PermissionResult, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };
+export type { ActionDefinition, ActionEntry, ActionHandlerFn, ActionsMap, AnyRecord, ArcDecorator, ArcFieldRule, ArcInternalMetadata, ArcRequest, AuthHelpers, AuthPluginOptions, Authenticator, AuthenticatorContext, AuthorizationDecision, BaseControllerOptions, ConfigError, ControllerHandler, ControllerLike, ControllerQueryOptions, CrudController, CrudRouteKey, CrudRouterOptions, CrudSchemas, DataPolicy, ElevationEvent, ElevationOptions, EventDefinition, EventsDecorator, FastifyHandler, FastifyRequestExtras, FastifyWithAuth, FastifyWithDecorators, FieldRule, GracefulShutdownOptions, HealthCheck, HealthOptions, IController, IControllerResponse, IRequestContext, InferAdapterDoc, InferDocType, InferResourceDoc, IntrospectionData, IntrospectionPluginOptions, JWTPayload, JwtContext, LookupOption, MiddlewareConfig, MiddlewareHandler, ObjectId, OnTenantDeleteConfig, OpenApiSchemas, OwnershipCheck, PaginationResult, ParsedQuery, PermissionCheck, PermissionContext, PopulateOption, PresetFunction, PresetHook, PresetResult, QueryParserInterface, RateLimitConfig, RegistryEntry, RegistryStats, RequestContext, RequestIdOptions, RequestScope, RequestWithExtras, ResolvedTenantPurge, ResourceCacheConfig, ResourceConfig, ResourceExtensions, ResourceHookContext, ResourceHooks, ResourceMetadata, ResourcePermissions, RouteDefinition, RouteHandler, RouteHandlerMethod, RouteMcpConfig, RouteMethod, RouteSchemaOptions, ServiceContext, TokenPair, TypedController, TypedRepository, TypedResourceConfig, UserBase, UserLike, UserOrganization, ValidateOptions, ValidationResult };

package/dist/{types-QFGc3Cjv.d.mts → types-Bmmn-fO0.d.mts}

@@ -1,4 +1,4 @@
-import { V as ResourceDefinition } from "./index-DPRH0Cme.mjs";
+import { V as ResourceDefinition } from "./index-Q5gzEIWY.mjs";
 import { z } from "zod";
 //#region src/integrations/mcp/types.d.ts
 /** Behavioral hints for MCP clients (tool annotations per MCP spec) */