pure-effect 0.14.0 → 0.16.0

package/examples/opentelemetry-example.js

@@ -0,0 +1,173 @@
+// @ts-check
+
+import { trace, SpanStatusCode } from '@opentelemetry/api';
+import { configureEffect } from 'pure-effect';
+
+/** @import { Tracer } from "@opentelemetry/api" */
+/** @import { EffectConfiguration, ParallelDecision, RunWrapper, StepRunner } from "pure-effect" */
+
+/**
+ * Reference wiring for OpenTelemetry spans
+ *
+ * `onRun` opens one span per `runEffect` call and `onStep` opens a child span per Command,
+ * which is the whole integration: the hooks already sit exactly where spans want to start
+ * and end.
+ *
+ * Importing this file does nothing on its own. Call `startTelemetrySdk()` to stand up an
+ * exporter, and `enableTelemetry()` to install the hooks, or `telemetryHooks()` to get them
+ * as a configuration you can merge with others.
+ *
+ * No Command input or output is put on a span, deliberately. Spans carry names, timings, and
+ * status; values belong in a trace, where `recorder`'s `redact` strips them before they leave the
+ * process and what remains can be replayed. Copying values onto spans would duplicate them into
+ * the one place they cannot be redacted after the fact, and an initial input routinely holds a
+ * password, a token, or a card number.
+ *
+ * A span has to wrap `op`: `startActiveSpan` is what makes each Command span a child of the run's
+ * span. Anything these hooks throw reaches the flow. A throw after `op` succeeded rejects the run
+ * without running the Command again, one before `op` is called counts as the Command failing, and
+ * one from `onRun` rejects the run. An integration that only watches, such as metrics or logging,
+ * should catch its own errors so it cannot change a run's outcome.
+ */
+
+/**
+ * @typedef {Object} TelemetryOptions
+ * @property {string} [tracerName] - Defaults to `'pure-effect'`.
+ * @property {Tracer} [tracer] - Supply a tracer directly instead of resolving one by name. Useful in tests.
+ */
+
+/**
+ * A span status message, without putting a Command's data on the span.
+ *
+ * Only a string error or an Error's message is used. A structured error object can hold the very
+ * values this file keeps off spans, and `String(someObject)` would say nothing useful anyway.
+ *
+ * @param {any} error
+ * @returns {string | undefined}
+ */
+const statusMessage = (error) =>
+    error instanceof Error ? error.message : typeof error === 'string' ? error : undefined;
+
+/**
+ * Builds the tracing hooks without installing them.
+ *
+ * Returning a configuration leaves the caller in charge of where tracing sits relative to recording:
+ * passed to one `configureEffect` call together, or installed as separate layers, the two merge the
+ * same way, and the caller holds the function that removes each.
+ *
+ * @param {TelemetryOptions} [options]
+ * @returns {EffectConfiguration}
+ */
+export function telemetryHooks(options = {}) {
+    const { tracerName = 'pure-effect', tracer = trace.getTracer(tracerName) } = options;
+
+    /**
+     * The root span is named after the flow, so traces are distinguishable in a UI. Every span
+     * ends in a `finally`, so a thrown Command cannot leak one.
+     * @type {RunWrapper}
+     */
+    const onRun = (effect, pipeline, flowName) =>
+        tracer.startActiveSpan(flowName || 'Effect Pipeline', async (rootSpan) => {
+            rootSpan.setAttribute('effect.flow', flowName || '');
+            try {
+                const result = await pipeline();
+                if (result.type === 'Failure') {
+                    rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: statusMessage(result.error) });
+                } else {
+                    rootSpan.setStatus({ code: SpanStatusCode.OK });
+                }
+                return result;
+            } catch (/** @type any */ err) {
+                rootSpan.recordException(err);
+                rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
+                throw err;
+            } finally {
+                rootSpan.end();
+            }
+        });
+
+    /**
+     * `op` has to be awaited and its result returned. Returning a value without calling `op` is how
+     * replay suppresses I/O, so a hook that forgot to call it would silently stop every Command.
+     * A Parallel's `op` returns its decision rather than throwing, even when a branch's own code threw,
+     * so a cancelled one is marked from the decision.
+     * @type {StepRunner}
+     */
+    const onStep = (name, type, op) =>
+        tracer.startActiveSpan(name, async (span) => {
+            span.setAttribute('effect.type', type);
+            try {
+                const result = await op();
+                const decision = type === 'Parallel' ? /** @type {ParallelDecision} */ (result) : undefined;
+                if (decision?.cancelled) {
+                    const by = decision.branch === null ? 'an enclosing Parallel' : `branch ${decision.branch}`;
+                    span.setStatus({ code: SpanStatusCode.ERROR, message: `Cancelled by ${by}` });
+                } else span.setStatus({ code: SpanStatusCode.OK });
+                return result;
+            } catch (/** @type any */ err) {
+                span.recordException(err);
+                span.setStatus({ code: SpanStatusCode.ERROR, message: err?.message });
+                throw err;
+            } finally {
+                span.end();
+            }
+        });
+
+    return { onRun, onStep };
+}
+
+/**
+ * Installs tracing as its own layer on top of whatever is configured, and returns the function that
+ * removes it again. Call it once per process: layers stack, so a second call opens a second span per
+ * run and per Command. A setup path that can run again (a reloading dev server, a per-suite
+ * bootstrap) should hold the remover and call it before installing a fresh layer.
+ *
+ * @param {TelemetryOptions} [options]
+ */
+export function enableTelemetry(options) {
+    return configureEffect(telemetryHooks(options));
+}
+
+/**
+ * Starts a Node SDK exporting over OTLP, and returns it so a caller can shut it down.
+ *
+ * Kept out of module scope on purpose: importing a reference file should not open exporters, spawn
+ * background work, or register process handlers. The SDK is imported dynamically so the hooks above
+ * stay usable wherever `@opentelemetry/api` runs, without pulling the Node SDK in behind them.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.serviceName]
+ * @param {string} [options.url] - OTLP HTTP endpoint.
+ * @param {boolean} [options.handleSigterm] - Flush and exit on SIGTERM. Off by default, since
+ *          installing a process handler is the application's decision, not a library's.
+ */
+export async function startTelemetrySdk(options = {}) {
+    const { serviceName = 'pure-effect', url = 'http://localhost:4318/v1/traces', handleSigterm = false } = options;
+    const [{ NodeSDK }, { OTLPTraceExporter }, { SimpleSpanProcessor }] = await Promise.all([
+        import('@opentelemetry/sdk-node'),
+        import('@opentelemetry/exporter-trace-otlp-proto'),
+        import('@opentelemetry/sdk-trace-base')
+    ]);
+
+    const traceExporter = new OTLPTraceExporter({ url });
+    // `spanProcessors` replaced the deprecated singular `spanProcessor`, and passing an exporter
+    // alongside a processor that already wraps it was redundant.
+    const sdk = new NodeSDK({
+        serviceName,
+        spanProcessors: [new SimpleSpanProcessor(traceExporter)],
+        instrumentations: []
+    });
+
+    sdk.start();
+
+    if (handleSigterm) {
+        process.on('SIGTERM', () => {
+            sdk.shutdown()
+                .then(() => console.log('Tracing terminated'))
+                .catch((error) => console.log('Error terminating tracing', error))
+                .finally(() => process.exit(0));
+        });
+    }
+
+    return sdk;
+}

package/examples/recording-example.js

@@ -0,0 +1,170 @@
+// @ts-check
+
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { configureEffect, recorder, Failure } from 'pure-effect';
+
+/** @import { Effect, EffectConfiguration, RunWrapper, StepRunner, CommandInterceptor, TraceEntry, TraceLog, SuccessState, FailureState } from "pure-effect" */
+
+/**
+ * Records every run of an application without touching any call site, one trace per run. `recordEffect` covers
+ * tests and scripts, where one call holds the whole run.
+ */
+
+/**
+ * @typedef {Object} RecordingStore
+ * @property {ReturnType<typeof recorder>} rec
+ * @property {TraceLog} head - The trace's own fields, packaged as the run starts rather than after it
+ * @property {boolean} contextCaptured
+ */
+
+/**
+ * @typedef {Object} RecordingOptions
+ * @property {(trace: TraceLog) => Promise<void> | void} [sink] - Receives each kept trace, to write to S3 or a
+ *           database. Hand slow writes to a queue rather than awaiting them inside a request.
+ * @property {(value: any, name: string, kind: string) => any} [redact] - Scrubs every value before it enters the
+ *           trace: results, serialized errors, and the stored `initialInput` and `context`, told apart by `kind`.
+ *           It receives a copy, so changing it in place never reaches the run.
+ * @property {number} [maxEntries] - Caps trace length, 500 by default; the overflow is reported as `dropped`.
+ * @property {boolean} [stack] - Records stack traces for thrown errors.
+ * @property {(result: SuccessState<any> | FailureState<any>) => boolean} [keep] - Decides which runs reach the sink:
+ *           failures only by default. Return `true` to keep everything, or sample. A run whose own code threw is
+ *           offered as a Failure carrying the thrown error.
+ * @property {(error: unknown, flowName?: string) => void} [onSinkError] - Receives an error thrown by `keep` or
+ *           `sink`. Defaults to `console.error`.
+ * @property {(message: string, flowName?: string) => void} [onWarning] - Receives a warning, once per flow, about a
+ *           kept trace that will not replay as recorded: it has no input, `maxEntries` cut it short, or some of its
+ *           steps are named 'anonymous'. Defaults to `console.warn`.
+ */
+
+/**
+ * Builds the three hooks that record each run, without installing them, so the caller decides where recording sits
+ * among its other hooks.
+ *
+ * @param {RecordingOptions} [options]
+ * @returns {EffectConfiguration}
+ */
+export function recordingHooks(options = {}) {
+    const {
+        sink = async () => {},
+        redact,
+        maxEntries = 500,
+        stack,
+        keep = (result) => result.type === 'Failure',
+        onSinkError = (error, flowName) => console.error(`Recording failed for '${flowName || 'flow'}':`, error),
+        onWarning = (message) => console.warn(message)
+    } = options;
+    // One recorder per run, found through async-local scope: a single shared recorder would mix concurrent runs.
+    /** @type {AsyncLocalStorage<RecordingStore>} */
+    const scope = new AsyncLocalStorage();
+    /** Warnings already given, as `kind:flowName`. */
+    const warned = new Set();
+
+    /** @type {RunWrapper} */
+    const onRun = async (effect, pipeline, flowName) => {
+        const rec = recorder({ redact, maxEntries, stack });
+        // Packaged before the run, so a Command that changes its input cannot rewrite what the trace says it received.
+        const head = rec.toTrace({ flowName, initialInput: effect.initialInput });
+        return scope.run({ rec, head, contextCaptured: false }, async () => {
+            /** @type {{ result: SuccessState<any> | FailureState<any> } | { error: unknown }} */
+            let outcome;
+            try {
+                outcome = { result: await pipeline() };
+            } catch (error) {
+                outcome = { error };
+            }
+            // A run whose own code threw is kept as a Failure: it is the one most worth replaying.
+            const result = 'result' in outcome ? outcome.result : Failure(outcome.error);
+            // Recording never decides the outcome: a keep or sink that throws is reported, not returned.
+            try {
+                if (keep(result)) {
+                    const { dropped = 0, trace } = rec.toTrace();
+                    warnAboutReplay(flowName, effect, dropped, trace);
+                    await sink({ ...head, dropped, trace });
+                }
+            } catch (error) {
+                reportSinkError(error, flowName);
+            }
+            if ('error' in outcome) throw outcome.error;
+            return outcome.result;
+        });
+    };
+
+    /**
+     * Warns, once per flow, about a kept trace that will not replay as recorded.
+     * @param {string} flowName
+     * @param {Effect<any, any, any>} effect
+     * @param {number} dropped
+     * @param {TraceEntry[]} trace
+     */
+    const warnAboutReplay = (flowName, effect, dropped, trace) => {
+        const warnOnce = (/** @type {string} */ kind, /** @type {string} */ message) => {
+            if (warned.has(`${kind}:${flowName}`)) return;
+            warned.add(`${kind}:${flowName}`);
+            onWarning(`Recording '${flowName || 'flow'}': ${message}`, flowName);
+        };
+        if (effect.initialInput === undefined) {
+            warnOnce(
+                'input',
+                'the flow carries no input, so its traces hold none and timeTravel rebuilds it from undefined. ' +
+                    'Build the outermost flow with effectPipe, even as a one-step pipeline.'
+            );
+        }
+        if (dropped > 0) {
+            warnOnce(
+                'capped',
+                `a kept trace dropped ${dropped} entries under maxEntries (${maxEntries}), so it replays only up to ` +
+                    'the first step it lacks. Raise maxEntries for this flow to replay whole runs.'
+            );
+        }
+        const anonymous = trace.filter((entry) => entry.command === 'anonymous').length;
+        if (anonymous > 0) {
+            warnOnce(
+                'anonymous',
+                `${anonymous} of its steps are named 'anonymous', usually inline arrow Commands, so a replay cannot ` +
+                    'tell them apart and would not notice two of them trading places. Name them with a const, as in ' +
+                    'const cmdLoadOrder = () => ..., or with meta.name.'
+            );
+        }
+    };
+
+    /** A reporter that throws does not change the run either. */
+    const reportSinkError = (/** @type {unknown} */ error, /** @type {string} */ flowName) => {
+        try {
+            onSinkError(error, flowName);
+        } catch {}
+    };
+
+    /**
+     * Outside a recorded run there is no store, so the Command runs untouched. `path` must be passed on: a replay
+     * matches steps on it.
+     * @type {StepRunner}
+     */
+    const onStep = async (name, type, op, path) => {
+        const store = scope.getStore();
+        return store ? await store.rec.onStep(name, type, op, path) : await op();
+    };
+
+    /**
+     * `onRun` never sees the context, so it is copied from the run's first Command, before that Command can change
+     * it. A run that stops before any Command records none.
+     * @type {CommandInterceptor}
+     */
+    const onBeforeCommand = async (command, context) => {
+        const store = scope.getStore();
+        if (!store || store.contextCaptured) return;
+        store.contextCaptured = true;
+        store.head.context = store.rec.toTrace({ context }).context;
+    };
+
+    return { onRun, onStep, onBeforeCommand };
+}
+
+/**
+ * Installs recording as its own layer and returns the function that removes it. Call it once per process: layers
+ * stack, so a second call records every run twice.
+ *
+ * @param {RecordingOptions} [options]
+ */
+export function enableRecording(options) {
+    return configureEffect(recordingHooks(options));
+}