@capybara-hq/device 0.1.0-rc.16 → 0.1.0-rc.18
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/README.md +79 -0
- package/dist/activity.d.ts +31 -0
- package/dist/activity.js +62 -0
- package/dist/args.d.ts +18 -2
- package/dist/args.js +56 -8
- package/dist/cli.js +13 -2
- package/dist/commands/ceiling.js +22 -0
- package/dist/commands/keep-awake.d.ts +19 -0
- package/dist/commands/keep-awake.js +77 -0
- package/dist/commands/login.js +29 -16
- package/dist/commands/service.d.ts +3 -1
- package/dist/commands/service.js +35 -2
- package/dist/commands/start.d.ts +7 -0
- package/dist/commands/start.js +120 -1
- package/dist/commands/status.d.ts +8 -1
- package/dist/commands/status.js +50 -2
- package/dist/control/client.d.ts +12 -0
- package/dist/control/client.js +63 -0
- package/dist/control/protocol.d.ts +58 -0
- package/dist/control/protocol.js +16 -0
- package/dist/control/server.d.ts +28 -0
- package/dist/control/server.js +254 -0
- package/dist/exec/mac-operation-backend.d.ts +5 -0
- package/dist/exec/mac-operation-backend.js +26 -6
- package/dist/exec/native-helper-client.js +10 -2
- package/dist/exec/operation-supervisor.d.ts +30 -1
- package/dist/exec/operation-supervisor.js +60 -2
- package/dist/exec/operation-worker.js +3 -0
- package/dist/exec/transfer-timing.d.ts +16 -0
- package/dist/exec/transfer-timing.js +26 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +1 -0
- package/dist/keep-awake.d.ts +39 -0
- package/dist/keep-awake.js +104 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/device-protocol.js +22 -4
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/hooks.d.ts +4 -3
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.d.ts +3 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/index.js +3 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/model.d.ts +1 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/permissions.js +3 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.d.ts +80 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-capabilities.js +13 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.d.ts +57 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/shell-environment.js +16 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.d.ts +12 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui-slots.js +23 -0
- package/dist/node_modules/@capybara-hq/plugin-sdk/dist/ui.d.ts +6 -1
- package/dist/node_modules/@capybara-hq/plugin-sdk/package.json +1 -1
- package/dist/runtime-manifest.json +1 -1
- package/dist/server-ops.d.ts +3 -0
- package/dist/server-ops.js +33 -0
- package/dist/service/launchd.d.ts +2 -0
- package/dist/service/launchd.js +10 -4
- package/dist/service/manager.d.ts +2 -0
- package/dist/service/manager.js +16 -2
- package/dist/service/systemd.d.ts +2 -0
- package/dist/service/systemd.js +8 -2
- package/dist/staged-connect.d.ts +9 -0
- package/dist/staged-connect.js +24 -2
- package/dist/staged-device.js +6 -0
- package/dist/state.d.ts +9 -0
- package/dist/state.js +9 -1
- package/dist/wake.d.ts +23 -0
- package/dist/wake.js +29 -0
- package/package.json +2 -2
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
import { chmodSync, lstatSync, statSync, unlinkSync } from "node:fs";
|
|
2
|
+
import { createConnection, createServer } from "node:net";
|
|
3
|
+
import { CONTROL_LINE_MAX_BYTES, CONTROL_OPS, CONTROL_PATH_MAX_BYTES, CONTROL_WRITE_MAX_BYTES, controlSocketPath, } from "./protocol.js";
|
|
4
|
+
/** How long the check for a live socket at the path waits for a connection. */
|
|
5
|
+
const PROBE_TIMEOUT_MS = 1000;
|
|
6
|
+
/** Owner-only peers: a handful of connections is plenty (the desktop app, a `status`). */
|
|
7
|
+
const MAX_CONNECTIONS = 32;
|
|
8
|
+
const mode = (st) => `0${(st.mode & 0o777).toString(8)}`;
|
|
9
|
+
/**
|
|
10
|
+
* Why no control socket can be made for this state directory, from what is visible without
|
|
11
|
+
* binding: a path over {@link CONTROL_PATH_MAX_BYTES}, or a state directory that is missing, not
|
|
12
|
+
* the user's or open to other users (the same owner and mode rule the credential file follows).
|
|
13
|
+
* Undefined when nothing is in the way. `status` uses it to explain a runner that does not answer.
|
|
14
|
+
*/
|
|
15
|
+
export function controlUnavailableReason(stateDir) {
|
|
16
|
+
const path = controlSocketPath(stateDir);
|
|
17
|
+
const bytes = Buffer.byteLength(path);
|
|
18
|
+
if (bytes > CONTROL_PATH_MAX_BYTES) {
|
|
19
|
+
return (`the control socket path ${path} is ${bytes} bytes, longer than the ` +
|
|
20
|
+
`${CONTROL_PATH_MAX_BYTES} bytes a unix socket path may have; use a shorter XDG_CONFIG_HOME`);
|
|
21
|
+
}
|
|
22
|
+
let st;
|
|
23
|
+
try {
|
|
24
|
+
st = statSync(stateDir);
|
|
25
|
+
}
|
|
26
|
+
catch (e) {
|
|
27
|
+
return `the state directory ${stateDir} cannot be read (${e.message})`;
|
|
28
|
+
}
|
|
29
|
+
if (!st.isDirectory())
|
|
30
|
+
return `the state directory ${stateDir} is not a directory`;
|
|
31
|
+
const uid = process.getuid?.();
|
|
32
|
+
if (uid !== undefined && st.uid !== uid) {
|
|
33
|
+
return `the state directory ${stateDir} belongs to another user (uid ${st.uid})`;
|
|
34
|
+
}
|
|
35
|
+
if ((st.mode & 0o077) !== 0) {
|
|
36
|
+
return (`the state directory ${stateDir} has mode ${mode(st)}, open to other users; ` +
|
|
37
|
+
`run chmod 700 ${stateDir}`);
|
|
38
|
+
}
|
|
39
|
+
return undefined;
|
|
40
|
+
}
|
|
41
|
+
/** Whether something answers on the socket at `path`: "live", "stale" (nothing listens) or why not. */
|
|
42
|
+
function probe(path) {
|
|
43
|
+
return new Promise((resolve) => {
|
|
44
|
+
const sock = createConnection(path);
|
|
45
|
+
const done = (r) => {
|
|
46
|
+
clearTimeout(timer);
|
|
47
|
+
sock.destroy();
|
|
48
|
+
resolve(r);
|
|
49
|
+
};
|
|
50
|
+
const timer = setTimeout(() => done({ error: "it did not answer in time" }), PROBE_TIMEOUT_MS);
|
|
51
|
+
sock.once("connect", () => done("live"));
|
|
52
|
+
sock.once("error", (e) => done(e.code === "ECONNREFUSED" || e.code === "ENOENT" ? "stale" : { error: e.message }));
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Clears the way for a socket at `path`: nothing there, or a stale socket of this user (nothing
|
|
57
|
+
* listens) that is removed. A live socket, a file that is not a socket or one of another user is
|
|
58
|
+
* never touched. Answers why not, or undefined when the path is free.
|
|
59
|
+
*/
|
|
60
|
+
async function clearPath(path) {
|
|
61
|
+
let st;
|
|
62
|
+
try {
|
|
63
|
+
st = lstatSync(path);
|
|
64
|
+
}
|
|
65
|
+
catch {
|
|
66
|
+
return undefined;
|
|
67
|
+
}
|
|
68
|
+
if (!st.isSocket())
|
|
69
|
+
return `${path} exists and is not a socket; it was left alone`;
|
|
70
|
+
const uid = process.getuid?.();
|
|
71
|
+
if (uid !== undefined && st.uid !== uid)
|
|
72
|
+
return `${path} belongs to another user`;
|
|
73
|
+
const found = await probe(path);
|
|
74
|
+
if (found === "live")
|
|
75
|
+
return `another capybara-device already answers on ${path}`;
|
|
76
|
+
if (found !== "stale")
|
|
77
|
+
return `${path} cannot be checked (${found.error})`;
|
|
78
|
+
try {
|
|
79
|
+
// only the socket judged stale: a file replaced meanwhile is left alone
|
|
80
|
+
const now = lstatSync(path);
|
|
81
|
+
if (now.ino === st.ino && now.dev === st.dev)
|
|
82
|
+
unlinkSync(path);
|
|
83
|
+
}
|
|
84
|
+
catch {
|
|
85
|
+
// gone already
|
|
86
|
+
}
|
|
87
|
+
return undefined;
|
|
88
|
+
}
|
|
89
|
+
/** Binds `path` with the umask closed to group and others, so the socket is never wider than 0600. */
|
|
90
|
+
function listen(server, path) {
|
|
91
|
+
return new Promise((resolve, reject) => {
|
|
92
|
+
server.once("error", reject);
|
|
93
|
+
// the bind of a unix socket happens inside listen(), synchronously: the umask is restored
|
|
94
|
+
// right after it, never left closed across an await
|
|
95
|
+
const umask = process.umask(0o077);
|
|
96
|
+
try {
|
|
97
|
+
server.listen(path, () => {
|
|
98
|
+
server.off("error", reject);
|
|
99
|
+
resolve();
|
|
100
|
+
});
|
|
101
|
+
}
|
|
102
|
+
finally {
|
|
103
|
+
process.umask(umask);
|
|
104
|
+
}
|
|
105
|
+
});
|
|
106
|
+
}
|
|
107
|
+
/**
|
|
108
|
+
* Starts the control socket at `<stateDir>/control.sock` (mode 0600). Answers `{ unavailable }`
|
|
109
|
+
* with the reason instead when the socket cannot be made safely; the runner keeps serving then.
|
|
110
|
+
*/
|
|
111
|
+
export async function startControlServer(opts) {
|
|
112
|
+
const path = controlSocketPath(opts.stateDir);
|
|
113
|
+
const blocked = controlUnavailableReason(opts.stateDir) ?? (await clearPath(path));
|
|
114
|
+
if (blocked !== undefined)
|
|
115
|
+
return { unavailable: blocked };
|
|
116
|
+
const sockets = new Set();
|
|
117
|
+
const subscribers = new Set();
|
|
118
|
+
const send = (sock, line) => {
|
|
119
|
+
if (sock.destroyed || !sock.writable)
|
|
120
|
+
return;
|
|
121
|
+
sock.write(`${JSON.stringify(line)}\n`);
|
|
122
|
+
// a peer that stopped reading (a subscriber above all) never pins memory here
|
|
123
|
+
if (sock.writableLength > CONTROL_WRITE_MAX_BYTES)
|
|
124
|
+
sock.destroy();
|
|
125
|
+
};
|
|
126
|
+
const failure = (id, code, message) => ({
|
|
127
|
+
id,
|
|
128
|
+
ok: false,
|
|
129
|
+
error: { code, message },
|
|
130
|
+
});
|
|
131
|
+
const fail = (sock, id, code, message) => send(sock, failure(id, code, message));
|
|
132
|
+
/** The answer to one request line; a subscribe also adds the connection to the subscribers. */
|
|
133
|
+
const respond = (sock, line) => {
|
|
134
|
+
let req;
|
|
135
|
+
try {
|
|
136
|
+
req = JSON.parse(line);
|
|
137
|
+
}
|
|
138
|
+
catch {
|
|
139
|
+
return failure(0, "bad_request", "The line is not JSON");
|
|
140
|
+
}
|
|
141
|
+
const r = (req !== null && typeof req === "object" ? req : {});
|
|
142
|
+
const id = typeof r.id === "number" && Number.isSafeInteger(r.id) && r.id > 0 ? r.id : 0;
|
|
143
|
+
if (id === 0)
|
|
144
|
+
return failure(0, "bad_request", 'The request needs "id", a positive integer');
|
|
145
|
+
if (typeof r.op !== "string" || !CONTROL_OPS.includes(r.op)) {
|
|
146
|
+
return failure(id, "unknown_op", `Unknown op; one of ${CONTROL_OPS.join(", ")}`);
|
|
147
|
+
}
|
|
148
|
+
const op = r.op;
|
|
149
|
+
try {
|
|
150
|
+
if (op === "status")
|
|
151
|
+
return { id, ok: true, result: opts.status() };
|
|
152
|
+
if (op === "running")
|
|
153
|
+
return { id, ok: true, result: opts.running() };
|
|
154
|
+
if (op === "subscribe") {
|
|
155
|
+
subscribers.add(sock);
|
|
156
|
+
return { id, ok: true, result: opts.status() };
|
|
157
|
+
}
|
|
158
|
+
if (op === "drain")
|
|
159
|
+
opts.drain();
|
|
160
|
+
else
|
|
161
|
+
opts.stop();
|
|
162
|
+
return { id, ok: true, result: null };
|
|
163
|
+
}
|
|
164
|
+
catch (e) {
|
|
165
|
+
return failure(id, "failed", e.message);
|
|
166
|
+
}
|
|
167
|
+
};
|
|
168
|
+
const answer = (sock, line) => send(sock, respond(sock, line));
|
|
169
|
+
const server = createServer((sock) => {
|
|
170
|
+
sockets.add(sock);
|
|
171
|
+
sock.setEncoding("utf8");
|
|
172
|
+
let buf = "";
|
|
173
|
+
let refused = false;
|
|
174
|
+
const overLong = () => {
|
|
175
|
+
refused = true;
|
|
176
|
+
buf = "";
|
|
177
|
+
fail(sock, 0, "bad_request", `A line is longer than ${CONTROL_LINE_MAX_BYTES} bytes`);
|
|
178
|
+
sock.end();
|
|
179
|
+
};
|
|
180
|
+
// one listener per connection: lines are answered in order
|
|
181
|
+
sock.on("data", (chunk) => {
|
|
182
|
+
if (refused)
|
|
183
|
+
return;
|
|
184
|
+
buf += chunk;
|
|
185
|
+
for (let i = buf.indexOf("\n"); i >= 0; i = buf.indexOf("\n")) {
|
|
186
|
+
const line = buf.slice(0, i);
|
|
187
|
+
buf = buf.slice(i + 1);
|
|
188
|
+
if (Buffer.byteLength(line) > CONTROL_LINE_MAX_BYTES)
|
|
189
|
+
return overLong();
|
|
190
|
+
if (line.trim() !== "")
|
|
191
|
+
answer(sock, line);
|
|
192
|
+
}
|
|
193
|
+
if (Buffer.byteLength(buf) > CONTROL_LINE_MAX_BYTES)
|
|
194
|
+
overLong();
|
|
195
|
+
});
|
|
196
|
+
sock.on("error", () => {
|
|
197
|
+
// a peer that went away: nothing to answer
|
|
198
|
+
});
|
|
199
|
+
sock.on("close", () => {
|
|
200
|
+
sockets.delete(sock);
|
|
201
|
+
subscribers.delete(sock);
|
|
202
|
+
});
|
|
203
|
+
});
|
|
204
|
+
server.maxConnections = MAX_CONNECTIONS;
|
|
205
|
+
try {
|
|
206
|
+
await listen(server, path);
|
|
207
|
+
}
|
|
208
|
+
catch (e) {
|
|
209
|
+
const err = e;
|
|
210
|
+
return {
|
|
211
|
+
unavailable: err.code === "EADDRINUSE"
|
|
212
|
+
? `another capybara-device already answers on ${path}`
|
|
213
|
+
: `cannot listen on ${path} (${err.message})`,
|
|
214
|
+
};
|
|
215
|
+
}
|
|
216
|
+
let bound;
|
|
217
|
+
try {
|
|
218
|
+
chmodSync(path, 0o600);
|
|
219
|
+
bound = lstatSync(path);
|
|
220
|
+
}
|
|
221
|
+
catch (e) {
|
|
222
|
+
await new Promise((r) => server.close(() => r()));
|
|
223
|
+
return { unavailable: `cannot secure ${path} (${e.message})` };
|
|
224
|
+
}
|
|
225
|
+
server.on("error", () => {
|
|
226
|
+
// a failure after listening affects new connections only; the runner keeps serving
|
|
227
|
+
});
|
|
228
|
+
let closed;
|
|
229
|
+
return {
|
|
230
|
+
publish(s) {
|
|
231
|
+
for (const sock of subscribers)
|
|
232
|
+
send(sock, { event: "status", status: s });
|
|
233
|
+
},
|
|
234
|
+
close() {
|
|
235
|
+
closed ??= new Promise((resolve) => {
|
|
236
|
+
for (const sock of sockets)
|
|
237
|
+
sock.destroy();
|
|
238
|
+
server.close(() => {
|
|
239
|
+
try {
|
|
240
|
+
// only the socket this server bound: one another runner bound meanwhile stays
|
|
241
|
+
const now = lstatSync(path);
|
|
242
|
+
if (now.ino === bound.ino && now.dev === bound.dev)
|
|
243
|
+
unlinkSync(path);
|
|
244
|
+
}
|
|
245
|
+
catch {
|
|
246
|
+
// removed already (the listener's close unlinks it)
|
|
247
|
+
}
|
|
248
|
+
resolve();
|
|
249
|
+
});
|
|
250
|
+
});
|
|
251
|
+
return closed;
|
|
252
|
+
},
|
|
253
|
+
};
|
|
254
|
+
}
|
|
@@ -14,6 +14,11 @@ export interface MacOperationBackendOptions {
|
|
|
14
14
|
*/
|
|
15
15
|
runtimeHash?: string;
|
|
16
16
|
readOwnerCeiling: () => Promise<DeviceOwnerCeiling>;
|
|
17
|
+
/**
|
|
18
|
+
* Called when an operation's worker is gone (completed, killed, failed to launch): a background
|
|
19
|
+
* task long after its start answered. Feeds the control socket's running operations.
|
|
20
|
+
*/
|
|
21
|
+
onOperationEnded?: (operationId: string) => void;
|
|
17
22
|
}
|
|
18
23
|
export type MacOperationBackend = Required<Pick<SandboxProvider, "permissionSupport" | "operation" | "browse" | "prepare" | "revokeOperation" | "background">> & {
|
|
19
24
|
forExecution(authority: LocalExecAuthority): Pick<MacOperationBackend, "operation" | "background">;
|
|
@@ -1,8 +1,10 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
1
2
|
import { resolve } from "node:path";
|
|
2
3
|
import { parseSandboxBrowseScope, parseSandboxOperationScope, parseSandboxPreparationScope, SandboxPermissionUnsupportedError, SandboxScopeDeniedError, validateSandboxPathShape, } from "@capybara-hq/plugin-sdk";
|
|
3
4
|
import { implicitWritePaths } from "../policy.js";
|
|
4
5
|
import { MacOperationSupervisor, } from "./operation-supervisor.js";
|
|
5
6
|
import { checkRoots, digest, freezeAuthority, intersectOperation, within, } from "./operation-types.js";
|
|
7
|
+
import { timed } from "./transfer-timing.js";
|
|
6
8
|
const PENDING = "Restricted macOS per-instance validation and coordinated policy/background activation are pending";
|
|
7
9
|
export async function createMacOperationBackend(options, dependencies = {}) {
|
|
8
10
|
const platform = dependencies.platform ?? process.platform;
|
|
@@ -75,6 +77,7 @@ export async function createLocalOperationBackend(options, dependencies, host) {
|
|
|
75
77
|
...(dependencies.now ? { now: dependencies.now } : {}),
|
|
76
78
|
...(host.startWorker ? { start: host.startWorker } : {}),
|
|
77
79
|
...(host.reapOrphan ? { reapOrphan: host.reapOrphan } : {}),
|
|
80
|
+
...(options.onOperationEnded ? { onLiveEnded: options.onOperationEnded } : {}),
|
|
78
81
|
onLiveChanged: (live) => {
|
|
79
82
|
if (live && !stopWatch) {
|
|
80
83
|
if (dependencies.watch)
|
|
@@ -208,7 +211,16 @@ export async function createLocalOperationBackend(options, dependencies, host) {
|
|
|
208
211
|
cwd: args?.cwd ?? options.roots.workspace,
|
|
209
212
|
},
|
|
210
213
|
};
|
|
211
|
-
|
|
214
|
+
// The admission hash binds the operation id to its exact input. A write's bytes enter it as
|
|
215
|
+
// their sha256, hashed once, instead of being re-serialised inside the request JSON: a
|
|
216
|
+
// collision-resistant hash of the bytes binds them as tightly as the bytes themselves.
|
|
217
|
+
const hash = timed(native?.method ?? "exec", "digest", () => {
|
|
218
|
+
const { dataB64, ...rest } = native ?? {};
|
|
219
|
+
const input = dataB64 === undefined
|
|
220
|
+
? native
|
|
221
|
+
: { ...rest, dataSha256: createHash("sha256").update(dataB64).digest("hex") };
|
|
222
|
+
return digest({ scope, native: input, args, authority, background });
|
|
223
|
+
});
|
|
212
224
|
return background
|
|
213
225
|
? supervisor.start(request, hash, background.retainUntilMs, signal)
|
|
214
226
|
: supervisor.execute(request, hash, signal);
|
|
@@ -221,15 +233,23 @@ export async function createLocalOperationBackend(options, dependencies, host) {
|
|
|
221
233
|
opts.maxBytes < 0 ||
|
|
222
234
|
opts.maxBytes > 16 * 1024 * 1024)
|
|
223
235
|
throw new SandboxScopeDeniedError("Invalid native read bound");
|
|
224
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
236
|
+
return timed("readFile", "total", async () => {
|
|
237
|
+
const result = (await run({ method: "readFile", path, maxBytes: opts.maxBytes }, opts.signal));
|
|
238
|
+
return result
|
|
239
|
+
? timed("readFile", "encode", () => ({
|
|
240
|
+
data: Buffer.from(result.dataB64, "base64"),
|
|
241
|
+
truncated: result.truncated,
|
|
242
|
+
}))
|
|
243
|
+
: null;
|
|
244
|
+
});
|
|
228
245
|
},
|
|
229
246
|
writeFile: async (path, data, signal) => {
|
|
230
247
|
if (data.byteLength > 16 * 1024 * 1024)
|
|
231
248
|
throw new SandboxScopeDeniedError("Native write exceeds bounded transport");
|
|
232
|
-
await
|
|
249
|
+
await timed("writeFile", "total", async () => {
|
|
250
|
+
const dataB64 = timed("writeFile", "encode", () => Buffer.from(data).toString("base64"));
|
|
251
|
+
await run({ method: "writeFile", path, dataB64 }, signal);
|
|
252
|
+
});
|
|
233
253
|
},
|
|
234
254
|
stat: (path, signal) => run({ method: "stat", path }, signal),
|
|
235
255
|
list: (path, opts) => run({ method: "list", path, limit: opts.limit }, opts.signal),
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { spawn } from "node:child_process";
|
|
2
2
|
import { fstatSync } from "node:fs";
|
|
3
3
|
import { SANDBOX_RUNTIME_SOURCE, SandboxPermissionUnsupportedError, SandboxScopeDeniedError, } from "@capybara-hq/plugin-sdk";
|
|
4
|
+
import { recordTransferTiming, timed } from "./transfer-timing.js";
|
|
4
5
|
// The pinned SDK source remains unchanged. This fixed transport only establishes its exact
|
|
5
6
|
// directory roots; the ancestor descriptor never becomes a NativeFiles data grant.
|
|
6
7
|
/** The native helper by name: the bundle also carries the Linux launcher, so order is not relied on. */
|
|
@@ -82,6 +83,8 @@ export async function runNativeHelper(request, roots, launch, signal) {
|
|
|
82
83
|
throw new Error("Pinned root must be a directory");
|
|
83
84
|
return [s.dev, s.ino];
|
|
84
85
|
});
|
|
86
|
+
const spawnedAt = performance.now();
|
|
87
|
+
let dispatchedAt = 0;
|
|
85
88
|
const child = (launch.spawn ?? spawn)(launch.pythonPath, ["-I", "-c", PRELUDE, NATIVE_FILES_SOURCE, JSON.stringify(expected)], { detached: true, stdio: ["pipe", "pipe", "pipe", "pipe", ...roots.map((r) => r.fd)] });
|
|
86
89
|
let bytes = 0;
|
|
87
90
|
let stderrBytes = 0;
|
|
@@ -144,6 +147,7 @@ export async function runNativeHelper(request, roots, launch, signal) {
|
|
|
144
147
|
}
|
|
145
148
|
if (handshake === "ready\n" && !ready) {
|
|
146
149
|
ready = true;
|
|
150
|
+
recordTransferTiming(request.method, "spawn", performance.now() - spawnedAt);
|
|
147
151
|
void (async () => {
|
|
148
152
|
try {
|
|
149
153
|
await launched;
|
|
@@ -160,7 +164,9 @@ export async function runNativeHelper(request, roots, launch, signal) {
|
|
|
160
164
|
...(r.components ? { components: r.components } : {}),
|
|
161
165
|
});
|
|
162
166
|
});
|
|
163
|
-
|
|
167
|
+
const body = timed(request.method, "serialise", () => JSON.stringify({ ...request, roots: mapped }));
|
|
168
|
+
dispatchedAt = performance.now();
|
|
169
|
+
child.stdin?.end(body);
|
|
164
170
|
}
|
|
165
171
|
catch (e) {
|
|
166
172
|
failure = e;
|
|
@@ -181,6 +187,8 @@ export async function runNativeHelper(request, roots, launch, signal) {
|
|
|
181
187
|
signal.removeEventListener("abort", abort);
|
|
182
188
|
kill();
|
|
183
189
|
}
|
|
190
|
+
if (dispatchedAt)
|
|
191
|
+
recordTransferTiming(request.method, "helperIo", performance.now() - dispatchedAt);
|
|
184
192
|
signal.throwIfAborted();
|
|
185
193
|
if (failure)
|
|
186
194
|
throw failure;
|
|
@@ -188,7 +196,7 @@ export async function runNativeHelper(request, roots, launch, signal) {
|
|
|
188
196
|
throw new SandboxPermissionUnsupportedError("Native helper descriptor handshake failed; pathname reopening is forbidden");
|
|
189
197
|
let response;
|
|
190
198
|
try {
|
|
191
|
-
response = JSON.parse(Buffer.concat(chunks).toString("utf8"));
|
|
199
|
+
response = timed(request.method, "parse", () => JSON.parse(Buffer.concat(chunks).toString("utf8")));
|
|
192
200
|
}
|
|
193
201
|
catch {
|
|
194
202
|
throw new Error("Native helper returned invalid bounded JSON");
|
|
@@ -11,7 +11,7 @@ interface Entry {
|
|
|
11
11
|
state: "consumed" | "running" | "completed" | "unknown";
|
|
12
12
|
revoked: boolean;
|
|
13
13
|
identity?: TrustedLaunchIdentity;
|
|
14
|
-
result?: ExecResult | NativeHelperResult;
|
|
14
|
+
result?: ExecResult | NativeHelperResult | OmittedReadResult;
|
|
15
15
|
stop?: SandboxStopResult;
|
|
16
16
|
request?: {
|
|
17
17
|
scope: MacWorkerRequest["scope"];
|
|
@@ -29,6 +29,17 @@ interface Entry {
|
|
|
29
29
|
cleaned?: boolean;
|
|
30
30
|
};
|
|
31
31
|
}
|
|
32
|
+
/**
|
|
33
|
+
* What the journal keeps of a completed native read: its outcome, never its bytes. The bytes stay
|
|
34
|
+
* in this process's memory for in-process retries; rewriting megabytes of file content on every
|
|
35
|
+
* fsynced journal commit is what made transfers slow and could exhaust the journal. A read has no
|
|
36
|
+
* lasting effect, so after a restart its retry reports an unknown outcome instead.
|
|
37
|
+
*/
|
|
38
|
+
interface OmittedReadResult {
|
|
39
|
+
omitted: "native-read";
|
|
40
|
+
bytes: number;
|
|
41
|
+
truncated: boolean;
|
|
42
|
+
}
|
|
32
43
|
export interface SupervisorOptions {
|
|
33
44
|
stateDir: string;
|
|
34
45
|
deviceId: string;
|
|
@@ -36,6 +47,11 @@ export interface SupervisorOptions {
|
|
|
36
47
|
now?: () => number;
|
|
37
48
|
start?: (request: MacWorkerRequest, signal: AbortSignal) => Promise<MacWorkerHandle>;
|
|
38
49
|
onLiveChanged?: (live: boolean) => void;
|
|
50
|
+
/**
|
|
51
|
+
* Called once each live worker (an exec, or a background task long after its start answered)
|
|
52
|
+
* is gone: completed, killed or failed to launch. Never throws into the supervisor.
|
|
53
|
+
*/
|
|
54
|
+
onLiveEnded?: (operationId: string) => void;
|
|
39
55
|
pythonPath?: string;
|
|
40
56
|
outputBarrier?: (name: string) => Promise<void>;
|
|
41
57
|
beforePersist?: () => void;
|
|
@@ -45,6 +61,12 @@ export interface SupervisorOptions {
|
|
|
45
61
|
* the entry stays unknown and is never resumed.
|
|
46
62
|
*/
|
|
47
63
|
reapOrphan?: (identity: TrustedLaunchIdentity) => void;
|
|
64
|
+
/**
|
|
65
|
+
* The most completed native read bytes kept in memory for retries (default 64 MiB). Past it the
|
|
66
|
+
* oldest reads give their bytes up and their retry reports an unknown outcome, as after a
|
|
67
|
+
* restart.
|
|
68
|
+
*/
|
|
69
|
+
retainedReadBytes?: number;
|
|
48
70
|
}
|
|
49
71
|
/** What a supervisor still owns: work that a drain must see settle before it disconnects. */
|
|
50
72
|
export interface SupervisorOwnership {
|
|
@@ -89,8 +111,14 @@ export declare class MacOperationSupervisor {
|
|
|
89
111
|
private controlFile;
|
|
90
112
|
private recoverControl;
|
|
91
113
|
private persistControl;
|
|
114
|
+
/**
|
|
115
|
+
* Keeps the completed read bytes held for retries within {@link SupervisorOptions.retainedReadBytes}:
|
|
116
|
+
* the oldest reads (admission order) give their bytes up first.
|
|
117
|
+
*/
|
|
118
|
+
private boundRetainedReads;
|
|
92
119
|
private serial;
|
|
93
120
|
private persist;
|
|
121
|
+
private persistNow;
|
|
94
122
|
private expireRetained;
|
|
95
123
|
private validate;
|
|
96
124
|
private admit;
|
|
@@ -117,6 +145,7 @@ export declare class MacOperationSupervisor {
|
|
|
117
145
|
* The owner watcher runs while anything is owned: a live worker, a faulted collector's owner or
|
|
118
146
|
* an exact cancellation still settling (an idle socket or a disconnect does not end it).
|
|
119
147
|
*/
|
|
148
|
+
private liveEnded;
|
|
120
149
|
private notifyOwned;
|
|
121
150
|
ownership(): SupervisorOwnership;
|
|
122
151
|
/** Starts a graceful drain: no new admission from now on, for the rest of this process. */
|
|
@@ -6,6 +6,23 @@ import { parseSandboxExecutionRef, parseSandboxOperationRef, SandboxOperationOut
|
|
|
6
6
|
import { digest } from "./operation-types.js";
|
|
7
7
|
import { startMacOperationWorker, } from "./operation-worker.js";
|
|
8
8
|
import { finalizeRecoveredOutput, ManagedOutputSpool, validateOutputRange, } from "./output-spool.js";
|
|
9
|
+
import { timed } from "./transfer-timing.js";
|
|
10
|
+
const isOmittedRead = (result) => typeof result === "object" && result !== null && "omitted" in result;
|
|
11
|
+
/** A completed native read's bytes as base64, while the entry still holds them. */
|
|
12
|
+
const readBytes = (result) => typeof result === "object" && result !== null && "dataB64" in result ? result.dataB64 : undefined;
|
|
13
|
+
const omitRead = (result) => ({
|
|
14
|
+
omitted: "native-read",
|
|
15
|
+
bytes: Buffer.byteLength(result.dataB64, "base64"),
|
|
16
|
+
truncated: result.truncated,
|
|
17
|
+
});
|
|
18
|
+
/** The entry as the journal stores it (see {@link OmittedReadResult}). */
|
|
19
|
+
function journalForm(entry) {
|
|
20
|
+
const result = entry.result;
|
|
21
|
+
if (readBytes(result) === undefined)
|
|
22
|
+
return entry;
|
|
23
|
+
return { ...entry, result: omitRead(result) };
|
|
24
|
+
}
|
|
25
|
+
const RETAINED_READ_BYTES = 64 * 1024 * 1024;
|
|
9
26
|
class JournalCommitUncertainError extends Error {
|
|
10
27
|
}
|
|
11
28
|
/** A drain gave up before everything it owns settled; the supervisor stays draining. */
|
|
@@ -290,12 +307,38 @@ export class MacOperationSupervisor {
|
|
|
290
307
|
catch { }
|
|
291
308
|
}
|
|
292
309
|
}
|
|
310
|
+
/**
|
|
311
|
+
* Keeps the completed read bytes held for retries within {@link SupervisorOptions.retainedReadBytes}:
|
|
312
|
+
* the oldest reads (admission order) give their bytes up first.
|
|
313
|
+
*/
|
|
314
|
+
boundRetainedReads() {
|
|
315
|
+
const budget = this.options.retainedReadBytes ?? RETAINED_READ_BYTES;
|
|
316
|
+
const held = [];
|
|
317
|
+
let total = 0;
|
|
318
|
+
for (const entry of this.entries.values()) {
|
|
319
|
+
const data = readBytes(entry.result);
|
|
320
|
+
if (data === undefined)
|
|
321
|
+
continue;
|
|
322
|
+
held.push(entry);
|
|
323
|
+
total += Buffer.byteLength(data, "base64");
|
|
324
|
+
}
|
|
325
|
+
for (const entry of held) {
|
|
326
|
+
if (total <= budget)
|
|
327
|
+
break;
|
|
328
|
+
const result = entry.result;
|
|
329
|
+
total -= Buffer.byteLength(result.dataB64, "base64");
|
|
330
|
+
entry.result = omitRead(result);
|
|
331
|
+
}
|
|
332
|
+
}
|
|
293
333
|
serial(fn) {
|
|
294
334
|
const next = this.queue.then(fn);
|
|
295
335
|
this.queue = next.catch(() => { });
|
|
296
336
|
return next;
|
|
297
337
|
}
|
|
298
338
|
persist() {
|
|
339
|
+
timed("supervisor", "journal", () => this.persistNow());
|
|
340
|
+
}
|
|
341
|
+
persistNow() {
|
|
299
342
|
if (this.closed)
|
|
300
343
|
throw new SandboxPermissionUnsupportedError("This instance generation was superseded; its journal belongs to the current binding");
|
|
301
344
|
if (this.journalBlocked)
|
|
@@ -309,7 +352,11 @@ export class MacOperationSupervisor {
|
|
|
309
352
|
deviceId: this.options.deviceId,
|
|
310
353
|
generation: this.options.instanceGeneration,
|
|
311
354
|
};
|
|
312
|
-
const journal = {
|
|
355
|
+
const journal = {
|
|
356
|
+
version: 1,
|
|
357
|
+
transaction,
|
|
358
|
+
entries: [...this.entries.values()].map(journalForm),
|
|
359
|
+
};
|
|
313
360
|
const text = JSON.stringify(journal);
|
|
314
361
|
if (Buffer.byteLength(text) > 64 * 1024 * 1024)
|
|
315
362
|
throw Error("Operation journal capacity exhausted");
|
|
@@ -539,6 +586,7 @@ export class MacOperationSupervisor {
|
|
|
539
586
|
};
|
|
540
587
|
entry.state = "completed";
|
|
541
588
|
entry.result = value;
|
|
589
|
+
this.boundRetainedReads();
|
|
542
590
|
if (entry.stop?.outcome === "cancel-pending" &&
|
|
543
591
|
!this.cancellations.has(entry.ref.operationId) &&
|
|
544
592
|
value &&
|
|
@@ -580,6 +628,7 @@ export class MacOperationSupervisor {
|
|
|
580
628
|
await spool?.close();
|
|
581
629
|
signal.removeEventListener("abort", abort);
|
|
582
630
|
this.live.delete(entry.ref.operationId);
|
|
631
|
+
this.liveEnded(entry.ref.operationId);
|
|
583
632
|
this.notifyOwned();
|
|
584
633
|
})
|
|
585
634
|
.catch((error) => {
|
|
@@ -604,6 +653,7 @@ export class MacOperationSupervisor {
|
|
|
604
653
|
});
|
|
605
654
|
reject(error);
|
|
606
655
|
this.live.delete(entry.ref.operationId);
|
|
656
|
+
this.liveEnded(entry.ref.operationId);
|
|
607
657
|
this.notifyOwned();
|
|
608
658
|
throw error;
|
|
609
659
|
}
|
|
@@ -613,7 +663,7 @@ export class MacOperationSupervisor {
|
|
|
613
663
|
async execute(request, hash, signal) {
|
|
614
664
|
const { entry, fresh } = await this.admit(request, hash, this.now() + 60000, signal);
|
|
615
665
|
if (!fresh) {
|
|
616
|
-
if (entry.state === "completed")
|
|
666
|
+
if (entry.state === "completed" && !isOmittedRead(entry.result))
|
|
617
667
|
return entry.result ?? null;
|
|
618
668
|
throw new SandboxOperationOutcomeUnknownError("Consumed operation outcome is unknown");
|
|
619
669
|
}
|
|
@@ -872,6 +922,14 @@ export class MacOperationSupervisor {
|
|
|
872
922
|
* The owner watcher runs while anything is owned: a live worker, a faulted collector's owner or
|
|
873
923
|
* an exact cancellation still settling (an idle socket or a disconnect does not end it).
|
|
874
924
|
*/
|
|
925
|
+
liveEnded(operationId) {
|
|
926
|
+
try {
|
|
927
|
+
this.options.onLiveEnded?.(operationId);
|
|
928
|
+
}
|
|
929
|
+
catch {
|
|
930
|
+
// an observer never affects the supervisor
|
|
931
|
+
}
|
|
932
|
+
}
|
|
875
933
|
notifyOwned() {
|
|
876
934
|
this.options.onLiveChanged?.(this.live.size > 0 || this.faultOwners.size > 0 || this.cancellations.size > 0);
|
|
877
935
|
}
|
|
@@ -12,6 +12,7 @@ import { runNativeHelper, } from "./native-helper-client.js";
|
|
|
12
12
|
import { withCanonicalForms } from "./operation-types.js";
|
|
13
13
|
import { acquireSealedRuntime, stagePrivateSource, stageRuntimeSource, } from "./runtime-source.js";
|
|
14
14
|
import { ENV_NAME_RE, OutputCap, restrictedToolHomes, shellQuote } from "./shared.js";
|
|
15
|
+
import { recordTransferTiming } from "./transfer-timing.js";
|
|
15
16
|
/** Coalesce an active owned cancellation; a failed attempt never becomes a cached outcome. */
|
|
16
17
|
export function createCancellationAttempt(attempt) {
|
|
17
18
|
let pending;
|
|
@@ -370,6 +371,7 @@ export async function startMacOperationWorker(request, signal) {
|
|
|
370
371
|
abort();
|
|
371
372
|
let sealed;
|
|
372
373
|
let privateTmp;
|
|
374
|
+
const preparedAt = performance.now();
|
|
373
375
|
const completion = (async () => {
|
|
374
376
|
try {
|
|
375
377
|
// Restricted workers import only the sealed private copy of the verified runtime closure
|
|
@@ -578,6 +580,7 @@ export async function startMacOperationWorker(request, signal) {
|
|
|
578
580
|
const transport = await import("./native-helper-client.js");
|
|
579
581
|
const invocation = transport.nativeHelperInvocation(roots, launch);
|
|
580
582
|
prepared = await wrap([invocation.command, ...invocation.args].map(shellQuote).join(" "));
|
|
583
|
+
recordTransferTiming(request.native.method, "prepare", performance.now() - preparedAt);
|
|
581
584
|
return await runNativeHelper({
|
|
582
585
|
...request.native,
|
|
583
586
|
path: (() => {
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Debug-level stage timings of native file transfers (readFile / writeFile). Off by default:
|
|
3
|
+
* `CAPYBARA_DEVICE_DEBUG_TIMINGS=1` prints one line per stage to stderr, and tests observe the
|
|
4
|
+
* stages through {@link observeTransferTimings}. Timings carry no paths and no data.
|
|
5
|
+
*/
|
|
6
|
+
export type TransferStage = "encode" | "digest" | "journal" | "prepare" | "spawn" | "serialise" | "helperIo" | "parse" | "total";
|
|
7
|
+
export interface TransferTiming {
|
|
8
|
+
method: string;
|
|
9
|
+
stage: TransferStage;
|
|
10
|
+
ms: number;
|
|
11
|
+
}
|
|
12
|
+
/** Observes every recorded stage until the returned function is called. */
|
|
13
|
+
export declare function observeTransferTimings(listener: (timing: TransferTiming) => void): () => void;
|
|
14
|
+
export declare function recordTransferTiming(method: string, stage: TransferStage, ms: number): void;
|
|
15
|
+
/** Runs `work` and records how long it took as `stage`. */
|
|
16
|
+
export declare function timed<T>(method: string, stage: TransferStage, work: () => T): T;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
const listeners = new Set();
|
|
2
|
+
/** Observes every recorded stage until the returned function is called. */
|
|
3
|
+
export function observeTransferTimings(listener) {
|
|
4
|
+
listeners.add(listener);
|
|
5
|
+
return () => listeners.delete(listener);
|
|
6
|
+
}
|
|
7
|
+
export function recordTransferTiming(method, stage, ms) {
|
|
8
|
+
if (process.env.CAPYBARA_DEVICE_DEBUG_TIMINGS === "1")
|
|
9
|
+
process.stderr.write(`[capybara-device] ${method} ${stage} ${ms.toFixed(1)} ms\n`);
|
|
10
|
+
for (const listener of listeners)
|
|
11
|
+
try {
|
|
12
|
+
listener({ method, stage, ms });
|
|
13
|
+
}
|
|
14
|
+
catch {
|
|
15
|
+
// instrumentation never changes an operation's outcome
|
|
16
|
+
}
|
|
17
|
+
}
|
|
18
|
+
/** Runs `work` and records how long it took as `stage`. */
|
|
19
|
+
export function timed(method, stage, work) {
|
|
20
|
+
const started = performance.now();
|
|
21
|
+
const result = work();
|
|
22
|
+
if (result instanceof Promise)
|
|
23
|
+
return result.finally(() => recordTransferTiming(method, stage, performance.now() - started));
|
|
24
|
+
recordTransferTiming(method, stage, performance.now() - started);
|
|
25
|
+
return result;
|
|
26
|
+
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
export type { RunningOperation } from "./activity.js";
|
|
1
2
|
export { type Command, parseCommandLine } from "./args.js";
|
|
2
3
|
export { runCli } from "./cli.js";
|
|
4
|
+
export { type ControlEvent, type ControlRequest, type ControlResponse, controlSocketPath, type LiveStatus, } from "./control/protocol.js";
|
|
3
5
|
export { type Credential, type Policy, type SandboxMode, stateDir } from "./state.js";
|
package/dist/index.js
CHANGED