@deviltea/widget-inspector 0.0.4 → 0.1.1

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/channel.mjs CHANGED
@@ -1,6 +1,17 @@
1
1
  //#region src/channel.ts
2
2
  const MESSAGE_PORT_CHANNEL_TYPE = "@deviltea/widget-inspector/message-port-channel";
3
3
  const MESSAGE_PORT_CHANNEL_HUB_TYPE = "@deviltea/widget-inspector/message-port-channel-hub";
4
+ /**
5
+ * A message that arrives for a channel nobody has subscribed to yet (the peer opened it first) is buffered,
6
+ * at most this many per channel; beyond that the OLDEST buffered message is dropped. The latest messages
7
+ * matter most for a request/response protocol whose peer retries, and a flood cannot grow memory.
8
+ */
9
+ const MAX_BUFFERED_MESSAGES_PER_CHANNEL = 64;
10
+ /**
11
+ * At most this many channel names the local side has not opened yet may hold state for the peer. A message
12
+ * for any further unknown name is dropped without creating state, so a peer cannot grow the map without bound.
13
+ */
14
+ const MAX_UNOPENED_CHANNELS = 16;
4
15
  function cloneJson(message) {
5
16
  const serialized = JSON.stringify(message);
6
17
  if (serialized === void 0) throw new TypeError("MessagePort channel messages must be JSON-serializable.");
@@ -26,21 +37,26 @@ function isHubCloseEnvelope(value) {
26
37
  function createMessagePortChannelHub(port) {
27
38
  const states = /* @__PURE__ */ new Map();
28
39
  let closed = false;
29
- function stateFor(name) {
30
- let state = states.get(name);
31
- if (state === void 0) {
32
- state = {
33
- messageListeners: /* @__PURE__ */ new Set(),
34
- closeListeners: /* @__PURE__ */ new Set(),
35
- closed
36
- };
37
- states.set(name, state);
38
- }
39
- return state;
40
+ function createState() {
41
+ return {
42
+ messageListeners: /* @__PURE__ */ new Set(),
43
+ closeListeners: /* @__PURE__ */ new Set(),
44
+ buffer: [],
45
+ closed: false,
46
+ opened: false,
47
+ closedByPeer: false,
48
+ flushScheduled: false
49
+ };
50
+ }
51
+ function unopenedCount() {
52
+ let count = 0;
53
+ for (const state of states.values()) if (!state.opened && !state.closed) count++;
54
+ return count;
40
55
  }
41
56
  function markChannelClosed(state) {
42
57
  if (state.closed) return;
43
58
  state.closed = true;
59
+ state.buffer.length = 0;
44
60
  state.messageListeners.clear();
45
61
  const listeners = [...state.closeListeners];
46
62
  state.closeListeners.clear();
@@ -65,13 +81,49 @@ function createMessagePortChannelHub(port) {
65
81
  }
66
82
  if (!isEnvelope(event.data)) return;
67
83
  const envelope = event.data;
68
- const state = stateFor(envelope.channel);
69
- if (state.closed) return;
84
+ let state = states.get(envelope.channel);
70
85
  if (envelope.kind === "close") {
71
- markChannelClosed(state);
86
+ if (state === void 0 || state.closed) return;
87
+ if (state.opened) {
88
+ state.closedByPeer = true;
89
+ markChannelClosed(state);
90
+ } else states.delete(envelope.channel);
72
91
  return;
73
92
  }
74
- for (const listener of [...state.messageListeners]) listener(envelope.payload);
93
+ if (state === void 0 || state.closed && state.closedByPeer) {
94
+ if (state === void 0 && unopenedCount() >= MAX_UNOPENED_CHANNELS) return;
95
+ state = createState();
96
+ states.set(envelope.channel, state);
97
+ } else if (state.closed) return;
98
+ deliver(state, envelope.payload);
99
+ }
100
+ /** Delivers buffered messages, in order, to whoever is subscribed when it runs. */
101
+ function flush(state) {
102
+ state.flushScheduled = false;
103
+ while (state.buffer.length > 0 && state.messageListeners.size > 0 && !state.closed) {
104
+ const message = state.buffer.shift();
105
+ for (const listener of [...state.messageListeners]) try {
106
+ listener(message);
107
+ } catch (error) {
108
+ queueMicrotask(() => {
109
+ throw error;
110
+ });
111
+ }
112
+ }
113
+ }
114
+ function scheduleFlush(state) {
115
+ if (state.flushScheduled) return;
116
+ state.flushScheduled = true;
117
+ queueMicrotask(() => flush(state));
118
+ }
119
+ function deliver(state, payload) {
120
+ if (state.messageListeners.size > 0 && state.buffer.length === 0 && !state.flushScheduled) {
121
+ for (const listener of [...state.messageListeners]) listener(payload);
122
+ return;
123
+ }
124
+ state.buffer.push(payload);
125
+ if (state.buffer.length > MAX_BUFFERED_MESSAGES_PER_CHANNEL) state.buffer.shift();
126
+ if (state.messageListeners.size > 0) scheduleFlush(state);
75
127
  }
76
128
  function onPortClose() {
77
129
  markHubClosed();
@@ -85,7 +137,13 @@ function createMessagePortChannelHub(port) {
85
137
  },
86
138
  openChannel(name) {
87
139
  if (name.length === 0) throw new TypeError("MessagePort channel name must not be empty.");
88
- const state = stateFor(name);
140
+ const existing = states.get(name);
141
+ const state = existing !== void 0 && !existing.closed ? existing : createState();
142
+ if (state !== existing) {
143
+ state.closed = closed;
144
+ states.set(name, state);
145
+ }
146
+ state.opened = true;
89
147
  return {
90
148
  get closed() {
91
149
  return state.closed;
@@ -103,6 +161,7 @@ function createMessagePortChannelHub(port) {
103
161
  subscribe(listener) {
104
162
  if (closed || state.closed) return () => {};
105
163
  state.messageListeners.add(listener);
164
+ if (state.buffer.length > 0) scheduleFlush(state);
106
165
  return () => state.messageListeners.delete(listener);
107
166
  },
108
167
  subscribeClose(listener) {
package/dist/client.d.mts CHANGED
@@ -1,11 +1,29 @@
1
1
  import { InspectorTransport } from "./transport.mjs";
2
2
  import { InspectorEventMap, InspectorEventMessage, InspectorEventName, InspectorProtocolError, InspectorRequestMethod, InspectorRequestParams, InspectorRequestResult } from "./protocol.mjs";
3
3
  //#region src/client.d.ts
4
+ /** Codes a protocol peer sends, plus the ones only the Client itself produces. */
5
+ type InspectorClientErrorCode = InspectorProtocolError['code'] | 'timeout' | 'unknown-error';
6
+ interface InspectorClientErrorInfo {
7
+ readonly code: InspectorClientErrorCode;
8
+ readonly message: string;
9
+ /** For `unknown-error` only: the peer's own code string, verbatim. */
10
+ readonly peerCode?: string;
11
+ }
4
12
  declare class InspectorClientError extends Error {
5
13
  readonly name = "InspectorClientError";
6
- readonly code: InspectorProtocolError['code'];
7
- readonly protocolError: InspectorProtocolError;
8
- constructor(error: InspectorProtocolError);
14
+ readonly code: InspectorClientErrorCode;
15
+ readonly protocolError: InspectorClientErrorInfo;
16
+ /** Set when `code` is `unknown-error`: the code a newer peer sent, which this client does not define. */
17
+ readonly peerCode: string | undefined;
18
+ constructor(error: InspectorClientErrorInfo);
19
+ }
20
+ interface CreateInspectorClientOptions {
21
+ /**
22
+ * Rejects a request that has received no response after this many milliseconds with an
23
+ * `InspectorClientError` coded `timeout`. There is no default: unlimited unless configured. Must be a
24
+ * positive finite number. A late response to a timed-out request is ignored, except that a late successful `runtime.subscribeMember`/`runtime.subscribeEvent` response makes the client send the matching unsubscribe so no subscription outlives the failed request.
25
+ */
26
+ readonly requestTimeoutMs?: number;
9
27
  }
10
28
  interface InspectorClient {
11
29
  handshake: () => Promise<InspectorRequestResult<'handshake'>>;
@@ -13,9 +31,9 @@ interface InspectorClient {
13
31
  subscribe: (listener: (event: InspectorEventMessage) => void) => () => void;
14
32
  on: <Event extends InspectorEventName>(event: Event, listener: (payload: InspectorEventMap[Event]) => void) => () => void;
15
33
  close: () => void;
16
- /** Alias retained for owner-lifecycle terminology used by Lab integration/tests. */
34
+ /** Alias of `close`, for owner-lifecycle terminology. */
17
35
  dispose: () => void;
18
36
  }
19
- declare function createInspectorClient(transport: InspectorTransport): InspectorClient;
37
+ declare function createInspectorClient(transport: InspectorTransport, options?: CreateInspectorClientOptions): InspectorClient;
20
38
  //#endregion
21
- export { InspectorClient, InspectorClientError, createInspectorClient };
39
+ export { CreateInspectorClientOptions, InspectorClient, InspectorClientError, InspectorClientErrorCode, InspectorClientErrorInfo, createInspectorClient };
package/dist/client.mjs CHANGED
@@ -1,13 +1,16 @@
1
- import { a as isInspectorRequestResult, c as parseInspectorResponseMessage, n as isCompatibleProtocolVersion, o as parseInspectorEventMessage, t as INSPECTOR_PROTOCOL_VERSION } from "./protocol-D1gtirOC.mjs";
1
+ import { l as parseInspectorResponseMessage, o as isInspectorRequestResult, r as isCompatibleProtocolVersion, s as parseInspectorEventMessage, t as INSPECTOR_PROTOCOL_VERSION, u as parseInspectorUnrecognizedErrorResponse } from "./protocol-ZhhQaTAa.mjs";
2
2
  //#region src/client.ts
3
3
  var InspectorClientError = class extends Error {
4
4
  name = "InspectorClientError";
5
5
  code;
6
6
  protocolError;
7
+ /** Set when `code` is `unknown-error`: the code a newer peer sent, which this client does not define. */
8
+ peerCode;
7
9
  constructor(error) {
8
10
  super(error.message);
9
11
  this.code = error.code;
10
12
  this.protocolError = error;
13
+ this.peerCode = error.peerCode;
11
14
  }
12
15
  };
13
16
  function malformedResponseRequestId(value) {
@@ -15,52 +18,113 @@ function malformedResponseRequestId(value) {
15
18
  const candidate = value;
16
19
  return candidate.kind === "response" && typeof candidate.requestId === "string" ? candidate.requestId : null;
17
20
  }
18
- function createInspectorClient(transport) {
21
+ /**
22
+ * Runs one listener so that a throw cannot starve the listeners after it. Like Core's isolated
23
+ * listeners, the failure is reported outside the dispatch with a queued microtask rethrow.
24
+ */
25
+ function invokeIsolated(listener) {
26
+ try {
27
+ listener();
28
+ } catch (error) {
29
+ queueMicrotask(() => {
30
+ throw error;
31
+ });
32
+ }
33
+ }
34
+ /** How many timed-out subscribe requests a Client remembers in order to release a late subscription. */
35
+ const MAX_TIMED_OUT_SUBSCRIBES = 256;
36
+ function createInspectorClient(transport, options = {}) {
37
+ const requestTimeoutMs = options.requestTimeoutMs;
38
+ if (requestTimeoutMs !== void 0 && !(Number.isFinite(requestTimeoutMs) && requestTimeoutMs > 0)) throw new RangeError("requestTimeoutMs must be a positive finite number when configured.");
19
39
  let requestSequence = 0;
20
40
  let closed = false;
21
41
  const pending = /* @__PURE__ */ new Map();
42
+ const timedOutSubscribes = /* @__PURE__ */ new Map();
22
43
  const eventListeners = /* @__PURE__ */ new Map();
23
44
  const messageListeners = /* @__PURE__ */ new Set();
24
45
  let unsubscribeMessages = () => {};
25
46
  let unsubscribeClose = () => {};
47
+ /** Removes and returns the pending entry for a request, cancelling its timeout. */
48
+ function takePending(requestId) {
49
+ const entry = pending.get(requestId);
50
+ if (entry !== void 0) {
51
+ pending.delete(requestId);
52
+ clearTimeout(entry.timer ?? void 0);
53
+ }
54
+ return entry;
55
+ }
26
56
  function finalizeClose(message, closeTransport) {
27
57
  if (closed) return;
28
58
  closed = true;
29
59
  unsubscribeMessages();
30
60
  unsubscribeClose();
31
- for (const entry of pending.values()) entry.reject(new InspectorClientError({
32
- code: "disconnected",
33
- message
34
- }));
61
+ for (const entry of pending.values()) {
62
+ clearTimeout(entry.timer ?? void 0);
63
+ entry.reject(new InspectorClientError({
64
+ code: "disconnected",
65
+ message
66
+ }));
67
+ }
35
68
  pending.clear();
69
+ timedOutSubscribes.clear();
36
70
  eventListeners.clear();
37
71
  messageListeners.clear();
38
72
  if (closeTransport && !transport.closed) transport.close();
39
73
  }
40
- unsubscribeMessages = transport.subscribe((rawMessage) => {
41
- const event = parseInspectorEventMessage(rawMessage);
42
- if (event !== null && isCompatibleProtocolVersion(event.protocol)) {
43
- for (const listener of [...messageListeners]) listener(event);
44
- const listeners = eventListeners.get(event.event);
45
- if (listeners !== void 0) for (const listener of [...listeners]) listener(event.payload);
46
- return;
47
- }
74
+ /**
75
+ * A success response to a subscribe request the caller already gave up on: nobody knows the new
76
+ * subscription id, so release it instead of leaving it live on the Agent. Best effort and silent.
77
+ */
78
+ function releaseLateSubscription(response) {
79
+ const method = timedOutSubscribes.get(response.requestId);
80
+ if (method === void 0) return;
81
+ timedOutSubscribes.delete(response.requestId);
82
+ if (!response.ok || closed || transport.closed || !isCompatibleProtocolVersion(response.protocol)) return;
83
+ try {
84
+ if (!isInspectorRequestResult(method, response.result, response.protocol.minor)) return;
85
+ const subscriptionId = response.result.subscriptionId;
86
+ transport.send({
87
+ protocol: INSPECTOR_PROTOCOL_VERSION,
88
+ kind: "request",
89
+ requestId: `request-${++requestSequence}`,
90
+ method: method === "runtime.subscribeMember" ? "runtime.unsubscribeMember" : "runtime.unsubscribeEvent",
91
+ params: { subscriptionId }
92
+ });
93
+ } catch {}
94
+ }
95
+ function handleResponse(rawMessage) {
48
96
  const response = parseInspectorResponseMessage(rawMessage);
49
97
  if (response === null) {
50
- const requestId = malformedResponseRequestId(rawMessage);
51
- const entry = requestId === null ? void 0 : pending.get(requestId);
52
- if (requestId !== null && entry !== void 0) {
53
- pending.delete(requestId);
98
+ const unrecognized = parseInspectorUnrecognizedErrorResponse(rawMessage);
99
+ if (unrecognized !== null) {
100
+ const entry = takePending(unrecognized.requestId);
101
+ if (entry === void 0) return;
102
+ if (!isCompatibleProtocolVersion(unrecognized.protocol)) {
103
+ entry.reject(new InspectorClientError({
104
+ code: "unsupported-version",
105
+ message: "Inspector response uses an incompatible protocol major version."
106
+ }));
107
+ return;
108
+ }
54
109
  entry.reject(new InspectorClientError({
55
- code: "invalid-message",
56
- message: "Invalid Inspector protocol response envelope."
110
+ code: "unknown-error",
111
+ message: unrecognized.message,
112
+ peerCode: unrecognized.code
57
113
  }));
114
+ return;
58
115
  }
116
+ const requestId = malformedResponseRequestId(rawMessage);
117
+ (requestId === null ? void 0 : takePending(requestId))?.reject(new InspectorClientError({
118
+ code: "invalid-message",
119
+ message: "Invalid Inspector protocol response envelope."
120
+ }));
121
+ return;
122
+ }
123
+ const entry = takePending(response.requestId);
124
+ if (entry === void 0) {
125
+ releaseLateSubscription(response);
59
126
  return;
60
127
  }
61
- const entry = pending.get(response.requestId);
62
- if (entry === void 0) return;
63
- pending.delete(response.requestId);
64
128
  if (!isCompatibleProtocolVersion(response.protocol)) {
65
129
  entry.reject(new InspectorClientError({
66
130
  code: "unsupported-version",
@@ -72,7 +136,13 @@ function createInspectorClient(transport) {
72
136
  entry.reject(new InspectorClientError(response.error));
73
137
  return;
74
138
  }
75
- if (!isInspectorRequestResult(entry.method, response.result, response.protocol.minor)) {
139
+ let valid;
140
+ try {
141
+ valid = isInspectorRequestResult(entry.method, response.result, response.protocol.minor);
142
+ } catch {
143
+ valid = false;
144
+ }
145
+ if (!valid) {
76
146
  entry.reject(new InspectorClientError({
77
147
  code: "invalid-message",
78
148
  message: `Invalid ${entry.method} response payload.`
@@ -80,6 +150,27 @@ function createInspectorClient(transport) {
80
150
  return;
81
151
  }
82
152
  entry.resolve(response.result);
153
+ }
154
+ unsubscribeMessages = transport.subscribe((rawMessage) => {
155
+ let event = null;
156
+ try {
157
+ event = parseInspectorEventMessage(rawMessage);
158
+ if (event === null || !isCompatibleProtocolVersion(event.protocol)) {
159
+ event = null;
160
+ handleResponse(rawMessage);
161
+ }
162
+ } catch {
163
+ const requestId = malformedResponseRequestId(rawMessage);
164
+ (requestId === null ? void 0 : takePending(requestId))?.reject(new InspectorClientError({
165
+ code: "invalid-message",
166
+ message: "Unable to process the Inspector protocol response."
167
+ }));
168
+ return;
169
+ }
170
+ if (event === null) return;
171
+ for (const listener of [...messageListeners]) invokeIsolated(() => listener(event));
172
+ const listeners = eventListeners.get(event.event);
173
+ if (listeners !== void 0) for (const listener of [...listeners]) invokeIsolated(() => listener(event.payload));
83
174
  });
84
175
  unsubscribeClose = transport.subscribeClose(() => {
85
176
  finalizeClose("Inspector transport disconnected.", false);
@@ -94,7 +185,18 @@ function createInspectorClient(transport) {
94
185
  pending.set(requestId, {
95
186
  method,
96
187
  resolve,
97
- reject
188
+ reject,
189
+ timer: requestTimeoutMs === void 0 ? null : setTimeout(() => {
190
+ takePending(requestId);
191
+ if (method === "runtime.subscribeMember" || method === "runtime.subscribeEvent") {
192
+ timedOutSubscribes.set(requestId, method);
193
+ if (timedOutSubscribes.size > MAX_TIMED_OUT_SUBSCRIBES) timedOutSubscribes.delete(timedOutSubscribes.keys().next().value);
194
+ }
195
+ reject(new InspectorClientError({
196
+ code: "timeout",
197
+ message: `Inspector request ${method} timed out after ${requestTimeoutMs}ms.`
198
+ }));
199
+ }, requestTimeoutMs)
98
200
  });
99
201
  try {
100
202
  transport.send({
@@ -105,7 +207,7 @@ function createInspectorClient(transport) {
105
207
  params
106
208
  });
107
209
  } catch (error) {
108
- pending.delete(requestId);
210
+ takePending(requestId);
109
211
  reject(error);
110
212
  }
111
213
  });