@upstash/ratelimit 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 Upstash, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,239 @@
+# Upstash Redis
+
+An HTTP/REST based Redis client built on top of Upstash REST API.
+[Upstash REST API](https://docs.upstash.com/features/restapi).
+
+[![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)
+![npm bundle size](https://img.shields.io/bundlephobia/minzip/@upstash/ratelimit)
+
+It is the only connectionless (HTTP based) ratelimiter and designed for:
+
+- Serverless functions (AWS Lambda ...)
+- Cloudflare Workers
+- Fastly Compute@Edge (see
+- Next.js, Jamstack ...
+- Client side web/mobile applications
+- WebAssembly
+- and other environments where HTTP is preferred over TCP.
+
+## Quick Start
+
+### Install
+
+#### npm
+
+```bash
+npm install @upstash/ratelimit
+```
+
+#### Deno
+
+```ts
+import { Redis } from "https://deno.land/x/upstash_ratelimit/mod.ts";
+```
+
+### Create database
+
+Create a new redis database on [upstash](https://console.upstash.com/)
+
+### Use it
+
+See [here](https://github.com/upstash/upstash-redis#quick-start) for
+documentation on how to create a redis instance.
+
+```ts
+import { Ratelimit } from "@upstash/ratelimit"; // for deno: see above
+import { Redis } from "@upstash/redis";
+
+// Create a new ratelimiter, that allows 10 requests per 10 seconds
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+});
+
+// Use a constant string to limit all requests with a single ratelimit
+// Or use a userID, apiKey or ip address for individual limits.
+const identifier = "api";
+const { success } = await ratelimit.limit(identifier);
+
+if (!success) {
+  return "Unable to process at this time";
+}
+doExpensiveCalculation();
+return "Here you go!";
+```
+
+[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;
+};
+```
+
+### Block until ready
+
+In case you don't want to reject a request immediately but wait until it can be
+processed, we also provide
+`ratelimit.blockUntilReady(identifier: stirng, timeout: number): Promise<RatelimitResponse>`
+
+It is very similar to the `limit` method and takes an identifier and returns the
+same response. However if the current limit has already been exceeded, it will
+automatically wait until the next window starts and will try again. Setting the
+timeout parameter (in milliseconds) will cause the returned Promise to resolve
+in a finite amount of time.
+
+```ts
+// Create a new ratelimiter, that allows 10 requests per 10 seconds
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+});
+
+// `blockUntilReady` returns a promise that resolves as soon as the request is allowed to be processed, or after 30 seconds
+const { success } = await ratelimit.blockUntilReady("id", 30_000);
+
+if (!success) {
+  return "Unable to process, even after 30 seconds";
+}
+doExpensiveCalculation();
+return "Here you go!";
+```
+
+## Ratelimiting algorithms
+
+We provide different algorithms to use out of the box. Each has pros and cons.
+
+### Fixed Window
+
+This algorithm divides time into fixed durations/windows. For example each
+window is 10 seconds long. When a new request comes in, the current time is used
+to determine the window and a counter is increased. If the counter is larger
+than the set limit, the request is rejected.
+
+#### Pros:
+
+- Very cheap in terms of data size and computation
+- Newer requests are not starved due to a high burst in the past
+
+#### Cons:
+
+- Can cause high bursts at the window boundaries to leak through
+- Causes request stampedes if many users are trying to access your server,
+  whenever a new window begins
+
+#### Usage:
+
+Create a new ratelimiter, that allows 10 requests per 10 seconds.
+
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.fixedWindow(10, "10 s"),
+});
+```
+
+### Sliding Window
+
+Builds on top of fixed window but instead of a fixed window, we use a rolling
+window. Take this example: We have a rate limit of 10 requests per 1 minute. We
+dividie time into 1 minute slices, just like in the fixed window algorithm.
+Window 1 will be from 00:00:00 to 00:01:00 (HH:MM:SS). Let's assume it is
+currently 00:01:15 and we have received 4 requests in the first window and 5
+requests so far in the current window. The approximation to determine if the
+request should pass works like this:
+
+```ts
+limit = 10
+
+// 4 request from the old window, weighted + requests in current window
+rate = 4 * ((60 - 15) / 60) + 5 = 8
+
+return rate < limit // True means we should allow the request
+```
+
+#### Pros:
+
+- Solves the issue near boundary from fixed window.
+
+#### Cons:
+
+- More expensive in terms of storage and computation
+- Is only an approximation, because it assumes a uniform request flow in the
+  previous window, but this is fine in most cases
+
+#### Usage:
+
+Create a new ratelimiter, that allows 10 requests per 10 seconds.
+
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+});
+```
+
+### Token Bucket
+
+Consider 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.
+
+#### Pros:
+
+- 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`
+
+#### Cons:
+
+- Expensive in terms of computation
+
+#### Usage:
+
+Create a new bucket, that refills 5 tokens every 10 seconds and has a maximum
+size of 10.
+
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.tokenBucket(5, "10 s", 10),
+});
+```
+
+## Contributing
+
+### [Install Deno](https://deno.land/#installation)
+
+### Database
+
+Create a new redis database on [upstash](https://console.upstash.com/) and copy
+the url and token.
+
+### Running tests
+
+```sh
+UPSTASH_REDIS_REST_URL=".." UPSTASH_REDIS_REST_TOKEN=".." deno test -A
+```

package/esm/duration.js

@@ -0,0 +1,21 @@
+/**
+ * Convert a human readable duration to milliseconds
+ */
+export function ms(d) {
+    const [timeString, duration] = d.split(" ");
+    const time = parseFloat(timeString);
+    switch (duration) {
+        case "ms":
+            return time;
+        case "s":
+            return time * 1000;
+        case "m":
+            return time * 1000 * 60;
+        case "h":
+            return time * 1000 * 60 * 60;
+        case "d":
+            return time * 1000 * 60 * 60 * 24;
+        default:
+            throw new Error(`Unable to parse window size: ${d}`);
+    }
+}

package/esm/mod.js

@@ -0,0 +1,2 @@
+export * from "./ratelimiter.js";
+export * from "./types.js";

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/ratelimiter.js

@@ -0,0 +1,384 @@
+import { ms } from "./duration.js";
+/**
+ * Ratelimiter using serverless redis from https://upstash.com/
+ *
+ * @example
+ * ```ts
+ * const { limit } = new Ratelimit({
+ *    redis: Redis.fromEnv(),
+ *    limiter: Ratelimit.slidingWindow(
+ *      "30 m", // interval of 30 minutes
+ *      10,     // Allow 10 requests per window of 30 minutes
+ *    )
+ * })
+ *
+ * ```
+ */
+export class Ratelimit {
+    /**
+     * Create a new Ratelimit instance by providing a `@upstash/redis` instance and the algorithn of your choice.
+     */
+    constructor(config) {
+        Object.defineProperty(this, "redis", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "limiter", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "prefix", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /**
+         * 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"
+         * ```
+         */
+        Object.defineProperty(this, "limit", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: async (identifier) => {
+                const key = [this.prefix, identifier].join(":");
+                return await this.limiter({ redis: this.redis }, key);
+            }
+        });
+        /**
+         * 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"
+         * ```
+         */
+        Object.defineProperty(this, "blockUntilReady", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: async (
+            /**
+             * An identifier per user or api.
+             * Choose a userID, or api token, or ip address.
+             *
+             * If you want to globally limit your api, you can set a constant string.
+             */
+            identifier, 
+            /**
+             * Maximum duration to wait in milliseconds.
+             * After this time the request will be denied.
+             */
+            timeout) => {
+                if (timeout <= 0) {
+                    throw new Error("timeout must be positive");
+                }
+                let res;
+                const deadline = Date.now() + timeout;
+                while (true) {
+                    res = await this.limit(identifier);
+                    if (res.success) {
+                        break;
+                    }
+                    if (res.reset === 0) {
+                        throw new Error("This should not happen");
+                    }
+                    const wait = Math.min(res.reset, deadline) - Date.now();
+                    await new Promise((r) => setTimeout(r, wait));
+                    if (Date.now() > deadline) {
+                        break;
+                    }
+                }
+                return res;
+            }
+        });
+        this.redis = config.redis;
+        this.limiter = config.limiter;
+        this.prefix = config.prefix ?? "@upstash/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(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window) {
+        const windowDuration = ms(window);
+        const script = `
+    local key     = KEYS[1]
+    local window  = ARGV[1]
+    
+    local r = redis.call("INCR", key)
+    if r == 1 then 
+    -- The first time this key is set, the value will be 1.
+    -- So we only need the expire command once
+    redis.call("PEXPIRE", key, window)
+    end
+    
+    return r
+    `;
+        return async function (ctx, identifier) {
+            const bucket = Math.floor(Date.now() / windowDuration);
+            const key = [identifier, bucket].join(":");
+            const usedTokensAfterUpdate = (await ctx.redis.eval(script, [key], [windowDuration]));
+            return {
+                success: usedTokensAfterUpdate <= tokens,
+                limit: tokens,
+                remaining: tokens - usedTokensAfterUpdate,
+                reset: (bucket + 1) * windowDuration,
+            };
+        };
+    }
+    // /**
+    //  * For each request all past requests in the last `{window}` are summed up and
+    //  * if they exceed `{tokens}`, the request will be rejected.
+    //  *
+    //  * **Pro:**
+    //  *
+    //  * Does not have the problem of `fixedWindow` at the window boundaries.
+    //  *
+    //  * **Con:**
+    //  *
+    //  * More expensive to store and compute, which makes this unsuitable for apis
+    //  * with very high traffic.
+    //  *
+    //  * @param window - The duration in which the user can max X requests.
+    //  * @param tokens - How many requests a user can make in each time window.
+    //  */
+    // static slidingLogs(window: Duration, tokens: number): Ratelimiter {
+    //   const script = `
+    //   local key         = KEYS[1] -- identifier including prefixes
+    //   local windowStart = ARGV[1] -- timestamp of window start
+    //   local windowEnd   = ARGV[2] -- timestamp of window end
+    //   local tokens      = ARGV[3] -- tokens per window
+    //   local now         = ARGV[4] -- current timestamp
+    //   local count = redis.call("ZCOUNT", key, windowStart, windowEnd)
+    //   if count < tonumber(tokens) then
+    //     -- Log the current request
+    //     redis.call("ZADD", key, now, now)
+    //     -- Remove all previous requests that are outside the window
+    //     redis.call("ZREMRANGEBYSCORE", key, "-inf", windowStart - 1)
+    //   end
+    //   return count
+    //   `;
+    //   return async function (ctx: Context, identifier: string) {
+    //     const windowEnd = Date.now();
+    //     const windowStart = windowEnd - ms(window);
+    //     const count = (await ctx.redis.eval(
+    //       script,
+    //       [identifier],
+    //       [windowStart, windowEnd, tokens, Date.now()]
+    //     )) as number;
+    //     return {
+    //       success: count < tokens,
+    //       limit: tokens,
+    //       remaining: Math.max(0, tokens - count - 1),
+    //       reset: windowEnd,
+    //     };
+    //   };
+    // }
+    /**
+     * 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(
+    /**
+     * How many requests are allowed per window.
+     */
+    tokens, 
+    /**
+     * The duration in which `tokens` requests are allowed.
+     */
+    window) {
+        const script = `
+      local currentKey  = KEYS[1]           -- identifier including prefixes
+      local previousKey = KEYS[2]           -- key of the previous bucket
+      local tokens      = tonumber(ARGV[1]) -- tokens per window
+      local now         = ARGV[2]           -- current timestamp in milliseconds
+      local window      = ARGV[3]           -- interval in milliseconds
+
+      local requestsInCurrentWindow = redis.call("GET", currentKey)
+      if requestsInCurrentWindow == false then
+        requestsInCurrentWindow = 0
+      end
+
+
+      local requestsInPreviousWindow = redis.call("GET", previousKey)
+      if requestsInPreviousWindow == false then
+        requestsInPreviousWindow = 0
+      end
+      local percentageInCurrent = ( now % window) / window
+      if requestsInPreviousWindow * ( 1 - percentageInCurrent ) + requestsInCurrentWindow >= tokens then
+        return 0
+      end
+
+      local newValue = redis.call("INCR", currentKey)
+      if newValue == 1 then 
+        -- The first time this key is set, the value will be 1.
+        -- So we only need the expire command once
+        redis.call("PEXPIRE", currentKey, window * 2 + 1000) -- Enough time to overlap with a new window + 1 second
+      end
+      return tokens - newValue
+      `;
+        const windowSize = ms(window);
+        return async function (ctx, identifier) {
+            const now = Date.now();
+            const currentWindow = Math.floor(now / windowSize);
+            const currentKey = [identifier, currentWindow].join(":");
+            const previousWindow = currentWindow - windowSize;
+            const previousKey = [identifier, previousWindow].join(":");
+            const remaining = (await ctx.redis.eval(script, [currentKey, previousKey], [tokens, now, windowSize]));
+            return {
+                success: remaining > 0,
+                limit: tokens,
+                remaining,
+                reset: (currentWindow + 1) * windowSize,
+            };
+        };
+    }
+    /**
+     * 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`
+     *
+     * **Usage of Upstash Redis requests:**
+     */
+    static tokenBucket(
+    /**
+     * How many tokens are refilled per `interval`
+     *
+     * An interval of `10s` and refillRate of 5 will cause a new token to be added every 2 seconds.
+     */
+    refillRate, 
+    /**
+     * The interval for the `refillRate`
+     */
+    interval, 
+    /**
+     * Maximum number of tokens.
+     * A newly created bucket starts with this many tokens.
+     * Useful to allow higher burst limits.
+     */
+    maxTokens) {
+        const script = `
+        local key         = KEYS[1]           -- identifier including prefixes
+        local maxTokens   = tonumber(ARGV[1]) -- maximum number of tokens
+        local interval    = tonumber(ARGV[2]) -- size of the window in milliseconds
+        local refillRate  = tonumber(ARGV[3]) -- how many tokens are refilled after each interval
+        local now         = tonumber(ARGV[4]) -- current timestamp in milliseconds
+        local remaining   = 0
+        
+        local bucket = redis.call("HMGET", key, "updatedAt", "tokens")
+        
+        if bucket[1] == false then
+          -- The bucket does not exist yet, so we create it and add a ttl.
+          remaining = maxTokens - 1
+          
+          redis.call("HMSET", key, "updatedAt", now, "tokens", remaining)
+          redis.call("PEXPIRE", key, interval)
+  
+          return {remaining, now + interval}
+        end
+
+        -- The bucket does exist
+  
+        local updatedAt = tonumber(bucket[1])
+        local tokens = tonumber(bucket[2])
+  
+        if now >= updatedAt + interval then
+          remaining = math.min(maxTokens, tokens + refillRate) - 1
+          
+          redis.call("HMSET", key, "updatedAt", now, "tokens", remaining)
+          return {remaining, now + interval}
+        end
+  
+        if tokens > 0 then
+          remaining = tokens - 1
+          redis.call("HMSET", key, "updatedAt", now, "tokens", remaining)
+        end
+  
+        return {remaining, updatedAt + interval}
+       `;
+        const intervalDuration = ms(interval);
+        return async function (ctx, identifier) {
+            const now = Date.now();
+            const key = [identifier, Math.floor(now / intervalDuration)].join(":");
+            const [remaining, reset] = (await ctx.redis.eval(script, [key], [maxTokens, intervalDuration, refillRate, now]));
+            return { success: remaining > 0, limit: maxTokens, remaining, reset };
+        };
+    }
+}

package/esm/types.js

@@ -0,0 +1 @@
+export {};