@upstash/ratelimit 1.1.3 → 1.2.0-canary

package/dist/index.d.mts

@@ -14,15 +14,23 @@ interface EphemeralCache {
     incr: (key: string) => number;
     pop: (key: string) => void;
     empty: () => void;
+    size: () => number;
 }
 type RegionContext = {
     redis: Redis;
     cache?: EphemeralCache;
+    scriptHashes: {
+        limitHash?: string;
+        getRemainingHash?: string;
+        resetHash?: string;
+    };
+    cacheScripts: boolean;
 };
 type MultiRegionContext = {
-    redis: Redis[];
+    regionContexts: Omit<RegionContext[], "cache">;
     cache?: EphemeralCache;
 };
+type RatelimitResponseType = "timeout" | "cacheBlock" | "denyList";
 type Context = RegionContext | MultiRegionContext;
 type RatelimitResponse = {
     /**
@@ -60,13 +68,37 @@ type RatelimitResponse = {
      * ```
      */
     pending: Promise<unknown>;
+    /**
+     * Reason behind the result in `success` field.
+     * - Is set to "timeout" when request times out
+     * - Is set to "cacheBlock" when an identifier is blocked through cache without calling redis because it was
+     *    rate limited previously.
+     * - Is set to "denyList" when identifier or one of ip/user-agent/country parameters is in deny list. To enable
+     *    deny list, see `enableProtection` parameter. To edit the deny list, see the Upstash Ratelimit Dashboard
+     *    at https://console.upstash.com/ratelimit.
+     * - Is set to undefined if rate limit check had to use Redis. This happens in cases when `success` field in
+     *    the response is true. It can also happen the first time sucecss is false.
+     */
+    reason?: RatelimitResponseType;
+    /**
+     * The value which was in the deny list if reason: "denyList"
+     */
+    deniedValue?: string;
 };
 type Algorithm<TContext> = () => {
     limit: (ctx: TContext, identifier: string, rate?: number, opts?: {
         cache?: EphemeralCache;
     }) => Promise<RatelimitResponse>;
     getRemaining: (ctx: TContext, identifier: string) => Promise<number>;
-    resetTokens: (ctx: TContext, identifier: string) => void;
+    resetTokens: (ctx: TContext, identifier: string) => Promise<void>;
+};
+type IsDenied = 0 | 1;
+type LimitOptions = {
+    geo?: Geo;
+    rate?: number;
+    ip?: string;
+    userAgent?: string;
+    country?: string;
 };
 /**
  * This is all we need from the redis sdk.
@@ -77,6 +109,9 @@ interface Redis {
         [key: string]: TValue;
     }) => Promise<number>;
     eval: <TArgs extends unknown[], TData = unknown>(...args: [script: string, keys: string[], args: TArgs]) => Promise<TData>;
+    evalsha: <TArgs extends unknown[], TData = unknown>(...args: [sha1: string, keys: string[], args: TArgs]) => Promise<TData>;
+    scriptLoad: (...args: [script: string]) => Promise<string>;
+    smismember: (key: string, members: string[]) => Promise<IsDenied[]>;
 }
 
 type Geo = {
@@ -85,10 +120,16 @@ type Geo = {
     region?: string;
     ip?: string;
 };
+/**
+ * denotes the success field in the analytics submission.
+ * Set to true when ratelimit check passes. False when request is ratelimited.
+ * Set to "denied" when some request value is in deny list.
+ */
+type EventSuccess = boolean | "denied";
 type Event = Geo & {
     identifier: string;
     time: number;
-    success: boolean;
+    success: EventSuccess;
 };
 type AnalyticsConfig = {
     redis: Redis;
@@ -124,7 +165,11 @@ declare class Analytics {
             identifier: string;
             count: number;
         }[];
-        blocked: {
+        ratelimited: {
+            identifier: string;
+            count: number;
+        }[];
+        denied: {
             identifier: string;
             count: number;
         }[];
@@ -184,6 +229,14 @@ type RatelimitConfig<TContext> = {
      * @default false
      */
     analytics?: boolean;
+    /**
+     * Enables deny list. If set to true, requests with identifier or ip/user-agent/countrie
+     * in the deny list will be rejected automatically. To edit the deny list, check out the
+     * ratelimit dashboard at https://console.upstash.com/ratelimit
+     *
+     * @default false
+     */
+    enableProtection?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
@@ -205,7 +258,9 @@ declare abstract class Ratelimit<TContext extends Context> {
     protected readonly ctx: TContext;
     protected readonly prefix: string;
     protected readonly timeout: number;
+    protected readonly primaryRedis: Redis;
     protected readonly analytics?: Analytics;
+    protected readonly enableProtection: boolean;
     constructor(config: RatelimitConfig<TContext>);
     /**
      * Determine if a request should pass or be rejected based on the identifier and previously chosen ratelimit.
@@ -243,10 +298,7 @@ declare abstract class Ratelimit<TContext extends Context> {
      *  return "Yes"
      * ```
      */
-    limit: (identifier: string, req?: {
-        geo?: Geo;
-        rate?: number;
-    }) => Promise<RatelimitResponse>;
+    limit: (identifier: string, req?: LimitOptions) => Promise<RatelimitResponse>;
     /**
      * Block until the request may pass or timeout is reached.
      *
@@ -272,6 +324,46 @@ declare abstract class Ratelimit<TContext extends Context> {
     blockUntilReady: (identifier: string, timeout: number) => Promise<RatelimitResponse>;
     resetUsedTokens: (identifier: string) => Promise<void>;
     getRemaining: (identifier: string) => Promise<number>;
+    /**
+     * Checks if the identifier or the values in req are in the deny list cache.
+     * If so, returns the default denied response.
+     *
+     * Otherwise, calls redis to check the rate limit and deny list. Returns after
+     * resolving the result. Resolving is overriding the rate limit result if
+     * the some value is in deny list.
+     *
+     * @param identifier identifier to block
+     * @param req options with ip, user agent, country, rate and geo info
+     * @returns rate limit response
+     */
+    private getRatelimitResponse;
+    /**
+     * Creates an array with the original response promise and a timeout promise
+     * if this.timeout > 0.
+     *
+     * @param response Ratelimit response promise
+     * @returns array with the response and timeout promise. also includes the timeout id
+     */
+    private applyTimeout;
+    /**
+     * submits analytics if this.analytics is set
+     *
+     * @param ratelimitResponse final rate limit response
+     * @param identifier identifier to submit
+     * @param req limit options
+     * @returns rate limit response after updating the .pending field
+     */
+    private submitAnalytics;
+    private getKey;
+    /**
+     * returns a list of defined values from
+     * [identifier, req.ip, req.userAgent, req.country]
+     *
+     * @param identifier identifier
+     * @param req limit options
+     * @returns list of defined values
+     */
+    private getDefinedMembers;
 }
 
 type MultiRegionRatelimitConfig = {
@@ -324,6 +416,13 @@ type MultiRegionRatelimitConfig = {
      * @default false
      */
     analytics?: boolean;
+    /**
+     * If enabled, lua scripts will be sent to Redis with SCRIPT LOAD durint the first request.
+     * In the subsequent requests, hash of the script will be used to invoke it
+     *
+     * @default true
+     */
+    cacheScripts?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
@@ -451,6 +550,17 @@ type RegionRatelimitConfig = {
      * @default false
      */
     analytics?: boolean;
+    /**
+     * If enabled, lua scripts will be sent to Redis with SCRIPT LOAD durint the first request.
+     * In the subsequent requests, hash of the script will be used to invoke it
+     *
+     * @default true
+     */
+    cacheScripts?: boolean;
+    /**
+     * @default false
+     */
+    enableProtection?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/

package/dist/index.d.ts

@@ -14,15 +14,23 @@ interface EphemeralCache {
     incr: (key: string) => number;
     pop: (key: string) => void;
     empty: () => void;
+    size: () => number;
 }
 type RegionContext = {
     redis: Redis;
     cache?: EphemeralCache;
+    scriptHashes: {
+        limitHash?: string;
+        getRemainingHash?: string;
+        resetHash?: string;
+    };
+    cacheScripts: boolean;
 };
 type MultiRegionContext = {
-    redis: Redis[];
+    regionContexts: Omit<RegionContext[], "cache">;
     cache?: EphemeralCache;
 };
+type RatelimitResponseType = "timeout" | "cacheBlock" | "denyList";
 type Context = RegionContext | MultiRegionContext;
 type RatelimitResponse = {
     /**
@@ -60,13 +68,37 @@ type RatelimitResponse = {
      * ```
      */
     pending: Promise<unknown>;
+    /**
+     * Reason behind the result in `success` field.
+     * - Is set to "timeout" when request times out
+     * - Is set to "cacheBlock" when an identifier is blocked through cache without calling redis because it was
+     *    rate limited previously.
+     * - Is set to "denyList" when identifier or one of ip/user-agent/country parameters is in deny list. To enable
+     *    deny list, see `enableProtection` parameter. To edit the deny list, see the Upstash Ratelimit Dashboard
+     *    at https://console.upstash.com/ratelimit.
+     * - Is set to undefined if rate limit check had to use Redis. This happens in cases when `success` field in
+     *    the response is true. It can also happen the first time sucecss is false.
+     */
+    reason?: RatelimitResponseType;
+    /**
+     * The value which was in the deny list if reason: "denyList"
+     */
+    deniedValue?: string;
 };
 type Algorithm<TContext> = () => {
     limit: (ctx: TContext, identifier: string, rate?: number, opts?: {
         cache?: EphemeralCache;
     }) => Promise<RatelimitResponse>;
     getRemaining: (ctx: TContext, identifier: string) => Promise<number>;
-    resetTokens: (ctx: TContext, identifier: string) => void;
+    resetTokens: (ctx: TContext, identifier: string) => Promise<void>;
+};
+type IsDenied = 0 | 1;
+type LimitOptions = {
+    geo?: Geo;
+    rate?: number;
+    ip?: string;
+    userAgent?: string;
+    country?: string;
 };
 /**
  * This is all we need from the redis sdk.
@@ -77,6 +109,9 @@ interface Redis {
         [key: string]: TValue;
     }) => Promise<number>;
     eval: <TArgs extends unknown[], TData = unknown>(...args: [script: string, keys: string[], args: TArgs]) => Promise<TData>;
+    evalsha: <TArgs extends unknown[], TData = unknown>(...args: [sha1: string, keys: string[], args: TArgs]) => Promise<TData>;
+    scriptLoad: (...args: [script: string]) => Promise<string>;
+    smismember: (key: string, members: string[]) => Promise<IsDenied[]>;
 }
 
 type Geo = {
@@ -85,10 +120,16 @@ type Geo = {
     region?: string;
     ip?: string;
 };
+/**
+ * denotes the success field in the analytics submission.
+ * Set to true when ratelimit check passes. False when request is ratelimited.
+ * Set to "denied" when some request value is in deny list.
+ */
+type EventSuccess = boolean | "denied";
 type Event = Geo & {
     identifier: string;
     time: number;
-    success: boolean;
+    success: EventSuccess;
 };
 type AnalyticsConfig = {
     redis: Redis;
@@ -124,7 +165,11 @@ declare class Analytics {
             identifier: string;
             count: number;
         }[];
-        blocked: {
+        ratelimited: {
+            identifier: string;
+            count: number;
+        }[];
+        denied: {
             identifier: string;
             count: number;
         }[];
@@ -184,6 +229,14 @@ type RatelimitConfig<TContext> = {
      * @default false
      */
     analytics?: boolean;
+    /**
+     * Enables deny list. If set to true, requests with identifier or ip/user-agent/countrie
+     * in the deny list will be rejected automatically. To edit the deny list, check out the
+     * ratelimit dashboard at https://console.upstash.com/ratelimit
+     *
+     * @default false
+     */
+    enableProtection?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
@@ -205,7 +258,9 @@ declare abstract class Ratelimit<TContext extends Context> {
     protected readonly ctx: TContext;
     protected readonly prefix: string;
     protected readonly timeout: number;
+    protected readonly primaryRedis: Redis;
     protected readonly analytics?: Analytics;
+    protected readonly enableProtection: boolean;
     constructor(config: RatelimitConfig<TContext>);
     /**
      * Determine if a request should pass or be rejected based on the identifier and previously chosen ratelimit.
@@ -243,10 +298,7 @@ declare abstract class Ratelimit<TContext extends Context> {
      *  return "Yes"
      * ```
      */
-    limit: (identifier: string, req?: {
-        geo?: Geo;
-        rate?: number;
-    }) => Promise<RatelimitResponse>;
+    limit: (identifier: string, req?: LimitOptions) => Promise<RatelimitResponse>;
     /**
      * Block until the request may pass or timeout is reached.
      *
@@ -272,6 +324,46 @@ declare abstract class Ratelimit<TContext extends Context> {
     blockUntilReady: (identifier: string, timeout: number) => Promise<RatelimitResponse>;
     resetUsedTokens: (identifier: string) => Promise<void>;
     getRemaining: (identifier: string) => Promise<number>;
+    /**
+     * Checks if the identifier or the values in req are in the deny list cache.
+     * If so, returns the default denied response.
+     *
+     * Otherwise, calls redis to check the rate limit and deny list. Returns after
+     * resolving the result. Resolving is overriding the rate limit result if
+     * the some value is in deny list.
+     *
+     * @param identifier identifier to block
+     * @param req options with ip, user agent, country, rate and geo info
+     * @returns rate limit response
+     */
+    private getRatelimitResponse;
+    /**
+     * Creates an array with the original response promise and a timeout promise
+     * if this.timeout > 0.
+     *
+     * @param response Ratelimit response promise
+     * @returns array with the response and timeout promise. also includes the timeout id
+     */
+    private applyTimeout;
+    /**
+     * submits analytics if this.analytics is set
+     *
+     * @param ratelimitResponse final rate limit response
+     * @param identifier identifier to submit
+     * @param req limit options
+     * @returns rate limit response after updating the .pending field
+     */
+    private submitAnalytics;
+    private getKey;
+    /**
+     * returns a list of defined values from
+     * [identifier, req.ip, req.userAgent, req.country]
+     *
+     * @param identifier identifier
+     * @param req limit options
+     * @returns list of defined values
+     */
+    private getDefinedMembers;
 }
 
 type MultiRegionRatelimitConfig = {
@@ -324,6 +416,13 @@ type MultiRegionRatelimitConfig = {
      * @default false
      */
     analytics?: boolean;
+    /**
+     * If enabled, lua scripts will be sent to Redis with SCRIPT LOAD durint the first request.
+     * In the subsequent requests, hash of the script will be used to invoke it
+     *
+     * @default true
+     */
+    cacheScripts?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
@@ -451,6 +550,17 @@ type RegionRatelimitConfig = {
      * @default false
      */
     analytics?: boolean;
+    /**
+     * If enabled, lua scripts will be sent to Redis with SCRIPT LOAD durint the first request.
+     * In the subsequent requests, hash of the script will be used to invoke it
+     *
+     * @default true
+     */
+    cacheScripts?: boolean;
+    /**
+     * @default false
+     */
+    enableProtection?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/