@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/lib/tracing.js
ADDED
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
// Tracing (core ADR 0067, napi ADR 0016). The addon hands a registered hook
|
|
4
|
+
// the spans that ended in each pump turn as OTLP protobuf bytes
|
|
5
|
+
// (System.setTraceSink); lib/otlp.js decodes them for those who want
|
|
6
|
+
// objects. This module holds what JavaScript still needs: the kind mask,
|
|
7
|
+
// W3C traceparent parsing and formatting, and span IDs derived from step
|
|
8
|
+
// keys exactly as core derives them. It depends on no telemetry package.
|
|
9
|
+
|
|
10
|
+
const native = require('./native');
|
|
11
|
+
const { TinyactorsError } = require('./errors');
|
|
12
|
+
|
|
13
|
+
/** Record kinds, in core's order; a sink's mask is built from these names. */
|
|
14
|
+
const TRACE_KINDS = Object.freeze([...native.traceKinds]);
|
|
15
|
+
|
|
16
|
+
/*
|
|
17
|
+
* The definition records (core ADR 0080) are for hosts that follow core's
|
|
18
|
+
* record stream. napi's OTLP output already reports definitions from the
|
|
19
|
+
* definition sink (the tinyactors.definition.* logs), so no preset asks
|
|
20
|
+
* core to build them, and asking for them explicitly adds no output.
|
|
21
|
+
*/
|
|
22
|
+
const DEFINITION_KINDS = ['definitionRegistered', 'definitionRetired', 'definitionFreed'];
|
|
23
|
+
const ENCODED_KINDS = Object.freeze(TRACE_KINDS.filter((kind) => !DEFINITION_KINDS.includes(kind)));
|
|
24
|
+
|
|
25
|
+
const LIFECYCLE = ['spawned', 'loaded', 'unloaded', 'finished', 'destroyed'];
|
|
26
|
+
// The failure kinds are the ones the log path writes as failures: an action
|
|
27
|
+
// that failed, a run stopped for lack of memory, and a long or runaway
|
|
28
|
+
// macrostep (core ADR 0075). An operator's abandon and withdraw (core ADRs
|
|
29
|
+
// 0082, 0084) are rare, and without them a summary macrostep span ends with
|
|
30
|
+
// no reason given.
|
|
31
|
+
const FAILURES = ['actionFailed', 'stopped', 'longMacrostep', 'runaway'];
|
|
32
|
+
const INTERVENTIONS = ['abandoned', 'withdrawn'];
|
|
33
|
+
const SUMMARY = [...LIFECYCLE, 'macrostepBegin', 'macrostepEnd', ...FAILURES, ...INTERVENTIONS];
|
|
34
|
+
|
|
35
|
+
/**
|
|
36
|
+
* Detail presets over the kind mask (napi ADR 0017 section 3):
|
|
37
|
+
* - summary: a span per macrostep, lifecycle spans, failures and an
|
|
38
|
+
* operator's interventions;
|
|
39
|
+
* - decisions: adds microsteps, guard conditions and raised events;
|
|
40
|
+
* - full: every kind.
|
|
41
|
+
*/
|
|
42
|
+
const TRACE_DETAIL = Object.freeze({
|
|
43
|
+
summary: Object.freeze(SUMMARY),
|
|
44
|
+
decisions: Object.freeze([...SUMMARY, 'microstep', 'condition', 'raised']),
|
|
45
|
+
full: ENCODED_KINDS,
|
|
46
|
+
});
|
|
47
|
+
|
|
48
|
+
/** The mask for `kinds` (names from TRACE_KINDS); every encoded kind when undefined. */
|
|
49
|
+
function kindMask(kinds, what = 'setTraceSink()') {
|
|
50
|
+
if (kinds === undefined) {
|
|
51
|
+
return kindMask(ENCODED_KINDS, what);
|
|
52
|
+
}
|
|
53
|
+
if (!Array.isArray(kinds)) {
|
|
54
|
+
throw new TinyactorsError(`${what}: options.kinds must be an array of record kinds`, 'invalid');
|
|
55
|
+
}
|
|
56
|
+
let mask = 0;
|
|
57
|
+
for (const kind of kinds) {
|
|
58
|
+
const bit = TRACE_KINDS.indexOf(kind);
|
|
59
|
+
if (bit < 0) {
|
|
60
|
+
throw new TinyactorsError(`${what}: unknown record kind "${kind}"`, 'invalid');
|
|
61
|
+
}
|
|
62
|
+
mask |= 2 ** bit;
|
|
63
|
+
}
|
|
64
|
+
return mask;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
// ------------------------------------------------------------------------
|
|
68
|
+
// W3C trace context: traceparent = version "-" trace-id "-" parent-id "-" flags
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Parses a `traceparent` header: { traceID, parentSpanID, flags, sampled },
|
|
72
|
+
* or undefined when it is not a valid one (the W3C rule: a receiver that
|
|
73
|
+
* cannot parse it starts a new trace). Core parses it (ta_traceparent_parse),
|
|
74
|
+
* as it does a traceparent given to post(), send() or spawn(), so the two
|
|
75
|
+
* agree: spaces and tabs around it are ignored; hex is lowercase; version
|
|
76
|
+
* ff, an all-zero trace or parent ID, and version 00 with anything after
|
|
77
|
+
* the flags are refused; a later version is read by its first four fields,
|
|
78
|
+
* and what follows a dash after its flags is ignored.
|
|
79
|
+
*/
|
|
80
|
+
function parseTraceparent(header) {
|
|
81
|
+
if (typeof header !== 'string') {
|
|
82
|
+
return undefined;
|
|
83
|
+
}
|
|
84
|
+
let parsed;
|
|
85
|
+
try {
|
|
86
|
+
parsed = native.core.traceparent_parse(header);
|
|
87
|
+
} catch (error) {
|
|
88
|
+
if (error instanceof TinyactorsError && error.code === 'invalid') {
|
|
89
|
+
return undefined;
|
|
90
|
+
}
|
|
91
|
+
throw error;
|
|
92
|
+
}
|
|
93
|
+
const { context, cause } = parsed;
|
|
94
|
+
return {
|
|
95
|
+
traceID: hex16(context.trace_id_high) + hex16(context.trace_id_low),
|
|
96
|
+
parentSpanID: hex16(cause.macrostep),
|
|
97
|
+
flags: context.flags,
|
|
98
|
+
sampled: (context.flags & 1) === 1,
|
|
99
|
+
};
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** A `traceparent` header for a span: { traceID, spanID, sampled | flags }. */
|
|
103
|
+
function formatTraceparent({ traceID, spanID, sampled = true, flags }) {
|
|
104
|
+
const bits = flags ?? (sampled ? 1 : 0);
|
|
105
|
+
return `00-${traceID}-${spanID}-${bits.toString(16).padStart(2, '0')}`;
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
const MASK64 = (1n << 64n) - 1n;
|
|
109
|
+
|
|
110
|
+
function mix(value) {
|
|
111
|
+
let v = value;
|
|
112
|
+
v ^= v >> 33n;
|
|
113
|
+
v = (v * 0xff51afd7ed558ccdn) & MASK64;
|
|
114
|
+
v ^= v >> 33n;
|
|
115
|
+
v = (v * 0xc4ceb9fe1a85ec53n) & MASK64;
|
|
116
|
+
v ^= v >> 33n;
|
|
117
|
+
return v;
|
|
118
|
+
}
|
|
119
|
+
|
|
120
|
+
const hex16 = (value) => value.toString(16).padStart(16, '0');
|
|
121
|
+
|
|
122
|
+
/**
|
|
123
|
+
* The 16-hex-digit span ID of step (session, macrostep, microstep). A host
|
|
124
|
+
* cause (session 0) is the host's own span ID, `macrostep`.
|
|
125
|
+
*/
|
|
126
|
+
function stepSpanID(session, macrostep, microstep = 0) {
|
|
127
|
+
const s = BigInt(session);
|
|
128
|
+
const m = BigInt(macrostep);
|
|
129
|
+
if (s === 0n) {
|
|
130
|
+
return hex16(m);
|
|
131
|
+
}
|
|
132
|
+
let span = mix(s);
|
|
133
|
+
span = mix(span ^ m);
|
|
134
|
+
span = mix(span ^ (BigInt(microstep) | (1n << 32n)));
|
|
135
|
+
return hex16(span === 0n ? 1n : span);
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
/**
|
|
139
|
+
* The masks and sample ratio `options` asks for: { kinds, watchedKinds,
|
|
140
|
+
* sample } with `sample` in parts per 10^9. `kinds` overrides `detail`.
|
|
141
|
+
*/
|
|
142
|
+
function traceConfig({ detail = 'summary', kinds, sample = 1 }, what) {
|
|
143
|
+
if (kinds === undefined && !Object.hasOwn(TRACE_DETAIL, detail)) {
|
|
144
|
+
throw new TinyactorsError(`${what}: options.detail must be "summary", "decisions" or "full"`, 'invalid');
|
|
145
|
+
}
|
|
146
|
+
if (typeof sample !== 'number' || !(sample >= 0 && sample <= 1)) {
|
|
147
|
+
throw new TinyactorsError(`${what}: options.sample must be a number from 0 to 1`, 'invalid');
|
|
148
|
+
}
|
|
149
|
+
return {
|
|
150
|
+
kinds: kindMask(kinds ?? TRACE_DETAIL[detail], what),
|
|
151
|
+
watchedKinds: kindMask(undefined, what),
|
|
152
|
+
sample: Math.round(sample * 1e9),
|
|
153
|
+
};
|
|
154
|
+
}
|
|
155
|
+
|
|
156
|
+
module.exports = {
|
|
157
|
+
TRACE_KINDS,
|
|
158
|
+
TRACE_DETAIL,
|
|
159
|
+
traceConfig,
|
|
160
|
+
kindMask,
|
|
161
|
+
parseTraceparent,
|
|
162
|
+
formatTraceparent,
|
|
163
|
+
stepSpanID,
|
|
164
|
+
};
|
package/package.json
ADDED
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@tinyactors/node",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Tinyactors for Node.js and Bun: SCXML statecharts as actors, on a native runtime",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"actor",
|
|
7
|
+
"actors",
|
|
8
|
+
"statechart",
|
|
9
|
+
"scxml",
|
|
10
|
+
"state-machine",
|
|
11
|
+
"napi",
|
|
12
|
+
"bun"
|
|
13
|
+
],
|
|
14
|
+
"homepage": "https://github.com/dhamidi/tinyactors/tree/main/tinyactors-napi#readme",
|
|
15
|
+
"repository": {
|
|
16
|
+
"type": "git",
|
|
17
|
+
"url": "git+https://github.com/dhamidi/tinyactors.git",
|
|
18
|
+
"directory": "tinyactors-napi"
|
|
19
|
+
},
|
|
20
|
+
"bugs": {
|
|
21
|
+
"url": "https://github.com/dhamidi/tinyactors/issues"
|
|
22
|
+
},
|
|
23
|
+
"license": "MIT",
|
|
24
|
+
"main": "index.js",
|
|
25
|
+
"types": "index.d.ts",
|
|
26
|
+
"files": [
|
|
27
|
+
"index.js",
|
|
28
|
+
"index.d.ts",
|
|
29
|
+
"lib",
|
|
30
|
+
"README.md"
|
|
31
|
+
],
|
|
32
|
+
"engines": {
|
|
33
|
+
"node": ">=22.14"
|
|
34
|
+
},
|
|
35
|
+
"optionalDependencies": {
|
|
36
|
+
"@tinyactors/node-darwin-arm64": "0.1.0",
|
|
37
|
+
"@tinyactors/node-darwin-x64": "0.1.0",
|
|
38
|
+
"@tinyactors/node-linux-x64": "0.1.0",
|
|
39
|
+
"@tinyactors/node-linux-arm64": "0.1.0"
|
|
40
|
+
}
|
|
41
|
+
}
|