feat(webui): Add cache control for static files. #1235
Conversation
WalkthroughImplements explicit Cache-Control handling for static assets in the web UI server. Switches to default import for @fastify/static. Adds a helper to set headers based on request paths, configuring no-cache for index.html (and settings.json in SPA) and long-term caching for other assets. Updates static route registrations to use setHeaders. Changes
Sequence Diagram(s)sequenceDiagram
participant Client
participant Fastify
participant StaticPlugin as @fastify/static
participant CacheHelper as setCacheHeaders
Client->>Fastify: GET /... (static asset)
Fastify->>StaticPlugin: serve file with setHeaders
StaticPlugin->>CacheHelper: setCacheHeaders(res, req.path, extraNoCachePaths)
alt Path is /index.html or in extraNoCachePaths
CacheHelper-->>StaticPlugin: Cache-Control: public, max-age=0
else
CacheHelper-->>StaticPlugin: Cache-Control: public, max-age=31536000, immutable
end
StaticPlugin-->>Client: 200 OK + headers + file
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Tip 🔌 Remote MCP (Model Context Protocol) integration is now available!Pro plan users can now connect to remote MCP servers from the Integrations page. Connect with popular remote MCPs such as Notion and Linear to add more context to your reviews and chats. ✨ Finishing Touches
🧪 Generate unit tests
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR/Issue comments)Type Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
📜 Review details
Configuration used: CodeRabbit UI
Review profile: ASSERTIVE
Plan: Pro
💡 Knowledge Base configuration:
- MCP integration is disabled by default for public repositories
- Jira integration is disabled by default for public repositories
- Linear integration is disabled by default for public repositories
You can enable these sources in your CodeRabbit configuration.
📒 Files selected for processing (1)
components/webui/server/src/routes/static.ts(2 hunks)
🧰 Additional context used
📓 Path-based instructions (1)
**/*.{cpp,hpp,java,js,jsx,tpp,ts,tsx}
⚙️ CodeRabbit Configuration File
- Prefer
false == <expression>rather than!<expression>.
Files:
components/webui/server/src/routes/static.ts
🧠 Learnings (2)
📓 Common learnings
Learnt from: davemarco
PR: y-scope/clp#1015
File: components/log-viewer-webui/server/src/routes/static.ts:65-70
Timestamp: 2025-06-16T13:05:27.349Z
Learning: In components/log-viewer-webui/server/src/routes/static.ts, when decorateReply is set to true in fastifyStatic configuration, the reply.sendFile() method automatically uses the root directory configured in the static plugin registration, eliminating the need to pass the root directory as a second parameter.
📚 Learning: 2025-06-16T13:05:27.349Z
Learnt from: davemarco
PR: y-scope/clp#1015
File: components/log-viewer-webui/server/src/routes/static.ts:65-70
Timestamp: 2025-06-16T13:05:27.349Z
Learning: In components/log-viewer-webui/server/src/routes/static.ts, when decorateReply is set to true in fastifyStatic configuration, the reply.sendFile() method automatically uses the root directory configured in the static plugin registration, eliminating the need to pass the root directory as a second parameter.
Applied to files:
components/webui/server/src/routes/static.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: lint-check (ubuntu-24.04)
🔇 Additional comments (1)
components/webui/server/src/routes/static.ts (1)
104-107: SPA fallback looks correct and aligns with prior learning
With decorateReply: true on the client static registration, reply.sendFile("index.html") uses the configured root automatically, matching our prior learning.
| import {fileURLToPath} from "node:url"; | ||
|
|
||
| import {fastifyStatic} from "@fastify/static"; | ||
| import fastifyStatic from "@fastify/static"; |
There was a problem hiding this comment.
Fix type reference for FastifyStaticOptions — default import doesn’t expose types
fastifyStatic.FastifyStaticOptions will not resolve when using a default import. Bring the type in via a separate type-only import to avoid a TS compile error.
Apply this diff to add the type import:
import fastifyStatic from "@fastify/static";
+import type { FastifyStaticOptions } from "@fastify/static";📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| import fastifyStatic from "@fastify/static"; | |
| import fastifyStatic from "@fastify/static"; | |
| import type { FastifyStaticOptions } from "@fastify/static"; |
🤖 Prompt for AI Agents
In components/webui/server/src/routes/static.ts around line 4, the code uses a
default import (import fastifyStatic from "@fastify/static") and references
fastifyStatic.FastifyStaticOptions which doesn't resolve; add a separate
type-only import like `import type { FastifyStaticOptions } from
"@fastify/static"` and replace usages of fastifyStatic.FastifyStaticOptions with
the imported FastifyStaticOptions type while keeping the existing default import
for runtime use.
| const CACHE_CONTROL_HEADER_KEY = "Cache-Control"; | ||
| const CACHE_CONTROL_HEADER_VALUE_NO_CACHE = "public, max-age=0"; | ||
|
|
||
| // Cache all other static files for 1 year without revalidation. | ||
| const CACHE_CONTROL_HEADER_VALUE_LONG_TERM_CACHE = "public, max-age=31536000, immutable"; | ||
|
|
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Optional: strengthen revalidation for no-cache responses
If you want stricter behaviour for intermediaries, consider appending must-revalidate to the no-cache value. Current value is broadly fine; this is a belt-and-suspenders tweak.
-const CACHE_CONTROL_HEADER_VALUE_NO_CACHE = "public, max-age=0";
+const CACHE_CONTROL_HEADER_VALUE_NO_CACHE = "public, max-age=0, must-revalidate";📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const CACHE_CONTROL_HEADER_KEY = "Cache-Control"; | |
| const CACHE_CONTROL_HEADER_VALUE_NO_CACHE = "public, max-age=0"; | |
| // Cache all other static files for 1 year without revalidation. | |
| const CACHE_CONTROL_HEADER_VALUE_LONG_TERM_CACHE = "public, max-age=31536000, immutable"; | |
| const CACHE_CONTROL_HEADER_KEY = "Cache-Control"; | |
| const CACHE_CONTROL_HEADER_VALUE_NO_CACHE = "public, max-age=0, must-revalidate"; | |
| // Cache all other static files for 1 year without revalidation. | |
| const CACHE_CONTROL_HEADER_VALUE_LONG_TERM_CACHE = "public, max-age=31536000, immutable"; |
🤖 Prompt for AI Agents
In components/webui/server/src/routes/static.ts around lines 10 to 15, the
no-cache header value should enforce stronger revalidation by intermediaries;
change the CACHE_CONTROL_HEADER_VALUE_NO_CACHE constant to include
must-revalidate (e.g. "public, max-age=0, must-revalidate") so that proxies and
caches are required to revalidate before serving cached responses.
| const setCacheHeaders = ( | ||
| res: Parameters<NonNullable<fastifyStatic.FastifyStaticOptions["setHeaders"]>>[0], | ||
| reqPath: string, | ||
| extraNoCachePaths: string[] = [] | ||
| ): void => { | ||
| const noCachePaths = [ | ||
| "/index.html", | ||
| ...extraNoCachePaths, | ||
| ]; | ||
|
|
||
| if (noCachePaths.some((noCachePath) => reqPath.endsWith(noCachePath))) { | ||
| res.setHeader(CACHE_CONTROL_HEADER_KEY, CACHE_CONTROL_HEADER_VALUE_NO_CACHE); | ||
|
|
||
| return; | ||
| } | ||
|
|
||
| res.setHeader(CACHE_CONTROL_HEADER_KEY, CACHE_CONTROL_HEADER_VALUE_LONG_TERM_CACHE); | ||
| }; |
There was a problem hiding this comment.
🛠️ Refactor suggestion
Make no-cache matching OS-agnostic (Windows path separators)
reqPath passed to setHeaders is a filesystem path. On Windows it uses backslashes, so endsWith("/index.html") won’t match. Normalise path separators before checking suffixes.
const setCacheHeaders = (
res: Parameters<NonNullable<FastifyStaticOptions["setHeaders"]>>[0],
reqPath: string,
extraNoCachePaths: string[] = []
): void => {
+ // Normalise to POSIX-style separators so suffix checks work on all OSes
+ const normalizedReqPath = reqPath.split(path.win32.sep).join("/");
const noCachePaths = [
"/index.html",
...extraNoCachePaths,
];
- if (noCachePaths.some((noCachePath) => reqPath.endsWith(noCachePath))) {
+ if (noCachePaths.some((noCachePath) => normalizedReqPath.endsWith(noCachePath))) {
res.setHeader(CACHE_CONTROL_HEADER_KEY, CACHE_CONTROL_HEADER_VALUE_NO_CACHE);
return;
}
res.setHeader(CACHE_CONTROL_HEADER_KEY, CACHE_CONTROL_HEADER_VALUE_LONG_TERM_CACHE);
};📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const setCacheHeaders = ( | |
| res: Parameters<NonNullable<fastifyStatic.FastifyStaticOptions["setHeaders"]>>[0], | |
| reqPath: string, | |
| extraNoCachePaths: string[] = [] | |
| ): void => { | |
| const noCachePaths = [ | |
| "/index.html", | |
| ...extraNoCachePaths, | |
| ]; | |
| if (noCachePaths.some((noCachePath) => reqPath.endsWith(noCachePath))) { | |
| res.setHeader(CACHE_CONTROL_HEADER_KEY, CACHE_CONTROL_HEADER_VALUE_NO_CACHE); | |
| return; | |
| } | |
| res.setHeader(CACHE_CONTROL_HEADER_KEY, CACHE_CONTROL_HEADER_VALUE_LONG_TERM_CACHE); | |
| }; | |
| const setCacheHeaders = ( | |
| res: Parameters<NonNullable<fastifyStatic.FastifyStaticOptions["setHeaders"]>>[0], | |
| reqPath: string, | |
| extraNoCachePaths: string[] = [] | |
| ): void => { | |
| // Normalise to POSIX-style separators so suffix checks work on all OSes | |
| const normalizedReqPath = reqPath.split(path.win32.sep).join("/"); | |
| const noCachePaths = [ | |
| "/index.html", | |
| ...extraNoCachePaths, | |
| ]; | |
| if (noCachePaths.some((noCachePath) => normalizedReqPath.endsWith(noCachePath))) { | |
| res.setHeader(CACHE_CONTROL_HEADER_KEY, CACHE_CONTROL_HEADER_VALUE_NO_CACHE); | |
| return; | |
| } | |
| res.setHeader(CACHE_CONTROL_HEADER_KEY, CACHE_CONTROL_HEADER_VALUE_LONG_TERM_CACHE); | |
| }; |
🤖 Prompt for AI Agents
In components/webui/server/src/routes/static.ts around lines 24 to 41, the
no-cache check uses reqPath.endsWith("/index.html") which fails on Windows
because reqPath can contain backslashes; normalize path separators (e.g. replace
backslashes with forward slashes or use a path-normalization utility) before
performing the endsWith checks so the noCachePaths comparisons are OS-agnostic.
| * @param extraNoCachePaths | ||
| */ | ||
| const setCacheHeaders = ( | ||
| res: Parameters<NonNullable<fastifyStatic.FastifyStaticOptions["setHeaders"]>>[0], |
There was a problem hiding this comment.
Use the proper type name instead of fastifyStatic.FastifyStaticOptions
This reference will fail under default import; switch to the named type.
- res: Parameters<NonNullable<fastifyStatic.FastifyStaticOptions["setHeaders"]>>[0],
+ res: Parameters<NonNullable<FastifyStaticOptions["setHeaders"]>>[0],📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| res: Parameters<NonNullable<fastifyStatic.FastifyStaticOptions["setHeaders"]>>[0], | |
| res: Parameters<NonNullable<FastifyStaticOptions["setHeaders"]>>[0], |
🤖 Prompt for AI Agents
In components/webui/server/src/routes/static.ts around line 25, the parameter
type references fastifyStatic.FastifyStaticOptions which breaks under a default
import; change to the named type from the package (e.g. import type {
FastifyStaticOptions } from 'fastify-static') and use FastifyStaticOptions in
the signature, ensuring the import is a named type import rather than relying on
a default namespace import.
| // Prevent fastify-static from adding its own cache headers and provide our own. | ||
| cacheControl: false, | ||
| setHeaders: (res, reqPath) => { | ||
| setCacheHeaders(res, reqPath); | ||
| }, | ||
| }); |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Minor TS ergonomics: include the third ‘stat’ parameter for signature parity
Not required at runtime, but including the third arg avoids potential typing friction if lib definitions tighten.
- setHeaders: (res, reqPath) => {
- setCacheHeaders(res, reqPath);
- },
+ setHeaders: (res, reqPath, _stat) => {
+ setCacheHeaders(res, reqPath);
+ },📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // Prevent fastify-static from adding its own cache headers and provide our own. | |
| cacheControl: false, | |
| setHeaders: (res, reqPath) => { | |
| setCacheHeaders(res, reqPath); | |
| }, | |
| }); | |
| // Prevent fastify-static from adding its own cache headers and provide our own. | |
| cacheControl: false, | |
| setHeaders: (res, reqPath, _stat) => { | |
| setCacheHeaders(res, reqPath); | |
| }, | |
| }); |
🤖 Prompt for AI Agents
In components/webui/server/src/routes/static.ts around lines 80 to 85, the
setHeaders callback currently declares only (res, reqPath) which mismatches the
expected signature; add the third parameter (stat) to the function signature for
TypeScript parity (e.g. (res, reqPath, _stat) => { setCacheHeaders(res,
reqPath); }) and name it with a leading underscore to avoid unused-variable lint
errors; no runtime change is needed beyond the signature update.
| // Prevent fastify-static from adding its own cache headers and provide our own. | ||
| cacheControl: false, | ||
| setHeaders: (res, reqPath) => { | ||
| setCacheHeaders(res, reqPath, ["/settings.json"]); | ||
| }, | ||
| }); |
There was a problem hiding this comment.
🧹 Nitpick (assertive)
Same as above: include third ‘stat’ param and simplify wrapper
Keeps callback shape consistent with @fastify/static definitions.
- setHeaders: (res, reqPath) => {
- setCacheHeaders(res, reqPath, ["/settings.json"]);
- },
+ setHeaders: (res, reqPath, _stat) => {
+ setCacheHeaders(res, reqPath, ["/settings.json"]);
+ },📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| // Prevent fastify-static from adding its own cache headers and provide our own. | |
| cacheControl: false, | |
| setHeaders: (res, reqPath) => { | |
| setCacheHeaders(res, reqPath, ["/settings.json"]); | |
| }, | |
| }); | |
| // Prevent fastify-static from adding its own cache headers and provide our own. | |
| cacheControl: false, | |
| setHeaders: (res, reqPath, _stat) => { | |
| setCacheHeaders(res, reqPath, ["/settings.json"]); | |
| }, | |
| }); |
🤖 Prompt for AI Agents
In components/webui/server/src/routes/static.ts around lines 97 to 102, the
setHeaders wrapper currently has only (res, reqPath) but must match
@fastify/static's signature; change it to accept the third stat parameter and
pass it through to setCacheHeaders (i.e. setHeaders: (res, reqPath, stat) =>
setCacheHeaders(res, reqPath, stat, ["/settings.json"])), simplifying the
wrapper by forwarding all three args instead of omitting stat.
Good point. do note adding cache control headers does help reduce load on the Fastify server in all cases. While it's technically possible, and probably most efficient, to handle this in any proxy server's configuration, doing so requires the maintainer to understand our webui's architecture, which is less convenient. our arch may also change over time by setting the headers in the Fastify server itself, we make the caching hints more self-contained. If a maintainer wants to apply additional or alternative caching rules, they can still override these headers in their proxy configuration |
Description
Add Cache-Control headers for static files to reduce network traffic
Checklist
breaking change.
Validation performed
Below test was done without the changes in #1234
Stress test
F12to open Developer Console in the browser.Inspect headers
Idled for 1 minute so that the rate limit recovered from the above stress test.
The Web UI SPA
The log viewer SPA
clp-package/sbin/compress.sh ~/sample/hive-24hrSummary by CodeRabbit
New Features
Bug Fixes