Skip to content

Commit 58a407c

Browse files
authored
feat(desktop): prepare server bytecode cache in native builds (#28572)
1 parent da21606 commit 58a407c

11 files changed

Lines changed: 345 additions & 12 deletions

‎apps/desktop/scripts/main-process-bundle.test.mjs‎

Lines changed: 5 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ import * as NodeFSP from "node:fs/promises";
33
import * as NodeOS from "node:os";
44
import * as NodePath from "node:path";
55
import * as NodeVM from "node:vm";
6+
import * as NodeURL from "node:url";
67
import { build } from "vite-plus/pack";
78
import { assert, it } from "vite-plus/test";
89

@@ -114,18 +115,16 @@ it("loads the emitted packaged boot entry and backend cache preload", async () =
114115
const directory = await NodeFSP.mkdtemp(NodePath.join(NodeOS.tmpdir(), "t3-desktop-boot-"));
115116
try {
116117
const entries = ["src/boot.ts", "src/compileCache.ts"];
117-
await NodeFSP.mkdir(NodePath.join(directory, "src"));
118-
await Promise.all(
119-
entries.map((entry) =>
120-
NodeFSP.copyFile(new URL(`../${entry}`, import.meta.url), NodePath.join(directory, entry)),
121-
),
122-
);
123118
assert.ok(Array.isArray(desktopConfig.pack));
124119
for (const packConfig of desktopConfig.pack) {
125120
if (!Array.isArray(packConfig.entry)) continue;
126121
if (!packConfig.entry.some((entry) => entries.includes(entry))) continue;
127122
await build({
128123
...packConfig,
124+
entry: packConfig.entry.map((entry) =>
125+
NodeURL.fileURLToPath(new URL(`../${entry}`, import.meta.url)),
126+
),
127+
outDir: NodePath.join(directory, "dist-electron"),
129128
config: false,
130129
cwd: directory,
131130
tsconfig: false,

‎apps/desktop/src/compileCache.ts‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,23 @@
22
import * as NodeModule from "node:module";
33
import * as NodeOS from "node:os";
44
import * as NodePath from "node:path";
5+
import { enablePreparedServerCache } from "../../../scripts/lib/server-compile-cache.ts";
56

67
// Linux /tmp is shared; macOS and Windows temp dirs are per user.
78
// AppImage mounts change paths each launch, so Node's path-keyed cache would miss and accumulate copies.
89
try {
9-
if (!process.env.APPIMAGE) {
10+
if (!process.env.APPIMAGE || process.env.ELECTRON_RUN_AS_NODE === "1") {
1011
const cacheRoot =
1112
// oxlint-disable-next-line t3code/no-global-process-runtime -- Loads before any Effect runtime.
1213
process.platform === "linux"
1314
? process.env.XDG_CACHE_HOME || NodePath.join(NodeOS.homedir(), ".cache")
1415
: NodeOS.tmpdir();
15-
NodeModule.enableCompileCache(NodePath.join(cacheRoot, "t3code", "compile-cache"));
16+
const directory = NodePath.join(cacheRoot, "t3code", "compile-cache");
17+
const prepared =
18+
process.env.ELECTRON_RUN_AS_NODE === "1" &&
19+
enablePreparedServerCache(process.argv[1] ?? "", directory);
20+
if (!prepared && !process.env.APPIMAGE) {
21+
NodeModule.enableCompileCache(directory);
22+
}
1623
}
1724
} catch {}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
export { generatePreparedServerCache } from "../../../scripts/lib/server-compile-cache.ts";

‎apps/desktop/vite.config.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ export default defineConfig({
9393
dts: false,
9494
sourcemap: true,
9595
outExtensions: () => ({ js: ".cjs" }),
96-
entry: ["src/boot.ts", "src/compileCache.ts"],
96+
entry: ["src/boot.ts", "src/compileCache.ts", "src/serverCompileCache.ts"],
9797
clean: false,
9898
deps: {
9999
neverBundle: (id) => id === "./main.cjs" || id === "./compileCache.cjs",

‎apps/server/src/compileCache.ts‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,8 @@ import * as NodeModule from "node:module";
22
import * as Effect from "effect/Effect";
33

44
// Windows force-kills on quit; persist the cache after startup.
5-
export const flushCompileCache = Effect.try(() => NodeModule.flushCompileCache()).pipe(
6-
Effect.ignore,
7-
);
5+
export const flushCompileCache = Effect.try(() => {
6+
if (!Reflect.get(globalThis, Symbol.for("t3code.preparedServerCache"))) {
7+
NodeModule.flushCompileCache();
8+
}
9+
}).pipe(Effect.ignore);

‎docs/operations/development.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -261,6 +261,28 @@ DMGs default to the host architecture. Use `--arch` to choose another target and
261261
to retain packaging files for inspection. Run `vp run dist:desktop:artifact --help` for other
262262
options.
263263

264+
### Prepared server bytecode
265+
266+
Native desktop artifact builds generate server bytecode with the packaged Electron executable,
267+
after ASAR creation and before signing. Cross-platform and cross-architecture builds skip this
268+
step explicitly. CLI, SEA and WSL runtimes keep their existing behavior; only desktop backend
269+
imports covered by generation receive prepared bytecode. Worker-only modules compile normally.
270+
271+
Electron's Node 24 cache has no read-only option and includes the producer UID in its directory
272+
name. The backend links individual prepared files into its writable cache with keys for the
273+
installed module paths. Node replaces files atomically, so regeneration cannot write through those
274+
links into signed resources. Windows uses hard links and falls back to normal caching when volumes
275+
differ or resource permissions prevent linking. Protected installations therefore may not reuse
276+
prepared bytecode. No cache bytes are copied during startup. AppImage backends discard their links
277+
on normal exit because each mount changes module paths.
278+
279+
The key calculation follows Node's internal portable ESM format. Generation checks that the
280+
packaged engine produced the expected CLI entry and fails the build if that format changes.
281+
The manifest also checks Electron, Node, OS, architecture and V8's flags-sensitive version tag.
282+
Missing or rejected entries compile from the shipped JavaScript. Prepared backends skip the
283+
explicit startup flush; Node can persist missing entries on normal exit. The writable fallback
284+
keeps the explicit flush needed when Windows force-kills the backend.
285+
264286
### Linux AppImage prerequisites
265287

266288
Build on Linux because the browser-secret helper links against the host's libsecret. Install

‎knip.jsonc‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,7 @@
3232
"mobile-native-client.ts",
3333
"setup-worktree.ts",
3434
"sign-macos.ts",
35+
"prepare-server-compile-cache.cjs",
3536
"smoke-desktop-app.ts",
3637
"verify-windows-desktop-artifact.ts",
3738
],
@@ -73,6 +74,7 @@
7374
"src/snapShot/SnapShotAccessibilityWorker.ts!",
7475
"src/boot.ts!",
7576
"src/compileCache.ts!",
77+
"src/serverCompileCache.ts!",
7678
"src/main.ts!",
7779
"src/preload.ts!",
7880
"src/preview-pick-preload.ts!",

‎scripts/build-desktop-artifact.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2771,6 +2771,7 @@ export const createBuildConfig = Effect.fn("createBuildConfig")(function* (
27712771
arch?: typeof BuildArch.Type,
27722772
) {
27732773
const buildConfig: Record<string, unknown> = {
2774+
afterPack: (yield* Path.Path).join(yield* RepoRoot, "scripts/prepare-server-compile-cache.cjs"),
27742775
appId: DESKTOP_APP_ID,
27752776
productName: resolveDesktopProductName(version),
27762777
artifactName: "T3-Code-${version}-${arch}.${ext}",
Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
// @effect-diagnostics nodeBuiltinImport:off
2+
import * as NodeFS from "node:fs";
3+
import * as NodeOS from "node:os";
4+
import * as NodePath from "node:path";
5+
import { expect, it } from "vite-plus/test";
6+
import { cacheKey, seedPreparedCache } from "./server-compile-cache.ts";
7+
8+
it("seeds relocated cache entries without allowing writes into shipped resources", () => {
9+
const root = NodeFS.realpathSync(
10+
NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-prepared-test-")),
11+
);
12+
try {
13+
const prepared = NodePath.join(root, "resources", "server-compile-cache");
14+
const active = NodePath.join(root, "user", "different-uid-tag");
15+
NodeFS.mkdirSync(prepared, { recursive: true });
16+
NodeFS.mkdirSync(active, { recursive: true });
17+
NodeFS.writeFileSync(NodePath.join(prepared, "12345678"), "prepared bytes");
18+
const manifest = {
19+
format: 1,
20+
runtime: "matching",
21+
entries: [{ module: "app.asar/apps/server/dist/chunk.mjs", file: "12345678" }],
22+
};
23+
NodeFS.writeFileSync(NodePath.join(prepared, "manifest.json"), JSON.stringify(manifest));
24+
expect(seedPreparedCache(prepared, active, "wrong-engine")).toBe(false);
25+
expect(seedPreparedCache(prepared, active, "matching")).toBe(true);
26+
const key = cacheKey(active, NodePath.join(root, "resources", manifest.entries[0]!.module));
27+
expect(NodeFS.readFileSync(NodePath.join(active, key), "utf8")).toBe("prepared bytes");
28+
// Node persists by replacing the directory entry, never by overwriting the linked inode.
29+
NodeFS.rmSync(NodePath.join(active, key));
30+
NodeFS.writeFileSync(NodePath.join(active, key), "runtime replacement");
31+
expect(NodeFS.readFileSync(NodePath.join(prepared, "12345678"), "utf8")).toBe("prepared bytes");
32+
expect(seedPreparedCache(prepared, active, "matching")).toBe(true);
33+
expect(NodeFS.readFileSync(NodePath.join(active, key), "utf8")).toBe("runtime replacement");
34+
const missing = { module: "app.asar/apps/server/dist/missing.mjs", file: "87654321" };
35+
for (const entries of [
36+
[...manifest.entries, missing],
37+
[missing, ...manifest.entries],
38+
]) {
39+
NodeFS.writeFileSync(
40+
NodePath.join(prepared, "manifest.json"),
41+
JSON.stringify({ ...manifest, entries }),
42+
);
43+
expect(seedPreparedCache(prepared, active, "matching")).toBe(false);
44+
}
45+
NodeFS.writeFileSync(NodePath.join(prepared, "manifest.json"), "corrupt");
46+
expect(seedPreparedCache(prepared, active, "matching")).toBe(false);
47+
expect(seedPreparedCache(NodePath.join(root, "missing"), active, "matching")).toBe(false);
48+
} finally {
49+
NodeFS.rmSync(root, { recursive: true, force: true });
50+
}
51+
});
52+
53+
it.each(["app", "server"])(
54+
"generates %s.asar cache with the consumer engine and falls back after damage",
55+
async (archive) => {
56+
const { spawnSync } = await import("node:child_process");
57+
const helper = new URL("./server-compile-cache.ts", import.meta.url).href;
58+
const root = NodeFS.realpathSync(
59+
NodeFS.mkdtempSync(NodePath.join(NodeOS.tmpdir(), "t3-cache-engine-")),
60+
);
61+
const run = (code: string) => {
62+
const env = {
63+
...process.env,
64+
NODE_DEBUG_NATIVE: "COMPILE_CACHE",
65+
NODE_COMPILE_CACHE: undefined,
66+
NODE_DISABLE_COMPILE_CACHE: undefined,
67+
};
68+
const result = spawnSync(process.execPath, ["--input-type=module", "-e", code], {
69+
env,
70+
encoding: "utf8",
71+
});
72+
expect(result.status, result.stderr).toBe(0);
73+
return result.stderr;
74+
};
75+
try {
76+
const producer = NodePath.join(root, "producer", "resources");
77+
const consumer = NodePath.join(root, "relocated", "resources");
78+
const relative = `${archive}.asar/apps/server/dist/binCli-fixture.mjs`;
79+
NodeFS.mkdirSync(NodePath.dirname(NodePath.join(producer, relative)), { recursive: true });
80+
NodeFS.writeFileSync(NodePath.join(producer, relative), "export const answer = 42;");
81+
run(
82+
`import {generatePreparedServerCache} from ${JSON.stringify(helper)}; await generatePreparedServerCache(${JSON.stringify(producer)});`,
83+
);
84+
NodeFS.cpSync(producer, consumer, { recursive: true });
85+
const consume = (home: string, appImage = false) =>
86+
run(
87+
`if (${appImage}) process.env.APPIMAGE = "fixture"; import {enablePreparedServerCache} from ${JSON.stringify(helper)}; import {pathToFileURL} from 'node:url'; if(!enablePreparedServerCache(${JSON.stringify(NodePath.join(consumer, relative))},${JSON.stringify(NodePath.join(root, home))})) throw Error('cache disabled'); const m = await import(pathToFileURL(${JSON.stringify(NodePath.join(consumer, relative))}).href); if(m.answer!==42) throw Error('source fallback failed');`,
88+
);
89+
const prepared = NodePath.join(consumer, "server-compile-cache");
90+
NodeFS.chmodSync(prepared, 0o555);
91+
expect(consume("first-user")).toContain("was accepted");
92+
expect(consume("appimage-user", true)).toContain("was accepted");
93+
expect(NodeFS.readdirSync(NodePath.join(root, "appimage-user", "server"))).toEqual([]);
94+
NodeFS.chmodSync(prepared, 0o755);
95+
for (const file of NodeFS.readdirSync(prepared).filter((file) => file !== "manifest.json")) {
96+
NodeFS.writeFileSync(NodePath.join(prepared, file), "broken");
97+
}
98+
expect(consume("second-user")).toContain("was not initialized");
99+
for (const file of NodeFS.readdirSync(prepared).filter((file) => file !== "manifest.json")) {
100+
expect(NodeFS.readFileSync(NodePath.join(prepared, file), "utf8")).toBe("broken");
101+
}
102+
NodeFS.rmSync(prepared, { recursive: true });
103+
expect(consume("third-user")).toContain("was not initialized");
104+
} finally {
105+
NodeFS.rmSync(root, { recursive: true, force: true });
106+
}
107+
},
108+
);
Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
/* oxlint-disable t3code/no-global-process-runtime -- Runs in the packaged engine before an Effect runtime exists. */
2+
// @effect-diagnostics nodeBuiltinImport:off
3+
import * as NodeFS from "node:fs";
4+
import * as NodePath from "node:path";
5+
import * as NodeModule from "node:module";
6+
import * as NodeV8 from "node:v8";
7+
import * as NodeZlib from "node:zlib";
8+
import * as NodeURL from "node:url";
9+
10+
export const runtimeIdentity = () =>
11+
[
12+
process.versions.electron,
13+
process.version,
14+
process.platform,
15+
process.arch,
16+
NodeV8.cachedDataVersionTag(),
17+
].join("-");
18+
19+
// Node 24's portable key is CRC32 of the one-byte ESM type followed by the relative filename.
20+
// Generation verifies this against files produced by the packaged engine before shipping them.
21+
export const cacheKey = (active: string, filename: string) =>
22+
NodeZlib.crc32(NodePath.relative(active, filename), NodeZlib.crc32(Buffer.from([1])))
23+
.toString(16)
24+
.padStart(8, "0");
25+
26+
export function seedPreparedCache(prepared: string, active: string, runtime: string): boolean {
27+
try {
28+
const manifest: unknown = JSON.parse(
29+
NodeFS.readFileSync(NodePath.join(prepared, "manifest.json"), "utf8"),
30+
);
31+
if (
32+
typeof manifest !== "object" ||
33+
manifest === null ||
34+
!("format" in manifest) ||
35+
manifest.format !== 1 ||
36+
!("runtime" in manifest) ||
37+
manifest.runtime !== runtime ||
38+
!("entries" in manifest) ||
39+
!Array.isArray(manifest.entries) ||
40+
manifest.entries.length === 0
41+
)
42+
return false;
43+
for (const entry of manifest.entries) {
44+
if (
45+
typeof entry?.module !== "string" ||
46+
typeof entry?.file !== "string" ||
47+
!/^[a-f0-9]{8}$/.test(entry.file) ||
48+
!/^(app|server)\.asar\/apps\/server\/dist\/[^/\\]+\.mjs$/.test(entry.module)
49+
)
50+
return false;
51+
const source = NodePath.join(prepared, entry.file);
52+
const destination = NodePath.join(
53+
active,
54+
cacheKey(active, NodePath.join(NodePath.dirname(prepared), entry.module)),
55+
);
56+
try {
57+
// Node replaces cache files atomically. A directory link would instead allow writes into signed resources.
58+
if (process.platform === "win32") NodeFS.linkSync(source, destination);
59+
else NodeFS.symlinkSync(source, destination);
60+
} catch {}
61+
if (!NodeFS.existsSync(destination)) return false;
62+
}
63+
return true;
64+
} catch {
65+
return false;
66+
}
67+
}
68+
69+
export function enablePreparedServerCache(entry: string, cacheRoot: string): boolean {
70+
try {
71+
const archive = entry.match(/^(.*[\\/](?:app|server)\.asar)[\\/]/)?.[1];
72+
if (!archive) return false;
73+
const resources = NodeFS.realpathSync(NodePath.dirname(archive));
74+
// Keep different installations and builds separate without reading or copying their source files.
75+
const prepared = NodePath.join(resources, "server-compile-cache");
76+
if (process.env.APPIMAGE && !NodeFS.existsSync(NodePath.join(prepared, "manifest.json")))
77+
return false;
78+
const identity = NodeZlib.crc32(resources).toString(16);
79+
NodeFS.mkdirSync(NodePath.join(cacheRoot, "server"), { recursive: true });
80+
const directory = process.env.APPIMAGE
81+
? NodeFS.mkdtempSync(NodePath.join(cacheRoot, "server", "appimage-"))
82+
: NodePath.join(cacheRoot, "server", identity);
83+
if (process.env.APPIMAGE) {
84+
// Each mount has different module paths; discard its links rather than accumulating caches.
85+
process.once("exit", () => {
86+
try {
87+
NodeFS.rmSync(directory, { recursive: true, force: true });
88+
} catch {}
89+
});
90+
}
91+
const result = NodeModule.enableCompileCache({
92+
directory,
93+
portable: true,
94+
});
95+
const active = NodeModule.getCompileCacheDir();
96+
if (result.status !== NodeModule.constants.compileCacheStatus.ENABLED || !active) return false;
97+
const seeded = seedPreparedCache(prepared, active, runtimeIdentity());
98+
if (seeded) Reflect.set(globalThis, Symbol.for("t3code.preparedServerCache"), true);
99+
return true;
100+
} catch {
101+
return false;
102+
}
103+
}
104+
105+
export async function generatePreparedServerCache(resourcesInput: string): Promise<void> {
106+
const resources = NodeFS.realpathSync(resourcesInput);
107+
const prepared = NodePath.join(resources, "server-compile-cache");
108+
const archive = NodeFS.existsSync(NodePath.join(resources, "server.asar"))
109+
? "server.asar"
110+
: "app.asar";
111+
const dist = NodePath.join(resources, archive, "apps/server/dist");
112+
NodeFS.mkdirSync(prepared, { recursive: true });
113+
const result = NodeModule.enableCompileCache({ directory: prepared, portable: true });
114+
if (result.status !== NodeModule.constants.compileCacheStatus.ENABLED)
115+
throw new Error("Cannot enable release compile cache");
116+
const cli = NodeFS.readdirSync(dist).find((file) => /^binCli-.*\.mjs$/.test(file));
117+
if (!cli) throw new Error("Missing bundled server CLI");
118+
await import(NodeURL.pathToFileURL(NodePath.join(dist, cli)).href);
119+
NodeModule.flushCompileCache();
120+
const active = NodeModule.getCompileCacheDir()!;
121+
const entries = NodeFS.readdirSync(dist)
122+
.filter((file) => file.endsWith(".mjs"))
123+
.flatMap((file) => {
124+
const key = cacheKey(active, NodePath.join(dist, file));
125+
if (!NodeFS.existsSync(NodePath.join(active, key))) return [];
126+
NodeFS.copyFileSync(NodePath.join(active, key), NodePath.join(prepared, key));
127+
return [{ module: `${archive}/apps/server/dist/${file}`, file: key }];
128+
});
129+
if (!entries.some((entry) => entry.module.endsWith(`/${cli}`)))
130+
throw new Error("Packaged engine cache key format is unsupported");
131+
NodeFS.writeFileSync(
132+
NodePath.join(prepared, "manifest.json"),
133+
JSON.stringify({ format: 1, runtime: runtimeIdentity(), entries }),
134+
);
135+
NodeFS.rmSync(active, { recursive: true });
136+
}

0 commit comments

Comments
 (0)