lambder 7.3.1 → 8.0.2

package/dist/stores/LambderDdbIdempotencyStore.d.ts

@@ -32,23 +32,23 @@ export interface LambderDdbIdempotencyStoreOptions {
  *
  * Every claim carries a random ownerToken, and complete()/abandon() are
  * conditional on still holding it: an original that outlives its pending TTL
- * and loses the scope to a retry can no longer overwrite or delete the
- * retry's claim (both settle calls become silent no-ops instead). complete()
- * also requires the claim to be unexpired, so an owner whose claim ran out
- * reports "lost" whether or not TTL deletion has caught up with it, which is
- * what the memory store has always reported.
+ * and loses the scope to a retry cannot overwrite or delete the retry's claim
+ * (both settle calls become silent no-ops). complete() also requires the
+ * claim to be unexpired, so an owner whose claim ran out reports "lost"
+ * whether or not TTL deletion has caught up with it, as the memory store
+ * does. abandon() also requires the claim to be pending, so it never deletes
+ * a stored answer.
  *
- * Stored bodies are Brotli-compressed from 1KB by default (same scheme as
- * LambderDdbCache, see the `compression` option): the bodies are JSON
- * envelopes that typically shrink 5-10x, which cuts DynamoDB write units
- * and lets large responses fit the item budget instead of skipping replay
- * storage.
+ * Stored bodies are Brotli-compressed from 1KB by default (the scheme
+ * LambderDdbCache uses, see the `compression` option): JSON envelopes
+ * typically shrink 5-10x, which cuts write units and lets large responses
+ * fit the item budget instead of skipping replay storage.
  *
  * The scope key carries caller data (the client's idempotency key, and an
- * identity when one is configured), so a scope whose partition key would pass
- * DynamoDB's 2048-byte limit is refused here with an error that names the
- * limit, rather than reaching the table and coming back as a
- * ValidationException that reads as "the table is broken".
+ * identity when one is configured), so a partition key past DynamoDB's
+ * 2048-byte limit is refused here with an error naming the limit, rather
+ * than coming back from the table as a ValidationException that reads as
+ * "the table is broken".
  *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on
  * `expiresAt`. Items are prefixed `IDEM#` by default, so the table can be
@@ -81,6 +81,8 @@ export declare class LambderDdbIdempotencyStore implements LambderIdempotencySto
     private static readItemBody;
     /** A stored answer as the engine reads it, with every field of the record checked rather than cast. */
     private static answerOf;
+    /** The request fingerprint an item keeps; see UNKNOWN_REQUEST_FINGERPRINT for one that keeps none. */
+    private static fingerprintOf;
     /**
      * Read the scope without claiming it: the stored response when a
      * completed, unexpired record exists, null otherwise (absent, pending, or
@@ -93,17 +95,22 @@ export declare class LambderDdbIdempotencyStore implements LambderIdempotencySto
      * returned ownerToken) and must call complete() or abandon(); "pending"
      * means another request owns it right now; "done" carries the stored
      * response to replay.
+     *
+     * One write either way: a refused claim hands back the item that refused
+     * it (ALL_OLD), so there is no read after it. That item is also how a
+     * claim the SDK retried after it had already landed recognizes itself:
+     * the item carries this call's own ownerToken, so the scope is ours
+     * rather than somebody else's in-flight original.
      */
-    begin(scopeKey: string, { pendingTtlSeconds }: {
+    begin(scopeKey: string, { pendingTtlSeconds, fingerprint }: {
         pendingTtlSeconds: number;
+        fingerprint: string;
     }): Promise<LambderIdempotencyBeginResult>;
     /**
      * Store the response for replays, overwriting the pending claim. Bodies
-     * from the compression option's minBytes are stored Brotli-compressed
-     * (they are JSON envelopes, which typically shrink 5-10x), cutting
-     * DynamoDB write units and letting large responses fit the item budget;
-     * smaller bodies, or all of them with compression off, stay plain.
-     * Returns:
+     * from the compression option's minBytes up are stored Brotli-compressed
+     * (see the class comment); smaller bodies, or all of them with
+     * compression off, stay plain. Returns:
      *
      * - "stored": the record is in place and will replay.
      * - "too-large": even compressed, the body exceeds the item budget;
@@ -111,13 +118,17 @@ export declare class LambderDdbIdempotencyStore implements LambderIdempotencySto
      * - "lost": the ownerToken no longer matches, i.e. the claim expired and
      *   a retry took the scope over; nothing was written.
      */
-    complete(scopeKey: string, ownerToken: string, { statusCode, headers, body, ttlSeconds }: LambderIdempotencyDoneRecord & {
+    complete(scopeKey: string, ownerToken: string, { statusCode, headers, body, fingerprint, ttlSeconds }: LambderIdempotencyDoneRecord & {
         ttlSeconds: number;
     }): Promise<"stored" | "too-large" | "lost">;
     /**
      * Release the claim without storing a response (crash, uncacheable
      * response), so a retry can execute. Conditional on still holding the
-     * claim; a lost claim makes this a silent no-op.
+     * claim AND on its still being pending: a lost claim makes this a silent
+     * no-op, and so does a settled record, whose owner token is still the
+     * caller's. The engine abandons after a complete() that threw, and one
+     * whose response was lost may have landed; deleting its record would
+     * hand the retry a free scope, and the operation would run twice.
      */
     abandon(scopeKey: string, ownerToken: string): Promise<void>;
 }

package/dist/stores/LambderDdbIdempotencyStore.js

@@ -11,15 +11,24 @@ const COMPRESSION_DEFAULTS = { minBytes: 1024, quality: 5 };
  */
 const MAX_STORED_BODY_BYTES = 350_000;
 /**
- * Ceiling on a stored body's declared length, which is the budget the restore
+ * Ceiling on a stored body's declared length, the budget the restore
  * decompresses under. The store's own writes stay far inside it (a response
- * that reaches a client at all is a few megabytes at most, and the compressed
- * bytes have to fit MAX_STORED_BODY_BYTES), so a record declaring more than
- * this is one this store did not write, and taking its word for it would let
- * a few hundred kilobytes of Brotli expand until the function dies. The
- * cache bounds the same number the same way, against its maxValueBytes.
+ * that reaches a client is a few megabytes at most, and the compressed bytes
+ * must fit MAX_STORED_BODY_BYTES), so a record declaring more is not this
+ * store's, and trusting it would let a few hundred kilobytes of Brotli expand
+ * until the function dies. The cache bounds the same number against its
+ * maxValueBytes.
  */
 const MAX_REPLAY_BODY_BYTES = 32 * 1024 * 1024;
+/**
+ * What an item that keeps no fingerprint reports: one no request matches,
+ * since the engine's fingerprints are never empty. Such an item was not
+ * written by this store (every claim and record it writes keeps one), so the
+ * engine refuses the key as reused, a 409 a key scope moves past, rather than
+ * replaying an answer it cannot tie to the request or reading the scope as
+ * free and running the request over it.
+ */
+const UNKNOWN_REQUEST_FINGERPRINT = "";
 /**
  * A number attribute as stored, or the fallback when it is missing or not a
  * number. `Number(undefined)` and `Number("nope")` are both NaN, which every
@@ -47,23 +56,23 @@ const newOwnerToken = async () => {
  *
  * Every claim carries a random ownerToken, and complete()/abandon() are
  * conditional on still holding it: an original that outlives its pending TTL
- * and loses the scope to a retry can no longer overwrite or delete the
- * retry's claim (both settle calls become silent no-ops instead). complete()
- * also requires the claim to be unexpired, so an owner whose claim ran out
- * reports "lost" whether or not TTL deletion has caught up with it, which is
- * what the memory store has always reported.
+ * and loses the scope to a retry cannot overwrite or delete the retry's claim
+ * (both settle calls become silent no-ops). complete() also requires the
+ * claim to be unexpired, so an owner whose claim ran out reports "lost"
+ * whether or not TTL deletion has caught up with it, as the memory store
+ * does. abandon() also requires the claim to be pending, so it never deletes
+ * a stored answer.
  *
- * Stored bodies are Brotli-compressed from 1KB by default (same scheme as
- * LambderDdbCache, see the `compression` option): the bodies are JSON
- * envelopes that typically shrink 5-10x, which cuts DynamoDB write units
- * and lets large responses fit the item budget instead of skipping replay
- * storage.
+ * Stored bodies are Brotli-compressed from 1KB by default (the scheme
+ * LambderDdbCache uses, see the `compression` option): JSON envelopes
+ * typically shrink 5-10x, which cuts write units and lets large responses
+ * fit the item budget instead of skipping replay storage.
  *
  * The scope key carries caller data (the client's idempotency key, and an
- * identity when one is configured), so a scope whose partition key would pass
- * DynamoDB's 2048-byte limit is refused here with an error that names the
- * limit, rather than reaching the table and coming back as a
- * ValidationException that reads as "the table is broken".
+ * identity when one is configured), so a partition key past DynamoDB's
+ * 2048-byte limit is refused here with an error naming the limit, rather
+ * than coming back from the table as a ValidationException that reads as
+ * "the table is broken".
  *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on
  * `expiresAt`. Items are prefixed `IDEM#` by default, so the table can be
@@ -148,8 +157,13 @@ export class LambderDdbIdempotencyStore {
             statusCode: storedNumber(item.statusCode?.N, 200),
             headers: LambderDdbIdempotencyStore.readItemHeaders(item),
             body: await LambderDdbIdempotencyStore.readItemBody(item),
+            fingerprint: LambderDdbIdempotencyStore.fingerprintOf(item),
         };
     }
+    /** The request fingerprint an item keeps; see UNKNOWN_REQUEST_FINGERPRINT for one that keeps none. */
+    static fingerprintOf(item) {
+        return item.fingerprint?.S ?? UNKNOWN_REQUEST_FINGERPRINT;
+    }
     /**
      * Read the scope without claiming it: the stored response when a
      * completed, unexpired record exists, null otherwise (absent, pending, or
@@ -174,10 +188,17 @@ export class LambderDdbIdempotencyStore {
      * returned ownerToken) and must call complete() or abandon(); "pending"
      * means another request owns it right now; "done" carries the stored
      * response to replay.
+     *
+     * One write either way: a refused claim hands back the item that refused
+     * it (ALL_OLD), so there is no read after it. That item is also how a
+     * claim the SDK retried after it had already landed recognizes itself:
+     * the item carries this call's own ownerToken, so the scope is ours
+     * rather than somebody else's in-flight original.
      */
-    async begin(scopeKey, { pendingTtlSeconds }) {
+    async begin(scopeKey, { pendingTtlSeconds, fingerprint }) {
         const nowSeconds = this.nowSeconds();
         const ownerToken = await newOwnerToken();
+        let item;
         try {
             const { client, sdk } = await this.ready();
             await client.send(new sdk.PutItemCommand({
@@ -186,33 +207,33 @@ export class LambderDdbIdempotencyStore {
                     ...this.itemKey(scopeKey),
                     state: { S: "pending" },
                     ownerToken: { S: ownerToken },
+                    fingerprint: { S: fingerprint },
                     expiresAt: { N: String(nowSeconds + pendingTtlSeconds) },
                 },
                 // Every clause is one a missing attribute can satisfy rather
                 // than block: DynamoDB reads a comparison whose operand path
-                // is absent as FALSE, so a condition that only asked
-                // `expiresAt <= :now` refused an item carrying no expiry for
-                // ever, and a pending one of those deadlocked its scope with
-                // no TTL able to retire it.
+                // is absent as FALSE, so `expiresAt <= :now` alone would
+                // refuse an item carrying no expiry for ever, and a pending
+                // one would deadlock its scope with no TTL able to retire it.
                 ConditionExpression: "attribute_not_exists(pk) OR attribute_not_exists(expiresAt) OR expiresAt <= :now",
                 ExpressionAttributeValues: { ":now": { N: String(nowSeconds) } },
+                ReturnValuesOnConditionCheckFailure: "ALL_OLD",
             }));
             return { state: "new", ownerToken };
         }
         catch (error) {
             if (!isConditionalCheckFailure(error))
                 throw error;
+            item = error.Item;
         }
-        const { client, sdk } = await this.ready();
-        const existing = await client.send(new sdk.GetItemCommand({
-            TableName: this.tableName,
-            Key: this.itemKey(scopeKey),
-            ConsistentRead: true,
-        }));
-        const item = existing.Item;
-        // Deleted between the put and the read: treat as in-flight, the retry resolves it.
+        // Refused with no item to show for it: gone again by the time the
+        // condition was read, which the next retry resolves. The caller's own
+        // fingerprint keeps it the in-flight 409, which a client retries
+        // under the same key.
         if (!item)
-            return { state: "pending" };
+            return { state: "pending", fingerprint };
+        if (item.ownerToken?.S === ownerToken)
+            return { state: "new", ownerToken };
         // The same expiry test peek runs, because the condition above cannot
         // make it: an item whose expiresAt is present but unreadable (a
         // partial write, another writer on a shared table) refuses the claim
@@ -222,15 +243,13 @@ export class LambderDdbIdempotencyStore {
         const live = storedNumber(item.expiresAt?.N, 0) > nowSeconds;
         if (live && item.state?.S === "done")
             return { state: "done", ...await LambderDdbIdempotencyStore.answerOf(item) };
-        return { state: "pending" };
+        return { state: "pending", fingerprint: LambderDdbIdempotencyStore.fingerprintOf(item) };
     }
     /**
      * Store the response for replays, overwriting the pending claim. Bodies
-     * from the compression option's minBytes are stored Brotli-compressed
-     * (they are JSON envelopes, which typically shrink 5-10x), cutting
-     * DynamoDB write units and letting large responses fit the item budget;
-     * smaller bodies, or all of them with compression off, stay plain.
-     * Returns:
+     * from the compression option's minBytes up are stored Brotli-compressed
+     * (see the class comment); smaller bodies, or all of them with
+     * compression off, stay plain. Returns:
      *
      * - "stored": the record is in place and will replay.
      * - "too-large": even compressed, the body exceeds the item budget;
@@ -238,7 +257,7 @@ export class LambderDdbIdempotencyStore {
      * - "lost": the ownerToken no longer matches, i.e. the claim expired and
      *   a retry took the scope over; nothing was written.
      */
-    async complete(scopeKey, ownerToken, { statusCode, headers, body, ttlSeconds }) {
+    async complete(scopeKey, ownerToken, { statusCode, headers, body, fingerprint, ttlSeconds }) {
         const nowSeconds = this.nowSeconds();
         const rawBody = Buffer.from(body, "utf8");
         let bodyAttributes;
@@ -275,15 +294,15 @@ export class LambderDdbIdempotencyStore {
                     statusCode: { N: String(statusCode) },
                     headersJson: { S: JSON.stringify(headers) },
                     ...bodyAttributes,
+                    fingerprint: { S: fingerprint },
                     expiresAt: { N: String(nowSeconds + ttlSeconds) },
                 },
                 // The claim has to be BOTH still owned and still live. Owner
-                // alone let an owner whose claim had already expired store
-                // over it, because DynamoDB's TTL deletion is lazy and the
-                // expired item is usually still sitting there. The memory
-                // store drops an expired entry on read and answered "lost"
-                // for the same call, so the two disagreed, and DynamoDB's
-                // answer depended on whether AWS had got round to the sweep.
+                // alone would let an owner whose claim has expired store over
+                // it, since DynamoDB's TTL deletion is lazy and the expired
+                // item is usually still there; the memory store answers "lost"
+                // for the same call, and DynamoDB's answer would depend on
+                // whether AWS had run the sweep yet.
                 ConditionExpression: "ownerToken = :owner AND expiresAt > :now",
                 ExpressionAttributeValues: { ":owner": { S: ownerToken }, ":now": { N: String(nowSeconds) } },
             }));
@@ -298,7 +317,11 @@ export class LambderDdbIdempotencyStore {
     /**
      * Release the claim without storing a response (crash, uncacheable
      * response), so a retry can execute. Conditional on still holding the
-     * claim; a lost claim makes this a silent no-op.
+     * claim AND on its still being pending: a lost claim makes this a silent
+     * no-op, and so does a settled record, whose owner token is still the
+     * caller's. The engine abandons after a complete() that threw, and one
+     * whose response was lost may have landed; deleting its record would
+     * hand the retry a free scope, and the operation would run twice.
      */
     async abandon(scopeKey, ownerToken) {
         try {
@@ -306,8 +329,10 @@ export class LambderDdbIdempotencyStore {
             await client.send(new sdk.DeleteItemCommand({
                 TableName: this.tableName,
                 Key: this.itemKey(scopeKey),
-                ConditionExpression: "ownerToken = :owner",
-                ExpressionAttributeValues: { ":owner": { S: ownerToken } },
+                // `state` is a DynamoDB reserved word, hence the name placeholder.
+                ConditionExpression: "ownerToken = :owner AND #state = :pending",
+                ExpressionAttributeNames: { "#state": "state" },
+                ExpressionAttributeValues: { ":owner": { S: ownerToken }, ":pending": { S: "pending" } },
             }));
         }
         catch (error) {

package/dist/stores/LambderDdbRateLimiter.d.ts

@@ -19,29 +19,61 @@ export interface LambderDdbRateLimiterOptions {
 /**
  * Fixed-window rate limiter backed by DynamoDB.
  *
- * Each window is a single item counted with a conditional `ADD`, so the
- * increment and the limit check happen atomically in one request. Windows are
- * evaluated from smallest to largest and evaluation stops at the first
- * exceeded window, which keeps blocked requests cheap and spares the larger
- * counters. Attempts count, not successes: a counter checked before the
- * refusing one keeps its increment (there is no compensating decrement, which
- * would give up the conditional-ADD atomicity). Items carry an `expiresAt`
- * attribute for DynamoDB TTL.
+ * Each window is one item counted with a conditional `ADD`, so the increment
+ * and the limit check are one atomic request. Windows are evaluated smallest
+ * first and evaluation stops at the first exceeded one, which keeps blocked
+ * requests cheap and spares the larger counters. Attempts count, not
+ * successes: a counter checked before the refusing one keeps its increment,
+ * since a compensating decrement would give up the conditional-ADD
+ * atomicity. Items carry an `expiresAt` attribute for DynamoDB TTL.
  *
  * The tracker key is caller data (an address, a session key, whatever a
  * policy handler returned), so a key whose partition key would pass
- * DynamoDB's 2048-byte limit is refused here, before any window is counted,
- * rather than reaching the table and coming back as a ValidationException:
- * that is not a conditional-check failure, so it escapes as a store error and
- * a caller failing open on it counts nothing at all, which is the limit
- * silently off. Lambder's own engine folds an over-long key into a digest
- * long before this, so a key that gets here came from a direct caller.
+ * DynamoDB's 2048-byte limit is refused here, before any window is counted.
+ * At the table it would come back as a ValidationException, which is not a
+ * conditional-check failure: it would escape as a store error, and a caller
+ * failing open on it would count nothing, leaving the limit silently off.
+ * Lambder's own engine folds an over-long key into a digest first, so a key
+ * that gets here came from a direct caller.
  *
- * A DynamoDB error propagates: a limiter says whether the caller is over its
- * limit, and it cannot answer that question when it cannot reach the table.
- * Whether an unanswerable limit lets the request through is the application's
- * call, not the storage's, so it is made once for every limiter at
- * `rateLimits.failOpen` and the engine there handles the throw.
+ * A DynamoDB error propagates: a limiter cannot say whether the caller is
+ * over its limit when it cannot reach the table, and whether an unanswerable
+ * limit lets the request through is the application's call, made once for
+ * every limiter at `rateLimits.failOpen`.
+ *
+ * A throttle on the key's range can be an answer instead. DynamoDB
+ * throttles a partition's writes at roughly a thousand a second, and the SDK
+ * retries first, so a throttle whose reason is KeyRangeThroughputExceeded
+ * means the partition holding this counter is flooded. A partition holds a
+ * range of keys, though, not one: a flood on one address, or a session or
+ * cache spike on a shared table, throttles every counter on the same
+ * partition. The key's own counts tell the flood from its neighbours: the
+ * throttled window's and every capped window's after it, the ones this
+ * attempt has not been counted against yet, each read with a consistent
+ * GetItem, in parallel (reads have their own throughput, which the throttled
+ * writes leave alone). A key at or over the limit of any of them is the
+ * flood: it is refused, since passed on as a failure `failOpen` would wave
+ * the flood through unmetered, and the Retry-After is a few seconds, the
+ * time the partition takes to recover, rather than the window's reset. A key
+ * over its daily cap whose per-minute counter has just started again is the
+ * flood as much as one over its per-minute cap. Under every limit, or when a
+ * read fails too, the key is a neighbour: the throttle propagates like any
+ * other store failure and `failOpen` decides, as it does for a throttle of
+ * the table or the account (its provisioned capacity, an on-demand maximum,
+ * the account's quota), so no caller under its limit is refused because the
+ * table is busy with somebody else.
+ *
+ * A flood repeats, and each repeat would cost the partition another
+ * throttled write and another consistent read, until the reads throttle too
+ * and the flood fails open. So the process remembers, for
+ * THROTTLED_RETRY_SECONDS, each window it read at its limit, and refuses the
+ * key's next attempts from memory without touching the table, which also
+ * lets the partition recover for the neighbours. A count only rises within
+ * its window, so the table would answer the same. A window whose read was
+ * throttled as well is remembered too, with the throttle it was answered
+ * with: a next attempt whose write is throttled there again skips the read
+ * and throws that same throttle, which `rateLimits.failOpen` logs once
+ * rather than once per request.
  *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on `expiresAt`.
  * Items are prefixed `RL#` by default, so the table can be shared with
@@ -55,7 +87,11 @@ export declare class LambderDdbRateLimiter implements LambderRateLimiter {
     private readonly ready;
     private readonly ttlWindowMultiplier;
     private readonly now;
+    /** The windows seen during key-range throttles, by (partition key, window, window start); see the class doc. */
+    private readonly throttledWindows;
     constructor(options: LambderDdbRateLimiterOptions);
+    /** The clock the windows are computed against, for the engine's Retry-After. */
+    clockMilliseconds(): number;
     /**
      * Increment every configured window for `trackerKey` (IP, session, user id, ...)
      * and report whether any of them is over its limit, with the window's
@@ -64,7 +100,27 @@ export declare class LambderDdbRateLimiter implements LambderRateLimiter {
     isRateLimited(trackerKey: string, policy: LambderRateLimitPolicy): Promise<LambderRateLimitResult>;
     /** The item's partition key, refused when the tracker key makes it one DynamoDB will not take. */
     private partitionKeyFor;
-    /** Increments one window counter. Returns true when the limit was already reached. */
+    /**
+     * Increments one window counter. True when the limit was already reached
+     * (the refused condition is the limiter's own answer); any other failure
+     * throws.
+     */
     private incrementWindow;
+    /**
+     * The answer to a key-range throttle on the first of `uncounted`: that
+     * window and every capped one after it, the windows this attempt has not
+     * been counted against. The windows before it counted this attempt and
+     * allowed it, so reading them could only turn the attempt that filled
+     * one into a refusal.
+     *
+     * Each count is read strongly consistent: the count that decides is the
+     * one the throttled writes were racing to raise, and a replica lagging
+     * behind them could read a key that has just reached its limit as under
+     * it. Any window at or over its limit refuses, and is remembered (see the
+     * class doc). Otherwise the throttle is thrown on, and when a read was
+     * throttled too, the throttled window is remembered with it, so the
+     * key's next attempts skip the read and throw that same throttle.
+     */
+    private answerKeyRangeThrottle;
 }
 export default LambderDdbRateLimiter;