fix: audit pass 7 — Link header parser + cache Vary key

### Bug 50 — Link header parser (RFC 8288 §3)
The previous parser split on raw commas, which broke as soon as a URL
contained one (e.g. \`/items?ids=1,2,3\`). It also missed:
- space-separated rel values (\`rel="next foo"\`)
- malformed entries (returned a partial mapping)
- rel after a quoted value with embedded semicolons

Replaced the regex-split approach with a state machine that walks the
header treating \`<...>\` as the URL boundary and consuming params up to
the next top-level comma. Five new tests in test/link-header.test.ts
pin: simple rel=next, URL with commas, multi-link, space-separated rel,
malformed input.

### Bug — cache Vary stored only the latest variant
\`vary\` headers were recorded on the cache entry but the entry was keyed
only by URL+method. Sequential requests with different Accept-Language
overwrote each other; en-tr-en hit the network three times.

Now per-variant entries are stored under a derived key
(\`baseKey | header=value & ...\`) and the base entry remembers Vary so
beforeRequest knows to look up the variant. en-tr-en hits the network
twice (en2 served from cache).

Four new tests in test/cache-rfc.test.ts pin: \`Cache-Control: no-store\`,
\`max-age\` overriding local TTL, Vary header per-variant caching, and
\`Vary: *\` forcing revalidation.

126/126 tests pass; lint, typecheck, build, bundle budget all clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: productdevbook

src/cache/index.ts

@@ -72,15 +72,19 @@ export function withCache(misina: Misina, opts: CacheOptions = {}): Misina {
     hooks: {
       beforeRequest: async (ctx) => {
         if (!methods.includes(ctx.options.method)) return
-        const key = keyOf(ctx)
-        const entry = await store.get(key)
+        const baseKey = keyOf(ctx)
+        // Try the base key first; if that entry has Vary, build a per-variant
+        // key from the request headers and look that up too.
+        const baseEntry = await store.get(baseKey)
+        const variantKey = baseEntry?.vary
+          ? variantKeyFor(baseKey, baseEntry.vary, ctx.request.headers)
+          : undefined
+        const entry = variantKey ? await store.get(variantKey) : baseEntry
         if (!entry) return
 
-        // Vary check: stored vary headers must match the current request.
         if (entry.vary && !varyMatches(entry.vary, ctx.request.headers)) return
 
         if (entry.expires > Date.now()) {
-          // Fresh — short-circuit fetch
           return entry.response.clone()
         }
 
@@ -94,12 +98,12 @@ export function withCache(misina: Misina, opts: CacheOptions = {}): Misina {
       afterResponse: async (ctx) => {
         if (!ctx.response) return
         if (!methods.includes(ctx.options.method)) return
-        const key = keyOf(ctx)
+        const baseKey = keyOf(ctx)
 
         if (ctx.response.status === 304) {
-          const entry = await store.get(key)
+          const entry = await store.get(baseKey)
           if (entry) {
-            await store.set(key, { ...entry, expires: Date.now() + ttl })
+            await store.set(baseKey, { ...entry, expires: Date.now() + ttl })
             return entry.response.clone()
           }
         }
@@ -120,18 +124,40 @@ export function withCache(misina: Misina, opts: CacheOptions = {}): Misina {
         const cloned = ctx.response.clone()
         const vary = recordVaryHeaders(ctx.response, ctx.request)
 
-        await store.set(key, {
+        const entry: CacheEntry = {
           response: cloned,
           expires: Date.now() + entryTtl,
           etag: ctx.response.headers.get("etag") ?? undefined,
           lastModified: ctx.response.headers.get("last-modified") ?? undefined,
           vary,
-        })
+        }
+
+        if (vary && !("*" in vary)) {
+          // Store the per-variant entry under a derived key, but also keep the
+          // base entry's `vary` field so subsequent requests know to look up
+          // a variant.
+          const variantKey = variantKeyFor(baseKey, vary, ctx.request.headers)
+          await store.set(variantKey, entry)
+          await store.set(baseKey, { ...entry, response: ctx.response.clone() })
+        } else {
+          await store.set(baseKey, entry)
+        }
       },
     },
   })
 }
 
+function variantKeyFor(
+  baseKey: string,
+  vary: Record<string, string | null>,
+  headers: Headers,
+): string {
+  const parts = Object.keys(vary)
+    .sort()
+    .map((name) => `${name}=${headers.get(name) ?? ""}`)
+  return `${baseKey} | ${parts.join(" & ")}`
+}
+
 function parseMaxAge(cacheControl: string): number | null {
   const match = /(?:^|,)\s*max-age\s*=\s*(\d+)/i.exec(cacheControl)
   if (!match || !match[1]) return null

src/paginate/index.ts

@@ -118,15 +118,76 @@ function defaultNext<R>(
   return { url: next }
 }
 
+/**
+ * Parse a `Link` header (RFC 8288 §3) into a `{ rel: url }` map. Splitting on
+ * raw commas is wrong because URLs can contain commas (e.g.
+ * `/items?ids=1,2,3`). We instead walk the header, treating `<...>` as the
+ * URL and consuming params up to the next top-level comma.
+ */
 function parseLinkHeader(value: string): Record<string, string> {
   const out: Record<string, string> = {}
-  for (const part of value.split(",")) {
-    const match = /<([^>]+)>;\s*rel="?([^",]+)"?/.exec(part.trim())
-    if (match) {
-      const url = match[1]
-      const rel = match[2]
-      if (url && rel) out[rel] = url
+  let i = 0
+  while (i < value.length) {
+    // Skip whitespace and leading commas
+    while (i < value.length && (value[i] === "," || value[i] === " " || value[i] === "\t")) i++
+    if (i >= value.length) break
+    if (value[i] !== "<") break // malformed
+    const close = value.indexOf(">", i + 1)
+    if (close === -1) break
+    const url = value.slice(i + 1, close)
+    i = close + 1
+
+    // Walk parameters until the next top-level comma.
+    let rel: string | undefined
+    while (i < value.length && value[i] !== ",") {
+      // Skip ; and whitespace
+      while (i < value.length && (value[i] === ";" || value[i] === " " || value[i] === "\t")) i++
+      if (i >= value.length || value[i] === ",") break
+      // Read param name
+      const eq = value.indexOf("=", i)
+      const semi = value.indexOf(";", i)
+      const comma = value.indexOf(",", i)
+      const end = nextStop(eq, semi, comma, value.length)
+      const name = value.slice(i, end).trim().toLowerCase()
+      i = end
+      if (value[i] === "=") {
+        i++
+        let pval: string
+        if (value[i] === '"') {
+          const q = value.indexOf('"', i + 1)
+          if (q === -1) {
+            pval = value.slice(i + 1)
+            i = value.length
+          } else {
+            pval = value.slice(i + 1, q)
+            i = q + 1
+          }
+        } else {
+          const stopSemi = value.indexOf(";", i)
+          const stopComma = value.indexOf(",", i)
+          const stop = nextStop(stopSemi, stopComma, -1, value.length)
+          pval = value.slice(i, stop).trim()
+          i = stop
+        }
+        if (name === "rel" && !rel) rel = pval
+      }
+    }
+
+    if (rel) {
+      // A rel can be a space-separated list — store each so callers can ask
+      // for any one of them.
+      for (const r of rel.split(/\s+/)) {
+        if (r && !(r in out)) out[r] = url
+      }
     }
   }
   return out
 }
+
+function nextStop(...candidates: number[]): number {
+  let best = Infinity
+  for (const c of candidates) {
+    if (c >= 0 && c < best) best = c
+  }
+  return best === Infinity ? (candidates[candidates.length - 1] ?? 0) : best
+}

test/cache-rfc.test.ts

@@ -0,0 +1,137 @@
+import { describe, expect, it } from "vitest"
+import { createMisina } from "../src/index.ts"
+import { withCache, memoryStore } from "../src/cache/index.ts"
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    headers: { "content-type": "application/json" },
+    ...init,
+  })
+}
+
+describe("withCache — RFC 9111 compliance", () => {
+  it("Cache-Control: no-store is honored (response not stored)", async () => {
+    let calls = 0
+    const driver = {
+      name: "ns",
+      request: async () => {
+        calls++
+        return jsonResponse(
+          { count: calls },
+          {
+            headers: { "content-type": "application/json", "cache-control": "no-store" },
+          },
+        )
+      },
+    }
+
+    const store = memoryStore()
+    const m = withCache(createMisina({ driver, retry: 0 }), { store, ttl: 60_000 })
+
+    await m.get("https://api.test/")
+    await m.get("https://api.test/")
+
+    // No store, so both calls hit network.
+    expect(calls).toBe(2)
+  })
+
+  it("Cache-Control: max-age overrides local ttl", async () => {
+    let calls = 0
+    const driver = {
+      name: "served",
+      request: async () => {
+        calls++
+        return jsonResponse(
+          { x: 1 },
+          {
+            headers: {
+              "content-type": "application/json",
+              // 1 second max-age — well under the local ttl of 60s
+              "cache-control": "max-age=1",
+            },
+          },
+        )
+      },
+    }
+
+    const store = memoryStore()
+    const m = withCache(createMisina({ driver, retry: 0 }), { store, ttl: 60_000 })
+
+    await m.get("https://api.test/")
+    expect(calls).toBe(1)
+
+    // Wait past the server-controlled max-age but well within local ttl.
+    await new Promise((r) => setTimeout(r, 1100))
+
+    await m.get("https://api.test/")
+    expect(calls).toBe(2)
+  })
+
+  it("Vary header — different request headers bust the cache", async () => {
+    let calls = 0
+    const driver = {
+      name: "vary",
+      request: async (req: Request) => {
+        calls++
+        return jsonResponse(
+          { lang: req.headers.get("accept-language") },
+          {
+            headers: {
+              "content-type": "application/json",
+              vary: "Accept-Language",
+            },
+          },
+        )
+      },
+    }
+
+    const store = memoryStore()
+    const m = withCache(createMisina({ driver, retry: 0 }), { store, ttl: 60_000 })
+
+    const en = await m.get<{ lang: string }>("https://api.test/", {
+      headers: { "accept-language": "en" },
+    })
+    expect(en.data.lang).toBe("en")
+
+    // Same URL, different Accept-Language — must not reuse the en cache.
+    const tr = await m.get<{ lang: string }>("https://api.test/", {
+      headers: { "accept-language": "tr" },
+    })
+    expect(tr.data.lang).toBe("tr")
+    expect(calls).toBe(2)
+
+    // But en again hits the cache.
+    const en2 = await m.get<{ lang: string }>("https://api.test/", {
+      headers: { "accept-language": "en" },
+    })
+    expect(en2.data.lang).toBe("en")
+    expect(calls).toBe(2)
+  })
+
+  it("Vary: * forces revalidation every time", async () => {
+    let calls = 0
+    const driver = {
+      name: "vary-star",
+      request: async () => {
+        calls++
+        return jsonResponse(
+          { x: 1 },
+          {
+            headers: {
+              "content-type": "application/json",
+              vary: "*",
+            },
+          },
+        )
+      },
+    }
+
+    const store = memoryStore()
+    const m = withCache(createMisina({ driver, retry: 0 }), { store, ttl: 60_000 })
+
+    await m.get("https://api.test/")
+    await m.get("https://api.test/")
+
+    expect(calls).toBe(2)
+  })
+})