@upstash/ratelimit 0.3.2 → 0.3.4

package/README.md

@@ -87,6 +87,7 @@ import { Redis } from "@upstash/redis";
 const ratelimit = new Ratelimit({
   redis: Redis.fromEnv(),
   limiter: Ratelimit.slidingWindow(10, "10 s"),
+  analytics: true
 });
 
 // Use a constant string to limit all requests with a single ratelimit
@@ -161,6 +162,7 @@ const ratelimit = new Ratelimit({
   redis: Redis.fromEnv(),
   limiter: Ratelimit.slidingWindow(10, "10 s"),
   timeout: 1000, // 1 second
+  analytics: true
 });
 ```
 
@@ -184,6 +186,7 @@ in a finite amount of time.
 const ratelimit = new Ratelimit({
   redis: Redis.fromEnv(),
   limiter: Ratelimit.slidingWindow(10, "10 s"),
+  analytics: true
 });
 
 // `blockUntilReady` returns a promise that resolves as soon as the request is allowed to be processed, or after 30 seconds
@@ -259,6 +262,7 @@ const ratelimit = new MultiRegionRatelimit({
     }),
   ],
   limiter: MultiRegionRatelimit.slidingWindow(10, "10 s"),
+  analytics: true
 });
 
 // Use a constant string to limit all requests with a single ratelimit
@@ -326,6 +330,7 @@ Create a new ratelimiter, that allows 10 requests per 10 seconds.
 const ratelimit = new Ratelimit({
   redis: Redis.fromEnv(),
   limiter: Ratelimit.fixedWindow(10, "10 s"),
+  analytics: true
 });
 ```
 
@@ -366,6 +371,7 @@ Create a new ratelimiter, that allows 10 requests per 10 seconds.
 const ratelimit = new Ratelimit({
   redis: Redis.fromEnv(),
   limiter: Ratelimit.slidingWindow(10, "10 s"),
+  analytics: true
 });
 ```
 
@@ -397,9 +403,30 @@ size of 10.
 const ratelimit = new Ratelimit({
   redis: Redis.fromEnv(),
   limiter: Ratelimit.tokenBucket(5, "10 s", 10),
+  analytics: true
 });
 ```
 
+## Analytics
+
+You can enable analytics to get a better understanding of how your ratelimiting
+is performing. This is done by setting `analytics: true` in the options.
+
+All data is stored in the same Redis database.
+
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.tokenBucket(5, "10 s", 10),
+  analytics: true // <- Enable analytics
+});
+```
+
+Go to the [Ratelimit Dashboard](https://console.upstash.com/rate-limit) and select the database you are using.
+
+![Ratelimit Dashboard](/.github/img/dashboard.png)
+
+
 ## Contributing
 
 ### [Install Deno](https://deno.land/#installation)

package/dist/index.d.ts

@@ -89,8 +89,8 @@ type AnalyticsConfig = {
  * The Analytics package is experimental and can change at any time.
  */
 declare class Analytics {
-    private readonly redis;
-    private readonly prefix;
+    private readonly analytics;
+    private readonly table;
     constructor(config: AnalyticsConfig);
     /**
      * Try to extract the geo information from the request
@@ -104,25 +104,7 @@ declare class Analytics {
         cf?: Geo;
     }): Geo;
     record(event: Event): Promise<void>;
-    /**
-     * Aggregates the events by the given field and returns the number of successes and failures per value
-     *
-     * @param aggregateBy - The field to aggregate by
-     * @param cutoff - Timestamp in milliseconds to limit the aggregation to `cutoff` until now
-     * @returns
-     */
-    aggregate<TAggregateBy extends keyof Omit<Event, "time">>(aggregateBy: TAggregateBy, cutoff?: number): Promise<Record<string, Record<string, {
-        success: number;
-        blocked: number;
-    }>>>;
-    /**
-     * Builds a timeseries of the aggreagated value
-     *
-     * @param aggregateBy - The field to aggregate by
-     * @param cutoff - Timestamp in milliseconds to limit the aggregation to `cutoff` until now
-     * @returns
-     */
-    series<TAggregateBy extends keyof Omit<Event, "time">>(aggregateBy: TAggregateBy, cutoff?: number): Promise<({
+    series<TFilter extends keyof Omit<Event, "time">>(filter: TFilter, cutoff?: number): Promise<({
         time: number;
     } & Record<string, number>)[]>;
     getUsage(cutoff?: number): Promise<Record<string, {

package/dist/index.js

@@ -47,13 +47,25 @@ function ms(d) {
 }
 
 // src/analytics.ts
+var import_core_analytics = require("@upstash/core-analytics");
 var Analytics = class {
-  redis;
-  prefix;
+  analytics;
+  table = "events";
   constructor(config) {
-    this.redis = config.redis;
-    this.prefix = config.prefix ?? "@upstash/ratelimit";
+    this.analytics = new import_core_analytics.Analytics({
+      redis: config.redis,
+      window: "1h",
+      prefix: config.prefix ?? "@upstash/ratelimit",
+      retention: "90d"
+    });
   }
+  /**
+   * Try to extract the geo information from the request
+   *
+   * This handles Vercel's `req.geo` and  and Cloudflare's `request.cf` properties
+   * @param req
+   * @returns
+   */
   extractGeo(req) {
     if (typeof req.geo !== "undefined") {
       return req.geo;
@@ -64,116 +76,30 @@ var Analytics = class {
     return {};
   }
   async record(event) {
-    const bucket = new Date().setUTCHours(0, 0, 0, 0).toFixed(0);
-    const key = [this.prefix, "events", bucket].join(":");
-    await this.redis.hincrby(
-      key,
-      JSON.stringify({
-        ...event,
-        time: void 0
-      }),
-      1
-    );
-  }
-  async aggregate(aggregateBy, cutoff = 0) {
-    const keys = [];
-    let cursor = 0;
-    do {
-      const [nextCursor, found] = await this.redis.scan(cursor, {
-        match: [this.prefix, "events", "*"].join(":"),
-        count: 1e3
-      });
-      cursor = nextCursor;
-      for (const key of found) {
-        const timestamp = parseInt(key.split(":").pop());
-        if (timestamp >= cutoff) {
-          keys.push(key);
-        }
-      }
-    } while (cursor !== 0);
-    const days = {};
-    await Promise.all(
-      keys.sort().map(async (key) => {
-        const fields = await this.redis.hgetall(key);
-        if (!fields) {
-          return;
-        }
-        const day = {};
-        for (const [field, count] of Object.entries(fields)) {
-          const r = JSON.parse(field);
-          for (const [k, v] of Object.entries(r)) {
-            if (k !== aggregateBy) {
-              continue;
-            }
-            if (!day[v]) {
-              day[v] = {
-                success: 0,
-                blocked: 0
-              };
-            }
-            if (r.success) {
-              day[v].success += count;
-            } else {
-              day[v].blocked += count;
-            }
-          }
-        }
-        days[key.split(":")[2]] = day;
-      })
-    );
-    return days;
+    await this.analytics.ingest(this.table, event);
   }
-  async series(aggregateBy, cutoff = 0) {
-    const keys = [];
-    let cursor = 0;
-    do {
-      const [nextCursor, found] = await this.redis.scan(cursor, {
-        match: [this.prefix, "events", "*"].join(":"),
-        count: 1e3
-      });
-      cursor = nextCursor;
-      for (const key of found) {
-        const timestamp = parseInt(key.split(":").pop());
-        if (timestamp >= cutoff) {
-          keys.push(key);
-        }
-      }
-    } while (cursor !== 0);
-    const days = await Promise.all(
-      keys.sort().map(async (key) => {
-        const fields = await this.redis.hgetall(key);
-        const day = { time: parseInt(key.split(":")[2]) };
-        if (!fields) {
-          return day;
-        }
-        for (const [field, count] of Object.entries(fields)) {
-          const r = JSON.parse(field);
-          for (const [k, v] of Object.entries(r)) {
-            console.log({ k, v });
-            if (k !== aggregateBy) {
-              continue;
-            }
-            if (!day[v]) {
-              day[v] = 0;
-            }
-            day[v] += count;
-          }
-        }
-        return day;
-      })
-    );
-    return days;
+  async series(filter, cutoff = 0) {
+    const records = await this.analytics.query(this.table, {
+      filter: [filter],
+      range: cutoff ? [cutoff] : void 0
+    });
+    return records;
   }
   async getUsage(cutoff = 0) {
-    const records = await this.aggregate("identifier", cutoff);
+    const records = await this.analytics.aggregateBy(this.table, "identifier", {
+      range: cutoff ? [cutoff] : void 0
+    });
     const usage = {};
-    for (const day of Object.values(records)) {
-      for (const [k, v] of Object.entries(day)) {
+    for (const bucket of records) {
+      for (const [k, v] of Object.entries(bucket)) {
+        if (k === "time") {
+          continue;
+        }
         if (!usage[k]) {
           usage[k] = { success: 0, blocked: 0 };
         }
-        usage[k].success += v.success;
-        usage[k].blocked += v.blocked;
+        usage[k].success += v;
+        usage[k].blocked += v;
       }
     }
     return usage;
@@ -182,6 +108,9 @@ var Analytics = class {
 
 // src/cache.ts
 var Cache = class {
+  /**
+   * Stores identifier -> reset (in milliseconds)
+   */
   cache;
   constructor(cache) {
     this.cache = cache;
@@ -236,6 +165,25 @@ var Ratelimit = class {
       this.ctx.cache = new Cache(/* @__PURE__ */ new Map());
     }
   }
+  /**
+   * Determine if a request should pass or be rejected based on the identifier and previously chosen ratelimit.
+   *
+   * Use this if you want to reject all requests that you can not handle right now.
+   *
+   * @example
+   * ```ts
+   *  const ratelimit = new Ratelimit({
+   *    redis: Redis.fromEnv(),
+   *    limiter: Ratelimit.slidingWindow(10, "10 s")
+   *  })
+   *
+   *  const { success } = await ratelimit.limit(id)
+   *  if (!success){
+   *    return "Nope"
+   *  }
+   *  return "Yes"
+   * ```
+   */
   limit = async (identifier, req) => {
     const key = [this.prefix, identifier].join(":");
     let timeoutId = null;
@@ -274,6 +222,28 @@ var Ratelimit = class {
       }
     }
   };
+  /**
+   * Block until the request may pass or timeout is reached.
+   *
+   * This method returns a promsie that resolves as soon as the request may be processed
+   * or after the timeoue has been reached.
+   *
+   * Use this if you want to delay the request until it is ready to get processed.
+   *
+   * @example
+   * ```ts
+   *  const ratelimit = new Ratelimit({
+   *    redis: Redis.fromEnv(),
+   *    limiter: Ratelimit.slidingWindow(10, "10 s")
+   *  })
+   *
+   *  const { success } = await ratelimit.blockUntilReady(id, 60_000)
+   *  if (!success){
+   *    return "Nope"
+   *  }
+   *  return "Yes"
+   * ```
+   */
   blockUntilReady = async (identifier, timeout) => {
     if (timeout <= 0) {
       throw new Error("timeout must be positive");
@@ -300,6 +270,9 @@ var Ratelimit = class {
 
 // src/single.ts
 var RegionRatelimit = class extends Ratelimit {
+  /**
+   * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
+   */
   constructor(config) {
     super({
       prefix: config.prefix,
@@ -312,6 +285,24 @@ var RegionRatelimit = class extends Ratelimit {
       ephemeralCache: config.ephemeralCache
     });
   }
+  /**
+   * Each requests inside a fixed time increases a counter.
+   * Once the counter reaches a maxmimum allowed number, all further requests are
+   * rejected.
+   *
+   * **Pro:**
+   *
+   * - Newer requests are not starved by old ones.
+   * - Low storage cost.
+   *
+   * **Con:**
+   *
+   * A burst of requests near the boundary of a window can result in a very
+   * high request rate because two windows will be filled with requests quickly.
+   *
+   * @param tokens - How many requests a user can make in each time window.
+   * @param window - A fixed timeframe
+   */
   static fixedWindow(tokens, window) {
     const windowDuration = ms(window);
     const script = `
@@ -357,6 +348,22 @@ var RegionRatelimit = class extends Ratelimit {
       };
     };
   }
+  /**
+   * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
+   * costs than `slidingLogs` and improved boundary behavior by calcualting a
+   * weighted score between two windows.
+   *
+   * **Pro:**
+   *
+   * Good performance allows this to scale to very high loads.
+   *
+   * **Con:**
+   *
+   * Nothing major.
+   *
+   * @param tokens - How many requests a user can make in each time window.
+   * @param window - The duration in which the user can max X requests.
+   */
   static slidingWindow(tokens, window) {
     const script = `
       local currentKey  = KEYS[1]           -- identifier including prefixes
@@ -422,6 +429,19 @@ var RegionRatelimit = class extends Ratelimit {
       };
     };
   }
+  /**
+   * You have a bucket filled with `{maxTokens}` tokens that refills constantly
+   * at `{refillRate}` per `{interval}`.
+   * Every request will remove one token from the bucket and if there is no
+   * token to take, the request is rejected.
+   *
+   * **Pro:**
+   *
+   * - Bursts of requests are smoothed out and you can process them at a constant
+   * rate.
+   * - Allows to set a higher initial burst limit by setting `maxTokens` higher
+   * than `refillRate`
+   */
   static tokenBucket(refillRate, interval, maxTokens) {
     const script = `
         local key         = KEYS[1]           -- identifier including prefixes
@@ -496,6 +516,30 @@ var RegionRatelimit = class extends Ratelimit {
       };
     };
   }
+  /**
+   * cachedFixedWindow first uses the local cache to decide if a request may pass and then updates
+   * it asynchronously.
+   * This is experimental and not yet recommended for production use.
+   *
+   * @experimental
+   *
+   * Each requests inside a fixed time increases a counter.
+   * Once the counter reaches a maxmimum allowed number, all further requests are
+   * rejected.
+   *
+   * **Pro:**
+   *
+   * - Newer requests are not starved by old ones.
+   * - Low storage cost.
+   *
+   * **Con:**
+   *
+   * A burst of requests near the boundary of a window can result in a very
+   * high request rate because two windows will be filled with requests quickly.
+   *
+   * @param tokens - How many requests a user can make in each time window.
+   * @param window - A fixed timeframe
+   */
   static cachedFixedWindow(tokens, window) {
     const windowDuration = ms(window);
     const script = `
@@ -558,6 +602,9 @@ function randomId() {
   return result;
 }
 var MultiRegionRatelimit = class extends Ratelimit {
+  /**
+   * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
+   */
   constructor(config) {
     super({
       prefix: config.prefix,
@@ -570,6 +617,24 @@ var MultiRegionRatelimit = class extends Ratelimit {
       }
     });
   }
+  /**
+   * Each requests inside a fixed time increases a counter.
+   * Once the counter reaches a maxmimum allowed number, all further requests are
+   * rejected.
+   *
+   * **Pro:**
+   *
+   * - Newer requests are not starved by old ones.
+   * - Low storage cost.
+   *
+   * **Con:**
+   *
+   * A burst of requests near the boundary of a window can result in a very
+   * high request rate because two windows will be filled with requests quickly.
+   *
+   * @param tokens - How many requests a user can make in each time window.
+   * @param window - A fixed timeframe
+   */
   static fixedWindow(tokens, window) {
     const windowDuration = ms(window);
     const script = `
@@ -639,6 +704,22 @@ var MultiRegionRatelimit = class extends Ratelimit {
       };
     };
   }
+  /**
+   * Combined approach of `slidingLogs` and `fixedWindow` with lower storage
+   * costs than `slidingLogs` and improved boundary behavior by calcualting a
+   * weighted score between two windows.
+   *
+   * **Pro:**
+   *
+   * Good performance allows this to scale to very high loads.
+   *
+   * **Con:**
+   *
+   * Nothing major.
+   *
+   * @param tokens - How many requests a user can make in each time window.
+   * @param window - The duration in which the user can max X requests.
+   */
   static slidingWindow(tokens, window) {
     const windowSize = ms(window);
     const script = `