@frondruntime/devtools 0.3.0
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/CHANGELOG.md +23 -0
- package/LICENSE +21 -0
- package/README.md +123 -0
- package/dist/chunk-8xwbnbvs.js +164 -0
- package/dist/chunk-8xwbnbvs.js.map +10 -0
- package/dist/index.d.ts +1062 -0
- package/dist/index.js +705 -0
- package/dist/index.js.map +18 -0
- package/dist/node.d.ts +48 -0
- package/dist/node.js +45 -0
- package/dist/node.js.map +10 -0
- package/package.json +73 -0
- package/src/attach.ts +256 -0
- package/src/attachDevtools.ts +221 -0
- package/src/cause.ts +369 -0
- package/src/descriptors.ts +107 -0
- package/src/encode.ts +154 -0
- package/src/full.ts +232 -0
- package/src/index.ts +15 -0
- package/src/node.ts +110 -0
- package/src/policy.ts +37 -0
- package/src/protocol.ts +458 -0
- package/src/shape.ts +161 -0
- package/src/snapshot.ts +229 -0
package/src/cause.ts
ADDED
|
@@ -0,0 +1,369 @@
|
|
|
1
|
+
import { Diagnostics } from "@frondruntime/core";
|
|
2
|
+
import type { ErrorDescriptor } from "./descriptors.ts";
|
|
3
|
+
import type { EncodePolicy } from "./policy.ts";
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Failures, as chains of causes.
|
|
7
|
+
*
|
|
8
|
+
* Kept apart from the two value encoders because it is not one: a failure is
|
|
9
|
+
* described the same way at every policy, and what varies is only how much of
|
|
10
|
+
* each frame crosses. The value encoders call in here; nothing here calls back
|
|
11
|
+
* out to them except through {@link FullContext}, which is what keeps this
|
|
12
|
+
* module a leaf.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* How far up a `cause` chain to walk. Matches the core default.
|
|
17
|
+
*
|
|
18
|
+
* Chains this long are rare and the frames are small; the expensive parts of a
|
|
19
|
+
* frame — its stack and its payload — are bounded separately below.
|
|
20
|
+
*/
|
|
21
|
+
const CAUSE_MAX_DEPTH = 8;
|
|
22
|
+
const SHAPE_CAUSE_STRING_LENGTH = 256;
|
|
23
|
+
const FULL_CAUSE_STRING_LENGTH = 1024;
|
|
24
|
+
/**
|
|
25
|
+
* How much stack to take from core before selecting frames out of it.
|
|
26
|
+
*
|
|
27
|
+
* Deliberately far above anything a real stack reaches: cutting here cuts by
|
|
28
|
+
* character, which is the thing {@link abridgeStack} exists to stop doing. This
|
|
29
|
+
* is a guard against a fabricated `stack` string, not a budget.
|
|
30
|
+
*/
|
|
31
|
+
const CAUSE_STACK_SOURCE_LENGTH = 32768;
|
|
32
|
+
/**
|
|
33
|
+
* How many frames survive selection.
|
|
34
|
+
*
|
|
35
|
+
* The frame that names app code is almost always within the first few once the
|
|
36
|
+
* library frames are gone; fifteen is room for a couple of layers of wrapping on
|
|
37
|
+
* top of that without the trace becoming the record.
|
|
38
|
+
*/
|
|
39
|
+
const KEPT_STACK_FRAMES = 15;
|
|
40
|
+
/** Kept from a trace that is library frames all the way down. See {@link abridgeStack}. */
|
|
41
|
+
const LIBRARY_ONLY_STACK_FRAMES = 2;
|
|
42
|
+
/** The fallback bound, for a `stack` this cannot read as frames at all. */
|
|
43
|
+
const FULL_CAUSE_STACK_LENGTH = 2048;
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* Frames, in the two formats a JS runtime produces.
|
|
47
|
+
*
|
|
48
|
+
* V8 (Node, Bun, Chromium) indents every frame with `at `; JSC and SpiderMonkey
|
|
49
|
+
* write `name@url:line:column`. Matched rather than assumed because the header
|
|
50
|
+
* of a stack is the error's own message, which is app text and must not be
|
|
51
|
+
* mistaken for a frame and dropped.
|
|
52
|
+
*/
|
|
53
|
+
const V8_STACK_FRAME = /^\s*at\s\S/;
|
|
54
|
+
// Anchored and whitespace-free on both sides of the `@`, because a JSC stack has
|
|
55
|
+
// no header line to protect it: a message like `Cannot find module
|
|
56
|
+
// /app/node_modules/x/index.js:1:1` ends the way a frame ends, and an unanchored
|
|
57
|
+
// pattern would call line 0 a frame, leaving `header` empty and feeding the
|
|
58
|
+
// message itself to the library filter.
|
|
59
|
+
const AT_STACK_FRAME = /^\S*@\S*:\d+:\d+\s*$/;
|
|
60
|
+
|
|
61
|
+
/**
|
|
62
|
+
* Frames that belong to someone else's code.
|
|
63
|
+
*
|
|
64
|
+
* `node_modules` is the whole point; the rest are the same idea for code that
|
|
65
|
+
* has no file in the tree at all — Node's builtins, Bun's, and native frames.
|
|
66
|
+
* Bun writes its own native frames as `at moduleEvaluation (native:1:11)` rather
|
|
67
|
+
* than in either of the parenthesized spellings, hence the bare `native:`.
|
|
68
|
+
*/
|
|
69
|
+
const LIBRARY_STACK_FRAME = /node_modules|node:|bun:|native:|\(native\)|\[native code]/;
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* What the `"full"` policy needs in order to encode an error's own payload.
|
|
73
|
+
*
|
|
74
|
+
* `encodeValue` is injected rather than imported. The full encoder descends into
|
|
75
|
+
* errors and errors descend into their payloads, so calling that encoder by name
|
|
76
|
+
* from here would make the two modules mutually recursive at module scope for no
|
|
77
|
+
* gain — the caller already holds the depth, the `seen` set and the budget that
|
|
78
|
+
* such a call would need, and closing over them is both shorter and the only
|
|
79
|
+
* arrangement in which this file has no dependency on either value encoder.
|
|
80
|
+
*
|
|
81
|
+
* `seen` is still passed through, because this function adds to it: every link
|
|
82
|
+
* of the chain joins the ancestor path for the duration of the walk below it.
|
|
83
|
+
*/
|
|
84
|
+
export type FullContext = {
|
|
85
|
+
readonly seen: Set<object>;
|
|
86
|
+
readonly encodeValue: (value: unknown) => unknown;
|
|
87
|
+
};
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Serializes a failure and everything that caused it.
|
|
91
|
+
*
|
|
92
|
+
* Thin over `Diagnostics.serializeCauseChain`, which is already the runtime's
|
|
93
|
+
* own answer to "what went wrong" and is already defensive about it — getters
|
|
94
|
+
* that throw, cycles, absent fields. Reusing it means the devtools feed and a
|
|
95
|
+
* runtime sink describe the same failure the same way; hand-rolling a second
|
|
96
|
+
* walk here would eventually mean two accounts of one error that disagree.
|
|
97
|
+
*
|
|
98
|
+
* `preview` is dropped from every frame. Core builds it for a human reading a
|
|
99
|
+
* report, and for an `Error` it is name, message, stack and cause — all of
|
|
100
|
+
* which the frame already carries, one of them recursively, so keeping it would
|
|
101
|
+
* send the chain once per link and add nothing.
|
|
102
|
+
*
|
|
103
|
+
* Two things are `"full"`-only, for the same reason the rest of this encoder
|
|
104
|
+
* withholds things. A `stack` is bulk at `"shape"`: a wall of Effect internals
|
|
105
|
+
* around the two frames that name app code. And `fields` is the error's own
|
|
106
|
+
* payload — `status`, `endpoint`, whatever the app put on it — which is app
|
|
107
|
+
* data by any other name. What survives at `"shape"` is what the chain names
|
|
108
|
+
* explicitly: `tag`, `nodeId`, `operation`, `dependency`, `path`.
|
|
109
|
+
*/
|
|
110
|
+
export function describeError(
|
|
111
|
+
value: unknown,
|
|
112
|
+
policy: EncodePolicy,
|
|
113
|
+
full?: FullContext
|
|
114
|
+
): ErrorDescriptor {
|
|
115
|
+
const disclose = policy === "full";
|
|
116
|
+
|
|
117
|
+
const frames = Diagnostics.serializeCauseChain(value, {
|
|
118
|
+
maxDepth: CAUSE_MAX_DEPTH,
|
|
119
|
+
maxStringLength: disclose ? FULL_CAUSE_STRING_LENGTH : SHAPE_CAUSE_STRING_LENGTH,
|
|
120
|
+
// Asked for whole, then abridged by frame below. Core can only cut by
|
|
121
|
+
// character, which is exactly the cut that loses the frame worth keeping.
|
|
122
|
+
maxStackLength: CAUSE_STACK_SOURCE_LENGTH,
|
|
123
|
+
maxObjectKeys: disclose ? 20 : 8,
|
|
124
|
+
});
|
|
125
|
+
|
|
126
|
+
if (full === undefined) {
|
|
127
|
+
// `path` and `valueKind` are the two frame fields that describe the app's
|
|
128
|
+
// data rather than the runtime's: a path is a list of the app's own key
|
|
129
|
+
// names, and a value kind says whether what failed was an array or an
|
|
130
|
+
// object. Both are shape by any definition, so `"none"` — whose whole
|
|
131
|
+
// contract is that no shape crosses — drops them. The message still
|
|
132
|
+
// crosses at every policy; that is deliberate, and it is the one thing a
|
|
133
|
+
// reader cannot diagnose without.
|
|
134
|
+
const shed = policy === "none" ? { path: undefined, valueKind: undefined } : {};
|
|
135
|
+
|
|
136
|
+
return {
|
|
137
|
+
_: "error",
|
|
138
|
+
message: rootMessage(frames),
|
|
139
|
+
causes: frames.map((frame) =>
|
|
140
|
+
compact({ ...frame, ...shed, stack: undefined, preview: undefined })
|
|
141
|
+
),
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
|
|
145
|
+
// Every link joins the ancestor path for the duration, so a payload field
|
|
146
|
+
// pointing back at an error already on the chain is a cycle rather than a
|
|
147
|
+
// second trip through this function.
|
|
148
|
+
//
|
|
149
|
+
// Only what this call actually inserted comes back out. A link an enclosing
|
|
150
|
+
// frame is still standing on has to stay marked: an error reached through an
|
|
151
|
+
// app object whose payload points back at that object is the ordinary shape of
|
|
152
|
+
// a wrapped failure, and un-marking it there would let the walk descend into
|
|
153
|
+
// the ancestor instead of naming the cycle.
|
|
154
|
+
const links = causeValues(value, frames.length);
|
|
155
|
+
const marked = links.filter(
|
|
156
|
+
(link): link is object => typeof link === "object" && link !== null && !full.seen.has(link)
|
|
157
|
+
);
|
|
158
|
+
|
|
159
|
+
for (const link of marked) {
|
|
160
|
+
full.seen.add(link);
|
|
161
|
+
}
|
|
162
|
+
|
|
163
|
+
try {
|
|
164
|
+
return {
|
|
165
|
+
_: "error",
|
|
166
|
+
message: rootMessage(frames),
|
|
167
|
+
causes: frames.map((frame, index) =>
|
|
168
|
+
compact({
|
|
169
|
+
...frame,
|
|
170
|
+
preview: undefined,
|
|
171
|
+
stack: frame.stack === undefined ? undefined : abridgeStack(frame.stack),
|
|
172
|
+
fields: errorFields(links[index], full.encodeValue),
|
|
173
|
+
})
|
|
174
|
+
),
|
|
175
|
+
};
|
|
176
|
+
} finally {
|
|
177
|
+
for (const link of marked) {
|
|
178
|
+
full.seen.delete(link);
|
|
179
|
+
}
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
|
|
183
|
+
/**
|
|
184
|
+
* A stack, selected by frame instead of cut by character.
|
|
185
|
+
*
|
|
186
|
+
* A raw stack is mostly other people's code — Effect's fiber runtime, the test
|
|
187
|
+
* runner, the module loader — and the frames that name the app are scattered
|
|
188
|
+
* through it rather than at the top. Truncating at a character count therefore
|
|
189
|
+
* spends the budget on internals and can cut the one frame a reader needed, so
|
|
190
|
+
* this drops library frames outright and keeps the first {@link
|
|
191
|
+
* KEPT_STACK_FRAMES} of what is left.
|
|
192
|
+
*
|
|
193
|
+
* The dropped count is not decoration. An abridged trace that does not say it is
|
|
194
|
+
* abridged reads as "this is where it came from", and a reader who then cannot
|
|
195
|
+
* find the caller concludes the wrong thing about the code rather than about the
|
|
196
|
+
* trace.
|
|
197
|
+
*
|
|
198
|
+
* Two cases deliberately do not select. A trace that is library frames all the
|
|
199
|
+
* way down — a failure raised entirely inside a dependency — still says where in
|
|
200
|
+
* that dependency, and an empty stack would throw that away for nothing. And a
|
|
201
|
+
* `stack` with no recognizable frames is not a stack this can reason about, so
|
|
202
|
+
* it falls back to the character bound rather than guessing.
|
|
203
|
+
*/
|
|
204
|
+
function abridgeStack(stack: string): string {
|
|
205
|
+
const lines = stack.split("\n");
|
|
206
|
+
const first = lines.findIndex(isStackFrame);
|
|
207
|
+
|
|
208
|
+
if (first === -1) {
|
|
209
|
+
return stack.length <= FULL_CAUSE_STACK_LENGTH
|
|
210
|
+
? stack
|
|
211
|
+
: `${stack.slice(0, FULL_CAUSE_STACK_LENGTH)}…`;
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
// Everything above the first frame is the error's own header, kept whole: it
|
|
215
|
+
// is the name and message, which is the part a reader reads first.
|
|
216
|
+
const header = lines.slice(0, first);
|
|
217
|
+
// Counted against everything below the header, not just the lines the two
|
|
218
|
+
// patterns recognize. JSC writes frames this cannot parse — `promiseReactionJob@[native code]`
|
|
219
|
+
// has no `:line:col` — and dropping those out of the denominator would let the
|
|
220
|
+
// trace claim it accounted for what it removed while quietly removing more.
|
|
221
|
+
const body = lines.slice(first).filter((line) => line.trim() !== "");
|
|
222
|
+
const frames = body.filter(isStackFrame);
|
|
223
|
+
const own = frames.filter((line) => !LIBRARY_STACK_FRAME.test(line));
|
|
224
|
+
const kept = (own.length === 0 ? frames.slice(0, LIBRARY_ONLY_STACK_FRAMES) : own).slice(
|
|
225
|
+
0,
|
|
226
|
+
KEPT_STACK_FRAMES
|
|
227
|
+
);
|
|
228
|
+
const dropped = body.length - kept.length;
|
|
229
|
+
|
|
230
|
+
if (dropped === 0) {
|
|
231
|
+
return [...header, ...kept].join("\n");
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
return [
|
|
235
|
+
...header,
|
|
236
|
+
...kept,
|
|
237
|
+
` … ${dropped} frame${dropped === 1 ? "" : "s"} dropped: library internals, unrecognized lines, and any past the first ${KEPT_STACK_FRAMES}`,
|
|
238
|
+
].join("\n");
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
function isStackFrame(line: string): boolean {
|
|
242
|
+
return V8_STACK_FRAME.test(line) || AT_STACK_FRAME.test(line);
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
/**
|
|
246
|
+
* Re-walks the chain for the values behind the frames.
|
|
247
|
+
*
|
|
248
|
+
* Bounded by `count`, which is the frame count rather than a limit of its own:
|
|
249
|
+
* two walks of the same chain that could stop in different places would
|
|
250
|
+
* eventually pair a frame with the wrong value.
|
|
251
|
+
*/
|
|
252
|
+
function causeValues(root: unknown, count: number): ReadonlyArray<unknown> {
|
|
253
|
+
const values: Array<unknown> = [];
|
|
254
|
+
let current: unknown = root;
|
|
255
|
+
|
|
256
|
+
for (let index = 0; index < count; index += 1) {
|
|
257
|
+
values.push(current);
|
|
258
|
+
|
|
259
|
+
if (typeof current !== "object" || current === null) {
|
|
260
|
+
break;
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
try {
|
|
264
|
+
current = (current as Record<string, unknown>)["cause"];
|
|
265
|
+
} catch {
|
|
266
|
+
break;
|
|
267
|
+
}
|
|
268
|
+
}
|
|
269
|
+
|
|
270
|
+
return values;
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
/**
|
|
274
|
+
* Keys a frame already accounts for, by name, and should not repeat.
|
|
275
|
+
*
|
|
276
|
+
* `cause` is the next frame. The rest are what `serializeCauseChain` lifts out
|
|
277
|
+
* of a failure into named fields — sometimes renamed, as `tag` is to `nodeTag`,
|
|
278
|
+
* which is why this list is written against the *source* keys and has to stay
|
|
279
|
+
* in step with that function rather than with the frame type.
|
|
280
|
+
*/
|
|
281
|
+
const NAMED_ERROR_KEYS = new Set([
|
|
282
|
+
"boundary",
|
|
283
|
+
"cancellation",
|
|
284
|
+
"cause",
|
|
285
|
+
"dependency",
|
|
286
|
+
"invariant",
|
|
287
|
+
"kind",
|
|
288
|
+
"message",
|
|
289
|
+
"name",
|
|
290
|
+
"nodeId",
|
|
291
|
+
"operation",
|
|
292
|
+
"path",
|
|
293
|
+
"stack",
|
|
294
|
+
"tag",
|
|
295
|
+
"timeout",
|
|
296
|
+
"_tag",
|
|
297
|
+
]);
|
|
298
|
+
|
|
299
|
+
/**
|
|
300
|
+
* What a failure carries beyond being a failure.
|
|
301
|
+
*
|
|
302
|
+
* The half of an error a cause chain cannot name in advance: an HTTP status, a
|
|
303
|
+
* request id, the arguments the call was made with. `undefined` when there is
|
|
304
|
+
* none, which is the common case — a wrapper carries nothing but the fields
|
|
305
|
+
* above — and {@link compact} drops the key on the way out.
|
|
306
|
+
*/
|
|
307
|
+
function errorFields(value: unknown, encodeValue: (value: unknown) => unknown): unknown {
|
|
308
|
+
if (typeof value !== "object" || value === null) {
|
|
309
|
+
// A thrown string or number is its own payload, and the frame's `message`
|
|
310
|
+
// only got a rendering of it.
|
|
311
|
+
return encodeValue(value);
|
|
312
|
+
}
|
|
313
|
+
|
|
314
|
+
const own: Record<string, unknown> = {};
|
|
315
|
+
|
|
316
|
+
try {
|
|
317
|
+
for (const key of Object.keys(value)) {
|
|
318
|
+
if (!NAMED_ERROR_KEYS.has(key)) {
|
|
319
|
+
own[key] = (value as Record<string, unknown>)[key];
|
|
320
|
+
}
|
|
321
|
+
}
|
|
322
|
+
} catch {
|
|
323
|
+
return undefined;
|
|
324
|
+
}
|
|
325
|
+
|
|
326
|
+
return Object.keys(own).length === 0 ? undefined : encodeValue(own);
|
|
327
|
+
}
|
|
328
|
+
|
|
329
|
+
/**
|
|
330
|
+
* The innermost thing that had something to say.
|
|
331
|
+
*
|
|
332
|
+
* Two kinds of frame have nothing: a `Data.TaggedError` wrapper, whose message
|
|
333
|
+
* is empty, and a failure that is not an error at all — a node status, say —
|
|
334
|
+
* for which core falls back to the value's kind. Both are skipped, the second
|
|
335
|
+
* because `"object"` in a field called `message` reads as a message and is not
|
|
336
|
+
* one. When the whole chain is like that, the outermost frame's own name is the
|
|
337
|
+
* most this can honestly say, and the frames below it carry the rest.
|
|
338
|
+
*/
|
|
339
|
+
function rootMessage(frames: ReadonlyArray<Diagnostics.SerializedCauseFrame>): string {
|
|
340
|
+
for (let index = frames.length - 1; index >= 0; index -= 1) {
|
|
341
|
+
const frame = frames[index];
|
|
342
|
+
const message = frame?.message;
|
|
343
|
+
|
|
344
|
+
if (message !== undefined && message !== "" && message !== frame?.valueKind) {
|
|
345
|
+
return message;
|
|
346
|
+
}
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
return frames[0]?.tag ?? frames[0]?.name ?? "";
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* Drops absent keys.
|
|
354
|
+
*
|
|
355
|
+
* A cause frame declares every field any failure might carry, so most of them
|
|
356
|
+
* are `undefined` on any given one. JSON would drop those anyway; doing it here
|
|
357
|
+
* means the in-memory record the hub retains and renders matches the wire.
|
|
358
|
+
*/
|
|
359
|
+
function compact(frame: Record<string, unknown>): Record<string, unknown> {
|
|
360
|
+
const out: Record<string, unknown> = {};
|
|
361
|
+
|
|
362
|
+
for (const [key, value] of Object.entries(frame)) {
|
|
363
|
+
if (value !== undefined) {
|
|
364
|
+
out[key] = value;
|
|
365
|
+
}
|
|
366
|
+
}
|
|
367
|
+
|
|
368
|
+
return out;
|
|
369
|
+
}
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The vocabulary both encoders emit where a value did not survive whole.
|
|
3
|
+
*
|
|
4
|
+
* Shared rather than duplicated because the two encoders disagree about almost
|
|
5
|
+
* everything else — `"shape"` says as little as it can and `"full"` says as much
|
|
6
|
+
* as it can — and the one thing they must agree on is how a reader tells a
|
|
7
|
+
* marker from data.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* A failure, as its chain of causes rather than as its outermost link.
|
|
12
|
+
*
|
|
13
|
+
* The outermost link is almost never the interesting one. Frond wraps failures
|
|
14
|
+
* as it unwinds — `RefreshFailed` around `ActionFailed` around whatever the app
|
|
15
|
+
* actually threw — and those wrappers are `Data.TaggedError`s, whose `message`
|
|
16
|
+
* is the empty string. Encoding one as `{name, message}` therefore yields
|
|
17
|
+
* `{"RefreshFailed", ""}`: the shape of an answer with none of the content.
|
|
18
|
+
*
|
|
19
|
+
* Deliberately not a *projection*. Core can also produce one of those, with a
|
|
20
|
+
* headline, a severity guess and a retryability guess, and it is the right thing
|
|
21
|
+
* to put in front of a human or into an error reporter. This feed is read by an
|
|
22
|
+
* agent, which is better served by the frames themselves — every wrapper, in
|
|
23
|
+
* order, with the fields each one carries — than by someone else's summary of
|
|
24
|
+
* them.
|
|
25
|
+
*/
|
|
26
|
+
export type ErrorDescriptor = {
|
|
27
|
+
readonly _: "error";
|
|
28
|
+
/**
|
|
29
|
+
* The deepest non-empty message in the chain: what actually went wrong.
|
|
30
|
+
*
|
|
31
|
+
* A selection, not a synthesis — it is one of the messages in `causes`,
|
|
32
|
+
* hoisted because it is the field worth reading first and it is otherwise
|
|
33
|
+
* buried under however many wrappers the unwinding added.
|
|
34
|
+
*/
|
|
35
|
+
readonly message: string;
|
|
36
|
+
/** Outermost first. Frame `n + 1` is frame `n`'s `cause`. */
|
|
37
|
+
readonly causes: ReadonlyArray<Record<string, unknown>>;
|
|
38
|
+
};
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* A marker that survived where a value did not.
|
|
42
|
+
*
|
|
43
|
+
* Only ever emitted alongside real data — at `"full"`, and at `"shape"` for a
|
|
44
|
+
* string long enough to be cut — which is why these stay objects while the
|
|
45
|
+
* `"shape"` vocabulary is strings. A reader looking at real values has to be
|
|
46
|
+
* able to tell a marker from one of them, and `{_: …}` is that tell.
|
|
47
|
+
*
|
|
48
|
+
* `_` rather than `_tag` so a descriptor is never mistaken for a domain tagged
|
|
49
|
+
* union by anything reading the feed.
|
|
50
|
+
*
|
|
51
|
+
* Two markers are *keys* rather than arms of this union, because they annotate
|
|
52
|
+
* an encoded object from the inside and have nowhere else to go: `"full"` adds
|
|
53
|
+
* `_type` — a string — to a class instance, and `_elided` (whose value is the
|
|
54
|
+
* `"elided"` arm below) to an object whose key list was cut. Both are listed
|
|
55
|
+
* here so this type stays the one place the vocabulary is written down.
|
|
56
|
+
*/
|
|
57
|
+
export type ShapeDescriptor =
|
|
58
|
+
| { readonly _: "opaque"; readonly type: string }
|
|
59
|
+
| { readonly _: "string"; readonly length: number; readonly head: string }
|
|
60
|
+
| ErrorDescriptor
|
|
61
|
+
/** A value already on the path above this one. Emitted instead of recursing. */
|
|
62
|
+
| { readonly _: "cycle" }
|
|
63
|
+
/** A bound stopped the walk here. `by` names which one. */
|
|
64
|
+
| { readonly _: "elided"; readonly by: "depth" | "budget" | "entries"; readonly length?: number }
|
|
65
|
+
/**
|
|
66
|
+
* Collections, at `"full"` only — `"shape"` names them `Map(3)` and `Set(3)`.
|
|
67
|
+
* `size` is the collection's real size; `entries` and `values` are what
|
|
68
|
+
* survived the entry bound, so the two disagree when one was hit.
|
|
69
|
+
*/
|
|
70
|
+
| {
|
|
71
|
+
readonly _: "map";
|
|
72
|
+
readonly entries: ReadonlyArray<readonly [unknown, unknown]>;
|
|
73
|
+
readonly size: number;
|
|
74
|
+
}
|
|
75
|
+
| { readonly _: "set"; readonly values: ReadonlyArray<unknown>; readonly size: number };
|
|
76
|
+
|
|
77
|
+
/**
|
|
78
|
+
* What `"none"` puts where a value was.
|
|
79
|
+
*
|
|
80
|
+
* A word, not a descriptor: `"none"` is the policy that has decided the reader
|
|
81
|
+
* learns nothing about this value, and a key list or a type name is something.
|
|
82
|
+
* The same marker for every value, so it cannot be read as a shape either.
|
|
83
|
+
*/
|
|
84
|
+
export const WITHHELD = "withheld";
|
|
85
|
+
|
|
86
|
+
/**
|
|
87
|
+
* Reading a value can run the app's code, so reading it can throw.
|
|
88
|
+
*
|
|
89
|
+
* A getter that throws, a revoked `Proxy` — a finalized immer draft, a torn-down
|
|
90
|
+
* reactive scope — a prototype whose `constructor` is a throwing getter: every
|
|
91
|
+
* one of those turns `Object.keys` or an `instanceof` into an exception, and
|
|
92
|
+
* none of them is exotic in a frontend app.
|
|
93
|
+
*
|
|
94
|
+
* The consequence is what makes this worth guarding rather than letting throw.
|
|
95
|
+
* On the event path the encoder runs inside the app's own observer, and core
|
|
96
|
+
* routes an observer failure to sinks only — so the record would vanish without
|
|
97
|
+
* incrementing `dropped`, which is exactly the "did not happen" versus "was
|
|
98
|
+
* lost" distinction the protocol exists to preserve. On the snapshot path one
|
|
99
|
+
* unreadable node would fail the whole graph read and leave a reader with
|
|
100
|
+
* nothing instead of with 299 good rows and one marked hole.
|
|
101
|
+
*
|
|
102
|
+
* `{_: "opaque"}` is the honest answer: there is something here, and this
|
|
103
|
+
* encoder could not look at it. The thrown error's own message is not carried —
|
|
104
|
+
* it comes from app code, and a `"shape"` read that let one through would be a
|
|
105
|
+
* hole in the policy rather than a diagnostic.
|
|
106
|
+
*/
|
|
107
|
+
export const UNREADABLE = { _: "opaque", type: "unreadable" } satisfies ShapeDescriptor;
|
package/src/encode.ts
ADDED
|
@@ -0,0 +1,154 @@
|
|
|
1
|
+
import type { Runtime } from "@frondruntime/core";
|
|
2
|
+
import { describeError } from "./cause.ts";
|
|
3
|
+
import { WITHHELD } from "./descriptors.ts";
|
|
4
|
+
import { type Budget, describeFull, FULL_MAX_NODES } from "./full.ts";
|
|
5
|
+
import type { EncodePolicy } from "./policy.ts";
|
|
6
|
+
import type { EncodedEventRecord } from "./protocol.ts";
|
|
7
|
+
import { describeShape } from "./shape.ts";
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Applies a policy to a value.
|
|
11
|
+
*
|
|
12
|
+
* The three encoders this composes are deliberately separate modules: the clamp
|
|
13
|
+
* that decides disclosure (`policy.ts`), the walk that says as little as it can
|
|
14
|
+
* (`shape.ts`), the walk that says as much as it can (`full.ts`), and the one
|
|
15
|
+
* that describes failures the same way at every policy (`cause.ts`). What is
|
|
16
|
+
* left here is the wiring — which walk a policy gets, and how one runtime event
|
|
17
|
+
* is laid out on the wire.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* A policy, applied to one answer.
|
|
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.
|
|
27
|
+
*/
|
|
28
|
+
export type ValueEncoder = {
|
|
29
|
+
/** Ordinary app data, redacted according to the policy. */
|
|
30
|
+
readonly value: (value: unknown) => unknown;
|
|
31
|
+
/**
|
|
32
|
+
* A failure, as a chain of causes.
|
|
33
|
+
*
|
|
34
|
+
* Separate from {@link value} because the runtime already knows which is
|
|
35
|
+
* which, and sniffing would get it wrong: a failure that is not an `Error`
|
|
36
|
+
* instance — an Effect `Cause`, a node status — reaches the value encoder as
|
|
37
|
+
* an anonymous bag of keys.
|
|
38
|
+
*/
|
|
39
|
+
readonly failure: (value: unknown) => unknown;
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
export function createValueEncoder(policy: EncodePolicy): ValueEncoder {
|
|
43
|
+
// Spelled out rather than folded into the `"shape"` branch. Falling through
|
|
44
|
+
// was the bug: `"none"` reached the shape encoder and emitted key lists for
|
|
45
|
+
// every node in a graph snapshot, which is a description of app data by an
|
|
46
|
+
// app that had said it would send none.
|
|
47
|
+
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
|
+
};
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
if (policy === "shape") {
|
|
59
|
+
return {
|
|
60
|
+
value: (value) => describeShape(value, 0),
|
|
61
|
+
failure: (value) => describeError(value, policy),
|
|
62
|
+
};
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const budget: Budget = { remaining: FULL_MAX_NODES };
|
|
66
|
+
|
|
67
|
+
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
|
+
},
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Encodes one runtime event for the wire.
|
|
86
|
+
*
|
|
87
|
+
* Classification, work context, and node ids are metadata the runtime already
|
|
88
|
+
* owns and are copied verbatim — they are ids and enum members, never user
|
|
89
|
+
* data. Only the event body goes through the value encoder.
|
|
90
|
+
*/
|
|
91
|
+
export function encodeRecord(
|
|
92
|
+
record: Runtime.RuntimeEventRecord,
|
|
93
|
+
policy: EncodePolicy
|
|
94
|
+
): EncodedEventRecord {
|
|
95
|
+
const encoder = createValueEncoder(policy);
|
|
96
|
+
|
|
97
|
+
// The runtime pulls `failures` straight off the event's own fields, so the
|
|
98
|
+
// same object arrives twice — once as `fields.error`, once as `failures[0]`.
|
|
99
|
+
// Matched by identity so both come out as the same thing; a record that
|
|
100
|
+
// described one failure two different ways would read as two.
|
|
101
|
+
const known = new Set(
|
|
102
|
+
record.failures.filter(
|
|
103
|
+
(failure): failure is object => typeof failure === "object" && failure !== null
|
|
104
|
+
)
|
|
105
|
+
);
|
|
106
|
+
|
|
107
|
+
const encodeField = (value: unknown): unknown =>
|
|
108
|
+
typeof value === "object" && value !== null && known.has(value)
|
|
109
|
+
? encoder.failure(value)
|
|
110
|
+
: encoder.value(value);
|
|
111
|
+
|
|
112
|
+
return {
|
|
113
|
+
sequence: record.sequence,
|
|
114
|
+
recordedAt: record.recordedAt,
|
|
115
|
+
tag: record.event._tag,
|
|
116
|
+
category: record.classification.category,
|
|
117
|
+
severity: record.classification.severity,
|
|
118
|
+
timeline: record.classification.timeline,
|
|
119
|
+
reportable: record.classification.reportable,
|
|
120
|
+
workId: record.work.workId,
|
|
121
|
+
parentWorkId: record.work.parentWorkId,
|
|
122
|
+
source: record.work.source,
|
|
123
|
+
reason: record.work.reason,
|
|
124
|
+
priority: record.work.priority,
|
|
125
|
+
nodeIds: record.nodeIds,
|
|
126
|
+
fields: policy === "none" ? {} : describeFields(record.event, encodeField),
|
|
127
|
+
// Failures are causes, not results: their messages are what makes a
|
|
128
|
+
// devtools feed worth reading, so they are described rather than dropped —
|
|
129
|
+
// including under `"none"`, whose subject is values, not what broke.
|
|
130
|
+
//
|
|
131
|
+
// Encoded as failures rather than as values, because that is what the
|
|
132
|
+
// runtime says they are — no sniffing required. Which matters for the ones
|
|
133
|
+
// that are not `Error` instances: an Effect `Cause` reaching the value
|
|
134
|
+
// encoder comes out as a bag of key names.
|
|
135
|
+
failures: record.failures.map(encoder.failure),
|
|
136
|
+
};
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
function describeFields(
|
|
140
|
+
event: Runtime.RuntimeEvent,
|
|
141
|
+
encodeValue: (value: unknown) => unknown
|
|
142
|
+
): Record<string, unknown> {
|
|
143
|
+
const fields: Record<string, unknown> = {};
|
|
144
|
+
|
|
145
|
+
for (const [key, value] of Object.entries(event)) {
|
|
146
|
+
if (key === "_tag") {
|
|
147
|
+
continue;
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
fields[key] = encodeValue(value);
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
return fields;
|
|
154
|
+
}
|