@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/dist/index.d.ts +10 -4
- package/dist/index.js +494 -117
- package/dist/index.js.map +8 -8
- package/package.json +2 -2
- package/src/attach.ts +40 -6
- package/src/cause.ts +241 -64
- package/src/descriptors.ts +70 -3
- package/src/encode.ts +208 -80
- package/src/full.ts +327 -39
- package/src/shape.ts +71 -15
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
|
|
24
|
-
* is the thing worth bounding: what a single answer costs
|
|
25
|
-
* with one enormous field should spend its own allowance
|
|
26
|
-
* field by field, and two records should never be able
|
|
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) =>
|
|
69
|
-
|
|
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
|
|
98
|
-
|
|
99
|
-
|
|
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:
|
|
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
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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;
|