Added reason for limiting in the check method.

Fixes #7

Author: ciscoheat

CHANGELOG.md

@@ -9,6 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- The `check` method now exists on both limiters, and will return a `reason` property.
 - `RateLimiterOptions` is now exported.
 
 ## [0.6.2] - 2025-06-17

README.md

@@ -48,6 +48,17 @@ export const actions = {
   default: async (event) => {
     // Every call to isLimited counts as a hit towards the rate limit for the event.
     if (await limiter.isLimited(event)) throw error(429);
+  },
+
+  debug: async (event) => {
+    // Alternatively you can call check to get more details.
+    // (will also count as a hit)
+    const status = await limiter.check(event);
+    if (status.limited) {
+      // 'IP' | 'IPUA' | 'cookie' | number
+      console.log('Limited due to ' + status.reason);
+      throw error(429);
+    }
   }
 };
 ```

src/index.test.ts

@@ -3,7 +3,7 @@ import type { RateLimiterPlugin } from '$lib/server/limiters/rateLimiterPlugin.j
 import { RateLimiter } from '$lib/server/rateLimiter.js';
 import { RetryAfterRateLimiter } from '$lib/server/retryAfterRateLimiter.js';
 import type { RequestEvent } from '@sveltejs/kit';
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, assert } from 'vitest';
 import { mock } from 'vitest-mock-extended';
 
 const hashFunction = async (input: string) => {
@@ -166,7 +166,10 @@ describe('Basic rate limiter', async () => {
 
     expect(await limiter.isLimited(event)).toEqual(false); //  1 1 1
     expect(await limiter.isLimited(event)).toEqual(false); //  2 2 2
-    expect(await limiter.isLimited(event)).toEqual(true); // 3 2 2 (Cookie fails)
+    expect(await limiter.check(event)).toEqual({
+      limited: true,
+      reason: 'cookie'
+    }); // 3 2 2 (Cookie fails)
 
     event.cookies.delete('testcookie', { path: '/' });
 
@@ -491,8 +494,9 @@ describe('Retry-After rate limiter', () => {
     expect(status).toEqual({ limited: false, retryAfter: 0 });
 
     status = await limiter.check(event);
-    expect(status.limited).toBe(true);
+    assert(status.limited);
     expect(status.retryAfter.toString()).toMatch(/^[345]$/);
+    expect(status.reason).toEqual('IPUA');
 
     await delay(5100);
 
@@ -522,8 +526,9 @@ describe('Retry-After rate limiter', () => {
     expect(status).toEqual({ limited: false, retryAfter: 0 });
 
     status = await limiter.check(event);
-    expect(status.limited).toEqual(true);
+    assert(status.limited);
     expect(status.retryAfter.toString()).toMatch(/^[01]$/);
+    expect(status.reason).toEqual('IPUA');
 
     event.request.headers.set('User-Agent', 'Safari 2');
 
@@ -534,23 +539,26 @@ describe('Retry-After rate limiter', () => {
     expect(status).toEqual({ limited: false, retryAfter: 0 });
 
     status = await limiter.check(event);
-    expect(status.limited).toEqual(true);
+    assert(status.limited);
     expect(status.retryAfter).toBeGreaterThanOrEqual(59);
     expect(status.retryAfter).toBeLessThanOrEqual(60);
+    expect(status.reason).toEqual('IP');
 
     event.request.headers.set('User-Agent', 'Safari 3');
 
     status = await limiter.check(event);
-    expect(status.limited).toEqual(true);
+    assert(status.limited);
     expect(status.retryAfter).toBeGreaterThanOrEqual(59);
     expect(status.retryAfter).toBeLessThanOrEqual(60);
+    expect(status.reason).toEqual('IP');
 
     await delay(1100);
 
     status = await limiter.check(event);
-    expect(status.limited).toEqual(true);
+    assert(status.limited);
     expect(status.retryAfter).toBeGreaterThanOrEqual(58);
     expect(status.retryAfter).toBeLessThanOrEqual(59);
+    expect(status.reason).toEqual('IP');
 
     await limiter.clear();
 

src/lib/server/rateLimiter.ts

@@ -87,6 +87,28 @@ export class RateLimiter<Extra = never> {
     return await this.store.clear();
   }
 
+  /**
+   * Check if a request event is rate limited.
+   * @param {RequestEvent} event
+   * @returns {Promise<limited: boolean, reason: 'IP' | 'IPUA' | 'cookie' | number>} Rate limit status for the event.
+   */
+  async check(
+    event: RequestEvent,
+    extraData?: Extra
+  ): Promise<
+    | { limited: false }
+    | {
+        limited: true;
+        reason: 'IP' | 'IPUA' | 'cookie' | number;
+      }
+  > {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const result = await this._isLimited(event, extraData as any);
+
+    if (!result.limited) return { limited: false };
+    return { limited: true, reason: result.reason };
+  }
+
   /**
    * Check if a request event is rate limited.
    * @param {RequestEvent} event
@@ -95,7 +117,15 @@ export class RateLimiter<Extra = never> {
   protected async _isLimited(
     event: RequestEvent,
     extraData: Extra
-  ): Promise<{ limited: boolean; hash: string | null; ttl: number }> {
+  ): Promise<
+    | { limited: false; hash: string | null; ttl: number }
+    | {
+        limited: true;
+        hash: string | null;
+        ttl: number;
+        reason: 'IP' | 'IPUA' | 'cookie' | number;
+      }
+  > {
     let limited: boolean | undefined = undefined;
 
     for (let i = 0; i < this.plugins.length; i++) {
@@ -109,7 +139,12 @@ export class RateLimiter<Extra = never> {
           if (status === true)
             return { limited: false, hash: null, ttl: rate[1] };
         }
-        return { limited: true, hash: null, ttl: rate[1] };
+        return {
+          limited: true,
+          hash: null,
+          ttl: rate[1],
+          reason: this.limitReason(plugin.limiter, i)
+        };
       } else if (id === null) {
         if (limited === undefined) limited = true;
         continue;
@@ -136,17 +171,44 @@ export class RateLimiter<Extra = never> {
           const status = await this.onLimited(event, 'rate');
           if (status === true) return { limited: false, hash, ttl: rate[1] };
         }
-        return { limited: true, hash, ttl: rate[1] };
+        return {
+          limited: true,
+          hash,
+          ttl: rate[1],
+          reason: this.limitReason(plugin.limiter, i)
+        };
       }
     }
 
+    if (limited) {
+      return {
+        limited: true,
+        hash: null,
+        ttl: this.plugins[this.plugins.length - 1].rate[1],
+        reason: this.limitReason(
+          this.plugins[this.plugins.length - 1].limiter,
+          this.plugins.length - 1
+        )
+      };
+    }
+
     return {
-      limited: limited ?? false,
+      limited: false,
       hash: null,
       ttl: this.plugins[this.plugins.length - 1].rate[1]
     };
   }
 
+  protected limitReason(
+    plugin: RateLimiterPlugin,
+    index: number
+  ): 'IP' | 'IPUA' | 'cookie' | number {
+    if (plugin instanceof IPRateLimiter) return 'IP';
+    if (plugin instanceof IPUserAgentRateLimiter) return 'IPUA';
+    if (plugin instanceof CookieRateLimiter) return 'cookie';
+    return index;
+  }
+
   constructor(options: RateLimiterOptions = {}) {
     this.onLimited = options.onLimited;
     this.hashFunction = options.hashFunction ?? defaultHashFunction;

src/lib/server/retryAfterRateLimiter.ts

@@ -29,12 +29,19 @@ export class RetryAfterRateLimiter<Extra = never> extends RateLimiter<Extra> {
   /**
    * Check if a request event is rate limited.
    * @param {RequestEvent} event
-   * @returns {Promise<limited: boolean, retryAfter: number>} Rate limit status for the event.
+   * @returns {Promise<limited: boolean, retryAfter: number, reason: 'IP' | 'IPUA' | 'cookie' | number>} Rate limit status for the event.
    */
-  async check(
+  override async check(
     event: RequestEvent,
     extraData?: Extra
-  ): Promise<{ limited: boolean; retryAfter: number }> {
+  ): Promise<
+    | { limited: false; retryAfter: 0 }
+    | {
+        limited: true;
+        retryAfter: number;
+        reason: 'IP' | 'IPUA' | 'cookie' | number;
+      }
+  > {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const result = await this._isLimited(event, extraData as any);
 
@@ -43,14 +50,15 @@ export class RetryAfterRateLimiter<Extra = never> extends RateLimiter<Extra> {
     if (result.hash === null) {
       return {
         limited: true,
-        retryAfter: RetryAfterRateLimiter.toSeconds(result.ttl)
+        retryAfter: RetryAfterRateLimiter.toSeconds(result.ttl),
+        reason: result.reason
       };
     }
 
     const retryAfter = RetryAfterRateLimiter.toSeconds(
       (await this.retryAfter.add(result.hash, result.ttl)) - Date.now()
     );
 
-    return { limited: true, retryAfter };
+    return { limited: true, retryAfter, reason: result.reason };
   }
 }