fix(ssr): prevent reloadOnFirstRequest infinite reload loop in hint-stripping browsers (#334) (#376)

* feat(ssr): add one-shot first-request reload guard helpers (#334)

* fix(ssr): guard reloadOnFirstRequest against infinite reload loop (#334)

* fix(ssr): write reload guard cookie only when reloading; test path arg (#334)

Author: AndreyYolkin

packages/vuetify-nuxt-module/src/runtime/plugins/first-request-reload-guard.ts

@@ -0,0 +1,27 @@
+/**
+ * Session cookie marking that the one-time `reloadOnFirstRequest` reload has
+ * already happened this browser session. Prevents an infinite reload loop when
+ * a browser requests client hints but never delivers them (e.g. Brave Shields
+ * strip `Sec-CH-*`), since `firstRequest` would otherwise stay `true` forever (#334).
+ */
+export const RELOAD_GUARD_COOKIE = 'vuetify-nuxt-client-hints-reloaded'
+
+/** True when the guard cookie is present in a `document.cookie` string. */
+export function hasReloadGuardCookie (cookie: string): boolean {
+  const prefix = `${RELOAD_GUARD_COOKIE}=`
+  return cookie.split(';').some(c => c.trim().startsWith(prefix))
+}
+
+/** Build a session guard cookie (no expiry → cleared on browser close). */
+export function buildReloadGuardCookie (path: string): string {
+  return `${RELOAD_GUARD_COOKIE}=1; Path=${path}; SameSite=Lax`
+}
+
+/** Whether to perform the first-request reload: only once per session. */
+export function shouldReloadOnFirstRequest (
+  firstRequest: boolean,
+  reloadOnFirstRequest: boolean,
+  alreadyReloaded: boolean,
+): boolean {
+  return firstRequest && reloadOnFirstRequest && !alreadyReloaded
+}

packages/vuetify-nuxt-module/src/runtime/plugins/vuetify-client-hints.client.ts

@@ -5,6 +5,7 @@ import { defineNuxtPlugin, useNuxtApp, useState } from '#imports'
 import { ssrClientHintsConfiguration } from 'virtual:vuetify-ssr-client-hints-configuration'
 import { reactive, ref, watch } from 'vue'
 import { VuetifyHTTPClientHints } from './client-hints'
+import { buildReloadGuardCookie, hasReloadGuardCookie, shouldReloadOnFirstRequest } from './first-request-reload-guard'
 
 const plugin: Plugin<{
   ssrClientHints: UnwrapNestedRefs<SSRClientHints>
@@ -31,8 +32,17 @@ const plugin: Plugin<{
       prefersColorSchemeOptions,
     } = ssrClientHintsConfiguration
 
-    // reload the page when it is the first request, explicitly configured, and any feature available
-    if (firstRequest && reloadOnFirstRequest) {
+    // reload the page when it is the first request, explicitly configured, and not already
+    // reloaded this session — the guard cookie prevents an infinite loop when the browser
+    // requests client hints but never delivers them (e.g. Brave Shields strip Sec-CH-*) (#334)
+    if (shouldReloadOnFirstRequest(firstRequest, reloadOnFirstRequest, hasReloadGuardCookie(document.cookie))) {
+      // set the one-shot guard cookie (session cookie) immediately before reloading so a
+      // browser that never delivers client hints (e.g. Brave) reloads at most once (#334)
+      const markAndReload = () => {
+        // eslint-disable-next-line unicorn/no-document-cookie
+        document.cookie = buildReloadGuardCookie(prefersColorSchemeOptions?.baseUrl ?? '/')
+        window.location.reload()
+      }
       if (prefersColorScheme) {
         const themeCookie = state.value.colorSchemeCookie
         // write the cookie and refresh the page if configured
@@ -44,22 +54,22 @@ const plugin: Plugin<{
           const newThemeName = prefersDark ? prefersColorSchemeOptions.darkThemeName : prefersColorSchemeOptions.lightThemeName
           // eslint-disable-next-line unicorn/no-document-cookie
           document.cookie = themeCookie.replace(cookieEntry, `${cookieName}=${newThemeName};`)
-          window.location.reload()
+          markAndReload()
         } else if (prefersColorSchemeAvailable) {
-          window.location.reload()
+          markAndReload()
         }
       }
 
       if (prefersReducedMotion && prefersReducedMotionAvailable) {
-        window.location.reload()
+        markAndReload()
       }
 
       if (viewportSize && viewportHeightAvailable) {
-        window.location.reload()
+        markAndReload()
       }
 
       if (viewportSize && viewportWidthAvailable) {
-        window.location.reload()
+        markAndReload()
       }
     }
 

packages/vuetify-nuxt-module/test/first-request-reload-guard.test.ts

@@ -0,0 +1,27 @@
+import { describe, expect, it } from 'vitest'
+import { buildReloadGuardCookie, hasReloadGuardCookie, RELOAD_GUARD_COOKIE, shouldReloadOnFirstRequest } from '../src/runtime/plugins/first-request-reload-guard'
+
+describe('first-request reload guard', () => {
+  it('detects the guard cookie among others', () => {
+    expect(hasReloadGuardCookie(`color-scheme=dark; ${RELOAD_GUARD_COOKIE}=1`)).toBe(true)
+    expect(hasReloadGuardCookie('color-scheme=dark')).toBe(false)
+    expect(hasReloadGuardCookie('')).toBe(false)
+    expect(hasReloadGuardCookie(`x-${RELOAD_GUARD_COOKIE}=1`)).toBe(false)
+  })
+
+  it('builds a session cookie (no Expires/Max-Age)', () => {
+    const c = buildReloadGuardCookie('/')
+    expect(c).toContain(`${RELOAD_GUARD_COOKIE}=1`)
+    expect(c).toContain('Path=/')
+    expect(c).toContain('SameSite=Lax')
+    expect(c).not.toMatch(/Expires|Max-Age/i)
+    expect(buildReloadGuardCookie('/app')).toContain('Path=/app')
+  })
+
+  it('reloads only on a first request when configured and not already reloaded', () => {
+    expect(shouldReloadOnFirstRequest(true, true, false)).toBe(true)
+    expect(shouldReloadOnFirstRequest(true, true, true)).toBe(false)
+    expect(shouldReloadOnFirstRequest(false, true, false)).toBe(false)
+    expect(shouldReloadOnFirstRequest(true, false, false)).toBe(false)
+  })
+})