@narumitw/pi-sync-daemon 0.3.0 → 0.4.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 +10 -0
- package/dist/client.d.ts +21 -1
- package/dist/client.js +175 -21
- package/dist/index.d.ts +1 -1
- package/dist/protocol.d.ts +14 -0
- package/dist/protocol.js +7 -0
- package/dist/server.js +146 -11
- package/docs/architecture.md +21 -1
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# @narumitw/pi-sync-daemon
|
|
2
2
|
|
|
3
|
+
## 0.4.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 223b0ba: Restore a live Pi session after its heartbeat expires without reloading Pi. The
|
|
8
|
+
daemon distinguishes heartbeat expiry from deliberate disconnection and keeps
|
|
9
|
+
file-queue and session protection in place. Pi Sync reconnects to the same owner
|
|
10
|
+
without resubmitting interrupted operations, and checks participation before
|
|
11
|
+
reporting that it is connected.
|
|
12
|
+
|
|
3
13
|
## 0.3.0
|
|
4
14
|
|
|
5
15
|
### Minor Changes
|
package/dist/client.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type RuntimePaths } from "./identity.js";
|
|
2
|
-
import { type Callback, type ClientEvent, type ClientFacts, type ClientHandoff, type Identity, type RemoteError } from "./protocol.js";
|
|
2
|
+
import { type Callback, type ClientEvent, type ClientFacts, type ClientHandoff, type ClientContact as ContactState, type Identity, type RemoteError } from "./protocol.js";
|
|
3
3
|
export declare class DaemonError extends Error {
|
|
4
4
|
readonly remote: RemoteError;
|
|
5
5
|
constructor(remote: RemoteError);
|
|
@@ -23,6 +23,8 @@ export interface ConnectionOptions {
|
|
|
23
23
|
callback(callback: Callback, signal: AbortSignal): Promise<unknown>;
|
|
24
24
|
event?(event: ClientEvent): void;
|
|
25
25
|
error?(error: unknown): void;
|
|
26
|
+
/** Each current background observation after admission, including repeated states. */
|
|
27
|
+
contact?(state: ContactState): void;
|
|
26
28
|
}
|
|
27
29
|
export declare class DaemonConnection {
|
|
28
30
|
readonly paths: RuntimePaths;
|
|
@@ -36,17 +38,35 @@ export declare class DaemonConnection {
|
|
|
36
38
|
private callbackTasks;
|
|
37
39
|
private updates;
|
|
38
40
|
private attached;
|
|
41
|
+
private admitting;
|
|
42
|
+
private observedContact;
|
|
43
|
+
private contactRevision;
|
|
44
|
+
private lifecycleRevision;
|
|
45
|
+
private resuming;
|
|
46
|
+
private resumeUncertain;
|
|
47
|
+
private pendingJobs;
|
|
39
48
|
private uncertain;
|
|
40
49
|
private reportedError;
|
|
41
50
|
private commits;
|
|
42
51
|
private completedCallbacks;
|
|
52
|
+
private pausing;
|
|
43
53
|
private disposing;
|
|
44
54
|
private polling;
|
|
45
55
|
private closed;
|
|
46
56
|
constructor(paths: RuntimePaths, identity: Identity, facts: ClientFacts, options: ConnectionOptions);
|
|
57
|
+
/** Latest owner observation, or undefined if contact is unsupported or not observed. */
|
|
58
|
+
get contactState(): ContactState | undefined;
|
|
59
|
+
/** An uncertain attempt must not be retried or turned into a new attach. */
|
|
60
|
+
get contactResumeState(): "idle" | "running" | "uncertain";
|
|
61
|
+
/** Original submitted jobs must finish (or be reconciled) before repairing contact. */
|
|
62
|
+
get hasPendingWork(): boolean;
|
|
47
63
|
attach(signal?: AbortSignal): Promise<this>;
|
|
48
64
|
update(facts: ClientFacts): Promise<void>;
|
|
65
|
+
/** Resume this participant without replacing its callbacks, jobs, or polling. */
|
|
66
|
+
resumeContact(facts: ClientFacts, signal?: AbortSignal): Promise<void>;
|
|
67
|
+
private sameClient;
|
|
49
68
|
run(operation: string, payload: unknown, signal?: AbortSignal, onCommit?: () => void): Promise<unknown>;
|
|
69
|
+
private publishContact;
|
|
50
70
|
private consume;
|
|
51
71
|
private performCallback;
|
|
52
72
|
private wait;
|
package/dist/client.js
CHANGED
|
@@ -47,9 +47,9 @@ export async function requestDaemon(paths, identity, method, params, signal) {
|
|
|
47
47
|
})
|
|
48
48
|
.catch(reject);
|
|
49
49
|
});
|
|
50
|
-
//
|
|
51
|
-
// cancels that wait; an idle timeout must not let
|
|
52
|
-
request.setTimeout(method === "attach" ? 0 : 30_000, () => request.destroy(new Error("Daemon request timed out.")));
|
|
50
|
+
// Admission can wait behind a complete apply. The request owner's signal
|
|
51
|
+
// cancels that wait; an idle timeout must not let admission escape the fence.
|
|
52
|
+
request.setTimeout(method === "attach" || method === "resume-contact" ? 0 : 30_000, () => request.destroy(new Error("Daemon request timed out.")));
|
|
53
53
|
request.once("error", reject);
|
|
54
54
|
request.end(body);
|
|
55
55
|
});
|
|
@@ -226,10 +226,18 @@ export class DaemonConnection {
|
|
|
226
226
|
callbackTasks = new Set();
|
|
227
227
|
updates = Promise.resolve();
|
|
228
228
|
attached = false;
|
|
229
|
+
admitting = false;
|
|
230
|
+
observedContact;
|
|
231
|
+
contactRevision = 0;
|
|
232
|
+
lifecycleRevision = 0;
|
|
233
|
+
resuming;
|
|
234
|
+
resumeUncertain = false;
|
|
235
|
+
pendingJobs = 0;
|
|
229
236
|
uncertain = false;
|
|
230
237
|
reportedError = false;
|
|
231
238
|
commits = new Map();
|
|
232
239
|
completedCallbacks = new Set();
|
|
240
|
+
pausing;
|
|
233
241
|
disposing;
|
|
234
242
|
polling;
|
|
235
243
|
closed = false;
|
|
@@ -239,9 +247,29 @@ export class DaemonConnection {
|
|
|
239
247
|
this.facts = facts;
|
|
240
248
|
this.options = options;
|
|
241
249
|
}
|
|
250
|
+
/** Latest owner observation, or undefined if contact is unsupported or not observed. */
|
|
251
|
+
get contactState() {
|
|
252
|
+
return this.observedContact;
|
|
253
|
+
}
|
|
254
|
+
/** An uncertain attempt must not be retried or turned into a new attach. */
|
|
255
|
+
get contactResumeState() {
|
|
256
|
+
return this.resumeUncertain ? "uncertain" : this.resuming ? "running" : "idle";
|
|
257
|
+
}
|
|
258
|
+
/** Original submitted jobs must finish (or be reconciled) before repairing contact. */
|
|
259
|
+
get hasPendingWork() {
|
|
260
|
+
return this.pendingJobs > 0 || this.uncertain;
|
|
261
|
+
}
|
|
242
262
|
async attach(signal) {
|
|
243
|
-
if (this.closed ||
|
|
263
|
+
if (this.closed ||
|
|
264
|
+
this.hasPendingWork ||
|
|
265
|
+
this.contactResumeState !== "idle" ||
|
|
266
|
+
this.admitting ||
|
|
267
|
+
this.pausing ||
|
|
268
|
+
this.disposing)
|
|
244
269
|
throw new Error("Daemon client is unavailable; reconnect after draining work.");
|
|
270
|
+
this.admitting = true;
|
|
271
|
+
this.lifecycleRevision++;
|
|
272
|
+
this.contactRevision++;
|
|
245
273
|
const request = requestDaemon(this.paths, this.identity, "attach", this.facts, signal ? AbortSignal.any([signal, this.controller.signal]) : this.controller.signal);
|
|
246
274
|
// Poll during attach: stopping a previous controller may need release answers
|
|
247
275
|
// from this reattached participant before the attach response can complete.
|
|
@@ -250,7 +278,7 @@ export class DaemonConnection {
|
|
|
250
278
|
try {
|
|
251
279
|
const result = await request;
|
|
252
280
|
admitted = true;
|
|
253
|
-
this.consume(result);
|
|
281
|
+
this.publishContact(this.consume(result));
|
|
254
282
|
this.attached = true;
|
|
255
283
|
return this;
|
|
256
284
|
}
|
|
@@ -279,24 +307,111 @@ export class DaemonConnection {
|
|
|
279
307
|
}
|
|
280
308
|
});
|
|
281
309
|
}
|
|
310
|
+
finally {
|
|
311
|
+
this.admitting = false;
|
|
312
|
+
}
|
|
282
313
|
}
|
|
283
|
-
update(facts) {
|
|
314
|
+
async update(facts) {
|
|
315
|
+
const lifecycle = this.lifecycleRevision;
|
|
316
|
+
if (this.admitting || this.pausing || this.disposing)
|
|
317
|
+
throw new Error("Daemon client is changing; wait before updating facts.");
|
|
284
318
|
const update = this.updates.then(async () => {
|
|
285
|
-
if (this.closed || this.uncertain)
|
|
319
|
+
if (this.closed || this.uncertain || this.resumeUncertain || lifecycle !== this.lifecycleRevision)
|
|
286
320
|
throw new Error("Daemon client is unavailable; reconnect after draining work.");
|
|
287
|
-
const
|
|
321
|
+
const revision = this.contactRevision;
|
|
322
|
+
let result;
|
|
323
|
+
try {
|
|
324
|
+
result = await requestDaemon(this.paths, this.identity, "update", { facts }, this.controller.signal);
|
|
325
|
+
}
|
|
326
|
+
catch (error) {
|
|
327
|
+
if (this.attached &&
|
|
328
|
+
revision === this.contactRevision &&
|
|
329
|
+
this.sameClient(facts) &&
|
|
330
|
+
error instanceof DaemonError &&
|
|
331
|
+
error.remote.name === "ClientContactExpiredError")
|
|
332
|
+
this.publishContact("expired");
|
|
333
|
+
throw error;
|
|
334
|
+
}
|
|
288
335
|
if (this.closed)
|
|
289
336
|
throw new Error("Daemon client closed during update.");
|
|
337
|
+
if (revision !== this.contactRevision)
|
|
338
|
+
throw new Error("Daemon client changed during update.");
|
|
339
|
+
const contact = this.consume(result);
|
|
340
|
+
if (revision !== this.contactRevision)
|
|
341
|
+
throw new Error("Daemon client changed during update.");
|
|
290
342
|
Object.assign(this.facts, facts);
|
|
291
|
-
this.
|
|
343
|
+
this.publishContact(contact);
|
|
292
344
|
});
|
|
293
345
|
this.updates = update.catch(() => { });
|
|
294
346
|
return update;
|
|
295
347
|
}
|
|
348
|
+
/** Resume this participant without replacing its callbacks, jobs, or polling. */
|
|
349
|
+
async resumeContact(facts, signal) {
|
|
350
|
+
signal?.throwIfAborted();
|
|
351
|
+
if (this.contactResumeState !== "idle")
|
|
352
|
+
throw new Error("Daemon contact resume is running or uncertain.");
|
|
353
|
+
const check = () => {
|
|
354
|
+
if (!this.attached || this.admitting || this.pausing || this.disposing || this.closed || this.hasPendingWork)
|
|
355
|
+
throw new Error("Daemon client is unavailable; reconnect after draining work.");
|
|
356
|
+
if (!this.sameClient(facts) || this.contactState !== "expired")
|
|
357
|
+
throw new Error("No confirmed contact expiry for this daemon client.");
|
|
358
|
+
};
|
|
359
|
+
facts = structuredClone(facts);
|
|
360
|
+
check();
|
|
361
|
+
const resume = new AbortController();
|
|
362
|
+
this.resuming = resume;
|
|
363
|
+
const ownedSignal = signal ? AbortSignal.any([signal, resume.signal]) : resume.signal;
|
|
364
|
+
let sent = false;
|
|
365
|
+
const attempt = this.updates.then(async () => {
|
|
366
|
+
ownedSignal.throwIfAborted();
|
|
367
|
+
check();
|
|
368
|
+
sent = true;
|
|
369
|
+
const reply = await requestDaemon(this.paths, this.identity, "resume-contact", facts, ownedSignal);
|
|
370
|
+
ownedSignal.throwIfAborted();
|
|
371
|
+
const contact = this.consume(reply);
|
|
372
|
+
ownedSignal.throwIfAborted();
|
|
373
|
+
if (contact !== "active")
|
|
374
|
+
throw new Error("Daemon did not confirm resumed contact.");
|
|
375
|
+
Object.assign(this.facts, facts);
|
|
376
|
+
this.publishContact(contact);
|
|
377
|
+
});
|
|
378
|
+
this.updates = attempt.catch(() => { });
|
|
379
|
+
// Reject a queued repair on cancellation even if the earlier update has not finished.
|
|
380
|
+
const cancellation = Promise.withResolvers();
|
|
381
|
+
const abort = () => cancellation.reject(ownedSignal.reason);
|
|
382
|
+
ownedSignal.addEventListener("abort", abort, { once: true });
|
|
383
|
+
try {
|
|
384
|
+
await Promise.race([attempt, cancellation.promise]);
|
|
385
|
+
}
|
|
386
|
+
catch (error) {
|
|
387
|
+
if (sent) {
|
|
388
|
+
// The protocol does not distinguish definite pre-publication refusal from a lost acknowledgement.
|
|
389
|
+
this.resumeUncertain = true;
|
|
390
|
+
for (const { controller, kind } of this.callbacks.values())
|
|
391
|
+
if (kind !== "queue-release")
|
|
392
|
+
controller.abort();
|
|
393
|
+
}
|
|
394
|
+
throw error;
|
|
395
|
+
}
|
|
396
|
+
finally {
|
|
397
|
+
this.resuming = undefined;
|
|
398
|
+
ownedSignal.removeEventListener("abort", abort);
|
|
399
|
+
}
|
|
400
|
+
}
|
|
401
|
+
sameClient(facts) {
|
|
402
|
+
return facts.id === this.facts.id && facts.pid === this.facts.pid && facts.generation === this.facts.generation;
|
|
403
|
+
}
|
|
296
404
|
async run(operation, payload, signal, onCommit) {
|
|
297
|
-
if (this.closed ||
|
|
298
|
-
|
|
405
|
+
if (this.closed ||
|
|
406
|
+
this.uncertain ||
|
|
407
|
+
this.contactResumeState !== "idle" ||
|
|
408
|
+
this.pausing ||
|
|
409
|
+
this.disposing ||
|
|
410
|
+
this.contactState === "expired" ||
|
|
411
|
+
this.contactState === "inactive")
|
|
412
|
+
throw new Error("Daemon client is unavailable; confirm contact and drain work before submitting.");
|
|
299
413
|
signal?.throwIfAborted();
|
|
414
|
+
this.pendingJobs++;
|
|
300
415
|
const id = `${operationPrefix(this.identity)}${randomUUID()}`;
|
|
301
416
|
const abort = () => {
|
|
302
417
|
void requestDaemon(this.paths, this.identity, "cancel", { id, client: this.facts.id }, this.controller.signal).catch(() => { });
|
|
@@ -313,11 +428,11 @@ export class DaemonConnection {
|
|
|
313
428
|
const reply = await requestDaemon(this.paths, this.identity, "poll", { client: this.facts.id, cursor: this.cursor, job: id }, this.controller.signal);
|
|
314
429
|
this.consume(reply);
|
|
315
430
|
const job = record(reply) ? reply.job : undefined;
|
|
316
|
-
if (job?.phase === "failed") {
|
|
431
|
+
if (job?.id === id && job.phase === "failed") {
|
|
317
432
|
terminal = true;
|
|
318
433
|
throw new DaemonError(job.error ?? { name: "Error", message: "Daemon operation failed." });
|
|
319
434
|
}
|
|
320
|
-
if (job?.phase === "done") {
|
|
435
|
+
if (job?.id === id && job.phase === "done") {
|
|
321
436
|
terminal = true;
|
|
322
437
|
signal?.throwIfAborted();
|
|
323
438
|
return job.result;
|
|
@@ -343,7 +458,11 @@ export class DaemonConnection {
|
|
|
343
458
|
throw new Error("Operation outcome is uncertain; reload to reconnect and reconcile, never replay the write.", { cause: error });
|
|
344
459
|
}
|
|
345
460
|
}
|
|
346
|
-
});
|
|
461
|
+
}).finally(() => this.pendingJobs--);
|
|
462
|
+
}
|
|
463
|
+
publishContact(contact) {
|
|
464
|
+
this.contactRevision++;
|
|
465
|
+
this.observedContact = contact;
|
|
347
466
|
}
|
|
348
467
|
consume(reply) {
|
|
349
468
|
if (!record(reply) ||
|
|
@@ -353,8 +472,11 @@ export class DaemonConnection {
|
|
|
353
472
|
!Array.isArray(reply.callbacks) ||
|
|
354
473
|
!Array.isArray(reply.events))
|
|
355
474
|
throw new Error("Invalid daemon poll response.");
|
|
475
|
+
const { contact } = reply;
|
|
476
|
+
if (contact !== undefined && contact !== "active" && contact !== "expired" && contact !== "inactive")
|
|
477
|
+
throw new Error("Invalid daemon contact state.");
|
|
356
478
|
if (reply.cursor < this.cursor)
|
|
357
|
-
return;
|
|
479
|
+
return contact;
|
|
358
480
|
for (const event of reply.events)
|
|
359
481
|
if (event.id > this.cursor) {
|
|
360
482
|
if (event.kind === "commit" && record(event.payload) && typeof event.payload.job === "string") {
|
|
@@ -381,7 +503,7 @@ export class DaemonConnection {
|
|
|
381
503
|
let value;
|
|
382
504
|
let failed = false;
|
|
383
505
|
try {
|
|
384
|
-
if (this.uncertain && callback.kind !== "queue-release")
|
|
506
|
+
if ((this.uncertain || this.resumeUncertain) && callback.kind !== "queue-release")
|
|
385
507
|
throw new Error("Client is draining uncertain work.");
|
|
386
508
|
value = await this.performCallback(callback, controller.signal);
|
|
387
509
|
}
|
|
@@ -406,6 +528,7 @@ export class DaemonConnection {
|
|
|
406
528
|
});
|
|
407
529
|
this.callbackTasks.add(task);
|
|
408
530
|
}
|
|
531
|
+
return contact;
|
|
409
532
|
}
|
|
410
533
|
async performCallback(callback, signal) {
|
|
411
534
|
const reference = callback.review;
|
|
@@ -475,9 +598,25 @@ export class DaemonConnection {
|
|
|
475
598
|
async poll() {
|
|
476
599
|
while (!this.closed) {
|
|
477
600
|
try {
|
|
601
|
+
const revision = this.contactRevision;
|
|
478
602
|
const reply = await requestDaemon(this.paths, this.identity, "poll", { client: this.facts.id, cursor: this.cursor }, this.controller.signal);
|
|
479
|
-
|
|
480
|
-
this.
|
|
603
|
+
// An older poll must not undo typed update expiry or a successful resume.
|
|
604
|
+
if (revision === this.contactRevision) {
|
|
605
|
+
const contact = this.consume(reply);
|
|
606
|
+
this.reportedError = false;
|
|
607
|
+
if (revision === this.contactRevision &&
|
|
608
|
+
this.attached &&
|
|
609
|
+
!this.admitting &&
|
|
610
|
+
!this.pausing &&
|
|
611
|
+
!this.disposing &&
|
|
612
|
+
!this.closed) {
|
|
613
|
+
// A new observation fences older facts replies; identical polls do not.
|
|
614
|
+
if (contact !== this.observedContact)
|
|
615
|
+
this.publishContact(contact);
|
|
616
|
+
if (contact !== undefined)
|
|
617
|
+
this.options.contact?.(contact);
|
|
618
|
+
}
|
|
619
|
+
}
|
|
481
620
|
await this.wait(100);
|
|
482
621
|
}
|
|
483
622
|
catch (error) {
|
|
@@ -495,16 +634,31 @@ export class DaemonConnection {
|
|
|
495
634
|
}
|
|
496
635
|
}
|
|
497
636
|
async pause() {
|
|
498
|
-
if (this.closed)
|
|
637
|
+
if (this.closed || this.disposing)
|
|
499
638
|
throw new Error("Daemon client is closed.");
|
|
500
|
-
|
|
501
|
-
|
|
639
|
+
if (this.pausing)
|
|
640
|
+
return this.pausing;
|
|
641
|
+
this.resuming?.abort(new DOMException("Client paused", "AbortError"));
|
|
642
|
+
this.lifecycleRevision++;
|
|
643
|
+
this.contactRevision++;
|
|
644
|
+
this.pausing = (async () => {
|
|
645
|
+
const reply = await requestDaemon(this.paths, this.identity, "pause", { client: this.facts.id });
|
|
646
|
+
const contact = this.consume(reply);
|
|
647
|
+
if (!this.disposing)
|
|
648
|
+
this.publishContact(contact);
|
|
649
|
+
})().finally(() => {
|
|
650
|
+
this.pausing = undefined;
|
|
651
|
+
});
|
|
652
|
+
return this.pausing;
|
|
502
653
|
}
|
|
503
654
|
async dispose(handoff) {
|
|
504
655
|
if (this.disposing)
|
|
505
656
|
return this.disposing;
|
|
506
657
|
if (this.closed)
|
|
507
658
|
return;
|
|
659
|
+
this.resuming?.abort(new DOMException("Client disposed", "AbortError"));
|
|
660
|
+
this.lifecycleRevision++;
|
|
661
|
+
this.contactRevision++;
|
|
508
662
|
this.disposing = (async () => {
|
|
509
663
|
this.polling ??= this.poll();
|
|
510
664
|
// Cancel UI before drain, but keep polling for acknowledged queue-release callbacks.
|
package/dist/index.d.ts
CHANGED
|
@@ -4,5 +4,5 @@ export type { DocumentView } from "./document.js";
|
|
|
4
4
|
export { documentFingerprint } from "./document.js";
|
|
5
5
|
export type { EngineContext, EngineHost, EngineSession, ReviewRequest } from "./engine/host.js";
|
|
6
6
|
export { modelSignature } from "./model-signature.js";
|
|
7
|
-
export type { Callback, ClientEvent, ClientFacts, ClientHandoff, Identity, JobView, RemoteError } from "./protocol.js";
|
|
7
|
+
export type { Callback, ClientContact as ContactState, ClientEvent, ClientFacts, ClientHandoff, Identity, JobView, RemoteError, } from "./protocol.js";
|
|
8
8
|
export { MAX_SETTINGS_BYTES, PROTOCOL_VERSION } from "./protocol.js";
|
package/dist/protocol.d.ts
CHANGED
|
@@ -5,6 +5,11 @@ export declare class DaemonStoppingError extends Error {
|
|
|
5
5
|
name: string;
|
|
6
6
|
constructor();
|
|
7
7
|
}
|
|
8
|
+
/** This owner expired this client's heartbeat; a normal facts update cannot restore participation. */
|
|
9
|
+
export declare class ClientContactExpiredError extends Error {
|
|
10
|
+
name: string;
|
|
11
|
+
constructor();
|
|
12
|
+
}
|
|
8
13
|
export declare const MAX_MESSAGE_BYTES: number;
|
|
9
14
|
export declare const REVIEW_PAGE_CHARS: number;
|
|
10
15
|
export declare const MAX_REVIEW_BYTES: number;
|
|
@@ -79,6 +84,15 @@ export interface JobView {
|
|
|
79
84
|
result?: unknown;
|
|
80
85
|
error?: RemoteError;
|
|
81
86
|
}
|
|
87
|
+
export type ClientContact = "active" | "expired" | "inactive";
|
|
88
|
+
export interface PollReply {
|
|
89
|
+
cursor: number;
|
|
90
|
+
callbacks: Callback[];
|
|
91
|
+
events: ClientEvent[];
|
|
92
|
+
job?: JobView;
|
|
93
|
+
/** Absent on owners without protocol-v1 contact resume support. */
|
|
94
|
+
contact?: ClientContact;
|
|
95
|
+
}
|
|
82
96
|
export interface Execution {
|
|
83
97
|
readonly root: string;
|
|
84
98
|
readonly clientId: string | undefined;
|
package/dist/protocol.js
CHANGED
|
@@ -8,6 +8,13 @@ export class DaemonStoppingError extends Error {
|
|
|
8
8
|
super("Daemon is closing after its idle grace period; wait for owner exit before reconnecting.");
|
|
9
9
|
}
|
|
10
10
|
}
|
|
11
|
+
/** This owner expired this client's heartbeat; a normal facts update cannot restore participation. */
|
|
12
|
+
export class ClientContactExpiredError extends Error {
|
|
13
|
+
name = "ClientContactExpiredError";
|
|
14
|
+
constructor() {
|
|
15
|
+
super("Client contact expired; resume the same session before publishing facts.");
|
|
16
|
+
}
|
|
17
|
+
}
|
|
11
18
|
export const MAX_MESSAGE_BYTES = 4 * 1024 * 1024;
|
|
12
19
|
export const REVIEW_PAGE_CHARS = 64 * 1024;
|
|
13
20
|
export const MAX_REVIEW_BYTES = 16 * 1024 * 1024;
|
package/dist/server.js
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { createHash, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
|
|
2
|
+
import { addAbortListener } from "node:events";
|
|
2
3
|
import fs from "node:fs/promises";
|
|
3
4
|
import { createServer } from "node:http";
|
|
4
5
|
import path from "node:path";
|
|
@@ -8,7 +9,7 @@ import { canonicalRootGuard, daemonPaths, privateDirectory, processExists, publi
|
|
|
8
9
|
import { createIdleExit } from "./idle-exit.js";
|
|
9
10
|
import { withCleanup } from "./lifecycle.js";
|
|
10
11
|
import { ParticipantAdmission } from "./participant-admission.js";
|
|
11
|
-
import { DaemonStoppingError, MAX_MESSAGE_BYTES, MAX_REVIEW_BYTES, operationPrefix, PROTOCOL_VERSION, REVIEW_PAGE_CHARS, record, remoteError, validateFacts, validateHandoff, validId, } from "./protocol.js";
|
|
12
|
+
import { ClientContactExpiredError, DaemonStoppingError, MAX_MESSAGE_BYTES, MAX_REVIEW_BYTES, operationPrefix, PROTOCOL_VERSION, REVIEW_PAGE_CHARS, record, remoteError, validateFacts, validateHandoff, validId, } from "./protocol.js";
|
|
12
13
|
export async function startServer(root, execute, hooks = {}) {
|
|
13
14
|
const base = await runtimePaths(root);
|
|
14
15
|
const identity = {
|
|
@@ -50,6 +51,7 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
50
51
|
const peersFile = path.join(paths.directory, "clients.json");
|
|
51
52
|
let sequence = 0;
|
|
52
53
|
let closed = false;
|
|
54
|
+
let stopRequested = false;
|
|
53
55
|
let automaticClosing = false;
|
|
54
56
|
let peerWriteFailed = false;
|
|
55
57
|
let idleExit;
|
|
@@ -59,23 +61,23 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
59
61
|
let closing;
|
|
60
62
|
let peerWrites = Promise.resolve();
|
|
61
63
|
let heartbeat;
|
|
62
|
-
function savePeers() {
|
|
64
|
+
function savePeers(candidate) {
|
|
63
65
|
idleExit?.changed();
|
|
64
|
-
const operation = peerWrites.then(writePeers);
|
|
66
|
+
const operation = peerWrites.then(() => writePeers(candidate));
|
|
65
67
|
peerWrites = operation.catch(() => {
|
|
66
68
|
peerWriteFailed = true;
|
|
67
69
|
hooks.failure?.();
|
|
68
70
|
});
|
|
69
71
|
return operation;
|
|
70
72
|
}
|
|
71
|
-
async function writePeers() {
|
|
73
|
+
async function writePeers(candidate) {
|
|
72
74
|
const temporary = path.join(paths.directory, `.${randomUUID()}.clients`);
|
|
73
75
|
const data = {
|
|
74
76
|
version: 1,
|
|
75
77
|
root: paths.root,
|
|
76
78
|
clients: [...participants.values()]
|
|
77
79
|
.filter((peer) => processExists(peer.facts.pid))
|
|
78
|
-
.map((peer) => ({ ...peer.facts, handoff: peer.handoff })),
|
|
80
|
+
.map((peer) => ({ ...(candidate?.peer === peer ? candidate.facts : peer.facts), handoff: peer.handoff })),
|
|
79
81
|
};
|
|
80
82
|
const handle = await fs.open(temporary, "wx", 0o600);
|
|
81
83
|
try {
|
|
@@ -186,8 +188,16 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
186
188
|
const liveClientFacts = () => [...participants.values()].filter((peer) => processExists(peer.facts.pid)).map((peer) => peer.facts);
|
|
187
189
|
const participantFacts = () => [...participants.values()]
|
|
188
190
|
.filter((peer) => !peer.publishing && (peer.connected || peer.suspected) && processExists(peer.facts.pid))
|
|
189
|
-
.map((peer) =>
|
|
191
|
+
.map((peer) => peer.closing || peer.suspected ? { ...(peer.resumeFacts ?? peer.facts), idle: false } : peer.facts);
|
|
192
|
+
const contactState = (peer) => {
|
|
193
|
+
if (closed || stopRequested || compromised || peer.publishing || peer.closing || !processExists(peer.facts.pid))
|
|
194
|
+
return "inactive";
|
|
195
|
+
if (peer.connected)
|
|
196
|
+
return "active";
|
|
197
|
+
return peer.expiry ? "expired" : "inactive";
|
|
198
|
+
};
|
|
190
199
|
const poll = (peer, cursor, job) => ({
|
|
200
|
+
contact: contactState(peer),
|
|
191
201
|
cursor: sequence,
|
|
192
202
|
callbacks: [...peer.callbacks.values()],
|
|
193
203
|
events: peer.events.filter((event) => event.id > (typeof cursor === "number" && Number.isSafeInteger(cursor) ? cursor : 0)),
|
|
@@ -238,6 +248,18 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
238
248
|
Buffer.byteLength(JSON.stringify([...peer.callbacks.values(), callback])) > MAX_MESSAGE_BYTES / 8)
|
|
239
249
|
throw new Error("Callback exceeds its byte limit; no review was approved.");
|
|
240
250
|
job.peers.add(target);
|
|
251
|
+
const reservation = record(data) && typeof data.reservation === "string" ? data.reservation : undefined;
|
|
252
|
+
if (kind === "queue-acquire" || cleanup) {
|
|
253
|
+
// A lost acquire response is not proof that Pi never acquired the queue.
|
|
254
|
+
// Bound retained evidence even if a failing or malformed executor keeps requesting grants.
|
|
255
|
+
peer.reservations ??= new Set();
|
|
256
|
+
if (!reservation)
|
|
257
|
+
peer.resumeUnsafe = true;
|
|
258
|
+
else if (peer.reservations.size < 64)
|
|
259
|
+
peer.reservations.add(reservation);
|
|
260
|
+
else if (!peer.reservations.has(reservation))
|
|
261
|
+
peer.resumeUnsafe = true;
|
|
262
|
+
}
|
|
241
263
|
return new Promise((resolve, reject) => {
|
|
242
264
|
let timer;
|
|
243
265
|
const effectiveSignal = cleanup ? undefined : signal;
|
|
@@ -249,6 +271,8 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
249
271
|
if (!pending.delete(callback.id))
|
|
250
272
|
return;
|
|
251
273
|
peer.callbacks.delete(callback.id);
|
|
274
|
+
if (cleanup && reservation && error === undefined && value === true)
|
|
275
|
+
peer.reservations?.delete(reservation);
|
|
252
276
|
sequence++;
|
|
253
277
|
if (error)
|
|
254
278
|
reject(error);
|
|
@@ -344,6 +368,12 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
344
368
|
.catch((error) => {
|
|
345
369
|
job.view.phase = "failed";
|
|
346
370
|
job.view.error = remoteError(error);
|
|
371
|
+
if (job.committed)
|
|
372
|
+
for (const id of new Set([client, ...job.peers])) {
|
|
373
|
+
const affected = participants.get(id);
|
|
374
|
+
if (affected)
|
|
375
|
+
affected.resumeUnsafe = true;
|
|
376
|
+
}
|
|
347
377
|
})
|
|
348
378
|
.finally(() => {
|
|
349
379
|
for (const waiting of [...pending.values()])
|
|
@@ -355,16 +385,93 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
355
385
|
jobs.set(id, job);
|
|
356
386
|
return job;
|
|
357
387
|
}
|
|
388
|
+
function invalidateExpiry(peer) {
|
|
389
|
+
peer.expiry?.abort(new DOMException("Client is no longer eligible to resume contact", "AbortError"));
|
|
390
|
+
peer.expiry = undefined;
|
|
391
|
+
peer.resumeFacts = undefined;
|
|
392
|
+
}
|
|
393
|
+
async function resumeContact(facts, disconnect) {
|
|
394
|
+
const peer = requireParticipant(facts.id, true);
|
|
395
|
+
const expiry = peer.expiry;
|
|
396
|
+
const matchesSession = (old) => old.pid === facts.pid &&
|
|
397
|
+
old.generation === facts.generation &&
|
|
398
|
+
old.cwd === facts.cwd &&
|
|
399
|
+
old.sessionId === facts.sessionId &&
|
|
400
|
+
old.sessionFile === facts.sessionFile &&
|
|
401
|
+
old.sessionDir === facts.sessionDir &&
|
|
402
|
+
old.mode === facts.mode &&
|
|
403
|
+
old.hasUI === facts.hasUI;
|
|
404
|
+
if (!expiry || contactState(peer) !== "expired" || peer.resumeFacts || !matchesSession(peer.facts))
|
|
405
|
+
throw new Error("Client is not eligible to resume contact for this session.");
|
|
406
|
+
const signal = disconnect ? AbortSignal.any([disconnect, expiry.signal]) : expiry.signal;
|
|
407
|
+
const candidate = structuredClone(facts);
|
|
408
|
+
const recheck = () => {
|
|
409
|
+
assertOwner();
|
|
410
|
+
signal.throwIfAborted();
|
|
411
|
+
if (peerWriteFailed)
|
|
412
|
+
throw new Error("Daemon client ledger persistence is uncertain; reconcile with the existing owner before reconnecting.");
|
|
413
|
+
if (participants.get(facts.id) !== peer ||
|
|
414
|
+
peer.expiry !== expiry ||
|
|
415
|
+
contactState(peer) !== "expired" ||
|
|
416
|
+
!matchesSession(peer.facts))
|
|
417
|
+
throw new Error("Client is no longer eligible to resume contact.");
|
|
418
|
+
};
|
|
419
|
+
const affected = (job) => job.client === facts.id || job.peers.has(facts.id);
|
|
420
|
+
const running = (job) => affected(job) && job.view.phase === "running";
|
|
421
|
+
const stopped = Promise.withResolvers();
|
|
422
|
+
const abort = addAbortListener(signal, () => stopped.reject(signal.reason));
|
|
423
|
+
try {
|
|
424
|
+
recheck();
|
|
425
|
+
// Expose the new binding to the monitor, but only as a non-ready, busy suspect.
|
|
426
|
+
peer.resumeFacts = { ...candidate, ready: false };
|
|
427
|
+
// Never wait for jobs or monitor transitions inside admission: they can need the fence.
|
|
428
|
+
await Promise.race([
|
|
429
|
+
Promise.all([hooks.factsChanged?.(), ...[...jobs.values()].filter(running).map((job) => job.promise)]),
|
|
430
|
+
stopped.promise,
|
|
431
|
+
]);
|
|
432
|
+
recheck();
|
|
433
|
+
return await admission.run(async () => {
|
|
434
|
+
const safe = () => {
|
|
435
|
+
recheck();
|
|
436
|
+
if (peer.resumeUnsafe ||
|
|
437
|
+
peer.reservations?.size ||
|
|
438
|
+
peer.callbacks.size ||
|
|
439
|
+
[...jobs.values()].some(running) ||
|
|
440
|
+
[...backgroundJobs].some((job) => job.committed && affected(job)))
|
|
441
|
+
throw new Error("Client work or file-queue cleanup is uncertain; reconcile with the existing owner before reconnecting.");
|
|
442
|
+
};
|
|
443
|
+
safe();
|
|
444
|
+
// The staged facts have the same location and identity. Even if cancelled mid-write,
|
|
445
|
+
// the on-disk record does not authorize work or confer expiry eligibility on restart.
|
|
446
|
+
await savePeers({ peer, facts: candidate });
|
|
447
|
+
safe();
|
|
448
|
+
peer.facts = candidate;
|
|
449
|
+
peer.seen = Date.now();
|
|
450
|
+
peer.expiry = undefined;
|
|
451
|
+
peer.resumeFacts = undefined;
|
|
452
|
+
peer.suspected = false;
|
|
453
|
+
peer.connected = true;
|
|
454
|
+
hooks.idle?.();
|
|
455
|
+
return poll(peer, 0);
|
|
456
|
+
}, signal);
|
|
457
|
+
}
|
|
458
|
+
finally {
|
|
459
|
+
abort[Symbol.dispose]();
|
|
460
|
+
if (peer.expiry === expiry)
|
|
461
|
+
peer.resumeFacts = undefined;
|
|
462
|
+
}
|
|
463
|
+
}
|
|
358
464
|
async function detach(id, retain = false, handoff) {
|
|
359
465
|
const peer = participants.get(id);
|
|
360
466
|
if (!peer) {
|
|
361
467
|
if (closedClients.size < 10_000)
|
|
362
468
|
closedClients.add(id);
|
|
363
|
-
return { cursor: sequence, callbacks: [], events: [] };
|
|
469
|
+
return { contact: "inactive", cursor: sequence, callbacks: [], events: [] };
|
|
364
470
|
}
|
|
365
471
|
if (closedClients.has(id))
|
|
366
472
|
return poll(peer, 0);
|
|
367
473
|
peer.closing = true;
|
|
474
|
+
invalidateExpiry(peer);
|
|
368
475
|
for (const waiting of [...pending.values()])
|
|
369
476
|
if (waiting.target === id && !waiting.callback.kind.startsWith("queue-"))
|
|
370
477
|
waiting.reject(new Error("Client detaching."));
|
|
@@ -416,8 +523,12 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
416
523
|
(old.facts.pid !== params.pid ||
|
|
417
524
|
((old.connected || old.suspected) && old.facts.generation !== params.generation)))
|
|
418
525
|
throw new Error("Client identity collision.");
|
|
526
|
+
if (old)
|
|
527
|
+
invalidateExpiry(old);
|
|
419
528
|
participants.set(params.id, {
|
|
420
529
|
facts: structuredClone(params),
|
|
530
|
+
reservations: old?.reservations,
|
|
531
|
+
resumeUnsafe: old?.resumeUnsafe,
|
|
421
532
|
callbacks: old?.callbacks ?? new Map(),
|
|
422
533
|
events: old?.events ?? [],
|
|
423
534
|
connected: true,
|
|
@@ -464,6 +575,10 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
464
575
|
assertOwner();
|
|
465
576
|
return poll(attached, 0);
|
|
466
577
|
}
|
|
578
|
+
if (method === "resume-contact") {
|
|
579
|
+
validateFacts(params);
|
|
580
|
+
return resumeContact(params, signal);
|
|
581
|
+
}
|
|
467
582
|
if (!record(params))
|
|
468
583
|
throw new Error("Invalid request parameters.");
|
|
469
584
|
const contact = typeof params.client === "string" ? participants.get(params.client) : undefined;
|
|
@@ -476,10 +591,13 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
476
591
|
}
|
|
477
592
|
if (method === "update") {
|
|
478
593
|
validateFacts(params.facts);
|
|
479
|
-
const peer = requireParticipant(params.facts.id);
|
|
594
|
+
const peer = requireParticipant(params.facts.id, true);
|
|
480
595
|
const old = peer.facts;
|
|
481
596
|
if (old.pid !== params.facts.pid || old.generation !== params.facts.generation)
|
|
482
597
|
throw new Error("Client generation mismatch.");
|
|
598
|
+
if (contactState(peer) === "expired")
|
|
599
|
+
throw new ClientContactExpiredError();
|
|
600
|
+
requireParticipant(params.facts.id);
|
|
483
601
|
peer.facts = structuredClone(params.facts);
|
|
484
602
|
const published = peer.facts;
|
|
485
603
|
try {
|
|
@@ -491,7 +609,15 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
491
609
|
throw error;
|
|
492
610
|
}
|
|
493
611
|
await hooks.factsChanged?.();
|
|
494
|
-
|
|
612
|
+
assertOwner();
|
|
613
|
+
if (participants.get(params.facts.id) !== peer)
|
|
614
|
+
throw new Error("Client changed during update.");
|
|
615
|
+
const reply = poll(peer, 0);
|
|
616
|
+
if (reply.contact === "expired")
|
|
617
|
+
throw new ClientContactExpiredError();
|
|
618
|
+
if (reply.contact !== "active")
|
|
619
|
+
throw new Error("Client is not attached or is closing.");
|
|
620
|
+
return reply;
|
|
495
621
|
}
|
|
496
622
|
if (["detach", "pause", "handoff"].includes(method)) {
|
|
497
623
|
if (!validId(params.client))
|
|
@@ -564,6 +690,7 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
564
690
|
return job.view;
|
|
565
691
|
}
|
|
566
692
|
if (method === "stop") {
|
|
693
|
+
stopRequested = true;
|
|
567
694
|
setImmediate(() => {
|
|
568
695
|
void close().catch(() => { });
|
|
569
696
|
});
|
|
@@ -600,12 +727,14 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
600
727
|
respond(response, 403, { error: { name: "Error", message: "Invalid daemon identity or protocol." } });
|
|
601
728
|
return;
|
|
602
729
|
}
|
|
603
|
-
if (body.method === "attach") {
|
|
730
|
+
if (body.method === "attach" || body.method === "resume-contact") {
|
|
604
731
|
admissionController = new AbortController();
|
|
605
732
|
response.once("close", disconnect);
|
|
733
|
+
if (response.destroyed)
|
|
734
|
+
disconnect();
|
|
606
735
|
}
|
|
607
736
|
const operation = handle(body.method, body.params, admissionController?.signal);
|
|
608
|
-
if (["attach", "update", "detach", "pause", "handoff"].includes(body.method)) {
|
|
737
|
+
if (["attach", "resume-contact", "update", "detach", "pause", "handoff"].includes(body.method)) {
|
|
609
738
|
peerOperations.add(operation);
|
|
610
739
|
void operation.finally(() => peerOperations.delete(operation)).catch(() => { });
|
|
611
740
|
}
|
|
@@ -652,6 +781,10 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
652
781
|
continue;
|
|
653
782
|
peer.connected = false;
|
|
654
783
|
peer.suspected = !exited;
|
|
784
|
+
if (exited)
|
|
785
|
+
invalidateExpiry(peer);
|
|
786
|
+
else if (!peer.closing && !peer.publishing)
|
|
787
|
+
peer.expiry = new AbortController();
|
|
655
788
|
changed = true;
|
|
656
789
|
for (const job of [...jobs.values(), ...backgroundJobs])
|
|
657
790
|
if (!job.committed && (job.client === id || job.peers.has(id)))
|
|
@@ -730,6 +863,8 @@ export async function startServer(root, execute, hooks = {}) {
|
|
|
730
863
|
return closing;
|
|
731
864
|
closing = (async () => {
|
|
732
865
|
closed = true;
|
|
866
|
+
for (const peer of participants.values())
|
|
867
|
+
invalidateExpiry(peer);
|
|
733
868
|
clearInterval(heartbeat);
|
|
734
869
|
for (const waiting of [...pending.values()])
|
|
735
870
|
if (!waiting.callback.kind.startsWith("queue-"))
|
package/docs/architecture.md
CHANGED
|
@@ -105,7 +105,27 @@ After grace, stop new automatic work and cancel cancellable work. Drain foregrou
|
|
|
105
105
|
|
|
106
106
|
After quiescence, the authenticated final fence returns `RemoteError.name = "DaemonStoppingError"` to rejected admissions and handshakes on the existing version-1 protocol. `ensureDaemon()` recognizes only this error and waits at most 30 seconds for the recorded PID to exit before singleton startup. The lightweight public `waitForDaemonExit(identity, signal)` helper provides the same cancellable process-exit check for an attach race; it never kills the owner or treats lost contact as exit. Pi Sync retries only an unpublished connection, at most once, and does not replay submitted operations. A rejected first attach preserves this stopping error after local disposal when no callbacks or prior attachment can own grants; a failed cleanup transport remains available as the error cause. Other combined attach and cleanup failures remain aggregate errors and do not authorize a retry. `DaemonConnection.attach(signal)` cancels queued admission without stopping the shared owner; the signal does not own the established connection's lifetime. The next eligible interactive client or explicit command may start after proven owner exit. An incompatible identity, uncertain ownership, or unreachable live owner still fails closed. Print/JSON never launch a service. Manual stop and restart retain explicit behavior. Authorization uncertainty and failed revocation remain paused, not cleared by an implicit restart that could restore an older persisted grant.
|
|
107
107
|
|
|
108
|
-
A later command can reconnect after a cancelled or failed unpublished attach. First, Pi Sync confirms the old connection's detach and drain, then releases its local queue grants. It uses a fresh client ID and generation for the next connection. Daemon retirement records stay intact, so late requests cannot revive the old attempt. Failed cleanup blocks a new identity and operation; it does not release uncertain grants.
|
|
108
|
+
A later command can reconnect after a cancelled or failed unpublished attach. First, Pi Sync confirms the old connection's detach and drain, then releases its local queue grants. It uses a fresh client ID and generation for the next connection. Daemon retirement records stay intact, so late requests cannot revive the old attempt. Failed cleanup blocks a new identity and operation; it does not release uncertain grants. A cancelled or submitted operation is never replayed by this recovery.
|
|
109
|
+
|
|
110
|
+
### Recovering expired contact
|
|
111
|
+
|
|
112
|
+
A running daemon can expire a Pi session's heartbeat after a computer sleeps. A
|
|
113
|
+
cleanup poll still returns callbacks and job results. Its optional version-1
|
|
114
|
+
`contact` field distinguishes `expired` from `active` and `inactive`. Only a
|
|
115
|
+
heartbeat expired by this daemon instance gets `expired`. A facts update from
|
|
116
|
+
the matching expired client returns `ClientContactExpiredError`. An older
|
|
117
|
+
service can omit `contact`, which does not authorize repair.
|
|
118
|
+
|
|
119
|
+
`DaemonConnection.resumeContact()` sends the same client's current facts to
|
|
120
|
+
the authenticated owner with `resume-contact`. The daemon retains the existing
|
|
121
|
+
participant, protects the live session, and fences publication with the same
|
|
122
|
+
admission gate used by attach. Deliberate pauses, handoffs, retired identities,
|
|
123
|
+
and peers loaded from disk are not eligible. Cleanup polling stays available
|
|
124
|
+
while admission waits. Unknown work outcomes and unconfirmed queue releases
|
|
125
|
+
block repair. Pi Sync supplies non-ready, busy facts during admission, then
|
|
126
|
+
publishes fresh facts after confirmation. The binding and consent checks still
|
|
127
|
+
apply. A failed or uncertain repair does not start a replacement owner, release
|
|
128
|
+
uncertain grants, or resubmit work.
|
|
109
129
|
|
|
110
130
|
## Repository lifetime smoke
|
|
111
131
|
|