@c9up/ream 0.2.12 → 0.2.14

package/src/bodyparser/MultipartFile.ts

@@ -1,3 +1,51 @@
+/**
+ * The top-level mime types IANA registers.
+ *
+ * Closed on purpose. Typing {@link MultipartFile.type} as a bare `string` let
+ * `file.type === 'image/png'` compile and quietly never match — a mime filter
+ * that passes everything, which is the shape a comment used to warn about and
+ * a compiler can simply refuse. Against this union that comparison is an
+ * error, and {@link MultipartFile.mime} is what a full-mime check wants.
+ *
+ * A top-level type outside this list is malformed: an unregistered format
+ * belongs under one of these trees, `application/x-…` rather than `x-foo/bar`.
+ *
+ * Additive, not a replacement: {@link MultipartFile.type} keeps upstream's
+ * `string` and its raw segment, and {@link MultipartFile.registeredType}
+ * narrows it here for callers who want `=== 'image/png'` refused at compile
+ * time. Nothing a valid AdonisJS call site does stops compiling, and no type
+ * outside this set is swallowed — closing `type` itself would have done both.
+ */
+export type MimeType =
+  | 'application'
+  | 'audio'
+  | 'example'
+  | 'font'
+  | 'image'
+  | 'message'
+  | 'model'
+  | 'multipart'
+  | 'text'
+  | 'video'
+
+const MIME_TYPES = new Set<string>([
+  'application',
+  'audio',
+  'example',
+  'font',
+  'image',
+  'message',
+  'model',
+  'multipart',
+  'text',
+  'video',
+])
+
+/** Whether a parsed top-level type is one IANA registers. */
+function isMimeType(value: string): value is MimeType {
+  return MIME_TYPES.has(value)
+}
+
 /**
  * MultipartFile — represents an uploaded file.
  *
@@ -28,14 +76,32 @@ export class MultipartFile {
    * `image/png` would otherwise sail through a mime allowlist. A renamed file
    * reports what it actually is.
    *
-   * BREAKING as of 0.2.0: it used to hold the whole `image/png`. TypeScript
-   * cannot catch a comparison against a full mime string — `file.type ===
-   * 'image/png'` still compiles and simply never matches. Use {@link mime}.
+   * BREAKING as of 0.2.0: it used to hold the whole `image/png`. A comparison
+   * against a full mime — `file.type === 'image/png'` — compiles and never
+   * matches, which is what {@link mime} exists for, and what
+   * {@link registeredType} refuses at compile time for callers who want that.
+   *
+   * `string` and the raw segment, as upstream: a type outside the registered
+   * set is still reported rather than swallowed.
    */
   get type(): string | undefined {
     return this.#mimeParts()[0]
   }
 
+  /**
+   * The same primary type, narrowed to what IANA registers.
+   *
+   * Additive, and the point of it: against a closed union
+   * `file.registeredType === 'image/png'` is a compile error instead of a
+   * comparison that always fails. `undefined` where {@link type} holds
+   * something outside the set — a malformed or unregistered tree — so the two
+   * disagree exactly there and nowhere else.
+   */
+  get registeredType(): MimeType | undefined {
+    const type = this.#mimeParts()[0]
+    return type !== undefined && isMimeType(type) ? type : undefined
+  }
+
   /** The mime SUBTYPE — `png` for `image/png`. Same source as {@link type}. */
   get subtype(): string | undefined {
     return this.#mimeParts()[1]
@@ -297,7 +363,7 @@ export class MultipartFile {
    * passing `file.clientName` straight through.
    */
   async move(location: string, options?: { name?: string; overwrite?: boolean }): Promise<void> {
-    const { mkdir, writeFile, access } = await import('node:fs/promises')
+    const { mkdir, writeFile } = await import('node:fs/promises')
     const { join } = await import('node:path')
 
     const name = options?.name ?? `${randomBytes(16).toString('hex')}.${this.extname || 'unknown'}`
@@ -308,20 +374,28 @@ export class MultipartFile {
     }
 
     const filePath = join(location, name)
-    if (options?.overwrite === false) {
-      const exists = await access(filePath).then(
-        () => true,
-        () => false,
-      )
-      if (exists) {
+    await mkdir(location, { recursive: true })
+
+    // NAMED DEVIATION — the refusal is ATOMIC where upstream's is not.
+    //
+    // Upstream checks `pathExists` and then renames, so two uploads landing on
+    // the same name both see nothing and both succeed: the second silently
+    // replaces the first, which is the one thing `overwrite: false` exists to
+    // prevent. `wx` is O_EXCL — the kernel decides, and exactly one of the two
+    // writes wins.
+    //
+    // The message is upstream's, word for word: a caller matching on it keeps
+    // working, and only the race is gone.
+    try {
+      await writeFile(filePath, this.content, options?.overwrite === false ? { flag: 'wx' } : {})
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
         throw new Error(
           `"${name}" already exists at "${location}". Set "overwrite = true" to overwrite it`,
         )
       }
+      throw error
     }
-
-    await mkdir(location, { recursive: true })
-    await writeFile(filePath, this.content)
     this.markAsMoved(name, filePath)
   }
 

package/src/container/Container.ts

@@ -32,8 +32,8 @@ const RESERVED_TOKEN_NAMES = new Set(['__proto__', 'constructor', 'prototype'])
 
 /** One resolution chain: the tokens on it, and a set for O(1) membership. */
 interface ResolutionChain {
-  stack: string[]
-  set: Set<string>
+  stack: ServiceToken[]
+  set: Set<ServiceToken>
   /**
    * Values bound on the {@link ContainerResolver} that opened this chain.
    *
@@ -42,7 +42,7 @@ interface ResolutionChain {
    * a controller's constructor dependency sees the same `HttpContext` the
    * middleware bound — and to nothing outside it.
    */
-  values?: ReadonlyMap<string, unknown>
+  values?: ReadonlyMap<ServiceToken, unknown>
   /**
    * How many scoped values this chain has handed out so far.
    *
@@ -69,8 +69,8 @@ interface ResolutionChain {
 }
 
 export class Container {
-  #bindings: Map<string, Binding> = new Map()
-  #singletons: Map<string, unknown> = new Map()
+  #bindings: Map<ServiceToken, Binding> = new Map()
+  #singletons: Map<ServiceToken, unknown> = new Map()
   /**
    * Singletons currently being built, by key.
    *
@@ -79,22 +79,22 @@ export class Container {
    * point is one, and silently discarding the first (a second connection
    * pool, a second scheduler). Concurrent callers await the same promise.
    */
-  #pendingSingletons: Map<string, Promise<unknown>> = new Map()
-  #overrides: Map<string, ServiceFactory> = new Map()
+  #pendingSingletons: Map<ServiceToken, Promise<unknown>> = new Map()
+  #overrides: Map<ServiceToken, ServiceFactory> = new Map()
   /**
    * Snapshot of singletons taken when `swap`/`override` shadows a previously
    * resolved instance. `restore()` re-seats them without re-invoking the
    * original factory, so callers that captured the live reference keep
    * pointing at the same object after the test ends.
    */
-  #singletonBackup: Map<string, unknown> = new Map()
+  #singletonBackup: Map<ServiceToken, unknown> = new Map()
   /** Alias key → the token it forwards to (AdonisJS `container.alias`). */
-  #aliases: Map<string, ServiceToken> = new Map()
+  #aliases: Map<ServiceToken, ServiceToken> = new Map()
   /** parent class → (binding key → the factory that class gets instead). */
-  #contextualBindings: Map<new (...args: never[]) => unknown, Map<string, ServiceFactory>> =
+  #contextualBindings: Map<new (...args: never[]) => unknown, Map<ServiceToken, ServiceFactory>> =
     new Map()
   /** token key → post-resolution callbacks (AdonisJS `container.resolving`). */
-  #resolvingHooks: Map<string, Array<(value: unknown) => void | Promise<void>>> = new Map()
+  #resolvingHooks: Map<ServiceToken, Array<(value: unknown) => void | Promise<void>>> = new Map()
   /**
    * The resolution chain currently being walked, for cycle detection.
    *
@@ -176,7 +176,7 @@ export class Container {
     else this.#resolvingHooks.set(key, [callback])
   }
 
-  async #runResolvingHooks(key: string, value: unknown): Promise<void> {
+  async #runResolvingHooks(key: ServiceToken, value: unknown): Promise<void> {
     const hooks = this.#resolvingHooks.get(key)
     if (hooks) for (const hook of hooks) await hook(value)
   }
@@ -235,7 +235,7 @@ export class Container {
     }
   }
 
-  #restoreOne(key: string): void {
+  #restoreOne(key: ServiceToken): void {
     this.#overrides.delete(key)
     this.#singletons.delete(key)
     if (this.#singletonBackup.has(key)) {
@@ -272,7 +272,7 @@ export class Container {
     // `alias('b','a')` overflowed the stack instead of naming the cycle.
     let resolvedToken = token
     let key = this.#tokenToKey(resolvedToken)
-    const seenAliases = new Set<string>([key])
+    const seenAliases = new Set<ServiceToken>([key])
     for (
       let target = this.#aliases.get(key);
       target !== undefined;
@@ -281,7 +281,7 @@ export class Container {
       resolvedToken = target
       key = this.#tokenToKey(target)
       if (seenAliases.has(key)) {
-        const cycle = [...seenAliases, key].join(' → ')
+        const cycle = [...seenAliases, key].map(describeToken).join(' → ')
         throw new ReamError('E_CIRCULAR_DEPENDENCY', `Circular alias detected: ${cycle}`, {
           hint: 'An alias chain must end at a real binding — remove one of the aliases.',
           context: { chain: cycle },
@@ -301,7 +301,7 @@ export class Container {
     }
 
     if (chain.set.has(key)) {
-      const cycle = [...chain.stack, key].join(' → ')
+      const cycle = [...chain.stack, key].map(describeToken).join(' → ')
       throw new ReamError('E_CIRCULAR_DEPENDENCY', `Circular dependency detected: ${cycle}`, {
         hint: 'Break the cycle by resolving one dependency lazily inside a method (`await container.make(Dep)`) instead of injecting it in the constructor.',
         context: { chain: cycle },
@@ -401,7 +401,10 @@ export class Container {
    * Reuses an open chain rather than starting a second one, so cycle detection
    * still spans the whole resolution when a resolver is used inside a factory.
    */
-  runWithScopedValues<T>(values: ReadonlyMap<string, unknown>, fn: () => Promise<T>): Promise<T> {
+  runWithScopedValues<T>(
+    values: ReadonlyMap<ServiceToken, unknown>,
+    fn: () => Promise<T>,
+  ): Promise<T> {
     const chain = this.#chain.getStore()
     return this.#chain.run(
       chain === undefined ? { stack: [], set: new Set(), values } : { ...chain, values },
@@ -409,8 +412,8 @@ export class Container {
     )
   }
 
-  /** @internal Normalise a token the way the container keys it. */
-  keyFor(token: ServiceToken): string {
+  /** @internal Validate a token and hand back the value the container keys on. */
+  keyFor(token: ServiceToken): ServiceToken {
     return this.#tokenToKey(token)
   }
 
@@ -434,6 +437,41 @@ export class Container {
 
   // ─── Introspection ────────────────────────────────────────
 
+  /**
+   * Every token the container holds, sorted, with the kind beside it.
+   *
+   * `ream inspect` advertised a section for these and rendered none, because
+   * nothing could enumerate them — `has()` answers about one token you already
+   * know the name of, which is no help when the question is what is in there.
+   *
+   * These are bindings, not every `@inject()`-decorated class: a decorated
+   * class is discovered when it is resolved, and nothing registers it before
+   * that, so no complete list of those exists to return.
+   */
+  get bindings(): ReadonlyArray<{ token: string; scope: string; target?: string }> {
+    const seen = new Map<ServiceToken, { scope: string; target?: string }>()
+    for (const [key, binding] of this.#bindings) seen.set(key, { scope: binding.scope })
+    for (const key of this.#singletons.keys()) {
+      if (!seen.has(key)) seen.set(key, { scope: 'value' })
+    }
+    // Aliases LAST and overwriting, because that is the order `resolve()` uses:
+    // it follows an alias before it ever looks at a binding. Reporting the
+    // binding for a token that also has an alias showed a definition nobody
+    // gets — `service` listed as transient while resolving it hands back
+    // `target`. Where both exist the alias is what runs, and the binding it
+    // shadows is named beside it rather than dropped.
+    for (const [key, target] of this.#aliases) {
+      const shadowed = seen.get(key)
+      seen.set(key, {
+        scope: shadowed === undefined ? 'alias' : `alias (shadows ${shadowed.scope})`,
+        target: describeToken(target),
+      })
+    }
+    return [...seen.entries()]
+      .map(([token, entry]) => ({ token: describeToken(token), ...entry }))
+      .sort((a, b) => a.token.localeCompare(b.token))
+  }
+
   /** Check if a token is registered or resolvable. */
   has(token: ServiceToken): boolean {
     const key = this.#tokenToKey(token)
@@ -472,7 +510,7 @@ export class Container {
   /** Auto-register all @Service() decorated classes from the global registry. */
   autoRegister(): void {
     for (const [target, metadata] of getServiceRegistry()) {
-      const key = metadata.as ?? target.name
+      const key = metadata.as ?? target
       if (!this.#bindings.has(key)) {
         const targetClass = target
         this.#bindings.set(key, {
@@ -487,7 +525,11 @@ export class Container {
 
   // ─── Internal resolution ──────────────────────────────────
 
-  async #resolveInner<T>(key: string, token: ServiceToken, runtimeValues?: unknown[]): Promise<T> {
+  async #resolveInner<T>(
+    key: ServiceToken,
+    token: ServiceToken,
+    runtimeValues?: unknown[],
+  ): Promise<T> {
     // 1. Check swaps (test overrides) — a swap factory may be async.
     if (this.#overrides.has(key)) {
       const swapped = await this.#overrides.get(key)?.(this)
@@ -562,11 +604,12 @@ export class Container {
     }
 
     // 7. Not found
-    const allKeys = [...this.#bindings.keys(), ...this.#overrides.keys()]
-    const suggestion = didYouMean(key, allKeys)
+    const name = describeToken(key)
+    const allKeys = [...this.#bindings.keys(), ...this.#overrides.keys()].map(describeToken)
+    const suggestion = didYouMean(name, allKeys)
     throw new ReamError(
       'E_CONTAINER_NOT_FOUND',
-      `No binding found for '${key}'.${suggestion ? ` ${suggestion}` : ''}`,
+      `No binding found for '${name}'.${suggestion ? ` ${suggestion}` : ''}`,
       {
         hint: 'Register it with container.singleton() or decorate with @inject().',
       },
@@ -604,7 +647,9 @@ export class Container {
   ): Promise<unknown> {
     const metadata = getServiceMetadata(target)
     const scope = metadata?.scope ?? 'transient'
-    const key = metadata?.as ?? target.name
+    // The class itself, not `target.name`: two classes called `Service` share a
+    // name and must not share a singleton cache entry.
+    const key = metadata?.as ?? target
 
     if (scope === 'singleton' && this.#singletons.has(key)) {
       return this.#singletons.get(key)
@@ -712,7 +757,7 @@ export class Container {
    */
   #cacheIfAppWide(
     scope: string,
-    key: string,
+    key: ServiceToken,
     instance: unknown,
     store: ResolutionChain | undefined,
     readsBefore: number,
@@ -722,39 +767,36 @@ export class Container {
     this.#singletons.set(key, instance)
   }
 
-  #tokenToKey(token: ServiceToken): string {
-    if (typeof token === 'string') {
-      this.#assertNotReserved(token, 'string')
-      return token
-    }
-    if (typeof token === 'symbol') {
-      // Reject unique `Symbol(x)` — two `Symbol("foo")` calls create distinct
-      // symbols, so an override registered with one would be invisible to a
-      // resolver holding the other. Force callers onto `Symbol.for(x)` which
-      // is the global registry and round-trips across modules.
-      if (Symbol.keyFor(token) === undefined) {
-        throw new ReamError(
-          'E_CONTAINER_INVALID_TOKEN',
-          `Unique Symbol() tokens are not supported — use Symbol.for("${token.description ?? 'name'}") so different modules see the same symbol.`,
-        )
-      }
-      const desc = token.description
-      if (desc === undefined) {
-        throw new ReamError('E_CONTAINER_INVALID_TOKEN', 'Symbol tokens must have a description.')
-      }
-      this.#assertNotReserved(desc, 'symbol description')
-      return `Symbol(${desc})`
-    }
-    return token.name
+  /**
+   * Validate a token and hand back the value every map keys on: the token.
+   *
+   * Fold's stores are `Map<string | symbol | AbstractConstructor, …>`, so a
+   * token IS its own key and identity is preserved. Deriving a string key
+   * instead cost exactly what identity buys: `Symbol.for('cache')` became
+   * `"Symbol(cache)"` and collided with the plain string `"Symbol(cache)"`,
+   * and a unique `Symbol()` had to be refused because its description is all a
+   * string key can carry. Both go away when the token is the key.
+   */
+  #tokenToKey(token: ServiceToken): ServiceToken {
+    if (typeof token === 'string') this.#assertNotReserved(token)
+    return token
   }
 
-  #assertNotReserved(name: string, kind: 'string' | 'symbol description'): void {
+  /**
+   * NAMED DEVIATION from Fold, kept deliberately.
+   *
+   * These three read as prototype keys, and a token named after one is far
+   * likelier to be a mistake than a deliberate binding. Nothing indexes tokens
+   * on a plain object any more — every store above is a `Map` — so this is a
+   * tripwire for a caller error, not a pollution guard.
+   */
+  #assertNotReserved(name: string): void {
     if (RESERVED_TOKEN_NAMES.has(name)) {
       throw new ReamError(
         'E_CONTAINER_RESERVED_TOKEN',
         `Reserved container token name '${name}'.`,
         {
-          hint: `'${name}' would collide with an Object.prototype key. Pick a different ${kind}.`,
+          hint: `'${name}' reads as an Object.prototype key. Pick a different token name.`,
         },
       )
     }
@@ -781,6 +823,18 @@ const NON_INJECTABLE_CONSTRUCTORS = new Set<unknown>([
   Error,
 ])
 
+/**
+ * A token as it reads in an error message or in `ream inspect`.
+ *
+ * Display only — the container keys on the token itself, so two distinct
+ * classes that share a name are two bindings that happen to print alike.
+ */
+function describeToken(token: ServiceToken): string {
+  if (typeof token === 'string') return token
+  if (typeof token === 'symbol') return token.toString()
+  return token.name === '' ? 'AnonymousClass' : token.name
+}
+
 /** True for a real, injectable class token (excludes native primitive constructors). */
 function isInjectableClass(value: unknown): value is new (...args: never[]) => unknown {
   return typeof value === 'function' && !NON_INJECTABLE_CONSTRUCTORS.has(value)

package/src/container/ContainerResolver.ts

@@ -20,7 +20,7 @@ import type { ServiceToken } from './types.js'
 export class ContainerResolver {
   readonly #container: Container
   /** Values bound here, keyed the way the container keys its tokens. */
-  readonly #values = new Map<string, unknown>()
+  readonly #values = new Map<ServiceToken, unknown>()
 
   constructor(container: Container) {
     this.#container = container

package/src/errors/PipelineStageError.ts

@@ -6,8 +6,14 @@
 
 import { ReamError } from './ReamError.js'
 
-/** Pipeline stage names in execution order. */
-export const E_PIPELINE_STAGES = [
+/**
+ * Pipeline stage names in execution order.
+ *
+ * NOT an error code, despite living beside them — it is the list of stages, and
+ * an application imports it by this name. The `E_` prefix belongs to codes
+ * alone; a rename here breaks a public import for nothing.
+ */
+export const PIPELINE_STAGES = [
   'Security (Blackhole)',
   'Logging',
   'Global Middleware',
@@ -20,12 +26,12 @@ export const E_PIPELINE_STAGES = [
   'Response Logging',
 ] as const
 
-export type PipelineStageName = (typeof E_PIPELINE_STAGES)[number]
+export type PipelineStageName = (typeof PIPELINE_STAGES)[number]
 
 /**
  * Create a pipeline stage error with position context.
  *
- * @param stageIndex - Zero-based index in E_PIPELINE_STAGES (clamped to valid range)
+ * @param stageIndex - Zero-based index in PIPELINE_STAGES (clamped to valid range)
  * @param originalError - The error that occurred
  * @param context - Additional context
  */
@@ -34,11 +40,11 @@ export function createPipelineError(
   originalError: Error,
   context?: Record<string, string>,
 ): ReamError {
-  const total = E_PIPELINE_STAGES.length
+  const total = PIPELINE_STAGES.length
   const clampedIndex = Math.max(0, Math.min(stageIndex, total - 1))
-  const stageName = E_PIPELINE_STAGES[clampedIndex]
+  const stageName = PIPELINE_STAGES[clampedIndex]
   const position = `${clampedIndex + 1}/${total}`
-  const nextStage = clampedIndex + 1 < total ? E_PIPELINE_STAGES[clampedIndex + 1] : '(end)'
+  const nextStage = clampedIndex + 1 < total ? PIPELINE_STAGES[clampedIndex + 1] : '(end)'
 
   const errorCode = originalError instanceof ReamError ? originalError.code : 'E_PIPELINE_ERROR'
 

package/src/http/Response.ts

@@ -11,10 +11,10 @@ import { randomUUID } from 'node:crypto'
 import { createReadStream } from 'node:fs'
 import { readFile, stat } from 'node:fs/promises'
 import { basename } from 'node:path'
-import etag from 'etag'
-import { contentType } from 'mime-types'
 import { ReamError } from '../errors/ReamError.js'
 import { durationToSeconds } from '../helpers/duration.js'
+import { etag, matchesIfNoneMatch } from './etag.js'
+import { contentType } from './mime.js'
 
 /**
  * Default ceiling on a buffered response body — the same 100MB the Rust layer
@@ -738,12 +738,8 @@ export class Response extends Macroable {
     if (!((status >= 200 && status < 300) || status === 304)) return false
     const noneMatch = this.#request?.header('if-none-match')
     const currentEtag = this.getHeader('etag')
-    if (!noneMatch || !currentEtag) return false
-    if (noneMatch.trim() === '*') return true
-    return noneMatch.split(',').some((tag) => {
-      const t = tag.trim()
-      return t === currentEtag || t === `W/${currentEtag}` || `W/${t}` === currentEtag
-    })
+    if (!currentEtag) return false
+    return matchesIfNoneMatch(noneMatch, currentEtag)
   }
 
   /**

package/src/http/SseStream.ts

@@ -106,13 +106,22 @@ export class SseStream {
         // stop the timer and run close listeners once, so a dropped-
         // at-open stream can't leave an orphaned keepalive ticking
         // against a dead registry slot.
-        void this.#backend.writeStream(this.id, ':keepalive\n\n').then((ok) => {
-          if (!ok && this.#open) {
-            this.#open = false
-            this.#stopPing()
-            this.#fireClose()
-          }
-        })
+        //
+        // A REJECTION means the same thing as `false` and is treated the same
+        // way. It was unhandled before, and an unhandled rejection from a
+        // detached timer takes the whole process down on a default Node —
+        // one client's socket dying would have ended every other client's.
+        void this.#backend
+          .writeStream(this.id, ':keepalive\n\n')
+          .then((ok) => ok)
+          .catch(() => false)
+          .then((ok) => {
+            if (!ok && this.#open) {
+              this.#open = false
+              this.#stopPing()
+              this.#fireClose()
+            }
+          })
       }, ping)
       // The keepalive must not pin the Node event loop — letting the
       // process exit on its own when nothing else is keeping it busy

package/src/http/etag.ts

@@ -0,0 +1,68 @@
+/**
+ * Entity tags, computed here rather than pulled in.
+ *
+ * The `etag` package is fifteen lines of hashing behind a dependency, and this
+ * is the whole of what a response needs. The format is reproduced byte for
+ * byte on purpose: an ETag is a cache key, and changing its shape would
+ * invalidate every cached response in flight the day it shipped.
+ *
+ * `<hex length>-<27 chars of base64 sha1>`, quoted, with `W/` in front when
+ * the caller asks for a weak one. The empty body has a fixed answer because
+ * hashing nothing is the same work every time.
+ */
+
+import { createHash } from 'node:crypto'
+
+/** base64 sha1 of the empty string, truncated as below — precomputed. */
+const EMPTY = '"0-2jmj7l5rSw0yVb/vlWAYkK/YBwk"'
+
+/** The tag for a response body (`etag` package parity, string or Buffer). */
+export function etag(body: string | Buffer, options?: { weak?: boolean }): string {
+  const tag = body.length === 0 ? EMPTY : entityTag(body)
+  return options?.weak === true ? `W/${tag}` : tag
+}
+
+function entityTag(body: string | Buffer): string {
+  const hash = createHash('sha1')
+    .update(typeof body === 'string' ? Buffer.from(body, 'utf8') : body)
+    .digest('base64')
+    .slice(0, 27)
+  // Byte length, not character count: a multi-byte body is longer on the wire
+  // than its string length says.
+  const length = typeof body === 'string' ? Buffer.byteLength(body, 'utf8') : body.length
+  return `"${length.toString(16)}-${hash}"`
+}
+
+/**
+ * The tag for a file, from its metadata rather than its bytes.
+ *
+ * `W/"<size hex>-<mtime hex>"`, which is what the `etag` package produces for
+ * a `Stats` and therefore what Express's `send` — and so every static file
+ * server people have cached against — puts on a static asset. Weak because it
+ * is derived from metadata: two files with the same size and mtime are
+ * equivalent for caching, not provably byte-identical.
+ *
+ * The quotes are not decoration. RFC 9110 §8.8.3 defines an entity-tag as a
+ * quoted string, and a bare hex digest is not one: a strict cache is entitled
+ * to ignore it, which turns every conditional request back into a full
+ * transfer.
+ */
+export function statTag(stat: { size: number; mtimeMs: number }): string {
+  return `W/"${stat.size.toString(16)}-${Math.floor(stat.mtimeMs).toString(16)}"`
+}
+
+/**
+ * Whether `If-None-Match` covers `tag` (RFC 9110 §13.1.2).
+ *
+ * The header is a LIST, and it is compared with the WEAK comparison function —
+ * `W/"x"` and `"x"` match. Raw string equality against the whole header value
+ * failed a client that sent two tags, and failed every client that sent back
+ * the weak form of a strong tag, so both re-downloaded a file they already had.
+ */
+export function matchesIfNoneMatch(header: string | undefined, tag: string): boolean {
+  if (!header || tag === '') return false
+  if (header.trim() === '*') return true
+  const bare = (value: string): string => (value.startsWith('W/') ? value.slice(2) : value)
+  const current = bare(tag)
+  return header.split(',').some((candidate) => bare(candidate.trim()) === current)
+}