@capybara-hq/device 0.1.0-rc.10 → 0.1.0-rc.11
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 +43 -25
- package/dist/cli.d.ts +13 -2
- package/dist/cli.js +25 -4
- package/dist/client.d.ts +5 -3
- package/dist/client.js +7 -7
- package/dist/commands/drain.d.ts +3 -3
- package/dist/commands/drain.js +5 -4
- package/dist/commands/login.d.ts +3 -0
- package/dist/commands/login.js +33 -5
- package/dist/commands/logout.d.ts +2 -0
- package/dist/commands/logout.js +1 -1
- package/dist/commands/mode.d.ts +23 -6
- package/dist/commands/mode.js +24 -3
- package/dist/commands/service.d.ts +11 -4
- package/dist/commands/service.js +122 -65
- package/dist/commands/signal.d.ts +6 -2
- package/dist/commands/signal.js +7 -4
- package/dist/commands/start.d.ts +4 -0
- package/dist/commands/start.js +12 -5
- package/dist/commands/stop.d.ts +18 -7
- package/dist/commands/stop.js +20 -8
- package/dist/exec/switch.d.ts +10 -3
- package/dist/exec/switch.js +15 -4
- package/dist/pid.d.ts +33 -4
- package/dist/pid.js +91 -35
- package/dist/server-ops.d.ts +5 -3
- package/dist/server-ops.js +6 -4
- package/dist/service/launchd.d.ts +9 -6
- package/dist/service/launchd.js +22 -7
- package/dist/service/manager.d.ts +41 -0
- package/dist/service/manager.js +91 -0
- package/dist/service/systemd.d.ts +2 -0
- package/dist/service/systemd.js +8 -0
- package/package.json +1 -1
package/dist/commands/service.js
CHANGED
|
@@ -1,14 +1,11 @@
|
|
|
1
|
-
import { execFileSync } from "node:child_process";
|
|
2
1
|
import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
|
|
3
|
-
import { dirname } from "node:path";
|
|
2
|
+
import { dirname, join } from "node:path";
|
|
4
3
|
import { fileURLToPath } from "node:url";
|
|
5
4
|
import { readRunning } from "../pid.js";
|
|
6
|
-
import {
|
|
5
|
+
import { hasLoginService } from "../service/installed.js";
|
|
6
|
+
import { plistContent, plistPath } from "../service/launchd.js";
|
|
7
|
+
import { defaultRunSystem, launchdTarget, managerState, packageVersionAt, serviceBinPath, } from "../service/manager.js";
|
|
7
8
|
import { SYSTEMD_UNIT, unitContent, unitPath } from "../service/systemd.js";
|
|
8
|
-
import { PROGRAM_VERSION } from "../version.js";
|
|
9
|
-
function defaultRun(cmd, args) {
|
|
10
|
-
execFileSync(cmd, args, { stdio: "pipe" });
|
|
11
|
-
}
|
|
12
9
|
/** The bin script next to this package's `dist` (or `src`) directory. */
|
|
13
10
|
function defaultBinPath() {
|
|
14
11
|
return fileURLToPath(new URL("../../bin/capybara-device.mjs", import.meta.url));
|
|
@@ -27,6 +24,8 @@ export function serviceEnv(env) {
|
|
|
27
24
|
export const SERVICE_POLL_MS = 200;
|
|
28
25
|
/** How long install / uninstall wait for `launchctl bootout` to finish (it is asynchronous). */
|
|
29
26
|
export const SERVICE_GONE_TIMEOUT_MS = 10_000;
|
|
27
|
+
/** How long `service start|restart` wait for the program to be running. */
|
|
28
|
+
export const SERVICE_UP_TIMEOUT_MS = 10_000;
|
|
30
29
|
/** The waits before each retry of a `launchctl bootstrap` that failed with error 5. */
|
|
31
30
|
export const BOOTSTRAP_BACKOFF_MS = [500, 1000, 2000];
|
|
32
31
|
/**
|
|
@@ -34,7 +33,7 @@ export const BOOTSTRAP_BACKOFF_MS = [500, 1000, 2000];
|
|
|
34
33
|
* (systemd user), removes it, or reports whether it is loaded and running.
|
|
35
34
|
*/
|
|
36
35
|
export async function serviceCommand(action, deps) {
|
|
37
|
-
const run = deps.run ??
|
|
36
|
+
const run = deps.run ?? defaultRunSystem;
|
|
38
37
|
const spec = {
|
|
39
38
|
nodePath: deps.nodePath ?? process.execPath,
|
|
40
39
|
binPath: deps.binPath ?? defaultBinPath(),
|
|
@@ -45,7 +44,7 @@ export async function serviceCommand(action, deps) {
|
|
|
45
44
|
if (deps.platform === "darwin")
|
|
46
45
|
return await launchd(action, spec, deps, run);
|
|
47
46
|
if (deps.platform === "linux")
|
|
48
|
-
return systemd(action, spec, deps, run);
|
|
47
|
+
return await systemd(action, spec, deps, run);
|
|
49
48
|
}
|
|
50
49
|
catch (e) {
|
|
51
50
|
deps.err(`capybara-device service ${action} failed: ${e instanceof Error ? e.message : String(e)}`);
|
|
@@ -67,30 +66,85 @@ function failureText(e) {
|
|
|
67
66
|
function isBootstrapIoError(e) {
|
|
68
67
|
return e.status === 5 || /Bootstrap failed: 5:/.test(failureText(e));
|
|
69
68
|
}
|
|
69
|
+
/** The pid file's program, checked to be this program (never trusted on the file alone). */
|
|
70
|
+
function running(deps) {
|
|
71
|
+
return readRunning(deps.stateDir, {
|
|
72
|
+
...(deps.kill && { kill: deps.kill }),
|
|
73
|
+
...(deps.ps && { ps: deps.ps }),
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
function where(deps) {
|
|
77
|
+
return {
|
|
78
|
+
home: deps.home,
|
|
79
|
+
platform: deps.platform,
|
|
80
|
+
...(deps.uid !== undefined && { uid: deps.uid }),
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
const NOT_INSTALLED = "capybara-device service is not installed. Install it: capybara-device service install";
|
|
70
84
|
/**
|
|
71
|
-
* One status report
|
|
72
|
-
*
|
|
85
|
+
* One status report, in four shapes: not installed; installed but not loaded; loaded but the
|
|
86
|
+
* program is not running (it exited: the reason is in service.log); running, with its pid and
|
|
87
|
+
* version, plus a restart line when the package the service file runs is a different version (a
|
|
88
|
+
* stale daemon after an upgrade). Exit code 0 only when running.
|
|
73
89
|
*/
|
|
74
|
-
function reportStatus(deps,
|
|
75
|
-
|
|
76
|
-
|
|
90
|
+
function reportStatus(deps, run) {
|
|
91
|
+
const at = where(deps);
|
|
92
|
+
if (!hasLoginService(at.home, at.platform)) {
|
|
93
|
+
deps.out(NOT_INSTALLED);
|
|
94
|
+
return 1;
|
|
95
|
+
}
|
|
96
|
+
const state = managerState(at, run);
|
|
97
|
+
if (!state.loaded) {
|
|
98
|
+
deps.out("capybara-device service is installed but not loaded. Start it: capybara-device service start");
|
|
77
99
|
return 1;
|
|
78
100
|
}
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
101
|
+
if (state.pid === undefined) {
|
|
102
|
+
deps.out("capybara-device service is loaded, but the program is not running: it exited. The reason " +
|
|
103
|
+
`is at the end of ${join(deps.stateDir, "service.log")}; once it is fixed: ` +
|
|
104
|
+
"capybara-device service restart");
|
|
82
105
|
return 1;
|
|
83
106
|
}
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
107
|
+
const program = running(deps);
|
|
108
|
+
const version = program?.pid === state.pid ? program.version : undefined;
|
|
109
|
+
deps.out(`capybara-device service is loaded; running (pid ${state.pid}, ${version ?? "version unknown"}).`);
|
|
110
|
+
const bin = serviceBinPath(at);
|
|
111
|
+
const installed = bin === undefined ? undefined : packageVersionAt(bin);
|
|
112
|
+
if (installed !== undefined && version !== installed) {
|
|
113
|
+
deps.out(`installed ${installed} — restart it: capybara-device service restart`);
|
|
87
114
|
}
|
|
88
115
|
return 0;
|
|
89
116
|
}
|
|
117
|
+
/**
|
|
118
|
+
* Refuses to start the service while a program started outside it runs (`capybara-device start`
|
|
119
|
+
* in a terminal): two programs would fight over the one connection of this device.
|
|
120
|
+
*/
|
|
121
|
+
function foregroundRunning(deps, state) {
|
|
122
|
+
const program = running(deps);
|
|
123
|
+
if (program === undefined || program.pid === state.pid)
|
|
124
|
+
return false;
|
|
125
|
+
deps.err(`capybara-device is already running outside the service (pid ${program.pid}). Stop it first: capybara-device stop`);
|
|
126
|
+
return true;
|
|
127
|
+
}
|
|
128
|
+
/** Waits until the service manager runs the program (a pid other than `previous`). */
|
|
129
|
+
async function cameUp(deps, run, sleep, previous) {
|
|
130
|
+
for (let waited = 0;; waited += SERVICE_POLL_MS) {
|
|
131
|
+
const pid = managerState(where(deps), run).pid;
|
|
132
|
+
if (pid !== undefined && pid !== previous)
|
|
133
|
+
return true;
|
|
134
|
+
if (waited >= SERVICE_UP_TIMEOUT_MS)
|
|
135
|
+
return false;
|
|
136
|
+
await sleep(SERVICE_POLL_MS);
|
|
137
|
+
}
|
|
138
|
+
}
|
|
139
|
+
/** The failure of a start or restart whose program is not running afterwards. */
|
|
140
|
+
function didNotComeBack(deps, action) {
|
|
141
|
+
deps.err(`capybara-device service ${action} failed: the program is not running. The reason is at the ` +
|
|
142
|
+
`end of ${join(deps.stateDir, "service.log")}.`);
|
|
143
|
+
return 1;
|
|
144
|
+
}
|
|
90
145
|
async function launchd(action, spec, deps, run) {
|
|
91
146
|
const file = plistPath(deps.home);
|
|
92
|
-
const domain =
|
|
93
|
-
const service = `${domain}/${LAUNCHD_LABEL}`;
|
|
147
|
+
const { domain, service } = launchdTarget(deps.uid);
|
|
94
148
|
const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
|
|
95
149
|
const tryRun = (args) => {
|
|
96
150
|
try {
|
|
@@ -101,15 +155,7 @@ async function launchd(action, spec, deps, run) {
|
|
|
101
155
|
}
|
|
102
156
|
};
|
|
103
157
|
/** Whether launchd still knows the service (`launchctl print` fails once it is gone). */
|
|
104
|
-
const loaded = () =>
|
|
105
|
-
try {
|
|
106
|
-
run("launchctl", ["print", service]);
|
|
107
|
-
return true;
|
|
108
|
-
}
|
|
109
|
-
catch {
|
|
110
|
-
return false;
|
|
111
|
-
}
|
|
112
|
-
};
|
|
158
|
+
const loaded = () => managerState(where(deps), run).loaded;
|
|
113
159
|
/** Boots the service out and waits until launchd has let it go (bootout returns before that). */
|
|
114
160
|
const bootout = async () => {
|
|
115
161
|
tryRun(["bootout", service]);
|
|
@@ -142,27 +188,31 @@ async function launchd(action, spec, deps, run) {
|
|
|
142
188
|
}
|
|
143
189
|
}
|
|
144
190
|
};
|
|
145
|
-
const installed = () =>
|
|
146
|
-
if (action === "status")
|
|
147
|
-
return reportStatus(deps,
|
|
148
|
-
}
|
|
191
|
+
const installed = () => hasLoginService(deps.home, "darwin");
|
|
192
|
+
if (action === "status")
|
|
193
|
+
return reportStatus(deps, run);
|
|
149
194
|
if (action === "start" || action === "restart") {
|
|
150
195
|
if (!installed()) {
|
|
151
|
-
deps.err(
|
|
196
|
+
deps.err(NOT_INSTALLED);
|
|
152
197
|
return 1;
|
|
153
198
|
}
|
|
154
|
-
|
|
199
|
+
const state = managerState(where(deps), run);
|
|
200
|
+
if (action === "start" && state.pid !== undefined) {
|
|
155
201
|
deps.out("The capybara-device login service is already running.");
|
|
156
202
|
return 0;
|
|
157
203
|
}
|
|
158
|
-
if (
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
204
|
+
if (foregroundRunning(deps, state))
|
|
205
|
+
return 1;
|
|
206
|
+
if (state.loaded) {
|
|
207
|
+
// Loaded: run the program again from the plist's bin (a newer package takes effect); a
|
|
208
|
+
// loaded service whose program exited is started without a kill.
|
|
209
|
+
run("launchctl", state.pid === undefined ? ["kickstart", service] : ["kickstart", "-k", service]);
|
|
163
210
|
}
|
|
164
|
-
if (!(await bootstrap()))
|
|
211
|
+
else if (!(await bootstrap())) {
|
|
165
212
|
return 1;
|
|
213
|
+
}
|
|
214
|
+
if (!(await cameUp(deps, run, sleep, state.pid)))
|
|
215
|
+
return didNotComeBack(deps, action);
|
|
166
216
|
deps.out(action === "restart"
|
|
167
217
|
? "Restarted the capybara-device login service."
|
|
168
218
|
: "Started the capybara-device login service.");
|
|
@@ -170,15 +220,19 @@ async function launchd(action, spec, deps, run) {
|
|
|
170
220
|
}
|
|
171
221
|
if (action === "stop") {
|
|
172
222
|
if (!installed()) {
|
|
173
|
-
deps.err(
|
|
223
|
+
deps.err(NOT_INSTALLED);
|
|
174
224
|
return 1;
|
|
175
225
|
}
|
|
176
226
|
if (!loaded()) {
|
|
177
227
|
deps.out("The capybara-device login service is not running.");
|
|
178
228
|
return 0;
|
|
179
229
|
}
|
|
180
|
-
// Unload, never a signal: KeepAlive would start a
|
|
230
|
+
// Unload, never a signal: KeepAlive would start a program that exits non-zero straight back.
|
|
181
231
|
await bootout();
|
|
232
|
+
if (loaded()) {
|
|
233
|
+
deps.err(`capybara-device service stop failed: launchd still has the service loaded. Check with: launchctl print ${service}`);
|
|
234
|
+
return 1;
|
|
235
|
+
}
|
|
182
236
|
deps.out("Stopped the capybara-device login service; running commands ended. It starts again at the next login or with: capybara-device service start");
|
|
183
237
|
return 0;
|
|
184
238
|
}
|
|
@@ -198,40 +252,43 @@ async function launchd(action, spec, deps, run) {
|
|
|
198
252
|
deps.out("Removed the capybara-device login service.");
|
|
199
253
|
return 0;
|
|
200
254
|
}
|
|
201
|
-
function systemd(action, spec, deps, run) {
|
|
255
|
+
async function systemd(action, spec, deps, run) {
|
|
202
256
|
const file = unitPath(deps.home);
|
|
203
|
-
const
|
|
204
|
-
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
catch {
|
|
209
|
-
return false;
|
|
210
|
-
}
|
|
211
|
-
};
|
|
212
|
-
const installed = () => existsSync(file);
|
|
213
|
-
if (action === "status") {
|
|
214
|
-
return reportStatus(deps, { installed: installed(), loaded: active() }, PROGRAM_VERSION);
|
|
215
|
-
}
|
|
257
|
+
const sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
|
|
258
|
+
const active = () => managerState(where(deps), run).loaded;
|
|
259
|
+
const installed = () => hasLoginService(deps.home, "linux");
|
|
260
|
+
if (action === "status")
|
|
261
|
+
return reportStatus(deps, run);
|
|
216
262
|
if (action === "start" || action === "stop" || action === "restart") {
|
|
217
263
|
if (!installed()) {
|
|
218
|
-
deps.err(
|
|
264
|
+
deps.err(NOT_INSTALLED);
|
|
219
265
|
return 1;
|
|
220
266
|
}
|
|
221
|
-
|
|
267
|
+
const state = managerState(where(deps), run);
|
|
268
|
+
if (action === "start" && state.loaded) {
|
|
222
269
|
deps.out("The capybara-device login service is already running.");
|
|
223
270
|
return 0;
|
|
224
271
|
}
|
|
225
|
-
if (action === "stop" && !
|
|
272
|
+
if (action === "stop" && !state.loaded) {
|
|
226
273
|
deps.out("The capybara-device login service is not running.");
|
|
227
274
|
return 0;
|
|
228
275
|
}
|
|
276
|
+
if (action !== "stop" && !state.loaded && foregroundRunning(deps, state))
|
|
277
|
+
return 1;
|
|
229
278
|
run("systemctl", ["--user", action, SYSTEMD_UNIT]);
|
|
279
|
+
if (action === "stop") {
|
|
280
|
+
if (active()) {
|
|
281
|
+
deps.err(`capybara-device service stop failed: the unit is still active. Check with: systemctl --user status ${SYSTEMD_UNIT}`);
|
|
282
|
+
return 1;
|
|
283
|
+
}
|
|
284
|
+
deps.out("Stopped the capybara-device login service; running commands ended. It starts again at the next login or with: capybara-device service start");
|
|
285
|
+
return 0;
|
|
286
|
+
}
|
|
287
|
+
if (!(await cameUp(deps, run, sleep, state.pid)))
|
|
288
|
+
return didNotComeBack(deps, action);
|
|
230
289
|
deps.out(action === "start"
|
|
231
290
|
? "Started the capybara-device login service."
|
|
232
|
-
:
|
|
233
|
-
? "Restarted the capybara-device login service."
|
|
234
|
-
: "Stopped the capybara-device login service; running commands ended. It starts again at the next login or with: capybara-device service start");
|
|
291
|
+
: "Restarted the capybara-device login service.");
|
|
235
292
|
return 0;
|
|
236
293
|
}
|
|
237
294
|
if (action === "install") {
|
|
@@ -1,2 +1,6 @@
|
|
|
1
|
-
|
|
2
|
-
|
|
1
|
+
import { type ProcessChecks } from "../pid.js";
|
|
2
|
+
/**
|
|
3
|
+
* Sends `signal` to the running program; exit code 0 when it was signalled, 1 when none runs. A
|
|
4
|
+
* pid the file names but that is not this program any more is never signalled.
|
|
5
|
+
*/
|
|
6
|
+
export declare function signalRunning(stateDir: string, signal: NodeJS.Signals, message: string, out: (line: string) => void, err: (line: string) => void, checks?: ProcessChecks): number;
|
package/dist/commands/signal.js
CHANGED
|
@@ -1,13 +1,16 @@
|
|
|
1
1
|
import { readRunningPid } from "../pid.js";
|
|
2
|
-
/**
|
|
3
|
-
|
|
4
|
-
|
|
2
|
+
/**
|
|
3
|
+
* Sends `signal` to the running program; exit code 0 when it was signalled, 1 when none runs. A
|
|
4
|
+
* pid the file names but that is not this program any more is never signalled.
|
|
5
|
+
*/
|
|
6
|
+
export function signalRunning(stateDir, signal, message, out, err, checks = {}) {
|
|
7
|
+
const pid = readRunningPid(stateDir, checks);
|
|
5
8
|
if (pid === undefined) {
|
|
6
9
|
err("capybara-device is not running.");
|
|
7
10
|
return 1;
|
|
8
11
|
}
|
|
9
12
|
try {
|
|
10
|
-
kill(pid, signal);
|
|
13
|
+
(checks.kill ?? process.kill)(pid, signal);
|
|
11
14
|
}
|
|
12
15
|
catch (e) {
|
|
13
16
|
err(`Could not signal pid ${pid}: ${e.message}`);
|
package/dist/commands/start.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { connect } from "../client.js";
|
|
2
2
|
import type { Executor } from "../exec/types.js";
|
|
3
|
+
import { type ProcessLookup } from "../pid.js";
|
|
3
4
|
import { PolicyStore } from "../policy-store.js";
|
|
4
5
|
import { type Credential } from "../state.js";
|
|
5
6
|
export interface StartDeps {
|
|
@@ -19,6 +20,9 @@ export interface StartDeps {
|
|
|
19
20
|
/** The process whose signals stop and drain the program. */
|
|
20
21
|
proc?: Pick<NodeJS.Process, "on" | "off" | "pid">;
|
|
21
22
|
kill?: typeof process.kill;
|
|
23
|
+
ps?: ProcessLookup;
|
|
24
|
+
/** The environment (default: process.env): tells whether the service manager started this. */
|
|
25
|
+
env?: Record<string, string | undefined>;
|
|
22
26
|
connect?: typeof connect;
|
|
23
27
|
}
|
|
24
28
|
/** Printed once when policy.json was written before auto mode (spec §4.4). */
|
package/dist/commands/start.js
CHANGED
|
@@ -6,6 +6,7 @@ import { readRunningPid, removePid, writePid } from "../pid.js";
|
|
|
6
6
|
import { PolicyStore } from "../policy-store.js";
|
|
7
7
|
import { hasLoginService } from "../service/installed.js";
|
|
8
8
|
import { rotateServiceLog } from "../service/launchd.js";
|
|
9
|
+
import { startedByServiceManager } from "../service/manager.js";
|
|
9
10
|
import { readCredential } from "../state.js";
|
|
10
11
|
import { PROGRAM_VERSION } from "../version.js";
|
|
11
12
|
/** Printed once when policy.json was written before auto mode (spec §4.4). */
|
|
@@ -26,7 +27,9 @@ export async function start(deps) {
|
|
|
26
27
|
return 1;
|
|
27
28
|
}
|
|
28
29
|
if (cred === undefined) {
|
|
29
|
-
//
|
|
30
|
+
// A deliberate stop: exit 0, which the service manager does not restart (launchd
|
|
31
|
+
// `KeepAlive { SuccessfulExit: false }`, systemd `Restart=on-failure`) until someone logs in
|
|
32
|
+
// and starts it.
|
|
30
33
|
err("Not logged in. Run capybara-device login --url <url> first.");
|
|
31
34
|
return 0;
|
|
32
35
|
}
|
|
@@ -35,13 +38,17 @@ export async function start(deps) {
|
|
|
35
38
|
return 1;
|
|
36
39
|
}
|
|
37
40
|
const where = deps.service ?? { home: homedir(), platform: process.platform };
|
|
38
|
-
if (hasLoginService(where.home, where.platform)
|
|
39
|
-
|
|
40
|
-
//
|
|
41
|
+
if (hasLoginService(where.home, where.platform) &&
|
|
42
|
+
!startedByServiceManager(deps.env ?? process.env, proc.pid)) {
|
|
43
|
+
// Started in a terminal while a service is installed: say how to control the installed one.
|
|
44
|
+
// The service manager runs exactly this command, so it must keep working, without the hint.
|
|
41
45
|
out("capybara-device runs as a login service on this machine. Restart it with: capybara-device service restart");
|
|
42
46
|
}
|
|
43
47
|
rotateServiceLog(stateDir);
|
|
44
|
-
const running = readRunningPid(stateDir,
|
|
48
|
+
const running = readRunningPid(stateDir, {
|
|
49
|
+
...(deps.kill && { kill: deps.kill }),
|
|
50
|
+
...(deps.ps && { ps: deps.ps }),
|
|
51
|
+
});
|
|
45
52
|
if (running !== undefined && running !== proc.pid) {
|
|
46
53
|
err(`capybara-device is already running (pid ${running}). Stop it first: capybara-device stop`);
|
|
47
54
|
return 1;
|
package/dist/commands/stop.d.ts
CHANGED
|
@@ -1,9 +1,20 @@
|
|
|
1
|
+
import { type ProcessChecks } from "../pid.js";
|
|
2
|
+
import { type RunSystem } from "../service/manager.js";
|
|
3
|
+
export interface StopOptions extends ProcessChecks {
|
|
4
|
+
/** Where the login service would be installed, and on which platform (default: this machine). */
|
|
5
|
+
service?: {
|
|
6
|
+
home: string;
|
|
7
|
+
platform: NodeJS.Platform;
|
|
8
|
+
uid?: number;
|
|
9
|
+
};
|
|
10
|
+
/** Asks the service manager (default: execFileSync). */
|
|
11
|
+
run?: RunSystem;
|
|
12
|
+
}
|
|
1
13
|
/**
|
|
2
|
-
* `stop`: SIGTERM to the running program.
|
|
3
|
-
*
|
|
4
|
-
*
|
|
14
|
+
* `stop`: SIGTERM to the running program. When the service manager runs that program (launchd has
|
|
15
|
+
* the service loaded, systemd has the unit active, and its pid is the running one), `stop` refuses
|
|
16
|
+
* and points at `service stop`, which unloads the service: a signalled service program would be
|
|
17
|
+
* started again by the restart policy, or would leave a service that looks loaded but stays down.
|
|
18
|
+
* A program started in a terminal is signalled as before, with or without a service installed.
|
|
5
19
|
*/
|
|
6
|
-
export declare function stop(stateDir: string, out: (line: string) => void, err: (line: string) => void,
|
|
7
|
-
home: string;
|
|
8
|
-
platform: NodeJS.Platform;
|
|
9
|
-
}): number;
|
|
20
|
+
export declare function stop(stateDir: string, out: (line: string) => void, err: (line: string) => void, opts?: StopOptions): number;
|
package/dist/commands/stop.js
CHANGED
|
@@ -1,16 +1,28 @@
|
|
|
1
1
|
import { homedir } from "node:os";
|
|
2
|
+
import { readRunning } from "../pid.js";
|
|
2
3
|
import { hasLoginService } from "../service/installed.js";
|
|
4
|
+
import { defaultRunSystem, managerState } from "../service/manager.js";
|
|
3
5
|
import { signalRunning } from "./signal.js";
|
|
4
6
|
/**
|
|
5
|
-
* `stop`: SIGTERM to the running program.
|
|
6
|
-
*
|
|
7
|
-
*
|
|
7
|
+
* `stop`: SIGTERM to the running program. When the service manager runs that program (launchd has
|
|
8
|
+
* the service loaded, systemd has the unit active, and its pid is the running one), `stop` refuses
|
|
9
|
+
* and points at `service stop`, which unloads the service: a signalled service program would be
|
|
10
|
+
* started again by the restart policy, or would leave a service that looks loaded but stays down.
|
|
11
|
+
* A program started in a terminal is signalled as before, with or without a service installed.
|
|
8
12
|
*/
|
|
9
|
-
export function stop(stateDir, out, err,
|
|
10
|
-
const where = service ?? { home: homedir(), platform: process.platform };
|
|
13
|
+
export function stop(stateDir, out, err, opts = {}) {
|
|
14
|
+
const where = opts.service ?? { home: homedir(), platform: process.platform };
|
|
15
|
+
const checks = {
|
|
16
|
+
...(opts.kill && { kill: opts.kill }),
|
|
17
|
+
...(opts.ps && { ps: opts.ps }),
|
|
18
|
+
};
|
|
11
19
|
if (hasLoginService(where.home, where.platform)) {
|
|
12
|
-
|
|
13
|
-
|
|
20
|
+
const state = managerState(where, opts.run ?? defaultRunSystem);
|
|
21
|
+
const program = readRunning(stateDir, checks);
|
|
22
|
+
if (state.loaded && program !== undefined && state.pid === program.pid) {
|
|
23
|
+
err("capybara-device runs as a login service on this machine. Stop it with: capybara-device service stop");
|
|
24
|
+
return 1;
|
|
25
|
+
}
|
|
14
26
|
}
|
|
15
|
-
return signalRunning(stateDir, "SIGTERM", "Stopping capybara-device.", out, err,
|
|
27
|
+
return signalRunning(stateDir, "SIGTERM", "Stopping capybara-device.", out, err, checks);
|
|
16
28
|
}
|
package/dist/exec/switch.d.ts
CHANGED
|
@@ -13,6 +13,12 @@ export type { ExecMode } from "./types.js";
|
|
|
13
13
|
export declare const FILE_OPS_DECISION_TTL_MS = 60000;
|
|
14
14
|
/** The refusal of an auto-mode command whose sandbox was turned back on before it started. */
|
|
15
15
|
export declare const SANDBOX_BACK_ON: string;
|
|
16
|
+
/**
|
|
17
|
+
* The refusal of a file operation on a machine without the OS sandbox when no recent command
|
|
18
|
+
* decided the mode: file operations never pass command review, so they cannot exceed a ceiling
|
|
19
|
+
* the deployment has not confirmed.
|
|
20
|
+
*/
|
|
21
|
+
export declare const NO_FRESH_DECISION: string;
|
|
16
22
|
/**
|
|
17
23
|
* The OS-mode executor the program serves: each command runs in the sandbox or, in auto mode,
|
|
18
24
|
* directly on the machine ({@link effectiveMode}). The policy is read per operation, so a change
|
|
@@ -61,9 +67,10 @@ export declare class SwitchingExecutor implements Executor {
|
|
|
61
67
|
* The executor for file operations now. File operations carry no limits and never pass command
|
|
62
68
|
* review, so they only follow an exec's decision when it is fresh: the sandboxed helper before
|
|
63
69
|
* any exec and once those limits are stale (the safe default for an organization whose ceiling
|
|
64
|
-
* is sandbox), else `effectiveMode(policy, limits)`. On a machine without the OS sandbox
|
|
65
|
-
*
|
|
66
|
-
*
|
|
70
|
+
* is sandbox), else `effectiveMode(policy, limits)`. On a machine without the OS sandbox there is
|
|
71
|
+
* no safe default: without a fresh decision they are refused ({@link NO_FRESH_DECISION}), never
|
|
72
|
+
* run on the host; a fresh auto decision runs them on the host, a sandbox one is refused by the
|
|
73
|
+
* sandboxed executor with the reason.
|
|
67
74
|
*/
|
|
68
75
|
private files;
|
|
69
76
|
exec(args: DeviceExecArgs, signal: AbortSignal): Promise<ExecResult>;
|
package/dist/exec/switch.js
CHANGED
|
@@ -14,6 +14,14 @@ const WATCH_INTERVAL_MS = 1000;
|
|
|
14
14
|
/** The refusal of an auto-mode command whose sandbox was turned back on before it started. */
|
|
15
15
|
export const SANDBOX_BACK_ON = "The sandbox was turned back on on this machine while the command was starting, so it did " +
|
|
16
16
|
"not run. Run it again: it runs in the sandbox now.";
|
|
17
|
+
/**
|
|
18
|
+
* The refusal of a file operation on a machine without the OS sandbox when no recent command
|
|
19
|
+
* decided the mode: file operations never pass command review, so they cannot exceed a ceiling
|
|
20
|
+
* the deployment has not confirmed.
|
|
21
|
+
*/
|
|
22
|
+
export const NO_FRESH_DECISION = "The OS sandbox is unavailable on this machine and no recent command decided this device's " +
|
|
23
|
+
"mode, so file operations are refused until the next command runs (the deployment decides the " +
|
|
24
|
+
"mode at each command).";
|
|
17
25
|
/**
|
|
18
26
|
* The OS-mode executor the program serves: each command runs in the sandbox or, in auto mode,
|
|
19
27
|
* directly on the machine ({@link effectiveMode}). The policy is read per operation, so a change
|
|
@@ -99,9 +107,10 @@ export class SwitchingExecutor {
|
|
|
99
107
|
* The executor for file operations now. File operations carry no limits and never pass command
|
|
100
108
|
* review, so they only follow an exec's decision when it is fresh: the sandboxed helper before
|
|
101
109
|
* any exec and once those limits are stale (the safe default for an organization whose ceiling
|
|
102
|
-
* is sandbox), else `effectiveMode(policy, limits)`. On a machine without the OS sandbox
|
|
103
|
-
*
|
|
104
|
-
*
|
|
110
|
+
* is sandbox), else `effectiveMode(policy, limits)`. On a machine without the OS sandbox there is
|
|
111
|
+
* no safe default: without a fresh decision they are refused ({@link NO_FRESH_DECISION}), never
|
|
112
|
+
* run on the host; a fresh auto decision runs them on the host, a sandbox one is refused by the
|
|
113
|
+
* sandboxed executor with the reason.
|
|
105
114
|
*/
|
|
106
115
|
async files() {
|
|
107
116
|
const policy = this.policy();
|
|
@@ -110,7 +119,9 @@ export class SwitchingExecutor {
|
|
|
110
119
|
return this.sandboxed;
|
|
111
120
|
if (this.lastLimits === undefined ||
|
|
112
121
|
Date.now() - this.lastLimitsAt > FILE_OPS_DECISION_TTL_MS) {
|
|
113
|
-
|
|
122
|
+
if (!this.sandboxReady)
|
|
123
|
+
throw new DeviceOpError("policy", NO_FRESH_DECISION);
|
|
124
|
+
return this.sandboxed;
|
|
114
125
|
}
|
|
115
126
|
return this.lastLimits.mode === "sandbox" ? this.sandboxed : this.host;
|
|
116
127
|
}
|
package/dist/pid.d.ts
CHANGED
|
@@ -9,10 +9,39 @@ export type RunningProgram = {
|
|
|
9
9
|
version?: string;
|
|
10
10
|
startedAt?: string;
|
|
11
11
|
};
|
|
12
|
+
/** What `ps` tells of a process: its command line and, when known, when it started. */
|
|
13
|
+
export interface ProcessInfo {
|
|
14
|
+
command: string;
|
|
15
|
+
started?: Date;
|
|
16
|
+
}
|
|
17
|
+
/** Looks a process up by pid (default: `ps`); undefined when there is no such process. */
|
|
18
|
+
export type ProcessLookup = (pid: number) => ProcessInfo | undefined;
|
|
19
|
+
/** How a pid is checked: `kill(pid, 0)` for liveness, `ps` for what the process is. */
|
|
20
|
+
export interface ProcessChecks {
|
|
21
|
+
kill?: typeof process.kill;
|
|
22
|
+
ps?: ProcessLookup;
|
|
23
|
+
}
|
|
24
|
+
/** The name every command line of this program contains (`…/bin/capybara-device.mjs start`). */
|
|
25
|
+
export declare const PROGRAM_BIN = "capybara-device";
|
|
26
|
+
/**
|
|
27
|
+
* Parses `ps -o lstart= -o command=` output (C locale): `Sat Nov 14 02:11:37 2026 <command>`, the
|
|
28
|
+
* start in local time. A line without a readable start keeps only the command.
|
|
29
|
+
*/
|
|
30
|
+
export declare function parsePsOutput(output: string): ProcessInfo | undefined;
|
|
31
|
+
/** The default {@link ProcessLookup}: one `ps` call in the C locale. */
|
|
32
|
+
export declare function psLookup(pid: number): ProcessInfo | undefined;
|
|
12
33
|
export declare function isAlive(pid: number, kill?: typeof process.kill): boolean;
|
|
13
|
-
/**
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
34
|
+
/**
|
|
35
|
+
* The entry a pid file holds: JSON `{pid, version, startedAt}`, or a bare pid from a program older
|
|
36
|
+
* than the version field. Undefined when it is neither.
|
|
37
|
+
*/
|
|
38
|
+
export declare function parsePidFile(raw: string): RunningProgram | undefined;
|
|
39
|
+
/**
|
|
40
|
+
* The running program, or undefined: no file, a file that is not a pid, a dead pid, or a pid that
|
|
41
|
+
* is not this program any more (see {@link namesThisProgram}). Nothing signals an unverified pid.
|
|
42
|
+
*/
|
|
43
|
+
export declare function readRunning(dir: string, checks?: ProcessChecks): RunningProgram | undefined;
|
|
44
|
+
/** The pid of the running program, or undefined (see {@link readRunning}). */
|
|
45
|
+
export declare function readRunningPid(dir: string, checks?: ProcessChecks): number | undefined;
|
|
17
46
|
export declare function writePid(dir: string, pid: number, version?: string): void;
|
|
18
47
|
export declare function removePid(dir: string, pid: number): void;
|