Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

fix(view): stop serving a cached Compass over a new install (#460)

KageBinary3eb3fe8f1416
diff --git a/ix-cli/src/cli/__tests__/view-running-port.test.ts b/ix-cli/src/cli/__tests__/view-running-port.test.ts
index e937cabe..78e35b66 100644
--- a/ix-cli/src/cli/__tests__/view-running-port.test.ts
+++ b/ix-cli/src/cli/__tests__/view-running-port.test.ts
@@ -267,15 +267,18 @@ describe("view running port state", () => {
describe("runningInstanceLines", () => {
it("never builds a URL from the requested port", async () => {
const { runningInstanceLines } = await import("../commands/view.js");
- const lines = runningInstanceLines(19123, 19124, true);
+ // The token is supplied so the assertion stays exact; it is the cache bust
+ // that makes an already-running visualizer reachable after `ix upgrade`
+ // replaced the dist underneath it.
+ const lines = runningInstanceLines(19123, 19124, true, "tok");
- expect(lines[0]).toBe(" http://localhost:19123");
+ expect(lines[0]).toBe(" http://localhost:19123/?ix=tok");
expect(lines.some(l => l.includes("http://localhost:19124"))).toBe(false);
});
it("does not warn when the running port is the one that was asked for", async () => {
const { runningInstanceLines } = await import("../commands/view.js");
- expect(runningInstanceLines(8080, 8080, true)).toEqual([" http://localhost:8080"]);
+ expect(runningInstanceLines(8080, 8080, true, "tok")).toEqual([" http://localhost:8080/?ix=tok"]);
});
it("admits it does not know rather than guessing", async () => {
diff --git a/ix-cli/src/cli/__tests__/view-server.test.ts b/ix-cli/src/cli/__tests__/view-server.test.ts
index 37f4c349..86e5a03e 100644
--- a/ix-cli/src/cli/__tests__/view-server.test.ts
+++ b/ix-cli/src/cli/__tests__/view-server.test.ts
@@ -1,11 +1,12 @@
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { spawn, type ChildProcess } from "node:child_process";
-import { mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
+import { mkdirSync, mkdtempSync, writeFileSync, readFileSync, existsSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createServer } from "node:net";
+import { Script } from "node:vm";
import * as http from "node:http";
-import { serverRuntimeArgs, serverScript } from "../commands/view.js";
+import { browserUrl, runningInstanceLines, serverRuntimeArgs, serverScript } from "../commands/view.js";
interface StartServerOptions {
workspaceId?: string;
@@ -370,4 +371,173 @@ describe("view server (/__ix/remap)", () => {
await new Promise<void>((resolve) => hung.close(() => resolve()));
}
}, 20000);
+
+ // ── Cache headers ────────────────────────────────────────────────────────
+ //
+ // Reported as "it reads the new release but looks the same": rc.10 installed,
+ // /.version showed the new stamp, and the screen showed the previous build.
+ // The server sent no cache headers at all — which is not "do not cache". With
+ // no Cache-Control, no ETag and no Last-Modified the browser picks its own
+ // freshness heuristic, and `ix view` reuses 127.0.0.1 on the same port across
+ // upgrades, so the entry point it cached before the upgrade is still a hit
+ // after it. The old index.html then names the old hashed bundles and the
+ // whole previous Compass runs, while /.version is fetched separately and
+ // reports the new build.
+
+ it("never lets the entry point be served from cache", async () => {
+ await startServer({ STUB_EXIT: "0" });
+ const res = await fetch(`http://127.0.0.1:${port}/`);
+ expect(res.status).toBe(200);
+ expect(res.headers.get("cache-control")).toBe("no-store");
+ }, 20000);
+
+ it("never lets the build stamp be served from cache", async () => {
+ // The stamp is what a bug report quotes. A stale one is worse than none:
+ // it makes the wrong build look like the right one.
+ writeFileSync(join(distDir, ".version"), "0.10.0-rc.10+release.6bce261\n");
+ await startServer({ STUB_EXIT: "0" });
+ const res = await fetch(`http://127.0.0.1:${port}/.version`);
+ expect(res.status).toBe(200);
+ expect(await res.text()).toContain("0.10.0-rc.10");
+ expect(res.headers.get("cache-control")).toBe("no-store");
+ }, 20000);
+
+ it("keeps fingerprinted assets cacheable", async () => {
+ // The point is not to disable caching — everything under assets/ is named
+ // by its own content, so it is safe to keep and expensive to refetch.
+ mkdirSync(join(distDir, "assets"), { recursive: true });
+ writeFileSync(join(distDir, "assets", "index-BbVrNAev.js"), "export const x = 1;\n");
+ await startServer({ STUB_EXIT: "0" });
+ const res = await fetch(`http://127.0.0.1:${port}/assets/index-BbVrNAev.js`);
+ expect(res.status).toBe(200);
+ expect(res.headers.get("cache-control")).toBe("public, max-age=31536000, immutable");
+ }, 20000);
+
+ it("does not let a missing asset poison the cache with the SPA fallback", async () => {
+ // A stale index.html asks for a bundle that no longer exists. The fallback
+ // answers with index.html, and caching *that* under the asset's URL is how
+ // one bad load becomes permanent.
+ await startServer({ STUB_EXIT: "0" });
+ const res = await fetch(`http://127.0.0.1:${port}/assets/index-GONE.js`);
+ expect(res.headers.get("cache-control")).toBe("no-store");
+ }, 20000);
+
+ it("only marks a file immutable when its name carries a content hash", async () => {
+ // Being under assets/ is not the claim that makes a year-long pin safe --
+ // a name that changes with the bytes is, and Compass is built in another
+ // repo, so nothing here can verify what it puts in that directory. One
+ // stable name pinned for a year against a fixed origin has no revalidation
+ // path and no recovery short of clearing site data.
+ mkdirSync(join(distDir, "assets"), { recursive: true });
+ writeFileSync(join(distDir, "assets", "logo.svg"), "<svg/>");
+ writeFileSync(join(distDir, "assets", "vendor-2f9ab31c.css"), "body{}");
+ await startServer({ STUB_EXIT: "0" });
+
+ const unhashed = await fetch(`http://127.0.0.1:${port}/assets/logo.svg`);
+ expect(unhashed.status).toBe(200);
+ expect(unhashed.headers.get("cache-control")).toBe("no-store");
+
+ const hashed = await fetch(`http://127.0.0.1:${port}/assets/vendor-2f9ab31c.css`);
+ expect(hashed.status).toBe(200);
+ expect(hashed.headers.get("cache-control")).toBe("public, max-age=31536000, immutable");
+ }, 20000);
+
+ it("refuses to read outside the dist directory", async () => {
+ // url.parse leaves dot-dot segments intact and path.join resolves straight
+ // out of the tree. A browser normalises the path before sending, so the
+ // reader here is another local process -- which still gets a file read as
+ // whoever ran the CLI. --path-as-is is how curl reproduces it; fetch()
+ // normalises, so the request is built by hand.
+ await startServer({ STUB_EXIT: "0" });
+ const outside = join(distDir, "..", "outside-secret.txt");
+ writeFileSync(outside, "top secret");
+ try {
+ const status = await new Promise<{ code: number; body: string }>((resolve, reject) => {
+ const req = http.request(
+ { host: "127.0.0.1", port, path: "/../outside-secret.txt", method: "GET" },
+ (res) => {
+ let body = "";
+ res.on("data", (c) => (body += c));
+ res.on("end", () => resolve({ code: res.statusCode ?? 0, body }));
+ },
+ );
+ req.on("error", reject);
+ req.end();
+ });
+ expect(status.body).not.toContain("top secret");
+ expect(status.code).toBe(404);
+ } finally {
+ rmSync(outside, { force: true });
+ }
+ }, 20000);
+
+ it("does not let an extensionless /assets/ miss poison the cache", async () => {
+ // The case above has an extension, so it takes the readFile-error branch
+ // and its hardcoded no-store — it never reaches the asset/entry decision at
+ // all. Without an extension the *earlier* SPA rewrite fires instead:
+ // filePath becomes index.html and readFile succeeds, so the response body
+ // is the entry point while the URL still says /assets/. Choosing the policy
+ // from the URL stamps that body `immutable` for a year, which is this bug
+ // made permanent. Choosing it from the resolved file does not.
+ await startServer({ STUB_EXIT: "0" });
+ const res = await fetch(`http://127.0.0.1:${port}/assets/index-GONE`);
+ expect(res.status).toBe(200);
+ // Proof the body really is the entry point, not a 404 that happens to
+ // carry the right header.
+ expect(await res.text()).toContain("fake compass");
+ expect(res.headers.get("cache-control")).toBe("no-store");
+ }, 20000);
+
+});
+
+// ── Entry-point cache busting ────────────────────────────────────────────────
+//
+// `no-store` fixes the *next* upgrade. It cannot fix the one the reporter just
+// ran: their browser cached `/` before it, so it never issues the request that
+// would carry the new header. A different query string is a different cache
+// key, which is the only thing that reaches an entry the browser is not asking
+// about.
+describe("view URLs", () => {
+ it("busts the cache key on every URL the CLI names", () => {
+ expect(browserUrl("http://localhost:4173", "abc123")).toBe(
+ "http://localhost:4173/?ix=abc123",
+ );
+ // The already-running branch is the reporter's path: `ix upgrade` replaces
+ // the dist in place and leaves the server up, so the next `ix view` prints
+ // a URL and opens nothing. A bust on the opened tab alone would miss it.
+ expect(runningInstanceLines(8080, 8080, false, "abc123")).toEqual([
+ " http://localhost:8080/?ix=abc123",
+ ]);
+ // …and the port-mismatch advice still comes with it.
+ expect(runningInstanceLines(19123, 19124, true, "abc123")[0]).toBe(
+ " http://localhost:19123/?ix=abc123",
+ );
+ });
+
+ it("uses a fresh key per invocation rather than the build stamp", () => {
+ // The entry point is `no-store` now, so there is no cache entry a repeat
+ // start could have hit and nothing is lost by changing the key every time.
+ // A stamp would have to be read from the dist — which a dev build does not
+ // have, exactly where an iterating developer needs this most.
+ expect(browserUrl("http://localhost:4173")).toMatch(/^http:\/\/localhost:4173\/\?ix=[a-z0-9]+$/);
+ expect(browserUrl("http://localhost:4173")).toBe(browserUrl("http://localhost:4173"));
+ });
+});
+
+// The server script is emitted from a template literal, so a stray backtick
+// anywhere in it — including inside a comment — ends the literal, and a
+// backslash escape is eaten before it reaches the generated file. Both have
+// happened; the second took the server down, and a backtick in a comment
+// warning about backticks is what broke this block most recently. Compiling
+// the emitted source is the check that would have caught every one of them.
+describe("generated server script", () => {
+ it("is syntactically valid JavaScript", () => {
+ expect(() => new Script(serverScript())).not.toThrow();
+ });
+
+ it("carries no backtick or backslash into the emitted file", () => {
+ const script = serverScript();
+ expect(script).not.toContain("`");
+ expect(script).not.toContain("\\");
+ });
});
diff --git a/ix-cli/src/cli/commands/view.ts b/ix-cli/src/cli/commands/view.ts
index 2788bb9c..36f9e407 100644
--- a/ix-cli/src/cli/commands/view.ts
+++ b/ix-cli/src/cli/commands/view.ts
@@ -126,11 +126,18 @@ function readRunningPort(): number | null {
*
* Pure, because the decision is all this is, and inline in a command action it
* could only be exercised by launching a detached server.
+ *
+ * `token` is threaded rather than read from `CACHE_BUST` so this stays pure.
+ * The URL it prints carries the bust for a reason: `ix upgrade` replaces the
+ * dist in place and leaves the server running, so the next `ix view` lands
+ * here, prints a URL and opens nothing. That is the reporter's exact path, and
+ * a bust that only covered the opened tab would miss it.
*/
export function runningInstanceLines(
runningPort: number | null,
requestedPort: number,
portWasRequested: boolean,
+ token: string = CACHE_BUST,
): string[] {
if (runningPort === null) {
return [
@@ -139,7 +146,7 @@ export function runningInstanceLines(
];
}
- const lines = [` http://localhost:${runningPort}`];
+ const lines = [` ${browserUrl(`http://localhost:${runningPort}`, token)}`];
if (portWasRequested && runningPort !== requestedPort) {
lines.push(`[!] You asked for port ${requestedPort}, but it is serving on ${runningPort}.`);
lines.push(` Run 'ix view stop' then 'ix view -p ${requestedPort}' to move it.`);
@@ -311,6 +318,50 @@ const MIME = {
".map": "application/json",
};
+// ── Cache policy ────────────────────────────────────────────────────────────
+//
+// Sending no cache headers is not the same as sending "do not cache": with no
+// Cache-Control, no ETag and no Last-Modified, a browser picks its own freshness
+// heuristic and may reuse a response without ever asking. This server always
+// serves 127.0.0.1 on a port it reuses, so that cache outlives an upgrade -- the
+// old index.html comes back, names the old content-hashed bundles, and the
+// entire previous Compass runs while /.version, fetched separately, reports the
+// new build. The result is a status bar that says the fix shipped while the
+// screen shows the build before it.
+//
+// The decision is keyed on the file about to be sent, never on the URL that
+// asked for it. Those are not the same path: the SPA fallback rewrites filePath
+// to index.html for any extensionless miss, so GET /assets/anything answers with
+// index.html -- and deciding from the URL would stamp the entry point
+// "immutable" for a year under an /assets/ key, which is the permanent form of
+// the bug this exists to prevent.
+//
+// A content hash in the name is what makes "keep this forever" safe: the name
+// changes whenever the bytes do. Sitting under assets/ is not the same claim.
+// Compass is built in another repo, so nothing here can verify what it puts
+// there, and one stable name -- a hand-placed file, a build whose
+// assetFileNames drops [hash] -- would be pinned in a user's browser for a year
+// against a fixed origin, with no revalidation path and no recovery short of
+// clearing site data. So the guard checks for the hash it is asserting. The
+// charset excludes the dash on purpose: a hash containing one simply misses
+// the optimisation and is revalidated, while my-long-name.css matching would
+// be the unrecoverable direction.
+//
+// No backslash escapes and no backticks anywhere in this block: the whole
+// script is emitted from a template literal, so an escape is eaten before it
+// reaches the generated file and a backtick ends the literal outright. Both
+// were tried here; the second took the server down. Hence a bracketed dot
+// rather than an escaped one, path.sep rather than a literal separator, and
+// no backticks even inside these comments -- one here ends the literal just
+// as surely as one in the code, which is how this block first failed to parse.
+const DIST_ROOT = path.resolve(DIST);
+const ASSET_PREFIX = path.join(DIST_ROOT, "assets") + path.sep;
+const FINGERPRINTED = /-[A-Za-z0-9_]{8,}[.]/;
+const cacheControl = (f) =>
+ f.startsWith(ASSET_PREFIX) && FINGERPRINTED.test(path.basename(f))
+ ? "public, max-age=31536000, immutable"
+ : "no-store";
+
const server = http.createServer((req, res) => {
const parsed = url.parse(req.url);
const pathname = parsed.pathname || "/";
@@ -449,8 +500,22 @@ const server = http.createServer((req, res) => {
return;
}
- // Serve static files
- let filePath = path.join(DIST, pathname === "/" ? "index.html" : pathname);
+ // Serve static files.
+ let filePath = path.resolve(path.join(DIST, pathname === "/" ? "index.html" : pathname));
+
+ // Everything served comes from inside DIST. url.parse does not normalise
+ // a dot-dot segment, and path.join resolves straight out of the tree, so
+ // without this GET /../../../../etc/passwd is read and returned 200. A
+ // browser normalises dot-dot before sending, so the exposure is to other local
+ // processes reading files as the user who ran the CLI rather than as
+ // themselves -- which is still a file read this server has no business
+ // doing. Checked before the SPA fallback, because an escaping path that
+ // happens to exist never reaches it.
+ if (filePath !== DIST_ROOT && !filePath.startsWith(DIST_ROOT + path.sep)) {
+ res.writeHead(404, { "Content-Type": "text/plain", "Cache-Control": "no-store" });
+ res.end("Not found");
+ return;
+ }
// SPA fallback: if file doesn't exist and no extension, serve index.html
if (!fs.existsSync(filePath) && !path.extname(filePath)) {
@@ -466,14 +531,20 @@ const server = http.createServer((req, res) => {
res.end("Not found");
return;
}
- res.writeHead(200, { "Content-Type": "text/html" });
+ res.writeHead(200, {
+ "Content-Type": "text/html",
+ "Cache-Control": "no-store",
+ });
res.end(fallback);
});
return;
}
const ext = path.extname(filePath).toLowerCase();
const mime = MIME[ext] || "application/octet-stream";
- res.writeHead(200, { "Content-Type": mime });
+ res.writeHead(200, {
+ "Content-Type": mime,
+ "Cache-Control": cacheControl(filePath),
+ });
res.end(data);
});
});
@@ -484,6 +555,43 @@ server.listen(PORT, "127.0.0.1", () => {
`;
}
+/**
+ * One cache-bust token per CLI invocation.
+ *
+ * Base-36 milliseconds: short, URL-safe, and made here rather than read from
+ * anywhere, so nothing on disk reaches the shell `openBrowser` runs.
+ */
+const CACHE_BUST = Date.now().toString(36);
+
+/**
+ * The visualizer URL, with the cache-bust token.
+ *
+ * `Cache-Control: no-store` only reaches a response the browser actually asks
+ * for. The client that reported this cached `/` before the upgrade, so it never
+ * asks — its entry is still fresh, it keeps serving the old index.html naming
+ * the old hashed bundles, and it never learns the policy changed. `ix view`
+ * reuses 127.0.0.1 on the same port across upgrades, so that entry outlives the
+ * install meant to replace it. Without a different key the header is
+ * prospective only: it protects the next upgrade, not the one the user just
+ * ran, which is the one they are looking at.
+ *
+ * Every URL the CLI names goes through this, not just the one it opens. The
+ * reporter's path is `ix upgrade` (which replaces the dist in place and leaves
+ * the server running) then `ix view`, which takes the already-running branch
+ * and only *prints* a URL; a bust on the opened tab alone would miss it
+ * entirely, along with `--no-open`, a copied URL and a bookmark.
+ *
+ * Per invocation rather than keyed on the build stamp. The entry point is
+ * `no-store` now, so there is no cache entry a repeat start could have hit and
+ * nothing is lost by changing the key every time — while a stamp would have to
+ * be read from the dist, which is absent in a dev build, exactly where an
+ * iterating developer needs this most. Assets keep their own URLs, so they
+ * still come from cache.
+ */
+export function browserUrl(serverUrl: string, token: string = CACHE_BUST): string {
+ return `${serverUrl}/?ix=${token}`;
+}
+
function openBrowser(url: string): void {
try {
const plat = platform();
@@ -647,7 +755,11 @@ export function registerViewCommand(program: Command): void {
writeFileSync(SCOPE_FILE, scopeKey);
writeFileSync(PORT_FILE, String(port));
- const url = `http://localhost:${port}`;
+ // One URL, printed and opened. They used to differ: only the opened
+ // one carried the cache bust, so --no-open, a copied URL, a bookmark
+ // and the not-ready branch below all still resolved to the entry the
+ // browser cached before the upgrade.
+ const url = browserUrl(`http://localhost:${port}`);
// Reported rather than fatal: the wait is a heuristic, and a machine slow
// enough to exceed it would otherwise have a working visualizer killed off