pi-reply-reader 0.1.0 → 0.2.0
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/CHANGELOG.md +143 -0
- package/README.md +402 -39
- package/dist/src/cli.js +137 -10
- package/dist/src/listener.js +532 -0
- package/dist/src/music.js +452 -0
- package/dist/src/outputs.js +29 -4
- package/dist/src/playback.js +170 -46
- package/dist/src/player.js +265 -0
- package/dist/src/project.js +50 -0
- package/dist/src/reading-lock.js +296 -68
- package/dist/src/settings.js +32 -3
- package/dist/src/speech-text.js +581 -64
- package/examples/reply-reader-desktop-audio.service +23 -10
- package/examples/reply-reader-vps-audio.service +57 -0
- package/extensions/reply-reader.ts +920 -106
- package/package.json +3 -2
- package/src/auto-queue.ts +123 -0
- package/src/cli.ts +131 -10
- package/src/listener.ts +522 -0
- package/src/music.ts +474 -0
- package/src/outputs.ts +37 -5
- package/src/pause-key.ts +105 -0
- package/src/playback.ts +179 -48
- package/src/player.ts +255 -0
- package/src/project.ts +46 -0
- package/src/prompts.ts +142 -0
- package/src/reading-lock.ts +364 -66
- package/src/settings.ts +34 -3
- package/src/speech-text.ts +692 -56
package/src/playback.ts
CHANGED
|
@@ -1,7 +1,9 @@
|
|
|
1
1
|
import { type ChildProcess, spawn } from "node:child_process";
|
|
2
|
+
import { readFileSync } from "node:fs";
|
|
2
3
|
import type { Output } from "./outputs.ts";
|
|
3
|
-
import { PLAYER_MARK } from "./
|
|
4
|
+
import { OWNER_VAR, ownerTag, PLAYER_MARK, playerTimeout, reapOrphans, terminate, track, withDeathSignal } from "./player.ts";
|
|
4
5
|
import { DEFAULT_SPEED } from "./settings.ts";
|
|
6
|
+
import type { Boundary, Fragment } from "./speech-text.ts";
|
|
5
7
|
import { onPath, type Speaker, type Voice } from "./voice.ts";
|
|
6
8
|
|
|
7
9
|
/** What one segment asks of Supertonic; the real loader wraps `generationConfig` in sherpa's GenerationConfig. */
|
|
@@ -25,6 +27,11 @@ export interface Reading {
|
|
|
25
27
|
/** Settles when the audio ends or the reading is stopped; rejects with a message for the user. */
|
|
26
28
|
readonly done: Promise<void>;
|
|
27
29
|
stop(): void;
|
|
30
|
+
/**
|
|
31
|
+
* The index, in the fragments given, of the fragment being heard now (S15: a paused reading resumes from its start),
|
|
32
|
+
* or of the next one during a pause after its fragment. 0 before any audio.
|
|
33
|
+
*/
|
|
34
|
+
position(): number;
|
|
28
35
|
}
|
|
29
36
|
|
|
30
37
|
const PAPLAY_MISSING =
|
|
@@ -34,28 +41,70 @@ const PAPLAY_MISSING =
|
|
|
34
41
|
const SEED = 42;
|
|
35
42
|
|
|
36
43
|
/**
|
|
37
|
-
*
|
|
44
|
+
* How far behind the time since a fragment was handed over the player is taken to be (S15): its connection, Pulse's
|
|
45
|
+
* buffer and pipe make what is heard lag what was written, so a pause rather resumes a little early than skip words.
|
|
46
|
+
*/
|
|
47
|
+
const HEARD_LAG_MS = 500;
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Speaks `fragments` (from `speechNarration`, or `spokenFragments` for plain text) with `speaker` at `speed` (Supertonic's voice speed, 1.1 by default; our pauses do not
|
|
38
51
|
* change with it) on `output`. Supertonic synthesizes one sentence at a time, so the first
|
|
39
52
|
* audio comes after one sentence instead of the whole reply, and the next sentence is synthesized while the
|
|
40
53
|
* current one plays (at most LOOKAHEAD wait for the player); each sentence loses its own leading and
|
|
41
54
|
* trailing silence and is followed right away by our pause for its boundary, then goes to `paplay` as raw 16-bit
|
|
42
55
|
* mono PCM, on this machine's default sink or, for a named output, on its PULSE_SERVER. Nothing here
|
|
43
56
|
* throws: every failure ends in `done`, and `stop()` ends the player and settles `done` quietly.
|
|
57
|
+
*
|
|
58
|
+
* A player that hangs (S13), such as paplay waiting forever on a Pulse server behind a broken SSH tunnel, is ended:
|
|
59
|
+
* when it takes no audio for the player timeout (REPLY_READER_PLAYER_TIMEOUT seconds in `env`, 15 by default) while
|
|
60
|
+
* audio waits for it, or does not end within the audio's length plus that timeout once it has all of it, it is killed
|
|
61
|
+
* and `done` rejects with `Playback on "<output>" failed: timed out` (a player that had already exited by then is
|
|
62
|
+
* not). Every kill is SIGTERM, then SIGKILL two seconds later; a player left by a reader that died is ended when the
|
|
63
|
+
* next reading starts, and this process's player dies with it (through `setpriv --pdeathsig KILL` when available, so
|
|
64
|
+
* even a reader killed outright takes it along).
|
|
44
65
|
*/
|
|
45
66
|
export function startReading(options: {
|
|
46
67
|
voice: Voice;
|
|
47
68
|
speaker: Speaker;
|
|
48
|
-
text
|
|
69
|
+
/** Spoken in order, each followed by the pause for its own boundary; their text is never split again. */
|
|
70
|
+
fragments: readonly Fragment[];
|
|
49
71
|
output: Output;
|
|
50
72
|
env: NodeJS.ProcessEnv;
|
|
51
73
|
loadSherpa?: (voice: Voice) => Promise<SherpaTts>;
|
|
52
74
|
speed?: number;
|
|
53
75
|
/** Told the player's pid once it starts, so another session can stop this reading (T21). */
|
|
54
76
|
onPlayer?: (pid: number) => void;
|
|
77
|
+
/**
|
|
78
|
+
* The player timeout of S13 in milliseconds; REPLY_READER_PLAYER_TIMEOUT in `env` (or 15 s) when not given. Callers
|
|
79
|
+
* pass playerTimeoutMs(env, warn), which also warns about an invalid value.
|
|
80
|
+
*/
|
|
81
|
+
timeoutMs?: number;
|
|
82
|
+
/**
|
|
83
|
+
* Seconds of silence the player gets before the first fragment (S14: the gap before a reading that waited in the
|
|
84
|
+
* line). Written at once, so the first synthesis overlaps it.
|
|
85
|
+
*/
|
|
86
|
+
leadSilence?: number;
|
|
55
87
|
}): Reading {
|
|
56
|
-
const { voice, speaker,
|
|
88
|
+
const { voice, speaker, fragments: list, output, env, loadSherpa = loadSherpaTts, speed = DEFAULT_SPEED, onPlayer } = options;
|
|
57
89
|
let player: ChildProcess | undefined;
|
|
58
90
|
let stopped = false;
|
|
91
|
+
/** Set by the watchdog (S13): the player took no audio, or did not end, in time. */
|
|
92
|
+
let timedOut = false;
|
|
93
|
+
/** Set when the deadline passed after the player exited (S13 g): it settles on its exit, not on its pipes. */
|
|
94
|
+
let overdue = false;
|
|
95
|
+
/** Settles `done` from the player's exit status once it exited; set by `finished`. */
|
|
96
|
+
let settleExited: (() => void) | undefined;
|
|
97
|
+
/**
|
|
98
|
+
* When each fragment handed to the player starts being heard (S15), modelled as real-time playback that waits for
|
|
99
|
+
* audio when it runs out: a fragment starts when it is handed over or when the one before it ends, whichever is later.
|
|
100
|
+
*/
|
|
101
|
+
const heard: { index: number; at: number }[] = [];
|
|
102
|
+
let heardUntil = 0;
|
|
103
|
+
const handed = (index: number, samples: number, sampleRate: number): void => {
|
|
104
|
+
const at = Math.max(Date.now(), heardUntil);
|
|
105
|
+
heard.push({ index, at });
|
|
106
|
+
heardUntil = at + (samples / sampleRate) * 1000;
|
|
107
|
+
};
|
|
59
108
|
|
|
60
109
|
const run = async (): Promise<void> => {
|
|
61
110
|
const paplay = onPath("paplay", env);
|
|
@@ -69,10 +118,15 @@ export function startReading(options: {
|
|
|
69
118
|
}
|
|
70
119
|
if (stopped) return;
|
|
71
120
|
|
|
72
|
-
const playerEnv = output.pulseServer ? {
|
|
121
|
+
const playerEnv = { ...env, ...(output.pulseServer ? { PULSE_SERVER: output.pulseServer } : {}), [OWNER_VAR]: ownerTag() };
|
|
73
122
|
const args = ["--raw", "--format=s16le", `--rate=${tts.sampleRate}`, "--channels=1", PLAYER_MARK, "--stream-name=reply"];
|
|
74
|
-
|
|
123
|
+
// Players left playing or hung by a reader that died (S13) go before this one starts.
|
|
124
|
+
reapOrphans();
|
|
125
|
+
// Through setpriv, the player gets SIGKILL when this process dies however it dies (S13 h).
|
|
126
|
+
const [command, commandArgs] = withDeathSignal(onPath("setpriv", env), paplay, args);
|
|
127
|
+
const child = spawn(command, commandArgs, { env: playerEnv, stdio: ["pipe", "ignore", "pipe"] });
|
|
75
128
|
player = child;
|
|
129
|
+
track(child);
|
|
76
130
|
// A player that quits early closes its stdin; writing to it must not crash Pi.
|
|
77
131
|
child.stdin?.on("error", () => {});
|
|
78
132
|
const playback = finished(child, `Playback on "${output.name}" failed`);
|
|
@@ -86,20 +140,83 @@ export function startReading(options: {
|
|
|
86
140
|
// A player that exited takes nothing more, even before its pipes close.
|
|
87
141
|
child.once("exit", () => (playerGone = true));
|
|
88
142
|
|
|
89
|
-
//
|
|
143
|
+
// The watchdog (S13): armed while a chunk waits for the player, and once all audio is handed over.
|
|
144
|
+
const timeout = options.timeoutMs ?? playerTimeout(env).ms;
|
|
145
|
+
let watchdog: NodeJS.Timeout | undefined;
|
|
146
|
+
const arm = (ms: number): void => {
|
|
147
|
+
clearTimeout(watchdog);
|
|
148
|
+
// setTimeout takes at most 2^31-1 ms (about 24.8 days); a longer wait would fire at once.
|
|
149
|
+
watchdog = setTimeout(() => {
|
|
150
|
+
if (stopped) return;
|
|
151
|
+
// A player that already exited is not hung (S13 g): settle on how it exited, without waiting for pipes a
|
|
152
|
+
// process it left behind may still hold.
|
|
153
|
+
if (exited(child)) {
|
|
154
|
+
overdue = true;
|
|
155
|
+
settleExited?.();
|
|
156
|
+
return;
|
|
157
|
+
}
|
|
158
|
+
timedOut = true;
|
|
159
|
+
playerGone = true;
|
|
160
|
+
terminate(child);
|
|
161
|
+
taken?.();
|
|
162
|
+
}, Math.min(ms, MAX_TIMER_MS));
|
|
163
|
+
};
|
|
164
|
+
gone.then(() => clearTimeout(watchdog));
|
|
165
|
+
|
|
166
|
+
// Fragments handed over that the pipe has not taken whole yet. Each fragment goes in CHUNK-byte writes, one at a
|
|
167
|
+
// time, so the watchdog sees a player that keeps taking a long fragment as alive.
|
|
90
168
|
let queued = 0;
|
|
91
169
|
let taken: (() => void) | undefined;
|
|
92
|
-
const
|
|
93
|
-
|
|
94
|
-
|
|
170
|
+
const backlog: { chunk: Buffer; last: boolean }[] = [];
|
|
171
|
+
let writing = false;
|
|
172
|
+
let ending = false;
|
|
173
|
+
let samplesSent = 0;
|
|
174
|
+
const pump = (): void => {
|
|
175
|
+
if (writing) return;
|
|
176
|
+
if (playerGone) backlog.length = 0;
|
|
177
|
+
const next = backlog.shift();
|
|
178
|
+
if (!next) {
|
|
179
|
+
if (ending) {
|
|
180
|
+
ending = false;
|
|
181
|
+
child.stdin?.end();
|
|
182
|
+
// The player has all the audio: it must end within the audio's length plus the timeout.
|
|
183
|
+
if (!playerGone) arm(Math.round((samplesSent / tts.sampleRate) * 1000) + timeout);
|
|
184
|
+
}
|
|
185
|
+
return;
|
|
186
|
+
}
|
|
187
|
+
writing = true;
|
|
188
|
+
arm(timeout);
|
|
189
|
+
child.stdin?.write(next.chunk, (error) => {
|
|
190
|
+
writing = false;
|
|
191
|
+
clearTimeout(watchdog);
|
|
95
192
|
// A write that fails means the player closed its input: it will take nothing more.
|
|
96
193
|
if (error) playerGone = true;
|
|
97
|
-
|
|
98
|
-
|
|
194
|
+
if (next.last) {
|
|
195
|
+
queued--;
|
|
196
|
+
taken?.();
|
|
197
|
+
}
|
|
198
|
+
pump();
|
|
99
199
|
});
|
|
100
200
|
};
|
|
201
|
+
const send = (audio: Float32Array): void => {
|
|
202
|
+
queued++;
|
|
203
|
+
samplesSent += audio.length;
|
|
204
|
+
const bytes = pcm16(audio, speaker.gain);
|
|
205
|
+
for (let at = 0; at < bytes.length; at += CHUNK) {
|
|
206
|
+
backlog.push({ chunk: bytes.subarray(at, at + CHUNK), last: at + CHUNK >= bytes.length });
|
|
207
|
+
}
|
|
208
|
+
pump();
|
|
209
|
+
};
|
|
210
|
+
const close = (): void => {
|
|
211
|
+
ending = true;
|
|
212
|
+
pump();
|
|
213
|
+
};
|
|
101
214
|
|
|
102
|
-
const
|
|
215
|
+
const lead = Math.round((options.leadSilence ?? 0) * tts.sampleRate);
|
|
216
|
+
if (lead > 0) {
|
|
217
|
+
handed(0, lead, tts.sampleRate);
|
|
218
|
+
send(new Float32Array(lead));
|
|
219
|
+
}
|
|
103
220
|
// Samples of pause already written after the last audible fragment; undefined before the first one.
|
|
104
221
|
let paused: number | undefined;
|
|
105
222
|
for (const [index, fragment] of list.entries()) {
|
|
@@ -122,27 +239,30 @@ export function startReading(options: {
|
|
|
122
239
|
if (stopped || playerGone) break;
|
|
123
240
|
const speech = trimSilence(samples, speaker.gain, tts.sampleRate);
|
|
124
241
|
// The last fragment's pause is never written.
|
|
125
|
-
const after = index === list.length - 1 ? 0 : Math.round(PAUSES[fragment.
|
|
242
|
+
const after = index === list.length - 1 ? 0 : Math.round(PAUSES[fragment.after] * tts.sampleRate);
|
|
126
243
|
// A silent fragment is dropped, but a stronger boundary it ends still counts: top up the pause written.
|
|
127
244
|
if (!speech) {
|
|
128
245
|
if (paused !== undefined && after > paused) {
|
|
246
|
+
handed(index + 1, after - paused, tts.sampleRate);
|
|
129
247
|
send(new Float32Array(after - paused));
|
|
130
248
|
paused = after;
|
|
131
249
|
}
|
|
132
250
|
continue;
|
|
133
251
|
}
|
|
134
252
|
// Each pause goes right after its own fragment, so the next synthesis overlaps it too.
|
|
253
|
+
handed(index, speech.length, tts.sampleRate);
|
|
254
|
+
if (after) handed(index + 1, after, tts.sampleRate);
|
|
135
255
|
send(after ? concat(speech, new Float32Array(after)) : speech);
|
|
136
256
|
paused = after;
|
|
137
257
|
}
|
|
138
|
-
|
|
258
|
+
close();
|
|
139
259
|
await playback;
|
|
140
260
|
};
|
|
141
261
|
|
|
142
262
|
const done = run().then(
|
|
143
263
|
() => undefined,
|
|
144
264
|
(error: Error) => {
|
|
145
|
-
player
|
|
265
|
+
if (player) terminate(player);
|
|
146
266
|
if (!stopped) throw error;
|
|
147
267
|
},
|
|
148
268
|
);
|
|
@@ -150,7 +270,16 @@ export function startReading(options: {
|
|
|
150
270
|
done,
|
|
151
271
|
stop() {
|
|
152
272
|
stopped = true;
|
|
153
|
-
player
|
|
273
|
+
if (player) terminate(player);
|
|
274
|
+
},
|
|
275
|
+
position() {
|
|
276
|
+
const now = Date.now() - HEARD_LAG_MS;
|
|
277
|
+
let index = 0;
|
|
278
|
+
for (const segment of heard) {
|
|
279
|
+
if (segment.at > now) break;
|
|
280
|
+
index = segment.index;
|
|
281
|
+
}
|
|
282
|
+
return Math.min(index, Math.max(0, list.length - 1));
|
|
154
283
|
},
|
|
155
284
|
};
|
|
156
285
|
|
|
@@ -159,18 +288,46 @@ export function startReading(options: {
|
|
|
159
288
|
let stderr = "";
|
|
160
289
|
child.stderr?.on("data", (chunk: Buffer) => (stderr = (stderr + chunk.toString()).slice(-4096)));
|
|
161
290
|
return new Promise((resolve, reject) => {
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
if (code === 0 || stopped) return resolve();
|
|
291
|
+
const settle = (code: number | null, signal: NodeJS.Signals | null): void => {
|
|
292
|
+
if (stopped) return resolve();
|
|
293
|
+
if (timedOut) return reject(new Error(`${prefix}: timed out`));
|
|
294
|
+
if (code === 0) return resolve();
|
|
167
295
|
const last = stderr.trim().split("\n").at(-1)?.trim();
|
|
168
296
|
reject(new Error(`${prefix}: ${last || (signal ? `killed by ${signal}` : `exit code ${code}`)}`));
|
|
297
|
+
};
|
|
298
|
+
settleExited = () => {
|
|
299
|
+
if (child.exitCode !== null || child.signalCode !== null) settle(child.exitCode, child.signalCode);
|
|
300
|
+
};
|
|
301
|
+
child.on("error", (error) => reject(new Error(`${prefix}: ${error.message}`)));
|
|
302
|
+
// After stop, a timeout or a passed deadline, do not wait for pipes a grandchild may still hold open.
|
|
303
|
+
child.on("exit", (code, signal) => {
|
|
304
|
+
if (stopped || timedOut || overdue) settle(code, signal);
|
|
169
305
|
});
|
|
306
|
+
child.on("close", settle);
|
|
170
307
|
});
|
|
171
308
|
}
|
|
172
309
|
}
|
|
173
310
|
|
|
311
|
+
/** The longest delay setTimeout takes; a longer one fires at once with a TimeoutOverflowWarning. */
|
|
312
|
+
const MAX_TIMER_MS = 2 ** 31 - 1;
|
|
313
|
+
|
|
314
|
+
/**
|
|
315
|
+
* Whether `child` already exited: its exit was seen, or it is a zombie whose exit event has not come yet (the deadline
|
|
316
|
+
* and the exit can land in the same turn of the event loop).
|
|
317
|
+
*/
|
|
318
|
+
function exited(child: ChildProcess): boolean {
|
|
319
|
+
if (child.exitCode !== null || child.signalCode !== null) return true;
|
|
320
|
+
try {
|
|
321
|
+
const stat = readFileSync(`/proc/${child.pid}/stat`, "utf8");
|
|
322
|
+
return stat.slice(stat.lastIndexOf(")") + 2, stat.lastIndexOf(")") + 3) === "Z";
|
|
323
|
+
} catch {
|
|
324
|
+
return false;
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
/** Bytes per write to the player: about 0.37 s of audio at 44.1 kHz, well under a Linux pipe's 64 KiB. */
|
|
329
|
+
const CHUNK = 32 * 1024;
|
|
330
|
+
|
|
174
331
|
/**
|
|
175
332
|
* Synthesized fragments that may wait for the player at once (T26): the one playing and the next one, ready.
|
|
176
333
|
* Synthesis is one call at a time and, under load, slower than real time (L70), so a deeper queue would rarely
|
|
@@ -179,38 +336,12 @@ export function startReading(options: {
|
|
|
179
336
|
*/
|
|
180
337
|
const LOOKAHEAD = 2;
|
|
181
338
|
|
|
182
|
-
type Boundary = "sentence" | "line" | "paragraph";
|
|
183
|
-
|
|
184
339
|
/**
|
|
185
340
|
* Seconds of silence after a fragment, by what follows it: a sentence on the same line, a line, a blank line
|
|
186
341
|
* (also after a heading or bold-only line). Longer than the voice's own 0.08-0.26 s at `,`, `;` and `:` (L39).
|
|
187
342
|
*/
|
|
188
343
|
const PAUSES: Record<Boundary, number> = { sentence: 0.35, line: 0.5, paragraph: 0.75 };
|
|
189
344
|
|
|
190
|
-
/**
|
|
191
|
-
* Sentences and lines, in order, each with the boundary after it; Supertonic only calls back once per
|
|
192
|
-
* 300 characters, so we split first. Never at ":" or ";", where a pause would sound like a full stop.
|
|
193
|
-
*/
|
|
194
|
-
function fragments(text: string): { text: string; boundary: Boundary }[] {
|
|
195
|
-
const result: { text: string; boundary: Boundary }[] = [];
|
|
196
|
-
let blank = false;
|
|
197
|
-
for (const line of text.split("\n")) {
|
|
198
|
-
const sentences = line
|
|
199
|
-
.split(/(?<=[.!?…])\s+/)
|
|
200
|
-
.map((sentence) => sentence.trim())
|
|
201
|
-
.filter((sentence) => sentence !== "");
|
|
202
|
-
if (sentences.length === 0) {
|
|
203
|
-
blank = true;
|
|
204
|
-
continue;
|
|
205
|
-
}
|
|
206
|
-
const previous = result.at(-1);
|
|
207
|
-
if (previous) previous.boundary = blank ? "paragraph" : "line";
|
|
208
|
-
blank = false;
|
|
209
|
-
for (const sentence of sentences) result.push({ text: sentence, boundary: "sentence" });
|
|
210
|
-
}
|
|
211
|
-
return result;
|
|
212
|
-
}
|
|
213
|
-
|
|
214
345
|
/** Windows quieter than this, after the speaker's gain, count as silence (-45 dBFS RMS over 10 ms). */
|
|
215
346
|
const SILENCE = 10 ** (-45 / 20);
|
|
216
347
|
const WINDOW_SECONDS = 0.01;
|
package/src/player.ts
ADDED
|
@@ -0,0 +1,255 @@
|
|
|
1
|
+
import { type ChildProcess, spawnSync } from "node:child_process";
|
|
2
|
+
import { readdirSync, readFileSync, readlinkSync, statSync } from "node:fs";
|
|
3
|
+
|
|
4
|
+
/** Every player we start carries this argument, so a pid can be told apart from an unrelated process. */
|
|
5
|
+
export const PLAYER_MARK = "--client-name=pi-reply-reader";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Set in each player's environment to `<pid>:<start time>` of the process that started it (S13), so a later reading
|
|
9
|
+
* can tell a player whose reader is gone from one that still has a reader, and from a paplay that is not ours.
|
|
10
|
+
*/
|
|
11
|
+
export const OWNER_VAR = "PI_REPLY_READER_OWNER";
|
|
12
|
+
|
|
13
|
+
/** How long a player gets to end after SIGTERM before SIGKILL (S13): paplay stuck connecting may ignore SIGTERM. */
|
|
14
|
+
export const KILL_GRACE_MS = 2000;
|
|
15
|
+
|
|
16
|
+
/** The value of OWNER_VAR for players started by this process. */
|
|
17
|
+
export function ownerTag(): string {
|
|
18
|
+
return `${process.pid}:${startTime(process.pid) ?? ""}`;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
const ending = new WeakSet<ChildProcess>();
|
|
22
|
+
|
|
23
|
+
/** SIGTERM to a player we started, then SIGKILL after KILL_GRACE_MS if it has not exited. Never throws. */
|
|
24
|
+
export function terminate(child: ChildProcess): void {
|
|
25
|
+
if (child.exitCode !== null || child.signalCode !== null) return;
|
|
26
|
+
try {
|
|
27
|
+
child.kill("SIGTERM");
|
|
28
|
+
} catch {}
|
|
29
|
+
if (ending.has(child)) return;
|
|
30
|
+
ending.add(child);
|
|
31
|
+
const timer = setTimeout(() => {
|
|
32
|
+
if (child.exitCode !== null || child.signalCode !== null) return;
|
|
33
|
+
try {
|
|
34
|
+
child.kill("SIGKILL");
|
|
35
|
+
} catch {}
|
|
36
|
+
}, KILL_GRACE_MS);
|
|
37
|
+
child.once("exit", () => clearTimeout(timer));
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** How often a player signalled by pid is checked for having ended during its grace. */
|
|
41
|
+
const POLL_MS = 50;
|
|
42
|
+
/** Players signalled by terminatePid whose grace has not run out, each settling when it ended or was SIGKILLed. */
|
|
43
|
+
const signalled = new Set<Promise<void>>();
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* SIGTERM to the player `pid` (started at `start`), then SIGKILL after KILL_GRACE_MS if that same player of ours is
|
|
47
|
+
* still there. Its timer does not keep this process alive: a process about to exit awaits signalledPlayersEnded()
|
|
48
|
+
* first. Never throws.
|
|
49
|
+
*/
|
|
50
|
+
export function terminatePid(pid: number, start: string | undefined): void {
|
|
51
|
+
try {
|
|
52
|
+
process.kill(pid, "SIGTERM");
|
|
53
|
+
} catch {
|
|
54
|
+
return;
|
|
55
|
+
}
|
|
56
|
+
const began = Date.now();
|
|
57
|
+
const ended = new Promise<void>((done) => {
|
|
58
|
+
const timer = setInterval(() => {
|
|
59
|
+
if (isPlayer(pid, start) && Date.now() - began < KILL_GRACE_MS) return;
|
|
60
|
+
clearInterval(timer);
|
|
61
|
+
if (isPlayer(pid, start)) {
|
|
62
|
+
try {
|
|
63
|
+
process.kill(pid, "SIGKILL");
|
|
64
|
+
} catch {}
|
|
65
|
+
}
|
|
66
|
+
done();
|
|
67
|
+
}, POLL_MS);
|
|
68
|
+
timer.unref();
|
|
69
|
+
});
|
|
70
|
+
signalled.add(ended);
|
|
71
|
+
ended.then(() => signalled.delete(ended));
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
/**
|
|
75
|
+
* Settles once every player this process signalled with terminatePid (a reaped orphan, a lock takeover) has exited or
|
|
76
|
+
* been SIGKILLed (S13 e), so a command that exits right after never cuts the SIGKILL short.
|
|
77
|
+
*/
|
|
78
|
+
export async function signalledPlayersEnded(): Promise<void> {
|
|
79
|
+
if (signalled.size === 0) return;
|
|
80
|
+
// The grace timers are unref'd so they never hold Pi; this one holds the event loop while we wait for them.
|
|
81
|
+
const hold = setInterval(() => {}, KILL_GRACE_MS);
|
|
82
|
+
try {
|
|
83
|
+
await Promise.all([...signalled]);
|
|
84
|
+
} finally {
|
|
85
|
+
clearInterval(hold);
|
|
86
|
+
}
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
const live = new Set<ChildProcess>();
|
|
90
|
+
let exitHooked = false;
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Keeps `child` until it exits; if this process exits first (Pi quitting without session_shutdown, the CLI's
|
|
94
|
+
* process.exit), the player is killed with it instead of playing or hanging on, orphaned (S13).
|
|
95
|
+
*/
|
|
96
|
+
export function track(child: ChildProcess): void {
|
|
97
|
+
live.add(child);
|
|
98
|
+
child.once("exit", () => live.delete(child));
|
|
99
|
+
if (exitHooked) return;
|
|
100
|
+
exitHooked = true;
|
|
101
|
+
process.on("exit", () => {
|
|
102
|
+
for (const player of live) {
|
|
103
|
+
try {
|
|
104
|
+
player.kill("SIGKILL");
|
|
105
|
+
} catch {}
|
|
106
|
+
}
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
/**
|
|
111
|
+
* Ends every player whose reader is gone (S13): a process of this user, in this process's PID namespace, whose command
|
|
112
|
+
* line carries PLAYER_MARK and whose OWNER_VAR names a process that no longer runs (a Pi killed with SIGKILL, say). A
|
|
113
|
+
* paplay without both marks, whose reader still runs, or in another PID namespace (or one that cannot be read: an
|
|
114
|
+
* owner pid means something only in its own namespace, so a reader in a sandbox keeps its player), is never touched.
|
|
115
|
+
* A listener's `reply-reader --serve` (S20) carries PLAYER_MARK too, but is never reaped here: an OWNER_VAR it got from
|
|
116
|
+
* the agent host (ssh SendEnv) names a process of another machine; it ends itself when its standard input closes.
|
|
117
|
+
* Returns the pids it signalled; nothing where /proc is missing.
|
|
118
|
+
*/
|
|
119
|
+
export function reapOrphans(): number[] {
|
|
120
|
+
let names: string[];
|
|
121
|
+
const namespace = pidNamespace("self");
|
|
122
|
+
if (namespace === undefined) return [];
|
|
123
|
+
try {
|
|
124
|
+
names = readdirSync("/proc");
|
|
125
|
+
} catch {
|
|
126
|
+
return [];
|
|
127
|
+
}
|
|
128
|
+
const uid = process.getuid?.();
|
|
129
|
+
const reaped: number[] = [];
|
|
130
|
+
for (const name of names) {
|
|
131
|
+
if (!/^\d+$/.test(name)) continue;
|
|
132
|
+
const pid = Number(name);
|
|
133
|
+
if (pid === process.pid) continue;
|
|
134
|
+
try {
|
|
135
|
+
if (uid !== undefined && statSync(`/proc/${pid}`).uid !== uid) continue;
|
|
136
|
+
const args = readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0");
|
|
137
|
+
if (!args.includes(PLAYER_MARK) || isListenerServe(args)) continue;
|
|
138
|
+
if (pidNamespace(String(pid)) !== namespace) continue;
|
|
139
|
+
const tag = readFileSync(`/proc/${pid}/environ`, "utf8")
|
|
140
|
+
.split("\0")
|
|
141
|
+
.find((entry) => entry.startsWith(`${OWNER_VAR}=`));
|
|
142
|
+
if (!tag) continue;
|
|
143
|
+
const [owner, start] = tag.slice(OWNER_VAR.length + 1).split(":");
|
|
144
|
+
const ownerPid = Number(owner);
|
|
145
|
+
if (!Number.isInteger(ownerPid) || ownerPid <= 0) continue;
|
|
146
|
+
if (sameProcess(ownerPid, start || undefined)) continue;
|
|
147
|
+
terminatePid(pid, startTime(pid));
|
|
148
|
+
reaped.push(pid);
|
|
149
|
+
} catch {}
|
|
150
|
+
}
|
|
151
|
+
return reaped;
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Whether a command line is a listener's `reply-reader --serve` (S20): "--serve" right after the path of the
|
|
156
|
+
* reply-reader script (`…/reply-reader`, `…/reply-reader.ts` or `.js`). The agent host's ssh child, whose remote
|
|
157
|
+
* command is the bare word `reply-reader`, does not match, so an orphaned one is still reaped.
|
|
158
|
+
*/
|
|
159
|
+
export function isListenerServe(args: readonly string[]): boolean {
|
|
160
|
+
const at = args.indexOf("--serve");
|
|
161
|
+
if (at < 1) return false;
|
|
162
|
+
const script = args[at - 1];
|
|
163
|
+
return script.includes("/") && /^reply-reader(\.[cm]?[jt]s)?$/.test(script.slice(script.lastIndexOf("/") + 1));
|
|
164
|
+
}
|
|
165
|
+
|
|
166
|
+
/** The PID namespace of `/proc/<pid>` ("self" for this process), as `pid:[inode]`; undefined when unreadable. */
|
|
167
|
+
function pidNamespace(pid: string): string | undefined {
|
|
168
|
+
try {
|
|
169
|
+
return readlinkSync(`/proc/${pid}/ns/pid`);
|
|
170
|
+
} catch {
|
|
171
|
+
return undefined;
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** The player timeout of S13 when REPLY_READER_PLAYER_TIMEOUT is unset or invalid. */
|
|
176
|
+
const DEFAULT_TIMEOUT_SECONDS = 15;
|
|
177
|
+
const MIN_TIMEOUT_SECONDS = 5;
|
|
178
|
+
const MAX_TIMEOUT_SECONDS = 86400;
|
|
179
|
+
/** The warning for an invalid REPLY_READER_PLAYER_TIMEOUT (S13 f). */
|
|
180
|
+
export const PLAYER_TIMEOUT_HINT = `REPLY_READER_PLAYER_TIMEOUT must be a number of seconds from ${MIN_TIMEOUT_SECONDS} to ${MAX_TIMEOUT_SECONDS}; using ${DEFAULT_TIMEOUT_SECONDS}.`;
|
|
181
|
+
|
|
182
|
+
/**
|
|
183
|
+
* The player timeout of S13 in milliseconds: REPLY_READER_PLAYER_TIMEOUT, whole or fractional seconds from 5 to 86400,
|
|
184
|
+
* else 15 s; any value set but outside that (empty, `0`, `abc`, `3000000`) also returns the warning.
|
|
185
|
+
*/
|
|
186
|
+
export function playerTimeout(env: NodeJS.ProcessEnv): { ms: number; problem?: string } {
|
|
187
|
+
const value = env.REPLY_READER_PLAYER_TIMEOUT;
|
|
188
|
+
if (value === undefined) return { ms: DEFAULT_TIMEOUT_SECONDS * 1000 };
|
|
189
|
+
const text = value.trim();
|
|
190
|
+
const seconds = /^\d+(\.\d+)?$/.test(text) ? Number(text) : Number.NaN;
|
|
191
|
+
if (seconds >= MIN_TIMEOUT_SECONDS && seconds <= MAX_TIMEOUT_SECONDS) return { ms: Math.round(seconds * 1000) };
|
|
192
|
+
return { ms: DEFAULT_TIMEOUT_SECONDS * 1000, problem: PLAYER_TIMEOUT_HINT };
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
let timeoutWarned = false;
|
|
196
|
+
|
|
197
|
+
/** playerTimeout's milliseconds, telling `warn` about an invalid value once per process (S13 f). */
|
|
198
|
+
export function playerTimeoutMs(env: NodeJS.ProcessEnv, warn: (message: string) => void): number {
|
|
199
|
+
const { ms, problem } = playerTimeout(env);
|
|
200
|
+
if (problem && !timeoutWarned) {
|
|
201
|
+
timeoutWarned = true;
|
|
202
|
+
warn(problem);
|
|
203
|
+
}
|
|
204
|
+
return ms;
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
const deathSignal = new Map<string, boolean>();
|
|
208
|
+
|
|
209
|
+
/**
|
|
210
|
+
* The command and arguments that start `command` so it gets SIGKILL when this process dies (S13 h), however it dies:
|
|
211
|
+
* `setpriv --pdeathsig KILL` when setpriv (`setpriv`, found by the caller on PATH) runs and supports it, else
|
|
212
|
+
* `command` alone. Checked under Pi's Bun (T37): a player started through it from the JS thread is not cut while its
|
|
213
|
+
* reader runs, and dies when the reader is SIGKILLed.
|
|
214
|
+
*/
|
|
215
|
+
export function withDeathSignal(setpriv: string | undefined, command: string, args: string[]): [string, string[]] {
|
|
216
|
+
if (!setpriv) return [command, args];
|
|
217
|
+
let works = deathSignal.get(setpriv);
|
|
218
|
+
if (works === undefined) {
|
|
219
|
+
const check = spawnSync(setpriv, ["--pdeathsig", "KILL", "/bin/sh", "-c", ":"], { stdio: "ignore", timeout: 2000 });
|
|
220
|
+
works = check.status === 0;
|
|
221
|
+
deathSignal.set(setpriv, works);
|
|
222
|
+
}
|
|
223
|
+
return works ? [setpriv, ["--pdeathsig", "KILL", command, ...args]] : [command, args];
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
/** A live process of this user with that pid, started when recorded (when recorded). */
|
|
227
|
+
export function sameProcess(pid: number, start: string | undefined): boolean {
|
|
228
|
+
try {
|
|
229
|
+
process.kill(pid, 0);
|
|
230
|
+
} catch {
|
|
231
|
+
return false;
|
|
232
|
+
}
|
|
233
|
+
return start === undefined || startTime(pid) === start;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/** Guards against pid reuse: only a live player we started, of this user, may be signalled. */
|
|
237
|
+
export function isPlayer(pid: number, start: string | undefined): boolean {
|
|
238
|
+
if (!sameProcess(pid, start)) return false;
|
|
239
|
+
try {
|
|
240
|
+
if (process.getuid && statSync(`/proc/${pid}`).uid !== process.getuid()) return false;
|
|
241
|
+
return readFileSync(`/proc/${pid}/cmdline`, "utf8").split("\0").includes(PLAYER_MARK);
|
|
242
|
+
} catch {
|
|
243
|
+
return false;
|
|
244
|
+
}
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
/** Field 22 of /proc/<pid>/stat, the process start time; undefined where /proc is missing. */
|
|
248
|
+
export function startTime(pid: number): string | undefined {
|
|
249
|
+
try {
|
|
250
|
+
const stat = readFileSync(`/proc/${pid}/stat`, "utf8");
|
|
251
|
+
return stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19];
|
|
252
|
+
} catch {
|
|
253
|
+
return undefined;
|
|
254
|
+
}
|
|
255
|
+
}
|
package/src/project.ts
ADDED
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import { existsSync, readFileSync, statSync } from "node:fs";
|
|
2
|
+
import { basename, dirname, resolve } from "node:path";
|
|
3
|
+
import { openReadingLock } from "./reading-lock.ts";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* A reading's project (S19): the folder name of the Git root its working folder is in, else of the working folder
|
|
7
|
+
* itself. The root is the nearest folder upward holding a `.git`, found without running git. A `.git` file names its
|
|
8
|
+
* gitdir: a linked worktree's holds `commondir`, so it is the same repo and is named by the folder of the main
|
|
9
|
+
* `.git`; a submodule's does not, so it keeps its own folder name.
|
|
10
|
+
*/
|
|
11
|
+
export function projectOf(cwd: string): string {
|
|
12
|
+
const start = resolve(cwd);
|
|
13
|
+
for (let dir = start; ; dir = dirname(dir)) {
|
|
14
|
+
const git = resolve(dir, ".git");
|
|
15
|
+
if (existsSync(git)) return mainRepo(dir, git) ?? (basename(dir) || dir);
|
|
16
|
+
if (dirname(dir) === dir) return basename(start) || start;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** For a linked worktree (its `.git` a file whose gitdir holds `commondir`), the main repository's folder name. */
|
|
21
|
+
function mainRepo(dir: string, git: string): string | undefined {
|
|
22
|
+
try {
|
|
23
|
+
if (!statSync(git).isFile()) return undefined;
|
|
24
|
+
const gitdir = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(git, "utf8"))?.[1];
|
|
25
|
+
if (!gitdir) return undefined;
|
|
26
|
+
const resolved = resolve(dir, gitdir);
|
|
27
|
+
const common = readFileSync(resolve(resolved, "commondir"), "utf8").trim();
|
|
28
|
+
if (!common) return undefined;
|
|
29
|
+
const main = dirname(resolve(resolved, common));
|
|
30
|
+
return basename(main) || undefined;
|
|
31
|
+
} catch {
|
|
32
|
+
return undefined;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Records `project` as the machine's last reading's (S19) and says whether it must be announced: it differs from the
|
|
38
|
+
* one remembered, or none was. The memory is shared next to the reading lock by every Pi session and the
|
|
39
|
+
* `reply-reader` command; without a usable XDG_RUNTIME_DIR it is `local`, the caller's own (a process's).
|
|
40
|
+
*/
|
|
41
|
+
export function projectChanged(env: NodeJS.ProcessEnv, project: string, local: { last?: string }): boolean {
|
|
42
|
+
const lock = openReadingLock(env);
|
|
43
|
+
const previous = lock ? lock.swapProject(project) : local.last;
|
|
44
|
+
if (!lock) local.last = project;
|
|
45
|
+
return previous !== project;
|
|
46
|
+
}
|