lambder 8.1.2 → 8.3.1

package/dist/testing/lambderIdempotencyStoreConformance.js

@@ -0,0 +1,237 @@
+import { CONFORMANCE_START_MILLIS as START, conformanceClock, } from "./LambderConformanceRunner.js";
+/**
+ * Registers the idempotency store rules as cases of the runner, one `it`
+ * each, against the store `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderIdempotencyStoreConformance } from "lambder/testing";
+ *
+ * describe("OrderIdempotencyStore", () => {
+ *     lambderIdempotencyStoreConformance({
+ *         it, expect,
+ *         create: ({ now }) => new OrderIdempotencyStore({ pool, now }),
+ *         oversizedBody: "x".repeat(2_000_000),
+ *         largestStorableBody: "x".repeat(1_000_000),
+ *     });
+ * });
+ * ```
+ */
+export const lambderIdempotencyStoreConformance = (options) => {
+    const { it, expect, oversizedBody, largestStorableBody } = options;
+    const answer = { statusCode: 201, headers: { "Content-Type": ["application/json"] }, body: '{"ok":true}', fingerprint: "request-1", ttlSeconds: 60 };
+    /** A fresh store and the clock it reads. */
+    const begin = async () => {
+        const clock = conformanceClock();
+        return { clock, store: await options.create(clock) };
+    };
+    /**
+     * A granted claim's owner token, or a failure. Every rule below is about
+     * what happens AFTER a claim is granted, so a rule that returned early on
+     * a claim that was not new would pass on a store that grants nothing.
+     */
+    const claimNew = async (store, scopeKey, pendingTtlSeconds = 60) => {
+        const claim = await store.begin(scopeKey, { pendingTtlSeconds, fingerprint: "request-1" });
+        if (claim.state !== "new")
+            throw new Error(`expected a new claim on "${scopeKey}", got "${claim.state}"`);
+        return claim.ownerToken;
+    };
+    it("keeps the request fingerprint through the claim and the settled record, so the engine can tell a retry from another request", async () => {
+        const { store } = await begin();
+        const owner = await claimNew(store, "scope-f");
+        expect(await store.begin("scope-f", { pendingTtlSeconds: 60, fingerprint: "request-2" })).toEqual({ state: "pending", fingerprint: "request-1" });
+        expect(await store.complete("scope-f", owner, { ...answer, fingerprint: "request-1" })).toBe("stored");
+        expect(await store.peek("scope-f")).toMatchObject({ statusCode: 201, fingerprint: "request-1" });
+        expect(await store.begin("scope-f", { pendingTtlSeconds: 60, fingerprint: "request-2" })).toMatchObject({ state: "done", fingerprint: "request-1" });
+    });
+    it("claims a free scope, refuses a concurrent claim, and hides the record until it is settled", async () => {
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        expect(ownerToken).toBeTruthy();
+        expect((await store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" })).state).toBe("pending");
+        expect(await store.peek("s")).toBeNull();
+    });
+    it("settles by the owner, then replays the answer through both peek and begin", async () => {
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        expect(await store.complete("s", ownerToken, answer)).toBe("stored");
+        const peeked = await store.peek("s");
+        expect(peeked).toEqual({ statusCode: 201, headers: { "Content-Type": ["application/json"] }, body: '{"ok":true}', fingerprint: "request-1" });
+        const begun = await store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" });
+        expect(begun).toMatchObject({ state: "done", statusCode: 201, body: '{"ok":true}' });
+    });
+    it("hands back a copy, so a caller writing onto what it read cannot rewrite the record", async () => {
+        // The pipeline applies the replaying call's own headers onto the answer
+        // it got back. A store that returns its own map lets one call's
+        // Set-Cookie become part of the record and reach every later replay.
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        await store.complete("s", ownerToken, answer);
+        const peeked = await store.peek("s");
+        peeked.headers["Set-Cookie"] = ["sid=; Max-Age=0"];
+        const begun = await store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" });
+        if (begun.state === "done")
+            begun.headers["Set-Cookie"] = ["sid=; Max-Age=0"];
+        expect((await store.peek("s"))?.headers["Set-Cookie"]).toBeUndefined();
+    });
+    it("reports a settle from a non-owner as lost, and writes nothing", async () => {
+        const { store } = await begin();
+        await claimNew(store, "s");
+        expect(await store.complete("s", "not-the-owner", answer)).toBe("lost");
+        expect(await store.peek("s")).toBeNull();
+    });
+    it("reports a body it cannot hold as too-large, and writes nothing", async () => {
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        expect(await store.complete("s", ownerToken, { ...answer, body: oversizedBody })).toBe("too-large");
+        expect(await store.peek("s")).toBeNull();
+        // The claim survives, so the caller can release it and let retries run.
+        await store.abandon("s", ownerToken);
+        expect((await store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" })).state).toBe("new");
+    });
+    it("decides size before ownership, the only order a single conditional write allows", async () => {
+        const { store } = await begin();
+        await claimNew(store, "s");
+        // A store settles in one write, so the only thing it can judge before
+        // reaching the table is whether the body fits. Both answers are safe
+        // for the caller; what matters is that every store gives the same one.
+        expect(await store.complete("s", "not-the-owner", { ...answer, body: oversizedBody })).toBe("too-large");
+    });
+    it("releases a claim only for its owner", async () => {
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        await store.abandon("s", "not-the-owner");
+        expect((await store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" })).state).toBe("pending");
+        await store.abandon("s", ownerToken);
+        expect((await store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" })).state).toBe("new");
+    });
+    it("lets a pending claim expire, so a crashed original does not block retries forever", async () => {
+        const { clock, store } = await begin();
+        await claimNew(store, "s", 30);
+        clock.set(START + 31_000);
+        expect((await store.begin("s", { pendingTtlSeconds: 30, fingerprint: "request-1" })).state).toBe("new");
+    });
+    it("reports an owner settling after its own claim expired as lost", async () => {
+        // A claim that ran out is a claim the owner does not hold, whatever
+        // the storage does about it. DynamoDB's TTL deletion is lazy, so a
+        // store that checked only the owner token would usually still find
+        // the item and say "stored", and the answer would depend on whether
+        // AWS had swept yet.
+        const { clock, store } = await begin();
+        const ownerToken = await claimNew(store, "s", 30);
+        clock.set(START + 31_000);
+        expect(await store.complete("s", ownerToken, answer)).toBe("lost");
+        expect(await store.peek("s")).toBeNull();
+    });
+    it("stops replaying a settled record once its ttl runs out", async () => {
+        const { clock, store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        await store.complete("s", ownerToken, { ...answer, ttlSeconds: 60 });
+        clock.set(START + 61_000);
+        expect(await store.peek("s")).toBeNull();
+        expect((await store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" })).state).toBe("new");
+    });
+    it("replays an empty body", async () => {
+        // A 204, or a 200 with an empty body, is an answer like any other, and
+        // the replay has to be the same answer. A compressed empty body must
+        // not declare a length the codec refuses on the way back: peek and
+        // begin would throw for the record's whole TTL, the engine would fail
+        // open on each, and every retry would execute again.
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        expect(await store.complete("s", ownerToken, { ...answer, statusCode: 204, body: "" })).toBe("stored");
+        expect(await store.peek("s")).toEqual({ statusCode: 204, headers: { "Content-Type": ["application/json"] }, body: "", fingerprint: "request-1" });
+        expect(await store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" })).toMatchObject({ state: "done", statusCode: 204, body: "" });
+    });
+    it("keeps scopes apart", async () => {
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "a");
+        await store.complete("a", ownerToken, answer);
+        expect(await store.peek("b")).toBeNull();
+        expect((await store.begin("b", { pendingTtlSeconds: 60, fingerprint: "request-1" })).state).toBe("new");
+    });
+    it("takes a copy of what it is given, so a caller writing onto the record afterwards cannot rewrite it", async () => {
+        // The other half of the copy rule. The pipeline hands complete() the
+        // answer object and goes on writing the call's own headers into it
+        // afterwards, so a store that kept the caller's map would take one
+        // request's Set-Cookie into the stored record and replay it to
+        // everybody else.
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        const record = { statusCode: 201, headers: { "Content-Type": ["application/json"] }, body: '{"ok":true}', fingerprint: "request-1", ttlSeconds: 60 };
+        expect(await store.complete("s", ownerToken, record)).toBe("stored");
+        record.headers["Set-Cookie"] = ["sid=planted"];
+        record.headers["Content-Type"] = ["text/plain"];
+        record.statusCode = 500;
+        expect(await store.peek("s")).toEqual({
+            statusCode: 201,
+            headers: { "Content-Type": ["application/json"] },
+            body: '{"ok":true}',
+            fingerprint: "request-1",
+        });
+    });
+    it("holds a body that is exactly at its budget, the other side of the too-large boundary", async () => {
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        expect(await store.complete("s", ownerToken, { ...answer, body: largestStorableBody })).toBe("stored");
+        expect((await store.peek("s"))?.body).toBe(largestStorableBody);
+    });
+    it("counts the expiry second itself as expired, on the claim and on the record", async () => {
+        // Whether expiry is `<=` or `<` decides what happens in the second a
+        // claim runs out, and implementations settle it in different places:
+        // one compares in the process, another in a database condition. On
+        // the boundary second the claim is gone and the record no longer
+        // replays.
+        const { clock, store } = await begin();
+        await claimNew(store, "s", 30);
+        clock.set(START + 30_000);
+        expect((await store.begin("s", { pendingTtlSeconds: 30, fingerprint: "request-1" })).state).toBe("new");
+        clock.set(START);
+        const second = await options.create(clock);
+        const secondToken = await claimNew(second, "s");
+        await second.complete("s", secondToken, { ...answer, ttlSeconds: 60 });
+        clock.set(START + 60_000);
+        expect(await second.peek("s")).toBeNull();
+    });
+    it("lets the owner settle the same scope twice, so a retried complete is not a lost claim", async () => {
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        expect(await store.complete("s", ownerToken, answer)).toBe("stored");
+        expect(await store.complete("s", ownerToken, { ...answer, body: '{"ok":2}' })).toBe("stored");
+        expect((await store.peek("s"))?.body).toBe('{"ok":2}');
+    });
+    it("keeps the settled record when its own owner abandons after completing", async () => {
+        // The engine abandons after a complete() that threw, and one whose
+        // response was lost may have landed. A settled record still carries
+        // the owner token, so an abandon conditional on the token alone would
+        // delete the stored answer, hand the client's retry a free scope, and
+        // run the operation twice. Only a pending claim is released.
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s");
+        await store.complete("s", ownerToken, answer);
+        await store.abandon("s", ownerToken);
+        expect(await store.peek("s")).toMatchObject({ statusCode: 201, body: '{"ok":true}', fingerprint: "request-1" });
+        expect((await store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" })).state).toBe("done");
+    });
+    it("treats a zero pendingTtlSeconds as a claim that is already over, rather than one that never ends", async () => {
+        // The engine validates the option, so this is about what a store does
+        // when one reaches it anyway: the claim expires in the second it is
+        // taken, so the next request claims the scope rather than seeing a
+        // pending original, and the first owner has already lost it.
+        const { store } = await begin();
+        const ownerToken = await claimNew(store, "s", 0);
+        expect((await store.begin("s", { pendingTtlSeconds: 0, fingerprint: "request-1" })).state).toBe("new");
+        expect(await store.complete("s", ownerToken, answer)).toBe("lost");
+    });
+    it("grants exactly one claim when two requests claim the same scope at once", async () => {
+        // The rule the whole store exists for: begin() has to be atomic, not
+        // read-then-write.
+        const { store } = await begin();
+        const claims = await Promise.all([
+            store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" }),
+            store.begin("s", { pendingTtlSeconds: 60, fingerprint: "request-1" }),
+        ]);
+        expect(claims.filter((claim) => claim.state === "new")).toHaveLength(1);
+        expect(claims.filter((claim) => claim.state === "pending")).toHaveLength(1);
+    });
+};

package/dist/testing/lambderOneShotSecretStoreConformance.d.ts

@@ -0,0 +1,43 @@
+import type { LambderOneShotSecretShape, LambderOneShotSecretStore } from "../shared/contracts/LambderOneShotSecretStore.js";
+import { type LambderConformanceRunner, type LambderConformanceSetup } from "./LambderConformanceRunner.js";
+export type LambderOneShotSecretStoreConformanceOptions = LambderConformanceRunner & {
+    /**
+     * A store holding nothing under either scope, built for one case over
+     * the case's clock. A store over a database empties what the previous
+     * case wrote here, since cases reuse the same digests.
+     */
+    create: (setup: LambderConformanceSetup) => LambderOneShotSecretStore | Promise<LambderOneShotSecretStore>;
+    /** Two scopes the store can hold a secret under; the second is the one a case keeps apart from the first. Default: two addresses under one purpose. */
+    scopes?: readonly [string, string];
+    /**
+     * The kind the cases write for each shape the store holds, which the
+     * store has to hand back as written. A store that holds only codes, or
+     * only tokens, names that shape alone, and the cases for the other are
+     * left out. Default: `{ code: "emailCode", token: "activationLink" }`.
+     */
+    kinds?: Partial<Record<LambderOneShotSecretShape, string>>;
+    /** The meta written with a record of each scope, which the store has to hand back as written. `[{}, {}]` for a store that keeps none. Default: one small map per scope. */
+    meta?: readonly [Record<string, string>, Record<string, string>];
+    /** Seconds from a record's issue to its expiry, the same for every record a case writes, as a store that derives one from the other needs. Default: 600. */
+    lifetimeSeconds?: number;
+};
+/**
+ * Registers the one-shot secret store rules as cases of the runner, one `it`
+ * each and once per shape, against the store `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderOneShotSecretStoreConformance } from "lambder/testing";
+ *
+ * describe("TicketCodeStore", () => {
+ *     lambderOneShotSecretStoreConformance({
+ *         it, expect,
+ *         create: async () => { await emptyTicketCodes(); return new TicketCodeStore(pool); },
+ *         scopes: [ticketA.id, ticketB.id],
+ *         kinds: { code: "ticketCode" },
+ *         meta: [{}, {}],
+ *     });
+ * });
+ * ```
+ */
+export declare const lambderOneShotSecretStoreConformance: (options: LambderOneShotSecretStoreConformanceOptions) => void;

package/dist/testing/lambderOneShotSecretStoreConformance.js

@@ -0,0 +1,224 @@
+import { CONFORMANCE_START_MILLIS as START, conformanceClock, } from "./LambderConformanceRunner.js";
+/**
+ * Registers the one-shot secret store rules as cases of the runner, one `it`
+ * each and once per shape, against the store `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderOneShotSecretStoreConformance } from "lambder/testing";
+ *
+ * describe("TicketCodeStore", () => {
+ *     lambderOneShotSecretStoreConformance({
+ *         it, expect,
+ *         create: async () => { await emptyTicketCodes(); return new TicketCodeStore(pool); },
+ *         scopes: [ticketA.id, ticketB.id],
+ *         kinds: { code: "ticketCode" },
+ *         meta: [{}, {}],
+ *     });
+ * });
+ * ```
+ */
+export const lambderOneShotSecretStoreConformance = (options) => {
+    const [scopeA, scopeB] = options.scopes ?? ["register:ada@example.com", "register:grace@example.com"];
+    const kinds = options.kinds ?? { code: "emailCode", token: "activationLink" };
+    const shapes = ["code", "token"].filter((shape) => kinds[shape] !== undefined);
+    if (shapes.length === 0)
+        throw new Error("lambderOneShotSecretStoreConformance: kinds names no shape; give the kind the store holds as a code, as a token, or both.");
+    const { expect } = options;
+    const [metaA, metaB] = options.meta ?? [{ holder: "ada" }, { holder: "grace" }];
+    const lifetimeSeconds = options.lifetimeSeconds ?? 600;
+    const startSeconds = Math.floor(START / 1000);
+    const begin = async () => {
+        const clock = conformanceClock();
+        return { clock, store: await options.create(clock) };
+    };
+    // Every case once per shape the store holds, named for it.
+    for (const shape of shapes) {
+        const kind = kinds[shape];
+        const isToken = shape === "token";
+        const it = (name, run) => options.it(`${shape}: ${name}`, run);
+        /** A record of scope A issued at the start, unless a case says otherwise; the expiry always follows from the issue time. */
+        const draft = (over = {}) => {
+            const issuedAt = over.issuedAt ?? startSeconds;
+            return {
+                kind,
+                scope: over.scope ?? scopeA,
+                shape,
+                digest: over.digest ?? "digest-1",
+                issuedAt,
+                expiresAt: issuedAt + lifetimeSeconds,
+                meta: over.meta ?? (over.scope === scopeB ? metaB : metaA),
+            };
+        };
+        /** The record a store holds for a draft: the draft less its shape, with the id it handed out and no tries. */
+        const recordFor = (written, id) => {
+            const { shape: _shape, ...record } = written;
+            return { ...record, id, attempts: 0 };
+        };
+        /** An issue that went through, or a failure: every rule below is about a record that exists. */
+        const issued = async (store, over = {}) => {
+            const outcome = await store.issue(draft(over), {});
+            if (!outcome.issued)
+                throw new Error(`expected the secret to be issued, refused as ${outcome.refused}`);
+            return outcome.id;
+        };
+        it("holds one record per scope, found by its scope (and a token by its digest), with what was written and no tries", async () => {
+            const { store } = await begin();
+            const id = await issued(store);
+            const byScope = await store.findByScope(scopeA);
+            expect(byScope).toEqual(recordFor(draft(), id));
+            expect(await store.findByScope(scopeB)).toBeNull();
+            if (isToken) {
+                expect(await store.findByDigest("digest-1")).toEqual(byScope);
+                expect(await store.findByDigest("digest-9")).toBeNull();
+            }
+        });
+        it("retires the scope's older record in the act of issuing, so it can be neither found nor spent", async () => {
+            const { store } = await begin();
+            const first = await issued(store, { digest: "digest-1" });
+            const second = await issued(store, { digest: "digest-2", issuedAt: startSeconds + 30 });
+            expect(second).not.toBe(first);
+            expect((await store.findByScope(scopeA))?.digest).toBe("digest-2");
+            if (isToken) {
+                expect(await store.findByDigest("digest-1")).toBeNull();
+                expect((await store.findByDigest("digest-2"))?.id).toBe(second);
+            }
+            else {
+                expect(await store.attempt(scopeA, first)).toBeNull();
+            }
+            expect(await store.consume(scopeA, first)).toBe(false);
+        });
+        it("leaves exactly one live record when two issues for one scope race", async () => {
+            // Retire-then-write done as two statements lets both writers retire
+            // nothing and both write, and the scope then holds two live secrets.
+            // A second of apart, so a store whose id is the issue time tells the
+            // two apart.
+            const { store } = await begin();
+            const [idA, idB] = await Promise.all([
+                issued(store, { digest: "digest-a" }),
+                issued(store, { digest: "digest-b", issuedAt: startSeconds + 1 }),
+            ]);
+            const current = await store.findByScope(scopeA);
+            if (isToken) {
+                const live = [await store.findByDigest("digest-a"), await store.findByDigest("digest-b")].filter((record) => record !== null);
+                expect(live).toHaveLength(1);
+                expect(current?.digest).toBe(live[0].digest);
+            }
+            // Only the scope's current record can be spent.
+            expect([await store.consume(scopeA, idA), await store.consume(scopeA, idB)].filter(Boolean)).toHaveLength(1);
+            expect(current).not.toBeNull();
+        });
+        it("refuses an issue inside the cooldown, naming when the current record was issued, and writes nothing", async () => {
+            const { store } = await begin();
+            await issued(store, { digest: "digest-1", issuedAt: startSeconds });
+            const refused = await store.issue(draft({ digest: "digest-2", issuedAt: startSeconds + 10 }), { unlessIssuedAfter: startSeconds - 1 });
+            expect(refused).toEqual({ issued: false, refused: "cooldown", issuedAt: startSeconds });
+            expect((await store.findByScope(scopeA))?.digest).toBe("digest-1");
+            if (isToken)
+                expect(await store.findByDigest("digest-2")).toBeNull();
+            // At the threshold itself the cooldown is over, and a scope with no record has none.
+            expect((await store.issue(draft({ digest: "digest-3", issuedAt: startSeconds + 30 }), { unlessIssuedAfter: startSeconds })).issued).toBe(true);
+            expect((await store.issue(draft({ scope: scopeB, digest: "digest-4" }), { unlessIssuedAfter: startSeconds + 1000 })).issued).toBe(true);
+        });
+        it("grants exactly one of two issues racing past a cooldown", async () => {
+            const { store } = await begin();
+            await issued(store, { digest: "digest-0", issuedAt: startSeconds - 100 });
+            const [a, b] = await Promise.all([
+                store.issue(draft({ digest: "digest-a" }), { unlessIssuedAfter: startSeconds - 30 }),
+                store.issue(draft({ digest: "digest-b" }), { unlessIssuedAfter: startSeconds - 30 }),
+            ]);
+            expect([a.issued, b.issued].filter(Boolean)).toHaveLength(1);
+        });
+        if (isToken) {
+            it("refuses a digest another scope's record holds, writes nothing, and leaves it with its holder", async () => {
+                // Two scopes that drew the same token would share one digest,
+                // and whoever typed it would redeem the other's record.
+                const { store } = await begin();
+                const holderId = await issued(store, { digest: "digest-x" });
+                expect(await store.issue(draft({ scope: scopeB, digest: "digest-x" }), {})).toEqual({ issued: false, refused: "digestTaken" });
+                expect(await store.findByScope(scopeB)).toBeNull();
+                expect(await store.findByDigest("digest-x")).toEqual(recordFor(draft({ digest: "digest-x" }), holderId));
+            });
+            it("grants a digest to exactly one of two scopes racing for it", async () => {
+                const { store } = await begin();
+                const [a, b] = await Promise.all([
+                    store.issue(draft({ digest: "digest-x" }), {}),
+                    store.issue(draft({ scope: scopeB, digest: "digest-x" }), {}),
+                ]);
+                expect([a, b].filter((outcome) => outcome.issued)).toHaveLength(1);
+                expect([a, b].filter((outcome) => !outcome.issued && outcome.refused === "digestTaken")).toHaveLength(1);
+                const winner = a.issued ? scopeA : scopeB;
+                expect((await store.findByDigest("digest-x"))?.scope).toBe(winner);
+                expect(await store.findByScope(winner === scopeA ? scopeB : scopeA)).toBeNull();
+            });
+        }
+        else {
+            it("counts a try in the act that reads the record, on the record named and no other", async () => {
+                const { store } = await begin();
+                const id = await issued(store);
+                const first = await store.attempt(scopeA, id);
+                expect(first).toMatchObject({ id, digest: "digest-1", attempts: 1, meta: metaA });
+                expect((await store.attempt(scopeA, id))?.attempts).toBe(2);
+                expect((await store.findByScope(scopeA))?.attempts).toBe(2);
+                // The record is scope A's: named under another scope, it is not the one there.
+                expect(await store.attempt(scopeB, id)).toBeNull();
+                expect((await store.findByScope(scopeA))?.attempts).toBe(2);
+            });
+            it("counts tries sent together every one, so a ceiling cannot be raced past", async () => {
+                const { store } = await begin();
+                const id = await issued(store);
+                const counted = await Promise.all(Array.from({ length: 5 }, () => store.attempt(scopeA, id)));
+                expect(counted.map((record) => record?.attempts).sort()).toEqual([1, 2, 3, 4, 5]);
+            });
+        }
+        it("consumes the record named exactly once, after which nothing finds it", async () => {
+            const { store } = await begin();
+            const id = await issued(store);
+            expect(await store.consume(scopeB, id)).toBe(false);
+            expect(await store.consume(scopeA, id)).toBe(true);
+            expect(await store.consume(scopeA, id)).toBe(false);
+            expect(await store.findByScope(scopeA)).toBeNull();
+            if (isToken)
+                expect(await store.findByDigest("digest-1")).toBeNull();
+            else
+                expect(await store.attempt(scopeA, id)).toBeNull();
+        });
+        it("accepts exactly one of two consumes racing for one record", async () => {
+            const { store } = await begin();
+            const id = await issued(store);
+            const outcomes = await Promise.all([store.consume(scopeA, id), store.consume(scopeA, id)]);
+            expect(outcomes.filter(Boolean)).toHaveLength(1);
+        });
+        it("retires whatever the scope holds and nothing of another scope, and nothing when it holds nothing", async () => {
+            const { store } = await begin();
+            await issued(store, { digest: "digest-a" });
+            await issued(store, { scope: scopeB, digest: "digest-b" });
+            await store.retire(scopeA);
+            expect(await store.findByScope(scopeA)).toBeNull();
+            if (isToken)
+                expect(await store.findByDigest("digest-a")).toBeNull();
+            expect((await store.findByScope(scopeB))?.digest).toBe("digest-b");
+            await store.retire(scopeA);
+        });
+        it("keeps an expired record until its own housekeeping removes it, so the class can say expired rather than none", async () => {
+            const { clock, store } = await begin();
+            const id = await issued(store);
+            clock.set(START + (lifetimeSeconds + 1) * 1000);
+            expect((await store.findByScope(scopeA))?.id).toBe(id);
+            if (isToken)
+                expect((await store.findByDigest("digest-1"))?.id).toBe(id);
+        });
+        it("keeps scopes apart, and hands back copies", async () => {
+            const { store } = await begin();
+            const idA = await issued(store, { digest: "digest-a" });
+            const idB = await issued(store, { scope: scopeB, digest: "digest-b" });
+            const a = (await store.findByScope(scopeA));
+            a.meta["planted"] = "changed";
+            a.digest = "changed";
+            expect(await store.findByScope(scopeA)).toEqual(recordFor(draft({ digest: "digest-a" }), idA));
+            expect(await store.findByScope(scopeB)).toEqual(recordFor(draft({ scope: scopeB, digest: "digest-b" }), idB));
+            if (isToken)
+                expect((await store.findByDigest("digest-b"))?.scope).toBe(scopeB);
+        });
+    }
+};

package/dist/testing/lambderRateLimiterConformance.d.ts

@@ -0,0 +1,20 @@
+import { type LambderRateLimiter } from "../shared/contracts/LambderRateLimiter.js";
+import { type LambderConformanceRunner, type LambderConformanceSetup } from "./LambderConformanceRunner.js";
+export type LambderRateLimiterConformanceOptions = LambderConformanceRunner & {
+    /** A limiter holding no counts, built for one case over the case's clock. */
+    create: (setup: LambderConformanceSetup) => LambderRateLimiter | Promise<LambderRateLimiter>;
+};
+/**
+ * Registers the rate limiter rules as cases of the runner, one `it` each,
+ * against the limiter `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderRateLimiterConformance } from "lambder/testing";
+ *
+ * describe("RedisRateLimiter", () => {
+ *     lambderRateLimiterConformance({ it, expect, create: ({ now }) => new RedisRateLimiter({ client, now }) });
+ * });
+ * ```
+ */
+export declare const lambderRateLimiterConformance: (options: LambderRateLimiterConformanceOptions) => void;

package/dist/testing/lambderRateLimiterConformance.js

@@ -0,0 +1,72 @@
+import { RATE_LIMIT_WINDOWS } from "../shared/contracts/LambderRateLimiter.js";
+import { CONFORMANCE_START_MILLIS as START, conformanceClock, } from "./LambderConformanceRunner.js";
+/**
+ * Registers the rate limiter rules as cases of the runner, one `it` each,
+ * against the limiter `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderRateLimiterConformance } from "lambder/testing";
+ *
+ * describe("RedisRateLimiter", () => {
+ *     lambderRateLimiterConformance({ it, expect, create: ({ now }) => new RedisRateLimiter({ client, now }) });
+ * });
+ * ```
+ */
+export const lambderRateLimiterConformance = (options) => {
+    const { it, expect } = options;
+    const begin = async () => {
+        const clock = conformanceClock();
+        return { clock, limiter: await options.create(clock) };
+    };
+    it("counts attempts and refuses the one past the limit, naming the window", async () => {
+        const { limiter } = await begin();
+        expect(await limiter.isRateLimited("k", { perMin: 2 })).toBe(false);
+        expect(await limiter.isRateLimited("k", { perMin: 2 })).toBe(false);
+        const refused = await limiter.isRateLimited("k", { perMin: 2 });
+        expect(refused).toMatchObject({ window: "perMin", limit: 2 });
+        if (refused === false)
+            throw new Error("expected the third attempt to be refused");
+        expect(refused.resetAt).toBeGreaterThan(Math.floor(START / 1000));
+    });
+    it("counts attempts rather than allowed requests, so a refusal does not reset anything", async () => {
+        const { limiter } = await begin();
+        await limiter.isRateLimited("k", { perMin: 1 });
+        expect(await limiter.isRateLimited("k", { perMin: 1 })).not.toBe(false);
+        expect(await limiter.isRateLimited("k", { perMin: 1 })).not.toBe(false);
+    });
+    it("does not enforce a window the policy leaves out or caps at zero", async () => {
+        const { limiter } = await begin();
+        for (let i = 0; i < 5; i += 1) {
+            expect(await limiter.isRateLimited("k", { perHour: 0 })).toBe(false);
+        }
+        expect(await limiter.isRateLimited("k", {})).toBe(false);
+    });
+    it("reports the smallest exceeded window, since that is the one evaluated first", async () => {
+        const { limiter } = await begin();
+        await limiter.isRateLimited("k", { perMin: 1, perHour: 10 });
+        expect(await limiter.isRateLimited("k", { perMin: 1, perHour: 10 })).toMatchObject({ window: "perMin" });
+    });
+    it("keeps tracker keys apart", async () => {
+        const { limiter } = await begin();
+        await limiter.isRateLimited("a", { perMin: 1 });
+        expect(await limiter.isRateLimited("b", { perMin: 1 })).toBe(false);
+    });
+    it("starts a fresh count once the fixed window rolls over", async () => {
+        const { clock, limiter } = await begin();
+        await limiter.isRateLimited("k", { perMin: 1 });
+        expect(await limiter.isRateLimited("k", { perMin: 1 })).not.toBe(false);
+        clock.set(START + 61_000);
+        expect(await limiter.isRateLimited("k", { perMin: 1 })).toBe(false);
+    });
+    for (const { key, seconds } of RATE_LIMIT_WINDOWS) {
+        it(`enforces ${key} and resets after it`, async () => {
+            const { clock, limiter } = await begin();
+            const policy = { [key]: 1 };
+            expect(await limiter.isRateLimited("k", policy)).toBe(false);
+            expect(await limiter.isRateLimited("k", policy)).toMatchObject({ window: key, limit: 1 });
+            clock.set(START + (seconds + 1) * 1000);
+            expect(await limiter.isRateLimited("k", policy)).toBe(false);
+        });
+    }
+};

package/dist/testing/lambderSessionStoreConformance.d.ts

@@ -0,0 +1,27 @@
+import type { LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import { type LambderConformanceRunner, type LambderConformanceSetup } from "./LambderConformanceRunner.js";
+export type LambderSessionStoreConformanceOptions = LambderConformanceRunner & {
+    /** A store holding no sessions, built for one case over the case's clock. */
+    create: (setup: LambderConformanceSetup) => LambderSessionStore | Promise<LambderSessionStore>;
+    /** What the store's `isMemoryOnly` must say: true only for a store nothing outlives the process of. Default: false. */
+    isMemoryOnly?: boolean;
+};
+/**
+ * Registers the session store rules as cases of the runner, one `it` each,
+ * against the store `create` builds:
+ *
+ * ```ts
+ * import { describe, it, expect } from "vitest";
+ * import { lambderSessionStoreConformance } from "lambder/testing";
+ *
+ * describe("PostgresSessionStore", () => {
+ *     lambderSessionStoreConformance({ it, expect, create: async () => { await emptySessions(); return new PostgresSessionStore(pool); } });
+ * });
+ * ```
+ *
+ * The records a case writes are dated from the case's clock, which starts at
+ * a fixed moment and stands still unless a case moves it: a store that
+ * expires records by the system clock, rather than by `now`, finds them all
+ * long expired.
+ */
+export declare const lambderSessionStoreConformance: (options: LambderSessionStoreConformanceOptions) => void;