@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/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 maximumTimer = 2_147_483_647;
15
- function duration(value, fallback, name) {
16
- const result = value ?? fallback;
17
- if (!Number.isFinite(result) || result < 0 || result > maximumTimer) {
18
- throw new ConfigurationError(`${name} must be finite and between 0 and ${maximumTimer}`, { requestState: 'not_sent' });
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
- return result;
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 ? undefined : duration(options.timeoutMs, 0, 'timeoutMs');
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
- this.pending.delete(entry.id);
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
- const error = new TransportError(code, entry.sent ? 'Local request cancelled after possible dispatch; the action was not rolled back' : 'Local request cancelled before dispatch', { ...this.details(entry), cause });
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
- void this.terminate();
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.11",
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.11",
62
- "@cbxss/eoka-server-linux-arm64-gnu": "0.1.0-beta.11",
63
- "@cbxss/eoka-server-darwin-x64": "0.1.0-beta.11",
64
- "@cbxss/eoka-server-darwin-arm64": "0.1.0-beta.11",
65
- "@cbxss/eoka-server-win32-x64": "0.1.0-beta.11"
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",