kitcn 0.16.0 → 0.17.0

package/dist/ratelimit/index.js

@@ -1,6 +1,6 @@
 import { u as requireMutationCtx } from "../api-entry-N3nBOlI2.js";
-import { _ as CRPCError } from "../builder-DBgto1yn.js";
-import { t as definePlugin } from "../middleware-Bg-PdtrI.js";
+import { _ as CRPCError } from "../builder-f4F_NRvK.js";
+import { t as definePlugin } from "../middleware-Cgrv2jIu.js";
 import { v } from "convex/values";
 import { mutationGeneric, queryGeneric } from "convex/server";
 
@@ -30,58 +30,121 @@ function toMs(duration) {
 const DEFAULT_SHARDS = 1;
 function fixedWindow(limit, window, options) {
 	validatePositive(limit, "limit");
-	const shards = normalizeShards(options?.shards);
 	const capacity = options?.capacity ?? limit;
 	validatePositive(capacity, "capacity");
-	return {
+	validateMaxReserved(options?.maxReserved);
+	return assertShardBudget({
 		kind: "fixedWindow",
 		limit,
 		window: toMs(window),
 		capacity,
 		maxReserved: options?.maxReserved,
 		start: options?.start,
-		shards
-	};
+		shards: normalizeShards(options?.shards)
+	});
 }
 function slidingWindow(limit, window, options) {
 	validatePositive(limit, "limit");
-	return {
+	validateMaxReserved(options?.maxReserved);
+	return assertShardBudget({
 		kind: "slidingWindow",
 		limit,
 		window: toMs(window),
 		maxReserved: options?.maxReserved,
 		shards: normalizeShards(options?.shards)
-	};
+	});
 }
 function tokenBucket(refillRate, interval, maxTokens, options) {
 	validatePositive(refillRate, "refillRate");
 	validatePositive(maxTokens, "maxTokens");
-	return {
+	validateMaxReserved(options?.maxReserved);
+	return assertShardBudget({
 		kind: "tokenBucket",
 		refillRate,
 		interval: toMs(interval),
 		maxTokens,
 		maxReserved: options?.maxReserved,
 		shards: normalizeShards(options?.shards)
-	};
+	});
 }
 function applyDynamicLimit(algorithm, dynamicLimit) {
-	if (!dynamicLimit || dynamicLimit <= 0) return algorithm;
-	if (algorithm.kind === "tokenBucket") return {
+	if (dynamicLimit === null) return algorithm;
+	validatePositive(dynamicLimit, "dynamicLimit");
+	if (algorithm.kind === "tokenBucket") return assertShardBudget({
 		...algorithm,
 		refillRate: dynamicLimit,
 		maxTokens: algorithm.maxTokens === algorithm.refillRate ? dynamicLimit : algorithm.maxTokens
-	};
-	if (algorithm.kind === "fixedWindow") return {
+	});
+	if (algorithm.kind === "fixedWindow") return assertShardBudget({
 		...algorithm,
 		limit: dynamicLimit,
 		capacity: algorithm.capacity === algorithm.limit ? dynamicLimit : algorithm.capacity
+	});
+	return assertShardBudget({
+		...algorithm,
+		limit: dynamicLimit
+	});
+}
+/**
+* Narrow the configured budget down to the slice one shard owns.
+*
+* Every shard stores its own row and spends only what it owns, so without this
+* the effective limit would be multiplied by the shard count. Shares are dealt
+* so they add back up to the configured budget exactly — see {@link shardShare}.
+*/
+function shardAlgorithm(algorithm, shard) {
+	const { shards } = algorithm;
+	if (shards <= 1) return algorithm;
+	const share = (value) => shardShare(value, shards, shard);
+	const maxReserved = algorithm.maxReserved === void 0 ? void 0 : share(algorithm.maxReserved);
+	if (algorithm.kind === "tokenBucket") {
+		const maxTokens = share(algorithm.maxTokens);
+		return {
+			...algorithm,
+			refillRate: algorithm.refillRate * (maxTokens / algorithm.maxTokens),
+			maxTokens,
+			maxReserved,
+			shards: 1
+		};
+	}
+	if (algorithm.kind === "fixedWindow") return {
+		...algorithm,
+		limit: share(algorithm.limit),
+		capacity: share(algorithm.capacity),
+		maxReserved,
+		shards: 1
 	};
 	return {
 		...algorithm,
-		limit: dynamicLimit
+		limit: share(algorithm.limit),
+		maxReserved,
+		shards: 1
 	};
 }
+/** Tokens a shard-level config may spend, ignoring the per-window refill. */
+function algorithmBudget(algorithm) {
+	return algorithm.kind === "tokenBucket" ? algorithm.maxTokens : algorithm.limit;
+}
+/** Tokens the algorithm can hold, including fixed-window burst capacity. */
+function algorithmCapacity(algorithm) {
+	if (algorithm.kind === "fixedWindow") return algorithm.capacity;
+	return algorithmBudget(algorithm);
+}
+/**
+* Deal a whole-token budget across `shards` so the shares sum back to `total`.
+*
+* A plain `total / shards` strands the fractional part of every shard: a shard
+* holding `2.5` tokens only ever grants two whole requests and refills to `2.5`
+* again, so `limit: 5` over two shards would enforce `4` forever. Whole budgets
+* are dealt as `floor` plus one extra token to the first `total % shards` shards
+* instead. Fractional budgets have no whole-token floor to hit, so they keep the
+* even split.
+*/
+function shardShare(total, shards, shard) {
+	const whole = Math.floor(total);
+	const fractional = total - whole;
+	return Math.floor(whole / shards) + (shard < whole % shards ? 1 : 0) + (shard === 0 ? fractional : 0);
+}
 function normalizeShards(shards) {
 	if (shards === void 0) return DEFAULT_SHARDS;
 	const rounded = Math.round(shards);
@@ -91,14 +154,98 @@ function normalizeShards(shards) {
 function validatePositive(value, field) {
 	if (!Number.isFinite(value) || value <= 0) throw new Error(`${field} must be a positive number`);
 }
+function validateMaxReserved(value) {
+	if (value !== void 0 && (!Number.isFinite(value) || value < 0)) throw new Error("maxReserved must be a non-negative finite number");
+}
+/**
+* Reject budgets that leave a shard with nothing to spend.
+*
+* Shares are dealt, so the smallest shard holds `floor(budget / shards)`. Once
+* that reaches zero the shard is dead weight: it absorbs writes it can never
+* grant, and the caller sees unexplained denials. Fail where the budget is
+* configured instead — including the runtime override, which rewrites the
+* budget after the builders ran.
+*/
+function assertShardBudget(algorithm) {
+	const { shards } = algorithm;
+	if (algorithm.kind === "tokenBucket") {
+		validateShardBudget(algorithm.maxTokens, "maxTokens", shards);
+		return algorithm;
+	}
+	validateShardBudget(algorithm.limit, "limit", shards);
+	if (algorithm.kind === "fixedWindow") validateShardBudget(algorithm.capacity, "capacity", shards);
+	return algorithm;
+}
+function validateShardBudget(value, field, shards) {
+	if (value / shards < 1) throw new Error(`${field} (${value}) must be at least shards (${shards}). Sharding deals ${field} across the shards, and a share below one token cannot serve a request. Lower shards or raise ${field}.`);
+}
 
 //#endregion
 //#region src/ratelimit/core/calculate-rate-limit.ts
 function calculateRatelimit(state, algorithm, now, count) {
+	const shardStates = state?.shards;
+	if (algorithm.shards > 1 && count > maximumShardCapacity(algorithm)) return {
+		...calculateSingleRatelimit(state, algorithm, now, count),
+		retryAfter: Number.POSITIVE_INFINITY,
+		reset: Number.POSITIVE_INFINITY
+	};
+	if (algorithm.shards > 1 && shardStates?.length === algorithm.shards) return calculateShardedRatelimit(shardStates, algorithm, now, count);
+	return calculateSingleRatelimit(state, algorithm, now, count);
+}
+function calculateSingleRatelimit(state, algorithm, now, count) {
 	if (algorithm.kind === "fixedWindow") return calculateFixedWindow(state, algorithm, now, count);
 	if (algorithm.kind === "tokenBucket") return calculateTokenBucket(state, algorithm, now, count);
 	return calculateSlidingWindow(state, algorithm, now, count);
 }
+function maximumShardCapacity(algorithm) {
+	let maximum = 0;
+	for (let shard = 0; shard < algorithm.shards; shard += 1) maximum = Math.max(maximum, algorithmCapacity(shardAlgorithm(algorithm, shard)));
+	return maximum;
+}
+function calculateShardedRatelimit(shardStates, algorithm, now, count) {
+	const candidates = shardStates.map(({ shard, state: shardState }) => {
+		const perShard = shardAlgorithm(algorithm, shard);
+		return {
+			baseline: calculateRatelimit(shardState, perShard, now, 0),
+			requested: calculateRatelimit(shardState, perShard, now, count),
+			shard
+		};
+	});
+	const selected = [...count === 0 ? candidates : candidates.filter((candidate) => candidate.requested.retryAfter === void 0)].sort((a, b) => b.requested.remainingRaw - a.requested.remainingRaw)[0];
+	const projected = candidates.map((candidate) => ({
+		evaluated: count !== 0 && candidate.shard === selected?.shard ? candidate.requested : candidate.baseline,
+		shard: candidate.shard
+	}));
+	const retryValues = candidates.flatMap((candidate) => candidate.requested.retryAfter === void 0 ? [] : [candidate.requested.retryAfter]);
+	const retryAfter = selected ? void 0 : Math.min(...retryValues);
+	const remaining = selected ? projected.reduce((total, candidate) => total + candidate.evaluated.remaining, 0) : 0;
+	const remainingRaw = selected ? projected.reduce((total, candidate) => total + Math.max(0, candidate.evaluated.remainingRaw), 0) : Math.max(...candidates.map((candidate) => candidate.requested.remainingRaw));
+	const auxTimestamps = projected.flatMap((candidate) => candidate.evaluated.state.auxTs === void 0 ? [] : [candidate.evaluated.state.auxTs]);
+	return {
+		state: {
+			value: selected || count === 0 ? projected.reduce((total, candidate) => total + candidate.evaluated.state.value, 0) : remainingRaw,
+			ts: Math.max(...projected.map((candidate) => candidate.evaluated.state.ts)),
+			...auxTimestamps.length > 0 ? {
+				auxValue: projected.reduce((total, candidate) => total + (candidate.evaluated.state.auxValue ?? 0), 0),
+				auxTs: Math.max(...auxTimestamps)
+			} : {},
+			shards: projected.map(({ evaluated, shard }) => ({
+				shard,
+				state: {
+					value: evaluated.state.value,
+					ts: evaluated.state.ts,
+					auxValue: evaluated.state.auxValue,
+					auxTs: evaluated.state.auxTs
+				}
+			}))
+		},
+		retryAfter,
+		remaining,
+		remainingRaw,
+		reset: Math.min(...candidates.map((candidate) => candidate.requested.reset)),
+		limit: algorithmBudget(algorithm)
+	};
+}
 function calculateTokenBucket(state, config, now, count) {
 	const ratePerMs = config.refillRate / config.interval;
 	const initial = state ?? {
@@ -107,7 +254,8 @@ function calculateTokenBucket(state, config, now, count) {
 	};
 	const elapsed = Math.max(0, now - initial.ts);
 	const nextValue = Math.min(initial.value + elapsed * ratePerMs, config.maxTokens) - count;
-	const retryAfter = nextValue < 0 ? Math.ceil(-nextValue / ratePerMs) : void 0;
+	let retryAfter;
+	if (nextValue < 0) retryAfter = count > config.maxTokens ? Number.POSITIVE_INFINITY : Math.ceil(-nextValue / ratePerMs);
 	return {
 		state: {
 			value: nextValue,
@@ -115,6 +263,7 @@ function calculateTokenBucket(state, config, now, count) {
 		},
 		retryAfter,
 		remaining: Math.max(0, Math.floor(nextValue)),
+		remainingRaw: nextValue,
 		reset: retryAfter ? now + retryAfter : now,
 		limit: config.maxTokens
 	};
@@ -129,7 +278,8 @@ function calculateFixedWindow(state, config, now, count) {
 	const replenished = Math.min(initial.value + config.limit * elapsedWindows, config.capacity);
 	const ts = initial.ts + elapsedWindows * config.window;
 	const nextValue = replenished - count;
-	const retryAfter = nextValue < 0 ? ts + config.window * Math.ceil(-nextValue / config.limit) - now : void 0;
+	let retryAfter;
+	if (nextValue < 0) retryAfter = count > config.capacity ? Number.POSITIVE_INFINITY : ts + config.window * Math.ceil(-nextValue / config.limit) - now;
 	return {
 		state: {
 			value: nextValue,
@@ -137,7 +287,8 @@ function calculateFixedWindow(state, config, now, count) {
 		},
 		retryAfter,
 		remaining: Math.max(0, Math.floor(nextValue)),
-		reset: ts + config.window,
+		remainingRaw: nextValue,
+		reset: retryAfter === Number.POSITIVE_INFINITY ? Number.POSITIVE_INFINITY : ts + config.window,
 		limit: config.limit
 	};
 }
@@ -157,7 +308,8 @@ function calculateSlidingWindow(state, config, now, count) {
 	const projectedCurrent = currentCount + count;
 	const projectedUsed = projectedCurrent + previousCount * previousWeight;
 	const remaining = config.limit - projectedUsed;
-	const retryAfter = remaining < 0 ? Math.max(1, config.window - elapsedInWindow) : void 0;
+	let retryAfter;
+	if (remaining < 0) retryAfter = count > config.limit ? Number.POSITIVE_INFINITY : Math.max(1, config.window - elapsedInWindow);
 	return {
 		state: {
 			value: projectedCurrent,
@@ -167,10 +319,22 @@ function calculateSlidingWindow(state, config, now, count) {
 		},
 		retryAfter,
 		remaining: Math.max(0, Math.floor(remaining)),
-		reset: windowStart + config.window,
+		remainingRaw: remaining,
+		reset: retryAfter === Number.POSITIVE_INFINITY ? Number.POSITIVE_INFINITY : windowStart + config.window,
 		limit: config.limit
 	};
 }
+/**
+* Convert a {@link RatelimitSnapshot} back into the `RatelimitState` shape that
+* {@link calculateRatelimit} consumes.
+*
+* Snapshot `value` is always "tokens left". Fixed window and token bucket store
+* that directly, but sliding window state stores the used count, so it has to be
+* inverted before it can be replayed.
+*/
+function snapshotToState(snapshot) {
+	return { ...snapshot.state };
+}
 function alignWindowStart(now, window, start = 0) {
 	const offsetNow = now - start;
 	return start + Math.floor(offsetNow / window) * window;
@@ -178,18 +342,27 @@ function alignWindowStart(now, window, start = 0) {
 
 //#endregion
 //#region src/ratelimit/core/cache.ts
+/**
+* Remembers exhausted shards so a request routed to one skips its read.
+*
+* Entries are per shard, requested count, and reservation mode, never per
+* identifier: a shard can reject a large or ordinary request while still
+* serving a smaller or reserved one, and its peers may still hold tokens.
+*/
+const MAX_BLOCK_VARIANTS_PER_IDENTIFIER = 32;
 var EphemeralBlockCache = class {
 	constructor(cache) {
 		this.cache = cache;
 	}
-	isBlocked(identifier) {
-		const reset = this.cache.get(identifier);
+	isBlocked(identifier, shard, count, reserve) {
+		const key = shardKey(identifier, shard, count, reserve);
+		const reset = this.cache.get(key);
 		if (!reset) return {
 			blocked: false,
 			reset: 0
 		};
 		if (reset <= Date.now()) {
-			this.cache.delete(identifier);
+			this.cache.delete(key);
 			return {
 				blocked: false,
 				reset: 0
@@ -200,16 +373,45 @@ var EphemeralBlockCache = class {
 			reset
 		};
 	}
-	blockUntil(identifier, reset) {
-		this.cache.set(identifier, reset);
+	blockUntil(identifier, shard, count, reserve, reset) {
+		if (!Number.isFinite(reset)) return;
+		this.pruneExpired();
+		const key = shardKey(identifier, shard, count, reserve);
+		if (!this.cache.has(key)) this.evictOldestVariant(identifier);
+		this.cache.set(key, reset);
 	}
 	clear(identifier) {
-		this.cache.delete(identifier);
+		const prefix = identifierPrefix(identifier);
+		for (const key of this.cache.keys()) if (key.startsWith(prefix)) this.cache.delete(key);
+	}
+	clearAll() {
+		this.cache.clear();
 	}
 	size() {
 		return this.cache.size;
 	}
+	pruneExpired() {
+		const now = Date.now();
+		for (const [key, reset] of this.cache) if (reset <= now) this.cache.delete(key);
+	}
+	evictOldestVariant(identifier) {
+		const prefix = identifierPrefix(identifier);
+		let variants = 0;
+		let oldest;
+		for (const key of this.cache.keys()) {
+			if (!key.startsWith(prefix)) continue;
+			oldest ??= key;
+			variants += 1;
+		}
+		if (variants >= MAX_BLOCK_VARIANTS_PER_IDENTIFIER && oldest) this.cache.delete(oldest);
+	}
 };
+function shardKey(identifier, shard, count, reserve) {
+	return `${identifierPrefix(identifier)}${shard}:${count}:${reserve ? 1 : 0}`;
+}
+function identifierPrefix(identifier) {
+	return `${identifier.length}:${identifier}:`;
+}
 function createReadDedupeCache() {
 	const cache = /* @__PURE__ */ new Map();
 	return {
@@ -483,6 +685,7 @@ var Ratelimit = class Ratelimit {
 	blockCache;
 	blockCacheSource;
 	checkCache = createReadDedupeCache();
+	cacheGeneration = 0;
 	constructor(config) {
 		this.config = config;
 		this.store = new ConvexRatelimitStore(config.db);
@@ -518,23 +721,22 @@ var Ratelimit = class Ratelimit {
 	}
 	async resetUsedTokens(identifier) {
 		await this.store.deleteStates(this.prefix, identifier);
+		this.cacheGeneration += 1;
 		this.checkCache.clear();
-		if (this.blockCache) this.blockCache.clear(identifier);
+		if (this.blockCache) this.blockCache.clear(this.blockKey(identifier));
 		clearProtection(this.prefix, identifier);
 	}
 	async getRemaining(identifier) {
-		const value = await this.getValue(identifier, { sampleShards: this.limiter.shards });
-		const evaluated = calculateRatelimit({
-			value: value.value,
-			ts: value.ts
-		}, value.config, Date.now(), 0);
+		const algorithm = await this.resolveAlgorithm();
+		const evaluated = await this.readShards(identifier, algorithm, Array.from({ length: algorithm.shards }, (_, shard) => shard));
 		return {
-			remaining: Math.max(0, evaluated.remaining),
-			reset: evaluated.reset,
-			limit: evaluated.limit
+			remaining: Math.max(0, evaluated.reduce((total, shard) => total + shard.evaluated.remaining, 0)),
+			reset: Math.min(...evaluated.map((shard) => shard.evaluated.reset)),
+			limit: algorithmBudget(algorithm)
 		};
 	}
 	async getValue(identifier, options) {
+		const cacheGeneration = this.cacheGeneration;
 		const cacheKey = `${identifier}:${options?.sampleShards ?? 0}`;
 		const cached = this.checkCache.get(cacheKey);
 		if (cached) {
@@ -544,30 +746,70 @@ var Ratelimit = class Ratelimit {
 		const algorithm = await this.resolveAlgorithm();
 		const sampleShards = Math.max(1, Math.min(options?.sampleShards ?? 1, algorithm.shards));
 		const shards = pickSampleShards(algorithm.shards, sampleShards);
-		const now = Date.now();
-		let best = null;
-		for (const shard of shards) {
-			const evaluated = calculateRatelimit(normalizeState(await this.store.getState(this.prefix, identifier, shard)), algorithm, now, 0);
-			const current = {
-				value: algorithm.kind === "slidingWindow" ? evaluated.remaining : evaluated.state.value,
-				ts: evaluated.state.ts,
-				shard,
-				config: algorithm
-			};
-			if (!best || current.value > best.value) best = current;
+		const samples = await this.readShards(identifier, algorithm, shards);
+		let sampledRemaining = 0;
+		let sampledCapacity = 0;
+		let sampledStateValue = 0;
+		let sampledAuxValue = 0;
+		let latestTs = null;
+		let latestAuxTs = null;
+		let fullestShard = null;
+		let fullestRemaining = Number.NEGATIVE_INFINITY;
+		for (const { evaluated, perShard, shard } of samples) {
+			sampledRemaining += evaluated.remainingRaw;
+			sampledCapacity += algorithmCapacity(perShard);
+			sampledStateValue += evaluated.state.value;
+			sampledAuxValue += evaluated.state.auxValue ?? 0;
+			latestTs = latestTs === null ? evaluated.state.ts : Math.max(latestTs, evaluated.state.ts);
+			if (evaluated.state.auxTs !== void 0) latestAuxTs = latestAuxTs === null ? evaluated.state.auxTs : Math.max(latestAuxTs, evaluated.state.auxTs);
+			if (evaluated.remainingRaw > fullestRemaining) {
+				fullestRemaining = evaluated.remainingRaw;
+				fullestShard = shard;
+			}
 		}
-		const result = best ?? {
-			value: algorithm.kind === "tokenBucket" ? algorithm.maxTokens : algorithm.limit,
-			ts: now,
+		const result = fullestShard === null ? {
+			value: algorithmCapacity(algorithm),
+			ts: Date.now(),
 			shard: 0,
-			config: algorithm
+			config: algorithm,
+			state: {
+				value: algorithm.kind === "slidingWindow" ? 0 : algorithmCapacity(algorithm),
+				ts: Date.now(),
+				shards: []
+			}
+		} : {
+			value: scaleToGlobal(sampledRemaining, sampledCapacity, algorithmCapacity(algorithm)),
+			ts: latestTs ?? Date.now(),
+			shard: fullestShard,
+			config: algorithm,
+			state: {
+				value: scaleToGlobal(sampledStateValue, sampledCapacity, algorithmCapacity(algorithm)),
+				ts: latestTs ?? Date.now(),
+				...algorithm.kind === "slidingWindow" ? {
+					auxValue: scaleToGlobal(sampledAuxValue, sampledCapacity, algorithmCapacity(algorithm)),
+					auxTs: latestAuxTs ?? (latestTs ?? Date.now()) - algorithm.window
+				} : {},
+				shards: samples.map(({ evaluated, shard }) => ({
+					shard,
+					state: {
+						value: evaluated.state.value,
+						ts: evaluated.state.ts,
+						auxValue: evaluated.state.auxValue,
+						auxTs: evaluated.state.auxTs
+					}
+				}))
+			}
 		};
-		this.checkCache.set(cacheKey, Promise.resolve(result));
+		if (cacheGeneration === this.cacheGeneration) this.checkCache.set(cacheKey, Promise.resolve(result));
 		return result;
 	}
 	async setDynamicLimit(options) {
 		if (!this.dynamicLimits) throw new Error("dynamicLimits must be enabled in the Ratelimit constructor to use setDynamicLimit()");
+		applyDynamicLimit(this.limiter, options.limit === false ? null : options.limit);
 		await this.store.setDynamicLimit(this.prefix, options.limit);
+		this.cacheGeneration += 1;
+		this.checkCache.clear();
+		this.blockCache?.clearAll();
 	}
 	async getDynamicLimit() {
 		if (!this.dynamicLimits) throw new Error("dynamicLimits must be enabled in the Ratelimit constructor to use getDynamicLimit()");
@@ -584,7 +826,22 @@ var Ratelimit = class Ratelimit {
 					value: v.number(),
 					ts: v.number(),
 					shard: v.number(),
-					config: v.any()
+					config: v.any(),
+					state: v.object({
+						value: v.number(),
+						ts: v.number(),
+						auxValue: v.optional(v.number()),
+						auxTs: v.optional(v.number()),
+						shards: v.optional(v.array(v.object({
+							shard: v.number(),
+							state: v.object({
+								value: v.number(),
+								ts: v.number(),
+								auxValue: v.optional(v.number()),
+								auxTs: v.optional(v.number())
+							})
+						})))
+					})
 				}),
 				handler: async (ctx, args) => {
 					const identifier = await resolveIdentifier(options?.identifier, ctx, args.identifier);
@@ -606,6 +863,7 @@ var Ratelimit = class Ratelimit {
 		});
 	}
 	async evaluate(identifier, request, consume) {
+		const cacheGeneration = this.cacheGeneration;
 		const deniedValue = this.enableProtection ? pickDeniedValue({
 			prefix: this.prefix,
 			identifier,
@@ -615,7 +873,7 @@ var Ratelimit = class Ratelimit {
 		if (deniedValue) return {
 			success: false,
 			ok: false,
-			limit: this.rawLimit(this.limiter),
+			limit: algorithmBudget(this.limiter),
 			remaining: 0,
 			reset: Date.now() + 6e4,
 			pending: Promise.resolve(),
@@ -623,47 +881,73 @@ var Ratelimit = class Ratelimit {
 			deniedValue
 		};
 		const algorithm = await this.resolveAlgorithm();
-		const count = consume ? normalizeCount(request) : 0;
-		const reserveRequested = consume && Boolean(request?.reserve);
-		if (this.blockCache && count > 0) {
-			const cacheKey = `${this.prefix}:${identifier}`;
-			const blocked = this.blockCache.isBlocked(cacheKey);
-			if (blocked.blocked) return {
-				success: false,
-				ok: false,
-				limit: this.rawLimit(algorithm),
-				remaining: 0,
-				reset: blocked.reset,
-				pending: Promise.resolve(),
-				reason: "cacheBlock"
-			};
-		}
+		const count = normalizeCount(request);
+		const reserveRequested = Boolean(request?.reserve);
+		if (count > maximumRequestSize(algorithm, reserveRequested)) return {
+			success: false,
+			ok: false,
+			limit: algorithmBudget(algorithm),
+			remaining: 0,
+			reset: 0,
+			pending: Promise.resolve(),
+			reason: "requestTooLarge"
+		};
+		const picked = pickCandidateShards(algorithm.shards);
+		const attempted = /* @__PURE__ */ new Set();
+		let blockedUntil = Number.POSITIVE_INFINITY;
+		const findOpen = (shards) => {
+			const open = [];
+			for (const shard of shards) {
+				attempted.add(shard);
+				const blocked = this.blockCache && count > 0 ? this.blockCache.isBlocked(this.blockKey(identifier), shard, count, reserveRequested) : void 0;
+				if (blocked?.blocked) blockedUntil = Math.min(blockedUntil, blocked.reset);
+				else open.push(shard);
+			}
+			return open;
+		};
 		const now = Date.now();
-		const candidates = await this.evaluateCandidates(identifier, algorithm, now, count, reserveRequested);
+		const candidates = await this.evaluateCandidates(identifier, algorithm, findOpen(picked), now, count, reserveRequested);
+		if (!candidates.some((candidate) => candidate.success)) {
+			const fallback = Array.from({ length: algorithm.shards }, (_, shard) => shard).filter((shard) => !attempted.has(shard));
+			candidates.push(...await this.evaluateCandidates(identifier, algorithm, findOpen(fallback), now, count, reserveRequested));
+		}
+		if (candidates.length === 0) return {
+			success: false,
+			ok: false,
+			limit: algorithmBudget(algorithm),
+			remaining: 0,
+			reset: blockedUntil,
+			pending: Promise.resolve(),
+			reason: "cacheBlock"
+		};
+		if (consume && this.blockCache && count > 0 && cacheGeneration === this.cacheGeneration) {
+			for (const candidate of candidates) if (!candidate.success) this.blockCache.blockUntil(this.blockKey(identifier), candidate.shard, count, reserveRequested, now + (candidate.retryAfter ?? 1));
+		}
 		const successful = candidates.filter((candidate) => candidate.success);
 		if (successful.length > 0) {
-			const best = successful.sort((a, b) => b.evaluated.remaining - a.evaluated.remaining)[0];
-			if (consume && count !== 0) await this.store.upsertState({
-				name: this.prefix,
-				key: identifier,
-				shard: best.shard,
-				state: best.evaluated.state
-			});
-			if (this.blockCache) this.blockCache.clear(`${this.prefix}:${identifier}`);
+			const best = successful.sort((a, b) => b.evaluated.remainingRaw - a.evaluated.remainingRaw)[0];
+			if (consume && count !== 0) {
+				await this.store.upsertState({
+					name: this.prefix,
+					key: identifier,
+					shard: best.shard,
+					state: best.evaluated.state
+				});
+				this.cacheGeneration += 1;
+			}
 			clearProtection(this.prefix, identifier);
 			this.checkCache.clear();
 			return {
 				success: true,
 				ok: true,
-				limit: best.evaluated.limit,
-				remaining: best.evaluated.remaining,
+				limit: algorithmBudget(algorithm),
+				remaining: Math.max(0, Math.floor(scaleToGlobal(best.evaluated.remainingRaw, algorithmCapacity(shardAlgorithm(algorithm, best.shard)), algorithmCapacity(algorithm)))),
 				reset: best.evaluated.reset,
 				pending: Promise.resolve()
 			};
 		}
-		const failure = candidates.filter((candidate) => candidate.evaluated.retryAfter !== void 0).sort((a, b) => (a.evaluated.retryAfter ?? Number.MAX_SAFE_INTEGER) - (b.evaluated.retryAfter ?? Number.MAX_SAFE_INTEGER))[0] ?? candidates[0];
-		const reset = now + (failure.evaluated.retryAfter ?? 1);
-		if (consume && this.blockCache && count > 0) this.blockCache.blockUntil(`${this.prefix}:${identifier}`, reset);
+		const retryAfter = (candidates.filter((candidate) => candidate.retryAfter !== void 0).sort((a, b) => (a.retryAfter ?? Number.MAX_SAFE_INTEGER) - (b.retryAfter ?? Number.MAX_SAFE_INTEGER))[0] ?? candidates[0]).retryAfter ?? 1;
+		const reset = Math.min(now + retryAfter, blockedUntil);
 		if (consume && this.enableProtection) recordRatelimitFailure({
 			prefix: this.prefix,
 			identifier,
@@ -673,38 +957,48 @@ var Ratelimit = class Ratelimit {
 		return {
 			success: false,
 			ok: false,
-			limit: failure.evaluated.limit,
+			limit: algorithmBudget(algorithm),
 			remaining: 0,
 			reset,
 			pending: Promise.resolve()
 		};
 	}
-	async evaluateCandidates(identifier, algorithm, now, count, reserveRequested) {
-		const shards = pickCandidateShards(algorithm.shards);
-		const result = [];
-		for (const shard of shards) {
+	blockKey(identifier) {
+		return `${this.prefix}:${identifier}`;
+	}
+	async readShards(identifier, algorithm, shards) {
+		const samples = await Promise.all(shards.map(async (shard) => ({
+			perShard: shardAlgorithm(algorithm, shard),
+			shard,
+			state: normalizeState(await this.store.getState(this.prefix, identifier, shard))
+		})));
+		const now = Date.now();
+		return samples.map(({ perShard, shard, state }) => ({
+			shard,
+			perShard,
+			evaluated: calculateRatelimit(state, perShard, now, 0)
+		}));
+	}
+	async evaluateCandidates(identifier, algorithm, shards, now, count, reserveRequested) {
+		return Promise.all(shards.map(async (shard) => {
+			const perShard = shardAlgorithm(algorithm, shard);
 			const state = normalizeState(await this.store.getState(this.prefix, identifier, shard));
-			const evaluated = calculateRatelimit(state, algorithm, now, count);
-			const canReserve = reserveRequested && evaluated.retryAfter !== void 0 && algorithm.kind !== "slidingWindow" && (algorithm.maxReserved === void 0 || Math.abs(evaluated.state.value) <= algorithm.maxReserved);
-			const success = evaluated.retryAfter === void 0 || canReserve;
-			result.push({
+			const evaluated = calculateRatelimit(state, perShard, now, count);
+			const retryAfter = getRequestRetryAfter(evaluated, perShard, now, count, reserveRequested);
+			return {
 				shard,
 				state,
 				evaluated,
-				success
-			});
-		}
-		return result;
+				retryAfter,
+				success: retryAfter === void 0
+			};
+		}));
 	}
 	async resolveAlgorithm() {
 		if (!this.dynamicLimits) return this.limiter;
 		const dynamicLimit = await this.store.getDynamicLimit(this.prefix);
 		return applyDynamicLimit(this.limiter, dynamicLimit);
 	}
-	rawLimit(algorithm) {
-		if (algorithm.kind === "tokenBucket") return algorithm.maxTokens;
-		return algorithm.limit;
-	}
 	async runWithTimeout(operation) {
 		if (this.timeout <= 0) return operation();
 		const startedAt = Date.now();
@@ -729,6 +1023,39 @@ var Ratelimit = class Ratelimit {
 		};
 	}
 };
+function maximumRequestSize(algorithm, reserveRequested) {
+	let maximum = 0;
+	for (let shard = 0; shard < algorithm.shards; shard += 1) {
+		const perShard = shardAlgorithm(algorithm, shard);
+		maximum = Math.max(maximum, algorithmCapacity(perShard) + reservationHeadroom(perShard, reserveRequested));
+	}
+	return maximum;
+}
+function reservationHeadroom(algorithm, reserveRequested) {
+	if (!reserveRequested || algorithm.kind === "slidingWindow") return 0;
+	return algorithm.maxReserved ?? Number.POSITIVE_INFINITY;
+}
+function getRequestRetryAfter(evaluated, algorithm, now, count, reserveRequested) {
+	const reservation = reservationHeadroom(algorithm, reserveRequested);
+	if (count > algorithmCapacity(algorithm) + reservation) return Number.POSITIVE_INFINITY;
+	if (!reserveRequested || evaluated.retryAfter === void 0 || algorithm.kind === "slidingWindow") return evaluated.retryAfter;
+	if (algorithm.maxReserved === void 0) return;
+	const excessDebt = -evaluated.remainingRaw - Math.max(0, algorithm.maxReserved);
+	if (excessDebt <= 0) return;
+	if (algorithm.kind === "tokenBucket") return Math.ceil(excessDebt / (algorithm.refillRate / algorithm.interval));
+	return Math.max(1, evaluated.state.ts + algorithm.window * Math.ceil(excessDebt / algorithm.limit) - now);
+}
+/**
+* Project the tokens left on the sampled shards onto the full budget.
+*
+* Sampling every shard adds up to the real global balance, so it is returned
+* untouched. A partial sample is scaled by the share of the budget it covers,
+* which assumes the unread shards are drained like the ones that were read.
+*/
+function scaleToGlobal(remaining, sampledBudget, totalBudget) {
+	if (sampledBudget <= 0 || sampledBudget >= totalBudget) return remaining;
+	return remaining * (totalBudget / sampledBudget);
+}
 function normalizeCount(request) {
 	if (!request) return 1;
 	const value = request.rate ?? request.count ?? 1;
@@ -853,4 +1180,4 @@ const DAY = 24 * HOUR;
 const WEEK = 7 * DAY;
 
 //#endregion
-export { DAY, HOUR, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, RatelimitPlugin, SECOND, WEEK, applyDynamicLimit, calculateRatelimit, fixedWindow, slidingWindow, toMs, tokenBucket };
+export { DAY, HOUR, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, RatelimitPlugin, SECOND, WEEK, applyDynamicLimit, calculateRatelimit, fixedWindow, slidingWindow, snapshotToState, toMs, tokenBucket };