@bakery-framework/core 2.1.2 → 2.2.1

package/src/startup.ts

@@ -1,6 +1,7 @@
 import { networkInterfaces } from 'node:os'
 import { Bakery } from './core/bakery'
 import { getConfigLoadError } from './core/config'
+import { getFrameworkVersion } from './core/context'
 import { resolvePort } from './core/port'
 import {
   ApiErrorHandler,
@@ -51,6 +52,19 @@ export function setupPlugins(): Promise<void> {
   return pluginSetup
 }
 
+/**
+ * `bakery --build`: every plugin's `build` hook, after their setup. Returns
+ * which plugins built and which failed.
+ */
+export async function buildPlugins(): Promise<{
+  built: string[]
+  failed: string[]
+}> {
+  await setupPlugins()
+  const { PluginHooks } = await import('./core/plugins')
+  return await PluginHooks.build()
+}
+
 /**
  * Test seam, in the family of `__setTestConfig` / `__setTestDb`. The memo above
  * is process-wide by design, which is exactly what a test asserting "once"
@@ -106,6 +120,10 @@ export async function runStartupBanner(): Promise<void> {
 
   const isThreadWorker = import.meta.env.THREAD_WORKER
   if (!isThreadWorker || import.meta.env.THREAD_ID === '0') {
+    // The framework's version, from core's own manifest: not the app's,
+    // which is what `<cwd>/package.json` would have said.
+    serveLog.BAKERY_VERSION({ version: getFrameworkVersion() })
+
     if (isThreadWorker) {
       serveLog.THREAD_STARTED({ id: import.meta.env.THREAD_ID })
     } else {

package/src/utils/http/index.ts

@@ -7,6 +7,7 @@ export * from './escape'
 export * from './etag'
 export * from './html'
 export * from './ip'
+export * from './rate-limit'
 export * from './response'
 export * from './sse'
 export * from './url'

package/src/utils/http/rate-limit.ts

@@ -0,0 +1,56 @@
+/**
+ * The shape of the `rateLimit` setting. Types only: the limiter itself runs in
+ * `@bakery-framework/cli` (`worker.ts`), before a request is routed, and its
+ * buckets live in the shared pool (`utils/shared-pool.ts`).
+ *
+ * Every bucket is a token bucket: it holds up to `max` tokens, a request
+ * spends one, and `refill` tokens come back each second. A request that finds
+ * its bucket empty is answered 429 with a `Retry-After` header.
+ */
+
+/** Who a request counts against. Nothing, or `''`, falls back to the client address, then the hostname. */
+export type RateLimitKey = (req: Request) => string | null | undefined
+
+/**
+ * A budget for one part of the site, kept in buckets of its own.
+ *
+ * A request is charged to the rule with the longest prefix that covers its
+ * path, and to that rule only: it does not also spend from the top-level
+ * bucket. A path no rule covers spends from the top level.
+ */
+export interface RateLimitRule {
+  /**
+   * The path the rule covers, matched by whole segments and ignoring case,
+   * the way routing reads a path: `/api/auth` covers `/api/auth`,
+   * `/api/auth/sign-in` and `/API//Auth/sign-in/`, and not `/api/authors`.
+   */
+  prefix: string
+  /** The largest burst one caller can make here: the bucket's size. */
+  max: number
+  /** Tokens back per second; fractions work, so `1 / 30` is one every thirty seconds. */
+  refill: number
+  /**
+   * Who the caller is, for this rule. When it is left out the key is the
+   * client address, whatever the top-level `keyBy` says: a rule usually
+   * guards something worth attacking (sign-in, a password reset), and an
+   * address cannot be multiplied by opening more sessions.
+   */
+  keyBy?: RateLimitKey
+}
+
+/** The `rateLimit` setting, when it is not `false`. */
+export interface RateLimitOptions {
+  /** The largest burst one caller can make: the bucket's size. */
+  max: number
+  /** Tokens back per second; fractions work, so `0.5` is one every two seconds. */
+  refill: number
+  /**
+   * Who the caller is. Without it the key is the client address
+   * (`utils/http/ip.ts`), and so it is whenever this returns nothing. Return
+   * an account id for signed-in requests to give each account its own bucket
+   * behind a shared address, a school's or an office's.
+   */
+  keyBy?: RateLimitKey
+  /** Budgets for parts of the site. See `RateLimitRule`. */
+  routes?: RateLimitRule[]
+}

package/src/utils/shared-pool.ts

@@ -1,11 +1,50 @@
 const HEADER_INT_COUNT = 16
 const COUNTERS_INT_COUNT = 256
-const RATE_LIMIT_SLOT_COUNT = 1024
+
+/**
+ * Number of token buckets, one 64-bit word each (see `consumeToken`).
+ *
+ * Every rate-limit key hashes into one of these, and keys that land in the
+ * same slot share a budget. With N keys live, about N / slots of them share
+ * with someone. At 1024, which this was, a school's thousand signed-in
+ * accounts would put most of them in a shared bucket; at 16384 about 6% share
+ * one, for 128 KB. The cost of the other direction is memory every server
+ * process allocates at import, so it grows with a consumer, not ahead of one.
+ */
+export const RATE_LIMIT_SLOT_COUNT = 16384
 const HEADER_BYTES = HEADER_INT_COUNT * 4
 const COUNTERS_BYTES = COUNTERS_INT_COUNT * 4
-const RATE_LIMIT_BYTES = RATE_LIMIT_SLOT_COUNT * 2 * 4
+// Eight-byte words, so the region has to start on an eight-byte boundary: it
+// does, at 1088, and a BigInt64Array view throws a RangeError if a resized
+// header or counter region ever moves it off one.
+const RATE_LIMIT_BYTES = RATE_LIMIT_SLOT_COUNT * 8
 const BUFFER_START_OFFSET = HEADER_BYTES + COUNTERS_BYTES + RATE_LIMIT_BYTES
 
+/**
+ * How far ahead of now a bucket may run, in microseconds: 2^52, about 142
+ * years. The bucket arithmetic is done in ordinary numbers, which hold
+ * integers exactly up to 2^53, and microseconds since 1970 are about 2^50.7,
+ * so a time this far ahead still fits exactly until the year 2112. A burst
+ * times an interval longer than this (a million tokens at one a week) is cut
+ * to it, which only shrinks the bucket.
+ *
+ * Numbers, not BigInt, because every request pays for this call. Measured
+ * over 2M calls, two adjacent runs: 234 to 243 ns with BigInt only at the
+ * load and the store, 547 to 606 ns with BigInt arithmetic throughout, and
+ * 104 to 142 ns for the 32-bit pair this replaced.
+ */
+const MAX_AHEAD_US = 2 ** 52
+
+/**
+ * Whole microseconds per token. Whole, so every sum below is an exact
+ * integer and the burst boundary never depends on rounding; the cost is a
+ * refill rate off by under 0.05% below 1000 a second, and by more only at
+ * rates no per-client limit uses.
+ */
+function tokenInterval(refillRatePerSec: number): number {
+  return Math.min(Math.max(Math.round(1e6 / refillRatePerSec), 1), MAX_AHEAD_US)
+}
+
 export const COUNTER_SLOTS = {
   TOTAL_REQUESTS: 0,
   TOTAL_ERRORS: 1,
@@ -21,7 +60,7 @@ export class SharedMemoryPool {
   buffer!: SharedArrayBuffer
   header!: Int32Array
   counters!: Int32Array
-  rateLimits!: Int32Array
+  rateLimits!: BigInt64Array
 
   /**
    * **The default is the layout's own size, not a megabyte.**
@@ -52,10 +91,10 @@ export class SharedMemoryPool {
         HEADER_BYTES,
         COUNTERS_INT_COUNT,
       )
-      this.rateLimits = new Int32Array(
+      this.rateLimits = new BigInt64Array(
         this.buffer,
         HEADER_BYTES + COUNTERS_BYTES,
-        RATE_LIMIT_SLOT_COUNT * 2,
+        RATE_LIMIT_SLOT_COUNT,
       )
       Atomics.store(this.header, 0, 0x42414b45)
       Atomics.store(this.header, 1, size)
@@ -77,12 +116,11 @@ export class SharedMemoryPool {
       HEADER_BYTES,
       COUNTERS_INT_COUNT,
     )
-    this.rateLimits = new Int32Array(
+    this.rateLimits = new BigInt64Array(
       this.buffer,
       HEADER_BYTES + COUNTERS_BYTES,
-      RATE_LIMIT_SLOT_COUNT * 2,
+      RATE_LIMIT_SLOT_COUNT,
     )
-
   }
 
   incrementCounter(slot: number, delta = 1): number {
@@ -105,68 +143,94 @@ export class SharedMemoryPool {
     return Atomics.store(this.counters, slot, value)
   }
 
+  /**
+   * Take `tokensRequested` from the bucket in `slot`, or answer `false` and
+   * take nothing. A bucket holds up to `maxTokens` and gains
+   * `refillRatePerSec` a second, fractions included: `1 / 30` is one token
+   * every thirty seconds.
+   *
+   * Each slot holds one number, the bucket's *theoretical arrival time* in
+   * microseconds since the epoch (GCRA, the generic cell rate algorithm): the
+   * moment it would be full again if nothing else arrived. A token is one
+   * `interval` of that time, and a request is admitted while granting it
+   * leaves the arrival time no more than `maxTokens` intervals ahead of now.
+   * A slot never used holds 0, and any time not ahead of now reads as full.
+   *
+   * It replaces two 32-bit words, tokens and whole seconds, which dropped the
+   * fraction of every refill under one token a second. A bucket refilling at
+   * 0.5 a second, asked once a second while empty, computed 0.5, stored 0
+   * and restarted its clock, so it never granted again while the client kept
+   * asking (measured: a grant due after 2 s did not come in 120). One word is
+   * also one compare-and-swap, where the pair could be torn between workers.
+   *
+   * `nowMs` is a seam for tests, in the manner of `sampleRateLimitLog`.
+   */
   consumeToken(
     slot: number,
     maxTokens: number,
     refillRatePerSec: number,
     tokensRequested = 1,
+    nowMs: number = Date.now(),
   ): boolean {
     if (slot < 0 || slot >= RATE_LIMIT_SLOT_COUNT) return false
-    const tokenIndex = slot * 2
-    const timeIndex = slot * 2 + 1
-
-    const nowSec = Math.floor(Date.now() / 1000)
+    // Fail closed on limits that are not positive numbers: nothing is
+    // admitted, rather than BigInt() throwing out of every request or a NaN
+    // comparison letting every request through.
+    if (!(maxTokens >= 1 && refillRatePerSec > 0 && tokensRequested >= 0)) {
+      return false
+    }
 
-    while (true) {
-      const currentTokens = Atomics.load(this.rateLimits, tokenIndex)
-      const lastTime = Atomics.load(this.rateLimits, timeIndex)
-
-      if (lastTime === 0 && currentTokens === 0) {
-        const initTokens = Math.max(0, maxTokens - tokensRequested)
-        if (
-          Atomics.compareExchange(this.rateLimits, timeIndex, 0, nowSec) === 0
-        ) {
-          Atomics.store(this.rateLimits, tokenIndex, initTokens)
-          return tokensRequested <= maxTokens
-        }
-        continue
-      }
+    const interval = tokenInterval(refillRatePerSec)
+    const limit = Math.min(Math.floor(maxTokens) * interval, MAX_AHEAD_US)
+    const cost = Math.floor(tokensRequested) * interval
+    if (cost > limit) return false
 
-      let availableTokens = currentTokens
-      const elapsed = Math.max(0, nowSec - lastTime)
-      if (elapsed > 0) {
-        availableTokens = Math.min(
-          maxTokens,
-          currentTokens + elapsed * refillRatePerSec,
-        )
+    const now = Math.floor(nowMs) * 1000
+    for (;;) {
+      const raw = Atomics.load(this.rateLimits, slot)
+      const stored = Number(raw)
+      const next = (stored > now ? stored : now) + cost
+      if (next - now > limit) return false
+      if (
+        Atomics.compareExchange(this.rateLimits, slot, raw, BigInt(next)) ===
+        raw
+      ) {
+        return true
       }
+    }
+  }
 
-      if (availableTokens < tokensRequested) {
-        if (elapsed > 0) {
-          Atomics.compareExchange(this.rateLimits, timeIndex, lastTime, nowSec)
-          Atomics.compareExchange(
-            this.rateLimits,
-            tokenIndex,
-            currentTokens,
-            availableTokens,
-          )
-        }
-        return false
-      }
+  /**
+   * Give back tokens a `consumeToken` call took, never past a full bucket.
+   *
+   * For a request that turned out not to count. The limiter has to charge
+   * before routing, since admitting first and charging later lets a burst of
+   * any size through at once, and whether a request was an asset is only
+   * known once the handler that served it says so.
+   */
+  refundToken(
+    slot: number,
+    refillRatePerSec: number,
+    tokens = 1,
+    nowMs: number = Date.now(),
+  ): void {
+    if (slot < 0 || slot >= RATE_LIMIT_SLOT_COUNT) return
+    if (!(refillRatePerSec > 0 && tokens > 0)) return
 
-      const newTokens = availableTokens - tokensRequested
+    const back = Math.floor(tokens) * tokenInterval(refillRatePerSec)
+    const now = Math.floor(nowMs) * 1000
+    for (;;) {
+      const raw = Atomics.load(this.rateLimits, slot)
+      const stored = Number(raw)
+      // Already full: there is nothing to give back, and moving the arrival
+      // time up to `now` would be a charge.
+      if (stored <= now) return
+      const next = Math.max(stored - back, now)
       if (
-        Atomics.compareExchange(
-          this.rateLimits,
-          tokenIndex,
-          currentTokens,
-          newTokens,
-        ) === currentTokens
+        Atomics.compareExchange(this.rateLimits, slot, raw, BigInt(next)) ===
+        raw
       ) {
-        if (elapsed > 0) {
-          Atomics.compareExchange(this.rateLimits, timeIndex, lastTime, nowSec)
-        }
-        return true
+        return
       }
     }
   }