credit lease SDK primitives: check / trackWithReservation / prewarm

src/cache/redis.ts

@@ -1,15 +1,42 @@
 import { CacheProvider, CacheOptions } from "./types";
 
 /**
- * Minimal interface describing the redis client methods used by RedisCacheProvider.
- * Compatible with the 'redis' package's RedisClientType.
+ * Minimal interface describing the redis client methods used by the SDK.
+ * Compatible with the 'redis' package's RedisClientType (node-redis v4).
+ *
+ * Includes hash + sorted-set + eval surface used by the credit-lease and
+ * reservation stores to coordinate state across multiple SDK pods.
  */
 export interface RedisClient {
   get(key: string): Promise<string | null>;
   set(key: string, value: string): Promise<unknown>;
   setEx(key: string, seconds: number, value: string): Promise<unknown>;
   del(key: string | string[]): Promise<unknown>;
   scanIterator(options: { MATCH: string; COUNT: number }): AsyncIterable<string>;
+  // Hash ops — used to store lease + reservation state as a single field-set
+  // so partial updates (e.g. atomic decrement on localRemainingCredits) don't
+  // step on neighboring fields.
+  hSet(key: string, field: string | Record<string, string | number>, value?: string | number): Promise<unknown>;
+  hGet(key: string, field: string): Promise<string | null | undefined>;
+  hGetAll(key: string): Promise<Record<string, string>>;
+  hDel(key: string, field: string | string[]): Promise<unknown>;
+  // Sorted-set ops — used to index reservations by expiry timestamp so the
+  // sweeper can pop expired entries in O(log n).
+  zAdd(key: string, members: { score: number; value: string } | { score: number; value: string }[]): Promise<unknown>;
+  zRangeByScore(key: string, min: number | string, max: number | string): Promise<string[]>;
+  zRem(key: string, member: string | string[]): Promise<unknown>;
+  zCard(key: string): Promise<number>;
+  // Lua scripts — used for the single-key atomic primitives (check-and-decrement
+  // on lease balance, claim-and-delete on a reservation). Kept single-key so
+  // they're safe under Redis Cluster (a multi-key EVAL whose keys span slots
+  // raises CROSSSLOT).
+  eval(
+    script: string,
+    options: { keys: string[]; arguments: string[] },
+  ): Promise<unknown>;
+  // Expiry on a millisecond-precision absolute timestamp — used to auto-clean
+  // lease + reservation rows shortly after their declared expiry.
+  pExpireAt(key: string, timestamp: number): Promise<unknown>;
 }
 
 export interface RedisOptions extends CacheOptions {