feat: add increment option to createRateLimit

README.md

@@ -517,6 +517,35 @@ If `isAllowed` is `false` the object also contains these additional properties:
 - `isExceeded`: `true` if the limit was exceeded.
 - `isBanned`: `true` if the request was banned according to the `ban` option.
 
+The limiter function accepts an optional second argument `{ increment?: boolean }`. The `increment` flag defaults to `true`, so omitting the argument keeps the original behavior (the request is consumed). When `increment` is `false`, the current rate limit status is returned **without consuming a request**. This is useful when a limit should only be enforced on certain outcomes (e.g. failed login attempts) while still checking the status before processing.
+
+```js
+const checkRateLimit = fastify.createRateLimit({ max: 5, timeWindow: '1 minute' });
+
+fastify.post('/login', async (request, reply) => {
+  // Peek at the current status without consuming a request
+  const status = await checkRateLimit(request, { increment: false });
+  if (status.isExceeded) {
+    return reply.code(429).send({ error: 'Too many attempts' });
+  }
+
+  const success = await tryLogin(request.body);
+  if (!success) {
+    // Only consume a request when the login fails
+    await checkRateLimit(request);
+    return reply.code(401).send({ error: 'Invalid credentials' });
+  }
+
+  return { ok: true };
+});
+```
+
+A few things to keep in mind when using `{ increment: false }`:
+
+- **It is a non-mutating snapshot.** A peek never increments the counter, resets the window, or advances the `ban`/`continueExceeding`/`exponentialBackoff` side effects that a real request triggers. The returned `isExceeded`/`isBanned` therefore reflect the *current* counters, but a peek will not, by itself, escalate a ban or extend a backoff window.
+- **`ttl` reflects the store's current window.** With the Redis store, `ttl` is the raw server `PTTL` (the same value `incr` reports), so it can exceed the configured `timeWindow` when `continueExceeding`/`exponentialBackoff` has extended it.
+- **Custom stores must implement `read`.** The flag relies on a non-mutating `read(ip, cb, timeWindow, max)` method, which mirrors the `incr` signature. The built-in local and Redis stores provide it; a custom store that does not will throw a clear error when called with `{ increment: false }`.
+
 ### Examples of Custom Store
 
 These examples show an overview of the `store` feature and you should take inspiration from it and tweak as you need:

index.js

@@ -128,7 +128,7 @@ async function fastifyRateLimit (fastify, settings) {
   if (!fastify.hasDecorator('createRateLimit')) {
     fastify.decorate('createRateLimit', (options) => {
       const args = createLimiterArgs(pluginComponent, globalParams, options)
-      return (req) => applyRateLimit.apply(this, args.concat(req))
+      return (req, callOptions) => applyRateLimit.apply(this, args.concat(req, callOptions))
     })
   }
 
@@ -210,7 +210,7 @@ function addRouteRateHook (pluginComponent, params, routeOptions) {
   }
 }
 
-async function applyRateLimit (pluginComponent, params, req) {
+async function applyRateLimit (pluginComponent, params, req, callOptions) {
   const { store } = pluginComponent
 
   // Retrieve the key from the generator (the global one or the one defined in the endpoint)
@@ -244,10 +244,18 @@ async function applyRateLimit (pluginComponent, params, req) {
   let ttl = 0
   let ttlInSeconds = 0
 
-  // We increment the rate limit for the current request
+  const storeMethod = callOptions?.increment === false ? 'read' : 'incr'
+
+  // `{ increment: false }` requires the store to implement a non-mutating
+  // `read` method. Custom stores may not, so fail fast with a clear message
+  // instead of a cryptic "store[storeMethod] is not a function" TypeError.
+  if (storeMethod === 'read' && typeof store.read !== 'function') {
+    throw new Error('The configured rate-limit store does not implement a `read` method, which is required to use `{ increment: false }`')
+  }
+
   try {
     const res = await new Promise((resolve, reject) => {
-      store.incr(key, (err, res) => {
+      store[storeMethod](key, (err, res) => {
         err ? reject(err) : resolve(res)
       }, timeWindow, max)
     })

store/LocalStore.js

@@ -43,6 +43,39 @@ LocalStore.prototype.incr = function (ip, cb, timeWindow, max) {
   cb(null, current)
 }
 
+/**
+ * Read the current rate-limit state for `ip` without mutating it.
+ *
+ * Stores expose `read` with the same argument contract as `incr`
+ * (`ip, cb, timeWindow, max`) so the two are interchangeable; an
+ * implementation may ignore the arguments it does not need (`max` here).
+ *
+ * `read` is a non-mutating snapshot: it never increments the counter, resets
+ * the window, or advances the `continueExceeding`/`exponentialBackoff`/`ban`
+ * side effects that `incr` applies. It mirrors `incr`'s window-expiry
+ * detection, so a peek and a real request agree on whether the window is
+ * still active.
+ *
+ * @param {string} ip
+ * @param {(err: Error | null, res: { current: number, ttl: number }) => void} cb
+ * @param {number} timeWindow
+ * @param {number} [max]
+ */
+LocalStore.prototype.read = function (ip, cb, timeWindow, max) {
+  const nowInMs = Date.now()
+  const current = this.lru.get(ip)
+
+  if (!current || current.iterationStartMs + timeWindow <= nowInMs) {
+    // Item doesn't exist or has expired: report a clean state without mutating
+    cb(null, { current: 0, ttl: 0 })
+    return
+  }
+
+  // Item is alive: report the current state without mutating
+  const ttl = timeWindow - (nowInMs - current.iterationStartMs)
+  cb(null, { current: current.current, ttl })
+}
+
 LocalStore.prototype.child = function (routeOptions) {
   return new LocalStore(routeOptions.continueExceeding, routeOptions.exponentialBackoff, routeOptions.cache)
 }

store/RedisStore.js

@@ -31,6 +31,30 @@ const lua = `
   return {current, timeWindow}
 `
 
+const luaRead = `
+  -- Key to operate on
+  local key = KEYS[1]
+
+  -- Read the counter without mutating it
+  local current = redis.call('GET', key)
+
+  -- A missing key returns false from redis.call (and nil from redis.pcall);
+  -- "not current" covers both, so the clean-state branch is robust either way.
+  if not current then
+    -- Key doesn't exist: clean state
+    return {0, 0}
+  end
+
+  -- Read the remaining TTL in milliseconds
+  local ttl = redis.call('PTTL', key)
+  if ttl < 0 then
+    -- -2 (no key) or -1 (no expiry): report no active window
+    ttl = 0
+  end
+
+  return {tonumber(current), ttl}
+`
+
 function RedisStore (continueExceeding, exponentialBackoff, redis, key = 'fastify-rate-limit-') {
   this.continueExceeding = continueExceeding
   this.exponentialBackoff = exponentialBackoff
@@ -43,6 +67,13 @@ function RedisStore (continueExceeding, exponentialBackoff, redis, key = 'fastif
       lua
     })
   }
+
+  if (!this.redis.rateLimitRead) {
+    this.redis.defineCommand('rateLimitRead', {
+      numberOfKeys: 1,
+      lua: luaRead
+    })
+  }
 }
 
 RedisStore.prototype.incr = function (ip, cb, timeWindow, max) {
@@ -51,6 +82,26 @@ RedisStore.prototype.incr = function (ip, cb, timeWindow, max) {
   })
 }
 
+/**
+ * Read the current rate-limit state for `ip` without mutating it.
+ *
+ * Same argument contract as `incr` (`ip, cb, timeWindow, max`); the Redis
+ * implementation only needs the key, so `timeWindow`/`max` are ignored. The
+ * reported `ttl` is the raw server `PTTL` — the same source `incr` returns on
+ * its alive path — so it may exceed the configured `timeWindow` when
+ * `continueExceeding`/`exponentialBackoff` extended it.
+ *
+ * @param {string} ip
+ * @param {(err: Error | null, res: { current: number, ttl: number }) => void} cb
+ * @param {number} [timeWindow]
+ * @param {number} [max]
+ */
+RedisStore.prototype.read = function (ip, cb, timeWindow, max) {
+  this.redis.rateLimitRead(this.key + ip, (err, result) => {
+    err ? cb(err, null) : cb(null, { current: result[0], ttl: result[1] })
+  })
+}
+
 RedisStore.prototype.child = function (routeOptions) {
   return new RedisStore(routeOptions.continueExceeding, routeOptions.exponentialBackoff, this.redis, `${this.key}${routeOptions.routeInfo.method}${routeOptions.routeInfo.url}-`)
 }