fix: isolate docs markdown negotiation

Author: tannerlinsley

src/routes/$libraryId/$version.docs.$.tsx

@@ -4,6 +4,7 @@ import { loadDocs, resolveDocsRedirect } from '~/utils/docs'
 import { findLibrary, getBranch, getLibrary } from '~/libraries'
 import { DocContainer } from '~/components/DocContainer'
 import type { ConfigSchema } from '~/utils/config'
+import { docsContentNegotiationVaryHeader } from '~/utils/http'
 import {
   notFound,
   redirect,
@@ -91,14 +92,14 @@ export const Route = createFileRoute('/$libraryId/$version/docs/$')({
         'cache-control': 'public, max-age=60, must-revalidate',
         'cdn-cache-control':
           'max-age=600, stale-while-revalidate=3600, durable',
-        vary: 'Accept-Encoding',
+        vary: docsContentNegotiationVaryHeader,
       }
     } else {
       return {
         'cache-control': 'public, max-age=3600, must-revalidate',
         'cdn-cache-control':
           'max-age=86400, stale-while-revalidate=604800, durable',
-        vary: 'Accept-Encoding',
+        vary: docsContentNegotiationVaryHeader,
       }
     }
   },

src/routes/$libraryId/$version.docs.tsx

@@ -8,6 +8,7 @@ import { DocsLayout } from '~/components/DocsLayout'
 import { findLibrary } from '~/libraries'
 import { seo } from '~/utils/seo'
 import type { ConfigSchema } from '~/utils/config'
+import { docsContentNegotiationVaryHeader } from '~/utils/http'
 
 export const Route = createFileRoute('/$libraryId/$version/docs')({
   head: (ctx) => {
@@ -30,6 +31,7 @@ export const Route = createFileRoute('/$libraryId/$version/docs')({
     return {
       'cache-control': 'public, max-age=0, must-revalidate',
       'cdn-cache-control': 'max-age=300, stale-while-revalidate=300, durable',
+      vary: docsContentNegotiationVaryHeader,
     }
   },
 })

src/server.ts

@@ -10,10 +10,29 @@ import {
   logRequestStart,
   runWithRequestDiagnostics,
 } from '~/utils/prod-diagnostics.server'
+import { docsContentNegotiationVaryHeader } from '~/utils/http'
 
 installProductionFetchProbe()
 installProductionProcessProbe()
 
+function isBrowserDocumentRequest(request: Request) {
+  return (
+    request.headers.get('Sec-Fetch-Dest') === 'document' ||
+    request.headers.get('Sec-Fetch-Mode') === 'navigate'
+  )
+}
+
+function shouldRewriteDocsRequestToMarkdown(request: Request, url: URL) {
+  const acceptHeader = request.headers.get('Accept') || ''
+
+  return (
+    acceptHeader.includes('text/markdown') &&
+    url.pathname.includes('/docs/') &&
+    !url.pathname.endsWith('.md') &&
+    !isBrowserDocumentRequest(request)
+  )
+}
+
 export default createServerEntry(
   wrapFetchWithSentry({
     async fetch(request) {
@@ -22,20 +41,24 @@ export default createServerEntry(
         logRequestStart(context)
 
         try {
-          const acceptHeader = request.headers.get('Accept') || ''
-          if (
-            acceptHeader.includes('text/markdown') &&
-            url.pathname.includes('/docs/') &&
-            !url.pathname.endsWith('.md')
-          ) {
+          if (shouldRewriteDocsRequestToMarkdown(request, url)) {
             const mdUrl = new URL(request.url)
             mdUrl.pathname = `${url.pathname}.md`
             const mdRequest = new Request(mdUrl, request)
             const mdResponse = await handler.fetch(mdRequest)
+            const markdownHeaders = new Headers(mdResponse.headers)
+            markdownHeaders.set('Vary', docsContentNegotiationVaryHeader)
+
+            const markdownResponse = new Response(mdResponse.body, {
+              status: mdResponse.status,
+              statusText: mdResponse.statusText,
+              headers: markdownHeaders,
+            })
+
             logRequestEnd(context, mdResponse.status, {
               rewrittenToMarkdown: true,
             })
-            return mdResponse
+            return markdownResponse
           }
 
           const response = await handler.fetch(request)

src/utils/http.ts

@@ -0,0 +1,2 @@
+export const docsContentNegotiationVaryHeader =
+  'Accept, Accept-Encoding, Sec-Fetch-Dest, Sec-Fetch-Mode'