feat(negotiate): RFC 7231 content negotiation with 406 support (#83)

Author: harlan-zw

packages/js/src/negotiate.ts

@@ -1,3 +1,5 @@
+export type ContentNegotiationResult = 'markdown' | 'html' | 'not-acceptable'
+
 interface AcceptEntry {
   type: string
   q: number
@@ -25,7 +27,6 @@ export function parseAcceptHeader(accept: string): AcceptEntry[] {
     }
     else {
       type = part.slice(0, semicolonIdx).trim()
-      // Extract q value without regex for performance
       const paramStr = part.slice(semicolonIdx + 1)
       const qIdx = paramStr.indexOf('q=')
       if (qIdx !== -1) {
@@ -43,36 +44,49 @@ export function parseAcceptHeader(accept: string): AcceptEntry[] {
 }
 
 /**
- * Determine if a client prefers markdown over HTML using proper content negotiation.
- *
- * Uses Accept header quality weights and position ordering:
- * - If text/markdown or text/plain has higher quality than text/html -> markdown
- * - If same quality, earlier position in Accept header wins
- * - Bare wildcard does NOT trigger markdown (prevents breaking OG crawlers)
- * - sec-fetch-dest: document always returns false (browser navigation)
+ * Perform RFC 7231 content negotiation for HTML vs Markdown.
  *
- * @param acceptHeader - The HTTP Accept header value
- * @param secFetchDest - The Sec-Fetch-Dest header value
+ * Resolution rules:
+ * - `Sec-Fetch-Dest: document` always returns `'html'` (browser navigation).
+ * - Missing or empty Accept header returns `'html'` (server picks default).
+ * - q=0 entries are treated as explicit rejections and ignored for matching
+ *   (but still count towards "something was listed").
+ * - `text/markdown` and `text/plain` are the markdown-capable types.
+ * - `text/html` and `application/xhtml+xml` are the html-capable types.
+ * - `*_/_*` and `text/*` are wildcards; they satisfy 406 but never on their
+ *   own tip negotiation towards markdown (preserves OG crawler behavior).
+ * - If nothing in the Accept header can be served (no explicit match, no
+ *   wildcard), returns `'not-acceptable'` so the caller can send 406.
+ * - Otherwise, compares best markdown entry vs best html-or-wildcard entry
+ *   by q, then by position.
  */
-export function shouldServeMarkdown(acceptHeader?: string, secFetchDest?: string): boolean {
-  if (secFetchDest === 'document') {
-    return false
-  }
+export function negotiateContent(acceptHeader?: string, secFetchDest?: string): ContentNegotiationResult {
+  if (secFetchDest === 'document')
+    return 'html'
 
   const accept = acceptHeader || ''
   if (!accept)
-    return false
+    return 'html'
 
-  const parts = accept.split(',')
   let bestMdQ = -1
   let bestMdPos = -1
-  let htmlQ = -1
-  let htmlPos = -1
+  let bestHtmlQ = -1
+  let bestHtmlPos = -1
+  let bestWildcardQ = -1
+  let bestWildcardPos = -1
+  let sawAnyEntry = false
+  let sawAcceptable = false
+  // Track explicit q=0 rejections so wildcard fallback can't resurrect them.
+  let rejectedMd = false
+  let rejectedHtml = false
 
+  const parts = accept.split(',')
   for (let i = 0; i < parts.length; i++) {
     const part = parts[i]!.trim()
     if (!part)
       continue
+    sawAnyEntry = true
+
     const semicolonIdx = part.indexOf(';')
     let type: string
     let q = 1
@@ -82,7 +96,15 @@ export function shouldServeMarkdown(acceptHeader?: string, secFetchDest?: string
     else {
       type = part.slice(0, semicolonIdx).trim()
       const paramStr = part.slice(semicolonIdx + 1)
-      const qIdx = paramStr.indexOf('q=')
+      // Find q= case-insensitively without allocating.
+      let qIdx = -1
+      for (let j = 0; j < paramStr.length - 1; j++) {
+        const c = paramStr.charCodeAt(j)
+        if ((c === 113 || c === 81) && paramStr.charCodeAt(j + 1) === 61 /* = */) {
+          qIdx = j
+          break
+        }
+      }
       if (qIdx !== -1) {
         const qStart = qIdx + 2
         let qEnd = qStart
@@ -93,26 +115,76 @@ export function shouldServeMarkdown(acceptHeader?: string, secFetchDest?: string
       }
     }
 
-    if (type === 'text/markdown' || type === 'text/plain') {
-      if (q > bestMdQ || (q === bestMdQ && (bestMdPos === -1 || i < bestMdPos))) {
+    // Normalize type for case-insensitive comparison (media types per RFC 7231).
+    const normalized = type.toLowerCase()
+
+    if (normalized === 'text/markdown' || normalized === 'text/plain') {
+      if (q === 0) {
+        rejectedMd = true
+        continue
+      }
+      sawAcceptable = true
+      if (q > bestMdQ || (q === bestMdQ && bestMdPos === -1)) {
         bestMdQ = q
         bestMdPos = i
       }
     }
-    else if (type === 'text/html') {
-      htmlQ = q
-      htmlPos = i
+    else if (normalized === 'text/html' || normalized === 'application/xhtml+xml') {
+      if (q === 0) {
+        rejectedHtml = true
+        continue
+      }
+      sawAcceptable = true
+      if (q > bestHtmlQ || (q === bestHtmlQ && bestHtmlPos === -1)) {
+        bestHtmlQ = q
+        bestHtmlPos = i
+      }
+    }
+    else if (normalized === '*/*' || normalized === 'text/*') {
+      if (q === 0)
+        continue
+      sawAcceptable = true
+      if (q > bestWildcardQ || (q === bestWildcardQ && bestWildcardPos === -1)) {
+        bestWildcardQ = q
+        bestWildcardPos = i
+      }
     }
   }
 
+  if (sawAnyEntry && !sawAcceptable)
+    return 'not-acceptable'
+
+  // Apply wildcard fallback only when the concrete type wasn't explicitly rejected.
+  if (bestMdPos === -1 && !rejectedMd && bestWildcardPos !== -1) {
+    bestMdQ = bestWildcardQ
+    bestMdPos = bestWildcardPos
+  }
+  if (bestHtmlPos === -1 && !rejectedHtml && bestWildcardPos !== -1) {
+    bestHtmlQ = bestWildcardQ
+    bestHtmlPos = bestWildcardPos
+  }
+
+  // Both concrete types were explicitly rejected (q=0) and only a wildcard
+  // remained. The wildcard satisfied `sawAcceptable`, but we literally cannot
+  // serve anything the client didn't veto, so 406 is the honest answer.
+  if (bestMdPos === -1 && bestHtmlPos === -1)
+    return 'not-acceptable'
   if (bestMdPos === -1)
-    return false
-  if (htmlPos === -1)
-    return true
-  if (bestMdQ > htmlQ)
-    return true
-  if (bestMdQ === htmlQ && bestMdPos < htmlPos)
-    return true
+    return 'html'
+  if (bestHtmlPos === -1)
+    return 'markdown'
+  if (bestMdQ > bestHtmlQ)
+    return 'markdown'
+  if (bestMdQ === bestHtmlQ && bestMdPos < bestHtmlPos)
+    return 'markdown'
+  return 'html'
+}
 
-  return false
+/**
+ * Determine if a client prefers markdown over HTML. Convenience wrapper over
+ * {@link negotiateContent}; treats `'not-acceptable'` the same as `'html'`
+ * (callers that want 406 semantics should use `negotiateContent` directly).
+ */
+export function shouldServeMarkdown(acceptHeader?: string, secFetchDest?: string): boolean {
+  return negotiateContent(acceptHeader, secFetchDest) === 'markdown'
 }

packages/js/test/unit/negotiate.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from 'vitest'
-import { parseAcceptHeader, shouldServeMarkdown } from '../../src/negotiate'
+import { negotiateContent, parseAcceptHeader, shouldServeMarkdown } from '../../src/negotiate'
 
 describe('parseAcceptHeader', () => {
   it('returns empty array for empty string', () => {
@@ -135,3 +135,80 @@ describe('shouldServeMarkdown', () => {
     expect(shouldServeMarkdown('text/markdown', undefined)).toBe(true)
   })
 })
+
+describe('negotiateContent', () => {
+  it('returns html for sec-fetch-dest: document regardless of Accept', () => {
+    expect(negotiateContent('text/markdown', 'document')).toBe('html')
+    expect(negotiateContent('*/*', 'document')).toBe('html')
+  })
+
+  it('returns html for missing Accept header', () => {
+    expect(negotiateContent()).toBe('html')
+    expect(negotiateContent('')).toBe('html')
+  })
+
+  it('returns html for standard browser Accept header', () => {
+    expect(negotiateContent('text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8')).toBe('html')
+  })
+
+  it('returns html for bare wildcard', () => {
+    expect(negotiateContent('*/*')).toBe('html')
+  })
+
+  it('returns markdown for text/markdown only', () => {
+    expect(negotiateContent('text/markdown')).toBe('markdown')
+  })
+
+  it('returns markdown when text/markdown beats text/html by quality', () => {
+    expect(negotiateContent('text/markdown, text/html;q=0.9, */*;q=0.1')).toBe('markdown')
+  })
+
+  it('returns html when text/html beats text/markdown by quality', () => {
+    expect(negotiateContent('text/markdown;q=0.5, text/html;q=1.0')).toBe('html')
+  })
+
+  it('returns markdown when text/plain has higher q than text/html', () => {
+    expect(negotiateContent('text/html;q=0.5, text/plain;q=0.9')).toBe('markdown')
+  })
+
+  it('returns not-acceptable when Accept lists only unsupported types', () => {
+    expect(negotiateContent('application/x-content-negotiation-probe')).toBe('not-acceptable')
+    expect(negotiateContent('application/json')).toBe('not-acceptable')
+    expect(negotiateContent('application/pdf, application/json')).toBe('not-acceptable')
+  })
+
+  it('returns html when wildcard is present alongside unsupported types', () => {
+    expect(negotiateContent('application/json, */*')).toBe('html')
+  })
+
+  it('treats q=0 as rejection', () => {
+    expect(negotiateContent('text/html;q=0, text/markdown')).toBe('markdown')
+    expect(negotiateContent('text/markdown;q=0, text/html')).toBe('html')
+    expect(negotiateContent('text/html;q=0, application/json;q=0')).toBe('not-acceptable')
+  })
+
+  it('does not let wildcard resurrect explicitly rejected types', () => {
+    // text/html was rejected, so */* can only satisfy markdown.
+    expect(negotiateContent('text/html;q=0, */*;q=1, text/markdown;q=0.5')).toBe('markdown')
+    // text/markdown was rejected, so */* can only satisfy html.
+    expect(negotiateContent('text/markdown;q=0, */*;q=1, text/html;q=0.5')).toBe('html')
+    // Both explicitly rejected; wildcard cannot satisfy anything we can serve.
+    expect(negotiateContent('text/markdown;q=0, text/html;q=0, */*;q=1')).toBe('not-acceptable')
+  })
+
+  it('normalizes media types case-insensitively', () => {
+    expect(negotiateContent('Text/Markdown')).toBe('markdown')
+    expect(negotiateContent('TEXT/HTML')).toBe('html')
+    expect(negotiateContent('Text/Markdown;Q=1')).toBe('markdown')
+    expect(negotiateContent('Application/XHTML+XML')).toBe('html')
+  })
+
+  it('accepts application/xhtml+xml as html-capable', () => {
+    expect(negotiateContent('application/xhtml+xml')).toBe('html')
+  })
+
+  it('respects text/* wildcard as html fallback', () => {
+    expect(negotiateContent('text/*')).toBe('html')
+    expect(negotiateContent('text/markdown, text/*')).toBe('markdown')
+  })
+})

packages/nuxt/src/runtime/server/middleware/mdream.ts

@@ -2,16 +2,16 @@ import type { H3Event } from 'h3'
 import type { MdreamOptions } from 'mdream'
 import type { MdreamMarkdownContext, MdreamNegotiateContext, ModuleRuntimeConfig } from '../../types.js'
 import { withSiteUrl } from '#site-config/server/composables/utils'
-import { shouldServeMarkdown as _shouldServeMarkdown } from '@mdream/js/negotiate'
+import { negotiateContent } from '@mdream/js/negotiate'
 import { consola } from 'consola'
-import { createError, defineEventHandler, getHeader, setHeader } from 'h3'
+import { appendHeader, createError, defineEventHandler, getHeader, setHeader } from 'h3'
 import { htmlToMarkdown } from 'mdream'
 import { useNitroApp, useRuntimeConfig } from 'nitropack/runtime'
 
 const logger = consola.withTag('nuxt-mdream')
 
-function shouldServeMarkdown(event: H3Event): boolean {
-  return _shouldServeMarkdown(
+function negotiate(event: H3Event) {
+  return negotiateContent(
     getHeader(event, 'accept'),
     getHeader(event, 'sec-fetch-dest'),
   )
@@ -76,16 +76,26 @@ export default defineEventHandler(async (event) => {
 
   // Check if we should serve markdown based on Accept header or .md extension
   const hasMarkdownExtension = path.endsWith('.md')
-  let clientPrefersMarkdown = shouldServeMarkdown(event)
+  const negotiation = negotiate(event)
+
+  // Advertise that the response varies by these request headers so caches
+  // don't collapse markdown and html responses together.
+  appendHeader(event, 'Vary', 'Accept, Sec-Fetch-Dest')
+
+  let clientPrefersMarkdown = negotiation === 'markdown'
 
   // Allow users to override the negotiate decision via hook
   const nitroApp = useNitroApp()
   const negotiateContext: MdreamNegotiateContext = { event, shouldServe: clientPrefersMarkdown }
   await nitroApp.hooks.callHook('mdream:negotiate', negotiateContext)
   clientPrefersMarkdown = negotiateContext.shouldServe
 
-  // Early exit: skip if not requesting .md and client doesn't prefer markdown
-  if (!hasMarkdownExtension && !clientPrefersMarkdown) {
+  // Early exit: skip if not requesting .md and client doesn't prefer markdown.
+  // We defer the 406 decision until after fetching downstream, because this
+  // middleware runs for every extensionless route and we can't 406 a JSON-only
+  // endpoint like /health just because Accept didn't list text/*.
+  const wantsNotAcceptable = !hasMarkdownExtension && !clientPrefersMarkdown && negotiation === 'not-acceptable'
+  if (!hasMarkdownExtension && !clientPrefersMarkdown && !wantsNotAcceptable) {
     return
   }
 
@@ -127,9 +137,20 @@ export default defineEventHandler(async (event) => {
           message: `Expected text/html but got ${contentType} for ${path}`,
         })
       }
+      // Not an HTML route, fall through so the non-HTML response is served
       return
     }
 
+    // We now know the route serves HTML. If the client's Accept header listed
+    // nothing we can serve, this is a genuine 406.
+    if (wantsNotAcceptable) {
+      return createError({
+        statusCode: 406,
+        statusMessage: 'Not Acceptable',
+        message: 'This resource can be served as text/html or text/markdown.',
+      })
+    }
+
     html = response._data as string
   }
   catch (e) {