@upstash/ratelimit 1.1.2 → 1.2.0-canary

package/README.md

@@ -1,7 +1,7 @@
 # Upstash Rate Limit
 
-[![Tests](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml/badge.svg)](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml)
 [![npm (scoped)](https://img.shields.io/npm/v/@upstash/ratelimit)](https://www.npmjs.com/package/@upstash/ratelimit)
+[![Tests](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml/badge.svg)](https://github.com/upstash/ratelimit/actions/workflows/tests.yaml)
 
 > [!NOTE] > **This project is in GA Stage.**
 > The Upstash Professional Support fully covers this project. It receives regular updates, and bug fixes. The Upstash team is committed to maintaining and improving its functionality.
@@ -69,84 +69,13 @@ doExpensiveCalculation();
 return "Here you go!";
 ```
 
-For Cloudflare Workers and Fastly Compute@Edge, you can use the following imports:
-
-```ts
-import { Redis } from "@upstash/redis/cloudflare"; // for cloudflare workers and pages
-import { Redis } from "@upstash/redis/fastly"; // for fastly compute@edge
-```
+For more information on getting started, you can refer to [our documentation](https://upstash.com/docs/oss/sdks/ts/ratelimit/gettingstarted).
 
 [Here's a complete nextjs example](https://github.com/upstash/ratelimit/tree/main/examples/nextjs)
 
-The `limit` method returns some more metadata that might be useful to you:
-
-````ts
-export type RatelimitResponse = {
-  /**
-   * Whether the request may pass(true) or exceeded the limit(false)
-   */
-  success: boolean;
-  /**
-   * Maximum number of requests allowed within a window.
-   */
-  limit: number;
-  /**
-   * How many requests the user has left within the current window.
-   */
-  remaining: number;
-  /**
-   * Unix timestamp in milliseconds when the limits are reset.
-   */
-  reset: number;
+## Documentation
 
-  /**
-   * For the MultiRegion setup we do some synchronizing in the background, after returning the current limit.
-   * Or when analytics is enabled, we send the analytics asynchronously after returning the limit.
-   * In most case you can simply ignore this.
-   *
-   * On Vercel Edge or Cloudflare workers, you need to explicitly handle the pending Promise like this:
-   *
-   * ```ts
-   * const { pending } = await ratelimit.limit("id")
-   * context.waitUntil(pending)
-   * ```
-   *
-   * See `waitUntil` documentation in
-   * [Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil)
-   * and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil)
-   * for more details.
-   * ```
-   */
-  pending: Promise<unknown>;
-};
-````
-
-### Docs
-
-See [the documentation](https://upstash.com/docs/oss/sdks/ts/ratelimit/overview) for more information details.
-
-
-### Using with CloudFlare Workers and Vercel Edge
-
-When we use CloudFlare Workers and Vercel Edge, we need to be careful about
-making sure that the rate limiting operations complete correctly before the runtime ends
-after returning the response.
-
-This is important in two cases where we do some operations in the backgroung asynchronously after `limit` is called:
-
-1. Using MultiRegion: synchronize Redis instances in different regions
-2. Enabling analytics: send analytics to Redis
-
-In these cases, we need to wait for these operations to finish before sending the response to the user. Otherwise, the runtime will end and we won't be able to complete our chores.
-
-In order to wait for these operations to finish, use the `pending` promise:
-
-```ts
-const { pending } = await ratelimit.limit("id");
-context.waitUntil(pending);
-```
-
-See `waitUntil` documentation in [Cloudflare](https://developers.cloudflare.com/workers/runtime-apis/handlers/fetch/#contextwaituntil) and [Vercel](https://vercel.com/docs/functions/edge-middleware/middleware-api#waituntil) for more details.
+See [the documentation](https://upstash.com/docs/oss/sdks/ts/ratelimit/overview) for more information details about this package.
 
 ## Contributing
 
@@ -157,6 +86,20 @@ the url and token.
 
 ### Running tests
 
+To run the tests, you will need to set some environment variables. Here is a list of
+variables to set:
+- `UPSTASH_REDIS_REST_URL`
+- `UPSTASH_REDIS_REST_TOKEN`
+- `US1_UPSTASH_REDIS_REST_URL`
+- `US1_UPSTASH_REDIS_REST_TOKEN`
+- `APN_UPSTASH_REDIS_REST_URL`
+- `APN_UPSTASH_REDIS_REST_TOKEN`
+- `EU2_UPSTASH_REDIS_REST_URL`
+- `EU2_UPSTASH_REDIS_REST_TOKEN`
+
+You can create a single Upstash Redis and use its URL and token for all four above.
+
+Once you set the environment variables, simply run:
 ```sh
-UPSTASH_REDIS_REST_URL=".." UPSTASH_REDIS_REST_TOKEN=".." pnpm test
+pnpm test
 ```

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/