@fluixi/api 0.0.0-stage → 0.1.0-alpha.2

package/dist/rate-limit.cjs

@@ -0,0 +1,158 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/rate-limit.ts
+var rate_limit_exports = {};
+__export(rate_limit_exports, {
+  clientAddressOf: () => clientAddressOf,
+  memoryRateLimitStore: () => memoryRateLimitStore,
+  postgresRateLimitStore: () => postgresRateLimitStore,
+  rateLimit: () => rateLimit
+});
+module.exports = __toCommonJS(rate_limit_exports);
+var import_rate_limiter_flexible = require("rate-limiter-flexible");
+
+// src/errors.ts
+var ApiError = class extends Error {
+  constructor(status, code, message, details) {
+    super(message);
+    this.name = "ApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+  }
+};
+function errorResponse(error) {
+  const body = { error: { code: error.code, message: error.message } };
+  if (error.details !== void 0) body.error.details = error.details;
+  return new Response(JSON.stringify(body), {
+    status: error.status,
+    headers: { "content-type": "application/json; charset=utf-8" }
+  });
+}
+
+// src/middleware.ts
+function withHeaders(response, set) {
+  try {
+    set(response.headers);
+    return response;
+  } catch {
+    const copy = new Response(response.body, response);
+    set(copy.headers);
+    return copy;
+  }
+}
+
+// src/rate-limit.ts
+function memoryRateLimitStore() {
+  return storeOf(async (limit, windowSeconds) => new import_rate_limiter_flexible.RateLimiterMemory({ points: limit, duration: windowSeconds }));
+}
+function postgresRateLimitStore(client, options = {}) {
+  const { table = "rate_limits", schema, createTable = true } = options;
+  const storeClient = { query: (q) => client.query(q.text, q.values) };
+  let hits = 0;
+  return storeOf(
+    (limit, windowSeconds) => new Promise((resolve, reject) => {
+      const limiter = new import_rate_limiter_flexible.RateLimiterPostgres(
+        {
+          storeClient,
+          storeType: "pool",
+          tableName: table,
+          schemaName: schema,
+          tableCreated: !createTable,
+          clearExpiredByTimeout: false,
+          points: limit,
+          duration: windowSeconds,
+          insuranceLimiter: new import_rate_limiter_flexible.RateLimiterMemory({ points: limit, duration: windowSeconds })
+        },
+        // Called inside the constructor when the table exists already: resolve once it returned.
+        (error) => error ? reject(error) : queueMicrotask(() => resolve(limiter))
+      );
+    }),
+    (limiter) => {
+      const sweep = limiter;
+      if (++hits % 1e3 === 0) void sweep.clearExpired(Date.now() - 36e5).catch(() => {
+      });
+    }
+  );
+}
+function storeOf(make, onHit) {
+  const limiters = /* @__PURE__ */ new Map();
+  return {
+    async hit(key, limit, windowSeconds) {
+      const id = `${limit}/${windowSeconds}`;
+      let pending = limiters.get(id);
+      if (!pending) {
+        limiters.set(id, pending = make(limit, windowSeconds));
+        pending.catch(() => limiters.delete(id));
+      }
+      const limiter = await pending;
+      onHit?.(limiter);
+      try {
+        const res = await limiter.consume(key);
+        return { allowed: true, remaining: res.remainingPoints, resetMs: res.msBeforeNext };
+      } catch (thrown) {
+        if (thrown instanceof import_rate_limiter_flexible.RateLimiterRes) return { allowed: false, remaining: 0, resetMs: thrown.msBeforeNext };
+        throw thrown;
+      }
+    }
+  };
+}
+var ADDRESSES = /* @__PURE__ */ Symbol.for("fluixi.clientAddress");
+var sharedMemory = memoryRateLimitStore();
+var created = 0;
+function clientAddressOf(request) {
+  return globalThis[ADDRESSES]?.get(request);
+}
+function rateLimit(options) {
+  const { match, methods, limit, window, key = clientAddressOf, store = sharedMemory } = options;
+  const applies = matcher(match);
+  const methodSet = methods && new Set(methods.map((m) => m.toUpperCase()));
+  const bucket = options.name ?? `limit${++created}`;
+  return async (request, next) => {
+    if (methodSet && !methodSet.has(request.method)) return next();
+    if (!applies(request)) return next();
+    const who = await key(request);
+    if (!who) return next();
+    const { allowed, remaining, resetMs } = await store.hit(`${bucket}:${who}`, limit, window);
+    const reset = String(Math.ceil(resetMs / 1e3));
+    const set = (headers) => {
+      headers.set("ratelimit-limit", String(limit));
+      headers.set("ratelimit-remaining", String(remaining));
+      headers.set("ratelimit-reset", reset);
+    };
+    if (!allowed) {
+      const refused = errorResponse(new ApiError(429, "rate_limited", "Too many requests. Try again later."));
+      refused.headers.set("retry-after", reset);
+      set(refused.headers);
+      return refused;
+    }
+    return withHeaders(await next(), set);
+  };
+}
+function matcher(match) {
+  if (!match) return () => true;
+  if (typeof match === "function") return match;
+  const exact = new Set(match.filter((p) => !p.endsWith("/*")));
+  const prefixes = match.filter((p) => p.endsWith("/*")).map((p) => p.slice(0, -1));
+  return (request) => {
+    const { pathname } = new URL(request.url);
+    return exact.has(pathname) || prefixes.some((p) => pathname.startsWith(p));
+  };
+}

package/dist/rate-limit.d.ts

@@ -0,0 +1,69 @@
+import { type Middleware } from './middleware.js';
+/** Where hits are counted. */
+export interface RateLimitStore {
+    /** Counts one hit on `key` in a window of `windowSeconds`, allowing `limit` of them. */
+    hit(key: string, limit: number, windowSeconds: number): Promise<{
+        allowed: boolean;
+        remaining: number;
+        resetMs: number;
+    }>;
+}
+/** Counts in this process. Enough for one instance; several need a shared store. */
+export declare function memoryRateLimitStore(): RateLimitStore;
+/**
+ * Anything that runs a parameterised query and returns rows: a node-postgres `Pool` or
+ * `Client`, PGlite. No driver is imported here; the app passes the connection it has.
+ */
+export interface SqlClient {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: any[];
+    }>;
+}
+export interface PostgresRateLimitOptions {
+    /** `rate_limits` by default. */
+    table?: string;
+    schema?: string;
+    /**
+     * Create the table on first use (`key varchar(255) primary key, points integer not null
+     * default 0, expire bigint`). Off when a migration already made it.
+     */
+    createTable?: boolean;
+}
+/**
+ * Counts in Postgres, so every instance of the API shares them. If the database fails, hits are
+ * counted in memory until it is back rather than refusing or letting everyone through.
+ *
+ * Expired rows are cleared now and then on a hit rather than by a timer, so an idle database
+ * that scales to zero is left asleep.
+ */
+export declare function postgresRateLimitStore(client: SqlClient, options?: PostgresRateLimitOptions): RateLimitStore;
+export interface RateLimitOptions {
+    /** Paths it applies to, exactly or as a prefix ending in `/*`; or a test. Every request when not given. */
+    match?: readonly string[] | ((request: Request) => boolean);
+    /** Methods it applies to. Every method when not given. */
+    methods?: readonly string[];
+    /** Hits allowed per window. */
+    limit: number;
+    /** Window length, in seconds. */
+    window: number;
+    /**
+     * Who a hit belongs to. The client address by default (`clientAddress` from `@fluixi/start`);
+     * a request with no key is not counted.
+     */
+    key?: (request: Request) => string | undefined | Promise<string | undefined>;
+    /** Where hits are counted. In memory by default. */
+    store?: RateLimitStore;
+    /**
+     * Keeps this limit's counts apart from the others' in a shared store. Defaults to the order
+     * limits are created in, which holds across instances running the same code.
+     */
+    name?: string;
+}
+/** The address `@fluixi/start` recorded for the request, read without importing it. */
+export declare function clientAddressOf(request: Request): string | undefined;
+/**
+ * Refuses a caller who goes over `limit` requests in `window` seconds with a 429 and
+ * `Retry-After`. Every counted response carries `RateLimit-Limit`, `-Remaining` and `-Reset`.
+ */
+export declare function rateLimit(options: RateLimitOptions): Middleware;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../src/rate-limit.ts"],"names":[],"mappings":"AAMA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE/D,8BAA8B;AAC9B,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC3H;AAED,oFAAoF;AACpF,wBAAgB,oBAAoB,IAAI,cAAc,CAErD;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,GAAG,EAAE,CAAA;KAAE,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,wBAAwB;IACvC,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,GAAE,wBAA6B,GAAG,cAAc,CA8BhH;AA4BD,MAAM,WAAW,gBAAgB;IAC/B,2GAA2G;IAC3G,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC;IAC5D,0DAA0D;IAC1D,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,iCAAiC;IACjC,MAAM,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7E,oDAAoD;IACpD,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAOD,uFAAuF;AACvF,wBAAgB,eAAe,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,UAAU,CA2B/D"}

package/dist/rate-limit.js

@@ -0,0 +1,121 @@
+/**
+ * Rate limits: `rate-limiter-flexible` counts, behind a store interface so a shared backend
+ * (Postgres, Redis) replaces the in-memory one without touching the middleware.
+ */
+import { RateLimiterMemory, RateLimiterPostgres, RateLimiterRes } from 'rate-limiter-flexible';
+import { ApiError, errorResponse } from './errors.js';
+import { withHeaders } from './middleware.js';
+/** Counts in this process. Enough for one instance; several need a shared store. */
+export function memoryRateLimitStore() {
+    return storeOf(async (limit, windowSeconds) => new RateLimiterMemory({ points: limit, duration: windowSeconds }));
+}
+/**
+ * Counts in Postgres, so every instance of the API shares them. If the database fails, hits are
+ * counted in memory until it is back rather than refusing or letting everyone through.
+ *
+ * Expired rows are cleared now and then on a hit rather than by a timer, so an idle database
+ * that scales to zero is left asleep.
+ */
+export function postgresRateLimitStore(client, options = {}) {
+    const { table = 'rate_limits', schema, createTable = true } = options;
+    // The limiter sends node-postgres query objects; this takes any client with query(text, values).
+    const storeClient = { query: (q) => client.query(q.text, q.values) };
+    let hits = 0;
+    return storeOf((limit, windowSeconds) => new Promise((resolve, reject) => {
+        const limiter = new RateLimiterPostgres({
+            storeClient,
+            storeType: 'pool',
+            tableName: table,
+            schemaName: schema,
+            tableCreated: !createTable,
+            clearExpiredByTimeout: false,
+            points: limit,
+            duration: windowSeconds,
+            insuranceLimiter: new RateLimiterMemory({ points: limit, duration: windowSeconds }),
+        }, 
+        // Called inside the constructor when the table exists already: resolve once it returned.
+        (error) => (error ? reject(error) : queueMicrotask(() => resolve(limiter))));
+    }), (limiter) => {
+        // Public in the library, missing from its type declarations.
+        const sweep = limiter;
+        if (++hits % 1000 === 0)
+            void sweep.clearExpired(Date.now() - 3_600_000).catch(() => { });
+    });
+}
+/** One limiter per limit and window, made on first use; counting and refusal read the same way. */
+function storeOf(make, onHit) {
+    const limiters = new Map();
+    return {
+        async hit(key, limit, windowSeconds) {
+            const id = `${limit}/${windowSeconds}`;
+            let pending = limiters.get(id);
+            if (!pending) {
+                limiters.set(id, (pending = make(limit, windowSeconds)));
+                pending.catch(() => limiters.delete(id));
+            }
+            const limiter = await pending;
+            onHit?.(limiter);
+            try {
+                const res = await limiter.consume(key);
+                return { allowed: true, remaining: res.remainingPoints, resetMs: res.msBeforeNext };
+            }
+            catch (thrown) {
+                if (thrown instanceof RateLimiterRes)
+                    return { allowed: false, remaining: 0, resetMs: thrown.msBeforeNext };
+                throw thrown;
+            }
+        },
+    };
+}
+const ADDRESSES = Symbol.for('fluixi.clientAddress');
+const sharedMemory = memoryRateLimitStore();
+let created = 0;
+/** The address `@fluixi/start` recorded for the request, read without importing it. */
+export function clientAddressOf(request) {
+    return globalThis[ADDRESSES]?.get(request);
+}
+/**
+ * Refuses a caller who goes over `limit` requests in `window` seconds with a 429 and
+ * `Retry-After`. Every counted response carries `RateLimit-Limit`, `-Remaining` and `-Reset`.
+ */
+export function rateLimit(options) {
+    const { match, methods, limit, window, key = clientAddressOf, store = sharedMemory } = options;
+    const applies = matcher(match);
+    const methodSet = methods && new Set(methods.map((m) => m.toUpperCase()));
+    const bucket = options.name ?? `limit${++created}`;
+    return async (request, next) => {
+        if (methodSet && !methodSet.has(request.method))
+            return next();
+        if (!applies(request))
+            return next();
+        const who = await key(request);
+        if (!who)
+            return next();
+        const { allowed, remaining, resetMs } = await store.hit(`${bucket}:${who}`, limit, window);
+        const reset = String(Math.ceil(resetMs / 1000));
+        const set = (headers) => {
+            headers.set('ratelimit-limit', String(limit));
+            headers.set('ratelimit-remaining', String(remaining));
+            headers.set('ratelimit-reset', reset);
+        };
+        if (!allowed) {
+            const refused = errorResponse(new ApiError(429, 'rate_limited', 'Too many requests. Try again later.'));
+            refused.headers.set('retry-after', reset);
+            set(refused.headers);
+            return refused;
+        }
+        return withHeaders(await next(), set);
+    };
+}
+function matcher(match) {
+    if (!match)
+        return () => true;
+    if (typeof match === 'function')
+        return match;
+    const exact = new Set(match.filter((p) => !p.endsWith('/*')));
+    const prefixes = match.filter((p) => p.endsWith('/*')).map((p) => p.slice(0, -1));
+    return (request) => {
+        const { pathname } = new URL(request.url);
+        return exact.has(pathname) || prefixes.some((p) => pathname.startsWith(p));
+    };
+}