lambder 7.3.1 → 8.0.2

package/dist/stores/LambderDdbRateLimiter.js

@@ -1,32 +1,82 @@
-import { assertPartitionKeyFits, createDynamoClientLoader, isConditionalCheckFailure, } from "./LambderDdbSdk.js";
+import { assertPartitionKeyFits, createDynamoClientLoader, isConditionalCheckFailure, isKeyRangeThrottle, } from "./LambderDdbSdk.js";
 import { assertNumberAtLeast } from "../shared/util/LambderOptionChecks.js";
+import { LambderExpiringMap } from "../shared/util/LambderExpiringMap.js";
+import { joinKeyFields } from "../shared/util/joinKeyFields.js";
 import { RATE_LIMIT_WINDOWS, } from "../shared/contracts/LambderRateLimiter.js";
+/** How long a key refused during a throttle is told to wait: long enough to let the partition recover, short enough for a legitimate caller. */
+const THROTTLED_RETRY_SECONDS = 5;
+/**
+ * Most (tracker key, window) pairs the limiter remembers from throttles at
+ * once. Only a key seen during a key-range throttle is remembered, for
+ * THROTTLED_RETRY_SECONDS, so this is reached only by a flood spread over
+ * that many keys at once, where the ones closest to expiring go first.
+ */
+const THROTTLED_WINDOW_MEMORY_ENTRIES = 10_000;
+/** The table key of one window's counter. */
+const counterKeyOf = (partitionKey, window) => ({
+    pk: { S: partitionKey },
+    sk: { S: `${window.key}#${window.start}` },
+});
+/** The same counter's key in the limiter's memory of throttled windows, its fields kept apart as the table's two attributes keep them. */
+const rememberedWindowKeyOf = (partitionKey, window) => joinKeyFields(partitionKey, window.key, String(window.start));
 /**
  * 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 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 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 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
@@ -40,6 +90,8 @@ export class LambderDdbRateLimiter {
     ready;
     ttlWindowMultiplier;
     now;
+    /** The windows seen during key-range throttles, by (partition key, window, window start); see the class doc. */
+    throttledWindows;
     constructor(options) {
         if (!options.tableName.trim())
             throw new Error("tableName is required");
@@ -47,8 +99,13 @@ export class LambderDdbRateLimiter {
         this.keyPrefix = options.keyPrefix ?? "RL";
         this.ttlWindowMultiplier = assertNumberAtLeast(options.ttlWindowMultiplier ?? 2, 1, "ttlWindowMultiplier");
         this.now = options.now ?? (() => Date.now());
+        this.throttledWindows = new LambderExpiringMap({ now: this.now, maxEntries: THROTTLED_WINDOW_MEMORY_ENTRIES });
         this.ready = createDynamoClientLoader({ user: "LambderDdbRateLimiter", region: options.region, client: options.client });
     }
+    /** The clock the windows are computed against, for the engine's Retry-After. */
+    clockMilliseconds() {
+        return this.now();
+    }
     /**
      * Increment every configured window for `trackerKey` (IP, session, user id, ...)
      * and report whether any of them is over its limit, with the window's
@@ -61,14 +118,30 @@ export class LambderDdbRateLimiter {
         // refusing it here is the difference between one clear error and a
         // policy that counts nothing while reporting nothing.
         const partitionKey = this.partitionKeyFor(trackerKey);
-        for (const { key, seconds } of RATE_LIMIT_WINDOWS) {
-            const limit = policy[key];
-            if (!limit)
-                continue;
-            const windowStart = Math.floor(nowSeconds / seconds) * seconds;
-            const exceeded = await this.incrementWindow(partitionKey, key, windowStart, seconds, limit, nowSeconds);
-            if (exceeded)
-                return { window: key, limit, resetAt: windowStart + seconds };
+        const windows = RATE_LIMIT_WINDOWS
+            .filter(({ key }) => policy[key])
+            .map(({ key, seconds }) => ({ key, seconds, limit: policy[key], start: Math.floor(nowSeconds / seconds) * seconds }));
+        // A window this process read at its limit during a throttle refuses
+        // without touching the table (see the class doc).
+        const rememberedAtLimit = windows.find((window) => {
+            const remembered = this.throttledWindows.get(rememberedWindowKeyOf(partitionKey, window));
+            return remembered !== undefined && "count" in remembered && remembered.count >= window.limit;
+        });
+        if (rememberedAtLimit)
+            return { window: rememberedAtLimit.key, limit: rememberedAtLimit.limit, resetAt: nowSeconds + THROTTLED_RETRY_SECONDS };
+        for (const [index, window] of windows.entries()) {
+            try {
+                if (await this.incrementWindow(partitionKey, window, nowSeconds))
+                    return { window: window.key, limit: window.limit, resetAt: window.start + window.seconds };
+            }
+            catch (error) {
+                // A key-range throttle may be the limiter's own answer (see
+                // the class doc); anything else is the table failing, which
+                // only the caller can decide what to do about.
+                if (!isKeyRangeThrottle(error))
+                    throw error;
+                return await this.answerKeyRangeThrottle(partitionKey, windows.slice(index), nowSeconds, error);
+            }
         }
         return false;
     }
@@ -81,22 +154,23 @@ export class LambderDdbRateLimiter {
             remedy: "Shorten the key the policy hands the limiter.",
         });
     }
-    /** Increments one window counter. Returns true when the limit was already reached. */
-    async incrementWindow(partitionKey, sortKeyPrefix, windowStart, windowSeconds, limit, nowSeconds) {
-        const expiresAt = nowSeconds + Math.ceil(windowSeconds * this.ttlWindowMultiplier);
+    /**
+     * Increments one window counter. True when the limit was already reached
+     * (the refused condition is the limiter's own answer); any other failure
+     * throws.
+     */
+    async incrementWindow(partitionKey, window, nowSeconds) {
+        const expiresAt = nowSeconds + Math.ceil(window.seconds * this.ttlWindowMultiplier);
         const input = {
             TableName: this.tableName,
-            Key: {
-                pk: { S: partitionKey },
-                sk: { S: `${sortKeyPrefix}#${windowStart}` },
-            },
+            Key: counterKeyOf(partitionKey, window),
             UpdateExpression: "ADD #count :one SET #expiresAt = if_not_exists(#expiresAt, :expiresAt)",
             ConditionExpression: "attribute_not_exists(#count) OR #count < :limit",
             ExpressionAttributeNames: { "#count": "count", "#expiresAt": "expiresAt" },
             ExpressionAttributeValues: {
                 ":one": { N: "1" },
                 ":expiresAt": { N: String(expiresAt) },
-                ":limit": { N: String(limit) },
+                ":limit": { N: String(window.limit) },
             },
         };
         try {
@@ -105,13 +179,51 @@ export class LambderDdbRateLimiter {
             return false;
         }
         catch (error) {
-            // The refused condition is the limiter's own answer; anything else
-            // is the table being unreachable, which only the caller can decide
-            // what to do about.
             if (isConditionalCheckFailure(error))
                 return true;
             throw error;
         }
     }
+    /**
+     * 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.
+     */
+    async answerKeyRangeThrottle(partitionKey, uncounted, nowSeconds, throttle) {
+        const throttledWindowKey = rememberedWindowKeyOf(partitionKey, uncounted[0]);
+        const remembered = this.throttledWindows.get(throttledWindowKey);
+        if (remembered !== undefined && "unreadable" in remembered)
+            throw remembered.unreadable;
+        const { client, sdk } = await this.ready();
+        const reads = await Promise.allSettled(uncounted.map(async (window) => {
+            const { Item } = await client.send(new sdk.GetItemCommand({ TableName: this.tableName, Key: counterKeyOf(partitionKey, window), ConsistentRead: true }));
+            return Number(Item?.count?.N ?? 0);
+        }));
+        const rememberUntil = nowSeconds + THROTTLED_RETRY_SECONDS;
+        let refusing;
+        for (const [index, read] of reads.entries()) {
+            const window = uncounted[index];
+            if (read.status === "fulfilled" && read.value >= window.limit) {
+                this.throttledWindows.set(rememberedWindowKeyOf(partitionKey, window), { count: read.value }, rememberUntil);
+                refusing ??= window;
+            }
+        }
+        if (refusing)
+            return { window: refusing.key, limit: refusing.limit, resetAt: rememberUntil };
+        if (reads.some((read) => read.status === "rejected" && isKeyRangeThrottle(read.reason))) {
+            this.throttledWindows.set(throttledWindowKey, { unreadable: throttle }, rememberUntil);
+        }
+        throw throttle;
+    }
 }
 export default LambderDdbRateLimiter;

package/dist/stores/LambderDdbSdk.d.ts

@@ -2,20 +2,18 @@
  * The DynamoDB SDK, loaded on first use.
  *
  * `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` are optional peer
- * dependencies, and an app that keeps no sessions and uses none of the
- * DynamoDB stores should neither install them nor pay for loading them: a
- * module-level import costs every cold start something and, bundled, makes
- * every Lambder app reference both packages. So the session manager and the
- * three stores import their types only and take the classes from here the
- * first time they touch the table, the way LambderS3FileSource and
- * LambderInvokeCaller load theirs. One loader per package, memoized for the
- * container's life; a missing package fails that first call with the
- * install hint rather than failing the import of lambder itself.
+ * dependencies: an app that uses no DynamoDB store should neither install
+ * them nor pay for loading them, and a module-level import would cost every
+ * cold start and make every bundled Lambder app reference both packages. So
+ * the session manager and the stores import their types only and take the
+ * classes from here the first time they touch the table, as
+ * LambderS3FileSource and LambderInvokeCaller do. One loader per package,
+ * memoized for the container's life; a missing package fails that first call
+ * with the install hint rather than failing the import of lambder itself.
  *
- * The two facts about DynamoDB itself that every one of those stores has to
- * agree on live here as well, for the same reason: a conditional write's
- * refusal is an answer rather than a failure, and a partition key has a
- * limit that the caller data these stores build keys from can pass.
+ * The facts about DynamoDB itself that every store must agree on live here
+ * too: a conditional write's refusal is an answer rather than a failure, and
+ * a partition key has a limit that keys built from caller data can pass.
  */
 import type { DynamoDBClient } from "@aws-sdk/client-dynamodb";
 import type { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
@@ -28,19 +26,16 @@ export type LambderDynamoClientReady = {
 };
 /**
  * The "ready" step each DynamoDB-backed store runs before its first table
- * call: load the SDK, then take the client the app supplied or build one.
- * Memoized for the store's life, and a FAILED load is deliberately not, so a
- * store that ran before the package was installed asks again rather than
- * caching the install hint for ever.
+ * call: load the SDK, then take the client the app supplied or the shared
+ * default one for the store's region. Memoized for the store's life, except
+ * that a FAILED load is not, so a store that ran before the package was
+ * installed asks again rather than caching the install hint forever.
  *
- * Written once because four stores had written it for themselves and had
- * already drifted apart on the region: three passed the SDK's default chain
- * through and the cache pinned `us-east-1`, so one store out of four ignored
- * the deployment's own region.
- *
- * `region` absent means the SDK's default chain (`AWS_REGION`, the Lambda
- * environment, the shared config file), which is what a store should leave
- * alone unless the caller names one.
+ * One implementation for every store, so they cannot drift apart on the
+ * region. `region` absent means the SDK's default chain (`AWS_REGION`, the
+ * Lambda environment, the shared config file); a store leaves it alone
+ * unless the caller names one, since pinning one (say `us-east-1`) would
+ * ignore the deployment's own region.
  */
 export declare const createDynamoClientLoader: (options: {
     user: string;
@@ -71,6 +66,23 @@ export declare const createDynamoDocumentClientLoader: (options: {
  * and the reason they must not catch any other.
  */
 export declare const isConditionalCheckFailure: (error: unknown) => boolean;
+/**
+ * Whether DynamoDB refused a request, after the SDK's own retries, because
+ * of the rate at one key range, rather than the table's or the account's.
+ * A key range is a partition, which holds many keys, so the throttle falls
+ * on the key asked about and on its neighbours alike: whether this key is
+ * the one flooding it is the caller's to find out.
+ *
+ * Every throttle names why in its ThrottlingReasons (throttlingReasons on a
+ * ThrottlingException), as `<Table|Index><Read|Write><LimitType>`; only
+ * KeyRangeThroughputExceeded is about one partition. The other limit types
+ * (ProvisionedThroughputExceeded, AccountLimitExceeded,
+ * MaxOnDemandThroughputExceeded) are the table or the account running out,
+ * which says nothing about any one partition. An SDK older than the reasons
+ * (`@aws-sdk/client-dynamodb` before 3.868.0, the peer dependency's
+ * minimum), or a local DynamoDB, names none, and reads as not a key range's.
+ */
+export declare const isKeyRangeThrottle: (error: unknown) => boolean;
 /**
  * DynamoDB's own limit on a partition key, which every store's
  * `<keyPrefix>#<caller data>` key has to fit inside.
@@ -78,14 +90,14 @@ export declare const isConditionalCheckFailure: (error: unknown) => boolean;
 export declare const MAX_PARTITION_KEY_BYTES = 2048;
 /**
  * The partition key, or a refusal naming the byte count. Every store here
- * builds its key out of caller data (an idempotency key and the identity it
- * is scoped by, a rate-limit key a policy handler returned), so the length is
+ * builds its key from caller data (an idempotency key and the identity it is
+ * scoped by, a rate-limit key a policy handler returned), so the length is
  * the caller's to reach and this is the one place that measures it.
  *
- * Checked rather than left to DynamoDB, which answers an over-long key with a
- * ValidationException: that is not a ConditionalCheckFailedException, so it
- * escapes as a store error that reads as "the table is broken" and, under a
- * fail-open setting, is swallowed into no protection at all. The message
+ * Checked here because DynamoDB answers an over-long key with a
+ * ValidationException, not a ConditionalCheckFailedException: it would
+ * escape as a store error that reads as "the table is broken" and, under a
+ * fail-open setting, be swallowed into no protection at all. The message
  * carries the count and never the key, because it reaches a log.
  */
 export declare const assertPartitionKeyFits: (options: {

package/dist/stores/LambderDdbSdk.js

@@ -2,20 +2,18 @@
  * The DynamoDB SDK, loaded on first use.
  *
  * `@aws-sdk/client-dynamodb` and `@aws-sdk/lib-dynamodb` are optional peer
- * dependencies, and an app that keeps no sessions and uses none of the
- * DynamoDB stores should neither install them nor pay for loading them: a
- * module-level import costs every cold start something and, bundled, makes
- * every Lambder app reference both packages. So the session manager and the
- * three stores import their types only and take the classes from here the
- * first time they touch the table, the way LambderS3FileSource and
- * LambderInvokeCaller load theirs. One loader per package, memoized for the
- * container's life; a missing package fails that first call with the
- * install hint rather than failing the import of lambder itself.
+ * dependencies: an app that uses no DynamoDB store should neither install
+ * them nor pay for loading them, and a module-level import would cost every
+ * cold start and make every bundled Lambder app reference both packages. So
+ * the session manager and the stores import their types only and take the
+ * classes from here the first time they touch the table, as
+ * LambderS3FileSource and LambderInvokeCaller do. One loader per package,
+ * memoized for the container's life; a missing package fails that first call
+ * with the install hint rather than failing the import of lambder itself.
  *
- * The two facts about DynamoDB itself that every one of those stores has to
- * agree on live here as well, for the same reason: a conditional write's
- * refusal is an answer rather than a failure, and a partition key has a
- * limit that the caller data these stores build keys from can pass.
+ * The facts about DynamoDB itself that every store must agree on live here
+ * too: a conditional write's refusal is an answer rather than a failure, and
+ * a partition key has a limit that keys built from caller data can pass.
  */
 let clientSdk;
 let documentSdk;
@@ -34,27 +32,42 @@ const loadDynamoDocumentSdk = (user) => {
     documentSdk ??= withInstallHint(import("@aws-sdk/lib-dynamodb"), "@aws-sdk/lib-dynamodb", user, () => { documentSdk = undefined; });
     return documentSdk;
 };
+/**
+ * The default clients, one per region ("" for the SDK's default chain),
+ * shared by every store not given a client of its own. A client is a
+ * connection pool and a credential chain: sessions, rate limits,
+ * idempotency and the cache building one each would mean four pools and, on
+ * a cold container, four TLS handshakes and credential lookups inside the
+ * first request.
+ */
+const defaultClients = new Map();
+const defaultDocumentClients = new Map();
+const defaultClientFor = (sdk, region) => {
+    let client = defaultClients.get(region ?? "");
+    if (!client) {
+        client = new sdk.DynamoDBClient(region ? { region } : {});
+        defaultClients.set(region ?? "", client);
+    }
+    return client;
+};
 /**
  * The "ready" step each DynamoDB-backed store runs before its first table
- * call: load the SDK, then take the client the app supplied or build one.
- * Memoized for the store's life, and a FAILED load is deliberately not, so a
- * store that ran before the package was installed asks again rather than
- * caching the install hint for ever.
- *
- * Written once because four stores had written it for themselves and had
- * already drifted apart on the region: three passed the SDK's default chain
- * through and the cache pinned `us-east-1`, so one store out of four ignored
- * the deployment's own region.
+ * call: load the SDK, then take the client the app supplied or the shared
+ * default one for the store's region. Memoized for the store's life, except
+ * that a FAILED load is not, so a store that ran before the package was
+ * installed asks again rather than caching the install hint forever.
  *
- * `region` absent means the SDK's default chain (`AWS_REGION`, the Lambda
- * environment, the shared config file), which is what a store should leave
- * alone unless the caller names one.
+ * One implementation for every store, so they cannot drift apart on the
+ * region. `region` absent means the SDK's default chain (`AWS_REGION`, the
+ * Lambda environment, the shared config file); a store leaves it alone
+ * unless the caller names one, since pinning one (say `us-east-1`) would
+ * ignore the deployment's own region.
  */
 export const createDynamoClientLoader = (options) => {
     let readyPromise;
     return () => {
         readyPromise ??= loadDynamoClientSdk(options.user)
-            .then((sdk) => ({ sdk, client: options.client ?? new sdk.DynamoDBClient(options.region ? { region: options.region } : {}) }))
+            .then((sdk) => ({ sdk, client: options.client ?? defaultClientFor(sdk, options.region) }))
             .catch((error) => { readyPromise = undefined; throw error; });
         return readyPromise;
     };
@@ -71,7 +84,14 @@ export const createDynamoDocumentClientLoader = (options) => {
         if (options.client)
             return { sdk: await loadDynamoDocumentSdk(options.user), client: options.client };
         const [clientSdk, sdk] = await Promise.all([loadDynamoClientSdk(options.user), loadDynamoDocumentSdk(options.user)]);
-        return { sdk, client: sdk.DynamoDBDocumentClient.from(new clientSdk.DynamoDBClient(options.region ? { region: options.region } : {})) };
+        // Over the same shared client the item-level stores use, so the
+        // session store's calls go through that one connection pool too.
+        let client = defaultDocumentClients.get(options.region ?? "");
+        if (!client) {
+            client = sdk.DynamoDBDocumentClient.from(defaultClientFor(clientSdk, options.region));
+            defaultDocumentClients.set(options.region ?? "", client);
+        }
+        return { sdk, client };
     };
     return () => {
         readyPromise ??= build().catch((error) => { readyPromise = undefined; throw error; });
@@ -86,6 +106,32 @@ export const createDynamoDocumentClientLoader = (options) => {
  * and the reason they must not catch any other.
  */
 export const isConditionalCheckFailure = (error) => !!error && typeof error === "object" && "name" in error && error.name === "ConditionalCheckFailedException";
+/** DynamoDB's names for "too many requests": a hot partition, the table's or account's throughput, the request rate. */
+const THROTTLE_ERROR_NAMES = ["ProvisionedThroughputExceededException", "ThrottlingException", "RequestLimitExceeded"];
+/**
+ * Whether DynamoDB refused a request, after the SDK's own retries, because
+ * of the rate at one key range, rather than the table's or the account's.
+ * A key range is a partition, which holds many keys, so the throttle falls
+ * on the key asked about and on its neighbours alike: whether this key is
+ * the one flooding it is the caller's to find out.
+ *
+ * Every throttle names why in its ThrottlingReasons (throttlingReasons on a
+ * ThrottlingException), as `<Table|Index><Read|Write><LimitType>`; only
+ * KeyRangeThroughputExceeded is about one partition. The other limit types
+ * (ProvisionedThroughputExceeded, AccountLimitExceeded,
+ * MaxOnDemandThroughputExceeded) are the table or the account running out,
+ * which says nothing about any one partition. An SDK older than the reasons
+ * (`@aws-sdk/client-dynamodb` before 3.868.0, the peer dependency's
+ * minimum), or a local DynamoDB, names none, and reads as not a key range's.
+ */
+export const isKeyRangeThrottle = (error) => {
+    if (!error || typeof error !== "object" || !("name" in error) || !THROTTLE_ERROR_NAMES.includes(String(error.name)))
+        return false;
+    const { ThrottlingReasons, throttlingReasons } = error;
+    const reasons = ThrottlingReasons ?? throttlingReasons;
+    return Array.isArray(reasons)
+        && reasons.some((reason) => typeof reason?.reason === "string" && reason.reason.endsWith("KeyRangeThroughputExceeded"));
+};
 /**
  * DynamoDB's own limit on a partition key, which every store's
  * `<keyPrefix>#<caller data>` key has to fit inside.
@@ -93,14 +139,14 @@ export const isConditionalCheckFailure = (error) => !!error && typeof error ===
 export const MAX_PARTITION_KEY_BYTES = 2048;
 /**
  * The partition key, or a refusal naming the byte count. Every store here
- * builds its key out of caller data (an idempotency key and the identity it
- * is scoped by, a rate-limit key a policy handler returned), so the length is
+ * builds its key from caller data (an idempotency key and the identity it is
+ * scoped by, a rate-limit key a policy handler returned), so the length is
  * the caller's to reach and this is the one place that measures it.
  *
- * Checked rather than left to DynamoDB, which answers an over-long key with a
- * ValidationException: that is not a ConditionalCheckFailedException, so it
- * escapes as a store error that reads as "the table is broken" and, under a
- * fail-open setting, is swallowed into no protection at all. The message
+ * Checked here because DynamoDB answers an over-long key with a
+ * ValidationException, not a ConditionalCheckFailedException: it would
+ * escape as a store error that reads as "the table is broken" and, under a
+ * fail-open setting, be swallowed into no protection at all. The message
  * carries the count and never the key, because it reaches a log.
  */
 export const assertPartitionKeyFits = (options) => {

package/dist/stores/LambderDdbSessionStore.d.ts

@@ -1,6 +1,6 @@
 import type { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
 import { type LambderCompressionOption } from "../shared/wire/LambderCompressionOption.js";
-import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+import type { LambderSessionChanges, LambderSessionRecord, LambderSessionStore, LambderSessionUpdateResult } from "../shared/contracts/LambderSessionStore.js";
 export type LambderDdbSessionStoreOptions = {
     tableName: string;
     /** Region the client is created for on first use; the SDK's default chain otherwise. */
@@ -28,6 +28,10 @@ export type LambderDdbSessionStoreOptions = {
  * Table shape: a string hash key (the salted sessionKey hash, every session
  * of one subject shares it) and a string range key (the bearer secret's
  * hash), plus a TTL on `expiresAt` to let DynamoDB sweep expired sessions.
+ *
+ * Every write is conditional: a create on the item not existing, an update
+ * on it existing, so no write already in flight can bring back a session a
+ * logout deleted.
  */
 export declare class LambderDdbSessionStore<SessionData = unknown> implements LambderSessionStore<SessionData> {
     /** DynamoDB keeps records after this process is gone. */
@@ -40,26 +44,35 @@ export declare class LambderDdbSessionStore<SessionData = unknown> implements La
     private readonly ready;
     constructor(options: LambderDdbSessionStoreOptions);
     private keyOf;
+    /**
+     * session.data as the attributes that hold it: `dataBr` and `dataBytes`
+     * when compressed, a plain `data` otherwise. Either way it goes through
+     * its JSON first, so a plain record holds exactly what a compressed one
+     * restores to: an `undefined` inside the data is dropped rather than
+     * handed to the document client, which refuses one and would fail the
+     * write (a login answering 500) only when compression is off.
+     */
+    private dataAttributes;
     /** The item for a record: the two hashes under the table's key names, the data plain or compressed. */
     private toItem;
     /**
      * The record for an item. A compressed record decodes back into `data`;
-     * one whose data cannot be decoded is a malformed record and reads as no
-     * session, the same as a record missing its csrfTokenHash.
+     * one whose data cannot be decoded is malformed and reads as no session,
+     * like a record missing its csrfTokenHash.
      *
-     * Read failures and malformed records have to stay apart, and this is the
-     * seam where they separate. A read failure is infrastructure and must
-     * surface as a 500, because signing somebody out over a transient
-     * DynamoDB error is a worse answer than an error page. A record that will
-     * not decode is not transient: it will not decode on the next request
-     * either, so a 500 there is a session the visitor can neither use nor
-     * clear, on every request, until the TTL retires it. Ending it lets them
-     * log in again.
+     * This is where read failures and malformed records separate. A read
+     * failure is infrastructure and must surface as a 500: signing somebody
+     * out over a transient DynamoDB error is worse than an error page. A
+     * record that will not decode will not decode on the next request either,
+     * so a 500 there would be a session the visitor can neither use nor clear
+     * until the TTL retires it. Ending it lets them log in again.
      */
     private fromItem;
     get(sessionKeyHash: string, secretHash: string): Promise<LambderSessionRecord<SessionData> | null>;
-    put(record: LambderSessionRecord<SessionData>): Promise<void>;
-    delete(sessionKeyHash: string, secretHash: string): Promise<void>;
+    create(record: LambderSessionRecord<SessionData>): Promise<void>;
+    update(sessionKeyHash: string, secretHash: string, changes: LambderSessionChanges<SessionData>, condition?: {
+        dataVersion: number;
+    }): Promise<LambderSessionUpdateResult>;
+    delete(sessionKeyHash: string, secretHash: string): Promise<LambderSessionRecord<SessionData> | null>;
     listSecretHashes(sessionKeyHash: string): Promise<string[]>;
-    markDataExpired(sessionKeyHash: string, secretHash: string, at: number): Promise<void>;
 }