galbe 0.15.6 → 0.16.0

package/src/middlewares/rateLimit.ts

@@ -0,0 +1,153 @@
+import type { MiddlewareDef, PreParseContext, PreParseHook } from '../types'
+import type { MaybePromise } from './_auth'
+
+import { TooManyRequestsError } from '../types'
+
+/** All a rejection knows about itself, and all an `errorHandler` is given. */
+export type RateLimitInfo = {
+  /** Bucket the request was accounted to — whatever `key` returned. */
+  key: string
+  /** Requests allowed per window, as configured. */
+  limit: number
+  /** Whole seconds until the request would be allowed through, at least `1`. */
+  retryAfter: number
+}
+
+export type RateLimitConfig = {
+  /** Requests allowed per `window`, and the burst a client may spend at once. */
+  limit: number
+  /** Seconds the bucket takes to refill completely. Fractional values are allowed. */
+  window: number
+  /**
+   * Bucket a request is accounted to. Defaults to `ctx.clientAddress`, which is
+   * the socket peer unless [`trustProxy`](https://galbe.dev/documentation/configuration#trustproxy)
+   * is configured — set it, or every client behind your proxy shares one bucket.
+   *
+   * Returning nothing exempts the request: that is how an allow-list, an
+   * internal caller or an authenticated tier opts out.
+   */
+  key?: (ctx: PreParseContext) => string | undefined | null
+  /**
+   * Maximum number of buckets held in memory. Default `10000`. Reaching it
+   * evicts refilled buckets first, then the least recently created one.
+   */
+  maxKeys?: number
+  /** Emit the `RateLimit-*` response headers. Default `true`. */
+  headers?: boolean
+  /**
+   * Replaces the default `429`. Return a `Response` to answer the request, or
+   * nothing to fall back to the default `429`; throwing takes the usual error
+   * handler path. A `Response` of your own carries no `Retry-After` unless you
+   * set one.
+   */
+  errorHandler?: (info: RateLimitInfo, ctx: PreParseContext) => MaybePromise<Response | void>
+}
+
+type Bucket = { tokens: number; updated: number }
+
+const DEFAULT_MAX_KEYS = 10_000
+/** Buckets examined per eviction: bounded work, so one request cannot pay for a full scan. */
+const SWEEP = 16
+
+/**
+ * #### rateLimit
+ * Caps how often one client may call the routes it covers, as a token bucket:
+ * every key gets `limit` tokens refilled smoothly over `window` seconds, a
+ * request spends one, and a request that finds none is answered **429** with a
+ * `Retry-After`. Spending them all at once is allowed — the burst a client may
+ * take is the limit itself.
+ *
+ * It runs in the [`beforeParse`](https://galbe.dev/documentation/middleware#before-parsing)
+ * slot, so a throttled request is rejected **before its body is read**.
+ *
+ * Counters live in this process's memory, so each instance is its own limiter
+ * and each replica of your app enforces the limit on its own — `n` replicas
+ * mean `n` × `limit`. It also only covers **routed** paths: a flood against URLs
+ * that match no route never reaches a middleware. Neither is a reason to skip
+ * it, but a public-facing service wants a limiter at the edge as well.
+ *
+ * ---
+ * @example
+ * ```typescript
+ * import { rateLimit } from 'galbe/middlewares'
+ *
+ * // 100 requests per minute per client, everywhere
+ * galbe.middleware(rateLimit({ limit: 100, window: 60 }))
+ *
+ * // a tighter bucket on top, for one subtree — each instance counts on its own
+ * galbe.middleware('/auth/*', rateLimit({ limit: 5, window: 60 }))
+ *
+ * // per account rather than per address, with signed-in users exempt from it
+ * galbe.middleware('/api/*', rateLimit({
+ *   limit: 1000,
+ *   window: 3600,
+ *   key: ctx => ctx.state.apiKey?.accountId
+ * }))
+ * ```
+ * @param config - see {@link RateLimitConfig}
+ */
+export const rateLimit = (config: RateLimitConfig): MiddlewareDef<{}> => {
+  const { limit, window } = config
+  if (!Number.isFinite(limit) || limit < 1) throw new SyntaxError('rateLimit: limit must be at least 1')
+  if (!Number.isFinite(window) || window <= 0) throw new SyntaxError('rateLimit: window must be a positive number')
+  const maxKeys = config.maxKeys ?? DEFAULT_MAX_KEYS
+  if (!Number.isInteger(maxKeys) || maxKeys < 1) throw new SyntaxError('rateLimit: maxKeys must be a positive integer')
+  const keyOf = config.key ?? ((ctx: PreParseContext) => ctx.clientAddress)
+  const rate = limit / window // tokens per second
+  const buckets = new Map<string, Bucket>()
+  // monotonic: a clock adjustment must not hand out tokens or freeze a bucket
+  const seconds = () => performance.now() / 1000
+
+  /**
+   * Keeps the store bounded, the same discipline as the router cache — a flood
+   * of distinct keys must never grow it without limit. Refilled buckets go
+   * first, as they say nothing a fresh one would not; only when the sweep frees
+   * none does the oldest bucket go.
+   */
+  const evict = (now: number) => {
+    let swept = 0
+    let freed = false
+    for (const [key, bucket] of buckets) {
+      if (swept++ >= SWEEP) break
+      if (bucket.tokens + (now - bucket.updated) * rate >= limit) {
+        buckets.delete(key)
+        freed = true
+      }
+    }
+    if (!freed) buckets.delete(buckets.keys().next().value as string)
+  }
+
+  /** Refills the key's bucket up to `now`, then spends a token if there is one. */
+  const consume = (key: string, now: number) => {
+    let bucket = buckets.get(key)
+    if (bucket) bucket.tokens = Math.min(limit, bucket.tokens + (now - bucket.updated) * rate)
+    else {
+      if (buckets.size >= maxKeys) evict(now)
+      buckets.set(key, (bucket = { tokens: limit, updated: now }))
+    }
+    bucket.updated = now
+    const allowed = bucket.tokens >= 1
+    if (allowed) bucket.tokens -= 1
+    return { allowed, tokens: bucket.tokens }
+  }
+
+  const beforeParse: PreParseHook = async ctx => {
+    const key = keyOf(ctx)
+    if (!key) return
+    const { allowed, tokens } = consume(key, seconds())
+    if (config.headers !== false) {
+      ctx.set.headers['ratelimit-limit'] = String(limit)
+      ctx.set.headers['ratelimit-remaining'] = String(Math.floor(tokens))
+      ctx.set.headers['ratelimit-reset'] = String(Math.ceil((limit - tokens) / rate))
+    }
+    if (allowed) return
+    // a bucket below one token needs that fraction of a second back; HTTP
+    // counts Retry-After in whole seconds, so it always asks for at least one
+    const retryAfter = Math.ceil((1 - tokens) / rate)
+    const handled = await config.errorHandler?.({ key, limit, retryAfter }, ctx)
+    if (handled) return handled
+    throw new TooManyRequestsError(undefined, { 'retry-after': String(retryAfter) })
+  }
+
+  return { beforeParse }
+}

package/src/middlewares/requestId.ts

@@ -0,0 +1,94 @@
+import type { MiddlewareDef, PreParseHook } from '../types'
+import type { STOptional, STString } from '../schema'
+
+import { $T } from '../index'
+
+/**
+ * What an id may be made of: enough for UUIDs, ULIDs, nanoids and W3C trace
+ * ids, and nothing that could break a header or a log line. An inbound id that
+ * does not match is replaced rather than rejected — a malformed trace header is
+ * not the caller's request failing.
+ */
+const ID = /^[\w.:-]{1,128}$/
+
+export type RequestIdConfig<N extends string = 'x-request-id', T extends boolean = true> = {
+  /** Header the id travels in, inbound and outbound. Default `x-request-id`. */
+  header?: N
+  /**
+   * Reuse a well-formed id sent by the caller, so one trace spans the services
+   * it passes through. Default `true`. Set it to `false` at the edge of a
+   * public API, where the id is the caller's to choose and yours to distrust.
+   */
+  trustHeader?: T
+  /**
+   * Makes an id when there is none to reuse. Default `crypto.randomUUID()`.
+   * It must satisfy the same shape an inbound id does, since it ends up in a
+   * response header and in your logs.
+   */
+  generate?: () => string
+  /** `ctx.state` key the id is stored under. Default `requestId`. */
+  stateHolder?: string
+}
+
+/** The header contract a trusting `requestId` instance imposes; a distrusting one reads nothing and declares nothing. */
+export type RequestIdFragment<N extends string, T extends boolean> = T extends false
+  ? {}
+  : { headers: Record<N, STOptional<STString>> }
+
+/**
+ * #### requestId
+ * Gives every request an id — the caller's, when it sent a usable one, and a
+ * fresh UUID otherwise — puts it on `ctx.state.requestId` and echoes it in the
+ * response header. That id is what ties a log line, a trace and a support
+ * ticket to one another.
+ *
+ * It runs in the [`beforeParse`](https://galbe.dev/documentation/middleware#before-parsing)
+ * slot so the id exists before anything can reject the request: a `400` from
+ * validation or a `401` from an auth middleware registered after it carries the
+ * header too. Register it first for that reason.
+ *
+ * ---
+ * @example
+ * ```typescript
+ * import { requestId } from 'galbe/middlewares'
+ *
+ * galbe.middleware(requestId())
+ *
+ * galbe.get('/orders', ctx => {
+ *   log.info({ id: ctx.state.requestId }, 'listing orders')
+ *   return orders()
+ * })
+ * ```
+ * @param config - see {@link RequestIdConfig}
+ */
+export const requestId = <N extends string = 'x-request-id', T extends boolean = true>(
+  config: RequestIdConfig<N, T> = {}
+): MiddlewareDef<RequestIdFragment<N, T>> => {
+  const header: string = config.header ?? 'x-request-id'
+  const stateHolder = config.stateHolder ?? 'requestId'
+  const generate = config.generate ?? (() => crypto.randomUUID())
+  const trusted = config.trustHeader !== false
+
+  const beforeParse: PreParseHook = ctx => {
+    const inbound = trusted ? ctx.request.headers.get(header) : null
+    let id: string
+    if (inbound && ID.test(inbound)) id = inbound
+    else {
+      id = generate()
+      // `generate` is caller code and the value becomes a response header:
+      // name the culprit here rather than let the Headers constructor reject it
+      // with a type error three frames away
+      if (typeof id !== 'string' || !ID.test(id))
+        throw new Error(
+          `requestId: generate() must return at most 128 characters of [A-Za-z0-9_.:-], got ${JSON.stringify(id)?.slice(0, 64)}`
+        )
+    }
+    ctx.state[stateHolder] = id
+    ctx.set.headers[header] = id
+  }
+
+  return {
+    beforeParse,
+    ...(trusted ? { schema: { headers: { [header]: $T.optional($T.string()) } } } : {}),
+  } as MiddlewareDef<RequestIdFragment<N, T>>
+}

package/src/middlewares/timing.ts

@@ -0,0 +1,86 @@
+import type { Context, MiddlewareDef, PreParseHook, ResponseHook } from '../types'
+
+export type TimingConfig = {
+  /** Name of the measurement, a `Server-Timing` token. Default `total`. */
+  name?: string
+  /** Label shown next to the measurement in a browser's network panel. */
+  description?: string
+  /** Decimal places kept in the reported duration. Default `1`. */
+  precision?: number
+  /** Response header the measurement is appended to. Default `server-timing`. */
+  header?: string
+  /**
+   * Leaves a request unmeasured. It runs once the request is done, so the
+   * response status is readable and a filter can keep only the slow or the
+   * failing ones.
+   */
+  skip?: (ctx: Context) => boolean
+}
+
+/** `Server-Timing` names are tokens: anything else would end the entry early. */
+const token = (name: string) => name.replace(/[^\w-]/g, '-')
+
+/**
+ * #### timing
+ * Reports how long the server spent on a request, in the
+ * [`Server-Timing`](https://developer.mozilla.org/docs/Web/HTTP/Headers/Server-Timing)
+ * header — the number a browser shows in its network panel, and the one a
+ * caller cannot measure itself, since its own clock also counts the network.
+ *
+ * The entry is **appended**, so measurements a route added to the same header
+ * survive alongside it. It measures the whole request: the clock starts in the
+ * `beforeParse` slot and the entry is written once a `Response` exists, so a
+ * request rejected before the hook chain — a `400` from validation, a `401`
+ * from an auth middleware — is measured too. A request that matched no route is
+ * not: a middleware runs per route, never for a `404`.
+ *
+ * The header is public, and so is what it says about your internals. Keep the
+ * names generic on a public API, or restrict it to development with `skip`.
+ *
+ * ---
+ * @example
+ * ```typescript
+ * import { timing } from 'galbe/middlewares'
+ *
+ * galbe.middleware(timing())
+ * // → Server-Timing: total;dur=12.4
+ *
+ * galbe.middleware('/api/*', timing({ name: 'api', description: 'handler', precision: 2 }))
+ * // → Server-Timing: api;dur=12.41;desc="handler"
+ * ```
+ * @param config - see {@link TimingConfig}
+ */
+export const timing = (config: TimingConfig = {}): MiddlewareDef<{}> => {
+  const precision = config.precision ?? 1
+  if (!Number.isInteger(precision) || precision < 0 || precision > 6)
+    throw new SyntaxError('timing: precision must be an integer between 0 and 6')
+  const description = config.description
+  if (description !== undefined && /["\\\x00-\x1f\x7f]/.test(description))
+    throw new SyntaxError('timing: description must not contain quotes, backslashes or control characters')
+  const header = token(config.header ?? 'server-timing').toLowerCase()
+  const name = token(config.name ?? 'total')
+  const suffix = description ? `;desc="${description}"` : ''
+
+  // the clock lives beside the request rather than on `ctx.state`, which is a
+  // public `Record<string, any>`: an internal marker has no business in a dump
+  // of it, and two instances on one route keep their own
+  const starts = new WeakMap<object, number>()
+
+  const beforeParse: PreParseHook = ctx => {
+    starts.set(ctx, performance.now())
+  }
+
+  const afterHandle: ResponseHook = (response, ctx) => {
+    const start = starts.get(ctx)
+    // the post slot also runs for a request answered before the pre slot did —
+    // a plugin that threw while routing — where there is no clock to read
+    if (typeof start !== 'number' || config.skip?.(ctx)) return
+    const entry = `${name};dur=${(performance.now() - start).toFixed(precision)}${suffix}`
+    // append to whatever the response already carries, so a measurement a route
+    // added to the same header survives alongside this one
+    const measured = response.headers.get(header)
+    response.headers.set(header, measured ? `${measured}, ${entry}` : entry)
+  }
+
+  return { beforeParse, afterHandle }
+}

package/src/middlewares.ts

@@ -0,0 +1,53 @@
+/**
+ * #### galbe/middlewares
+ * Built-in middlewares: request contracts, security metadata and hooks, ready
+ * to register. Each one is a plain {@link MiddlewareDef}, so it is accepted
+ * everywhere a hook is — `galbe.middleware`, `galbe.group`, or the default
+ * export of a `*.middleware.ts` file.
+ *
+ * Every middleware is also importable on its own path (`galbe/middlewares/jwt`)
+ * for apps that would rather not load the whole set.
+ *
+ * ---
+ * @example
+ * ```typescript
+ * import { jwt } from 'galbe/middlewares'
+ *
+ * galbe.middleware('/api/*', jwt({ key: Bun.env.JWT_SECRET! }))
+ * ```
+ */
+export { AuthError } from './middlewares/_auth'
+export type { AuthErrorCode, AuthErrorHandler } from './middlewares/_auth'
+
+export { jwt, JwtError, signJwt } from './middlewares/jwt'
+export type {
+  JwtAlgorithm,
+  JwtConfig,
+  JwtErrorCode,
+  JwtFragment,
+  JwtKey,
+  JwtPayload,
+  JwtSignOptions,
+  JwtSource,
+} from './middlewares/jwt'
+
+export { bearer } from './middlewares/bearer'
+export type { BearerConfig, BearerFragment } from './middlewares/bearer'
+
+export { apiKey } from './middlewares/apiKey'
+export type { ApiKeyConfig, ApiKeyFragment } from './middlewares/apiKey'
+
+export { basicAuth } from './middlewares/basicAuth'
+export type { BasicAuthConfig, BasicAuthFragment } from './middlewares/basicAuth'
+
+export { rateLimit } from './middlewares/rateLimit'
+export type { RateLimitConfig, RateLimitInfo } from './middlewares/rateLimit'
+
+export { requestId } from './middlewares/requestId'
+export type { RequestIdConfig, RequestIdFragment } from './middlewares/requestId'
+
+export { logger } from './middlewares/logger'
+export type { LogEntry, LoggerConfig } from './middlewares/logger'
+
+export { timing } from './middlewares/timing'
+export type { TimingConfig } from './middlewares/timing'