@loutrejs/loutre 0.6.0 → 0.8.0

package/dist/devtools/runtime.d.ts

@@ -0,0 +1,20 @@
+import type { RuntimeExecutionMetadata, RuntimeInstrumentation, RuntimeInstrumentationScope, RuntimeInvocationRegistration, RuntimeProviderMetadata, RuntimeOperationMetadata } from '../core/instrumentation.js';
+import type { ProviderMethodInvocationRequest, ProviderPlaygroundDescriptor, ProviderPlaygroundRequest, ReplayCapsuleRequest, RuntimeDevtoolsContextStorage, RuntimeInspector, RuntimeInvocationResult } from './inspector.js';
+import type { DevtoolsModuleOptions } from './module.js';
+import { type RuntimeObserver } from './observer.js';
+export interface RuntimeDevtoolsInstrumentationOptions {
+    readonly options: Readonly<DevtoolsModuleOptions>;
+    readonly observer: RuntimeObserver;
+    readonly context: RuntimeDevtoolsContextStorage;
+}
+export declare class RuntimeDevtoolsInstrumentation implements RuntimeInstrumentation, RuntimeInspector {
+    #private;
+    constructor(options: RuntimeDevtoolsInstrumentationOptions);
+    beginExecution(metadata: RuntimeExecutionMetadata, invocation?: RuntimeInvocationRegistration): RuntimeInstrumentationScope;
+    beginOperation(metadata: RuntimeOperationMetadata, invocation?: RuntimeInvocationRegistration): RuntimeInstrumentationScope | undefined;
+    providerCreated(metadata: RuntimeProviderMetadata, value: unknown): void;
+    providerPlayground(request: ProviderPlaygroundRequest): Promise<ProviderPlaygroundDescriptor>;
+    invokeProviderMethod(request: ProviderMethodInvocationRequest): Promise<RuntimeInvocationResult>;
+    replayCapsule(request: ReplayCapsuleRequest): Promise<RuntimeInvocationResult>;
+    close(): void;
+}

package/dist/devtools/runtime.js

@@ -0,0 +1,519 @@
+import { ReplayCapsuleStore } from './capsule.js';
+import { serializeDevtoolsError, } from './observer.js';
+import { discoverProviderMethods, instrumentProviderMethods, } from './provider-instrumentation.js';
+import { previewDevtoolsValue } from './values.js';
+export class RuntimeDevtoolsInstrumentation {
+    #options;
+    #observer;
+    #context;
+    #captureProviderMethods;
+    #captureResults;
+    #runId;
+    #capsules;
+    #providers = new Map();
+    #providerMethods = new WeakMap();
+    #instrumentedProviderIds = new WeakMap();
+    #externalProviderValues = new WeakSet();
+    #ambiguousProviders = new WeakSet();
+    #providerRestorers = new WeakMap();
+    #applicationProviderRestorers = new Map();
+    #seq = 0;
+    constructor(options) {
+        this.#options = options.options;
+        this.#observer = options.observer;
+        this.#context = options.context;
+        this.#captureProviderMethods =
+            options.options.capture?.providerMethods !== false;
+        const captureResults = options.options.capture?.results;
+        this.#captureResults =
+            captureResults !== false && captureResults !== 'errors';
+        this.#runId = options.observer.runId ?? `run_${crypto.randomUUID()}`;
+        const replay = options.options.replay;
+        this.#capsules =
+            replay?.enabled === false
+                ? undefined
+                : new ReplayCapsuleStore(this.#runId, {
+                    ...(replay?.capsuleTtlMs === undefined
+                        ? {}
+                        : { ttlMs: replay.capsuleTtlMs }),
+                    ...(replay?.maxCapsules === undefined
+                        ? {}
+                        : { maxCapsules: replay.maxCapsules }),
+                    ...(options.options.capture === undefined
+                        ? {}
+                        : { capture: options.options.capture }),
+                    ...(options.options.redact === undefined
+                        ? {}
+                        : { redact: options.options.redact }),
+                });
+    }
+    beginExecution(metadata, invocation) {
+        const traceId = `trace_${crypto.randomUUID()}`;
+        const spanId = `span_${crypto.randomUUID()}`;
+        const startedAt = performance.now();
+        const startedTimestamp = performance.timeOrigin + startedAt;
+        const name = metadata.name ?? metadata.executionId;
+        const replaySource = this.#context.current()?.replay;
+        const capsule = invocation && this.#capsules
+            ? this.#capsules.createExecution(traceId, spanId, metadata, {
+                input: invocation.input,
+                replay: (input, context) => this.#runReplayContext(context, () => invocation.invoke(input)),
+            })
+            : undefined;
+        let completed = false;
+        let failed = false;
+        let failureReason;
+        let cancelled = false;
+        const attributes = {};
+        this.#notify('executionStarted', {
+            type: 'execution.started',
+            ...this.#identity(startedTimestamp, traceId, spanId, metadata.graphNodeId),
+            executionId: metadata.executionId,
+            executionKind: metadata.executionKind,
+            name,
+            ...(capsule === undefined
+                ? {}
+                : {
+                    input: capsule.input,
+                    capsuleId: capsule.id,
+                    replayable: true,
+                    replayModes: capsule.replayModes,
+                }),
+            ...(replaySource === undefined
+                ? {}
+                : {
+                    replayedFromTraceId: replaySource.sourceTraceId,
+                    replayedFromCapsuleId: replaySource.sourceCapsuleId,
+                }),
+        });
+        this.#notify('spanStarted', {
+            type: 'span.started',
+            ...this.#identity(startedTimestamp, traceId, spanId, metadata.graphNodeId),
+            kind: 'execution',
+            name,
+            attributes: { executionKind: metadata.executionKind },
+        });
+        return {
+            run: (operation) => this.#context.run({
+                trace: { traceId, spanId },
+                ...(replaySource === undefined ? {} : { replay: replaySource }),
+            }, operation),
+            abort() {
+                cancelled = true;
+            },
+            fail(reason) {
+                failed = true;
+                failureReason = reason;
+            },
+            annotate(nextAttributes) {
+                Object.assign(attributes, nextAttributes);
+            },
+            complete: (...resultValues) => {
+                if (completed)
+                    return;
+                completed = true;
+                const status = failed ? 'error' : cancelled ? 'cancelled' : 'ok';
+                const error = failed ? serializeDevtoolsError(failureReason) : undefined;
+                const result = resultValues.length === 0
+                    ? undefined
+                    : this.#previewResult(resultValues[0]);
+                const endedAt = performance.now();
+                const timestamp = performance.timeOrigin + endedAt;
+                this.#notify('spanEnded', {
+                    type: 'span.ended',
+                    ...this.#identity(timestamp, traceId, spanId, metadata.graphNodeId),
+                    durationMs: endedAt - startedAt,
+                    status,
+                    ...(Object.keys(attributes).length === 0 ? {} : { attributes }),
+                    ...(result === undefined ? {} : { result }),
+                    ...(error === undefined ? {} : { error }),
+                });
+                this.#notify('executionEnded', {
+                    type: 'execution.ended',
+                    ...this.#identity(timestamp, traceId, spanId, metadata.graphNodeId),
+                    executionId: metadata.executionId,
+                    durationMs: endedAt - startedAt,
+                    status,
+                    ...(Object.keys(attributes).length === 0 ? {} : { attributes }),
+                    ...(result === undefined ? {} : { result }),
+                    ...(error === undefined ? {} : { error }),
+                });
+            },
+        };
+    }
+    beginOperation(metadata, invocation) {
+        const current = this.#context.current();
+        if (!current?.trace)
+            return undefined;
+        const spanId = `span_${crypto.randomUUID()}`;
+        const startedAt = performance.now();
+        const capsule = invocation && this.#capsules
+            ? this.#capsules.createExecution(current.trace.traceId, spanId, {
+                executionId: `span:${metadata.name}`,
+                executionKind: metadata.kind,
+                name: metadata.name,
+                ...(metadata.graphNodeId === undefined
+                    ? {}
+                    : { graphNodeId: metadata.graphNodeId }),
+            }, {
+                input: invocation.input,
+                replay: (input, context) => this.#runReplayContext(context, () => invocation.invoke(input)),
+            })
+            : undefined;
+        let completed = false;
+        let failed = false;
+        let failureReason;
+        const attributes = {};
+        this.#notify('spanStarted', {
+            type: 'span.started',
+            runId: this.#runId,
+            seq: ++this.#seq,
+            timestamp: performance.timeOrigin + startedAt,
+            traceId: current.trace.traceId,
+            spanId,
+            parentSpanId: current.trace.spanId,
+            ...(metadata.graphNodeId === undefined
+                ? {}
+                : { graphNodeId: metadata.graphNodeId }),
+            kind: metadata.kind,
+            name: metadata.name,
+            ...(capsule === undefined
+                ? {}
+                : {
+                    input: capsule.input,
+                    capsuleId: capsule.id,
+                    replayable: true,
+                    replayModes: capsule.replayModes,
+                }),
+        });
+        return {
+            run: (operation) => this.#context.run({
+                trace: { traceId: current.trace.traceId, spanId },
+                ...(current.replay === undefined ? {} : { replay: current.replay }),
+            }, operation),
+            fail(reason) {
+                failed = true;
+                failureReason = reason;
+            },
+            annotate(nextAttributes) {
+                Object.assign(attributes, nextAttributes);
+            },
+            complete: (...resultValues) => {
+                if (completed)
+                    return;
+                completed = true;
+                const result = resultValues.length === 0
+                    ? undefined
+                    : this.#previewResult(resultValues[0]);
+                const error = failed ? serializeDevtoolsError(failureReason) : undefined;
+                const endedAt = performance.now();
+                this.#notify('spanEnded', {
+                    type: 'span.ended',
+                    runId: this.#runId,
+                    seq: ++this.#seq,
+                    timestamp: performance.timeOrigin + endedAt,
+                    traceId: current.trace.traceId,
+                    spanId,
+                    parentSpanId: current.trace.spanId,
+                    ...(metadata.graphNodeId === undefined
+                        ? {}
+                        : { graphNodeId: metadata.graphNodeId }),
+                    durationMs: endedAt - startedAt,
+                    status: failed ? 'error' : 'ok',
+                    ...(Object.keys(attributes).length === 0 ? {} : { attributes }),
+                    ...(result === undefined ? {} : { result }),
+                    ...(error === undefined ? {} : { error }),
+                });
+            },
+        };
+    }
+    providerCreated(metadata, value) {
+        if (typeof value !== 'object' || value === null)
+            return;
+        let methods = this.#providerMethods.get(value);
+        if (!methods) {
+            methods = discoverProviderMethods(value);
+            this.#providerMethods.set(value, methods);
+        }
+        if (metadata.scope === 'application') {
+            this.#providers.set(metadata.graphNodeId, {
+                metadata,
+                instance: value,
+                methods: new Map(methods.flatMap((method) => typeof method.key === 'string' ? [[method.name, method]] : [])),
+            });
+        }
+        if (!this.#captureProviderMethods)
+            return;
+        if (metadata.providerKind === 'value' ||
+            metadata.providerKind === 'factory') {
+            this.#providerRestorers.get(value)?.();
+            this.#providerRestorers.delete(value);
+            this.#applicationProviderRestorers.delete(value);
+            this.#externalProviderValues.add(value);
+            return;
+        }
+        if (this.#externalProviderValues.has(value) ||
+            this.#ambiguousProviders.has(value)) {
+            return;
+        }
+        const instrumentedProviderId = this.#instrumentedProviderIds.get(value);
+        if (instrumentedProviderId !== undefined) {
+            if (instrumentedProviderId !== metadata.graphNodeId) {
+                this.#providerRestorers.get(value)?.();
+                this.#providerRestorers.delete(value);
+                this.#applicationProviderRestorers.delete(value);
+                this.#ambiguousProviders.add(value);
+            }
+            return;
+        }
+        const restore = instrumentProviderMethods(value, (invocation) => this.#invokeProviderMethod(metadata, value, invocation));
+        this.#instrumentedProviderIds.set(value, metadata.graphNodeId);
+        this.#providerRestorers.set(value, restore);
+        if (metadata.scope === 'application') {
+            this.#applicationProviderRestorers.set(value, restore);
+        }
+    }
+    async providerPlayground(request) {
+        const provider = this.#providers.get(request.graphNodeId);
+        if (!provider) {
+            throw new Error(`LUTRE_DEVTOOLS_PROVIDER_UNAVAILABLE: ${request.graphNodeId}`);
+        }
+        return {
+            requestId: request.requestId,
+            graphNodeId: request.graphNodeId,
+            providerName: provider.metadata.name,
+            methods: [...provider.methods.values()]
+                .map((method) => ({ name: method.name, arity: method.original.length }))
+                .toSorted((left, right) => left.name.localeCompare(right.name)),
+        };
+    }
+    async invokeProviderMethod(request) {
+        const provider = this.#providers.get(request.graphNodeId);
+        if (!provider) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                error: {
+                    name: 'ProviderUnavailableError',
+                    message: `LUTRE_DEVTOOLS_PROVIDER_UNAVAILABLE: ${request.graphNodeId}`,
+                },
+            };
+        }
+        const method = provider.methods.get(request.method);
+        if (!method) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                error: {
+                    name: 'ProviderMethodUnavailableError',
+                    message: `LUTRE_DEVTOOLS_PROVIDER_METHOD_UNAVAILABLE: ${request.method}`,
+                },
+            };
+        }
+        let traceId;
+        try {
+            const result = await this.#runProviderMethodExecution(provider.metadata, provider.instance, method.original, method.name, request.args, (nextTraceId) => {
+                traceId = nextTraceId;
+            });
+            return {
+                requestId: request.requestId,
+                status: 'ok',
+                ...(traceId === undefined ? {} : { traceId }),
+                result: this.#previewValue(result),
+            };
+        }
+        catch (error) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                ...(traceId === undefined ? {} : { traceId }),
+                error: serializeDevtoolsError(error),
+            };
+        }
+    }
+    async replayCapsule(request) {
+        if (!this.#capsules) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                error: {
+                    name: 'ReplayDisabledError',
+                    message: 'LUTRE_DEVTOOLS_REPLAY_DISABLED: Replay is not enabled.',
+                },
+            };
+        }
+        return this.#capsules.replay(request);
+    }
+    close() {
+        this.#capsules?.clear();
+        this.#providers.clear();
+        for (const restore of this.#applicationProviderRestorers.values())
+            restore();
+        this.#applicationProviderRestorers.clear();
+    }
+    #invokeProviderMethod(metadata, instance, invocation) {
+        const current = this.#context.current();
+        if (!current?.trace) {
+            return Reflect.apply(invocation.original, invocation.receiver, invocation.args);
+        }
+        const spanId = `span_${crypto.randomUUID()}`;
+        const startedAt = performance.now();
+        const name = `${metadata.name}.${invocation.name}`;
+        const capsule = metadata.scope === 'transient'
+            ? undefined
+            : this.#capsules?.createExecution(current.trace.traceId, spanId, {
+                executionId: `${metadata.providerId}.${invocation.name}`,
+                executionKind: 'provider.method',
+                graphNodeId: metadata.graphNodeId,
+                name,
+            }, {
+                input: invocation.args,
+                replay: (input, context) => this.#runReplayContext(context, () => this.#replayProviderMethod(metadata, instance, invocation.original, invocation.name, input)),
+            });
+        let result;
+        try {
+            result = Reflect.apply(invocation.original, invocation.receiver, invocation.args);
+        }
+        catch (error) {
+            this.#recordProviderMethodSpan(metadata, invocation, current.trace, spanId, startedAt, capsule, { status: 'error', error });
+            throw error;
+        }
+        // Promiseのsettlementを観測するとrejection handlerが追加され、Applicationの
+        // unhandled-rejection semanticsを変え得る。自動Traceは同期的に完結する呼び出しへ
+        // 限定し、明示実行であるPlaygroundとReplayだけがPromiseをawaitする。
+        if (result instanceof Promise) {
+            if (capsule)
+                this.#capsules?.discard(capsule.id);
+            return result;
+        }
+        this.#recordProviderMethodSpan(metadata, invocation, current.trace, spanId, startedAt, capsule, { status: 'ok', result });
+        return result;
+    }
+    #recordProviderMethodSpan(metadata, invocation, parent, spanId, startedAt, capsule, outcome) {
+        const name = `${metadata.name}.${invocation.name}`;
+        this.#notify('spanStarted', {
+            type: 'span.started',
+            runId: this.#runId,
+            seq: ++this.#seq,
+            timestamp: performance.timeOrigin + startedAt,
+            traceId: parent.traceId,
+            spanId,
+            parentSpanId: parent.spanId,
+            graphNodeId: metadata.graphNodeId,
+            kind: 'provider.method',
+            name,
+            ...(capsule === undefined
+                ? {}
+                : {
+                    input: capsule.input,
+                    capsuleId: capsule.id,
+                    replayable: true,
+                    replayModes: capsule.replayModes,
+                }),
+        });
+        const endedAt = performance.now();
+        const result = outcome.status === 'ok' ? this.#previewResult(outcome.result) : undefined;
+        this.#notify('spanEnded', {
+            type: 'span.ended',
+            runId: this.#runId,
+            seq: ++this.#seq,
+            timestamp: performance.timeOrigin + endedAt,
+            traceId: parent.traceId,
+            spanId,
+            parentSpanId: parent.spanId,
+            graphNodeId: metadata.graphNodeId,
+            durationMs: endedAt - startedAt,
+            status: outcome.status,
+            ...(result === undefined ? {} : { result }),
+            ...(outcome.status === 'error'
+                ? { error: serializeDevtoolsError(outcome.error) }
+                : {}),
+        });
+    }
+    async #replayProviderMethod(metadata, instance, original, method, input) {
+        return this.#runProviderMethodExecution(metadata, instance, original, method, input);
+    }
+    async #runProviderMethodExecution(metadata, instance, original, method, input, onTraceId) {
+        if (!Array.isArray(input)) {
+            throw new TypeError('LUTRE_DEVTOOLS_PROVIDER_ARGS_REQUIRED');
+        }
+        const scope = this.beginExecution({
+            executionId: `${metadata.providerId}.${method}`,
+            executionKind: 'provider.method',
+            graphNodeId: metadata.graphNodeId,
+            name: `${metadata.name}.${method}`,
+        }, {
+            input,
+            invoke: (nextInput) => this.#runProviderMethodExecution(metadata, instance, original, method, nextInput),
+        });
+        let result;
+        let hasResult = false;
+        try {
+            const invoke = () => {
+                const traceId = this.#context.current()?.trace?.traceId;
+                if (traceId)
+                    onTraceId?.(traceId);
+                return Reflect.apply(original, instance, input);
+            };
+            result = await (scope.run ? scope.run(invoke) : invoke());
+            hasResult = true;
+            return result;
+        }
+        catch (error) {
+            scope.fail?.(error);
+            throw error;
+        }
+        finally {
+            if (hasResult)
+                scope.complete(result);
+            else
+                scope.complete();
+        }
+    }
+    #runReplayContext(context, operation) {
+        const current = this.#context.current();
+        const next = {
+            ...(current?.trace === undefined ? {} : { trace: current.trace }),
+            replay: context,
+        };
+        return this.#context.run(next, operation);
+    }
+    #previewResult(value) {
+        if (!this.#captureResults)
+            return undefined;
+        return this.#previewValue(value);
+    }
+    #previewValue(value) {
+        const capture = this.#options.capture;
+        return previewDevtoolsValue(value, {
+            ...(capture?.maxValueBytes === undefined
+                ? {}
+                : { maxValueBytes: capture.maxValueBytes }),
+            ...(capture?.maxDepth === undefined
+                ? {}
+                : { maxDepth: capture.maxDepth }),
+            ...(this.#options.redact === undefined
+                ? {}
+                : { redact: this.#options.redact }),
+        });
+    }
+    #identity(timestamp, traceId, spanId, graphNodeId) {
+        return {
+            runId: this.#runId,
+            seq: ++this.#seq,
+            timestamp,
+            traceId,
+            spanId,
+            ...(graphNodeId === undefined ? {} : { graphNodeId }),
+        };
+    }
+    #notify(key, event) {
+        try {
+            const callback = this.#observer[key];
+            callback?.(event);
+        }
+        catch {
+            // observerの失敗をApplicationの挙動へ伝播させてはならない。
+        }
+    }
+}

package/dist/devtools/values.d.ts

@@ -0,0 +1,35 @@
+export type DevtoolsValue = null | boolean | number | string | {
+    readonly $type: 'undefined';
+} | {
+    readonly $type: 'bigint';
+    readonly value: string;
+} | {
+    readonly $type: 'date';
+    readonly value: string;
+} | {
+    readonly $type: 'bytes';
+    readonly base64: string;
+} | {
+    readonly $type: 'map';
+    readonly entries: readonly [DevtoolsValue, DevtoolsValue][];
+} | {
+    readonly $type: 'set';
+    readonly values: readonly DevtoolsValue[];
+} | {
+    readonly $type: 'redacted';
+} | readonly DevtoolsValue[] | {
+    readonly [key: string]: DevtoolsValue;
+};
+export interface DevtoolsValuePreview {
+    readonly value?: DevtoolsValue;
+    readonly preview: string;
+    readonly truncated?: boolean;
+    readonly redacted?: boolean;
+    readonly type?: string;
+}
+export interface DevtoolsValuePreviewOptions {
+    readonly maxValueBytes?: number;
+    readonly maxDepth?: number;
+    readonly redact?: readonly string[];
+}
+export declare function previewDevtoolsValue(value: unknown, options?: DevtoolsValuePreviewOptions): DevtoolsValuePreview;