@thi.ng/server 0.6.0 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-02-21T21:54:17Z
+- **Last updated**: 2025-03-09T19:21:53Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,15 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.7.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.7.0) (2025-03-09)
+
+#### 🚀 Features
+
+- update RateLimiter to use leaky buckets ([f342fde](https://github.com/thi-ng/umbrella/commit/f342fde))
+  - update `RateLimterOpts`
+  - update/simplify `RateLimiter` interceptor
+  - update deps
+
 ## [0.6.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/server@0.6.0) (2025-02-21)
 
 #### 🚀 Features

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 202 standalone projects, maintained as part
+> This is one of 203 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -149,7 +149,7 @@ For Node.js REPL:
 const ser = await import("@thi.ng/server");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 5.28 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 5.15 KB
 
 ## Dependencies
 
@@ -159,6 +159,7 @@ Package sizes (brotli'd, pre-treeshake): ESM: 5.28 KB
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/file-io](https://github.com/thi-ng/umbrella/tree/develop/packages/file-io)
+- [@thi.ng/leaky-bucket](https://github.com/thi-ng/umbrella/tree/develop/packages/leaky-bucket)
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
 - [@thi.ng/mime](https://github.com/thi-ng/umbrella/tree/develop/packages/mime)
 - [@thi.ng/paths](https://github.com/thi-ng/umbrella/tree/develop/packages/paths)

package/interceptors/rate-limit.d.ts

@@ -1,6 +1,13 @@
 import type { Fn, Fn2, Maybe } from "@thi.ng/api";
-import { TLRUCache } from "@thi.ng/cache";
+import { LeakyBucketMap } from "@thi.ng/leaky-bucket";
 import type { Interceptor, RequestCtx } from "../api.js";
+/**
+ * Configuration options for {@link RateLimiter}.
+ *
+ * References:
+ * - https://thi.ng/leaky-bucket
+ * - https://en.wikipedia.org/wiki/Leaky_bucket
+ */
 export interface RateLimitOpts<T extends RequestCtx = RequestCtx> {
     /**
      * Function to produce a unique ID for rate limiting a client. By default
@@ -8,23 +15,44 @@ export interface RateLimitOpts<T extends RequestCtx = RequestCtx> {
      * client will NOT be rate limited.
      */
     id?: Fn<T, Maybe<string>>;
+    /**
+     * Max. number of concurrently active client IDs/buckets. A bucket is
+     * created for each unique ID produced via {@link RateLimitOpts.id}.
+     *
+     * @remarks
+     * A bucket's counter is incremented for each related request, up to the
+     * configured {@link RateLimitOpts.bucketCapacity}. Once a bucket's capacity
+     * has been reached, any new requests are dropped by the interceptor. Bucket
+     * counters are slowly decremented every
+     * {@link RateLimiterOpts.leakInterval} milliseconds, thus slowly allowing
+     * again new requests. Once a bucket's counter goes back to zero, the bucket
+     * will be removed.
+     *
+     * @defaultValue 1000
+     */
+    maxBuckets: number;
     /**
      * Function to compute the max number of allowed requests for given client
-     * ID and configured {@link RateLimitOpts.period}. If given as number, that
-     * limit will be enforced for all identified clients.
+     * ID bucket. If given as number, that limit will be uniformly enforced for
+     * all clients. If given as function, per-client quotas can be defined.
      *
      * @remarks
-     * Quotas are only computed whenever a new client ID is first encountered or
-     * when its previous request records have expired from the cache (after
-     * {@link RateLimitOpts.period} seconds).
+     * Capacities are only computed whenever a new client ID is first
+     * encountered or when its existing bucket is empty again (also see
+     * {@link RateLimitOpts.leakInterval}).
+     *
+     * @defaultValue 60
      */
-    quota: number | Fn2<T, string, number>;
+    bucketCapacity: number | Fn2<T, string, number>;
     /**
-     * Size of the time window (in secords) to which this rate limiter applies.
+     * Time interval (in milliseconds) at which all active client ID buckets are
+     * decreasing their counters, slowly freeing again their capacities. Once a
+     * bucket is empty again (i.e. its counter is back at zero), the bucket will
+     * be automatically removed.
      *
-     * @defaultValue 900
+     * @defaultValue 1000
      */
-    period?: number;
+    leakInterval: number;
 }
 /**
  * Creates a new {@link RateLimiter} interceptor.
@@ -33,41 +61,17 @@ export interface RateLimitOpts<T extends RequestCtx = RequestCtx> {
  */
 export declare const rateLimiter: <T extends RequestCtx = RequestCtx>(opts: RateLimitOpts<T>) => RateLimiter<T>;
 /**
- * Configurable, sliding time window-based rate limiter interceptor.
+ * Configurable rate limiter interceptor using a counter-based leaky bucket
+ * algorithm to ensure both an average rate and allow temporary bursting (up to
+ * an implicitly defined limit).
+ *
+ *
  */
 export declare class RateLimiter<T extends RequestCtx = RequestCtx> implements Interceptor<T> {
-    cache: TLRUCache<string, Timestamps>;
-    clientQuota: Fn2<T, string, number>;
+    buckets: LeakyBucketMap<string>;
+    capacity: Fn2<T, string, number>;
     clientID: Fn<T, Maybe<string>>;
-    period: number;
-    constructor({ id, quota, period }: RateLimitOpts<T>);
+    constructor({ id, maxBuckets, bucketCapacity, leakInterval, }: RateLimitOpts<T>);
     pre(ctx: T): boolean;
 }
-/**
- * Ring-buffer based history of request timestamps (per client).
- *
- * @remarks
- * Based on thi.ng/buffers `FIFOBuffer` implementation.
- *
- * @internal
- */
-declare class Timestamps {
-    quota: number;
-    buf: number[];
-    rpos: number;
-    wpos: number;
-    num: number;
-    constructor(quota: number);
-    /**
-     * Removes any timestamps older than `threshold` from the buffer and returns
-     * remaining number of timestamps.
-     *
-     * @param threshold
-     */
-    expire(threshold: number): number;
-    peek(): number;
-    writable(): boolean;
-    write(x: number): boolean;
-}
-export {};
 //# sourceMappingURL=rate-limit.d.ts.map

package/interceptors/rate-limit.js

@@ -1,78 +1,28 @@
-import { TLRUCache } from "@thi.ng/cache";
 import { isNumber } from "@thi.ng/checks";
+import { LeakyBucketMap } from "@thi.ng/leaky-bucket";
 const rateLimiter = (opts) => new RateLimiter(opts);
 class RateLimiter {
-  cache;
-  clientQuota;
+  buckets;
+  capacity;
   clientID;
-  period;
-  constructor({ id, quota, period = 15 * 60 }) {
+  constructor({
+    id,
+    maxBuckets,
+    bucketCapacity,
+    leakInterval
+  }) {
     this.clientID = id ?? ((ctx) => ctx.req.socket.remoteAddress);
-    this.clientQuota = isNumber(quota) ? () => quota : quota;
-    this.period = (period ?? 15 * 60) * 1e3;
-    this.cache = new TLRUCache(null, {
-      ttl: this.period,
-      autoExtend: true
-    });
+    this.capacity = isNumber(bucketCapacity) ? () => bucketCapacity : bucketCapacity;
+    this.buckets = new LeakyBucketMap({ leakInterval, maxBuckets });
   }
   pre(ctx) {
-    const now = Date.now();
     const id = this.clientID(ctx);
     if (!id) return true;
-    let timestamps = this.cache.get(id);
-    if (timestamps) {
-      if (timestamps.expire(now - this.period) >= timestamps.quota) {
-        ctx.res.rateLimit(
-          {},
-          `Try again @ ${new Date(
-            timestamps.peek() + this.period
-          ).toISOString()}`
-        );
-        return false;
-      }
-    } else {
-      timestamps = new Timestamps(this.clientQuota(ctx, id));
-      this.cache.set(id, timestamps);
+    const cap = !this.buckets.has(id) ? this.capacity(ctx, id) : void 0;
+    if (!this.buckets.update(id, cap)) {
+      ctx.res.rateLimit({}, `Try again later.`);
+      return false;
     }
-    timestamps.write(now);
-    return true;
-  }
-}
-class Timestamps {
-  constructor(quota) {
-    this.quota = quota;
-  }
-  buf = [];
-  rpos = 0;
-  wpos = 0;
-  num = 0;
-  /**
-   * Removes any timestamps older than `threshold` from the buffer and returns
-   * remaining number of timestamps.
-   *
-   * @param threshold
-   */
-  expire(threshold) {
-    let { buf, rpos, num } = this;
-    const max = buf.length;
-    while (num && buf[rpos] < threshold) {
-      rpos = (rpos + 1) % max;
-      num--;
-    }
-    this.rpos = rpos;
-    return this.num = num;
-  }
-  peek() {
-    return this.buf[this.rpos];
-  }
-  writable() {
-    return this.num < this.quota;
-  }
-  write(x) {
-    const { buf, wpos } = this;
-    buf[wpos] = x;
-    this.wpos = (wpos + 1) % this.quota;
-    this.num++;
     return true;
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/server",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Minimal HTTP server with declarative routing, static file serving and freely extensible via pre/post interceptors",
   "type": "module",
   "module": "./index.js",
@@ -39,19 +39,20 @@
     "tool:tangle": "../../node_modules/.bin/tangle src/**/*.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.11.21",
-    "@thi.ng/arrays": "^2.10.17",
-    "@thi.ng/cache": "^2.3.25",
-    "@thi.ng/checks": "^3.7.0",
-    "@thi.ng/errors": "^2.5.27",
-    "@thi.ng/file-io": "^2.1.29",
-    "@thi.ng/logger": "^3.1.2",
-    "@thi.ng/mime": "^2.7.3",
-    "@thi.ng/paths": "^5.2.3",
-    "@thi.ng/router": "^4.1.20",
-    "@thi.ng/strings": "^3.9.6",
-    "@thi.ng/timestamp": "^1.1.6",
-    "@thi.ng/uuid": "^1.1.18"
+    "@thi.ng/api": "^8.11.22",
+    "@thi.ng/arrays": "^2.10.19",
+    "@thi.ng/cache": "^2.3.27",
+    "@thi.ng/checks": "^3.7.2",
+    "@thi.ng/errors": "^2.5.28",
+    "@thi.ng/file-io": "^2.1.31",
+    "@thi.ng/leaky-bucket": "^0.1.0",
+    "@thi.ng/logger": "^3.1.3",
+    "@thi.ng/mime": "^2.7.4",
+    "@thi.ng/paths": "^5.2.5",
+    "@thi.ng/router": "^4.1.22",
+    "@thi.ng/strings": "^3.9.7",
+    "@thi.ng/timestamp": "^1.1.7",
+    "@thi.ng/uuid": "^1.1.19"
   },
   "devDependencies": {
     "@types/node": "^22.13.1",
@@ -163,5 +164,5 @@
     "status": "alpha",
     "year": 2024
   },
-  "gitHead": "2958e6a9881bd9e06de587a2141f6d23c64278db\n"
+  "gitHead": "55987d581e4985b1c3091ba6be3f9b53a0c5eeea\n"
 }