lambder 8.1.2 → 9.0.1

package/dist/stores/LambderMemoryOneShotSecretStore.js

@@ -0,0 +1,93 @@
+import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
+/**
+ * How long past its expiry a record is kept, so the class can still answer
+ * "expired" from it rather than "none", the way a table's lazy TTL leaves an
+ * expired item in place for a while.
+ */
+const EXPIRED_GRACE_SECONDS = 3600;
+/**
+ * One-shot secrets held in memory: the same one-record-per-scope, count-then-
+ * compare and consume-once semantics as LambderDdbOneShotSecretStore, over a
+ * LambderExpiringMap in place of the table and its TTL. For tests and for an
+ * app's development runtime; lambderOneShotSecretStoreConformance drives
+ * this and the DynamoDB store through one set of rules.
+ *
+ * Two maps, as the table holds two items per secret: the scope's current
+ * record, and the scope a digest belongs to, which is how a token is found by
+ * its value. `now` is injectable so a test can expire a secret without
+ * waiting.
+ */
+export class LambderMemoryOneShotSecretStore {
+    records;
+    scopesByDigest;
+    idCounter = 0;
+    constructor(options = {}) {
+        this.records = new LambderExpiringMap({ now: options.now, maxEntries: options.maxEntries });
+        this.scopesByDigest = new LambderExpiringMap({ now: options.now, maxEntries: options.maxEntries });
+    }
+    /** A record as the class reads it: a copy, so a caller writing onto what it got back cannot rewrite the record. */
+    static copyOf(record) {
+        return { ...record, meta: { ...record.meta } };
+    }
+    async issue(draft, { unlessIssuedAfter }) {
+        const current = this.records.get(draft.scope);
+        if (unlessIssuedAfter !== undefined && current && current.issuedAt > unlessIssuedAfter)
+            return { issued: false, refused: "cooldown", issuedAt: current.issuedAt };
+        // A token's digest is its only address, so another scope's record
+        // holding it keeps it; a code's carries its scope, and no other scope
+        // can hold it.
+        const holder = draft.shape === "token" ? this.scopesByDigest.get(draft.digest) : undefined;
+        if (holder !== undefined && holder !== draft.scope && this.records.get(holder)?.digest === draft.digest)
+            return { issued: false, refused: "digestTaken" };
+        if (current)
+            this.scopesByDigest.delete(current.digest);
+        this.idCounter += 1;
+        const id = `secret-${this.idCounter}`;
+        const keepUntil = draft.expiresAt + EXPIRED_GRACE_SECONDS;
+        const { shape: _shape, ...record } = draft;
+        this.records.set(draft.scope, { ...record, id, attempts: 0, meta: { ...draft.meta } }, keepUntil);
+        if (draft.shape === "token")
+            this.scopesByDigest.set(draft.digest, draft.scope, keepUntil);
+        return { issued: true, id };
+    }
+    async findByScope(scope) {
+        const record = this.records.get(scope);
+        return record ? LambderMemoryOneShotSecretStore.copyOf(record) : null;
+    }
+    async findByDigest(digest) {
+        const scope = this.scopesByDigest.get(digest);
+        const record = scope === undefined ? undefined : this.records.get(scope);
+        // The scope may have been issued a newer secret since this digest was
+        // written, in which case this digest is nobody's.
+        return record && record.digest === digest ? LambderMemoryOneShotSecretStore.copyOf(record) : null;
+    }
+    async attempt(scope, id) {
+        const record = this.records.get(scope);
+        if (!record || record.id !== id)
+            return null;
+        record.attempts += 1;
+        return LambderMemoryOneShotSecretStore.copyOf(record);
+    }
+    async consume(scope, id) {
+        const record = this.records.get(scope);
+        if (!record || record.id !== id)
+            return false;
+        this.records.delete(scope);
+        this.scopesByDigest.delete(record.digest);
+        return true;
+    }
+    async retire(scope) {
+        const record = this.records.get(scope);
+        if (!record)
+            return;
+        this.records.delete(scope);
+        this.scopesByDigest.delete(record.digest);
+    }
+    /** Number of live records held. */
+    get size() { return this.records.size; }
+    /** Forgets every record. */
+    reset() {
+        this.records.clear();
+        this.scopesByDigest.clear();
+    }
+}

package/dist/testing/LambderConformanceRunner.d.ts

@@ -0,0 +1,46 @@
+/** The runner's `it`: registers one case under a name. */
+export type LambderConformanceIt = (name: string, run: () => Promise<void>) => unknown;
+/** The part of a jest-style assertion the suites use, which vitest's and jest's `expect` both provide. */
+export type LambderConformanceAssertion = {
+    toBe(expected: unknown): void;
+    toEqual(expected: unknown): void;
+    toMatchObject(expected: object): void;
+    toBeNull(): void;
+    toBeUndefined(): void;
+    toBeTruthy(): void;
+    toHaveLength(length: number): void;
+    toBeGreaterThan(value: number): void;
+    not: {
+        toBe(expected: unknown): void;
+        toBeNull(): void;
+    };
+    rejects: {
+        toThrow(): Promise<unknown>;
+    };
+    resolves: {
+        toBeNull(): Promise<unknown>;
+    };
+};
+/** The runner's `expect`. */
+export type LambderConformanceExpect = (actual: unknown) => LambderConformanceAssertion;
+/** The two things every suite takes from the runner. */
+export type LambderConformanceRunner = {
+    it: LambderConformanceIt;
+    expect: LambderConformanceExpect;
+};
+/**
+ * What a store factory is handed for one case: the clock the case moves, in
+ * epoch milliseconds. A store that judges time itself (a memory store
+ * expiring its entries) must read it from here; the system clock does not
+ * move with it, so a store that read Date.now() behind its `now` option
+ * would see time standing still and fail the expiry rules.
+ */
+export type LambderConformanceSetup = {
+    now: () => number;
+};
+/** Where every case's clock starts: a fixed moment, so the records a case writes are the same on every run. */
+export declare const CONFORMANCE_START_MILLIS = 1700000000000;
+/** The clock of one case: `now` for the store, `set` for the case. */
+export declare const conformanceClock: () => LambderConformanceSetup & {
+    set(millis: number): void;
+};

package/dist/testing/LambderConformanceRunner.js

@@ -0,0 +1,21 @@
+/*
+ * What the store conformance suites register their cases with, and the clock
+ * each case runs on.
+ *
+ * A suite is the set of rules one store interface promises, written once and
+ * driven through every implementation: Lambder's own memory and DynamoDB
+ * stores, and any store an app writes over its own database. The suites take
+ * the test runner's `it` and `expect` rather than importing one, so they run
+ * under vitest, jest, or any runner with a jest-style `expect`, and the
+ * package depends on none of them.
+ */
+/** Where every case's clock starts: a fixed moment, so the records a case writes are the same on every run. */
+export const CONFORMANCE_START_MILLIS = 1_700_000_000_000;
+/** The clock of one case: `now` for the store, `set` for the case. */
+export const conformanceClock = () => {
+    let millis = CONFORMANCE_START_MILLIS;
+    return {
+        now: () => millis,
+        set: (next) => { millis = next; },
+    };
+};

package/dist/testing/lambderIdempotencyStoreConformance.d.ts

@@ -0,0 +1,33 @@
+import type { LambderIdempotencyStore } from "../shared/contracts/LambderIdempotencyStore.js";
+import { type LambderConformanceRunner, type LambderConformanceSetup } from "./LambderConformanceRunner.js";
+export type LambderIdempotencyStoreConformanceOptions = LambderConformanceRunner & {
+    /** A store holding nothing, built for one case over the case's clock. */
+    create: (setup: LambderConformanceSetup) => LambderIdempotencyStore | Promise<LambderIdempotencyStore>;
+    /**
+     * A body this store will not hold. The budget is the store's own business
+     * (a DynamoDB store measures what it writes after compression, a memory
+     * store the bytes), so each says what "too big" means for it.
+     */
+    oversizedBody: string;
+    /** The other side of the same budget: the largest body this store does hold, so the boundary is pinned from both directions. */
+    largestStorableBody: string;
+};
+/**
+ * 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 declare const lambderIdempotencyStoreConformance: (options: LambderIdempotencyStoreConformanceOptions) => void;

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;