@nifrajs/web 2.9.1 → 2.11.0

package/src/isr.ts

@@ -20,6 +20,8 @@ export interface CachedResponse {
   readonly storedAt: number
   /** Freshness window (ms): `now - storedAt >= revalidate` ⇒ stale (serve it, regenerate behind it). */
   readonly revalidate: number
+  /** Public, bounded invalidation labels. A tag purge makes matching entries miss immediately. */
+  readonly tags?: readonly string[]
 }
 
 /**
@@ -35,6 +37,45 @@ export interface CacheStore {
   set(key: string, value: CachedResponse): Promise<void>
   /** Drop `key` (on-demand revalidation / purge). A no-op if absent. */
   delete(key: string): Promise<void>
+  /** Drop every cached response carrying `tag`, when the backend supports tag invalidation. */
+  readonly invalidateTag?: (tag: string) => Promise<void>
+}
+
+const ISR_TAG_PATTERN = /^[A-Za-z][A-Za-z0-9._:/-]{0,127}$/
+const MAX_ISR_TAGS = 32
+
+function normalizeTag(tag: string): string {
+  if (typeof tag !== "string" || !ISR_TAG_PATTERN.test(tag)) {
+    throw new TypeError("[nifra/web] ISR tag must be a bounded token")
+  }
+  return tag
+}
+
+function normalizeTags(tags: readonly string[] | undefined): readonly string[] {
+  if (tags === undefined) return []
+  if (!Array.isArray(tags) || tags.length > MAX_ISR_TAGS) {
+    throw new TypeError("[nifra/web] ISR tags must contain at most 32 bounded tokens")
+  }
+  const unique = new Set<string>()
+  for (const tag of tags) unique.add(normalizeTag(tag))
+  return Object.freeze([...unique])
+}
+
+function tagsFromHeader(value: string | null): readonly string[] {
+  if (value === null || value.trim() === "") return []
+  try {
+    return normalizeTags(value.split(",").map((tag) => tag.trim()))
+  } catch {
+    // A malformed response-controlled header must never accidentally create an unpurgeable cache
+    // entry. Treat it as untagged; route declarations are validated before they reach this path.
+    return []
+  }
+}
+
+/** Validate and serialize route-declared ISR tags for the internal response header. */
+export function serializeISRTags(tags: readonly string[]): string | undefined {
+  const normalized = normalizeTags(tags)
+  return normalized.length === 0 ? undefined : normalized.join(",")
 }
 
 export interface MemoryCacheStoreOptions {
@@ -52,8 +93,12 @@ export interface MemoryCacheStoreOptions {
  * page survives a burst of new pages).
  */
 export class MemoryCacheStore implements CacheStore {
-  private readonly cache = new Map<string, CachedResponse>()
+  private readonly cache = new Map<
+    string,
+    { readonly value: CachedResponse; readonly tagEpochs: Readonly<Record<string, string>> }
+  >()
   private readonly max: number
+  private readonly tagEpoch = new Map<string, string>()
 
   constructor(options: MemoryCacheStoreOptions = {}) {
     const isProd = typeof process !== "undefined" && process.env?.NODE_ENV === "production"
@@ -71,31 +116,75 @@ export class MemoryCacheStore implements CacheStore {
   }
 
   get(key: string): Promise<CachedResponse | undefined> {
-    const value = this.cache.get(key)
+    const row = this.cache.get(key)
+    if (row !== undefined) {
+      for (const [tag, epoch] of Object.entries(row.tagEpochs)) {
+        if ((this.tagEpoch.get(tag) ?? "0") !== epoch) {
+          this.cache.delete(key)
+          this.pruneTagEpochs()
+          return Promise.resolve(undefined)
+        }
+      }
+    }
+    const value = row?.value
     // LRU: a read bumps the entry to the tail so the bounded evict drops the LEAST-RECENTLY-USED,
     // not the oldest-written - otherwise a burst of new pages would evict a hot, frequently-read one.
     if (value !== undefined) {
       this.cache.delete(key)
-      this.cache.set(key, value)
+      this.cache.set(
+        key,
+        row as {
+          readonly value: CachedResponse
+          readonly tagEpochs: Readonly<Record<string, string>>
+        },
+      )
     }
     return Promise.resolve(value)
   }
 
   set(key: string, value: CachedResponse): Promise<void> {
+    const tags = normalizeTags(value.tags)
+    const tagEpochs: Record<string, string> = {}
+    for (const tag of tags) tagEpochs[tag] = this.tagEpoch.get(tag) ?? "0"
     this.cache.delete(key) // re-insert at the tail so Map order tracks recency (with get) for the LRU evict
-    this.cache.set(key, value)
+    this.cache.set(key, { value: tags.length === 0 ? value : { ...value, tags }, tagEpochs })
     while (this.cache.size > this.max) {
       const oldest = this.cache.keys().next().value
       if (oldest === undefined) break
       this.cache.delete(oldest)
     }
+    this.pruneTagEpochs()
     return Promise.resolve()
   }
 
   delete(key: string): Promise<void> {
     this.cache.delete(key)
+    this.pruneTagEpochs()
+    return Promise.resolve()
+  }
+
+  invalidateTag(tag: string): Promise<void> {
+    normalizeTag(tag)
+    this.tagEpoch.set(tag, crypto.randomUUID())
+    // This store is bounded and local, so eagerly remove matching rows. It keeps invalidation
+    // immediate and lets us discard epoch keys that no retained entry references anymore.
+    for (const [key, row] of this.cache) {
+      if (Object.hasOwn(row.tagEpochs, tag)) this.cache.delete(key)
+    }
+    this.pruneTagEpochs()
     return Promise.resolve()
   }
+
+  private pruneTagEpochs(): void {
+    if (this.tagEpoch.size === 0) return
+    const used = new Set<string>()
+    for (const row of this.cache.values()) {
+      for (const tag of Object.keys(row.tagEpochs)) used.add(tag)
+    }
+    for (const tag of this.tagEpoch.keys()) {
+      if (!used.has(tag)) this.tagEpoch.delete(tag)
+    }
+  }
 }
 
 /**
@@ -121,6 +210,16 @@ export interface KVCacheStoreOptions {
    * overwritten on regeneration or purged via `revalidateEndpoint`.
    */
   readonly expirationTtl?: number
+  /**
+   * Smallest `expirationTtl` this binding accepts (**seconds**). Defaults to 60, which is Cloudflare
+   * KV's floor - the common case, and worth rejecting at construction because Cloudflare fails the
+   * `put` at runtime instead, one deploy later.
+   *
+   * The floor belongs to the *binding*, not to this class. {@link KVNamespaceLike} is structural, so
+   * a Redis, Deno KV, Upstash, or in-memory binding satisfies it too, and those accept far shorter
+   * TTLs. Pass their real minimum, or `0` for a backend with none.
+   */
+  readonly minExpirationTtl?: number
 }
 
 /**
@@ -141,31 +240,64 @@ const isCachedResponse = (value: unknown): value is CachedResponse => {
   ) {
     return false
   }
+  if (v.tags !== undefined) {
+    if (!Array.isArray(v.tags)) return false
+    try {
+      normalizeTags(v.tags as string[])
+    } catch {
+      return false
+    }
+  }
   for (const headerValue of Object.values(v.headers as Record<string, unknown>)) {
     if (typeof headerValue !== "string") return false
   }
   return true
 }
 
+const KV_TAG_EPOCH_PREFIX = "__nifra_isr_tag_v1:"
+
+type StoredTaggedResponse = CachedResponse & {
+  readonly __nifraTagEpochs?: Readonly<Record<string, string>>
+}
+
 /**
  * A {@link CacheStore} backed by a **Cloudflare Workers KV** namespace (or any {@link KVNamespaceLike}
  * binding) - the production-grade shared/durable store ISR wants: cached pages and on-demand purges
  * hold *across* worker instances (unlike the per-instance {@link MemoryCacheStore}). Entries serialize
  * to JSON; every read is validated before it's trusted (a malformed/version-skewed entry is treated as
  * a miss). Construct it in your Workers `fetch` from the binding: `new KVCacheStore(env.ISR_CACHE)`.
+ *
+ * Cloudflare is the default, not a requirement: {@link KVNamespaceLike} is three structural methods,
+ * so a Redis, Deno KV, or Upstash binding satisfies it (pass `minExpirationTtl` for their TTL floor).
+ * A backend that *can* enumerate keys deserves its own {@link CacheStore} rather than this one - the
+ * epoch indirection in {@link KVCacheStore.invalidateTag} exists only because KV cannot list by tag.
  */
 export class KVCacheStore implements CacheStore {
   private readonly kv: KVNamespaceLike
   private readonly putOptions: { readonly expirationTtl?: number } | undefined
 
   constructor(kv: KVNamespaceLike, options: KVCacheStoreOptions = {}) {
-    if (options.expirationTtl !== undefined && options.expirationTtl < 60) {
-      throw new Error(
-        "[nifra/web] KVCacheStore expirationTtl must be >= 60 (Cloudflare KV's minimum), and should " +
-          "exceed your longest `revalidate` window so stale-while-revalidate isn't turned into a " +
-          "blocking miss by KV expiry.",
+    const floor = options.minExpirationTtl ?? 60
+    if (!Number.isSafeInteger(floor) || floor < 0) {
+      throw new RangeError(
+        "[nifra/web] KVCacheStore minExpirationTtl must be a non-negative integer",
       )
     }
+    if (options.expirationTtl !== undefined) {
+      if (!Number.isSafeInteger(options.expirationTtl) || options.expirationTtl < 0) {
+        throw new RangeError(
+          "[nifra/web] KVCacheStore expirationTtl must be a non-negative integer (seconds)",
+        )
+      }
+      if (options.expirationTtl < floor) {
+        throw new Error(
+          `[nifra/web] KVCacheStore expirationTtl must be >= ${floor}, this binding's minimum. 60 is ` +
+            "Cloudflare KV's floor and the default; pass `minExpirationTtl` for a backend with a " +
+            "lower one. Whatever the floor, the TTL should exceed your longest `revalidate` window, " +
+            "or expiry turns a stale-while-revalidate into a blocking miss.",
+        )
+      }
+    }
     this.kv = kv
     // Precompute the put options object once: omit it entirely when no TTL (KV then never expires).
     this.putOptions =
@@ -182,16 +314,53 @@ export class KVCacheStore implements CacheStore {
       // A corrupt (non-JSON) entry: treat as a miss so the page re-renders; the next set overwrites it.
       return undefined
     }
-    return isCachedResponse(parsed) ? parsed : undefined
+    if (!isCachedResponse(parsed)) return undefined
+    const tags = normalizeTags(parsed.tags)
+    if (tags.length === 0) return parsed
+    const epochs = (parsed as StoredTaggedResponse).__nifraTagEpochs
+    if (epochs === undefined) return undefined
+    const current = await Promise.all(
+      tags.map(async (tag) => [tag, (await this.kv.get(this.tagKey(tag))) ?? "0"] as const),
+    )
+    if (current.some(([tag, epoch]) => epochs[tag] !== epoch)) return undefined
+    const { __nifraTagEpochs: _ignored, ...value } = parsed as StoredTaggedResponse
+    return value
   }
 
   async set(key: string, value: CachedResponse): Promise<void> {
-    await this.kv.put(key, JSON.stringify(value), this.putOptions)
+    const tags = normalizeTags(value.tags)
+    if (tags.length === 0) {
+      await this.kv.put(key, JSON.stringify(value), this.putOptions)
+      return
+    }
+    const epochs = Object.fromEntries(
+      await Promise.all(
+        tags.map(async (tag) => [tag, (await this.kv.get(this.tagKey(tag))) ?? "0"] as const),
+      ),
+    )
+    const stored: StoredTaggedResponse = {
+      ...value,
+      tags,
+      __nifraTagEpochs: epochs,
+    }
+    await this.kv.put(key, JSON.stringify(stored), this.putOptions)
   }
 
   async delete(key: string): Promise<void> {
     await this.kv.delete(key)
   }
+
+  async invalidateTag(tag: string): Promise<void> {
+    normalizeTag(tag)
+    // Epoch invalidation avoids KV key enumeration and remains bounded for a tag with millions of
+    // pages. Epoch keys intentionally have no expiration: an expired epoch would resurrect entries
+    // written before the invalidation when their page key still exists.
+    await this.kv.put(this.tagKey(tag), crypto.randomUUID())
+  }
+
+  private tagKey(tag: string): string {
+    return `${KV_TAG_EPOCH_PREFIX}${encodeURIComponent(tag)}`
+  }
 }
 
 /** Minimal platform shape `withISR` needs - just `waitUntil` (edge runtimes extend the response
@@ -209,6 +378,9 @@ export interface ISRApp {
  * regenerating behind it), or `miss` (rendered now + stored). Useful for debugging + tests. */
 export const ISR_STATUS_HEADER = "x-nifra-isr"
 
+/** Response header carrying bounded route tags into {@link withISR}. */
+export const ISR_REVALIDATE_TAGS_HEADER = "x-nifra-isr-tags"
+
 /**
  * Response header a route uses to advertise its ISR freshness (**seconds**) to a {@link withISR}
  * wrapper - `createWebApp` emits it from a route's `export const revalidate`. Deliberately distinct
@@ -289,6 +461,9 @@ const CACHEABLE_RESPONSE_HEADERS = new Set([
   "link",
 ])
 
+const tagsOf = (res: Response): readonly string[] =>
+  tagsFromHeader(res.headers.get(ISR_REVALIDATE_TAGS_HEADER))
+
 const headersOf = (res: Response): Record<string, string> => {
   const out: Record<string, string> = {}
   res.headers.forEach((value, key) => {
@@ -349,12 +524,14 @@ export function withISR(
     const res = await app.fetch(req, platform)
     if (!isCacheablePage(req, res)) return res
     const body = await res.text()
+    const tags = tagsOf(res)
     const entry: CachedResponse = {
       body,
       status: res.status,
       headers: headersOf(res),
       storedAt: now(),
       revalidate: ttlMs(res),
+      ...(tags.length === 0 ? {} : { tags }),
     }
     await store.set(key, entry)
     return new Response(body, {
@@ -375,12 +552,14 @@ export function withISR(
     try {
       const res = await app.fetch(req, platform)
       if (isCacheablePage(req, res)) {
+        const tags = tagsOf(res)
         await store.set(key, {
           body: await res.text(),
           status: res.status,
           headers: headersOf(res),
           storedAt: now(),
           revalidate: ttlMs(res),
+          ...(tags.length === 0 ? {} : { tags }),
         })
       } else {
         await res.body?.cancel()
@@ -431,9 +610,10 @@ export interface RevalidateEndpointOptions {
 
 /**
  * An **on-demand revalidation** (purge) endpoint - a `fetch` handler that drops a path's cached entry
- * so the next request re-renders. `POST` with the secret in the token header and the path as `?path=`
- * or a JSON `{ "path": "/blog/x" }` body. The token is checked in **constant time** (wrong/missing →
- * `401`); a missing/relative path → `400`; non-POST → `405`. Mount it on a nifra route, e.g.
+ * or invalidates every entry carrying a tag. `POST` with the secret in the token header and either
+ * `?path=/blog/x`, `?tag=products`, or a JSON `{ "path": "/blog/x" }` / `{ "tag": "products" }` body.
+ * The token is checked in **constant time** (wrong/missing → `401`); malformed targets → `400`;
+ * non-POST → `405`. A store without tag support returns `501` for tag requests. Mount it on a nifra route, e.g.
  * `app.post("/__nifra/revalidate", (c) => handler(c.req))`.
  */
 export function revalidateEndpoint(
@@ -446,12 +626,29 @@ export function revalidateEndpoint(
     if (!timingSafeEqual(req.headers.get(tokenHeader) ?? "", options.secret)) {
       return jsonError(401, "unauthorized")
     }
-    let path = new URL(req.url).searchParams.get("path")
-    if (path === null) {
+    const url = new URL(req.url)
+    let path = url.searchParams.get("path")
+    let tag = url.searchParams.get("tag")
+    if (path === null && tag === null) {
       const body: unknown = await req.json().catch(() => null)
-      const candidate =
-        typeof body === "object" && body !== null ? (body as { path?: unknown }).path : undefined
-      path = typeof candidate === "string" ? candidate : null
+      if (typeof body === "object" && body !== null) {
+        const candidate = body as { path?: unknown; tag?: unknown }
+        path = typeof candidate.path === "string" ? candidate.path : null
+        tag = typeof candidate.tag === "string" ? candidate.tag : null
+      }
+    }
+    if (path !== null && tag !== null) return jsonError(400, "choose_path_or_tag")
+    if (tag !== null) {
+      try {
+        normalizeTag(tag)
+      } catch {
+        return jsonError(400, "invalid_tag")
+      }
+      if (options.store.invalidateTag === undefined) {
+        return jsonError(501, "tag_invalidation_not_supported")
+      }
+      await options.store.invalidateTag(tag)
+      return Response.json({ revalidatedTag: tag })
     }
     if (path === null || !path.startsWith("/")) return jsonError(400, "invalid_path")
     await options.store.delete(keyOf(path, req))

package/src/manifest.ts

@@ -227,6 +227,8 @@ export interface RouteModule {
    * default). Older-than-`revalidate` cached pages are served stale while regenerating.
    */
   readonly revalidate?: number
+  /** Optional bounded tags used by ISR on-demand invalidation (`?tag=...`). */
+  readonly revalidateTags?: readonly string[]
   /**
    * No-framework island bundles (`@nifrajs/web/islands`) to load on this route, as `<script
    * type="module">` in the document tail. Loaded **regardless of `hydrate`** - pair with

package/src/plugins/kit.ts

@@ -11,6 +11,16 @@ import type { BunPlugin } from "bun"
 /** The argument Bun passes to a plugin's `setup` - Bun doesn't export the type, so derive it. */
 export type PluginBuilder = Parameters<BunPlugin["setup"]>[0]
 
+/**
+ * Re-keys the app-owned imports of a module the SERVER half of a plugin just compiled, so an edit below
+ * a route reaches SSR instead of being served from Bun's import cache. A plugin that claims a file
+ * extension is the only code that ever sees that file's source, so it is the only place its imports can
+ * be versioned - every `generate: "ssr"` loader should return its output through this.
+ *
+ * A no-op on the client half and outside a dev server. See `../dev-ssr-graph.ts` for the whole design.
+ */
+export { rewriteSsrImports } from "../dev-ssr-graph.ts"
+
 const packageRootCache = new Map<string, string>()
 
 /** The nearest ancestor directory of `startDir` that holds a `package.json` (the file's package root),
@@ -57,6 +67,67 @@ export function hash8(input: string): string {
   return h.toString(16).padStart(8, "0")
 }
 
+/**
+ * Env flag a nifra dev server sets for its own lifetime, so a framework compiler plugin can tell a dev
+ * compile from a `nifra build` one. Exported for the dev server that sets it; plugins ask
+ * {@link devServerCompile} instead of reading it.
+ */
+export const DEV_HMR_ENV = "NIFRA_DEV_HMR"
+
+/**
+ * True while a nifra dev server is running, i.e. the compile may emit HMR wiring (and, where the
+ * framework couples the two, dev-mode runtime output).
+ *
+ * The phase cannot be a plugin constructor argument: an app builds its `clientPlugins` once in
+ * `nifra.config.ts` and the same plugin objects serve both `nifra dev` and `nifra build`. Guarding the
+ * emitted code with `if (import.meta.hot)` is not sufficient either - `Bun.build` keeps the branch, so
+ * the HMR calls were measured shipping in production client chunks. The dev server announces itself in
+ * the environment instead, and `nifra build` never sets it. Read per compile (not captured at
+ * registration) so the flag is honoured however late the server sets it.
+ */
+export function devServerCompile(): boolean {
+  return process.env[DEV_HMR_ENV] === "1"
+}
+
+/**
+ * The app root and the routes directory of the running dev server, for plugins that need to tell one of
+ * the app's own components from a dependency or a route module. Set alongside {@link DEV_HMR_ENV}; read
+ * through {@link devHotComponent}.
+ */
+export const DEV_ROOT_ENV = "NIFRA_DEV_ROOT"
+export const DEV_ROUTES_ENV = "NIFRA_DEV_ROUTES"
+
+const under = (path: string, dir: string | undefined): boolean =>
+  dir !== undefined &&
+  dir !== "" &&
+  (path === dir || path.startsWith(dir.endsWith("/") ? dir : `${dir}/`))
+
+/**
+ * Whether a dev compile of `path` may wrap the module in component-level hot-patching - i.e. whether it
+ * is one of the app's OWN components rather than a dependency or a route module.
+ *
+ * The exclusions are not caution, they are two things such a wrapper cannot survive:
+ *
+ *   - a **dependency**, whose components are the framework's own composition machinery. An adapter folds
+ *     a layout chain through them, so they are entered from a snippet or as a dynamic component - and a
+ *     wrapper there sits between the SSR markup and the component that is supposed to claim it.
+ *   - a **route module**, for the same reason one level down: a route or layout IS a chain member, so it
+ *     is always the dynamic child. It is also the wrong boundary to patch - a route module carries the
+ *     loader and meta the server ran, and re-running those is a navigation, not a patch. Editing one
+ *     finds no accepting module and reloads the page, which is the correct outcome.
+ *
+ * Both cost nothing in practice: the components an edit loop actually touches are the views, and a view
+ * that wants to hot-patch lives outside the routes directory. Where the split is unknown (no dev server,
+ * or a root that was never announced), the answer is `false` - a full reload is always correct, a
+ * mispatched tree is not.
+ */
+export function devHotComponent(path: string): boolean {
+  const root = process.env[DEV_ROOT_ENV]
+  if (!under(path, root)) return false
+  if (path.includes("/node_modules/")) return false
+  return !under(path, process.env[DEV_ROUTES_ENV])
+}
+
 /**
  * Records compiled CSS and wires it into the client bundle through a virtual `?<namespace>` module -
  * the idiom the Vue plugin established (`?vue-css`). Register one per plugin `setup`; call `emit` per

package/src/public-dir.ts

@@ -14,6 +14,7 @@
  */
 import { realpath } from "node:fs/promises"
 import { normalize, resolve, sep } from "node:path"
+import { parseByteRange } from "@nifrajs/core/range"
 import { pathnameOf } from "@nifrajs/core/server"
 
 /** How long each subtree may be cached. Content-hashed bundle output can be immutable; a
@@ -38,6 +39,35 @@ export interface ServePublicDirOptions {
 const IMMUTABLE = "public, max-age=31536000, immutable"
 const ONE_DAY = "public, max-age=86400"
 
+/** HTTP dates carry second precision; comparing raw milliseconds makes every file look stale. */
+function seconds(time: number): number {
+  return Math.floor(time / 1000)
+}
+
+/**
+ * `If-Range` decides whether a range request is still safe to answer partially. The only validator
+ * this handler publishes is `last-modified`, so an entity-tag form can never match and the whole
+ * representation is sent instead - which is the conformant outcome, not a fallback. Dates use strong
+ * comparison (RFC 9110 13.1.5): a file modified since the client's copy invalidates its byte offsets.
+ */
+function ifRangeMatches(value: string | null, lastModified: number | undefined): boolean {
+  if (value === null) return true
+  if (lastModified === undefined) return false
+  const item = value.trim()
+  if (item.startsWith('"') || item.startsWith("W/")) return false
+  const parsed = Date.parse(item)
+  return Number.isFinite(parsed) && seconds(parsed) === seconds(lastModified)
+}
+
+/** `If-Modified-Since` freshness. No ETag is published, so there is no `If-None-Match` precedence. */
+function isNotModified(request: Request, lastModified: number | undefined): boolean {
+  if (lastModified === undefined) return false
+  const since = request.headers.get("if-modified-since")
+  if (since === null) return false
+  const parsed = Date.parse(since)
+  return Number.isFinite(parsed) && seconds(parsed) >= seconds(lastModified)
+}
+
 /**
  * Resolve a URL pathname to an absolute path **confined** to `root`, or `undefined` if it escapes.
  *
@@ -101,12 +131,52 @@ export function servePublicDir(
     }
     const file = Bun.file(resolvedFile)
     if (!(await file.exists())) return undefined
+    const size = file.size
     const headers = new Headers({
       "cache-control": pathname.startsWith(hashedPrefix) ? hashed : assets,
+      // Advertised unconditionally: a client that never sees `accept-ranges` will not attempt a seek,
+      // so a video or audio file under `public/` is scrubbable only once this header is present.
+      "accept-ranges": "bytes",
     })
-    // HEAD must not carry a body, but must otherwise match GET's headers.
-    return request.method === "HEAD"
-      ? new Response(null, { headers })
-      : new Response(file, { headers })
+    // `new Response(file)` used to infer the media type, which meant HEAD - built from a null body -
+    // silently lost it. Setting it here is what makes the two methods agree.
+    if (file.type !== "") headers.set("content-type", file.type)
+    const lastModified =
+      Number.isFinite(file.lastModified) && file.lastModified > 0 ? file.lastModified : undefined
+    if (lastModified !== undefined) {
+      headers.set("last-modified", new Date(lastModified).toUTCString())
+    }
+    const head = request.method === "HEAD"
+
+    if (isNotModified(request, lastModified)) {
+      headers.delete("content-type")
+      return new Response(null, { status: 304, headers })
+    }
+
+    const rangeHeader = request.headers.get("range")
+    const range =
+      rangeHeader !== null && ifRangeMatches(request.headers.get("if-range"), lastModified)
+        ? parseByteRange(rangeHeader, size)
+        : ({ kind: "none" } as const)
+
+    if (range.kind === "unsatisfiable") {
+      headers.delete("content-type")
+      headers.set("content-range", `bytes */${size}`)
+      return new Response(null, { status: 416, headers })
+    }
+
+    if (range.kind === "satisfiable" && range.ranges.length === 1) {
+      const { start, end } = range.ranges[0]!
+      headers.set("content-range", `bytes ${start}-${end}/${size}`)
+      headers.set("content-length", String(end - start + 1))
+      // `slice` keeps the read lazy: only the selected window is ever pulled off disk.
+      return new Response(head ? null : file.slice(start, end + 1), { status: 206, headers })
+    }
+
+    // Multiple ranges would require assembling `multipart/byteranges`, and doing that for a file on
+    // disk means buffering the whole representation to serve a request that asked for less of it.
+    // RFC 9110 lets a server ignore Range entirely, so the full body is the conformant answer here.
+    if (head) headers.set("content-length", String(size))
+    return new Response(head ? null : file, { headers })
   }
 }

package/src/route-manifest.ts

@@ -41,6 +41,8 @@ export interface RouteManifestEntry {
   readonly hydrate: boolean
   /** Revalidation window in seconds. Present only for `isr`. */
   readonly revalidate?: number
+  /** Bounded tags that can purge this route from a shared ISR store. */
+  readonly revalidateTags?: readonly string[]
   /**
    * Concrete paths prerendered at build. Present for `static` routes: a single path for a static route,
    * one per `getStaticPaths` entry for a dynamic one. Absent means "no path was enumerated", which for a
@@ -84,7 +86,10 @@ const isDynamic = (pattern: string): boolean => /[:*]/.test(pattern)
 export function deriveRouteEntry(
   id: string,
   pattern: string,
-  module: Pick<RouteModule, "prerender" | "getStaticPaths" | "revalidate" | "hydrate">,
+  module: Pick<
+    RouteModule,
+    "prerender" | "getStaticPaths" | "revalidate" | "revalidateTags" | "hydrate"
+  >,
   prerenderedPaths?: readonly string[],
 ): RouteManifestEntry {
   const wantsPrerender = module.prerender === true || module.getStaticPaths !== undefined
@@ -105,10 +110,14 @@ export function deriveRouteEntry(
     mode: RenderMode
     hydrate: boolean
     revalidate?: number
+    revalidateTags?: readonly string[]
     prerenderedPaths?: readonly string[]
     requires: readonly RouteCapability[]
   } = { id, pattern, mode, hydrate: module.hydrate !== false, requires }
   if (mode === "isr" && module.revalidate !== undefined) entry.revalidate = module.revalidate
+  if (mode === "isr" && module.revalidateTags !== undefined) {
+    entry.revalidateTags = module.revalidateTags
+  }
   if (prerenderedPaths !== undefined) entry.prerenderedPaths = prerenderedPaths
   return entry as RouteManifestEntry
 }