kitcn 0.23.0 → 0.24.0

package/dist/ratelimit/index.js

@@ -422,94 +422,6 @@ function createReadDedupeCache() {
 	};
 }
 
-//#endregion
-//#region src/ratelimit/core/deny-list.ts
-const DEFAULT_BLOCK_MS = 6e4;
-const THRESHOLD_BLOCK_MS = 1440 * 60 * 1e3;
-const protectionState = /* @__PURE__ */ new Map();
-function getState(prefix) {
-	let state = protectionState.get(prefix);
-	if (!state) {
-		state = {
-			hits: /* @__PURE__ */ new Map(),
-			blockedUntil: /* @__PURE__ */ new Map()
-		};
-		protectionState.set(prefix, state);
-	}
-	return state;
-}
-function pickDeniedValue(options) {
-	const members = getMembers(options.identifier, options.request);
-	const state = getState(options.prefix);
-	for (const member of members) {
-		const until = state.blockedUntil.get(member.value);
-		if (until && until > Date.now()) return member.value;
-		if (until && until <= Date.now()) state.blockedUntil.delete(member.value);
-	}
-	if (!options.lists) return;
-	const listMatchers = [
-		{
-			values: options.lists.identifiers,
-			kind: "identifier"
-		},
-		{
-			values: options.lists.ips,
-			kind: "ip"
-		},
-		{
-			values: options.lists.userAgents,
-			kind: "userAgent"
-		},
-		{
-			values: options.lists.countries,
-			kind: "country"
-		}
-	];
-	for (const matcher of listMatchers) {
-		if (!matcher.values || matcher.values.length === 0) continue;
-		const valueSet = new Set(matcher.values);
-		const hit = members.find((member) => member.kind === matcher.kind && valueSet.has(member.value));
-		if (hit) {
-			state.blockedUntil.set(hit.value, Date.now() + DEFAULT_BLOCK_MS);
-			return hit.value;
-		}
-	}
-}
-function recordRatelimitFailure(options) {
-	const members = getMembers(options.identifier, options.request);
-	const state = getState(options.prefix);
-	for (const member of members) {
-		const next = (state.hits.get(member.value) ?? 0) + 1;
-		state.hits.set(member.value, next);
-		if (next >= options.threshold) state.blockedUntil.set(member.value, Date.now() + THRESHOLD_BLOCK_MS);
-	}
-}
-function clearProtection(prefix, identifier) {
-	const state = getState(prefix);
-	state.hits.delete(identifier);
-	state.blockedUntil.delete(identifier);
-}
-function getMembers(identifier, request) {
-	return [
-		{
-			kind: "identifier",
-			value: identifier
-		},
-		{
-			kind: "ip",
-			value: request?.ip
-		},
-		{
-			kind: "userAgent",
-			value: request?.userAgent
-		},
-		{
-			kind: "country",
-			value: request?.country
-		}
-	].filter((member) => Boolean(member.value));
-}
-
 //#endregion
 //#region src/ratelimit/store/convex-store.ts
 const RATE_LIMIT_STATE_TABLE = "ratelimitState";
@@ -584,6 +496,20 @@ var ConvexRatelimitStore = class ConvexRatelimitStore {
 			this.invalidateAll(name, key);
 		});
 	}
+	async deleteStatesBefore(before, limit) {
+		return this.withSetupGuidance(async () => {
+			const db = this.getWriter();
+			const rows = await db.query(RATE_LIMIT_STATE_TABLE).withIndex("by_ts", (q) => q.lt("ts", before)).take(limit + 1);
+			const selected = rows.slice(0, limit);
+			for (const row of selected) await db.delete(RATE_LIMIT_STATE_TABLE, row._id);
+			this.dedupe.clear();
+			this.listDedupe.clear();
+			return {
+				deleted: selected.length,
+				hasMore: rows.length > limit
+			};
+		});
+	}
 	async getDynamicLimit(prefix) {
 		return this.withSetupGuidance(async () => {
 			const db = this.getReader();
@@ -663,6 +589,227 @@ function withMissingTableGuidance(error) {
 	return new Error(`${missingTableGuidance} Original error: ${message}`, { cause: error instanceof Error ? error : void 0 });
 }
 
+//#endregion
+//#region src/ratelimit/maintenance.ts
+const DEFAULT_CLEANUP_LIMIT = 100;
+const MAX_CLEANUP_LIMIT = 1e3;
+/** Deletes one on-demand batch of state older than the caller-owned cutoff. */
+async function cleanupRatelimitState(db, options) {
+	if (!Number.isFinite(options.before)) throw new Error("before must be a finite timestamp");
+	const limit = options.limit ?? DEFAULT_CLEANUP_LIMIT;
+	if (!Number.isInteger(limit) || limit < 1 || limit > MAX_CLEANUP_LIMIT) throw new Error(`limit must be an integer from 1 to ${MAX_CLEANUP_LIMIT}`);
+	return new ConvexRatelimitStore(db).deleteStatesBefore(options.before, limit);
+}
+
+//#endregion
+//#region src/ratelimit/core/deny-list.ts
+const DEFAULT_BLOCK_MS = 6e4;
+const THRESHOLD_BLOCK_MS = 1440 * 60 * 1e3;
+/**
+* Only failures inside this rolling window count toward the threshold. Without
+* decay `hits` is an all-time counter, so any shared
+* NAT/carrier IP eventually accumulates `denyListThreshold` lifetime failures
+* and blocks every user behind it.
+*/
+const HITS_WINDOW_MS = 600 * 1e3;
+/**
+* Hard ceiling on tracked members per prefix. `userAgent` is an
+* attacker-forgeable header, so without a cap one source can plant an unbounded
+* number of permanent entries in this module-scope map.
+*/
+const MAX_TRACKED_MEMBERS = 4096;
+/** Bound timestamp storage even when applications configure a high threshold. */
+const MAX_TRACKED_HITS = 65536;
+/** Ceiling on a stored key so attacker-chosen value length cannot inflate cost. */
+const MAX_MEMBER_KEY_LENGTH = 128;
+/**
+* Sweeping expired entries is O(tracked members), so it runs on an interval
+* rather than per denial — the hot path under a flood is the denial path.
+* Correctness does not depend on it: an expired hit already reads as absent.
+*/
+const PRUNE_INTERVAL_MS = 3e4;
+const protectionState = /* @__PURE__ */ new Map();
+function getState(prefix) {
+	let state = protectionState.get(prefix);
+	if (!state) {
+		state = {
+			hitCount: 0,
+			members: /* @__PURE__ */ new Map(),
+			nextPruneAt: 0
+		};
+		protectionState.set(prefix, state);
+	}
+	return state;
+}
+/**
+* Storage key for a member value. Overlong values are truncated and tagged with
+* their length and hash, so a long forged header cannot inflate retained state
+* or share protection state with another value that has the same prefix.
+*/
+function memberKey(value) {
+	if (value.length <= MAX_MEMBER_KEY_LENGTH) return value;
+	return `${value.slice(0, MAX_MEMBER_KEY_LENGTH)}#${value.length}:${hashMember(value)}`;
+}
+function hashMember(value) {
+	let hash = 14695981039346656037n;
+	for (let index = 0; index < value.length; index++) {
+		hash ^= BigInt(value.charCodeAt(index));
+		hash = BigInt.asUintN(64, hash * 1099511628211n);
+	}
+	return hash.toString(16).padStart(16, "0");
+}
+function pruneExpired(state, now) {
+	const cutoff = now - HITS_WINDOW_MS;
+	for (const [key, member] of state.members) {
+		const retainedHits = member.hits.filter((hitAt) => hitAt > cutoff);
+		state.hitCount -= member.hits.length - retainedHits.length;
+		member.hits = retainedHits;
+		if (member.blockedUntil !== void 0 && member.blockedUntil <= now) member.blockedUntil = void 0;
+		if (member.hits.length === 0 && member.blockedUntil === void 0) state.members.delete(key);
+	}
+}
+function evictLeastRecentHitOnly(state) {
+	for (const [key, member] of state.members) {
+		if (member.blockedUntil !== void 0) continue;
+		state.hitCount -= member.hits.length;
+		member.hits = [];
+		state.members.delete(key);
+		return true;
+	}
+	return false;
+}
+function evictLeastRecentMember(state) {
+	for (const [key, member] of state.members) {
+		state.hitCount -= member.hits.length;
+		member.hits = [];
+		state.members.delete(key);
+		return;
+	}
+}
+function getMember(state, key) {
+	const existing = state.members.get(key);
+	if (existing) {
+		state.members.delete(key);
+		state.members.set(key, existing);
+		return existing;
+	}
+	if (state.members.size >= MAX_TRACKED_MEMBERS && !evictLeastRecentHitOnly(state)) evictLeastRecentMember(state);
+	const member = { hits: [] };
+	state.members.set(key, member);
+	return member;
+}
+function recordHit(state, key, threshold, now) {
+	const member = getMember(state, key);
+	const cutoff = now - HITS_WINDOW_MS;
+	const retainedHits = member.hits.filter((hitAt) => hitAt > cutoff);
+	state.hitCount -= member.hits.length - retainedHits.length;
+	member.hits = retainedHits;
+	while (state.hitCount >= MAX_TRACKED_HITS && evictLeastRecentHitOnly(state));
+	if (!state.members.has(key)) state.members.set(key, member);
+	member.hits.push(now);
+	state.hitCount += 1;
+	if (member.hits.length >= threshold) {
+		member.blockedUntil = now + THRESHOLD_BLOCK_MS;
+		state.hitCount -= member.hits.length;
+		member.hits = [];
+	}
+}
+function pickDeniedValue(options) {
+	const members = getMembers(options.identifier, options.request);
+	const state = getState(options.prefix);
+	const now = Date.now();
+	if (now >= state.nextPruneAt) {
+		pruneExpired(state, now);
+		state.nextPruneAt = now + PRUNE_INTERVAL_MS;
+	}
+	for (const member of members) {
+		const key = memberKey(member.value);
+		const tracked = state.members.get(key);
+		if (tracked?.blockedUntil && tracked.blockedUntil > now) {
+			state.members.delete(key);
+			state.members.set(key, tracked);
+			return member.value;
+		}
+		if (tracked?.blockedUntil && tracked.blockedUntil <= now) {
+			tracked.blockedUntil = void 0;
+			if (tracked.hits.length === 0) state.members.delete(key);
+		}
+	}
+	if (!options.lists) return;
+	const listMatchers = [
+		{
+			values: options.lists.identifiers,
+			kind: "identifier"
+		},
+		{
+			values: options.lists.ips,
+			kind: "ip"
+		},
+		{
+			values: options.lists.userAgents,
+			kind: "userAgent"
+		},
+		{
+			values: options.lists.countries,
+			kind: "country"
+		}
+	];
+	for (const matcher of listMatchers) {
+		if (!matcher.values || matcher.values.length === 0) continue;
+		const valueSet = new Set(matcher.values);
+		const hit = members.find((member) => member.kind === matcher.kind && valueSet.has(member.value));
+		if (hit) {
+			const tracked = getMember(state, memberKey(hit.value));
+			tracked.blockedUntil = now + DEFAULT_BLOCK_MS;
+			state.hitCount -= tracked.hits.length;
+			tracked.hits = [];
+			return hit.value;
+		}
+	}
+}
+function recordRatelimitFailure(options) {
+	const members = getMembers(options.identifier, options.request);
+	const state = getState(options.prefix);
+	const now = Date.now();
+	if (now >= state.nextPruneAt) {
+		pruneExpired(state, now);
+		state.nextPruneAt = now + PRUNE_INTERVAL_MS;
+	}
+	for (const member of members) recordHit(state, memberKey(member.value), options.threshold, now);
+}
+/**
+* Clears the identifier only. Widening this to every request member would let
+* an attacker reset their own ip/userAgent counters with a single success, or
+* clear a victim's counter by forging their user-agent.
+*/
+function clearProtection(prefix, identifier) {
+	const state = getState(prefix);
+	const key = memberKey(identifier);
+	const member = state.members.get(key);
+	state.hitCount -= member?.hits.length ?? 0;
+	state.members.delete(key);
+}
+function getMembers(identifier, request) {
+	return [
+		{
+			kind: "identifier",
+			value: identifier
+		},
+		{
+			kind: "ip",
+			value: request?.ip
+		},
+		{
+			kind: "userAgent",
+			value: request?.userAgent
+		},
+		{
+			kind: "country",
+			value: request?.country
+		}
+	].filter((member) => Boolean(member.value));
+}
+
 //#endregion
 //#region src/ratelimit/ratelimit.ts
 const DEFAULT_PREFIX = "kitcn/ratelimit";
@@ -859,7 +1006,7 @@ var Ratelimit = class Ratelimit {
 		return new Ratelimit({
 			...this.config,
 			db,
-			ephemeralCache: this.blockCacheSource
+			ephemeralCache: this.blockCacheSource ?? false
 		});
 	}
 	async evaluate(identifier, request, consume) {
@@ -1143,18 +1290,21 @@ const RatelimitPlugin = definePlugin("ratelimit", ({ options }) => {
 		meta
 	});
 	const tier = await options.getTier(user);
-	const identifier = await options.getIdentifier({
+	const requestArgs = {
 		ctx,
 		meta,
 		user,
-		bucket
+		bucket,
+		tier
+	};
+	const signals = await options.getSignals(requestArgs);
+	const identifier = await options.getIdentifier({
+		...requestArgs,
+		signals
 	});
 	const args = {
-		ctx,
-		meta,
-		user,
-		bucket,
-		tier,
+		...requestArgs,
+		signals,
 		identifier
 	};
 	if (!(await new Ratelimit({
@@ -1163,8 +1313,12 @@ const RatelimitPlugin = definePlugin("ratelimit", ({ options }) => {
 		limiter: resolveBucketLimiter(options, bucket, tier),
 		failureMode: options.failureMode,
 		enableProtection: options.enableProtection,
-		denyListThreshold: options.denyListThreshold
-	}).limit(identifier, await options.getSignals(args))).success) throw new CRPCError({
+		denyListThreshold: options.denyListThreshold,
+		denyList: options.denyList,
+		dynamicLimits: options.dynamicLimits,
+		timeout: options.timeout,
+		ephemeralCache: options.ephemeralCache
+	}).limit(identifier, signals)).success) throw new CRPCError({
 		code: "TOO_MANY_REQUESTS",
 		message: await resolveMessage(options, args)
 	});
@@ -1180,4 +1334,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, snapshotToState, toMs, tokenBucket };
+export { DAY, HOUR, MINUTE, RATE_LIMIT_DYNAMIC_TABLE, RATE_LIMIT_HIT_TABLE, RATE_LIMIT_STATE_TABLE, Ratelimit, RatelimitPlugin, SECOND, WEEK, applyDynamicLimit, calculateRatelimit, cleanupRatelimitState, fixedWindow, slidingWindow, snapshotToState, toMs, tokenBucket };

package/dist/react/index.d.ts

@@ -416,6 +416,12 @@ interface CRPCHttpRouter<TRecord extends HttpRouterRecord> {
 }
 //#endregion
 //#region src/crpc/http-types.d.ts
+/** Exact cache key for one route + args, as stored in the QueryClient */
+type HttpQueryKey = readonly ['httpQuery', string, unknown];
+/** Route-wide prefix key that matches every args variant of one route */
+type HttpQueryPrefixKey = readonly ['httpQuery', string];
+/** Mutation key for HTTP endpoints */
+type HttpMutationKey = readonly ['httpMutation', string];
 /** Error codes that can be returned from HTTP endpoints */
 type HttpErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'METHOD_NOT_SUPPORTED' | 'CONFLICT' | 'UNPROCESSABLE_CONTENT' | 'TOO_MANY_REQUESTS' | 'INTERNAL_SERVER_ERROR' | 'UNKNOWN';
 /** HTTP client error */
@@ -692,9 +698,6 @@ type InferHttpClientArgs<T> = T extends HttpProcedure<infer TInput, infer _TOutp
 }> : HttpInputArgs;
 /** Infer output type from HttpProcedure */
 type InferHttpOutput<T> = T extends HttpProcedure<infer _TInput, infer TOutput, infer _TParams, infer _TQuery> ? TOutput extends UnsetMarker ? unknown : TOutput extends z.ZodTypeAny ? z.infer<TOutput> : unknown : unknown;
-/** Query key with args (3-element) or prefix key without args (2-element) for invalidation */
-type HttpQueryKey = readonly ['httpQuery', string, unknown] | readonly ['httpQuery', string];
-type HttpMutationKey = readonly ['httpMutation', string];
 type ReservedQueryOptions$1 = 'queryKey' | 'queryFn';
 type ReservedMutationOptions$1 = 'mutationFn';
 /** Query options for GET HTTP endpoints - compatible with both useQuery and useSuspenseQuery */
@@ -713,8 +716,8 @@ type HttpMutationOptions<T extends HttpProcedure> = DistributiveOmit<HttpMutatio
  * - mutationOptions: For one-time actions like exports (useMutation)
  */
 type DecorateHttpQuery<T extends HttpProcedure> = {
-  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get query key for QueryClient methods (with args = exact match, without = prefix) */
-  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter for QueryClient methods (e.g., invalidateQueries) */
+  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get the exact cache key these args are stored under (getQueryData/setQueryData) */
+  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter matching every args variant (e.g., invalidateQueries) */
   queryFilter: (args?: InferHttpClientArgs<T>, filters?: DistributiveOmit<QueryFilters, 'queryKey'>) => QueryFilters; /** Mutation options for GET endpoints (exports, downloads - no caching) */
   mutationOptions: (opts?: HttpMutationOptions<T>) => HttpMutationOptsReturn<T>; /** Get mutation key for QueryClient methods */
   mutationKey: () => HttpMutationKey;
@@ -1151,4 +1154,4 @@ declare function useUploadMutationOptions<TGenerateUrlMutation extends FunctionR
  */
 declare function createVanillaCRPCProxy<TApi extends Record<string, unknown>>(api: TApi, meta: CallerMeta, convexClient: ConvexReactClient$1, transformer?: DataTransformerOptions): VanillaCRPCClient<TApi>;
 //#endregion
-export { AUTH_SESSION_SYNC_GRACE_MS, AuthMutationError, AuthProvider, AuthStore, AuthStoreState, Authenticated, CRPCHttpOptions, ConvexAuthBridge, ConvexAuthRecovery, ConvexAuthRecoveryError, ConvexAuthRecoveryErrorCode, ConvexAuthRecoveryOptions, ConvexAuthRecoveryStatus, ConvexProvider, ConvexProviderWithAuth, ConvexQueryClient, ConvexQueryClientOptions, ConvexQueryClientSingletonOptions, ConvexReactClient, CreateCRPCContextOptions, FetchAccessTokenContext, FetchAccessTokenFn, HttpCRPCClient, HttpCRPCClientFromRouter, type HttpClientOptions, type HttpFormValue, type HttpInputArgs, HttpMutationKey, HttpProxyOptions, HttpQueryKey, HttpRouteInfo, HttpRouteMap, MaybeAuthenticated, MaybeUnauthenticated, PaginationState, PaginationStatus, Unauthenticated, UseInfiniteQueryResult, VanillaHttpCRPCClient, VanillaHttpCRPCClientFromRouter, createAuthMutations, createCRPCContext, createCRPCOptionsProxy, createHttpProxy, createVanillaCRPCProxy, decodeJwtExp, getConvexQueryClientSingleton, getQueryClientSingleton, isAuthMutationError, isSessionSyncGraceActive, useAuth, useAuthGuard, useAuthState, useAuthStore, useAuthValue, useConvex, useConvexActionOptions, useConvexActionQueryOptions, useSafeConvexAuth as useConvexAuth, useSafeConvexAuth, useConvexAuthBridge, useConvexAuthRecovery, useConvexInfiniteQueryOptions, useConvexMutationOptions, useConvexQueryClient, useConvexQueryOptions, useFetchAccessToken, useFnMeta, useInfiniteQuery, useIsAuth, useMaybeAuth, useMeta, useUploadMutationOptions };
+export { AUTH_SESSION_SYNC_GRACE_MS, AuthMutationError, AuthProvider, AuthStore, AuthStoreState, Authenticated, CRPCHttpOptions, ConvexAuthBridge, ConvexAuthRecovery, ConvexAuthRecoveryError, ConvexAuthRecoveryErrorCode, ConvexAuthRecoveryOptions, ConvexAuthRecoveryStatus, ConvexProvider, ConvexProviderWithAuth, ConvexQueryClient, ConvexQueryClientOptions, ConvexQueryClientSingletonOptions, ConvexReactClient, CreateCRPCContextOptions, FetchAccessTokenContext, FetchAccessTokenFn, HttpCRPCClient, HttpCRPCClientFromRouter, type HttpClientOptions, type HttpFormValue, type HttpInputArgs, type HttpMutationKey, HttpProxyOptions, type HttpQueryKey, type HttpQueryPrefixKey, HttpRouteInfo, HttpRouteMap, MaybeAuthenticated, MaybeUnauthenticated, PaginationState, PaginationStatus, Unauthenticated, UseInfiniteQueryResult, VanillaHttpCRPCClient, VanillaHttpCRPCClientFromRouter, createAuthMutations, createCRPCContext, createCRPCOptionsProxy, createHttpProxy, createVanillaCRPCProxy, decodeJwtExp, getConvexQueryClientSingleton, getQueryClientSingleton, isAuthMutationError, isSessionSyncGraceActive, useAuth, useAuthGuard, useAuthState, useAuthStore, useAuthValue, useConvex, useConvexActionOptions, useConvexActionQueryOptions, useSafeConvexAuth as useConvexAuth, useSafeConvexAuth, useConvexAuthBridge, useConvexAuthRecovery, useConvexInfiniteQueryOptions, useConvexMutationOptions, useConvexQueryClient, useConvexQueryOptions, useFetchAccessToken, useFnMeta, useInfiniteQuery, useIsAuth, useMaybeAuth, useMeta, useUploadMutationOptions };

package/dist/react/index.js

@@ -126,6 +126,38 @@ function getFunctionMeta(path, source) {
 
 //#endregion
 //#region src/crpc/http-types.ts
+/**
+* Build the exact cache key for an HTTP route.
+*
+* Missing args normalize to `{}` so the RSC prefetch, the browser observer, and
+* a hand-written `getQueryData` call all hash to the same key. Every producer
+* of an `httpQuery` cache key goes through here.
+*/
+function buildHttpQueryKey(routeKey, args) {
+	return [
+		"httpQuery",
+		routeKey,
+		args ?? {}
+	];
+}
+/**
+* Build the route-wide prefix key.
+*
+* Filters match on prefix, so this matches every args variant of the route.
+* Not a cache key: nothing is ever stored under it.
+*/
+function buildHttpQueryPrefixKey(routeKey) {
+	return ["httpQuery", routeKey];
+}
+/**
+* Freshness window for `crpc.http.*` routes, in milliseconds.
+*
+* HTTP routes are a pull model with no push channel, so hydrated data needs a
+* real freshness window or the browser refetches it on mount. The RSC
+* QueryClient reads the same constant, so the server dedupe window and the
+* client freshness window cannot drift apart.
+*/
+const HTTP_DEFAULT_STALE_TIME = 3e4;
 /** HTTP client error */
 var HttpClientError = class extends Error {
 	name = "HttpClientError";
@@ -524,12 +556,9 @@ function createRecursiveHttpProxy(opts, path = []) {
 			if (!route) throw new Error(`Unknown HTTP procedure: ${routeKey}`);
 			if (route.method !== "GET") throw new Error(`queryOptions is only available for GET endpoints, got ${route.method} for ${routeKey}`);
 			return (args, queryOpts) => ({
+				staleTime: HTTP_DEFAULT_STALE_TIME,
 				...queryOpts,
-				queryKey: [
-					"httpQuery",
-					routeKey,
-					args
-				],
+				queryKey: buildHttpQueryKey(routeKey, args),
 				queryFn: async () => {
 					try {
 						return await executeHttpRequest({
@@ -548,22 +577,12 @@ function createRecursiveHttpProxy(opts, path = []) {
 				}
 			});
 		}
-		if (prop === "queryKey") return (args) => {
-			return args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0) ? [
-				"httpQuery",
-				routeKey,
-				args
-			] : ["httpQuery", routeKey];
-		};
+		if (prop === "queryKey") return (args) => buildHttpQueryKey(routeKey, args);
 		if (prop === "queryFilter") return (args, filters) => {
 			const hasArgs = args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0);
 			return {
 				...filters,
-				queryKey: hasArgs ? [
-					"httpQuery",
-					routeKey,
-					args
-				] : ["httpQuery", routeKey]
+				queryKey: hasArgs ? buildHttpQueryKey(routeKey, args) : buildHttpQueryPrefixKey(routeKey)
 			};
 		};
 		if (prop === "mutationOptions") {

package/dist/rsc/index.d.ts

@@ -1,7 +1,7 @@
 import { n as DeepPartial, o as Simplify, r as DistributiveOmit } from "../types-DF2cg_w0.js";
-import { C as HttpProcedure, d as CRPCHttpRouter, j as DataTransformerOptions, p as HttpRouterRecord } from "../http-types-BoSDAh4Y.js";
+import { L as DataTransformerOptions, _ as CRPCHttpRouter, c as HttpQueryKey, k as HttpProcedure, o as HttpMutationKey, y as HttpRouterRecord } from "../http-types-DXOgaerG.js";
 import { g as UnsetMarker } from "../types-CnTpHR1F.js";
-import { A as HttpInputArgs, C as ReservedMutationOptions$1, S as ReservedInfiniteQueryOptions, T as StaticQueryOptsParam, _ as IsPaginated, b as PaginatedFnMeta, c as ConvexMutationKey, d as ConvexQueryMeta, f as EmptyObject, g as InfiniteQueryInput, l as ConvexQueryHookOptions, m as FUNC_REF_SYMBOL, o as ConvexActionKey, p as ExtractPaginatedItem, s as ConvexInfiniteQueryMeta, u as ConvexQueryKey, w as ReservedQueryOptions$1, y as MutationVariables } from "../types-C0Xl7P8K.js";
+import { A as HttpInputArgs, C as ReservedMutationOptions$1, S as ReservedInfiniteQueryOptions, T as StaticQueryOptsParam, _ as IsPaginated, b as PaginatedFnMeta, c as ConvexMutationKey, d as ConvexQueryMeta, f as EmptyObject, g as InfiniteQueryInput, l as ConvexQueryHookOptions, m as FUNC_REF_SYMBOL, o as ConvexActionKey, p as ExtractPaginatedItem, s as ConvexInfiniteQueryMeta, u as ConvexQueryKey, w as ReservedQueryOptions$1, y as MutationVariables } from "../types-BHR7ZKKD.js";
 import { FunctionArgs, FunctionReference, FunctionReturnType } from "convex/server";
 import { z } from "zod";
 import { DefaultError, QueryFilters, SkipToken, UseMutationOptions, UseQueryOptions } from "@tanstack/react-query";
@@ -137,9 +137,6 @@ type InferHttpClientArgs<T> = T extends HttpProcedure<infer TInput, infer _TOutp
 }> : HttpInputArgs;
 /** Infer output type from HttpProcedure */
 type InferHttpOutput<T> = T extends HttpProcedure<infer _TInput, infer TOutput, infer _TParams, infer _TQuery> ? TOutput extends UnsetMarker ? unknown : TOutput extends z.ZodTypeAny ? z.infer<TOutput> : unknown : unknown;
-/** Query key with args (3-element) or prefix key without args (2-element) for invalidation */
-type HttpQueryKey = readonly ['httpQuery', string, unknown] | readonly ['httpQuery', string];
-type HttpMutationKey = readonly ['httpMutation', string];
 type ReservedQueryOptions = 'queryKey' | 'queryFn';
 type ReservedMutationOptions = 'mutationFn';
 /** Query options for GET HTTP endpoints - compatible with both useQuery and useSuspenseQuery */
@@ -158,8 +155,8 @@ type HttpMutationOptions<T extends HttpProcedure> = DistributiveOmit<HttpMutatio
  * - mutationOptions: For one-time actions like exports (useMutation)
  */
 type DecorateHttpQuery<T extends HttpProcedure> = {
-  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get query key for QueryClient methods (with args = exact match, without = prefix) */
-  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter for QueryClient methods (e.g., invalidateQueries) */
+  queryOptions: keyof InferHttpInput<T> extends never ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : object extends InferHttpInput<T> ? (args?: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T> : (args: InferHttpClientArgs<T>, opts?: HttpQueryOptions<T>) => HttpQueryOptsReturn<T>; /** Get the exact cache key these args are stored under (getQueryData/setQueryData) */
+  queryKey: (args?: InferHttpClientArgs<T>) => HttpQueryKey; /** Get query filter matching every args variant (e.g., invalidateQueries) */
   queryFilter: (args?: InferHttpClientArgs<T>, filters?: DistributiveOmit<QueryFilters, 'queryKey'>) => QueryFilters; /** Mutation options for GET endpoints (exports, downloads - no caching) */
   mutationOptions: (opts?: HttpMutationOptions<T>) => HttpMutationOptsReturn<T>; /** Get mutation key for QueryClient methods */
   mutationKey: () => HttpMutationKey;

package/dist/rsc/index.js

@@ -1,7 +1,7 @@
 import { n as defaultIsUnauthorized } from "../error-Bvo7YEhk.js";
 import { n as getFuncRef, r as getFunctionMeta, t as buildMetaIndex } from "../meta-utils-D9K4fICl.js";
 import { o as encodeWire, s as getTransformer } from "../transformer-yZuBWo8v.js";
-import { n as convexInfiniteQueryOptions, o as executeHttpRequest, r as convexQuery } from "../query-options-C_eBSIXG.js";
+import { c as HTTP_DEFAULT_STALE_TIME, n as convexInfiniteQueryOptions, o as executeHttpRequest, r as convexQuery, u as buildHttpQueryKey } from "../query-options-CzRV4G4N.js";
 import { convexToJson } from "convex/values";
 import { getFunctionName } from "convex/server";
 import { fetchAction, fetchQuery } from "convex/nextjs";
@@ -14,11 +14,7 @@ import { hashKey } from "@tanstack/query-core";
 */
 function buildHttpQueryOptions(route, routeKey, args) {
 	return {
-		queryKey: [
-			"httpQuery",
-			routeKey,
-			args
-		],
+		queryKey: buildHttpQueryKey(routeKey, args),
 		meta: {
 			path: route.path,
 			method: route.method
@@ -59,7 +55,7 @@ function createRecursiveProxy(api, path, meta) {
 			const routeKey = path.slice(1).join(".");
 			const route = meta._http?.[routeKey];
 			if (!route) throw new Error(`HTTP route not found: ${routeKey}`);
-			return (args = {}) => buildHttpQueryOptions(route, routeKey, args);
+			return (args) => buildHttpQueryOptions(route, routeKey, args);
 		}
 		if (prop === "queryOptions") return (args = {}, opts) => {
 			return convexQuery(getFuncRef(api, path), args, meta, opts);
@@ -189,7 +185,7 @@ function createHashFn(fallback = hashKey) {
 function getServerQueryClientOptions({ getToken, convexSiteUrl, transformer: transformerOptions } = {}) {
 	const transformer = getTransformer(transformerOptions);
 	return { queries: {
-		staleTime: 3e4,
+		staleTime: HTTP_DEFAULT_STALE_TIME,
 		queryFn: async ({ queryKey, meta }) => {
 			const [type, ...rest] = queryKey;
 			const token = await getToken?.();

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
-import { $ as ActionProcedureBuilder, A as CRPCError, B as RuntimeEnv, C as createProcedureHandlerFactory, Ct as zCustomQuery, D as WithHttpRouter, Dt as zodToConvex, E as typedProcedureResolver, Et as zodOutputToConvexFields, F as getCRPCErrorFromUnknown, G as createLazyCaller, H as ConvexContext, I as getHTTPStatusCodeFromError, J as ServerCaller, K as CallerMeta, L as isCRPCError, M as CRPCErrorData, N as CRPC_ERROR_CODES_BY_KEY, O as inferApiInputs, Ot as zodToConvexFields, P as CRPC_ERROR_CODE_TO_HTTP, Q as getGeneratedValue, R as toCRPCError, S as createProcedureCallerFactory, St as zCustomMutation, T as getGeneratedFunctionReference, Tt as zodOutputToConvex, U as createCallerFactory, V as createEnv, W as LazyCaller, X as createApiLeaf, Y as createServerCaller, Z as createGeneratedFunctionReference, _ as ProcedureSchedulableCallerFromRegistry, _t as ZodValidatorFromConvex, a as CreateProcedureCallerFactoryOptions, at as initCRPC, b as createGenericCallerFactory, bt as withSystemFields, c as GeneratedRegistryCallerFactory, ct as extractPathParams, d as GeneratedRegistryHandlerForContext, dt as ConvexValidatorFromZod, et as CRPCFunctionTypeHint, f as ProcedureActionCallerFromRegistry, ft as ConvexValidatorFromZodOutput, g as ProcedureFromFunctionReference, gt as ZodFromValidatorBase, h as ProcedureDefinition, ht as Zid, i as registerProcedureNameLookup, it as createMiddlewareFactory, j as CRPCErrorCode, k as inferApiOutputs, l as GeneratedRegistryCallerForContext, lt as handleHttpError, m as ProcedureCallerFromRegistry, mt as ZCustomCtx, n as ProcedureNameLookup, nt as ProcedureBuilder, o as GeneratedProcedureRegistry, ot as HttpProcedureBuilder, p as ProcedureCaller, pt as CustomBuilder, q as CallerOpts, r as inferProcedureNameFromCallsite, rt as QueryProcedureBuilder, s as GeneratedProcedureRegistryEntry, st as createHttpProcedureBuilder, t as ProcedureNameEntry, tt as MutationProcedureBuilder, u as GeneratedRegistryHandlerFactory, ut as matchPathParams, v as ProcedureScheduleCallerFromRegistry, vt as convexToZod, w as defineProcedure, wt as zid, x as createGenericHandlerFactory, xt as zCustomAction, y as createGeneratedRegistryRuntime, yt as convexToZodFields, z as CreateEnvOptions } from "../procedure-name-C55TynK3.js";
-import { C as HttpProcedure, D as ProcedureMeta, E as InferHttpInput, S as HttpMethod, T as HttpRouteDefinition, _ as extractRouteMap, b as HttpActionHandler, d as CRPCHttpRouter, f as HttpRouterDef, g as createHttpRouterFactory, h as createHttpRouter, m as HttpRouterWithHono, p as HttpRouterRecord, v as CRPCHonoHandler, w as HttpProcedureBuilderDef, x as HttpHandlerOpts, y as HttpActionConstructor } from "../http-types-BoSDAh4Y.js";
+import { $ as ActionProcedureBuilder, A as CRPCError, B as RuntimeEnv, C as createProcedureHandlerFactory, Ct as zCustomQuery, D as WithHttpRouter, Dt as zodToConvex, E as typedProcedureResolver, Et as zodOutputToConvexFields, F as getCRPCErrorFromUnknown, G as createLazyCaller, H as ConvexContext, I as getHTTPStatusCodeFromError, J as ServerCaller, K as CallerMeta, L as isCRPCError, M as CRPCErrorData, N as CRPC_ERROR_CODES_BY_KEY, O as inferApiInputs, Ot as zodToConvexFields, P as CRPC_ERROR_CODE_TO_HTTP, Q as getGeneratedValue, R as toCRPCError, S as createProcedureCallerFactory, St as zCustomMutation, T as getGeneratedFunctionReference, Tt as zodOutputToConvex, U as createCallerFactory, V as createEnv, W as LazyCaller, X as createApiLeaf, Y as createServerCaller, Z as createGeneratedFunctionReference, _ as ProcedureSchedulableCallerFromRegistry, _t as ZodValidatorFromConvex, a as CreateProcedureCallerFactoryOptions, at as initCRPC, b as createGenericCallerFactory, bt as withSystemFields, c as GeneratedRegistryCallerFactory, ct as extractPathParams, d as GeneratedRegistryHandlerForContext, dt as ConvexValidatorFromZod, et as CRPCFunctionTypeHint, f as ProcedureActionCallerFromRegistry, ft as ConvexValidatorFromZodOutput, g as ProcedureFromFunctionReference, gt as ZodFromValidatorBase, h as ProcedureDefinition, ht as Zid, i as registerProcedureNameLookup, it as createMiddlewareFactory, j as CRPCErrorCode, k as inferApiOutputs, l as GeneratedRegistryCallerForContext, lt as handleHttpError, m as ProcedureCallerFromRegistry, mt as ZCustomCtx, n as ProcedureNameLookup, nt as ProcedureBuilder, o as GeneratedProcedureRegistry, ot as HttpProcedureBuilder, p as ProcedureCaller, pt as CustomBuilder, q as CallerOpts, r as inferProcedureNameFromCallsite, rt as QueryProcedureBuilder, s as GeneratedProcedureRegistryEntry, st as createHttpProcedureBuilder, t as ProcedureNameEntry, tt as MutationProcedureBuilder, u as GeneratedRegistryHandlerFactory, ut as matchPathParams, v as ProcedureScheduleCallerFromRegistry, vt as convexToZod, w as defineProcedure, wt as zid, x as createGenericHandlerFactory, xt as zCustomAction, y as createGeneratedRegistryRuntime, yt as convexToZodFields, z as CreateEnvOptions } from "../procedure-name-C20pFZnk.js";
+import { A as HttpProcedureBuilderDef, C as extractRouteMap, D as HttpHandlerOpts, E as HttpActionHandler, M as InferHttpInput, N as ProcedureMeta, O as HttpMethod, S as createHttpRouterFactory, T as HttpActionConstructor, _ as CRPCHttpRouter, b as HttpRouterWithHono, j as HttpRouteDefinition, k as HttpProcedure, v as HttpRouterDef, w as CRPCHonoHandler, x as createHttpRouter, y as HttpRouterRecord } from "../http-types-DXOgaerG.js";
 import { a as MergeZodObjects, c as MiddlewareMarker, d as MiddlewareProcedureType, f as MiddlewareResult, g as UnsetMarker, h as Simplify, i as IntersectIfDefined, l as MiddlewareNext, m as ResolveIfSet, n as AnyMiddlewareBuilder, o as MiddlewareBuilder, p as Overwrite, r as GetRawInputFn, s as MiddlewareFunction, t as AnyMiddleware, u as MiddlewareProcedureInfo } from "../types-CnTpHR1F.js";
 import { a as isMutationCtx, c as isSchedulerCtx, d as requireQueryCtx, f as requireRunMutationCtx, i as isActionCtx, l as requireActionCtx, n as RunMutationCtx, o as isQueryCtx, p as requireSchedulerCtx, r as SchedulerCtx, s as isRunMutationCtx, t as GenericCtx, u as requireMutationCtx } from "../context-utils-BBUtBqjN.js";
 export { ActionProcedureBuilder, AnyMiddleware, AnyMiddlewareBuilder, CRPCError, CRPCErrorCode, CRPCErrorData, CRPCFunctionTypeHint, CRPCHonoHandler, CRPCHttpRouter, CRPC_ERROR_CODES_BY_KEY, CRPC_ERROR_CODE_TO_HTTP, CallerMeta, CallerOpts, ConvexContext, ConvexValidatorFromZod, ConvexValidatorFromZodOutput, CreateEnvOptions, CreateProcedureCallerFactoryOptions, CustomBuilder, GeneratedProcedureRegistry, GeneratedProcedureRegistryEntry, GeneratedRegistryCallerFactory, GeneratedRegistryCallerForContext, GeneratedRegistryHandlerFactory, GeneratedRegistryHandlerForContext, GenericCtx, GetRawInputFn, HttpActionConstructor, HttpActionHandler, HttpHandlerOpts, HttpMethod, HttpProcedure, HttpProcedureBuilder, HttpProcedureBuilderDef, HttpRouteDefinition, HttpRouterDef, HttpRouterRecord, HttpRouterWithHono, InferHttpInput, IntersectIfDefined, LazyCaller, MergeZodObjects, MiddlewareBuilder, MiddlewareFunction, MiddlewareMarker, MiddlewareNext, MiddlewareProcedureInfo, MiddlewareProcedureType, MiddlewareResult, MutationProcedureBuilder, Overwrite, ProcedureActionCallerFromRegistry, ProcedureBuilder, ProcedureCaller, ProcedureCallerFromRegistry, ProcedureDefinition, ProcedureFromFunctionReference, ProcedureMeta, ProcedureNameEntry, ProcedureNameLookup, ProcedureSchedulableCallerFromRegistry, ProcedureScheduleCallerFromRegistry, QueryProcedureBuilder, ResolveIfSet, RunMutationCtx, RuntimeEnv, SchedulerCtx, ServerCaller, Simplify, UnsetMarker, WithHttpRouter, ZCustomCtx, Zid, ZodFromValidatorBase, ZodValidatorFromConvex, convexToZod, convexToZodFields, createApiLeaf, createCallerFactory, createEnv, createGeneratedFunctionReference, createGeneratedRegistryRuntime, createGenericCallerFactory, createGenericHandlerFactory, createHttpProcedureBuilder, createHttpRouter, createHttpRouterFactory, createLazyCaller, createMiddlewareFactory, createProcedureCallerFactory, createProcedureHandlerFactory, createServerCaller, defineProcedure, extractPathParams, extractRouteMap, getCRPCErrorFromUnknown, getGeneratedFunctionReference, getGeneratedValue, getHTTPStatusCodeFromError, handleHttpError, inferApiInputs, inferApiOutputs, inferProcedureNameFromCallsite, initCRPC, isActionCtx, isCRPCError, isMutationCtx, isQueryCtx, isRunMutationCtx, isSchedulerCtx, matchPathParams, registerProcedureNameLookup, requireActionCtx, requireMutationCtx, requireQueryCtx, requireRunMutationCtx, requireSchedulerCtx, toCRPCError, typedProcedureResolver, withSystemFields, zCustomAction, zCustomMutation, zCustomQuery, zid, zodOutputToConvex, zodOutputToConvexFields, zodToConvex, zodToConvexFields };