Skip to content

Commit e5c9d7d

Browse files
committed
fix(start-static-server-functions): fall back to the server function on a cache miss
The client half of `staticFunctionMiddleware` runs for every call in a production browser build and fetched the derived cache URL with no checks: `fetch(url).then((r) => r.json())`. A cache file only exists for calls the prerender pass actually executed, so with prerendering disabled, or for a route the crawler never reached, the request is answered by the application's catch-all route with the HTML shell. `r.json()` then rejected with "Unexpected token '<', "<!DOCTYPE "... is not valid JSON" and took the loader or navigation down with it, instead of falling through to the live server function. Treat an unreadable cache response as a miss. A failed request, a non-ok status, a body that is not JSON, and a body that does not parse all return undefined, which the middleware already handles by calling `ctx.next()`. The content type has to be checked as well as the status, because the HTML shell is served with a 200 in some setups. Also wire up `staticClientCache`, whose lookup was immediately overwritten by the fetch result and so never served anything, and enable the package's unit test script now that it has tests. This does not make prerendering populate the cache for SPA mode, the second half of the report. The build cannot know which server functions a client only route will call, so a live call is the correct outcome there.
1 parent 37877da commit e5c9d7d

5 files changed

Lines changed: 209 additions & 7 deletions

File tree

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
'@tanstack/start-static-server-functions': patch
3+
---
4+
5+
Fix `staticFunctionMiddleware` failing with `Unexpected token '<', "<!DOCTYPE "... is not valid JSON` when no prerendered cache file exists for a call. The client now treats an unreadable or non-JSON cache response as a miss and invokes the server function instead, and a cache hit is reused from the client cache rather than refetched.

‎docs/start/framework/react/guide/static-server-functions.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,3 +33,4 @@ This pattern goes as follows:
3333
- Initially, the prerendered page's html is served and the server function data is embedded in the html
3434
- When the client mounts, the embedded server function data is hydrated
3535
- For future client-side invocations, the server function is replaced with a fetch call to the static JSON file
36+
- If no cached file exists for that key, the call falls back to invoking the server function normally. This happens when prerendering is disabled, or when the call is made from a route that the prerender pass never reached, so a static server function stays usable instead of failing

‎packages/start-static-server-functions/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626
"scripts": {
2727
"clean": "rimraf ./dist && rimraf ./coverage",
2828
"test": "pnpm test:eslint && pnpm test:types && pnpm test:build && pnpm test:unit",
29-
"test:unit": "exit 0; vitest",
29+
"test:unit": "vitest",
3030
"test:unit:dev": "vitest --watch",
3131
"test:eslint": "eslint ./src",
3232
"test:types": "pnpm run \"/^test:types:ts[0-9]{2}$/\"",

‎packages/start-static-server-functions/src/staticFunctionMiddleware.ts‎

Lines changed: 46 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -104,6 +104,17 @@ async function addItemToCache({
104104
}
105105
}
106106

107+
/**
108+
* Look up a prerendered result for this call.
109+
*
110+
* Returns `undefined` for a cache miss so the caller can fall back to invoking
111+
* the server function. A miss is the normal case whenever the cache file was
112+
* never written, for example when `prerender` is disabled or when the route
113+
* that makes this call is not reached during the prerender pass. The request
114+
* for the missing file is then answered by the application's catch-all route,
115+
* which serves the HTML shell, so neither the status code nor the body can be
116+
* trusted without checking.
117+
*/
107118
const fetchItem = async ({
108119
data,
109120
functionId,
@@ -114,13 +125,42 @@ const fetchItem = async ({
114125
const hash = jsonToFilenameSafeString(data)
115126
const url = await getStaticCacheUrl({ functionId, hash })
116127

117-
let result: any = staticClientCache?.get(url)
128+
const cached = staticClientCache?.get(url)
129+
if (cached !== undefined) {
130+
return cached
131+
}
118132

119-
result = await fetch(url, {
120-
method: 'GET',
121-
})
122-
.then((r) => r.json())
123-
.then((d) => fromJSON(d, { plugins: getDefaultSerovalPlugins() }))
133+
let response: Response
134+
try {
135+
response = await fetch(url, {
136+
method: 'GET',
137+
})
138+
} catch {
139+
// The cache file could not be requested at all.
140+
return undefined
141+
}
142+
143+
if (!response.ok) {
144+
return undefined
145+
}
146+
147+
// The HTML shell is served with a 200 in some setups, so the content type is
148+
// what actually distinguishes a cache hit from the fallback document.
149+
if (!response.headers.get('content-type')?.includes('application/json')) {
150+
return undefined
151+
}
152+
153+
let result: any
154+
try {
155+
result = fromJSON(await response.json(), {
156+
plugins: getDefaultSerovalPlugins(),
157+
})
158+
} catch {
159+
// The file exists but is not a payload this build can read.
160+
return undefined
161+
}
162+
163+
staticClientCache?.set(url, result)
124164

125165
return result
126166
}
Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
2+
import { toJSONAsync } from 'seroval'
3+
4+
// `getDefaultSerovalPlugins` reads the Start options through an isomorphic
5+
// function. Uncompiled, that chain resolves to its server implementation and
6+
// wants a Start context in AsyncLocalStorage, which a browser never has. The
7+
// adapter list is irrelevant to the cache lookup under test, so stub it out and
8+
// serialize the fixtures the same way.
9+
vi.mock('@tanstack/start-client-core', async (importOriginal) => {
10+
const actual =
11+
await importOriginal<typeof import('@tanstack/start-client-core')>()
12+
return { ...actual, getDefaultSerovalPlugins: () => [] }
13+
})
14+
15+
const { staticFunctionMiddleware } =
16+
await import('../src/staticFunctionMiddleware')
17+
18+
const clientMiddleware = staticFunctionMiddleware.options.client!
19+
20+
/** The result the live server function produces when the cache is not used. */
21+
const LIVE_RESULT = { result: 'from the server function' }
22+
23+
/**
24+
* Each test uses its own `data`, so it hashes to its own cache URL and cannot
25+
* be served by the module level client cache another test populated.
26+
*/
27+
function callClientMiddleware(data: unknown) {
28+
const next = vi.fn(async () => LIVE_RESULT)
29+
const promise = clientMiddleware({
30+
serverFnMeta: { id: 'test_fn' },
31+
data,
32+
context: {},
33+
next,
34+
} as any)
35+
return { promise, next }
36+
}
37+
38+
function jsonResponse(body: string, status = 200) {
39+
return new Response(body, {
40+
status,
41+
headers: { 'content-type': 'application/json' },
42+
})
43+
}
44+
45+
/** What the application's catch-all route serves for a missing cache file. */
46+
function htmlShellResponse(status = 200) {
47+
return new Response('<!DOCTYPE html><html><body></body></html>', {
48+
status,
49+
headers: { 'content-type': 'text/html' },
50+
})
51+
}
52+
53+
beforeEach(() => {
54+
vi.stubEnv('NODE_ENV', 'production')
55+
})
56+
57+
afterEach(() => {
58+
vi.unstubAllEnvs()
59+
vi.unstubAllGlobals()
60+
vi.restoreAllMocks()
61+
})
62+
63+
describe('staticFunctionMiddleware client on a cache miss', () => {
64+
test('falls back to the server function when the HTML shell is served with a 200', async () => {
65+
vi.stubGlobal(
66+
'fetch',
67+
vi.fn(async () => htmlShellResponse(200)),
68+
)
69+
70+
const { promise, next } = callClientMiddleware({ case: 'html-200' })
71+
72+
await expect(promise).resolves.toBe(LIVE_RESULT)
73+
expect(next).toHaveBeenCalledTimes(1)
74+
})
75+
76+
test('falls back to the server function on a 404', async () => {
77+
vi.stubGlobal(
78+
'fetch',
79+
vi.fn(async () => htmlShellResponse(404)),
80+
)
81+
82+
const { promise, next } = callClientMiddleware({ case: 'html-404' })
83+
84+
await expect(promise).resolves.toBe(LIVE_RESULT)
85+
expect(next).toHaveBeenCalledTimes(1)
86+
})
87+
88+
test('falls back to the server function when the body is not valid JSON', async () => {
89+
vi.stubGlobal(
90+
'fetch',
91+
vi.fn(async () => jsonResponse('not json at all')),
92+
)
93+
94+
const { promise, next } = callClientMiddleware({ case: 'bad-json' })
95+
96+
await expect(promise).resolves.toBe(LIVE_RESULT)
97+
expect(next).toHaveBeenCalledTimes(1)
98+
})
99+
100+
test('falls back to the server function when the request fails outright', async () => {
101+
vi.stubGlobal(
102+
'fetch',
103+
vi.fn(async () => {
104+
throw new TypeError('Failed to fetch')
105+
}),
106+
)
107+
108+
const { promise, next } = callClientMiddleware({ case: 'network-error' })
109+
110+
await expect(promise).resolves.toBe(LIVE_RESULT)
111+
expect(next).toHaveBeenCalledTimes(1)
112+
})
113+
})
114+
115+
describe('staticFunctionMiddleware client on a cache hit', () => {
116+
test('returns the prerendered result without calling the server function', async () => {
117+
const payload = JSON.stringify(
118+
await toJSONAsync({
119+
result: 'from the static cache',
120+
context: { user: 'sean' },
121+
}),
122+
)
123+
const fetchMock = vi.fn(async () => jsonResponse(payload))
124+
vi.stubGlobal('fetch', fetchMock)
125+
126+
const first = callClientMiddleware({ case: 'hit' })
127+
await expect(first.promise).resolves.toMatchObject({
128+
result: 'from the static cache',
129+
context: { user: 'sean' },
130+
})
131+
expect(first.next).not.toHaveBeenCalled()
132+
expect(fetchMock).toHaveBeenCalledTimes(1)
133+
134+
// The same call is served from the client cache rather than refetched.
135+
const second = callClientMiddleware({ case: 'hit' })
136+
await expect(second.promise).resolves.toMatchObject({
137+
result: 'from the static cache',
138+
})
139+
expect(second.next).not.toHaveBeenCalled()
140+
expect(fetchMock).toHaveBeenCalledTimes(1)
141+
})
142+
})
143+
144+
describe('staticFunctionMiddleware client outside production', () => {
145+
test('does not request the cache at all', async () => {
146+
vi.stubEnv('NODE_ENV', 'development')
147+
const fetchMock = vi.fn(async () => jsonResponse('{}'))
148+
vi.stubGlobal('fetch', fetchMock)
149+
150+
const { promise, next } = callClientMiddleware({ case: 'development' })
151+
152+
await expect(promise).resolves.toBe(LIVE_RESULT)
153+
expect(fetchMock).not.toHaveBeenCalled()
154+
expect(next).toHaveBeenCalledTimes(1)
155+
})
156+
})

0 commit comments

Comments
 (0)