@frondruntime/devtools 0.5.0 → 0.6.0-rc.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/src/encode.ts CHANGED
@@ -1,6 +1,6 @@
1
1
  import type { Runtime } from "@frondruntime/core";
2
2
  import { describeError } from "./cause.ts";
3
- import { WITHHELD } from "./descriptors.ts";
3
+ import { setField, UNREADABLE, WITHHELD } from "./descriptors.ts";
4
4
  import { type Budget, describeFull, FULL_MAX_NODES } from "./full.ts";
5
5
  import type { EncodePolicy } from "./policy.ts";
6
6
  import type { EncodedEventRecord } from "./protocol.ts";
@@ -20,10 +20,11 @@ import { describeShape } from "./shape.ts";
20
20
  /**
21
21
  * A policy, applied to one answer.
22
22
  *
23
- * One of these per record and per snapshot, because the budget it closes over
24
- * is the thing worth bounding: what a single answer costs the wire. A record
25
- * with one enormous field should spend its own allowance rather than be judged
26
- * field by field, and two records should never be able to spend each other's.
23
+ * One of these per snapshot, and one budget per record in `encodeRecord`,
24
+ * because the budget is the thing worth bounding: what a single answer costs
25
+ * the wire. A record with one enormous field should spend its own allowance
26
+ * rather than be judged field by field, and two records should never be able
27
+ * to spend each other's.
27
28
  */
28
29
  export type ValueEncoder = {
29
30
  /** Ordinary app data, redacted according to the policy. */
@@ -45,42 +46,98 @@ export function createValueEncoder(policy: EncodePolicy): ValueEncoder {
45
46
  // every node in a graph snapshot, which is a description of app data by an
46
47
  // app that had said it would send none.
47
48
  if (policy === "none") {
48
- return {
49
- value: () => WITHHELD,
50
- // Still a chain, because "there is an error here" is not the value's
51
- // data. What crosses is what the failure names about itself — its tags,
52
- // its node, the innermost message — and never its payload or its stack,
53
- // which `describeError` withholds at anything below `"full"`.
54
- failure: (value) => describeError(value, policy),
55
- };
49
+ return { value: withheldValue, failure: noneFailure };
56
50
  }
57
51
 
58
52
  if (policy === "shape") {
59
- return {
60
- value: (value) => describeShape(value, 0),
61
- failure: (value) => describeError(value, policy),
62
- };
53
+ return { value: shapeValue, failure: shapeFailure };
63
54
  }
64
55
 
65
56
  const budget: Budget = { remaining: FULL_MAX_NODES };
66
57
 
67
58
  return {
68
- value: (value) => describeFull(value, 0, new Set<object>(), budget),
69
- // The `seen` set is per call and shared between the two halves of that call:
70
- // `describeError` marks each link of the chain as an ancestor, and the
71
- // payload walk it hands off to has to see those marks or it will descend
72
- // back into an error it is already standing on.
73
- failure: (value) => {
74
- const seen = new Set<object>();
75
-
76
- return describeError(value, policy, {
77
- seen,
78
- encodeValue: (own) => describeFull(own, 1, seen, budget),
79
- });
80
- },
59
+ value: (value) => fullValue(value, budget),
60
+ failure: (value) => fullFailure(value, budget),
81
61
  };
82
62
  }
83
63
 
64
+ // Module-level rather than closures made per encoder: `"none"` and `"shape"`
65
+ // hold no state, and `encodeRecord` calls the `"full"` pair with its own budget.
66
+ function withheldValue(): unknown {
67
+ return WITHHELD;
68
+ }
69
+
70
+ // Still a chain, because "there is an error here" is not the value's data.
71
+ // What crosses is what the failure names about itself — its tags, its node,
72
+ // the innermost message — and never its payload or its stack, which
73
+ // `describeError` withholds at anything below `"full"`.
74
+ function noneFailure(value: unknown): unknown {
75
+ return describeError(value, "none");
76
+ }
77
+
78
+ function shapeValue(value: unknown): unknown {
79
+ return describeShape(value, 0);
80
+ }
81
+
82
+ function shapeFailure(value: unknown): unknown {
83
+ return describeError(value, "shape");
84
+ }
85
+
86
+ function fullValue(value: unknown, budget: Budget): unknown {
87
+ return describeFull(value, 0, new Set<object>(), budget);
88
+ }
89
+
90
+ // The `seen` set is per call and shared between the two halves of that call:
91
+ // `describeError` marks each link of the chain as an ancestor, and the payload
92
+ // walk it hands off to has to see those marks or it will descend back into an
93
+ // error it is already standing on. That hand-off is a closure on purpose:
94
+ // `cause.ts` reaches the full walk only through `FullContext`.
95
+ function fullFailure(value: unknown, budget: Budget): unknown {
96
+ const seen = new Set<object>();
97
+
98
+ return describeError(value, "full", {
99
+ seen,
100
+ encodeValue: (own) => describeFull(own, 1, seen, budget),
101
+ });
102
+ }
103
+
104
+ function encodeValueAt(policy: EncodePolicy, value: unknown, budget: Budget): unknown {
105
+ switch (policy) {
106
+ case "none": {
107
+ return WITHHELD;
108
+ }
109
+ case "shape": {
110
+ return describeShape(value, 0);
111
+ }
112
+ case "full": {
113
+ return fullValue(value, budget);
114
+ }
115
+ }
116
+ }
117
+
118
+ function encodeFailureAt(policy: EncodePolicy, value: unknown, budget: Budget): unknown {
119
+ switch (policy) {
120
+ case "none":
121
+ case "shape": {
122
+ return describeError(value, policy);
123
+ }
124
+ case "full": {
125
+ return fullFailure(value, budget);
126
+ }
127
+ }
128
+ }
129
+
130
+ /** The budget below `"full"`, where nothing reads it. Frozen, so a spend would throw. */
131
+ const UNSPENT: Budget = Object.freeze({ remaining: FULL_MAX_NODES });
132
+
133
+ /** A record with its routing fields written, waiting for `fields` and `failures`. */
134
+ type RecordDraft = {
135
+ -readonly [K in keyof Omit<EncodedEventRecord, "fields" | "failures">]: EncodedEventRecord[K];
136
+ } & {
137
+ fields?: EncodedEventRecord["fields"];
138
+ failures?: EncodedEventRecord["failures"];
139
+ };
140
+
84
141
  /**
85
142
  * Encodes one runtime event for the wire.
86
143
  *
@@ -89,32 +146,22 @@ export function createValueEncoder(policy: EncodePolicy): ValueEncoder {
89
146
  * data. A signal's channel and name join them, on the reasoning
90
147
  * `EncodedEventRecord` gives for the two fields. Only the event body goes
91
148
  * through the value encoder.
149
+ *
150
+ * Built field by field rather than through a {@link ValueEncoder}: this runs
151
+ * once per runtime event, and on Hermes the encoder object, its closures, and
152
+ * an identity object spread into the record are a cost per event. One budget
153
+ * per record, as with an encoder.
92
154
  */
93
155
  export function encodeRecord(
94
156
  record: Runtime.RuntimeEventRecord,
95
157
  policy: EncodePolicy
96
158
  ): EncodedEventRecord {
97
- const encoder = createValueEncoder(policy);
98
-
99
- // The runtime pulls `failures` straight off the event's own fields, so the
100
- // same object arrives twice — once as `fields.error`, once as `failures[0]`.
101
- // Matched by identity so both come out as the same thing; a record that
102
- // described one failure two different ways would read as two.
103
- const known = new Set(
104
- record.failures.filter(
105
- (failure): failure is object => typeof failure === "object" && failure !== null
106
- )
107
- );
108
-
109
- const encodeField = (value: unknown): unknown =>
110
- typeof value === "object" && value !== null && known.has(value)
111
- ? encoder.failure(value)
112
- : encoder.value(value);
113
-
114
- return {
159
+ const budget = policy === "full" ? { remaining: FULL_MAX_NODES } : UNSPENT;
160
+ const event = record.event;
161
+ const encoded: RecordDraft = {
115
162
  sequence: record.sequence,
116
163
  recordedAt: record.recordedAt,
117
- tag: record.event._tag,
164
+ tag: event._tag,
118
165
  category: record.classification.category,
119
166
  severity: record.classification.severity,
120
167
  timeline: record.classification.timeline,
@@ -125,23 +172,39 @@ export function encodeRecord(
125
172
  reason: record.work.reason,
126
173
  priority: record.work.priority,
127
174
  nodeIds: record.nodeIds,
128
- // Unclamped, like every routing field above it. A signal's channel and name
129
- // are how a reader addresses one — the filters `frond_read_events` exposes —
130
- // and they are authored as constants next to the code that publishes, the
131
- // same standing as `tag` and `nodeIds`. What the payload holds is the value,
132
- // and that is what `fields` withholds a line below.
133
- ...signalIdentity(record.event),
134
- fields: policy === "none" ? {} : describeFields(record.event, encodeField),
135
- // Failures are causes, not results: their messages are what makes a
136
- // devtools feed worth reading, so they are described rather than dropped —
137
- // including under `"none"`, whose subject is values, not what broke.
138
- //
139
- // Encoded as failures rather than as values, because that is what the
140
- // runtime says they are — no sniffing required. Which matters for the ones
141
- // that are not `Error` instances: an Effect `Cause` reaching the value
142
- // encoder comes out as a bag of key names.
143
- failures: record.failures.map(encoder.failure),
144
175
  };
176
+
177
+ // Unclamped, like every routing field above it. A signal's channel and name
178
+ // are how a reader addresses one — the filters `frond_read_events` exposes —
179
+ // and they are authored as constants next to the code that publishes, the
180
+ // same standing as `tag` and `nodeIds`. What the payload holds is the value,
181
+ // and that is what `fields` withholds a line below.
182
+ writeSignalIdentity(encoded, event);
183
+ encoded.fields = policy === "none" ? {} : describeFields(event, policy, budget, record.failures);
184
+ // Failures are causes, not results: their messages are what makes a
185
+ // devtools feed worth reading, so they are described rather than dropped —
186
+ // including under `"none"`, whose subject is values, not what broke.
187
+ //
188
+ // Encoded as failures rather than as values, because that is what the
189
+ // runtime says they are — no sniffing required. Which matters for the ones
190
+ // that are not `Error` instances: an Effect `Cause` reaching the value
191
+ // encoder comes out as a bag of key names.
192
+ //
193
+ // With `Array.map`'s semantics, which the wire output was built on: the
194
+ // length is read once, so a failure appended while encoding is not encoded,
195
+ // and a hole stays a hole, which goes over JSON as `null`.
196
+ const source = record.failures;
197
+ const length = source.length;
198
+ const failures: Array<unknown> = new Array(length);
199
+ for (let index = 0; index < length; index++) {
200
+ if (index in source) {
201
+ failures[index] = encodeFailureAt(policy, source[index], budget);
202
+ }
203
+ }
204
+ encoded.failures = failures;
205
+
206
+ // Every field is written: the literal holds all but two, assigned above.
207
+ return encoded as EncodedEventRecord;
145
208
  }
146
209
 
147
210
  /**
@@ -158,33 +221,98 @@ export function encodeRecord(
158
221
  * Absent rather than empty on everything else. `channel: ""` is a record
159
222
  * claiming a channel it does not have, and a reader filtering on the field would
160
223
  * have to know to treat one string as meaning "no".
224
+ *
225
+ * Each read on its own guard, like the field walk's: these run outside it, so
226
+ * its guards never see them, and a getter that throws here would otherwise take
227
+ * the whole record with it. A read that throws, or a value that is not a string,
228
+ * costs that field — the transport takes `channel` and `name` as strings or not
229
+ * at all.
161
230
  */
162
- function signalIdentity(event: Runtime.RuntimeEvent): {
163
- readonly channel?: string;
164
- readonly name?: string;
165
- } {
166
- const signal =
167
- event._tag === "RuntimeSignalPublished"
168
- ? event.record.signal
169
- : event._tag === "RuntimeSignalSubscriberFailureObserved"
170
- ? event.signal.signal
171
- : undefined;
172
-
173
- return signal === undefined ? {} : { channel: signal.channel, name: signal.name };
231
+ function writeSignalIdentity(encoded: RecordDraft, event: Runtime.RuntimeEvent): void {
232
+ switch (event._tag) {
233
+ case "RuntimeSignalPublished": {
234
+ writeIdentityOf(encoded, readGuarded(readGuarded(event, "record"), "signal"));
235
+ return;
236
+ }
237
+ case "RuntimeSignalSubscriberFailureObserved": {
238
+ writeIdentityOf(encoded, readGuarded(readGuarded(event, "signal"), "signal"));
239
+ return;
240
+ }
241
+ default: {
242
+ return;
243
+ }
244
+ }
174
245
  }
175
246
 
247
+ function writeIdentityOf(encoded: RecordDraft, signal: unknown): void {
248
+ const channel = readGuarded(signal, "channel");
249
+ const name = readGuarded(signal, "name");
250
+
251
+ if (typeof channel === "string") {
252
+ encoded.channel = channel;
253
+ }
254
+
255
+ if (typeof name === "string") {
256
+ encoded.name = name;
257
+ }
258
+ }
259
+
260
+ /** `target[key]`, or `undefined` when `target` is not an object or the read throws. */
261
+ function readGuarded(target: unknown, key: string): unknown {
262
+ if (typeof target !== "object" || target === null) {
263
+ return undefined;
264
+ }
265
+
266
+ try {
267
+ return (target as Record<string, unknown>)[key];
268
+ } catch {
269
+ return undefined;
270
+ }
271
+ }
272
+
273
+ /**
274
+ * The event body, each field through the value walk.
275
+ *
276
+ * The runtime pulls `failures` straight off the event's own fields, so the
277
+ * same object arrives twice — once as `fields.error`, once as `failures[0]`.
278
+ * Matched by identity so both come out as the same thing; a record that
279
+ * described one failure two different ways would read as two.
280
+ */
176
281
  function describeFields(
177
282
  event: Runtime.RuntimeEvent,
178
- encodeValue: (value: unknown) => unknown
283
+ policy: EncodePolicy,
284
+ budget: Budget,
285
+ failures: ReadonlyArray<unknown>
179
286
  ): Record<string, unknown> {
180
287
  const fields: Record<string, unknown> = {};
288
+ const keys = Object.keys(event);
289
+
290
+ // Each read guarded on its own. The read runs before the value walk, so the
291
+ // walk's guards never see a getter that throws here, and the throw would
292
+ // otherwise take the whole record with it.
293
+ for (let index = 0; index < keys.length; index++) {
294
+ const key = keys[index] as string;
181
295
 
182
- for (const [key, value] of Object.entries(event)) {
183
296
  if (key === "_tag") {
184
297
  continue;
185
298
  }
186
299
 
187
- fields[key] = encodeValue(value);
300
+ let value: unknown;
301
+
302
+ try {
303
+ value = (event as unknown as Record<string, unknown>)[key];
304
+ } catch {
305
+ setField(fields, key, UNREADABLE);
306
+ continue;
307
+ }
308
+
309
+ setField(
310
+ fields,
311
+ key,
312
+ typeof value === "object" && value !== null && failures.includes(value)
313
+ ? encodeFailureAt(policy, value, budget)
314
+ : encodeValueAt(policy, value, budget)
315
+ );
188
316
  }
189
317
 
190
318
  return fields;