Skip to content

Commit 0ae4f42

Browse files
t3dotggkhoi
authored andcommitted
fix(build): TEMPORARY workaround so linux-arm64 builds run on 16/64 KiB page kernels
TEMPORARY workaround for an upstream Node bug: nodejs/node#67048 Node 26.9+ --build-sea writes linux-arm64 executables that 16/64 KiB page kernels cannot load. linux-arm64 now injects with postject, and the archive build rejects incompatible ELF layouts. One-time exception. Revert once Node ships a fix: grep for the Node issue URL and drop postject from scripts/package.json. Fixes #23433. Replaces #23443. Co-authored-by: Lakshmi Tanmay <[email protected]> Co-authored-by: maria-rcks <[email protected]> Upstream: c175e5737eddeef1b7376a6761f29da926f53ea3 (t3code PR 25825)
1 parent 11c2e6b commit 0ae4f42

8 files changed

Lines changed: 242 additions & 18 deletions

File tree

‎apps/server/scripts/cli.ts‎

Lines changed: 34 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ import { ChildProcess, ChildProcessSpawner } from "effect/process";
1111

1212
import { DEVELOPMENT_ICON_OVERRIDES } from "../../../scripts/lib/brand-assets.ts";
1313
import { findEsmImportsOfExternalPackages } from "../../../scripts/lib/cli-executable-imports.ts";
14+
import { injectLinuxArm64Sea } from "../../../scripts/lib/linux-arm64-sea.ts";
15+
import * as HostProcess from "@supaterm/shared/HostProcess";
1416
import { resolveSpawnCommand } from "@supaterm/shared/shell";
1517
import {
1618
ServerCliBuildAssetMissingError,
@@ -118,6 +120,12 @@ const buildExeCmd = Command.make(
118120
const serverDir = path.join(repoRoot, "apps/server");
119121

120122
yield* Effect.log("[cli] Building single-executable...");
123+
const target = Option.getOrUndefined(config.target);
124+
// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
125+
const linuxArm64 =
126+
!target &&
127+
(yield* HostProcess.Platform) === "linux" &&
128+
(yield* HostProcess.Architecture) === "arm64";
121129
// `vp env exec --node` selects the runtime in managed and system-first
122130
// modes alike. The pack runs on it, and a native build embeds it.
123131
const spawnCommand = yield* resolveSpawnCommand("vp", [
@@ -134,11 +142,8 @@ const buildExeCmd = Command.make(
134142
cwd: serverDir,
135143
env: {
136144
...process.env,
137-
SUPATERM_PACK_EXE: "1",
138-
...Option.match(config.target, {
139-
onNone: () => ({}),
140-
onSome: (target) => ({ SUPATERM_PACK_EXE_TARGET: target }),
141-
}),
145+
SUPATERM_PACK_EXE: linuxArm64 ? "bundle" : "1",
146+
SUPATERM_PACK_EXE_TARGET: target ?? "",
142147
},
143148
stdout: config.verbose ? "inherit" : "ignore",
144149
stderr: "inherit",
@@ -152,13 +157,36 @@ const buildExeCmd = Command.make(
152157
if (specifiers.length > 0) {
153158
return yield* new ServerCliExecutableImportError({ bundlePath, specifiers });
154159
}
160+
// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
161+
if (linuxArm64) {
162+
const seaNode = yield* resolveSpawnCommand("vp", [
163+
"env",
164+
"exec",
165+
"--node",
166+
SEA_NODE_VERSION,
167+
"--",
168+
"node",
169+
"-p",
170+
"process.execPath",
171+
]);
172+
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
173+
const nodePath = yield* spawner.string(
174+
ChildProcess.make(seaNode.command, seaNode.args, { shell: seaNode.shell }),
175+
);
176+
yield* injectLinuxArm64Sea({
177+
bundlePath,
178+
outputPath: path.join(serverDir, "dist-exe/supaterm"),
179+
nodePath: nodePath.trim(),
180+
verbose: config.verbose,
181+
});
182+
}
155183
yield* Effect.log(
156184
"[cli] Built dist-exe/supaterm (expects client/, resource-monitor/, and the runtime-external node_modules beside it; scripts/build-cli-archive.ts assembles that tree)",
157185
);
158186
}),
159187
).pipe(
160188
Command.withDescription(
161-
`Build the server as a Node ${SEA_NODE_VERSION} single-executable. vp runs the pack on that Node, and native builds reject any other host version. The binary still resolves native packages from a node_modules tree beside it.`,
189+
`Build the server as a Node ${SEA_NODE_VERSION} single-executable. vp runs the pack on that Node, and native builds reject any other host version. Linux ARM64 builds only on a Linux ARM64 host. The binary still resolves native packages from a node_modules tree beside it.`,
162190
),
163191
);
164192

‎apps/server/vite.config.ts‎

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,17 @@ if (!TELEMETRY_CHANNELS.includes(telemetryChannel)) {
2121
);
2222
}
2323

24-
// `build:exe` wraps the same bundle in a Node single-executable. tsdown's exe
25-
// step refuses multi-chunk output and counts the sourcemap as a chunk, and the
26-
// executable needs a host Node that supports `--build-sea` (25.7+), so this is
27-
// a separate mode rather than a second entry in the default build.
28-
const packExecutable = process.env.SUPATERM_PACK_EXE === "1";
24+
// `build:exe` wraps the same bundle in a Node single-executable. tsdown's exe step refuses
25+
// multi-chunk output and counts the sourcemap as a chunk, so this is a separate mode. "bundle"
26+
// stops at bin.mjs for scripts/cli.ts to inject on linux-arm64, a TEMPORARY Node fix.
27+
// Remove when fixed: https://github.com/nodejs/node/issues/67048
28+
const packMode = process.env.SUPATERM_PACK_EXE;
29+
const packExecutable = packMode === "1" || packMode === "bundle";
30+
// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
31+
// No linux-arm64: --build-sea output cannot load on 16/64 KiB page kernels, so it builds natively.
2932
const SEA_TARGETS = {
3033
"darwin-arm64": { platform: "darwin", arch: "arm64" },
3134
"darwin-x64": { platform: "darwin", arch: "x64" },
32-
"linux-arm64": { platform: "linux", arch: "arm64" },
3335
"linux-x64": { platform: "linux", arch: "x64" },
3436
"win-arm64": { platform: "win", arch: "arm64" },
3537
"win-x64": { platform: "win", arch: "x64" },
@@ -77,7 +79,10 @@ export default mergeConfig(
7779
outDir: packExecutable ? "dist-exe" : "dist",
7880
sourcemap: !packExecutable,
7981
clean: true,
80-
...(packExecutable
82+
// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
83+
// SEA can only resolve built-ins; keep dynamic imports inside its one module.
84+
...(packExecutable ? { outputOptions: { codeSplitting: false } } : {}),
85+
...(packMode === "1"
8186
? {
8287
exe: {
8388
fileName: "supaterm",

‎docs/operations/release.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -61,7 +61,7 @@ bumps require a new store binary under the existing OTA fingerprint policy.
6161
- Includes Electron auto-update metadata (for example `latest*.yml`, `nightly*.yml`, and `*.blockmap`) in release assets.
6262
- Builds a self-contained CLI archive per platform (`supaterm-<version>-<platform>-<arch>.tar.gz`, `.zip` on Windows) in the same job as that target's desktop artifact and attaches them to the GitHub Release with a `SHA256SUMS` file, on every channel, for five targets: macOS arm64, Linux x64 and arm64, Windows x64 and arm64. Every archive is smoke-tested on hardware of its own architecture, and every one but the Windows archives is also built and signed there. There is no macOS x64 archive: Node single-executables are unsupported on x64 macOS (the SEA docs list macOS as arm64 only) and the binary segfaults on start; the x64 desktop app is Electron and unaffected.
6363
- The archive holds the server as a Node single-executable (`scripts/build-cli-archive.ts`), so unpacking it needs neither Node, npm, nor a compiler. It is the only form in which Supaterm manages a runtime: the desktop's SSH environments, the boot service, `supaterm update`, and the install scripts all download and verify this archive against `SHA256SUMS`. The `supaterm` npm package exists for people who run `npx supaterm` or `npm install -g supaterm` themselves, and it downloads this same archive too; nothing in the product installs from npm. The `curl | sh` installers are `scripts/install.sh` and `scripts/install.ps1`; the marketing site copies them into its `public/` at build time (`apps/marketing/scripts/stage-install-scripts.mjs`) and serves them at `supaterm.com/install.sh` and `/install.ps1`.
64-
- Every executable embeds the exact Node in `SEA_NODE_VERSION` (`apps/server/scripts/seaNodeVersion.ts`), the only place that version is set. `build-exe` runs the pack on it through `vp env exec --node`; native builds reject a different host Node, and cross-target builds download that version for their target. Development, CI, and the desktop backend stay on the mise Node, the line Electron ships. Keep the version exact: only exact versions have a `nodejs.org/dist` directory. Runtime changes need a new release version because installed runtimes are cached by that version.
64+
- Every executable embeds the exact Node in `SEA_NODE_VERSION` (`apps/server/scripts/seaNodeVersion.ts`), the only place that version is set. `build-exe` runs the pack on it through `vp env exec --node`; native builds reject a different host Node, and cross-target builds download that version for their target. TEMPORARY: Linux arm64 executables build only on a Linux arm64 host and are injected with postject, because Node's `--build-sea` output cannot load on 16 or 64 KiB page kernels. Revert when [nodejs/node#67048](https://github.com/nodejs/node/issues/67048) is fixed. Development, CI, and the desktop backend stay on the mise Node, the line Electron ships. Keep the version exact: only exact versions have a `nodejs.org/dist` directory. Runtime changes need a new release version because installed runtimes are cached by that version.
6565
- Release macOS archives are signed with the Developer ID certificate and notarized using the Apple credentials loaded through fnox. Windows executables use the same Azure Trusted Signing setup as the installer. Every native addon in the macOS archive is signed too, since the hardened runtime refuses unsigned libraries.
6666
- Each archive is extracted and executed (`scripts/smoke-cli-archive.ts`) on its build runner, or on the `verify_runner` for Windows.
6767
- After the GitHub Release is published, publishes the `supaterm` npm package with OIDC trusted publishing from the same workflow file. It is only a launcher (`scripts/npm-launcher/supaterm.mjs`, packed by `scripts/build-npm-launcher.ts`): on first run it downloads its exact version's CLI archive from the GitHub Release (or from `SUPATERM_RELEASE_BASE_URL`), verifies it against `SHA256SUMS`, and unpacks it into `<Supaterm home>/runtime/versions/<version>`, the layout the install scripts and `supaterm update` share. The executables are not on npm: its publish-time scanning can hold 80-250 MB packages back for up to an hour after the launcher is live, and every install in that window would get a launcher with no executable. The old `@supabitapp/supaterm-<platform>-<arch>` packages get no new versions. Because the launcher reads from the release, `publish_cli` runs after `release`, never before. `release` waits for `check_cli_publish`, which packs the launcher and runs `npm publish --dry-run`, so a publish that would fail stops the run before the GitHub Release is public.

‎pnpm-lock.yaml‎

Lines changed: 4 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎scripts/build-cli-archive.ts‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ import {
2929
resolveFffNativeDependencies,
3030
STAGE_INSTALL_ARGS,
3131
} from "./build-desktop-artifact.ts";
32+
import { assertLinuxArm64PageCompatibility } from "./lib/linux-arm64-sea.ts";
3233
import { selectCliRuntimeExternalDependencies } from "./lib/cli-external-packages.ts";
3334
import { codesignArgs, MacSigningConfig, notarytoolSubmitArgs } from "./lib/mac-signing.ts";
3435
import { signWithJsign } from "./lib/windows-jsign.ts";
@@ -443,8 +444,13 @@ const buildCliArchive = Effect.fn("buildCliArchive")(function* (input: {
443444

444445
yield* requireInput(
445446
builtExecutable,
446-
`Run \`node apps/server/scripts/cli.ts build-exe --target ${targetKey}\` first.`,
447+
`Run \`node apps/server/scripts/cli.ts build-exe${targetKey === hostKey ? "" : ` --target ${targetKey}`}\` first.`,
447448
);
449+
// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
450+
if (input.platform === "linux" && input.arch === "arm64") {
451+
const bytes = yield* fs.readFile(builtExecutable);
452+
yield* Effect.try(() => assertLinuxArm64PageCompatibility(bytes));
453+
}
448454
yield* requireInput(
449455
path.join(webClient, "index.html"),
450456
"Run `vp run --filter supaterm build` first.",
Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
// TEMPORARY one-time Node fix. Remove when fixed: https://github.com/nodejs/node/issues/67048
2+
import { describe, expect, it } from "@effect/vitest";
3+
import { assertLinuxArm64PageCompatibility } from "./linux-arm64-sea.ts";
4+
5+
function elf(loads: Array<{ offset: bigint; address: bigint; size: bigint }>) {
6+
const bytes = new Uint8Array(64 + loads.length * 56);
7+
const view = new DataView(bytes.buffer);
8+
bytes.set([0x7f, 0x45, 0x4c, 0x46, 2, 1]);
9+
view.setUint16(18, 183, true);
10+
view.setBigUint64(32, 64n, true);
11+
view.setUint16(54, 56, true);
12+
view.setUint16(56, loads.length, true);
13+
loads.forEach((load, index) => {
14+
const start = 64 + index * 56;
15+
view.setUint32(start, 1, true);
16+
view.setBigUint64(start + 8, load.offset, true);
17+
view.setBigUint64(start + 16, load.address, true);
18+
view.setBigUint64(start + 40, load.size, true);
19+
view.setBigUint64(start + 48, 0x1000n, true);
20+
});
21+
return bytes;
22+
}
23+
24+
describe("Linux ARM64 SEA page compatibility", () => {
25+
it("rejects the relocated SEA note from nightly 3512", () => {
26+
expect(() =>
27+
assertLinuxArm64PageCompatibility(
28+
elf([{ offset: 0x8faf000n, address: 0x1015d000n, size: 0x1003000n }]),
29+
),
30+
).toThrow(/64 KiB/);
31+
});
32+
33+
it("accepts congruent offsets even with a smaller declared alignment", () => {
34+
expect(() =>
35+
assertLinuxArm64PageCompatibility(
36+
elf([
37+
{ offset: 0n, address: 0x400000n, size: 0x10000n },
38+
{ offset: 0x20000n, address: 0x420000n, size: 0x10000n },
39+
]),
40+
),
41+
).not.toThrow();
42+
});
43+
44+
it("rejects segments that share a 64 KiB page", () => {
45+
expect(() =>
46+
assertLinuxArm64PageCompatibility(
47+
elf([
48+
{ offset: 0n, address: 0x400000n, size: 0x11000n },
49+
{ offset: 0x11000n, address: 0x411000n, size: 0x1000n },
50+
]),
51+
),
52+
).toThrow(/overlap/);
53+
});
54+
55+
it("rejects missing or malformed program headers", () => {
56+
expect(() => assertLinuxArm64PageCompatibility(elf([]))).toThrow();
57+
expect(() => assertLinuxArm64PageCompatibility(new Uint8Array(64))).toThrow();
58+
expect(() =>
59+
assertLinuxArm64PageCompatibility(
60+
elf([{ offset: 0n, address: 0x400000n, size: 1n }]).subarray(0, 70),
61+
),
62+
).toThrow();
63+
});
64+
});

‎scripts/lib/linux-arm64-sea.ts‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
// TEMPORARY one-time workaround for a Node --build-sea bug on Linux arm64.
2+
// It breaks kernels with 16 KiB or 64 KiB pages. Revert when Node ships a fix.
3+
// Node issue: https://github.com/nodejs/node/issues/67048
4+
import * as NodeModule from "node:module";
5+
import * as Effect from "effect/Effect";
6+
import * as FileSystem from "effect/FileSystem";
7+
import * as Path from "effect/Path";
8+
import * as Schema from "effect/Schema";
9+
import { ChildProcess, ChildProcessSpawner } from "effect/process";
10+
11+
class LinuxArm64SeaError extends Schema.TaggedError<LinuxArm64SeaError>()("LinuxArm64SeaError", {
12+
message: Schema.String,
13+
}) {}
14+
15+
const encodeJson = Schema.encodeEffect(Schema.fromJsonString(Schema.Unknown));
16+
17+
const run = Effect.fn("LinuxArm64Sea.run")(function* (
18+
node: string,
19+
args: Array<string>,
20+
verbose: boolean,
21+
) {
22+
const spawner = yield* ChildProcessSpawner.ChildProcessSpawner;
23+
const child = yield* spawner.spawn(
24+
ChildProcess.make(node, args, {
25+
stdout: verbose ? "inherit" : "ignore",
26+
stderr: "inherit",
27+
}),
28+
);
29+
const exitCode = yield* child.exitCode;
30+
if (exitCode !== 0) {
31+
return yield* new LinuxArm64SeaError({ message: `${args[0]} exited with code ${exitCode}.` });
32+
}
33+
});
34+
35+
// Builds the SEA blob with `nodePath` and injects it into a copy of that Node with postject.
36+
export const injectLinuxArm64Sea = Effect.fn("LinuxArm64Sea.inject")(function* (input: {
37+
bundlePath: string;
38+
outputPath: string;
39+
nodePath: string;
40+
verbose: boolean;
41+
}) {
42+
const fs = yield* FileSystem.FileSystem;
43+
const path = yield* Path.Path;
44+
const temp = yield* fs.makeTempDirectoryScoped({ prefix: "supaterm-sea-" });
45+
const blobPath = path.join(temp, "sea.blob");
46+
const configPath = path.join(temp, "sea.json");
47+
yield* fs.writeFileString(
48+
configPath,
49+
yield* encodeJson({
50+
main: input.bundlePath,
51+
output: blobPath,
52+
mainFormat: "module",
53+
disableExperimentalSEAWarning: true,
54+
// Node SEA useCodeCache breaks import(), which the server needs.
55+
useCodeCache: false,
56+
}),
57+
);
58+
yield* run(input.nodePath, ["--experimental-sea-config", configPath], input.verbose);
59+
yield* fs.copyFile(input.nodePath, input.outputPath);
60+
yield* fs.chmod(input.outputPath, 0o755);
61+
const require = NodeModule.createRequire(import.meta.url);
62+
yield* run(
63+
process.execPath,
64+
[
65+
require.resolve("postject/dist/cli.js"),
66+
input.outputPath,
67+
"NODE_SEA_BLOB",
68+
blobPath,
69+
"--sentinel-fuse",
70+
"NODE_SEA_FUSE_fce680ab2cc467b6e072b8b5df1996b2",
71+
],
72+
input.verbose,
73+
);
74+
}, Effect.scoped);
75+
76+
// Kernels map LOAD segments in whole pages. Checking at 64 KiB covers 4, 16, and 64 KiB kernels.
77+
export function assertLinuxArm64PageCompatibility(bytes: Uint8Array) {
78+
const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
79+
if (
80+
bytes.length < 64 ||
81+
view.getUint32(0, false) !== 0x7f454c46 ||
82+
bytes[4] !== 2 ||
83+
bytes[5] !== 1 ||
84+
view.getUint16(18, true) !== 183
85+
) {
86+
throw new Error("Expected a little-endian ELF64 ARM64 executable.");
87+
}
88+
const tableOffset = Number(view.getBigUint64(32, true));
89+
const entrySize = view.getUint16(54, true);
90+
const count = view.getUint16(56, true);
91+
if (
92+
!Number.isSafeInteger(tableOffset) ||
93+
entrySize < 56 ||
94+
count === 0 ||
95+
tableOffset + entrySize * count > bytes.length
96+
) {
97+
throw new Error("Invalid ELF program header table.");
98+
}
99+
const pageSize = 0x10000n;
100+
const ranges: Array<{ start: bigint; end: bigint }> = [];
101+
for (let index = 0; index < count; index++) {
102+
const header = tableOffset + index * entrySize;
103+
if (view.getUint32(header, true) !== 1) continue;
104+
const offset = view.getBigUint64(header + 8, true);
105+
const address = view.getBigUint64(header + 16, true);
106+
const size = view.getBigUint64(header + 40, true);
107+
if (offset % pageSize !== address % pageSize) {
108+
throw new Error(`ARM64 LOAD segment ${index} is incompatible with 64 KiB pages.`);
109+
}
110+
if (size === 0n) continue;
111+
const start = address / pageSize;
112+
const end = (address + size + pageSize - 1n) / pageSize;
113+
if (ranges.some((range) => start < range.end && range.start < end)) {
114+
throw new Error(`ARM64 LOAD segments overlap on a 64 KiB page (segment ${index}).`);
115+
}
116+
ranges.push({ start, end });
117+
}
118+
if (ranges.length === 0) throw new Error("ELF executable has no LOAD segments.");
119+
}

‎scripts/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@
2525
"@types/plist": "3.0.5",
2626
"@types/pngjs": "6.0.5",
2727
"esbuild": "0.28.2",
28+
"postject": "1.0.0-alpha.6",
2829
"typescript": "catalog:",
2930
"typescript-legacy": "npm:typescript@~6.0.3",
3031
"vite-plus": "catalog:"

0 commit comments

Comments
 (0)