@cbxss/eoka 0.1.0-beta.11 → 0.1.0-beta.13
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 +89 -10
- package/dist/action-failure.d.ts +2 -0
- package/dist/action-failure.js +99 -0
- package/dist/browser.d.ts +2 -0
- package/dist/browser.js +12 -4
- package/dist/call-site.d.ts +5 -0
- package/dist/call-site.js +46 -0
- package/dist/duration.d.ts +3 -0
- package/dist/duration.js +10 -0
- package/dist/errors.d.ts +3 -1
- package/dist/errors.js +4 -1
- package/dist/generated/catalog.d.ts +102 -0
- package/dist/generated/catalog.js +90 -0
- package/dist/generated/protocol.d.ts +3223 -1456
- package/dist/generated/protocol.js +2 -2
- package/dist/generated/schema-bundle.json +14521 -6967
- package/dist/index.d.ts +2 -2
- package/dist/operations.js +2 -0
- package/dist/page-blockers.d.ts +7 -0
- package/dist/page-blockers.js +54 -0
- package/dist/page.d.ts +16 -2
- package/dist/page.js +63 -9
- package/dist/recording.js +2 -0
- package/dist/release-manifest.json +18 -18
- package/dist/transport.d.ts +7 -0
- package/dist/transport.js +98 -19
- package/package.json +6 -6
package/dist/transport.js
CHANGED
|
@@ -4,20 +4,51 @@ import { join } from 'node:path';
|
|
|
4
4
|
import { Ajv2020 } from 'ajv/dist/2020.js';
|
|
5
5
|
import bundle from './generated/schema-bundle.json' with { type: 'json' };
|
|
6
6
|
import { protocolVersion } from './generated/protocol.js';
|
|
7
|
+
import { traced } from './call-site.js';
|
|
8
|
+
import { duration, maximumTimer, serverGraceMs } from './duration.js';
|
|
7
9
|
import { ConfigurationError, EokaError, ProtocolError, ServerOperationError, TransportError } from './errors.js';
|
|
8
10
|
const contracts = bundle.methods;
|
|
9
11
|
let ajv;
|
|
10
12
|
const validators = new Map();
|
|
13
|
+
const waitFields = new Map();
|
|
14
|
+
const waitName = /^(?:ms|timeout|settle_ms|\w*timeout_?ms)$/i;
|
|
11
15
|
const localMessageLimit = 32 * 1024 * 1024;
|
|
12
16
|
const localPendingLimit = 128;
|
|
17
|
+
const responseWriteReserve = 1;
|
|
18
|
+
const resendFrameLimit = 1024 * 1024;
|
|
19
|
+
const intakeBusyMessage = 'maxInFlight pending requests exceeded';
|
|
13
20
|
const stderrLimit = 16 * 1024;
|
|
14
|
-
const
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
21
|
+
const groupExitGraceMs = 5_000;
|
|
22
|
+
const groupExitPollMs = 10;
|
|
23
|
+
export const defaultCallTimeoutMs = 120_000;
|
|
24
|
+
function collectWaitFields(root, schema, path, fields) {
|
|
25
|
+
const candidate = schema.anyOf?.find(item => item.$ref !== undefined || item.properties !== undefined) ?? schema;
|
|
26
|
+
const definition = candidate.$ref === undefined ? candidate : root.$defs?.[candidate.$ref.replace('#/$defs/', '')] ?? candidate;
|
|
27
|
+
for (const [name, property] of Object.entries(definition.properties ?? {})) {
|
|
28
|
+
if (typeof property === 'boolean')
|
|
29
|
+
continue;
|
|
30
|
+
if (waitName.test(name))
|
|
31
|
+
fields.push({ path: [...path, name], fallback: typeof property.default === 'number' ? property.default : 0 });
|
|
32
|
+
else if (path.length === 0)
|
|
33
|
+
collectWaitFields(root, property, [name], fields);
|
|
19
34
|
}
|
|
20
|
-
|
|
35
|
+
}
|
|
36
|
+
function requestedServerWait(method, params) {
|
|
37
|
+
let fields = waitFields.get(method);
|
|
38
|
+
if (!fields) {
|
|
39
|
+
fields = [];
|
|
40
|
+
if (Object.hasOwn(contracts, method))
|
|
41
|
+
collectWaitFields(contracts[method].params, contracts[method].params, [], fields);
|
|
42
|
+
waitFields.set(method, fields);
|
|
43
|
+
}
|
|
44
|
+
let total = 0;
|
|
45
|
+
for (const field of fields) {
|
|
46
|
+
let value = params;
|
|
47
|
+
for (const key of field.path)
|
|
48
|
+
value = object(value) ? value[key] : undefined;
|
|
49
|
+
total += typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : field.fallback;
|
|
50
|
+
}
|
|
51
|
+
return total;
|
|
21
52
|
}
|
|
22
53
|
function secretMatcher(values) {
|
|
23
54
|
const alternatives = new Set();
|
|
@@ -82,6 +113,7 @@ function operationEvidence(record, expectedId) {
|
|
|
82
113
|
export class SidecarTransport {
|
|
83
114
|
child;
|
|
84
115
|
shutdownTimeoutMs;
|
|
116
|
+
defaultTimeoutMs;
|
|
85
117
|
pending = new Map();
|
|
86
118
|
decoder = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true });
|
|
87
119
|
greeting;
|
|
@@ -89,6 +121,7 @@ export class SidecarTransport {
|
|
|
89
121
|
nextId = 1;
|
|
90
122
|
messageLimit = localMessageLimit;
|
|
91
123
|
pendingLimit = localPendingLimit;
|
|
124
|
+
inFlight = 0;
|
|
92
125
|
frame = Buffer.alloc(0);
|
|
93
126
|
frameLength = 0;
|
|
94
127
|
queuedBytes = 0;
|
|
@@ -106,16 +139,18 @@ export class SidecarTransport {
|
|
|
106
139
|
cleanupError;
|
|
107
140
|
closeCompletion;
|
|
108
141
|
teardownTimer;
|
|
142
|
+
closeDeadline = Number.POSITIVE_INFINITY;
|
|
109
143
|
shutdownId;
|
|
110
144
|
closed = Promise.withResolvers();
|
|
111
145
|
terminationConfirmed = false;
|
|
112
146
|
shutdownAcknowledged = false;
|
|
113
147
|
childClosed = false;
|
|
114
148
|
windowsTreeTerminated = false;
|
|
115
|
-
constructor(child, shutdownTimeoutMs, secrets) {
|
|
149
|
+
constructor(child, shutdownTimeoutMs, defaultTimeoutMs, secrets) {
|
|
116
150
|
void this.closed.promise.catch(() => { });
|
|
117
151
|
this.child = child;
|
|
118
152
|
this.shutdownTimeoutMs = shutdownTimeoutMs;
|
|
153
|
+
this.defaultTimeoutMs = defaultTimeoutMs;
|
|
119
154
|
this.secrets = secrets;
|
|
120
155
|
child.stdout.on('data', this.onData);
|
|
121
156
|
child.stdout.on('end', this.onEnd);
|
|
@@ -131,6 +166,9 @@ export class SidecarTransport {
|
|
|
131
166
|
static async start(options) {
|
|
132
167
|
const timeoutMs = duration(options.timeoutMs, 30_000, 'timeoutMs');
|
|
133
168
|
const shutdownTimeoutMs = duration(options.shutdownTimeoutMs, 45_000, 'shutdownTimeoutMs');
|
|
169
|
+
const defaultTimeoutMs = options.defaultTimeoutMs === null ? undefined : duration(options.defaultTimeoutMs, defaultCallTimeoutMs, 'defaultTimeoutMs');
|
|
170
|
+
if (defaultTimeoutMs === 0)
|
|
171
|
+
throw new ConfigurationError('defaultTimeoutMs must be positive; pass null to disable it', { requestState: 'not_sent' });
|
|
134
172
|
const secrets = secretMatcher(options.redactionValues ?? []);
|
|
135
173
|
if (!options.serverPath)
|
|
136
174
|
throw new ConfigurationError('An explicit serverPath is required', { requestState: 'not_sent' });
|
|
@@ -143,7 +181,7 @@ export class SidecarTransport {
|
|
|
143
181
|
catch (cause) {
|
|
144
182
|
throw new TransportError('Spawn', 'Could not spawn the sidecar', { cause, requestState: 'not_sent' });
|
|
145
183
|
}
|
|
146
|
-
const transport = new SidecarTransport(child, shutdownTimeoutMs, secrets);
|
|
184
|
+
const transport = new SidecarTransport(child, shutdownTimeoutMs, defaultTimeoutMs, secrets);
|
|
147
185
|
try {
|
|
148
186
|
options.onTransport?.(transport);
|
|
149
187
|
const hello = await transport.request('server.hello', { protocol: protocolVersion }, { timeoutMs, ...(options.signal === undefined ? {} : { signal: options.signal }) });
|
|
@@ -161,7 +199,7 @@ export class SidecarTransport {
|
|
|
161
199
|
transport.greeting = hello;
|
|
162
200
|
transport.supported = new Set(hello.methods);
|
|
163
201
|
transport.messageLimit = Math.min(localMessageLimit, hello.limits.maxMessageBytes);
|
|
164
|
-
transport.pendingLimit = Math.min(localPendingLimit, hello.limits.maxInFlight);
|
|
202
|
+
transport.pendingLimit = Math.max(1, Math.min(localPendingLimit, hello.limits.maxInFlight) - responseWriteReserve);
|
|
165
203
|
if (transport.frameLength > transport.messageLimit)
|
|
166
204
|
throw new ProtocolError('Buffered peer frame exceeds negotiated limit');
|
|
167
205
|
return transport;
|
|
@@ -248,7 +286,7 @@ export class SidecarTransport {
|
|
|
248
286
|
try {
|
|
249
287
|
const data = params;
|
|
250
288
|
operationId = options.operationId ?? (object(data) && typeof data.operation_id === 'string' ? data.operation_id : typeof method === 'string' && method.startsWith('operations.') && object(data) && typeof data.id === 'string' ? data.id : undefined);
|
|
251
|
-
const timeoutMs = options.timeoutMs === undefined ?
|
|
289
|
+
const timeoutMs = options.timeoutMs === undefined ? this.fallbackTimeout(method, params, cleanup) : duration(options.timeoutMs, 0, 'timeoutMs');
|
|
252
290
|
const deadline = timeoutMs === undefined ? undefined : performance.now() + timeoutMs;
|
|
253
291
|
const details = { operationId, requestState: 'not_sent' };
|
|
254
292
|
if (this.closing || this.failure || (this.quiescing && !cleanup))
|
|
@@ -259,8 +297,6 @@ export class SidecarTransport {
|
|
|
259
297
|
throw new TransportError('DeadlineExceeded', 'Request deadline expired before dispatch', details);
|
|
260
298
|
if (!Object.hasOwn(contracts, method) || (this.greeting && !this.supported.has(method)))
|
|
261
299
|
throw new TransportError('UnsupportedMethod', `Sidecar does not support ${method}`, details);
|
|
262
|
-
if (method !== 'server.shutdown' && this.pending.size >= this.pendingLimit)
|
|
263
|
-
throw new TransportError('PendingLimit', 'Sidecar in-flight request limit reached', details);
|
|
264
300
|
if (this.nextId > Number.MAX_SAFE_INTEGER)
|
|
265
301
|
throw new TransportError('RequestIdExhausted', 'Safe request IDs have been exhausted', details);
|
|
266
302
|
try {
|
|
@@ -289,15 +325,17 @@ export class SidecarTransport {
|
|
|
289
325
|
this.pending.set(id, current);
|
|
290
326
|
this.queuedBytes += frame.length;
|
|
291
327
|
if (options.signal) {
|
|
292
|
-
current.abort = () => this.cancel(current, 'Aborted', options.signal?.reason);
|
|
328
|
+
current.abort = () => this.cancel(current, 'Aborted', `${method} was aborted locally`, options.signal?.reason);
|
|
293
329
|
options.signal.addEventListener('abort', current.abort, { once: true });
|
|
294
330
|
}
|
|
295
331
|
if (deadline !== undefined) {
|
|
332
|
+
const origin = options.timeoutMs !== undefined ? 'local deadline' : timeoutMs === this.defaultTimeoutMs ? 'default deadline (defaultTimeoutMs)' : `default deadline (its server-side wait plus ${serverGraceMs} ms)`;
|
|
333
|
+
const expired = `${method} exceeded ${options.timeoutMs === undefined ? 'the' : 'its'} ${timeoutMs} ms ${origin}`;
|
|
296
334
|
const remaining = deadline - performance.now();
|
|
297
335
|
if (remaining <= 0)
|
|
298
|
-
this.cancel(current, 'DeadlineExceeded');
|
|
336
|
+
this.cancel(current, 'DeadlineExceeded', expired);
|
|
299
337
|
else
|
|
300
|
-
current.timer = setTimeout(() => this.cancel(current, 'DeadlineExceeded'), remaining);
|
|
338
|
+
current.timer = setTimeout(() => this.cancel(current, 'DeadlineExceeded', expired), remaining);
|
|
301
339
|
}
|
|
302
340
|
if (this.pending.has(current.id) && (method === 'server.shutdown' || method === 'browser.close'))
|
|
303
341
|
void this.beginClose(current).catch(() => { });
|
|
@@ -317,6 +355,12 @@ export class SidecarTransport {
|
|
|
317
355
|
return Promise.reject(error);
|
|
318
356
|
}
|
|
319
357
|
}
|
|
358
|
+
fallbackTimeout(method, params, cleanup) {
|
|
359
|
+
if (this.defaultTimeoutMs === undefined || cleanup || method === 'server.shutdown' || method === 'browser.close')
|
|
360
|
+
return undefined;
|
|
361
|
+
const serverWait = requestedServerWait(method, params);
|
|
362
|
+
return serverWait === 0 ? this.defaultTimeoutMs : Math.min(maximumTimer, Math.max(this.defaultTimeoutMs, serverWait + serverGraceMs));
|
|
363
|
+
}
|
|
320
364
|
details(entry, stderr = this.stderr) {
|
|
321
365
|
return { requestId: entry.id, operationId: entry.operationId, requestState: entry.sent ? 'may_have_been_sent' : 'not_sent', stderr };
|
|
322
366
|
}
|
|
@@ -333,16 +377,19 @@ export class SidecarTransport {
|
|
|
333
377
|
if (entry.frame)
|
|
334
378
|
this.queuedBytes -= entry.frame.length;
|
|
335
379
|
entry.frame = undefined;
|
|
336
|
-
|
|
380
|
+
entry.resend = undefined;
|
|
381
|
+
if (this.pending.delete(entry.id) && entry.sent)
|
|
382
|
+
this.inFlight--;
|
|
337
383
|
}
|
|
338
|
-
cancel(entry, code, cause) {
|
|
384
|
+
cancel(entry, code, reason, cause) {
|
|
339
385
|
if (!entry.reject)
|
|
340
386
|
return;
|
|
341
387
|
const reject = entry.reject;
|
|
342
388
|
this.detach(entry);
|
|
343
389
|
entry.reject = undefined;
|
|
344
390
|
entry.resolve = undefined;
|
|
345
|
-
|
|
391
|
+
entry.resend = undefined;
|
|
392
|
+
const error = new TransportError(code, entry.sent ? `${reason} after possible dispatch; the action was not rolled back` : `${reason} before dispatch`, { ...this.details(entry), cause });
|
|
346
393
|
reject(error);
|
|
347
394
|
if (!entry.sent) {
|
|
348
395
|
entry.completion?.reject(error);
|
|
@@ -355,10 +402,14 @@ export class SidecarTransport {
|
|
|
355
402
|
for (const entry of this.pending.values()) {
|
|
356
403
|
if (!entry.frame)
|
|
357
404
|
continue;
|
|
405
|
+
if (this.inFlight >= this.pendingLimit)
|
|
406
|
+
break;
|
|
358
407
|
const frame = entry.frame;
|
|
359
408
|
this.queuedBytes -= frame.length;
|
|
360
409
|
entry.frame = undefined;
|
|
410
|
+
entry.resend = frame.length <= resendFrameLimit ? frame : undefined;
|
|
361
411
|
entry.sent = true;
|
|
412
|
+
this.inFlight++;
|
|
362
413
|
try {
|
|
363
414
|
if (!this.child.stdin.write(frame)) {
|
|
364
415
|
this.blocked = true;
|
|
@@ -453,6 +504,14 @@ export class SidecarTransport {
|
|
|
453
504
|
receiptEvidence(wireError.data.receipt);
|
|
454
505
|
if (entry.operationId && wireError.data?.operation_id && entry.operationId !== wireError.data.operation_id)
|
|
455
506
|
throw new ProtocolError('Server error has a different operation ID');
|
|
507
|
+
if (wireError.code === 'ServerBusy' && wireError.message === intakeBusyMessage && entry.resend && entry.reject && this.inFlight > 1 && !this.closing) {
|
|
508
|
+
this.inFlight--;
|
|
509
|
+
this.pendingLimit = this.inFlight;
|
|
510
|
+
this.queuedBytes += entry.resend.length;
|
|
511
|
+
entry.frame = entry.resend;
|
|
512
|
+
entry.sent = false;
|
|
513
|
+
return;
|
|
514
|
+
}
|
|
456
515
|
const error = new ServerOperationError(wireError, details);
|
|
457
516
|
if (entry.id === this.shutdownId)
|
|
458
517
|
this.cleanupError = error;
|
|
@@ -482,6 +541,8 @@ export class SidecarTransport {
|
|
|
482
541
|
this.remove(entry);
|
|
483
542
|
if (entry.id === this.shutdownId && entry.method === 'browser.close')
|
|
484
543
|
this.child.stdin.end();
|
|
544
|
+
else
|
|
545
|
+
this.flush();
|
|
485
546
|
}
|
|
486
547
|
rejectPending(error) {
|
|
487
548
|
let stderr;
|
|
@@ -497,6 +558,7 @@ export class SidecarTransport {
|
|
|
497
558
|
}
|
|
498
559
|
entry.reject = undefined;
|
|
499
560
|
entry.resolve = undefined;
|
|
561
|
+
entry.resend = undefined;
|
|
500
562
|
this.detach(entry);
|
|
501
563
|
if (!entry.sent)
|
|
502
564
|
this.remove(entry);
|
|
@@ -552,10 +614,22 @@ export class SidecarTransport {
|
|
|
552
614
|
this.finishClose();
|
|
553
615
|
}
|
|
554
616
|
else if (process.platform !== 'win32' && this.ownedGroupAlive())
|
|
555
|
-
|
|
617
|
+
this.awaitGroupExit(Math.min(this.closeDeadline, performance.now() + groupExitGraceMs));
|
|
556
618
|
else
|
|
557
619
|
this.finishClose();
|
|
558
620
|
};
|
|
621
|
+
awaitGroupExit(deadline) {
|
|
622
|
+
if (this.finished || this.escalating)
|
|
623
|
+
return;
|
|
624
|
+
clearTimeout(this.teardownTimer);
|
|
625
|
+
this.teardownTimer = undefined;
|
|
626
|
+
if (!this.ownedGroupAlive())
|
|
627
|
+
this.finishClose();
|
|
628
|
+
else if (performance.now() >= deadline)
|
|
629
|
+
void this.terminate();
|
|
630
|
+
else
|
|
631
|
+
this.teardownTimer = setTimeout(() => this.awaitGroupExit(deadline), groupExitPollMs);
|
|
632
|
+
}
|
|
559
633
|
close() {
|
|
560
634
|
return this.beginClose();
|
|
561
635
|
}
|
|
@@ -581,6 +655,7 @@ export class SidecarTransport {
|
|
|
581
655
|
this.queuedBytes -= frame.length;
|
|
582
656
|
terminal.frame = undefined;
|
|
583
657
|
terminal.sent = true;
|
|
658
|
+
this.inFlight++;
|
|
584
659
|
if (terminal.method === 'browser.close')
|
|
585
660
|
this.child.stdin.write(frame);
|
|
586
661
|
else
|
|
@@ -590,6 +665,7 @@ export class SidecarTransport {
|
|
|
590
665
|
const id = this.nextId++;
|
|
591
666
|
this.shutdownId = id;
|
|
592
667
|
this.pending.set(id, { id, method: 'server.shutdown', operationId: undefined, sent: true, frame: undefined, resolve: undefined, reject: undefined, signal: undefined, abort: undefined, timer: undefined });
|
|
668
|
+
this.inFlight++;
|
|
593
669
|
this.child.stdin.end(`${JSON.stringify({ id, method: 'server.shutdown', params: {} })}\n`);
|
|
594
670
|
}
|
|
595
671
|
else
|
|
@@ -598,6 +674,7 @@ export class SidecarTransport {
|
|
|
598
674
|
catch (cause) {
|
|
599
675
|
this.cleanupError ??= new TransportError('ShutdownWrite', 'Could not send sidecar shutdown; cleanup may be incomplete', { cause, stderr: this.stderr });
|
|
600
676
|
}
|
|
677
|
+
this.closeDeadline = performance.now() + this.shutdownTimeoutMs;
|
|
601
678
|
this.teardownTimer = setTimeout(() => { void this.terminate(); }, this.shutdownTimeoutMs);
|
|
602
679
|
return this.closeCompletion.promise;
|
|
603
680
|
}
|
|
@@ -735,3 +812,5 @@ export class SidecarTransport {
|
|
|
735
812
|
}
|
|
736
813
|
}
|
|
737
814
|
}
|
|
815
|
+
SidecarTransport.start = traced(SidecarTransport.start);
|
|
816
|
+
SidecarTransport.prototype.invoke = traced(SidecarTransport.prototype.invoke);
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@cbxss/eoka",
|
|
3
|
-
"version": "0.1.0-beta.
|
|
3
|
+
"version": "0.1.0-beta.13",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"description": "Node.js SDK with pinned Chrome installation and verified eoka sidecar resolution",
|
|
@@ -58,11 +58,11 @@
|
|
|
58
58
|
"typescript": "6.0.3"
|
|
59
59
|
},
|
|
60
60
|
"optionalDependencies": {
|
|
61
|
-
"@cbxss/eoka-server-linux-x64-gnu": "0.1.0-beta.
|
|
62
|
-
"@cbxss/eoka-server-linux-arm64-gnu": "0.1.0-beta.
|
|
63
|
-
"@cbxss/eoka-server-darwin-x64": "0.1.0-beta.
|
|
64
|
-
"@cbxss/eoka-server-darwin-arm64": "0.1.0-beta.
|
|
65
|
-
"@cbxss/eoka-server-win32-x64": "0.1.0-beta.
|
|
61
|
+
"@cbxss/eoka-server-linux-x64-gnu": "0.1.0-beta.13",
|
|
62
|
+
"@cbxss/eoka-server-linux-arm64-gnu": "0.1.0-beta.13",
|
|
63
|
+
"@cbxss/eoka-server-darwin-x64": "0.1.0-beta.13",
|
|
64
|
+
"@cbxss/eoka-server-darwin-arm64": "0.1.0-beta.13",
|
|
65
|
+
"@cbxss/eoka-server-win32-x64": "0.1.0-beta.13"
|
|
66
66
|
},
|
|
67
67
|
"repository": {
|
|
68
68
|
"type": "git",
|