@profullstack/throttle 0.3.2 → 0.3.4

package/README.md

@@ -160,6 +160,15 @@ authenticated. **The sign-in routes need this**, or a brute-force attempt bolts
 an `Authorization` header onto every guess and buys itself the integration
 budget.
 
+### Subresources
+
+Images, fonts, scripts and styles (by `Sec-Fetch-Dest`) count against a bucket
+of their own, 1,000 a minute by default, so a page that pulls in hundreds of
+images never spends the reader's page allowance; at worst an image breaks, the
+page does not 402. They are metered rather than exempt because the header is
+the client's to write. `subresources: { limit }` changes the number;
+`subresources: false` counts them with pages, as 0.3 did.
+
 ### Never metered
 
 `/robots.txt`, `/favicon.ico`, `/.well-known/`, and — when a gateway is

package/index.d.ts

@@ -62,6 +62,12 @@ export interface ThrottleOptions {
   rules?: ThrottleRule[];
   /** Budget for callers presenting a credential. `false` to treat them as anonymous. */
   credential?: false | CredentialBudget;
+  /**
+   * Images, fonts, scripts and styles (by Sec-Fetch-Dest) count against their
+   * own bucket, so a page full of images never spends the page allowance.
+   * Default 1000 per window; `false` counts them with pages.
+   */
+  subresources?: false | { limit?: number };
   /** Told about every refusal. Its errors are swallowed. */
   onThrottle?: (event: ThrottleEvent) => void | Promise<void>;
 }
@@ -75,12 +81,15 @@ export interface Throttle {
     windowSeconds: number;
     rules: Required<ThrottleRule>[];
     credential: { limit: number; ceiling: number } | null;
+    subresources: { limit: number } | null;
     openPaths: string[];
     gateway: boolean;
   };
 }
 
 export function createThrottle(options?: ThrottleOptions): Throttle;
+/** Whether Sec-Fetch-Dest names an image, font, style, script or media fetch. */
+export function isSubresource(request: Request): boolean;
 
 export function memoryStore(options?: {
   now?: () => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@profullstack/throttle",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "type": "module",
   "description": "An app-wide rate limit whose answer to going over is a price, not a 429. 100 requests a minute free, then x402 Payment Required with an offer, settled by CoinPay. Meters every route, so a scraper wearing a browser user agent is charged like any other crawler.",
   "keywords": [
@@ -54,7 +54,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@profullstack/x402-gateway": "^0.6.0 || ^0.7.0 || ^0.8.0 || ^0.9.0 || ^0.10.0"
+    "@profullstack/x402-gateway": "^0.6.0 || ^0.7.0 || ^0.8.0 || ^0.9.0 || ^0.10.0 || ^0.11.0 || ^0.12.0 || ^0.13.0"
   },
   "scripts": {
     "test": "node --test"

package/src/index.js

@@ -1,4 +1,4 @@
-export { createThrottle } from './throttle.js';
+export { createThrottle, isSubresource } from './throttle.js';
 export { memoryStore } from './store.js';
 export { addressOf, fingerprint, presentedCredential } from './identify.js';
 export {

package/src/throttle.js

@@ -45,6 +45,7 @@ import { memoryStore } from './store.js';
  * @param {string[]} [options.openPaths]            extra paths never metered
  * @param {Array} [options.rules]                   per-path allowances, most specific wins
  * @param {{limit?: number, ceiling?: number}} [options.credential]  budget for callers presenting a credential
+ * @param {false|{limit?: number}} [options.subresources]  separate budget for images, fonts, scripts and styles; default 1000
  * @param {(event: object) => void|Promise<void>} [options.onThrottle]  told about every refusal; its errors are swallowed
  */
 export function createThrottle(options = {}) {
@@ -93,6 +94,19 @@ export function createThrottle(options = {}) {
     ...(options.openPaths ?? []),
   ];
 
+  /*
+   * Images, fonts, scripts and styles get a bucket of their own, ten times the
+   * page allowance. On 2026-10-23 one refresh of an admin page that listed
+   * ~1,500 logos at relative paths spent the whole page allowance in a second,
+   * and the page itself answered 402: the reader was billed for markup they
+   * did not write. Kept separate rather than exempt, because Sec-Fetch-Dest is
+   * a header the client writes; a scraper that claims every page is an image
+   * buys itself a bigger bucket, not an unmetered site.
+   */
+  const subresources = options.subresources === false ? null : {
+    limit: positive(options.subresources?.limit, 1000),
+  };
+
   const quotaFor = (rule) => ({
     requests: rule.limit,
     windowSeconds: rule.windowSeconds,
@@ -216,6 +230,13 @@ export function createThrottle(options = {}) {
       return null;
     }
 
+    if (subresources && isSubresource(request)) {
+      const assetRule = { ...rule, limit: subresources.limit };
+      const usage = await spend(quotaFor(assetRule), `asset:${rule.path || '*'}:${key}`);
+      if (usage?.overLimit) return refuse(request, assetRule, usage);
+      return null;
+    }
+
     const usage = await spend(quotaFor(rule), `${rule.path || '*'}:${key}`);
     if (usage?.overLimit) return refuse(request, rule, usage);
     return null;
@@ -225,10 +246,21 @@ export function createThrottle(options = {}) {
     handle,
     /** For tests and for a site that wants to reclaim memory on demand. */
     store,
-    options: { ...defaults, rules, credential, openPaths, gateway: Boolean(gateway) },
+    options: { ...defaults, rules, credential, subresources, openPaths, gateway: Boolean(gateway) },
   };
 }
 
+/**
+ * What a browser fetches to render a page, by its own account
+ * (Sec-Fetch-Dest). A navigation says `document`, fetch() and XHR say `empty`;
+ * both stay on the page allowance.
+ */
+const SUBRESOURCE = new Set(['image', 'font', 'style', 'script', 'audio', 'video', 'track', 'manifest']);
+
+export function isSubresource(request) {
+  return SUBRESOURCE.has(request.headers.get('sec-fetch-dest') ?? '');
+}
+
 function positive(value, fallback) {
   const n = Number(value);
   return Number.isFinite(n) && n >= 1 ? Math.floor(n) : fallback;