@tinyactors/node 0.1.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/LICENSE +21 -0
- package/README.md +169 -0
- package/index.d.ts +1875 -0
- package/index.js +34 -0
- package/lib/actor.js +85 -0
- package/lib/debug/breakpoints.js +349 -0
- package/lib/debug/console.js +149 -0
- package/lib/debug/expressions.js +133 -0
- package/lib/debug/frames.js +119 -0
- package/lib/debug/labels.js +142 -0
- package/lib/debug/macrosteps.js +207 -0
- package/lib/debug/protocol.js +186 -0
- package/lib/debug/sources.js +218 -0
- package/lib/debug/variables.js +265 -0
- package/lib/debug.js +1434 -0
- package/lib/definition.js +139 -0
- package/lib/errors.js +24 -0
- package/lib/events.js +56 -0
- package/lib/image.js +90 -0
- package/lib/loader.js +68 -0
- package/lib/metrics.js +333 -0
- package/lib/native.js +8 -0
- package/lib/otlp.js +332 -0
- package/lib/statechart.js +768 -0
- package/lib/system.js +2183 -0
- package/lib/tracing.js +164 -0
- package/package.json +41 -0
package/index.js
ADDED
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
const native = require('./lib/native');
|
|
4
|
+
const { TinyactorsError } = require('./lib/errors');
|
|
5
|
+
const { createSystem } = require('./lib/system');
|
|
6
|
+
const { statechart, literal, content } = require('./lib/statechart');
|
|
7
|
+
const { TRACE_KINDS, parseTraceparent, formatTraceparent, stepSpanID } = require('./lib/tracing');
|
|
8
|
+
const { decodeTraces } = require('./lib/otlp');
|
|
9
|
+
const { metricsToOTLP } = require('./lib/metrics');
|
|
10
|
+
const { createDebugSession, DAPReader, encodeDAPMessage } = require('./lib/debug');
|
|
11
|
+
|
|
12
|
+
module.exports = {
|
|
13
|
+
version: native.version,
|
|
14
|
+
createSystem,
|
|
15
|
+
statechart,
|
|
16
|
+
literal,
|
|
17
|
+
content,
|
|
18
|
+
TinyactorsError,
|
|
19
|
+
// Tracing (core ADR 0067, napi ADR 0016): OTLP bytes, and a decoder; no
|
|
20
|
+
// telemetry dependency.
|
|
21
|
+
TRACE_KINDS,
|
|
22
|
+
decodeTraces,
|
|
23
|
+
parseTraceparent,
|
|
24
|
+
formatTraceparent,
|
|
25
|
+
stepSpanID,
|
|
26
|
+
// Metrics (core ADR 0072, napi ADR 0017): system.metrics() and its OTLP bytes.
|
|
27
|
+
metricsToOTLP,
|
|
28
|
+
// The debug adapter (napi ADR 0026): a DAP session the application puts
|
|
29
|
+
// behind its own transport, and the base protocol's framing for byte
|
|
30
|
+
// streams.
|
|
31
|
+
createDebugSession,
|
|
32
|
+
DAPReader,
|
|
33
|
+
encodeDAPMessage,
|
|
34
|
+
};
|
package/lib/actor.js
ADDED
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// ActorID/Actor view (ADR 0002). An actor is named by its slot and
|
|
4
|
+
// generation, two small integers. A view holds its system and those two
|
|
5
|
+
// numbers and nothing else: it has no native resource and no finalizer, and
|
|
6
|
+
// every question about the actor is asked of core through the system. A view
|
|
7
|
+
// of a destroyed actor is harmless: its calls fail with `not-found`.
|
|
8
|
+
//
|
|
9
|
+
// The pump makes views natively for the actors it passes to hooks, so the
|
|
10
|
+
// class is registered with the addon once (setupActor).
|
|
11
|
+
|
|
12
|
+
const native = require('./native');
|
|
13
|
+
|
|
14
|
+
class ActorID {
|
|
15
|
+
constructor(system, slot, generation) {
|
|
16
|
+
this.system = system;
|
|
17
|
+
this.slot = slot;
|
|
18
|
+
this.generation = generation;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** Equality is by value (ADR 0002 point 5). */
|
|
22
|
+
equals(other) {
|
|
23
|
+
return (
|
|
24
|
+
other instanceof ActorID &&
|
|
25
|
+
other.system === this.system &&
|
|
26
|
+
other.slot === this.slot &&
|
|
27
|
+
other.generation === this.generation
|
|
28
|
+
);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Queue an event for this actor (System.post). */
|
|
32
|
+
post(event, data, options) {
|
|
33
|
+
this.system.post(this, event, data, options);
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** Queue an event for this actor and await its macrostep (System.send). */
|
|
37
|
+
send(event, data, options) {
|
|
38
|
+
return this.system.send(this, event, data, options);
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** A snapshot of core's view of this actor. */
|
|
42
|
+
inspect() {
|
|
43
|
+
return this.system.inspect(this);
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/** True when no resident actor has this ID any more. */
|
|
47
|
+
get destroyed() {
|
|
48
|
+
return !this.system.exists(this);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/** The actor's live data-model root, shared, not copied; undefined under the null data model. */
|
|
52
|
+
data() {
|
|
53
|
+
return this.system.inspect(this).data;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** Capture this actor in memory (System.capture). */
|
|
57
|
+
capture() {
|
|
58
|
+
return this.system.capture(this);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
/** Offload this stable named actor from memory (System.unload, core ADR 0074). */
|
|
62
|
+
unload() {
|
|
63
|
+
this.system.unload(this);
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/** Prepare a fresh unpublished actor of `definition` to replace this one (System.prepareReplacement). */
|
|
67
|
+
prepareReplacement(definition, options) {
|
|
68
|
+
return this.system.prepareReplacement(this, definition, options);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
/** Terminate this actor. Invoked children are not destroyed implicitly. */
|
|
72
|
+
destroy() {
|
|
73
|
+
this.system.destroy(this);
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
[Symbol.dispose]() {
|
|
77
|
+
if (!this.system.closed && !this.destroyed) {
|
|
78
|
+
this.destroy();
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
native.setupActor(ActorID);
|
|
84
|
+
|
|
85
|
+
module.exports = { ActorID };
|
|
@@ -0,0 +1,349 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Breakpoints: function breakpoints by name, line breakpoints on the
|
|
4
|
+
// element a source line holds (core ADR 0085), the exception filters, and
|
|
5
|
+
// data breakpoints on data-model locations. Each is found in the records of
|
|
6
|
+
// a macrostep that ended (lib/debug/macrosteps). A live actor is never
|
|
7
|
+
// stopped, so every breakpoint is a tracepoint: the session says where it
|
|
8
|
+
// would have stopped. A line breakpoint with a log message is a logpoint:
|
|
9
|
+
// it writes its message instead.
|
|
10
|
+
|
|
11
|
+
const { TinyactorsError } = require('../errors');
|
|
12
|
+
|
|
13
|
+
const EXCEPTION_FILTERS = Object.freeze([
|
|
14
|
+
{ filter: 'error.execution', label: 'error.execution',
|
|
15
|
+
description: 'An action, a guard or a <data> failed, and core raised error.execution' },
|
|
16
|
+
{ filter: 'error.communication', label: 'error.communication',
|
|
17
|
+
description: 'A <send> or an invocation could not reach its target' },
|
|
18
|
+
{ filter: 'error.platform', label: 'error.platform', description: 'The platform raised an error event' },
|
|
19
|
+
{ filter: 'ignored', label: 'Ignored events',
|
|
20
|
+
description: 'An event was taken and enabled no transition (core ADR 0072)' },
|
|
21
|
+
{ filter: 'stopped', label: 'Out of memory', description: 'A run stopped because an allocation failed (core ADR 0070)' },
|
|
22
|
+
{ filter: 'runaway', label: 'Runaway macrosteps',
|
|
23
|
+
description: 'A macrostep ran its microstep limit, and the actor was quarantined (core ADR 0075)' },
|
|
24
|
+
]);
|
|
25
|
+
const FILTERS = EXCEPTION_FILTERS.map((entry) => entry.filter);
|
|
26
|
+
const ERRORS = FILTERS.slice(0, 3);
|
|
27
|
+
|
|
28
|
+
// SCXML event descriptors match by prefix at dot boundaries (SCXML 3.12.1).
|
|
29
|
+
function matchesEvent(descriptor, name) {
|
|
30
|
+
if (typeof name !== 'string') return false;
|
|
31
|
+
const bare = descriptor.replace(/\.\*$/, '').replace(/\.$/, '');
|
|
32
|
+
return bare === '*' || name === bare || name.startsWith(`${bare}.`);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
const normalize = (text) => text.replaceAll('->', '→').replace(/\s+/g, ' ').trim();
|
|
36
|
+
|
|
37
|
+
// `5` and `>= 5` stop from the fifth hit on, `== 5` only at it, `% 5` at
|
|
38
|
+
// every fifth.
|
|
39
|
+
function hitConditionMet(text, hits) {
|
|
40
|
+
if (text === undefined || text === null || String(text).trim() === '') return true;
|
|
41
|
+
const match = /^\s*(>=|>|==|<=|<|%)?\s*(\d+)\s*$/.exec(String(text));
|
|
42
|
+
if (match === null) return true;
|
|
43
|
+
const count = Number(match[2]);
|
|
44
|
+
switch (match[1]) {
|
|
45
|
+
case '>': return hits > count;
|
|
46
|
+
case '==': return hits === count;
|
|
47
|
+
case '<=': return hits <= count;
|
|
48
|
+
case '<': return hits < count;
|
|
49
|
+
case '%': return count > 0 && hits % count === 0;
|
|
50
|
+
default: return hits >= count;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function parseFunction(name) {
|
|
55
|
+
let match = /^exit:\s*(\S+)$/.exec(name);
|
|
56
|
+
if (match !== null) return { kind: 'exit', target: match[1] };
|
|
57
|
+
match = /^on:\s*(\S+)$/.exec(name);
|
|
58
|
+
if (match !== null) return { kind: 'on', target: match[1] };
|
|
59
|
+
if (/(→|->)/.test(name)) return { kind: 'transition', target: normalize(name) };
|
|
60
|
+
return { kind: 'entry', target: name };
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
function describe(breakpoint) {
|
|
64
|
+
switch (breakpoint.kind) {
|
|
65
|
+
case 'entry': return `entered ${breakpoint.target}`;
|
|
66
|
+
case 'exit': return `exited ${breakpoint.target}`;
|
|
67
|
+
case 'on': return `took ${breakpoint.target}`;
|
|
68
|
+
default: return breakpoint.target;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
// A line breakpoint's element, as the breakpoint's description names it.
|
|
73
|
+
function describeLine(breakpoint) {
|
|
74
|
+
const { element } = breakpoint;
|
|
75
|
+
return `line ${breakpoint.line} (${element.kind} ${element.name ?? element.id})`;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
// The line breakpoints of one DAP Source are kept under its path, or its
|
|
79
|
+
// sourceReference for a virtual source (napi ADR 0026).
|
|
80
|
+
const sourceKey = (source) => (source.path !== undefined ? `path ${source.path}` : `reference ${source.sourceReference}`);
|
|
81
|
+
|
|
82
|
+
// A condition that is not blank.
|
|
83
|
+
function hasCondition(breakpoint) {
|
|
84
|
+
return breakpoint.condition !== undefined && breakpoint.condition !== null && String(breakpoint.condition).trim() !== '';
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
class Breakpoints {
|
|
88
|
+
#functions = [];
|
|
89
|
+
#data = [];
|
|
90
|
+
#lines = new Map();
|
|
91
|
+
#filters = new Set();
|
|
92
|
+
|
|
93
|
+
/** Whether the client asked to stop for the exception filter `filter`. */
|
|
94
|
+
wants(filter) {
|
|
95
|
+
return this.#filters.has(filter);
|
|
96
|
+
}
|
|
97
|
+
#next = 0;
|
|
98
|
+
|
|
99
|
+
#allLines() {
|
|
100
|
+
return [...this.#lines.values()].flatMap(({ entries }) => entries).filter((entry) => entry.element !== undefined);
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* setBreakpoints for one source, { path } or { sourceReference } (napi
|
|
105
|
+
* ADR 0026): replaces that source's breakpoints. `resolve(line)` answers
|
|
106
|
+
* the element the line stands for, as { element: { kind, id, name },
|
|
107
|
+
* line, column, source }, or a string saying why there is none. Answers
|
|
108
|
+
* DAP Breakpoint objects.
|
|
109
|
+
*/
|
|
110
|
+
setLines(source, specs, resolve) {
|
|
111
|
+
const entries = [];
|
|
112
|
+
const answered = specs.map((spec) => {
|
|
113
|
+
const id = (this.#next += 1);
|
|
114
|
+
const found = resolve(Number(spec?.line));
|
|
115
|
+
if (typeof found === 'string' || found === undefined) {
|
|
116
|
+
entries.push({ id, spec });
|
|
117
|
+
return { id, verified: false, message: found ?? `no state, transition or action at line ${spec?.line}` };
|
|
118
|
+
}
|
|
119
|
+
const breakpoint = { id, kind: 'line', spec, line: found.line, element: found.element, condition: spec.condition,
|
|
120
|
+
hitCondition: spec.hitCondition, logMessage: spec.logMessage, hits: 0 };
|
|
121
|
+
entries.push(breakpoint);
|
|
122
|
+
return { id, verified: true, line: found.line, column: found.column, source: found.source };
|
|
123
|
+
});
|
|
124
|
+
this.#lines.set(sourceKey(source), { source, entries });
|
|
125
|
+
return answered;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** The placed breakpoints of every kind that have a condition. */
|
|
129
|
+
get conditioned() {
|
|
130
|
+
const lines = [...this.#lines.values()].flatMap(({ entries }) => entries.filter((entry) => entry.kind === 'line'));
|
|
131
|
+
return [...lines, ...this.#functions, ...this.#data].filter((breakpoint) => hasCondition(breakpoint));
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
/** The sources with line breakpoints and what the client asked for, to resolve again later. */
|
|
135
|
+
get lineRequests() {
|
|
136
|
+
return [...this.#lines.values()].map(({ source, entries }) => ({ source, specs: entries.map((entry) => entry.spec),
|
|
137
|
+
ids: entries.map((entry) => entry.id) }));
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
/**
|
|
141
|
+
* Resolves a source's line breakpoints again (after attaching), keeping
|
|
142
|
+
* their IDs. Answers the DAP Breakpoint objects, for `breakpoint` events.
|
|
143
|
+
*/
|
|
144
|
+
relocate(source, resolve) {
|
|
145
|
+
const entries = this.#lines.get(sourceKey(source))?.entries ?? [];
|
|
146
|
+
const answered = [];
|
|
147
|
+
this.#lines.set(sourceKey(source), { source, entries: entries.map((entry) => {
|
|
148
|
+
const found = resolve(Number(entry.spec?.line));
|
|
149
|
+
if (typeof found === 'string' || found === undefined) {
|
|
150
|
+
answered.push({ id: entry.id, verified: false,
|
|
151
|
+
message: found ?? `no state, transition or action at line ${entry.spec?.line}` });
|
|
152
|
+
return { id: entry.id, spec: entry.spec };
|
|
153
|
+
}
|
|
154
|
+
answered.push({ id: entry.id, verified: true, line: found.line, column: found.column, source: found.source });
|
|
155
|
+
return { ...entry, kind: 'line', line: found.line, element: found.element, condition: entry.spec.condition,
|
|
156
|
+
hitCondition: entry.spec.hitCondition, logMessage: entry.spec.logMessage, hits: entry.hits ?? 0 };
|
|
157
|
+
}) });
|
|
158
|
+
return answered;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* setFunctionBreakpoints: replaces them all. `check(breakpoint)` answers
|
|
163
|
+
* undefined or why the breakpoint cannot be verified. Answers DAP
|
|
164
|
+
* Breakpoint objects.
|
|
165
|
+
*/
|
|
166
|
+
setFunctions(specs, check) {
|
|
167
|
+
this.#functions = [];
|
|
168
|
+
return specs.map((spec) => {
|
|
169
|
+
const name = String(spec?.name ?? '').trim();
|
|
170
|
+
const breakpoint = { id: (this.#next += 1), name, ...parseFunction(name), condition: spec?.condition,
|
|
171
|
+
hitCondition: spec?.hitCondition, hits: 0 };
|
|
172
|
+
const problem = name === '' ? 'a function breakpoint needs a name' : check(breakpoint);
|
|
173
|
+
if (problem !== undefined) {
|
|
174
|
+
return { id: breakpoint.id, verified: false, message: problem };
|
|
175
|
+
}
|
|
176
|
+
this.#functions.push(breakpoint);
|
|
177
|
+
return { id: breakpoint.id, verified: true };
|
|
178
|
+
});
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
setFilters(filters) {
|
|
182
|
+
const unknown = filters.filter((filter) => !FILTERS.includes(filter));
|
|
183
|
+
if (unknown.length > 0) {
|
|
184
|
+
throw new TinyactorsError(`unknown exception filter(s): ${unknown.join(', ')}`, 'invalid');
|
|
185
|
+
}
|
|
186
|
+
this.#filters = new Set(filters);
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
/**
|
|
190
|
+
* setDataBreakpoints: replaces them all. A dataId is the thread's label
|
|
191
|
+
* and a path of keys as JSON: `acct_1 ["failures"]`. `check(breakpoint)`
|
|
192
|
+
* as for functions.
|
|
193
|
+
*/
|
|
194
|
+
setData(specs, check) {
|
|
195
|
+
this.#data = [];
|
|
196
|
+
return specs.map((spec) => {
|
|
197
|
+
const parsed = Breakpoints.parseDataID(spec?.dataId);
|
|
198
|
+
const id = (this.#next += 1);
|
|
199
|
+
if (parsed === undefined) {
|
|
200
|
+
return { id, verified: false, message: `${JSON.stringify(spec?.dataId)} is not a data-model location` };
|
|
201
|
+
}
|
|
202
|
+
if (spec.accessType !== undefined && spec.accessType !== 'write') {
|
|
203
|
+
return { id, verified: false, message: 'only writes can be watched: core traces assignments, not reads' };
|
|
204
|
+
}
|
|
205
|
+
const breakpoint = { id, ...parsed, dataId: spec.dataId, condition: spec.condition,
|
|
206
|
+
hitCondition: spec.hitCondition, hits: 0 };
|
|
207
|
+
const problem = check(breakpoint);
|
|
208
|
+
if (problem !== undefined) {
|
|
209
|
+
return { id, verified: false, message: problem };
|
|
210
|
+
}
|
|
211
|
+
this.#data.push(breakpoint);
|
|
212
|
+
return { id, verified: true };
|
|
213
|
+
});
|
|
214
|
+
}
|
|
215
|
+
|
|
216
|
+
static dataID(label, path) {
|
|
217
|
+
return `${label} ${JSON.stringify(path)}`;
|
|
218
|
+
}
|
|
219
|
+
|
|
220
|
+
// A label can have spaces (`renewal/r1 invocation kid`), so the path is what
|
|
221
|
+
// follows the first ` [` that starts a JSON array.
|
|
222
|
+
static parseDataID(text) {
|
|
223
|
+
if (typeof text !== 'string') return undefined;
|
|
224
|
+
for (let at = text.indexOf(' ['); at > 0; at = text.indexOf(' [', at + 1)) {
|
|
225
|
+
let path;
|
|
226
|
+
try {
|
|
227
|
+
path = JSON.parse(text.slice(at + 1));
|
|
228
|
+
} catch {
|
|
229
|
+
continue;
|
|
230
|
+
}
|
|
231
|
+
return Array.isArray(path) && path.length > 0 ? { label: text.slice(0, at), path } : undefined;
|
|
232
|
+
}
|
|
233
|
+
return undefined;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* The hits in a macrostep that ended, of the actor labelled `label`:
|
|
238
|
+
* [{ kind: 'function' | 'exception' | 'data', breakpoints, description,
|
|
239
|
+
* exception }]. `location(expressionID)` names an <assign>'s location;
|
|
240
|
+
* `fires(breakpoint)` confirms a condition.
|
|
241
|
+
*/
|
|
242
|
+
hits(macrostep, { label, location, fires, log }) {
|
|
243
|
+
const out = [];
|
|
244
|
+
const exception = this.#exception(macrostep);
|
|
245
|
+
if (exception !== undefined) out.push(exception);
|
|
246
|
+
const lines = this.#allLines().filter((breakpoint) => lineRan(breakpoint.element, macrostep))
|
|
247
|
+
.filter((breakpoint) => this.#fire(breakpoint, fires))
|
|
248
|
+
.filter((breakpoint) => (breakpoint.logMessage ? (log(breakpoint), false) : true));
|
|
249
|
+
if (lines.length > 0) {
|
|
250
|
+
out.push({ kind: 'line', breakpoints: lines.map((entry) => entry.id),
|
|
251
|
+
description: lines.map(describeLine).join(', ') });
|
|
252
|
+
}
|
|
253
|
+
const functions = this.#functions.filter((breakpoint) => {
|
|
254
|
+
switch (breakpoint.kind) {
|
|
255
|
+
case 'on': return macrostep.event !== null && matchesEvent(breakpoint.target, macrostep.event.name);
|
|
256
|
+
case 'entry': return macrostep.microsteps.some((micro) => micro.entered.includes(breakpoint.target));
|
|
257
|
+
case 'exit': return macrostep.microsteps.some((micro) => micro.exited.includes(breakpoint.target));
|
|
258
|
+
default: return macrostep.microsteps.some((micro) => micro.transitions.some((text) => {
|
|
259
|
+
const shown = normalize(text);
|
|
260
|
+
return shown === breakpoint.target || shown.startsWith(`${breakpoint.target} on `);
|
|
261
|
+
}));
|
|
262
|
+
}
|
|
263
|
+
}).filter((breakpoint) => this.#fire(breakpoint, fires));
|
|
264
|
+
if (functions.length > 0) {
|
|
265
|
+
out.push({ kind: 'function', breakpoints: functions.map((entry) => entry.id),
|
|
266
|
+
description: functions.map(describe).join(', ') });
|
|
267
|
+
}
|
|
268
|
+
const written = macrostep.records.filter((entry) => entry.name === 'scxml.assign')
|
|
269
|
+
.map((entry) => ({ location: location(entry.attributes['scxml.expression.id']),
|
|
270
|
+
value: entry.attributes['scxml.value'] }))
|
|
271
|
+
.filter((entry) => entry.location !== undefined);
|
|
272
|
+
const data = this.#data.filter((breakpoint) => breakpoint.label === label &&
|
|
273
|
+
written.some((entry) => overlap(breakpoint.path, entry.location)))
|
|
274
|
+
.filter((breakpoint) => this.#fire(breakpoint, fires));
|
|
275
|
+
if (data.length > 0) {
|
|
276
|
+
const writes = written.filter((entry) => data.some((breakpoint) => overlap(breakpoint.path, entry.location)));
|
|
277
|
+
out.push({ kind: 'data', breakpoints: data.map((entry) => entry.id),
|
|
278
|
+
description: writes.map((entry) => `${entry.location.join('.')}${entry.value === undefined ? ' written'
|
|
279
|
+
: ` = ${entry.value}`}`).join(', ') });
|
|
280
|
+
}
|
|
281
|
+
return out;
|
|
282
|
+
}
|
|
283
|
+
|
|
284
|
+
#fire(breakpoint, fires) {
|
|
285
|
+
if (hasCondition(breakpoint) && !fires(breakpoint)) {
|
|
286
|
+
return false;
|
|
287
|
+
}
|
|
288
|
+
breakpoint.hits += 1;
|
|
289
|
+
return hitConditionMet(breakpoint.hitCondition, breakpoint.hits);
|
|
290
|
+
}
|
|
291
|
+
|
|
292
|
+
#exception(macrostep) {
|
|
293
|
+
if (this.#filters.size === 0) return undefined;
|
|
294
|
+
const candidates = [];
|
|
295
|
+
if (macrostep.event !== null) {
|
|
296
|
+
const filter = ERRORS.find((name) => matchesEvent(name, macrostep.event.name));
|
|
297
|
+
if (filter !== undefined) candidates.push({ filter, name: macrostep.event.name, data: macrostep.event.data });
|
|
298
|
+
}
|
|
299
|
+
let fault;
|
|
300
|
+
for (const entry of macrostep.records) {
|
|
301
|
+
const a = entry.attributes;
|
|
302
|
+
if (entry.name === 'scxml.error') {
|
|
303
|
+
fault = faultText(a);
|
|
304
|
+
} else if (entry.name === 'scxml.raise') {
|
|
305
|
+
const filter = ERRORS.find((name) => matchesEvent(name, a['scxml.event.name']));
|
|
306
|
+
if (filter !== undefined) candidates.push({ filter, name: a['scxml.event.name'], fault });
|
|
307
|
+
} else if (entry.name === 'scxml.ignored') {
|
|
308
|
+
candidates.push({ filter: 'ignored', name: a['scxml.event.name'] });
|
|
309
|
+
} else if (entry.name === 'scxml.stopped') {
|
|
310
|
+
candidates.push({ filter: 'stopped', name: undefined });
|
|
311
|
+
}
|
|
312
|
+
}
|
|
313
|
+
const hit = candidates.find((candidate) => this.#filters.has(candidate.filter));
|
|
314
|
+
if (hit === undefined) return undefined;
|
|
315
|
+
const description = hit.filter === 'ignored' ? `${hit.name} enabled no transition`
|
|
316
|
+
: hit.filter === 'stopped' ? 'an allocation failed; the run stopped where it stood'
|
|
317
|
+
: [hit.name, hit.fault].filter((part) => part !== undefined).join(': ');
|
|
318
|
+
return { kind: 'exception', breakpoints: [], description, exception: hit };
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
|
|
322
|
+
// What faulted and why, from a record's attributes: the action (or the
|
|
323
|
+
// transition whose guard failed) and the fault's message, as the test
|
|
324
|
+
// host's adapter says it too.
|
|
325
|
+
function faultText(a) {
|
|
326
|
+
const parts = [a['scxml.action'] ?? a['scxml.transition'], a['scxml.fault.message']]
|
|
327
|
+
.filter((part) => part !== undefined && part !== '');
|
|
328
|
+
return parts.length === 0 ? a['scxml.fault.detail'] : parts.join(': ');
|
|
329
|
+
}
|
|
330
|
+
|
|
331
|
+
// Whether a macrostep ran the element a line breakpoint stands for.
|
|
332
|
+
function lineRan(element, macrostep) {
|
|
333
|
+
switch (element.kind) {
|
|
334
|
+
case 'state': return macrostep.microsteps.some((micro) => micro.entered.includes(element.name));
|
|
335
|
+
case 'transition': return macrostep.microsteps.some((micro) => micro.transitionIDs.includes(element.id));
|
|
336
|
+
default: return macrostep.records.some((entry) => entry.attributes['scxml.action.id'] === element.id);
|
|
337
|
+
}
|
|
338
|
+
}
|
|
339
|
+
|
|
340
|
+
// A write to `written` touches `watched` when one path is a prefix of the other.
|
|
341
|
+
function overlap(watched, written) {
|
|
342
|
+
const length = Math.min(watched.length, written.length);
|
|
343
|
+
for (let at = 0; at < length; at += 1) {
|
|
344
|
+
if (String(watched[at]) !== String(written[at])) return false;
|
|
345
|
+
}
|
|
346
|
+
return true;
|
|
347
|
+
}
|
|
348
|
+
|
|
349
|
+
module.exports = { Breakpoints, EXCEPTION_FILTERS, matchesEvent };
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// The debug console: what a client sends as `evaluate` with context
|
|
4
|
+
// `repl`, and the completions it offers there.
|
|
5
|
+
//
|
|
6
|
+
// send <event> [json] deliver through the actor's mailbox, with the console as origin
|
|
7
|
+
// goto <state…> [from <state>] an operator transition (core ADR 0082)
|
|
8
|
+
// abandon abandon a macrostep that never ends (core ADR 0082)
|
|
9
|
+
// cancel <send ID> withdraw one pending delayed send (core ADR 0084)
|
|
10
|
+
// replace <revision> hot-replace the actor with another revision of its family
|
|
11
|
+
// <expression> JavaScript over the data model (lib/debug/expressions)
|
|
12
|
+
//
|
|
13
|
+
// The console is a sender an actor can answer (core ADR 0068): the adapter
|
|
14
|
+
// registers an I/O processor of type `debug` once per system and opens one
|
|
15
|
+
// scope per session, so a chart's reply to `event.origin` reaches the
|
|
16
|
+
// session that sent the message.
|
|
17
|
+
|
|
18
|
+
const { TinyactorsError } = require('../errors');
|
|
19
|
+
const { locations } = require('./expressions');
|
|
20
|
+
|
|
21
|
+
const TYPE = 'debug';
|
|
22
|
+
const COMMANDS = ['send', 'goto', 'abandon', 'cancel', 'replace', 'help'];
|
|
23
|
+
|
|
24
|
+
const HELP = [
|
|
25
|
+
'send <event> [json] deliver an event, queued behind the actor\'s mail; replies show here',
|
|
26
|
+
'goto <state…> [from <state>] an operator transition: exits, entries and history as a transition\'s',
|
|
27
|
+
'abandon abandon a macrostep that never ends; the actor keeps its last configuration',
|
|
28
|
+
'cancel <send ID> withdraw a pending delayed send, by the ID the Timers scope shows',
|
|
29
|
+
'replace <revision> replace the actor with another registered revision of its family',
|
|
30
|
+
'<expression> JavaScript over the data model: `failures`, `.items[0]`, `inState("busy")`',
|
|
31
|
+
];
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Splits a console line into a command and its arguments, or answers
|
|
35
|
+
* { command: 'expression', text } for anything else.
|
|
36
|
+
*/
|
|
37
|
+
function parse(line) {
|
|
38
|
+
const text = String(line).trim();
|
|
39
|
+
const [word, ...rest] = text.split(/\s+/);
|
|
40
|
+
const tail = text.slice(word.length).trim();
|
|
41
|
+
switch (word) {
|
|
42
|
+
case 'send': {
|
|
43
|
+
if (rest.length === 0) throw new TinyactorsError('send <event> [json]', 'invalid');
|
|
44
|
+
const event = rest[0];
|
|
45
|
+
const json = tail.slice(event.length).trim();
|
|
46
|
+
let data;
|
|
47
|
+
if (json !== '') {
|
|
48
|
+
try {
|
|
49
|
+
data = JSON.parse(json);
|
|
50
|
+
} catch (error) {
|
|
51
|
+
throw new TinyactorsError(`the event data is not JSON: ${error.message}`, 'invalid');
|
|
52
|
+
}
|
|
53
|
+
}
|
|
54
|
+
return { command: 'send', event, data };
|
|
55
|
+
}
|
|
56
|
+
case 'goto': {
|
|
57
|
+
const at = rest.indexOf('from');
|
|
58
|
+
const targets = at < 0 ? rest : rest.slice(0, at);
|
|
59
|
+
const from = at < 0 ? undefined : rest[at + 1];
|
|
60
|
+
if (targets.length === 0 || (at >= 0 && (from === undefined || rest.length > at + 2))) {
|
|
61
|
+
throw new TinyactorsError('goto <state…> [from <state>]', 'invalid');
|
|
62
|
+
}
|
|
63
|
+
return { command: 'goto', targets, from };
|
|
64
|
+
}
|
|
65
|
+
case 'abandon':
|
|
66
|
+
case 'help':
|
|
67
|
+
return { command: word };
|
|
68
|
+
case 'cancel':
|
|
69
|
+
if (rest.length !== 1) throw new TinyactorsError('cancel <send ID>: the ID the Timers scope shows', 'invalid');
|
|
70
|
+
return { command: 'cancel', id: rest[0] };
|
|
71
|
+
case 'replace':
|
|
72
|
+
if (rest.length !== 1) {
|
|
73
|
+
throw new TinyactorsError('replace <revision>: a registered revision of the actor\'s family', 'invalid');
|
|
74
|
+
}
|
|
75
|
+
return { command: 'replace', revision: rest[0] };
|
|
76
|
+
default:
|
|
77
|
+
return { command: 'expression', text };
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
/**
|
|
82
|
+
* Completion targets for `text` with the cursor at `column` (0-based).
|
|
83
|
+
* `context` gives events(), states(), sendIDs() and data() of the actor.
|
|
84
|
+
*/
|
|
85
|
+
function completions(text, column, context) {
|
|
86
|
+
const before = String(text).slice(0, column);
|
|
87
|
+
const target = (label, start, type) => ({ label, text: label, start, length: column - start, type });
|
|
88
|
+
let match = /^\s*send\s+(\S*)$/.exec(before);
|
|
89
|
+
if (match !== null) {
|
|
90
|
+
const prefix = match[1];
|
|
91
|
+
return context.events().filter((name) => name.startsWith(prefix))
|
|
92
|
+
.map((name) => target(name, column - prefix.length, 'event'));
|
|
93
|
+
}
|
|
94
|
+
match = /^\s*goto\s+(?:\S+\s+)*(\S*)$/.exec(before);
|
|
95
|
+
if (match !== null) {
|
|
96
|
+
const prefix = match[1];
|
|
97
|
+
return context.states().filter((name) => name.startsWith(prefix))
|
|
98
|
+
.map((name) => target(name, column - prefix.length, 'value'));
|
|
99
|
+
}
|
|
100
|
+
match = /^\s*cancel\s+(\S*)$/.exec(before);
|
|
101
|
+
if (match !== null) {
|
|
102
|
+
const prefix = match[1];
|
|
103
|
+
return context.sendIDs().filter((id) => id.startsWith(prefix))
|
|
104
|
+
.map((id) => target(id, column - prefix.length, 'value'));
|
|
105
|
+
}
|
|
106
|
+
match = /^\s*(\w*)$/.exec(before);
|
|
107
|
+
if (match !== null && match[1] !== '') {
|
|
108
|
+
const words = COMMANDS.filter((word) => word.startsWith(match[1]));
|
|
109
|
+
if (words.length > 0) return words.map((word) => target(word, column - match[1].length, 'keyword'));
|
|
110
|
+
}
|
|
111
|
+
return locations(before, context.data()).map(({ label, start }) => target(label, start, 'property'));
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
// One `debug` I/O processor per system; replies find their session by the
|
|
115
|
+
// scope URI they are sent to.
|
|
116
|
+
const registries = new WeakMap();
|
|
117
|
+
|
|
118
|
+
/**
|
|
119
|
+
* Registers the `debug` I/O processor on `system` (once), opens a scope
|
|
120
|
+
* for `uri`, and routes replies sent to it to `onReply(request)`. Answers
|
|
121
|
+
* { scope, close() }.
|
|
122
|
+
*/
|
|
123
|
+
function openConsole(system, uri, onReply) {
|
|
124
|
+
let registry = registries.get(system);
|
|
125
|
+
if (registry === undefined) {
|
|
126
|
+
registry = new Map();
|
|
127
|
+
registries.set(system, registry);
|
|
128
|
+
system.registerIO(TYPE, {
|
|
129
|
+
send(request) {
|
|
130
|
+
const listener = registry.get(String(request.target));
|
|
131
|
+
if (listener === undefined) {
|
|
132
|
+
throw new TinyactorsError(`no debug session listens at ${request.target}`, 'not-found');
|
|
133
|
+
}
|
|
134
|
+
listener(request);
|
|
135
|
+
},
|
|
136
|
+
});
|
|
137
|
+
}
|
|
138
|
+
const scope = system.openScope(TYPE, uri);
|
|
139
|
+
registry.set(uri, onReply);
|
|
140
|
+
return {
|
|
141
|
+
scope,
|
|
142
|
+
close() {
|
|
143
|
+
registry.delete(uri);
|
|
144
|
+
if (!system.closed) system.closeScope(scope);
|
|
145
|
+
},
|
|
146
|
+
};
|
|
147
|
+
}
|
|
148
|
+
|
|
149
|
+
module.exports = { parse, completions, openConsole, HELP, TYPE };
|