@capybara-hq/device 0.1.0-rc.3 → 0.1.0-rc.5
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 +201 -11
- package/dist/args.d.ts +4 -2
- package/dist/args.js +21 -5
- package/dist/cli.d.ts +12 -2
- package/dist/cli.js +60 -8
- package/dist/client.d.ts +13 -0
- package/dist/client.js +72 -13
- package/dist/command-log.d.ts +10 -0
- package/dist/commands/policy.d.ts +66 -3
- package/dist/commands/policy.js +347 -31
- package/dist/commands/start.d.ts +9 -3
- package/dist/commands/start.js +18 -3
- package/dist/exec/docker.d.ts +41 -5
- package/dist/exec/docker.js +73 -19
- package/dist/exec/groups.d.ts +42 -0
- package/dist/exec/groups.js +100 -0
- package/dist/exec/host.d.ts +53 -0
- package/dist/exec/host.js +183 -0
- package/dist/exec/os.d.ts +73 -5
- package/dist/exec/os.js +190 -15
- package/dist/exec/shared.d.ts +44 -0
- package/dist/exec/shared.js +210 -1
- package/dist/exec/switch.d.ts +108 -0
- package/dist/exec/switch.js +214 -0
- package/dist/exec/types.d.ts +37 -3
- package/dist/network.d.ts +45 -0
- package/dist/network.js +161 -0
- package/dist/policy-store.d.ts +38 -0
- package/dist/policy-store.js +92 -0
- package/dist/policy.d.ts +102 -11
- package/dist/policy.js +155 -20
- package/dist/proxy-guard.d.ts +58 -0
- package/dist/proxy-guard.js +137 -0
- package/dist/public-suffix.d.ts +6 -0
- package/dist/public-suffix.js +79 -0
- package/dist/server-ops.d.ts +65 -7
- package/dist/server-ops.js +289 -29
- package/dist/state.d.ts +44 -1
- package/dist/state.js +177 -9
- package/package.json +2 -2
package/dist/exec/docker.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { type DeviceExecArgs, type ExecResult, type SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
1
|
+
import { type DeviceExecArgs, type ExecResult, type SandboxRoots, type SandboxTier } from "@capybara-hq/plugin-sdk";
|
|
2
|
+
import { type EgressLimits, type TierFacts } from "../policy.js";
|
|
2
3
|
import type { Policy } from "../state.js";
|
|
3
4
|
import { type Executor } from "./types.js";
|
|
4
5
|
/** The version of the published sandbox images this program runs commands in. */
|
|
@@ -10,6 +11,20 @@ export declare const SANDBOX_IMAGE = "ghcr.io/capybara-hq/capybara-sandbox:0.1.0
|
|
|
10
11
|
* Docker Desktop (macOS) maps file ownership itself, so the image's user is used there.
|
|
11
12
|
*/
|
|
12
13
|
export declare function containerUser(platform?: NodeJS.Platform, uid?: number | undefined, gid?: number | undefined): string;
|
|
14
|
+
/**
|
|
15
|
+
* The container's `--shm-size` for a tier (spec §5.2): `strict` keeps Docker's default (64 MiB);
|
|
16
|
+
* `dev` and `open` get a quarter of the memory ceiling up to 1 GiB (at least the default), or
|
|
17
|
+
* 1 GiB without a ceiling, so browsers have room.
|
|
18
|
+
*/
|
|
19
|
+
export declare function shmSize(tier: SandboxTier, memoryMb: number | null): string | undefined;
|
|
20
|
+
/**
|
|
21
|
+
* Whether a command gets the default bridge (spec §5.2 table). Docker mode has no domain filter,
|
|
22
|
+
* and the bridge reaches the host and the intranet, so only an explicit choice opens it: the
|
|
23
|
+
* device's own allowed domains within the ceiling (as `strict` computes them; the dev hosts do
|
|
24
|
+
* not count), or tier `open` with a ceiling that allows any host (an allowlist ceiling at `open`
|
|
25
|
+
* counts only its explicit local domains, like the lower tiers).
|
|
26
|
+
*/
|
|
27
|
+
export declare function bridgeNetwork(policy: Policy, limits: EgressLimits): boolean;
|
|
13
28
|
/** Container name of a device. */
|
|
14
29
|
export declare function containerName(deviceId: string): string;
|
|
15
30
|
/** Whether the docker CLI can reach a daemon, and why not. */
|
|
@@ -23,7 +38,12 @@ export interface DockerExecutorOptions {
|
|
|
23
38
|
/** The device directory (from login). */
|
|
24
39
|
dir: string;
|
|
25
40
|
deviceId: string;
|
|
26
|
-
|
|
41
|
+
/**
|
|
42
|
+
* The local policy now. The network decision reads it at each command; cpu, memory and the
|
|
43
|
+
* tier's shm size apply when the container is next created (at the next command that finds it
|
|
44
|
+
* idle).
|
|
45
|
+
*/
|
|
46
|
+
policy: () => Policy;
|
|
27
47
|
}
|
|
28
48
|
/**
|
|
29
49
|
* Runs every command with `docker exec` in one long-lived container of the published sandbox
|
|
@@ -31,8 +51,10 @@ export interface DockerExecutorOptions {
|
|
|
31
51
|
* /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
|
|
32
52
|
* (as the `sandbox` user, so a link a command plants resolves in the container and never on the
|
|
33
53
|
* host); the skills directory, which commands cannot write, is accessed from the host with the
|
|
34
|
-
* same real-path checks as the OS executor. Network: none unless
|
|
35
|
-
*
|
|
54
|
+
* same real-path checks as the OS executor. Network: none unless {@link bridgeNetwork} says
|
|
55
|
+
* otherwise, then the default bridge (Docker mode has no domain allowlist). Tiers `dev` and
|
|
56
|
+
* `open` get a larger `/dev/shm` ({@link shmSize}); a change of the container's flags recreates it
|
|
57
|
+
* at the next command that finds it idle.
|
|
36
58
|
*/
|
|
37
59
|
export declare class DockerExecutor implements Executor {
|
|
38
60
|
private readonly opts;
|
|
@@ -54,19 +76,33 @@ export declare class DockerExecutor implements Executor {
|
|
|
54
76
|
private readonly queue;
|
|
55
77
|
private pumping;
|
|
56
78
|
private dirty;
|
|
79
|
+
/** The limits of the latest command: they decide the tier the container is made for. */
|
|
80
|
+
private lastLimits;
|
|
81
|
+
/** The spec hash of the container in use (set when it is created or reused). */
|
|
82
|
+
private spec;
|
|
57
83
|
constructor(opts: DockerExecutorOptions);
|
|
58
84
|
ensureRoot(): Promise<"ok" | "gone">;
|
|
59
85
|
markerOf(tag: string): string;
|
|
60
86
|
private serial;
|
|
61
87
|
private inspect;
|
|
62
88
|
private wanted;
|
|
89
|
+
/** The tier commands run at now (the owner's choice, else `dev`, before any command). */
|
|
90
|
+
tier(policy?: Policy): SandboxTier;
|
|
91
|
+
/** What the tier gives in this mode (for the policy summary). */
|
|
92
|
+
tierFacts(policy?: Policy): TierFacts;
|
|
63
93
|
/** Every `docker run` flag of the container except its name and spec label. */
|
|
64
94
|
private runArgs;
|
|
65
95
|
/** A hash of the run flags: a container made with other flags is recreated. */
|
|
66
96
|
private specHash;
|
|
97
|
+
private hashOf;
|
|
67
98
|
private matches;
|
|
68
99
|
private mustDocker;
|
|
69
|
-
/**
|
|
100
|
+
/**
|
|
101
|
+
* Creates the container, or reuses the existing one when it matches; call inside `serial`.
|
|
102
|
+
* A file operation (`anySpec`) reuses any container that sees the directory: it needs no
|
|
103
|
+
* particular flags, and before the first command the tier is not known yet. The next command
|
|
104
|
+
* that finds it idle recreates it if its flags differ.
|
|
105
|
+
*/
|
|
70
106
|
private ensureContainer;
|
|
71
107
|
/**
|
|
72
108
|
* Whether a reused container's mounts still show this directory's roots: after the directory was
|
package/dist/exec/docker.js
CHANGED
|
@@ -3,7 +3,7 @@ import { createHash, randomBytes } from "node:crypto";
|
|
|
3
3
|
import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
|
|
4
4
|
import { join, resolve } from "node:path";
|
|
5
5
|
import { DEFAULT_SANDBOX_ROOTS, } from "@capybara-hq/plugin-sdk";
|
|
6
|
-
import { effectiveEgress } from "../policy.js";
|
|
6
|
+
import { ANY_HOST, deviceTier, effectiveEgress, provisionalTier, tierFacts, } from "../policy.js";
|
|
7
7
|
import { EXEC_MARKER } from "./procs.js";
|
|
8
8
|
import { ENV_NAME_RE, HostFiles, isUnder, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, } from "./shared.js";
|
|
9
9
|
import { DeviceOpError } from "./types.js";
|
|
@@ -26,6 +26,31 @@ const SPEC_LABEL = "capybara.device.spec";
|
|
|
26
26
|
/** A file operation in the container that takes longer than this is killed. */
|
|
27
27
|
const FILE_OP_TIMEOUT_S = 30;
|
|
28
28
|
const ROOTS = DEFAULT_SANDBOX_ROOTS;
|
|
29
|
+
/**
|
|
30
|
+
* The container's `--shm-size` for a tier (spec §5.2): `strict` keeps Docker's default (64 MiB);
|
|
31
|
+
* `dev` and `open` get a quarter of the memory ceiling up to 1 GiB (at least the default), or
|
|
32
|
+
* 1 GiB without a ceiling, so browsers have room.
|
|
33
|
+
*/
|
|
34
|
+
export function shmSize(tier, memoryMb) {
|
|
35
|
+
if (tier === "strict")
|
|
36
|
+
return undefined;
|
|
37
|
+
if (memoryMb === null)
|
|
38
|
+
return "1g";
|
|
39
|
+
return `${Math.max(64, Math.min(1024, Math.floor(memoryMb / 4)))}m`;
|
|
40
|
+
}
|
|
41
|
+
/**
|
|
42
|
+
* Whether a command gets the default bridge (spec §5.2 table). Docker mode has no domain filter,
|
|
43
|
+
* and the bridge reaches the host and the intranet, so only an explicit choice opens it: the
|
|
44
|
+
* device's own allowed domains within the ceiling (as `strict` computes them; the dev hosts do
|
|
45
|
+
* not count), or tier `open` with a ceiling that allows any host (an allowlist ceiling at `open`
|
|
46
|
+
* counts only its explicit local domains, like the lower tiers).
|
|
47
|
+
*/
|
|
48
|
+
export function bridgeNetwork(policy, limits) {
|
|
49
|
+
if (deviceTier(policy, limits) === "open" && effectiveEgress(policy, limits).includes(ANY_HOST)) {
|
|
50
|
+
return true;
|
|
51
|
+
}
|
|
52
|
+
return effectiveEgress({ ...policy, tier: "strict" }, limits).length > 0;
|
|
53
|
+
}
|
|
29
54
|
/** Container name of a device. */
|
|
30
55
|
export function containerName(deviceId) {
|
|
31
56
|
return `capybara-device-${deviceId}`;
|
|
@@ -125,8 +150,10 @@ cat > "$f" || exit ${E_FAIL}`;
|
|
|
125
150
|
* /workspace, /skills and /tmp. Workspace and tmp files are read and written inside the container
|
|
126
151
|
* (as the `sandbox` user, so a link a command plants resolves in the container and never on the
|
|
127
152
|
* host); the skills directory, which commands cannot write, is accessed from the host with the
|
|
128
|
-
* same real-path checks as the OS executor. Network: none unless
|
|
129
|
-
*
|
|
153
|
+
* same real-path checks as the OS executor. Network: none unless {@link bridgeNetwork} says
|
|
154
|
+
* otherwise, then the default bridge (Docker mode has no domain allowlist). Tiers `dev` and
|
|
155
|
+
* `open` get a larger `/dev/shm` ({@link shmSize}); a change of the container's flags recreates it
|
|
156
|
+
* at the next command that finds it idle.
|
|
130
157
|
*/
|
|
131
158
|
export class DockerExecutor {
|
|
132
159
|
opts;
|
|
@@ -148,6 +175,10 @@ export class DockerExecutor {
|
|
|
148
175
|
queue = [];
|
|
149
176
|
pumping = false;
|
|
150
177
|
dirty = false;
|
|
178
|
+
/** The limits of the latest command: they decide the tier the container is made for. */
|
|
179
|
+
lastLimits;
|
|
180
|
+
/** The spec hash of the container in use (set when it is created or reused). */
|
|
181
|
+
spec;
|
|
151
182
|
constructor(opts) {
|
|
152
183
|
this.opts = opts;
|
|
153
184
|
const dir = resolve(opts.dir);
|
|
@@ -182,9 +213,20 @@ export class DockerExecutor {
|
|
|
182
213
|
{ source: this.hostRoots.tmp, dest: ROOTS.tmp, rw: true },
|
|
183
214
|
];
|
|
184
215
|
}
|
|
216
|
+
/** The tier commands run at now (the owner's choice, else `dev`, before any command). */
|
|
217
|
+
tier(policy = this.opts.policy()) {
|
|
218
|
+
return this.lastLimits === undefined
|
|
219
|
+
? provisionalTier(policy)
|
|
220
|
+
: deviceTier(policy, this.lastLimits);
|
|
221
|
+
}
|
|
222
|
+
/** What the tier gives in this mode (for the policy summary). */
|
|
223
|
+
tierFacts(policy = this.opts.policy()) {
|
|
224
|
+
return tierFacts(policy, this.lastLimits, { proxyDetected: false, mode: "docker" });
|
|
225
|
+
}
|
|
185
226
|
/** Every `docker run` flag of the container except its name and spec label. */
|
|
186
227
|
runArgs() {
|
|
187
|
-
const
|
|
228
|
+
const policy = this.opts.policy();
|
|
229
|
+
const shm = shmSize(this.tier(policy), policy.memoryMb);
|
|
188
230
|
return [
|
|
189
231
|
"--init",
|
|
190
232
|
"--read-only",
|
|
@@ -208,6 +250,7 @@ export class DockerExecutor {
|
|
|
208
250
|
...(policy.memoryMb !== null
|
|
209
251
|
? ["--memory", `${policy.memoryMb}m`, "--memory-swap", `${policy.memoryMb}m`]
|
|
210
252
|
: []),
|
|
253
|
+
...(shm !== undefined ? ["--shm-size", shm] : []),
|
|
211
254
|
"--entrypoint",
|
|
212
255
|
"sleep",
|
|
213
256
|
SANDBOX_IMAGE,
|
|
@@ -216,7 +259,10 @@ export class DockerExecutor {
|
|
|
216
259
|
}
|
|
217
260
|
/** A hash of the run flags: a container made with other flags is recreated. */
|
|
218
261
|
specHash() {
|
|
219
|
-
return
|
|
262
|
+
return this.hashOf(this.runArgs());
|
|
263
|
+
}
|
|
264
|
+
hashOf(runArgs) {
|
|
265
|
+
return createHash("sha256").update(JSON.stringify(runArgs)).digest("hex").slice(0, 16);
|
|
220
266
|
}
|
|
221
267
|
matches(c) {
|
|
222
268
|
return c.Config.Labels?.[SPEC_LABEL] === this.specHash();
|
|
@@ -228,8 +274,13 @@ export class DockerExecutor {
|
|
|
228
274
|
}
|
|
229
275
|
return r;
|
|
230
276
|
}
|
|
231
|
-
/**
|
|
232
|
-
|
|
277
|
+
/**
|
|
278
|
+
* Creates the container, or reuses the existing one when it matches; call inside `serial`.
|
|
279
|
+
* A file operation (`anySpec`) reuses any container that sees the directory: it needs no
|
|
280
|
+
* particular flags, and before the first command the tier is not known yet. The next command
|
|
281
|
+
* that finds it idle recreates it if its flags differ.
|
|
282
|
+
*/
|
|
283
|
+
async ensureContainer(opts = {}) {
|
|
233
284
|
if (this.ready)
|
|
234
285
|
return;
|
|
235
286
|
if (!existsSync(this.dir)) {
|
|
@@ -242,20 +293,16 @@ export class DockerExecutor {
|
|
|
242
293
|
mkdirSync(r, { recursive: true });
|
|
243
294
|
}
|
|
244
295
|
let c = await this.inspect();
|
|
245
|
-
if (c !== null &&
|
|
296
|
+
if (c !== null &&
|
|
297
|
+
((opts.anySpec !== true && !this.matches(c)) || !(await this.seesHostRoots(c)))) {
|
|
246
298
|
await this.mustDocker(["rm", "-f", this.name], "removing the old container");
|
|
247
299
|
c = null;
|
|
248
300
|
}
|
|
249
301
|
if (c === null) {
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
this.name,
|
|
255
|
-
"--label",
|
|
256
|
-
`${SPEC_LABEL}=${this.specHash()}`,
|
|
257
|
-
...this.runArgs(),
|
|
258
|
-
], "creating the container");
|
|
302
|
+
const runArgs = this.runArgs();
|
|
303
|
+
const spec = this.hashOf(runArgs);
|
|
304
|
+
await this.mustDocker(["run", "-d", "--name", this.name, "--label", `${SPEC_LABEL}=${spec}`, ...runArgs], "creating the container");
|
|
305
|
+
this.spec = spec;
|
|
259
306
|
// Created on the default bridge (a container created with `none` cannot join it later).
|
|
260
307
|
this.netOpen = true;
|
|
261
308
|
}
|
|
@@ -263,6 +310,7 @@ export class DockerExecutor {
|
|
|
263
310
|
if (!c.State.Running)
|
|
264
311
|
await this.mustDocker(["start", this.name], "starting the container");
|
|
265
312
|
this.netOpen = "bridge" in (await this.inspectNetworks());
|
|
313
|
+
this.spec = c.Config.Labels?.[SPEC_LABEL];
|
|
266
314
|
}
|
|
267
315
|
this.ready = true;
|
|
268
316
|
}
|
|
@@ -354,6 +402,11 @@ export class DockerExecutor {
|
|
|
354
402
|
let served;
|
|
355
403
|
try {
|
|
356
404
|
served = await this.serial(async () => {
|
|
405
|
+
// The policy or the tier changed the container's flags (shm, cpu, memory): recreate
|
|
406
|
+
// it once nothing runs in it.
|
|
407
|
+
if (this.ready && this.inflight === 0 && this.spec !== this.specHash()) {
|
|
408
|
+
this.ready = false;
|
|
409
|
+
}
|
|
357
410
|
await this.ensureContainer();
|
|
358
411
|
if (w.dead)
|
|
359
412
|
return true;
|
|
@@ -411,7 +464,8 @@ export class DockerExecutor {
|
|
|
411
464
|
if (!ENV_NAME_RE.test(k))
|
|
412
465
|
throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
|
|
413
466
|
}
|
|
414
|
-
|
|
467
|
+
this.lastLimits = args.limits;
|
|
468
|
+
const open = bridgeNetwork(this.opts.policy(), args.limits);
|
|
415
469
|
await this.acquire(open, signal);
|
|
416
470
|
try {
|
|
417
471
|
signal.throwIfAborted();
|
|
@@ -563,7 +617,7 @@ export class DockerExecutor {
|
|
|
563
617
|
/** Runs one file script in the container; `null` for a missing file. */
|
|
564
618
|
async fileOp(script, path, arg2, input) {
|
|
565
619
|
// A file operation does not need the network; it runs on whichever state the container has.
|
|
566
|
-
await this.serial(() => this.ensureContainer());
|
|
620
|
+
await this.serial(() => this.ensureContainer({ anySpec: true }));
|
|
567
621
|
const r = await docker([
|
|
568
622
|
"exec",
|
|
569
623
|
...(input !== undefined ? ["-i"] : []),
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { ChildProcess } from "node:child_process";
|
|
2
|
+
/**
|
|
3
|
+
* The key that marks every process of one device directory's commands (`<dirKey>.<tag>` in the
|
|
4
|
+
* marker variable). Executors of the same directory compute the same key, so either one finds
|
|
5
|
+
* and kills what the other started.
|
|
6
|
+
*/
|
|
7
|
+
export declare function dirKeyOf(realDir: string): string;
|
|
8
|
+
/** Sends `signal` (SIGKILL by default) to a process group; false when the group no longer exists. */
|
|
9
|
+
export declare function killGroupId(pgid: number, signal?: NodeJS.Signals | 0): boolean;
|
|
10
|
+
export declare function pidAlive(pid: number): boolean;
|
|
11
|
+
/**
|
|
12
|
+
* One command's process group. It is tracked after the command's main process exits, as long as
|
|
13
|
+
* the group has members (background children), so killTagged / killAll still reach them.
|
|
14
|
+
*/
|
|
15
|
+
export interface Group {
|
|
16
|
+
tag: string;
|
|
17
|
+
pgid: number;
|
|
18
|
+
/** The leader (the outer shell) has exited and been reaped. */
|
|
19
|
+
exited: boolean;
|
|
20
|
+
/** Called by a kill while the command runs: the result then has `exitCode: null`. */
|
|
21
|
+
onKill?: (() => void) | undefined;
|
|
22
|
+
}
|
|
23
|
+
/** The process groups of one executor's commands (each command leads its own group). */
|
|
24
|
+
export declare class GroupTracker {
|
|
25
|
+
private readonly groups;
|
|
26
|
+
private pruneTimer;
|
|
27
|
+
/** Tracks a spawned command's process group; undefined when it has no pid (spawn failed). */
|
|
28
|
+
track(tag: string, child: ChildProcess): Group | undefined;
|
|
29
|
+
/** Stops tracking a group (its command failed to start). */
|
|
30
|
+
forget(g: Group): void;
|
|
31
|
+
/** Forgets finished groups with no members left (or whose id was taken by another process). */
|
|
32
|
+
prune(): void;
|
|
33
|
+
kill(g: Group): void;
|
|
34
|
+
/** Kills the groups of the given tags. */
|
|
35
|
+
killTags(tags: Iterable<string>): void;
|
|
36
|
+
killAll(): void;
|
|
37
|
+
/** Stops the prune timer (the groups stay known). */
|
|
38
|
+
dispose(): void;
|
|
39
|
+
/** The number of groups tracked (for tests). */
|
|
40
|
+
get size(): number;
|
|
41
|
+
private stopTimerWhenEmpty;
|
|
42
|
+
}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
import { createHash } from "node:crypto";
|
|
2
|
+
/** How often process groups of finished commands are checked for remaining members. */
|
|
3
|
+
const PRUNE_INTERVAL_MS = 5_000;
|
|
4
|
+
/**
|
|
5
|
+
* The key that marks every process of one device directory's commands (`<dirKey>.<tag>` in the
|
|
6
|
+
* marker variable). Executors of the same directory compute the same key, so either one finds
|
|
7
|
+
* and kills what the other started.
|
|
8
|
+
*/
|
|
9
|
+
export function dirKeyOf(realDir) {
|
|
10
|
+
return createHash("sha256").update(realDir).digest("hex").slice(0, 16);
|
|
11
|
+
}
|
|
12
|
+
/** Sends `signal` (SIGKILL by default) to a process group; false when the group no longer exists. */
|
|
13
|
+
export function killGroupId(pgid, signal = "SIGKILL") {
|
|
14
|
+
try {
|
|
15
|
+
process.kill(-pgid, signal);
|
|
16
|
+
return true;
|
|
17
|
+
}
|
|
18
|
+
catch {
|
|
19
|
+
return false;
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
export function pidAlive(pid) {
|
|
23
|
+
try {
|
|
24
|
+
process.kill(pid, 0);
|
|
25
|
+
return true;
|
|
26
|
+
}
|
|
27
|
+
catch {
|
|
28
|
+
return false;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
/** The process groups of one executor's commands (each command leads its own group). */
|
|
32
|
+
export class GroupTracker {
|
|
33
|
+
groups = new Set();
|
|
34
|
+
pruneTimer;
|
|
35
|
+
/** Tracks a spawned command's process group; undefined when it has no pid (spawn failed). */
|
|
36
|
+
track(tag, child) {
|
|
37
|
+
if (child.pid === undefined)
|
|
38
|
+
return undefined;
|
|
39
|
+
const g = { tag, pgid: child.pid, exited: false };
|
|
40
|
+
this.groups.add(g);
|
|
41
|
+
if (this.pruneTimer === undefined) {
|
|
42
|
+
this.pruneTimer = setInterval(() => this.prune(), PRUNE_INTERVAL_MS);
|
|
43
|
+
this.pruneTimer.unref();
|
|
44
|
+
}
|
|
45
|
+
return g;
|
|
46
|
+
}
|
|
47
|
+
/** Stops tracking a group (its command failed to start). */
|
|
48
|
+
forget(g) {
|
|
49
|
+
this.groups.delete(g);
|
|
50
|
+
}
|
|
51
|
+
/** Forgets finished groups with no members left (or whose id was taken by another process). */
|
|
52
|
+
prune() {
|
|
53
|
+
for (const g of this.groups) {
|
|
54
|
+
if (!g.exited)
|
|
55
|
+
continue;
|
|
56
|
+
// A reaped leader's pid can be reused only once its group is gone: a live process with
|
|
57
|
+
// that pid means the id now belongs to someone else.
|
|
58
|
+
if (pidAlive(g.pgid) || !killGroupId(g.pgid, 0))
|
|
59
|
+
this.groups.delete(g);
|
|
60
|
+
}
|
|
61
|
+
this.stopTimerWhenEmpty();
|
|
62
|
+
}
|
|
63
|
+
kill(g) {
|
|
64
|
+
if (g.exited) {
|
|
65
|
+
this.prune();
|
|
66
|
+
if (!this.groups.has(g))
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
g.onKill?.();
|
|
70
|
+
if (!killGroupId(g.pgid) && g.exited)
|
|
71
|
+
this.groups.delete(g);
|
|
72
|
+
}
|
|
73
|
+
/** Kills the groups of the given tags. */
|
|
74
|
+
killTags(tags) {
|
|
75
|
+
const want = new Set(tags);
|
|
76
|
+
for (const g of [...this.groups])
|
|
77
|
+
if (want.has(g.tag))
|
|
78
|
+
this.kill(g);
|
|
79
|
+
}
|
|
80
|
+
killAll() {
|
|
81
|
+
for (const g of [...this.groups])
|
|
82
|
+
this.kill(g);
|
|
83
|
+
}
|
|
84
|
+
/** Stops the prune timer (the groups stay known). */
|
|
85
|
+
dispose() {
|
|
86
|
+
if (this.pruneTimer !== undefined)
|
|
87
|
+
clearInterval(this.pruneTimer);
|
|
88
|
+
this.pruneTimer = undefined;
|
|
89
|
+
}
|
|
90
|
+
/** The number of groups tracked (for tests). */
|
|
91
|
+
get size() {
|
|
92
|
+
return this.groups.size;
|
|
93
|
+
}
|
|
94
|
+
stopTimerWhenEmpty() {
|
|
95
|
+
if (this.groups.size === 0 && this.pruneTimer !== undefined) {
|
|
96
|
+
clearInterval(this.pruneTimer);
|
|
97
|
+
this.pruneTimer = undefined;
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
}
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
import type { DeviceExecArgs, ExecResult, SandboxRoots } from "@capybara-hq/plugin-sdk";
|
|
2
|
+
import type { ExecHooks, Executor } from "./types.js";
|
|
3
|
+
export interface HostExecutorOptions {
|
|
4
|
+
/** The device directory (from login). */
|
|
5
|
+
dir: string;
|
|
6
|
+
/** The environment commands start from (default: this program's own, `process.env`). */
|
|
7
|
+
env?: NodeJS.ProcessEnv;
|
|
8
|
+
}
|
|
9
|
+
/**
|
|
10
|
+
* Runs commands without a sandbox (spec §5.4): `/bin/bash -c` directly on this machine as the
|
|
11
|
+
* user, with this program's own environment plus the request's, so commands see the real `HOME`,
|
|
12
|
+
* `PATH`, credentials, Docker and network. Only the device owner turns it on, locally
|
|
13
|
+
* (`isolation: "none"` with tier `open`, OS mode); the program picks this executor per command
|
|
14
|
+
* (see `exec/switch.ts`).
|
|
15
|
+
*
|
|
16
|
+
* What stays the same as the OS sandbox: the working directory is checked inside the device's
|
|
17
|
+
* roots, file operations are confined to the roots (direct host IO), and every command leads its
|
|
18
|
+
* own process group and carries {@link EXEC_MARKER}, so timeouts, aborts, `killTagged` and
|
|
19
|
+
* `killAll` reach it and what it leaves running.
|
|
20
|
+
*/
|
|
21
|
+
export declare class HostExecutor implements Executor {
|
|
22
|
+
private readonly opts;
|
|
23
|
+
readonly mode: "os";
|
|
24
|
+
readonly roots: SandboxRoots;
|
|
25
|
+
private readonly dir;
|
|
26
|
+
/** Marks every process of this device's commands: `<dirKey>.<tag>` (as the OS executor). */
|
|
27
|
+
private readonly dirKey;
|
|
28
|
+
private readonly groups;
|
|
29
|
+
private readonly guard;
|
|
30
|
+
private readonly files;
|
|
31
|
+
constructor(opts: HostExecutorOptions);
|
|
32
|
+
ensureRoot(): Promise<"ok" | "gone">;
|
|
33
|
+
/** The marker value of a tag's processes. */
|
|
34
|
+
markerOf(tag: string): string;
|
|
35
|
+
/** The command's environment: this program's, the request's, then the marker. */
|
|
36
|
+
private envFor;
|
|
37
|
+
exec(args: DeviceExecArgs, signal: AbortSignal, hooks?: ExecHooks): Promise<ExecResult>;
|
|
38
|
+
readFile(path: string, maxBytes: number): Promise<{
|
|
39
|
+
data: Uint8Array;
|
|
40
|
+
truncated: boolean;
|
|
41
|
+
} | null>;
|
|
42
|
+
writeFile(path: string, data: Uint8Array): Promise<void>;
|
|
43
|
+
stat(path: string): Promise<{
|
|
44
|
+
size: number;
|
|
45
|
+
isDir: boolean;
|
|
46
|
+
} | null>;
|
|
47
|
+
killTagged(tags: string[]): Promise<void>;
|
|
48
|
+
killAll(): Promise<void>;
|
|
49
|
+
/** Kills every process carrying this device's marker (also a previous run's). */
|
|
50
|
+
killLeftovers(): Promise<void>;
|
|
51
|
+
/** Kills every running command and stops tracking. */
|
|
52
|
+
dispose(): Promise<void>;
|
|
53
|
+
}
|
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
import { spawn } from "node:child_process";
|
|
2
|
+
import { existsSync, realpathSync } from "node:fs";
|
|
3
|
+
import { constants as osConstants } from "node:os";
|
|
4
|
+
import { resolve } from "node:path";
|
|
5
|
+
import { dirKeyOf, GroupTracker } from "./groups.js";
|
|
6
|
+
import { EXEC_MARKER, killMarked } from "./procs.js";
|
|
7
|
+
import { ENV_NAME_RE, HostFiles, OutputCap, osRoots, PIPE_GRACE_MS, policyError, RootGuard, } from "./shared.js";
|
|
8
|
+
/**
|
|
9
|
+
* Runs commands without a sandbox (spec §5.4): `/bin/bash -c` directly on this machine as the
|
|
10
|
+
* user, with this program's own environment plus the request's, so commands see the real `HOME`,
|
|
11
|
+
* `PATH`, credentials, Docker and network. Only the device owner turns it on, locally
|
|
12
|
+
* (`isolation: "none"` with tier `open`, OS mode); the program picks this executor per command
|
|
13
|
+
* (see `exec/switch.ts`).
|
|
14
|
+
*
|
|
15
|
+
* What stays the same as the OS sandbox: the working directory is checked inside the device's
|
|
16
|
+
* roots, file operations are confined to the roots (direct host IO), and every command leads its
|
|
17
|
+
* own process group and carries {@link EXEC_MARKER}, so timeouts, aborts, `killTagged` and
|
|
18
|
+
* `killAll` reach it and what it leaves running.
|
|
19
|
+
*/
|
|
20
|
+
export class HostExecutor {
|
|
21
|
+
opts;
|
|
22
|
+
mode = "os";
|
|
23
|
+
roots;
|
|
24
|
+
dir;
|
|
25
|
+
/** Marks every process of this device's commands: `<dirKey>.<tag>` (as the OS executor). */
|
|
26
|
+
dirKey;
|
|
27
|
+
groups = new GroupTracker();
|
|
28
|
+
guard;
|
|
29
|
+
files;
|
|
30
|
+
constructor(opts) {
|
|
31
|
+
this.opts = opts;
|
|
32
|
+
const dir = resolve(opts.dir);
|
|
33
|
+
this.dir = existsSync(dir) ? realpathSync(dir) : dir;
|
|
34
|
+
this.roots = osRoots(this.dir);
|
|
35
|
+
this.guard = new RootGuard(this.dir, this.roots);
|
|
36
|
+
this.files = new HostFiles(this.roots);
|
|
37
|
+
this.dirKey = dirKeyOf(this.dir);
|
|
38
|
+
}
|
|
39
|
+
async ensureRoot() {
|
|
40
|
+
return this.guard.ensure();
|
|
41
|
+
}
|
|
42
|
+
/** The marker value of a tag's processes. */
|
|
43
|
+
markerOf(tag) {
|
|
44
|
+
return `${this.dirKey}.${tag}`;
|
|
45
|
+
}
|
|
46
|
+
/** The command's environment: this program's, the request's, then the marker. */
|
|
47
|
+
envFor(args) {
|
|
48
|
+
const env = {};
|
|
49
|
+
for (const [k, v] of Object.entries(this.opts.env ?? process.env)) {
|
|
50
|
+
if (v !== undefined)
|
|
51
|
+
env[k] = v;
|
|
52
|
+
}
|
|
53
|
+
for (const [k, v] of Object.entries(args.env ?? {})) {
|
|
54
|
+
if (!ENV_NAME_RE.test(k))
|
|
55
|
+
throw policyError(`invalid environment variable name ${JSON.stringify(k)}`);
|
|
56
|
+
env[k] = v;
|
|
57
|
+
}
|
|
58
|
+
env[EXEC_MARKER] = this.markerOf(args.tag);
|
|
59
|
+
return env;
|
|
60
|
+
}
|
|
61
|
+
async exec(args, signal, hooks) {
|
|
62
|
+
signal.throwIfAborted();
|
|
63
|
+
const cwd = await this.files.inside(args.cwd ?? this.roots.workspace, "cwd");
|
|
64
|
+
const env = this.envFor(args);
|
|
65
|
+
// The kernel may have cancelled while the cwd was checked.
|
|
66
|
+
signal.throwIfAborted();
|
|
67
|
+
// The sandbox may have been turned back on meanwhile: judged again with no await before the
|
|
68
|
+
// spawn, so a kill of every unsandboxed command never misses this one.
|
|
69
|
+
hooks?.beforeSpawn?.();
|
|
70
|
+
// detached: the command leads its own process group, so a kill reaches its children too.
|
|
71
|
+
const child = spawn("/bin/bash", ["-c", args.command], {
|
|
72
|
+
cwd,
|
|
73
|
+
env,
|
|
74
|
+
detached: true,
|
|
75
|
+
stdio: ["ignore", "pipe", "pipe"],
|
|
76
|
+
});
|
|
77
|
+
return new Promise((resolvePromise, reject) => {
|
|
78
|
+
const cap = new OutputCap(args.maxOutputBytes);
|
|
79
|
+
let timedOut = false;
|
|
80
|
+
let killed = false;
|
|
81
|
+
let exit;
|
|
82
|
+
let settled = false;
|
|
83
|
+
let grace;
|
|
84
|
+
const group = this.groups.track(args.tag, child);
|
|
85
|
+
if (group) {
|
|
86
|
+
group.onKill = () => {
|
|
87
|
+
// A kill after a clean exit (a background child) leaves the result alone.
|
|
88
|
+
if (exit === undefined)
|
|
89
|
+
killed = true;
|
|
90
|
+
};
|
|
91
|
+
}
|
|
92
|
+
const kill = () => {
|
|
93
|
+
if (group)
|
|
94
|
+
this.groups.kill(group);
|
|
95
|
+
};
|
|
96
|
+
const timer = setTimeout(() => {
|
|
97
|
+
if (exit === undefined)
|
|
98
|
+
timedOut = true;
|
|
99
|
+
kill();
|
|
100
|
+
}, args.timeoutMs);
|
|
101
|
+
const onAbort = () => kill();
|
|
102
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
103
|
+
const cleanup = () => {
|
|
104
|
+
clearTimeout(timer);
|
|
105
|
+
if (grace)
|
|
106
|
+
clearTimeout(grace);
|
|
107
|
+
signal.removeEventListener("abort", onAbort);
|
|
108
|
+
if (group) {
|
|
109
|
+
group.exited = true;
|
|
110
|
+
group.onKill = undefined;
|
|
111
|
+
}
|
|
112
|
+
};
|
|
113
|
+
const finish = () => {
|
|
114
|
+
if (settled || exit === undefined)
|
|
115
|
+
return;
|
|
116
|
+
settled = true;
|
|
117
|
+
cleanup();
|
|
118
|
+
child.stdout?.destroy();
|
|
119
|
+
child.stderr?.destroy();
|
|
120
|
+
let exitCode = exit.code;
|
|
121
|
+
if (killed || timedOut)
|
|
122
|
+
exitCode = null;
|
|
123
|
+
else if (exitCode === null && exit.sig !== null) {
|
|
124
|
+
exitCode = 128 + (osConstants.signals[exit.sig] ?? 0);
|
|
125
|
+
}
|
|
126
|
+
resolvePromise({
|
|
127
|
+
exitCode,
|
|
128
|
+
stdout: cap.text("stdout"),
|
|
129
|
+
stderr: cap.text("stderr"),
|
|
130
|
+
truncated: cap.truncated,
|
|
131
|
+
timedOut,
|
|
132
|
+
});
|
|
133
|
+
};
|
|
134
|
+
child.stdout?.on("data", (b) => cap.push("stdout", b));
|
|
135
|
+
child.stderr?.on("data", (b) => cap.push("stderr", b));
|
|
136
|
+
child.once("error", (e) => {
|
|
137
|
+
if (settled)
|
|
138
|
+
return;
|
|
139
|
+
settled = true;
|
|
140
|
+
if (group)
|
|
141
|
+
this.groups.forget(group);
|
|
142
|
+
cleanup();
|
|
143
|
+
reject(e);
|
|
144
|
+
});
|
|
145
|
+
child.once("exit", (code, sig) => {
|
|
146
|
+
exit = { code, sig };
|
|
147
|
+
if (group)
|
|
148
|
+
group.exited = true;
|
|
149
|
+
// A background child may hold the pipes open; do not wait for it past a short grace.
|
|
150
|
+
grace = setTimeout(finish, PIPE_GRACE_MS);
|
|
151
|
+
});
|
|
152
|
+
child.once("close", () => finish());
|
|
153
|
+
});
|
|
154
|
+
}
|
|
155
|
+
async readFile(path, maxBytes) {
|
|
156
|
+
return this.files.read(path, maxBytes);
|
|
157
|
+
}
|
|
158
|
+
async writeFile(path, data) {
|
|
159
|
+
await this.files.write(path, data);
|
|
160
|
+
}
|
|
161
|
+
async stat(path) {
|
|
162
|
+
return this.files.stat(path);
|
|
163
|
+
}
|
|
164
|
+
async killTagged(tags) {
|
|
165
|
+
this.groups.killTags(tags);
|
|
166
|
+
const values = new Set(tags.map((t) => this.markerOf(t)));
|
|
167
|
+
await killMarked((v) => values.has(v));
|
|
168
|
+
}
|
|
169
|
+
async killAll() {
|
|
170
|
+
this.groups.killAll();
|
|
171
|
+
await this.killLeftovers();
|
|
172
|
+
}
|
|
173
|
+
/** Kills every process carrying this device's marker (also a previous run's). */
|
|
174
|
+
async killLeftovers() {
|
|
175
|
+
const prefix = `${this.dirKey}.`;
|
|
176
|
+
await killMarked((v) => v.startsWith(prefix));
|
|
177
|
+
}
|
|
178
|
+
/** Kills every running command and stops tracking. */
|
|
179
|
+
async dispose() {
|
|
180
|
+
await this.killAll();
|
|
181
|
+
this.groups.dispose();
|
|
182
|
+
}
|
|
183
|
+
}
|