@tinyactors/node 0.1.0 → 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.
Files changed (43) hide show
  1. package/README.md +648 -154
  2. package/docs/guide/browser.md +494 -0
  3. package/docs/guide/capacity.md +202 -0
  4. package/docs/guide/charts.md +578 -0
  5. package/docs/guide/hibernation.md +201 -0
  6. package/docs/guide/inspection.md +381 -0
  7. package/docs/guide/io-processors.md +269 -0
  8. package/docs/guide/migration.md +323 -0
  9. package/docs/guide/other-systems.md +275 -0
  10. package/docs/guide/quickjs.md +135 -0
  11. package/docs/guide/services.md +317 -0
  12. package/docs/guide/snapshots.md +186 -0
  13. package/docs/guide/telemetry.md +265 -0
  14. package/docs/guide/testing.md +272 -0
  15. package/docs/values.md +107 -0
  16. package/index.d.ts +1166 -1820
  17. package/index.mjs +6 -0
  18. package/lib/convenience.mjs +162 -0
  19. package/lib/direct.mjs +65 -0
  20. package/package.json +29 -16
  21. package/index.js +0 -34
  22. package/lib/actor.js +0 -85
  23. package/lib/debug/breakpoints.js +0 -349
  24. package/lib/debug/console.js +0 -149
  25. package/lib/debug/expressions.js +0 -133
  26. package/lib/debug/frames.js +0 -119
  27. package/lib/debug/labels.js +0 -142
  28. package/lib/debug/macrosteps.js +0 -207
  29. package/lib/debug/protocol.js +0 -186
  30. package/lib/debug/sources.js +0 -218
  31. package/lib/debug/variables.js +0 -265
  32. package/lib/debug.js +0 -1434
  33. package/lib/definition.js +0 -139
  34. package/lib/errors.js +0 -24
  35. package/lib/events.js +0 -56
  36. package/lib/image.js +0 -90
  37. package/lib/loader.js +0 -68
  38. package/lib/metrics.js +0 -333
  39. package/lib/native.js +0 -8
  40. package/lib/otlp.js +0 -332
  41. package/lib/statechart.js +0 -768
  42. package/lib/system.js +0 -2183
  43. package/lib/tracing.js +0 -164
package/lib/tracing.js DELETED
@@ -1,164 +0,0 @@
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
- };