@tiqian/precompute 0.0.0-stage → 0.1.0-alpha.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +373 -0
- package/README.md +210 -2
- package/lib/cache.d.ts +58 -0
- package/lib/cache.js +196 -0
- package/lib/canonical.d.ts +26 -0
- package/lib/canonical.js +65 -0
- package/lib/fonts.d.ts +177 -0
- package/lib/fonts.js +89 -0
- package/lib/load.d.ts +138 -0
- package/lib/load.js +38 -0
- package/lib/nixos.d.ts +26 -0
- package/lib/nixos.js +315 -0
- package/lib/persistence.d.ts +127 -0
- package/lib/persistence.js +294 -0
- package/lib/precompute-html-projection.d.ts +32 -0
- package/lib/precompute-html-projection.js +140 -0
- package/lib/precompute-html.d.ts +98 -0
- package/lib/precompute-html.js +324 -0
- package/lib/precompute.d.ts +322 -0
- package/lib/precompute.js +540 -0
- package/lib/sqlite-store.d.ts +57 -0
- package/lib/sqlite-store.js +365 -0
- package/lib/stable-stringify.d.ts +8 -0
- package/lib/stable-stringify.js +40 -0
- package/lib/transport.d.ts +74 -0
- package/lib/transport.js +165 -0
- package/lib/vite.d.ts +6 -0
- package/lib/vite.js +22 -0
- package/package.json +115 -4
package/lib/load.js
ADDED
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
// Loads the platform-specific build of the addon on the current system.
|
|
2
|
+
// The four platforms are the first-version targets of ADR 0050. The debug
|
|
3
|
+
// path serves local builds placed by `neon dist` (`bun run debug:native`);
|
|
4
|
+
// when it is absent the proxy falls back to the installed platform package.
|
|
5
|
+
import { readFileSync } from "node:fs";
|
|
6
|
+
import { createRequire } from "node:module";
|
|
7
|
+
import { currentPlatform, proxy } from "@neon-rs/load";
|
|
8
|
+
import { loadLinuxAddon } from "./nixos.js";
|
|
9
|
+
// `proxy` needs synchronous CommonJS requires for the platform packages and
|
|
10
|
+
// the local `.node` file, so this ESM module carries its own require.
|
|
11
|
+
const require = createRequire(import.meta.url);
|
|
12
|
+
// The platform packages resolve under the scope of this package's own name,
|
|
13
|
+
// so a snapshot publication under a different scope loads without a source
|
|
14
|
+
// patch (GitHub Packages requires the npm scope to equal the repository
|
|
15
|
+
// owner; the snapshot workflow swaps the manifests temporarily).
|
|
16
|
+
const manifestUrl = new URL("../package.json", import.meta.url);
|
|
17
|
+
const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
|
|
18
|
+
const ownName = typeof manifest.name === "string" ? manifest.name : "";
|
|
19
|
+
const slash = ownName.indexOf("/");
|
|
20
|
+
const ownScope = ownName.startsWith("@") && slash > 0 ? ownName.slice(0, slash) : null;
|
|
21
|
+
const platformPackage = (platform) => {
|
|
22
|
+
if (ownScope === null) {
|
|
23
|
+
throw new Error("PlatformPackageScopeMissing");
|
|
24
|
+
}
|
|
25
|
+
return `${ownScope}/precompute-${platform}`;
|
|
26
|
+
};
|
|
27
|
+
export const addon = proxy({
|
|
28
|
+
platforms: {
|
|
29
|
+
"win32-x64-msvc": () => require(platformPackage("win32-x64-msvc")),
|
|
30
|
+
"darwin-arm64": () => require(platformPackage("darwin-arm64")),
|
|
31
|
+
// The linux loaders pass through the NixOS fallback of `nixos.ts`: on a
|
|
32
|
+
// failed dlopen they repair the runpath instead of surfacing a bare
|
|
33
|
+
// "cannot open shared object file".
|
|
34
|
+
"linux-x64-gnu": () => loadLinuxAddon(require, platformPackage("linux-x64-gnu")),
|
|
35
|
+
"linux-arm64-gnu": () => loadLinuxAddon(require, platformPackage("linux-arm64-gnu")),
|
|
36
|
+
},
|
|
37
|
+
debug: () => require(`../platforms/${currentPlatform()}/index.node`),
|
|
38
|
+
});
|
package/lib/nixos.d.ts
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
/** The `os-release(5)` ID value written by NixOS activation. */
|
|
2
|
+
export declare function isNixOsReleaseText(text: string): boolean;
|
|
3
|
+
/** True when the running system is NixOS proper, not nix on another distro. */
|
|
4
|
+
export declare function isNixOs(): boolean;
|
|
5
|
+
/** The DT_NEEDED library names of an ELF64 little-endian image, or null. */
|
|
6
|
+
export declare function readElfNeeded(bytes: Buffer): string[] | null;
|
|
7
|
+
/** Basenames of every mapped shared object in a `/proc/self/maps` dump. */
|
|
8
|
+
export declare function parseLoadedSonames(mapsText: string): Set<string>;
|
|
9
|
+
/** Directories of the nix store libraries the current process mapped. */
|
|
10
|
+
export declare function parseMapsLibraryDirs(mapsText: string): string[];
|
|
11
|
+
/** The soname-to-path entries of `ldconfig -p` output. */
|
|
12
|
+
export declare function parseLdconfigEntries(text: string): Map<string, string>;
|
|
13
|
+
/** Library directories of the fixed NixOS profiles, most specific first. */
|
|
14
|
+
export declare function profileLibraryDirs(home: string): string[];
|
|
15
|
+
/**
|
|
16
|
+
* Extra library directories from the environment, for nix-shell runspaces
|
|
17
|
+
* and other store prefixes the fixed profiles do not cover.
|
|
18
|
+
*/
|
|
19
|
+
export declare function environmentLibraryDirs(): string[];
|
|
20
|
+
/**
|
|
21
|
+
* Loads a linux platform package and, on NixOS, retries a failed load with a
|
|
22
|
+
* repaired runpath. `requireFn` is the CommonJS require of `load.ts`; the
|
|
23
|
+
* addon is cached under `~/.cache/tiqian-precompute/nix-rpath` keyed by the
|
|
24
|
+
* source file digest, so the patchelf run happens once per addon build.
|
|
25
|
+
*/
|
|
26
|
+
export declare function loadLinuxAddon(requireFn: NodeJS.Require, spec: string): ReturnType<NodeJS.Require>;
|
package/lib/nixos.js
ADDED
|
@@ -0,0 +1,315 @@
|
|
|
1
|
+
// NixOS fallback for loading the linux addon. The platform binaries are
|
|
2
|
+
// built by CI against a plain glibc and carry no runpath, so every
|
|
3
|
+
// DT_NEEDED entry must resolve through the running process: either the
|
|
4
|
+
// runtime already loaded the same SONAME, or the dynamic loader finds it in
|
|
5
|
+
// its search path. Plain Linux distributions provide the C++ runtime in a
|
|
6
|
+
// default directory; NixOS has none, and the libraries live in store paths
|
|
7
|
+
// that only the profiles know about. When the plain load fails on NixOS
|
|
8
|
+
// this module names the unresolved libraries and, when patchelf is
|
|
9
|
+
// available, loads a cached copy of the addon with a repaired runpath.
|
|
10
|
+
//
|
|
11
|
+
// Two mechanisms were measured and rejected on 2026-08-22 (ADR 0050):
|
|
12
|
+
// setting LD_LIBRARY_PATH in JS before require has no effect, because glibc
|
|
13
|
+
// parses the variable once at process startup; and preloading the missing
|
|
14
|
+
// library by absolute path needs dlopen of a plain shared object, which
|
|
15
|
+
// Node refuses ("Module did not self-register") and undoes.
|
|
16
|
+
import { spawnSync } from "node:child_process";
|
|
17
|
+
import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
|
|
18
|
+
import { dirname, join } from "node:path";
|
|
19
|
+
import { homedir } from "node:os";
|
|
20
|
+
import { createHash } from "node:crypto";
|
|
21
|
+
/** The `os-release(5)` ID value written by NixOS activation. */
|
|
22
|
+
export function isNixOsReleaseText(text) {
|
|
23
|
+
return /^ID=["']?nixos["']?$/m.test(text);
|
|
24
|
+
}
|
|
25
|
+
/** True when the running system is NixOS proper, not nix on another distro. */
|
|
26
|
+
export function isNixOs() {
|
|
27
|
+
try {
|
|
28
|
+
return isNixOsReleaseText(readFileSync("/etc/os-release", "utf8"));
|
|
29
|
+
}
|
|
30
|
+
catch {
|
|
31
|
+
return false;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
// ---------------------------------------------------------------------------
|
|
35
|
+
// ELF64 reading: only the DT_NEEDED names are needed here, and reading them
|
|
36
|
+
// without spawning a tool keeps the diagnosis working on minimal profiles.
|
|
37
|
+
// The parser accepts exactly what our addons are: 64-bit little-endian
|
|
38
|
+
// ELF shared objects. Anything else returns null and the caller rethrows.
|
|
39
|
+
const PT_LOAD = 1;
|
|
40
|
+
const PT_DYNAMIC = 2;
|
|
41
|
+
const DT_NULL = 0;
|
|
42
|
+
const DT_NEEDED = 1;
|
|
43
|
+
const DT_STRTAB = 5;
|
|
44
|
+
const DT_STRSZ = 10;
|
|
45
|
+
/** The DT_NEEDED library names of an ELF64 little-endian image, or null. */
|
|
46
|
+
export function readElfNeeded(bytes) {
|
|
47
|
+
if (bytes.length < 64 || bytes[0] !== 0x7f || bytes[1] !== 0x45 || bytes[2] !== 0x4c || bytes[3] !== 0x46) {
|
|
48
|
+
return null;
|
|
49
|
+
}
|
|
50
|
+
if (bytes[4] !== 2 || bytes[5] !== 1) {
|
|
51
|
+
return null;
|
|
52
|
+
}
|
|
53
|
+
const phoff = Number(bytes.readBigUInt64LE(0x20));
|
|
54
|
+
const phentsize = bytes.readUInt16LE(0x36);
|
|
55
|
+
const phnum = bytes.readUInt16LE(0x38);
|
|
56
|
+
let dynamicOffset = -1;
|
|
57
|
+
const loads = [];
|
|
58
|
+
for (let index = 0; index < phnum; index += 1) {
|
|
59
|
+
const header = phoff + index * phentsize;
|
|
60
|
+
if (header + 56 > bytes.length) {
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
const type = bytes.readUInt32LE(header);
|
|
64
|
+
if (type === PT_DYNAMIC) {
|
|
65
|
+
dynamicOffset = Number(bytes.readBigUInt64LE(header + 8));
|
|
66
|
+
}
|
|
67
|
+
else if (type === PT_LOAD) {
|
|
68
|
+
loads.push({
|
|
69
|
+
offset: Number(bytes.readBigUInt64LE(header + 8)),
|
|
70
|
+
vaddr: Number(bytes.readBigUInt64LE(header + 16)),
|
|
71
|
+
filesz: Number(bytes.readBigUInt64LE(header + 32)),
|
|
72
|
+
});
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
if (dynamicOffset < 0 || loads.length === 0) {
|
|
76
|
+
return null;
|
|
77
|
+
}
|
|
78
|
+
const vaddrToOffset = (vaddr) => {
|
|
79
|
+
for (const load of loads) {
|
|
80
|
+
if (vaddr >= load.vaddr && vaddr < load.vaddr + load.filesz) {
|
|
81
|
+
return vaddr - load.vaddr + load.offset;
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
return null;
|
|
85
|
+
};
|
|
86
|
+
let strtabOffset = -1;
|
|
87
|
+
let strsz = 0;
|
|
88
|
+
const neededOffsets = [];
|
|
89
|
+
for (let cursor = dynamicOffset; cursor + 16 <= bytes.length; cursor += 16) {
|
|
90
|
+
const tag = bytes.readBigInt64LE(cursor);
|
|
91
|
+
const value = Number(bytes.readBigUInt64LE(cursor + 8));
|
|
92
|
+
if (tag === BigInt(DT_NULL)) {
|
|
93
|
+
break;
|
|
94
|
+
}
|
|
95
|
+
if (tag === BigInt(DT_STRTAB)) {
|
|
96
|
+
const offset = vaddrToOffset(value);
|
|
97
|
+
if (offset === null) {
|
|
98
|
+
return null;
|
|
99
|
+
}
|
|
100
|
+
strtabOffset = offset;
|
|
101
|
+
}
|
|
102
|
+
else if (tag === BigInt(DT_STRSZ)) {
|
|
103
|
+
strsz = value;
|
|
104
|
+
}
|
|
105
|
+
else if (tag === BigInt(DT_NEEDED)) {
|
|
106
|
+
neededOffsets.push(value);
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
if (strtabOffset < 0 || strtabOffset + strsz > bytes.length) {
|
|
110
|
+
return null;
|
|
111
|
+
}
|
|
112
|
+
const names = [];
|
|
113
|
+
for (const offset of neededOffsets) {
|
|
114
|
+
const start = strtabOffset + offset;
|
|
115
|
+
if (start < strtabOffset || start >= strtabOffset + strsz) {
|
|
116
|
+
return null;
|
|
117
|
+
}
|
|
118
|
+
const end = bytes.indexOf(0, start);
|
|
119
|
+
if (end < 0 || end >= strtabOffset + strsz) {
|
|
120
|
+
return null;
|
|
121
|
+
}
|
|
122
|
+
names.push(bytes.toString("utf8", start, end));
|
|
123
|
+
}
|
|
124
|
+
return names;
|
|
125
|
+
}
|
|
126
|
+
// ---------------------------------------------------------------------------
|
|
127
|
+
// Library search. The dynamic loader consults, in order: the loaded images,
|
|
128
|
+
// the addon runpath, LD_LIBRARY_PATH (fixed at process startup), the
|
|
129
|
+
// ldconfig cache, and the default directories. NixOS has no default
|
|
130
|
+
// directories, so the last two sources cover only the system profile. The
|
|
131
|
+
// extra sources below are the ones glibc never looks at: the store
|
|
132
|
+
// directories of libraries the running process already mapped, and the
|
|
133
|
+
// user profile library directories.
|
|
134
|
+
// The pathname is the sixth column and may carry a trailing " (deleted)"
|
|
135
|
+
// marker with a space inside it, so the field cannot be split by whitespace.
|
|
136
|
+
const mapsPath = (line) => {
|
|
137
|
+
const match = line.match(/^\s*(?:\S+\s+){5}(\/\S.*)$/u);
|
|
138
|
+
if (match === null) {
|
|
139
|
+
return null;
|
|
140
|
+
}
|
|
141
|
+
return match[1].replace(/\s+\(deleted\)$/u, "");
|
|
142
|
+
};
|
|
143
|
+
/** Basenames of every mapped shared object in a `/proc/self/maps` dump. */
|
|
144
|
+
export function parseLoadedSonames(mapsText) {
|
|
145
|
+
const names = new Set();
|
|
146
|
+
for (const line of mapsText.split("\n")) {
|
|
147
|
+
const pathField = mapsPath(line);
|
|
148
|
+
if (pathField === null || !pathField.includes(".so")) {
|
|
149
|
+
continue;
|
|
150
|
+
}
|
|
151
|
+
names.add(pathField.slice(pathField.lastIndexOf("/") + 1));
|
|
152
|
+
}
|
|
153
|
+
return names;
|
|
154
|
+
}
|
|
155
|
+
/** Directories of the nix store libraries the current process mapped. */
|
|
156
|
+
export function parseMapsLibraryDirs(mapsText) {
|
|
157
|
+
const dirs = new Set();
|
|
158
|
+
for (const line of mapsText.split("\n")) {
|
|
159
|
+
const pathField = mapsPath(line);
|
|
160
|
+
if (pathField !== null && pathField.startsWith("/nix/store/") && pathField.includes(".so")) {
|
|
161
|
+
dirs.add(dirname(pathField));
|
|
162
|
+
}
|
|
163
|
+
}
|
|
164
|
+
return [...dirs];
|
|
165
|
+
}
|
|
166
|
+
/** The soname-to-path entries of `ldconfig -p` output. */
|
|
167
|
+
export function parseLdconfigEntries(text) {
|
|
168
|
+
const entries = new Map();
|
|
169
|
+
for (const line of text.split("\n")) {
|
|
170
|
+
const match = line.match(/^\s*(\S*\.so\S*)\s+\([^)]*\)\s+=>\s+(\S+)/u);
|
|
171
|
+
if (match) {
|
|
172
|
+
entries.set(match[1], match[2]);
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
return entries;
|
|
176
|
+
}
|
|
177
|
+
/** Library directories of the fixed NixOS profiles, most specific first. */
|
|
178
|
+
export function profileLibraryDirs(home) {
|
|
179
|
+
// Forward slashes on purpose: the directories exist on NixOS only, and the
|
|
180
|
+
// literal spelling keeps the output identical on every platform the test
|
|
181
|
+
// suite runs on.
|
|
182
|
+
return [
|
|
183
|
+
"/run/current-system/sw/lib",
|
|
184
|
+
"/nix/var/nix/profiles/default/lib",
|
|
185
|
+
`${home}/.local/state/nix/profiles/profile/lib`,
|
|
186
|
+
`${home}/.nix-profile/lib`,
|
|
187
|
+
];
|
|
188
|
+
}
|
|
189
|
+
/**
|
|
190
|
+
* Extra library directories from the environment, for nix-shell runspaces
|
|
191
|
+
* and other store prefixes the fixed profiles do not cover.
|
|
192
|
+
*/
|
|
193
|
+
export function environmentLibraryDirs() {
|
|
194
|
+
const value = process.env.TIQIAN_PRECOMPUTE_NIX_LIB_DIRS ?? "";
|
|
195
|
+
return value.split(":").filter((dir) => dir !== "");
|
|
196
|
+
}
|
|
197
|
+
const planRepair = (addonPath, home) => {
|
|
198
|
+
const needed = readElfNeeded(readFileSync(addonPath));
|
|
199
|
+
if (needed === null) {
|
|
200
|
+
return null;
|
|
201
|
+
}
|
|
202
|
+
const readMapsText = () => {
|
|
203
|
+
try {
|
|
204
|
+
return readFileSync("/proc/self/maps", "utf8");
|
|
205
|
+
}
|
|
206
|
+
catch {
|
|
207
|
+
return "";
|
|
208
|
+
}
|
|
209
|
+
};
|
|
210
|
+
const mapsText = readMapsText();
|
|
211
|
+
const loaded = parseLoadedSonames(mapsText);
|
|
212
|
+
const ldconfig = spawnSync("ldconfig", ["-p"], { encoding: "utf8" });
|
|
213
|
+
const cacheEntries = ldconfig.status === 0 ? parseLdconfigEntries(ldconfig.stdout) : new Map();
|
|
214
|
+
// ldconfig entries contribute candidate directories. A nix-built runtime
|
|
215
|
+
// links the store glibc, whose loader reads the cache at
|
|
216
|
+
// <glibc-store-path>/etc/ld.so.cache; on NixOS that file does not exist, so
|
|
217
|
+
// the host cache reported by `ldconfig -p` takes no part in resolution
|
|
218
|
+
// (ADR 0050). This function runs only after a real load failure, so only a
|
|
219
|
+
// SONAME the process already loaded counts as resolved.
|
|
220
|
+
const ldconfigDirs = [...new Set([...cacheEntries.values()].map(dirname))];
|
|
221
|
+
const candidateDirs = [
|
|
222
|
+
...environmentLibraryDirs(),
|
|
223
|
+
...parseMapsLibraryDirs(mapsText),
|
|
224
|
+
...profileLibraryDirs(home),
|
|
225
|
+
...ldconfigDirs,
|
|
226
|
+
];
|
|
227
|
+
const unresolved = [];
|
|
228
|
+
const runpathDirs = new Set();
|
|
229
|
+
for (const library of needed) {
|
|
230
|
+
if (loaded.has(library)) {
|
|
231
|
+
continue;
|
|
232
|
+
}
|
|
233
|
+
const directory = candidateDirs.find((dir) => existsSync(join(dir, library)));
|
|
234
|
+
if (directory === undefined) {
|
|
235
|
+
unresolved.push(library);
|
|
236
|
+
continue;
|
|
237
|
+
}
|
|
238
|
+
runpathDirs.add(directory);
|
|
239
|
+
}
|
|
240
|
+
if (unresolved.length === 0 && runpathDirs.size === 0) {
|
|
241
|
+
// Every dependency already resolves; the failure has another cause and
|
|
242
|
+
// the original error says more about it than a runpath repair would.
|
|
243
|
+
return null;
|
|
244
|
+
}
|
|
245
|
+
return { unresolved, runpathDirs: [...runpathDirs] };
|
|
246
|
+
};
|
|
247
|
+
const runPatchelf = (arguments_) => {
|
|
248
|
+
for (const candidate of ["patchelf", "/run/current-system/sw/bin/patchelf"]) {
|
|
249
|
+
const result = spawnSync(candidate, arguments_, { encoding: "utf8" });
|
|
250
|
+
if (result.error === undefined) {
|
|
251
|
+
return { status: result.status, error: undefined };
|
|
252
|
+
}
|
|
253
|
+
}
|
|
254
|
+
return { status: null, error: new Error("patchelf not found") };
|
|
255
|
+
};
|
|
256
|
+
const cacheDirectory = (home) => join(home, ".cache", "tiqian-precompute", "nix-rpath");
|
|
257
|
+
/**
|
|
258
|
+
* Loads a linux platform package and, on NixOS, retries a failed load with a
|
|
259
|
+
* repaired runpath. `requireFn` is the CommonJS require of `load.ts`; the
|
|
260
|
+
* addon is cached under `~/.cache/tiqian-precompute/nix-rpath` keyed by the
|
|
261
|
+
* source file digest, so the patchelf run happens once per addon build.
|
|
262
|
+
*/
|
|
263
|
+
export function loadLinuxAddon(requireFn, spec) {
|
|
264
|
+
try {
|
|
265
|
+
return requireFn(spec);
|
|
266
|
+
}
|
|
267
|
+
catch (failure) {
|
|
268
|
+
if (!isNixOs()) {
|
|
269
|
+
throw failure;
|
|
270
|
+
}
|
|
271
|
+
let addonPath;
|
|
272
|
+
try {
|
|
273
|
+
addonPath = requireFn.resolve(spec);
|
|
274
|
+
}
|
|
275
|
+
catch {
|
|
276
|
+
throw failure;
|
|
277
|
+
}
|
|
278
|
+
const home = homedir();
|
|
279
|
+
const source = readFileSync(addonPath);
|
|
280
|
+
const digest = createHash("sha256").update(source).digest("hex");
|
|
281
|
+
const repaired = join(cacheDirectory(home), `${digest}.node`);
|
|
282
|
+
// A previous run already repaired this exact addon build; the diagnosis
|
|
283
|
+
// below stays skipped so a repeat load works even when the environment
|
|
284
|
+
// that produced the repair is gone.
|
|
285
|
+
if (!existsSync(repaired)) {
|
|
286
|
+
const plan = planRepair(addonPath, home);
|
|
287
|
+
if (plan === null) {
|
|
288
|
+
throw failure;
|
|
289
|
+
}
|
|
290
|
+
if (plan.unresolved.length > 0) {
|
|
291
|
+
throw new Error(`TiqianPrecomputeNixLibraryMissing: the addon ${addonPath} needs ` +
|
|
292
|
+
`${plan.unresolved.join(", ")}; no directory among the loaded images, ` +
|
|
293
|
+
`the ldconfig cache, and the profile library directories provides it. ` +
|
|
294
|
+
`Install the package that ships the library, or start the process with ` +
|
|
295
|
+
`LD_LIBRARY_PATH pointing at its directory.`, { cause: failure });
|
|
296
|
+
}
|
|
297
|
+
const staging = `${repaired}.tmp-${process.pid}`;
|
|
298
|
+
const runpath = plan.runpathDirs.join(":");
|
|
299
|
+
mkdirSync(dirname(repaired), { recursive: true });
|
|
300
|
+
writeFileSync(staging, source);
|
|
301
|
+
const applied = runPatchelf(["--set-rpath", runpath, staging]);
|
|
302
|
+
if (applied.error !== undefined) {
|
|
303
|
+
throw new Error(`TiqianPrecomputeNixPatchelfMissing: the addon needs the runpath ` +
|
|
304
|
+
`${runpath}, and patchelf was not found. Install it ` +
|
|
305
|
+
`(nix profile install nixpkgs#patchelf) and retry.`, { cause: failure });
|
|
306
|
+
}
|
|
307
|
+
if (applied.status !== 0) {
|
|
308
|
+
throw new Error(`TiqianPrecomputeNixPatchelfFailed: patchelf --set-rpath ${runpath} ` +
|
|
309
|
+
`failed with status ${String(applied.status)}.`, { cause: failure });
|
|
310
|
+
}
|
|
311
|
+
renameSync(staging, repaired);
|
|
312
|
+
}
|
|
313
|
+
return requireFn(repaired);
|
|
314
|
+
}
|
|
315
|
+
}
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
import type { FontContractInput, PreparedEntry, SnapshotParagraphInput } from "./precompute.js";
|
|
2
|
+
import type { CacheBridge } from "./cache.js";
|
|
3
|
+
/**
|
|
4
|
+
* One host-owned address-to-bytes store. Addresses and record bytes are
|
|
5
|
+
* opaque: the SDK derives an address from the precomputer context and the
|
|
6
|
+
* content hash, and the value is the bridge's serialized record form. Reads
|
|
7
|
+
* return only the addresses the store actually holds.
|
|
8
|
+
*/
|
|
9
|
+
export interface PersistentCacheStore {
|
|
10
|
+
read(addresses: readonly string[]): Map<string, Uint8Array> | Promise<Map<string, Uint8Array>>;
|
|
11
|
+
write(entries: readonly (readonly [string, Uint8Array])[]): void | Promise<void>;
|
|
12
|
+
/**
|
|
13
|
+
* Records article-index rows, replacing the rows of the same article
|
|
14
|
+
* keys (ADR 0052 Article layer). One call must carry an article's full
|
|
15
|
+
* hash set for the context: the replacement drops whatever the article
|
|
16
|
+
* recorded before.
|
|
17
|
+
*/
|
|
18
|
+
recordArticles?(context: string, articles: readonly ArticleIndexRecord[]): void | Promise<void>;
|
|
19
|
+
/** Reads every article row of one context. */
|
|
20
|
+
readArticles?(context: string): ArticleIndexRecord[] | Promise<ArticleIndexRecord[]>;
|
|
21
|
+
/** Deletes article rows by key; returns the row count removed. */
|
|
22
|
+
deleteArticles?(context: string, articleKeys: readonly string[]): number | Promise<number>;
|
|
23
|
+
/**
|
|
24
|
+
* Drops entries of one context that are not in the keep list. Article
|
|
25
|
+
* rows are index data, not entries, so a prune leaves them alone.
|
|
26
|
+
*/
|
|
27
|
+
prune?(context: string, keep: readonly string[]): number | Promise<number>;
|
|
28
|
+
/**
|
|
29
|
+
* Bucket-scoped eviction (ADR 0052 BucketIntersectionEviction): the host
|
|
30
|
+
* hands one bucket id plus that bucket's current content hashes, and the
|
|
31
|
+
* store deletes the entries the bucket's article rows attribute but the
|
|
32
|
+
* list omits, protecting entries other buckets' rows still reference.
|
|
33
|
+
* The bucket's hash rows are trimmed to the list and emptied article rows
|
|
34
|
+
* are dropped. Returns the entry count removed. Sweeping every bucket
|
|
35
|
+
* converges on the whole-context union keep set, one bounded list per call.
|
|
36
|
+
*/
|
|
37
|
+
pruneBucket?(context: string, bucket: string, keep: readonly string[]): number | Promise<number>;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* One article-index row (ADR 0052 Article layer): the unit of invalidation
|
|
41
|
+
* and whole-article load. `bucket` is a host-chosen group tag; content
|
|
42
|
+
* hashes are the hex form the cache addresses derive from.
|
|
43
|
+
*/
|
|
44
|
+
export interface ArticleIndexRecord {
|
|
45
|
+
readonly articleKey: string;
|
|
46
|
+
readonly bucket: string;
|
|
47
|
+
readonly contentHashes: readonly string[];
|
|
48
|
+
}
|
|
49
|
+
/** The persistence front of one precomputer. */
|
|
50
|
+
export interface PersistentCache {
|
|
51
|
+
/** The context fingerprint as hex; namespaces this cache's addresses. */
|
|
52
|
+
context(): string;
|
|
53
|
+
/** Pushes stored records into the memory tier without rendering. */
|
|
54
|
+
warmSnapshots(inputs: readonly SnapshotParagraphInput[]): Promise<number>;
|
|
55
|
+
/** The contract form of {@link PersistentCache.warmSnapshots}. */
|
|
56
|
+
warmContracts(inputs: readonly FontContractInput[]): Promise<number>;
|
|
57
|
+
/**
|
|
58
|
+
* Hash-first render: stored entries hydrate the memory tier and resolve
|
|
59
|
+
* from the local copies after digest verification, so their content never
|
|
60
|
+
* crosses the bridge; the rest carry content once and compute. Entries
|
|
61
|
+
* match the JSON lanes byte for byte.
|
|
62
|
+
*/
|
|
63
|
+
renderSnapshots(inputs: readonly SnapshotParagraphInput[]): Promise<PreparedEntry[]>;
|
|
64
|
+
/** The contract form of {@link PersistentCache.renderSnapshots}. */
|
|
65
|
+
renderContracts(inputs: readonly FontContractInput[]): Promise<PreparedEntry[]>;
|
|
66
|
+
/**
|
|
67
|
+
* The background egress of {@link PersistentCache.renderSnapshots}: queues
|
|
68
|
+
* every item at the back of the render pool and returns once queued, so a
|
|
69
|
+
* host can warm content ahead of the waiting lanes. Failures surface when
|
|
70
|
+
* the same content arrives through a waiting lane.
|
|
71
|
+
*/
|
|
72
|
+
prefillSnapshots(inputs: readonly SnapshotParagraphInput[]): number;
|
|
73
|
+
/** The contract form of {@link PersistentCache.prefillSnapshots}. */
|
|
74
|
+
prefillContracts(inputs: readonly FontContractInput[]): number;
|
|
75
|
+
/**
|
|
76
|
+
* Records one article's full content-hash set for this cache's context
|
|
77
|
+
* (ADR 0052 Article layer). Both input lists together must carry
|
|
78
|
+
* everything this lane rendered for the article: the row replaces the
|
|
79
|
+
* article's previously recorded hashes. Returns the hash list it recorded,
|
|
80
|
+
* so a host assembles bucket prune keep lists without re-deriving them.
|
|
81
|
+
*/
|
|
82
|
+
recordArticle(articleKey: string, bucket: string, inputs: {
|
|
83
|
+
snapshots?: readonly SnapshotParagraphInput[];
|
|
84
|
+
contracts?: readonly FontContractInput[];
|
|
85
|
+
}): Promise<readonly string[]>;
|
|
86
|
+
/** The stored hash set of one article, or null when the article is unrecorded. */
|
|
87
|
+
articleHashes(articleKey: string): Promise<readonly string[] | null>;
|
|
88
|
+
/**
|
|
89
|
+
* Whole-article load: reads the article's stored records through the
|
|
90
|
+
* index and pushes them into the memory tier. Each copy verifies
|
|
91
|
+
* against its address hash and digest before warming, so a corrupt row
|
|
92
|
+
* is a skip, not poison. Returns the record count warmed.
|
|
93
|
+
*/
|
|
94
|
+
warmArticle(articleKey: string): Promise<number>;
|
|
95
|
+
/**
|
|
96
|
+
* Bucket-intersection eviction: keeps the union of every recorded
|
|
97
|
+
* article's hashes and drops this context's other entries. Articles in
|
|
98
|
+
* `dropArticles` lose their index rows before the union, so entries only
|
|
99
|
+
* those articles referenced go with them. Returns the entry count
|
|
100
|
+
* removed.
|
|
101
|
+
*/
|
|
102
|
+
pruneUnreferencedEntries(dropArticles?: readonly string[]): Promise<number>;
|
|
103
|
+
/**
|
|
104
|
+
* Bucket-scoped eviction (ADR 0052 BucketIntersectionEviction): `keep`
|
|
105
|
+
* carries every content hash the bucket should retain (hex, the form
|
|
106
|
+
* {@link PersistentCache.recordArticle} returns). The store deletes the
|
|
107
|
+
* entries the bucket's article rows attribute but the list omits and no
|
|
108
|
+
* other bucket's row references, trims the bucket's hash rows to the
|
|
109
|
+
* list and drops emptied article rows. One call carries one bucket's
|
|
110
|
+
* list; sweeping every bucket replaces the whole-context union prune for
|
|
111
|
+
* hosts that group articles into buckets. Returns the entry count
|
|
112
|
+
* removed.
|
|
113
|
+
*/
|
|
114
|
+
pruneBucket(bucket: string, keep: readonly string[]): Promise<number>;
|
|
115
|
+
/** Persists the buffered writes; returns the record count written. */
|
|
116
|
+
flush(): Promise<number>;
|
|
117
|
+
}
|
|
118
|
+
/**
|
|
119
|
+
* The lane host of {@link createPersistentCache}: any precomputer-like
|
|
120
|
+
* object with a cache bridge. The SDK binds to the bridge alone, so hosts
|
|
121
|
+
* can drive the Article index over a store without an engine attached.
|
|
122
|
+
*/
|
|
123
|
+
export type CacheLaneHost = {
|
|
124
|
+
readonly cache: CacheBridge;
|
|
125
|
+
};
|
|
126
|
+
/** Binds one lane host to one host store. */
|
|
127
|
+
export declare function createPersistentCache(host: CacheLaneHost, store: PersistentCacheStore): PersistentCache;
|