@upstash/ratelimit 2.0.8 → 2.1.0

package/README.md

@@ -78,6 +78,25 @@ For more information on getting started, you can refer to [our documentation](ht
 
 See [the documentation](https://upstash.com/docs/redis/sdks/ratelimit-ts/overview) for more information details about this package.
 
+## Telemetry
+
+The SDK reports its name and version to Upstash as a header on the requests made
+by the redis client you provide, so we know which SDK versions are in use. No
+personal data, keys or identifiers are collected.
+
+You can opt out with `enableTelemetry: false`:
+
+```ts
+const ratelimit = new Ratelimit({
+  redis: Redis.fromEnv(),
+  limiter: Ratelimit.slidingWindow(10, "10 s"),
+  enableTelemetry: false,
+});
+```
+
+or by setting the `UPSTASH_DISABLE_TELEMETRY` environment variable. Disabling
+telemetry on the redis client itself also disables it here.
+
 ## Contributing
 
 ### Database

package/dist/index.d.mts

@@ -495,6 +495,17 @@ type MultiRegionRatelimitConfig = {
      * @default false
      */
     dynamicLimits?: boolean;
+    /**
+     * Enable telemetry to help us improve the SDK.
+     *
+     * The sdk name and version are sent to Upstash as a header on the requests
+     * made by the redis clients you provide.
+     *
+     * Can also be disabled with the `UPSTASH_DISABLE_TELEMETRY` env variable.
+     *
+     * @default true
+     */
+    enableTelemetry?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
@@ -652,6 +663,17 @@ type RegionRatelimitConfig = {
      * @default false
      */
     dynamicLimits?: boolean;
+    /**
+     * Enable telemetry to help us improve the SDK.
+     *
+     * The sdk name and version are sent to Upstash as a header on the requests
+     * made by the redis client you provide.
+     *
+     * Can also be disabled with the `UPSTASH_DISABLE_TELEMETRY` env variable.
+     *
+     * @default true
+     */
+    enableTelemetry?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/

package/dist/index.d.ts

@@ -495,6 +495,17 @@ type MultiRegionRatelimitConfig = {
      * @default false
      */
     dynamicLimits?: boolean;
+    /**
+     * Enable telemetry to help us improve the SDK.
+     *
+     * The sdk name and version are sent to Upstash as a header on the requests
+     * made by the redis clients you provide.
+     *
+     * Can also be disabled with the `UPSTASH_DISABLE_TELEMETRY` env variable.
+     *
+     * @default true
+     */
+    enableTelemetry?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/
@@ -652,6 +663,17 @@ type RegionRatelimitConfig = {
      * @default false
      */
     dynamicLimits?: boolean;
+    /**
+     * Enable telemetry to help us improve the SDK.
+     *
+     * The sdk name and version are sent to Upstash as a header on the requests
+     * made by the redis client you provide.
+     *
+     * Can also be disabled with the `UPSTASH_DISABLE_TELEMETRY` env variable.
+     *
+     * @default true
+     */
+    enableTelemetry?: boolean;
 };
 /**
  * Ratelimiter using serverless redis from https://upstash.com/

package/dist/index.js

@@ -179,7 +179,7 @@ var safeEval = async (ctx, script, keys, args) => {
 };
 
 // src/lua-scripts/single.ts
-var fixedWindowLimitScript = `
+var fixedWindowLimitScript = `#!lua flags=allow-key-locking
   local key           = KEYS[1]
   local dynamicLimitKey = KEYS[2]  -- optional: key for dynamic limit in redis
   local tokens        = tonumber(ARGV[1])  -- default limit
@@ -188,7 +188,7 @@ var fixedWindowLimitScript = `
 
   -- Check for dynamic limit
   local effectiveLimit = tokens
-  if dynamicLimitKey ~= "" then
+  if dynamicLimitKey and dynamicLimitKey ~= "" then
     local dynamicLimit = redis.call("GET", dynamicLimitKey)
     if dynamicLimit then
       effectiveLimit = tonumber(dynamicLimit)
@@ -204,14 +204,14 @@ var fixedWindowLimitScript = `
 
   return {r, effectiveLimit}
 `;
-var fixedWindowRemainingTokensScript = `
+var fixedWindowRemainingTokensScript = `#!lua flags=allow-key-locking
   local key = KEYS[1]
   local dynamicLimitKey = KEYS[2]  -- optional: key for dynamic limit in redis
   local tokens = tonumber(ARGV[1])  -- default limit
 
   -- Check for dynamic limit
   local effectiveLimit = tokens
-  if dynamicLimitKey ~= "" then
+  if dynamicLimitKey and dynamicLimitKey ~= "" then
     local dynamicLimit = redis.call("GET", dynamicLimitKey)
     if dynamicLimit then
       effectiveLimit = tonumber(dynamicLimit)
@@ -226,7 +226,7 @@ var fixedWindowRemainingTokensScript = `
   
   return {effectiveLimit - usedTokens, effectiveLimit}
 `;
-var slidingWindowLimitScript = `
+var slidingWindowLimitScript = `#!lua flags=allow-key-locking
   local currentKey  = KEYS[1]           -- identifier including prefixes
   local previousKey = KEYS[2]           -- key of the previous bucket
   local dynamicLimitKey = KEYS[3]       -- optional: key for dynamic limit in redis
@@ -237,7 +237,7 @@ var slidingWindowLimitScript = `
 
   -- Check for dynamic limit
   local effectiveLimit = tokens
-  if dynamicLimitKey ~= "" then
+  if dynamicLimitKey and dynamicLimitKey ~= "" then
     local dynamicLimit = redis.call("GET", dynamicLimitKey)
     if dynamicLimit then
       effectiveLimit = tonumber(dynamicLimit)
@@ -270,7 +270,7 @@ var slidingWindowLimitScript = `
   end
   return {effectiveLimit - ( newValue + requestsInPreviousWindow ), effectiveLimit}
 `;
-var slidingWindowRemainingTokensScript = `
+var slidingWindowRemainingTokensScript = `#!lua flags=allow-key-locking
   local currentKey  = KEYS[1]           -- identifier including prefixes
   local previousKey = KEYS[2]           -- key of the previous bucket
   local dynamicLimitKey = KEYS[3]       -- optional: key for dynamic limit in redis
@@ -280,7 +280,7 @@ var slidingWindowRemainingTokensScript = `
 
   -- Check for dynamic limit
   local effectiveLimit = tokens
-  if dynamicLimitKey ~= "" then
+  if dynamicLimitKey and dynamicLimitKey ~= "" then
     local dynamicLimit = redis.call("GET", dynamicLimitKey)
     if dynamicLimit then
       effectiveLimit = tonumber(dynamicLimit)
@@ -304,7 +304,7 @@ var slidingWindowRemainingTokensScript = `
   local usedTokens = requestsInPreviousWindow + requestsInCurrentWindow
   return {effectiveLimit - usedTokens, effectiveLimit}
 `;
-var tokenBucketLimitScript = `
+var tokenBucketLimitScript = `#!lua flags=allow-key-locking
   local key         = KEYS[1]           -- identifier including prefixes
   local dynamicLimitKey = KEYS[2]       -- optional: key for dynamic limit in redis
   local maxTokens   = tonumber(ARGV[1]) -- default maximum number of tokens
@@ -315,7 +315,7 @@ var tokenBucketLimitScript = `
 
   -- Check for dynamic limit
   local effectiveLimit = maxTokens
-  if dynamicLimitKey ~= "" then
+  if dynamicLimitKey and dynamicLimitKey ~= "" then
     local dynamicLimit = redis.call("GET", dynamicLimitKey)
     if dynamicLimit then
       effectiveLimit = tonumber(dynamicLimit)
@@ -358,14 +358,14 @@ var tokenBucketLimitScript = `
   return {remaining, refilledAt + interval, effectiveLimit}
 `;
 var tokenBucketIdentifierNotFound = -1;
-var tokenBucketRemainingTokensScript = `
+var tokenBucketRemainingTokensScript = `#!lua flags=allow-key-locking
   local key         = KEYS[1]
   local dynamicLimitKey = KEYS[2]       -- optional: key for dynamic limit in redis
   local maxTokens   = tonumber(ARGV[1]) -- default maximum number of tokens
 
   -- Check for dynamic limit
   local effectiveLimit = maxTokens
-  if dynamicLimitKey ~= "" then
+  if dynamicLimitKey and dynamicLimitKey ~= "" then
     local dynamicLimit = redis.call("GET", dynamicLimitKey)
     if dynamicLimit then
       effectiveLimit = tonumber(dynamicLimit)
@@ -380,7 +380,7 @@ var tokenBucketRemainingTokensScript = `
         
   return {tonumber(bucket[2]), tonumber(bucket[1]), effectiveLimit}
 `;
-var cachedFixedWindowLimitScript = `
+var cachedFixedWindowLimitScript = `#!lua flags=allow-key-locking
   local key     = KEYS[1]
   local window  = ARGV[1]
   local incrementBy   = ARGV[2] -- increment rate per request at a given value, default is 1
@@ -394,7 +394,7 @@ var cachedFixedWindowLimitScript = `
       
   return r
 `;
-var cachedFixedWindowRemainingTokenScript = `
+var cachedFixedWindowRemainingTokenScript = `#!lua flags=allow-key-locking
   local key = KEYS[1]
   local tokens = 0
 
@@ -406,7 +406,7 @@ var cachedFixedWindowRemainingTokenScript = `
 `;
 
 // src/lua-scripts/multi.ts
-var fixedWindowLimitScript2 = `
+var fixedWindowLimitScript2 = `#!lua flags=allow-key-locking
 	local key           = KEYS[1]
 	local id            = ARGV[1]
 	local window        = ARGV[2]
@@ -422,7 +422,7 @@ var fixedWindowLimitScript2 = `
 
 	return fields
 `;
-var fixedWindowRemainingTokensScript2 = `
+var fixedWindowRemainingTokensScript2 = `#!lua flags=allow-key-locking
       local key = KEYS[1]
       local tokens = 0
 
@@ -430,7 +430,7 @@ var fixedWindowRemainingTokensScript2 = `
 
       return fields
     `;
-var slidingWindowLimitScript2 = `
+var slidingWindowLimitScript2 = `#!lua flags=allow-key-locking
 	local currentKey    = KEYS[1]           -- identifier including prefixes
 	local previousKey   = KEYS[2]           -- key of the previous bucket
 	local tokens        = tonumber(ARGV[1]) -- tokens per window
@@ -467,7 +467,7 @@ var slidingWindowLimitScript2 = `
 	end
 	return {currentFields, previousFields, true}
 `;
-var slidingWindowRemainingTokensScript2 = `
+var slidingWindowRemainingTokensScript2 = `#!lua flags=allow-key-locking
 	local currentKey    = KEYS[1]           -- identifier including prefixes
 	local previousKey   = KEYS[2]           -- key of the previous bucket
 	local now         	= ARGV[1]           -- current timestamp in milliseconds
@@ -522,41 +522,41 @@ var SCRIPTS = {
     fixedWindow: {
       limit: {
         script: fixedWindowLimitScript,
-        hash: "472e55443b62f60d0991028456c57815a387066d"
+        hash: "b2efc02798c8e9b471a10f9b1d5745db89923ff3"
       },
       getRemaining: {
         script: fixedWindowRemainingTokensScript,
-        hash: "40515c9dd0a08f8584f5f9b593935f6a87c1c1c3"
+        hash: "823cb2a5a902d69681244f5e28e5ebb8f2a89edd"
       }
     },
     slidingWindow: {
       limit: {
         script: slidingWindowLimitScript,
-        hash: "977fb636fb5ceb7e98a96d1b3a1272ba018efdae"
+        hash: "74740bb3d7792848093cdef586b6b6037c455fd6"
       },
       getRemaining: {
         script: slidingWindowRemainingTokensScript,
-        hash: "ee3a3265fad822f83acad23f8a1e2f5c0b156b03"
+        hash: "7ca36169e0fc9caedd81b4eef8e99854c157f9b5"
       }
     },
     tokenBucket: {
       limit: {
         script: tokenBucketLimitScript,
-        hash: "b35c5bc0b7fdae7dd0573d4529911cabaf9d1d89"
+        hash: "a9873a8026b509e99a49a0e5a2049756c693c384"
       },
       getRemaining: {
         script: tokenBucketRemainingTokensScript,
-        hash: "deb03663e8af5a968deee895dd081be553d2611b"
+        hash: "40daf4a441df736f5c99f8b77bbe176c909e5de4"
       }
     },
     cachedFixedWindow: {
       limit: {
         script: cachedFixedWindowLimitScript,
-        hash: "c26b12703dd137939b9a69a3a9b18e906a2d940f"
+        hash: "1861a700bafe96c833a483af6b1c28a8897cfdb0"
       },
       getRemaining: {
         script: cachedFixedWindowRemainingTokenScript,
-        hash: "8e8f222ccae68b595ee6e3f3bf2199629a62b91a"
+        hash: "eb82f0e853d2fc9a236fa9bfbe704fda6ac2fc36"
       }
     }
   },
@@ -564,21 +564,21 @@ var SCRIPTS = {
     fixedWindow: {
       limit: {
         script: fixedWindowLimitScript2,
-        hash: "a8c14f3835aa87bd70e5e2116081b81664abcf5c"
+        hash: "e04b753a75909b7f99aae4c04cf8869a8de02a9e"
       },
       getRemaining: {
         script: fixedWindowRemainingTokensScript2,
-        hash: "8ab8322d0ed5fe5ac8eb08f0c2e4557f1b4816fd"
+        hash: "e066c8ce3eaca142b0894ad1541e0a58c9924819"
       }
     },
     slidingWindow: {
       limit: {
         script: slidingWindowLimitScript2,
-        hash: "1e7ca8dcd2d600a6d0124a67a57ea225ed62921b"
+        hash: "aeb4d8f381e8dafc8e69041baae1324d254ded44"
       },
       getRemaining: {
         script: slidingWindowRemainingTokensScript2,
-        hash: "558c9306b7ec54abb50747fe0b17e5d44bd24868"
+        hash: "87828c1088f6a8d1f512a434ea330189982a1c0a"
       }
     }
   }
@@ -1059,6 +1059,27 @@ var Ratelimit = class {
   };
 };
 
+// src/version.ts
+var VERSION = "2.1.0";
+
+// src/telemetry.ts
+var taggedClients = /* @__PURE__ */ new WeakSet();
+var getSafeEnv = () => typeof process === "object" && process && typeof process.env === "object" ? process.env : {};
+var addTelemetry = (redis, enableTelemetry = true) => {
+  if (!enableTelemetry || getSafeEnv().UPSTASH_DISABLE_TELEMETRY)
+    return;
+  if (!redis || typeof redis !== "object")
+    return;
+  if (taggedClients.has(redis))
+    return;
+  taggedClients.add(redis);
+  try {
+    const client = redis;
+    client.addTelemetry?.({ sdk: `@upstash/ratelimit@${VERSION}` });
+  } catch {
+  }
+};
+
 // src/multi.ts
 function randomId() {
   let result = "";
@@ -1088,6 +1109,9 @@ var MultiRegionRatelimit = class extends Ratelimit {
         cache: config.ephemeralCache ? new Cache(config.ephemeralCache) : void 0
       }
     });
+    for (const redis of config.redis) {
+      addTelemetry(redis, config.enableTelemetry);
+    }
     if (config.dynamicLimits) {
       console.warn(
         "Warning: Dynamic limits are not yet supported for multi-region rate limiters. The dynamicLimits option will be ignored."
@@ -1458,6 +1482,7 @@ var RegionRatelimit = class extends Ratelimit {
       denyListThreshold: config.denyListThreshold,
       dynamicLimits: config.dynamicLimits
     });
+    addTelemetry(config.redis, config.enableTelemetry);
   }
   /**
    * Each request inside a fixed time increases a counter.
@@ -1497,11 +1522,11 @@ var RegionRatelimit = class extends Ratelimit {
             };
           }
         }
-        const dynamicLimitKey = ctx.dynamicLimits ? `${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}` : "";
+        const dynamicLimitKeys = ctx.dynamicLimits ? [`${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}`] : [];
         const [usedTokensAfterUpdate, effectiveLimit] = await safeEval(
           ctx,
           SCRIPTS.singleRegion.fixedWindow.limit,
-          [key, dynamicLimitKey],
+          [key, ...dynamicLimitKeys],
           [tokens, windowDuration, incrementBy]
         );
         const success = usedTokensAfterUpdate <= effectiveLimit;
@@ -1525,11 +1550,11 @@ var RegionRatelimit = class extends Ratelimit {
       async getRemaining(ctx, identifier) {
         const bucket = Math.floor(Date.now() / windowDuration);
         const key = [identifier, bucket].join(":");
-        const dynamicLimitKey = ctx.dynamicLimits ? `${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}` : "";
+        const dynamicLimitKeys = ctx.dynamicLimits ? [`${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}`] : [];
         const [remaining, effectiveLimit] = await safeEval(
           ctx,
           SCRIPTS.singleRegion.fixedWindow.getRemaining,
-          [key, dynamicLimitKey],
+          [key, ...dynamicLimitKeys],
           [tokens]
         );
         return {
@@ -1591,11 +1616,11 @@ var RegionRatelimit = class extends Ratelimit {
             };
           }
         }
-        const dynamicLimitKey = ctx.dynamicLimits ? `${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}` : "";
+        const dynamicLimitKeys = ctx.dynamicLimits ? [`${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}`] : [];
         const [remainingTokens, effectiveLimit] = await safeEval(
           ctx,
           SCRIPTS.singleRegion.slidingWindow.limit,
-          [currentKey, previousKey, dynamicLimitKey],
+          [currentKey, previousKey, ...dynamicLimitKeys],
           [tokens, now, windowSize, incrementBy]
         );
         const success = remainingTokens >= 0;
@@ -1621,11 +1646,11 @@ var RegionRatelimit = class extends Ratelimit {
         const currentKey = [identifier, currentWindow].join(":");
         const previousWindow = currentWindow - 1;
         const previousKey = [identifier, previousWindow].join(":");
-        const dynamicLimitKey = ctx.dynamicLimits ? `${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}` : "";
+        const dynamicLimitKeys = ctx.dynamicLimits ? [`${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}`] : [];
         const [remaining, effectiveLimit] = await safeEval(
           ctx,
           SCRIPTS.singleRegion.slidingWindow.getRemaining,
-          [currentKey, previousKey, dynamicLimitKey],
+          [currentKey, previousKey, ...dynamicLimitKeys],
           [tokens, now, windowSize]
         );
         return {
@@ -1680,11 +1705,11 @@ var RegionRatelimit = class extends Ratelimit {
             };
           }
         }
-        const dynamicLimitKey = ctx.dynamicLimits ? `${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}` : "";
+        const dynamicLimitKeys = ctx.dynamicLimits ? [`${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}`] : [];
         const [remaining, reset, effectiveLimit] = await safeEval(
           ctx,
           SCRIPTS.singleRegion.tokenBucket.limit,
-          [identifier, dynamicLimitKey],
+          [identifier, ...dynamicLimitKeys],
           [maxTokens, intervalDuration, refillRate, now, incrementBy]
         );
         const success = remaining >= 0;
@@ -1704,11 +1729,11 @@ var RegionRatelimit = class extends Ratelimit {
         };
       },
       async getRemaining(ctx, identifier) {
-        const dynamicLimitKey = ctx.dynamicLimits ? `${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}` : "";
+        const dynamicLimitKeys = ctx.dynamicLimits ? [`${ctx.prefix}${DYNAMIC_LIMIT_KEY_SUFFIX}`] : [];
         const [remainingTokens, refilledAt, effectiveLimit] = await safeEval(
           ctx,
           SCRIPTS.singleRegion.tokenBucket.getRemaining,
-          [identifier, dynamicLimitKey],
+          [identifier, ...dynamicLimitKeys],
           [maxTokens]
         );
         const freshRefillAt = Date.now() + intervalDuration;