@loutrejs/loutre 0.5.0 → 0.7.0

package/dist/devtools/capsule.js

@@ -0,0 +1,245 @@
+import { serializeDevtoolsError } from './observer.js';
+import { previewDevtoolsValue } from './values.js';
+const defaultCapsuleTtlMs = 5 * 60_000;
+const defaultMaxCapsules = 1_000;
+export class ReplayCapsuleStore {
+    #runId;
+    #ttlMs;
+    #maxCapsules;
+    #capture;
+    #redact;
+    #capsules = new Map();
+    #references = new Map();
+    constructor(runId, options = {}) {
+        this.#runId = runId;
+        this.#ttlMs = options.ttlMs ?? defaultCapsuleTtlMs;
+        this.#maxCapsules = options.maxCapsules ?? defaultMaxCapsules;
+        this.#capture = options.capture;
+        this.#redact = options.redact ?? [];
+        if (!Number.isFinite(this.#ttlMs) || this.#ttlMs <= 0) {
+            throw new TypeError('capsuleTtlMs must be a positive finite number.');
+        }
+        if (!Number.isInteger(this.#maxCapsules) || this.#maxCapsules < 1) {
+            throw new TypeError('maxCapsules must be a positive integer.');
+        }
+    }
+    createExecution(traceId, spanId, observation, registration) {
+        this.#purgeExpired();
+        const id = `capsule_${crypto.randomUUID()}`;
+        const createdAt = Date.now();
+        const captured = this.#captureValue(registration.input);
+        const preview = {
+            id,
+            kind: 'execution',
+            runId: this.#runId,
+            traceId,
+            spanId,
+            createdAt,
+            expiresAt: createdAt + this.#ttlMs,
+            execution: {
+                executionId: observation.executionId,
+                executionKind: observation.executionKind,
+                name: observation.name ?? observation.executionId,
+                ...(observation.graphNodeId === undefined
+                    ? {}
+                    : { graphNodeId: observation.graphNodeId }),
+            },
+            input: previewDevtoolsValue(registration.input, {
+                ...(this.#capture?.maxValueBytes === undefined
+                    ? {}
+                    : { maxValueBytes: this.#capture.maxValueBytes }),
+                ...(this.#capture?.maxDepth === undefined
+                    ? {}
+                    : { maxDepth: this.#capture.maxDepth }),
+                redact: this.#redact,
+            }),
+            fidelity: captured.mode,
+            replayModes: ['direct'],
+        };
+        this.#capsules.set(id, { preview, captured, replay: registration.replay });
+        while (this.#capsules.size > this.#maxCapsules) {
+            const oldest = this.#capsules.keys().next().value;
+            if (!oldest)
+                break;
+            this.#delete(oldest);
+        }
+        return preview;
+    }
+    preview(capsuleId) {
+        this.#purgeExpired();
+        return this.#capsules.get(capsuleId)?.preview;
+    }
+    async replay(request) {
+        this.#purgeExpired();
+        const capsule = this.#capsules.get(request.capsuleId);
+        if (!capsule) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                error: {
+                    name: 'ReplayCapsuleUnavailableError',
+                    message: `LUTRE_DEVTOOLS_CAPSULE_UNAVAILABLE: ${request.capsuleId}`,
+                },
+            };
+        }
+        let input;
+        try {
+            input =
+                'inputOverride' in request
+                    ? request.inputOverride
+                    : this.#restore(capsule.captured);
+        }
+        catch (error) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                error: serializeDevtoolsError(error),
+            };
+        }
+        const context = {
+            sourceTraceId: capsule.preview.traceId,
+            sourceCapsuleId: capsule.preview.id,
+            ...(request.parentTraceId === undefined
+                ? {}
+                : { parentTraceId: request.parentTraceId }),
+        };
+        try {
+            const result = await capsule.replay(input, context);
+            return {
+                requestId: request.requestId,
+                status: 'ok',
+                result: previewDevtoolsValue(result, {
+                    ...(this.#capture?.maxValueBytes === undefined
+                        ? {}
+                        : { maxValueBytes: this.#capture.maxValueBytes }),
+                    ...(this.#capture?.maxDepth === undefined
+                        ? {}
+                        : { maxDepth: this.#capture.maxDepth }),
+                    redact: this.#redact,
+                }),
+            };
+        }
+        catch (error) {
+            return {
+                requestId: request.requestId,
+                status: 'error',
+                error: serializeDevtoolsError(error),
+            };
+        }
+    }
+    discard(capsuleId) {
+        this.#delete(capsuleId);
+    }
+    clear() {
+        this.#capsules.clear();
+        this.#references.clear();
+    }
+    #captureValue(value) {
+        try {
+            if (isSnapshotCandidate(value)) {
+                return { mode: 'snapshot', value: structuredClone(value) };
+            }
+        }
+        catch {
+            // cloneできない値を失うより、同一process内だけで有効な参照として保持する。
+        }
+        if (value !== undefined) {
+            const handleId = `ref_${crypto.randomUUID()}`;
+            this.#references.set(handleId, value);
+            return { mode: 'reference', handleId };
+        }
+        return { mode: 'snapshot', value: undefined };
+    }
+    #restore(captured) {
+        switch (captured.mode) {
+            case 'snapshot':
+                return structuredClone(captured.value);
+            case 'reference':
+                if (this.#references.has(captured.handleId)) {
+                    return this.#references.get(captured.handleId);
+                }
+                throw new Error(`LUTRE_DEVTOOLS_REFERENCE_UNAVAILABLE: ${captured.handleId}`);
+            case 'unavailable':
+                throw new Error(`LUTRE_DEVTOOLS_CAPTURE_UNAVAILABLE: ${captured.reason}`);
+        }
+    }
+    #purgeExpired() {
+        const now = Date.now();
+        for (const [id, capsule] of this.#capsules) {
+            if (capsule.preview.expiresAt > now)
+                continue;
+            this.#delete(id);
+        }
+    }
+    #delete(id) {
+        const capsule = this.#capsules.get(id);
+        if (!capsule)
+            return;
+        if (capsule.captured.mode === 'reference') {
+            this.#references.delete(capsule.captured.handleId);
+        }
+        this.#capsules.delete(id);
+    }
+}
+function isSnapshotCandidate(value, seen = new WeakSet()) {
+    if (value === null)
+        return true;
+    if (typeof value === 'undefined' ||
+        typeof value === 'string' ||
+        typeof value === 'number' ||
+        typeof value === 'boolean' ||
+        typeof value === 'bigint') {
+        return true;
+    }
+    if (typeof value !== 'object')
+        return false;
+    if (seen.has(value))
+        return true;
+    seen.add(value);
+    try {
+        if (value instanceof Date ||
+            value instanceof ArrayBuffer ||
+            ArrayBuffer.isView(value)) {
+            return true;
+        }
+        if (Array.isArray(value)) {
+            return dataPropertiesAreSnapshotCandidates(value, seen, 'length');
+        }
+        if (value instanceof Map) {
+            for (const [key, item] of Map.prototype.entries.call(value)) {
+                if (!isSnapshotCandidate(key, seen) ||
+                    !isSnapshotCandidate(item, seen)) {
+                    return false;
+                }
+            }
+            return true;
+        }
+        if (value instanceof Set) {
+            for (const item of Set.prototype.values.call(value)) {
+                if (!isSnapshotCandidate(item, seen))
+                    return false;
+            }
+            return true;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            return false;
+        return dataPropertiesAreSnapshotCandidates(value, seen);
+    }
+    finally {
+        seen.delete(value);
+    }
+}
+function dataPropertiesAreSnapshotCandidates(value, seen, ignoredKey) {
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    for (const key of Reflect.ownKeys(descriptors)) {
+        if (key === ignoredKey)
+            continue;
+        const descriptor = descriptors[key];
+        if (!descriptor || !('value' in descriptor))
+            return false;
+        if (!isSnapshotCandidate(descriptor.value, seen))
+            return false;
+    }
+    return true;
+}

package/dist/devtools/index.d.ts

@@ -0,0 +1,11 @@
+export { DEVTOOLS_PROTOCOL_VERSION } from './protocol.js';
+export { DevtoolsModule, devtoolsOptionsOf } from './module.js';
+export type { DevtoolsModuleOptions } from './module.js';
+export { ReplayCapsuleStore, type CapturedValue, type ExecutionReplayCapsulePreview, type ReplayCapsuleStoreOptions, } from './capsule.js';
+export type { ProviderMethodInvocationRequest, ProviderPlaygroundDescriptor, ProviderPlaygroundMethod, ProviderPlaygroundRequest, ReplayCapsuleRequest, ReplayExecutionContext, RuntimeDevtoolsContext, RuntimeDevtoolsContextStorage, RuntimeInspector, RuntimeInvocationResult, RuntimeTraceContext, } from './inspector.js';
+export { RuntimeDevtoolsInstrumentation } from './runtime.js';
+export type { RuntimeDevtoolsInstrumentationOptions } from './runtime.js';
+export type { ExecutionEndedEvent, ExecutionStartedEvent, RuntimeEvent, RuntimeEventBase, RuntimeObserver, RuntimeSpanKind, SerializedDevtoolsError, SpanEndedEvent, SpanStartedEvent, } from './observer.js';
+export { serializeDevtoolsError } from './observer.js';
+export type { DevtoolsValue, DevtoolsValuePreview, DevtoolsValuePreviewOptions, } from './values.js';
+export { previewDevtoolsValue } from './values.js';

package/dist/devtools/index.js

@@ -0,0 +1,6 @@
+export { DEVTOOLS_PROTOCOL_VERSION } from './protocol.js';
+export { DevtoolsModule, devtoolsOptionsOf } from './module.js';
+export { ReplayCapsuleStore, } from './capsule.js';
+export { RuntimeDevtoolsInstrumentation } from './runtime.js';
+export { serializeDevtoolsError } from './observer.js';
+export { previewDevtoolsValue } from './values.js';

package/dist/devtools/inspector.d.ts

@@ -0,0 +1,57 @@
+import type { SerializedDevtoolsError } from './observer.js';
+import type { DevtoolsValuePreview } from './values.js';
+export interface ReplayExecutionContext {
+    readonly sourceTraceId: string;
+    readonly sourceCapsuleId: string;
+    readonly parentTraceId?: string;
+}
+export interface ReplayCapsuleRequest {
+    readonly requestId: string;
+    readonly capsuleId: string;
+    readonly inputOverride?: unknown;
+    readonly parentTraceId?: string;
+}
+export interface ProviderPlaygroundRequest {
+    readonly requestId: string;
+    readonly graphNodeId: string;
+}
+export interface ProviderMethodInvocationRequest {
+    readonly requestId: string;
+    readonly graphNodeId: string;
+    readonly method: string;
+    readonly args: readonly unknown[];
+}
+export interface ProviderPlaygroundMethod {
+    readonly name: string;
+    readonly arity: number;
+}
+export interface ProviderPlaygroundDescriptor {
+    readonly requestId: string;
+    readonly graphNodeId: string;
+    readonly providerName: string;
+    readonly methods: readonly ProviderPlaygroundMethod[];
+}
+export interface RuntimeInvocationResult {
+    readonly requestId: string;
+    readonly status: 'ok' | 'error';
+    readonly traceId?: string;
+    readonly result?: DevtoolsValuePreview;
+    readonly error?: SerializedDevtoolsError;
+}
+export interface RuntimeInspector {
+    replayCapsule(request: ReplayCapsuleRequest): Promise<RuntimeInvocationResult>;
+    providerPlayground(request: ProviderPlaygroundRequest): Promise<ProviderPlaygroundDescriptor>;
+    invokeProviderMethod(request: ProviderMethodInvocationRequest): Promise<RuntimeInvocationResult>;
+}
+export interface RuntimeTraceContext {
+    readonly traceId: string;
+    readonly spanId: string;
+}
+export interface RuntimeDevtoolsContext {
+    readonly trace?: RuntimeTraceContext;
+    readonly replay?: ReplayExecutionContext;
+}
+export interface RuntimeDevtoolsContextStorage {
+    run<T>(context: RuntimeDevtoolsContext, operation: () => T): T;
+    current(): RuntimeDevtoolsContext | undefined;
+}

package/dist/devtools/inspector.js

@@ -0,0 +1 @@
+export {};

package/dist/devtools/module.d.ts

@@ -0,0 +1,18 @@
+import type { ApplicationModel } from '../core/model/types.js';
+export interface DevtoolsModuleOptions {
+    readonly enabled?: boolean;
+    readonly capture?: {
+        readonly providerMethods?: boolean;
+        readonly results?: false | 'errors' | 'all';
+        readonly maxValueBytes?: number;
+        readonly maxDepth?: number;
+    };
+    readonly replay?: {
+        readonly enabled?: boolean;
+        readonly capsuleTtlMs?: number;
+        readonly maxCapsules?: number;
+    };
+    readonly redact?: readonly string[];
+}
+export declare function DevtoolsModule(options?: DevtoolsModuleOptions): import("../core/module.js").ModuleInstance<import("../core/module.js").ModuleDefinition>;
+export declare function devtoolsOptionsOf(model: ApplicationModel): Readonly<DevtoolsModuleOptions> | undefined;

package/dist/devtools/module.js

@@ -0,0 +1,26 @@
+import { defineModule } from '../core/module.js';
+import { provide } from '../core/provider.js';
+import { token } from '../core/token.js';
+const devtoolsOptionsToken = token('loutre.devtools.options');
+const devtoolsModuleTemplate = defineModule((options = {}) => ({
+    name: 'LoutreDevtoolsModule',
+    providers: [
+        provide(devtoolsOptionsToken).useValue(Object.freeze({ ...options })),
+    ],
+}));
+export function DevtoolsModule(options) {
+    return devtoolsModuleTemplate(options);
+}
+export function devtoolsOptionsOf(model) {
+    const provider = model.providers.find((candidate) => {
+        if (candidate.kind !== 'value')
+            return false;
+        const provided = candidate.provide;
+        return (typeof provided !== 'function' &&
+            provided.kind === 'token' &&
+            provided.id === devtoolsOptionsToken.id);
+    });
+    return provider?.kind === 'value'
+        ? provider.useValue
+        : undefined;
+}

package/dist/devtools/observer.d.ts

@@ -0,0 +1,77 @@
+import type { RuntimeExecutionMetadata } from '../core/instrumentation.js';
+import type { DevtoolsValuePreview } from './values.js';
+export type RuntimeSpanKind = 'execution' | 'http.request' | 'http.middleware' | 'http.handler' | 'task.handler' | 'message-port.handler' | 'websocket.handler' | 'di.resolve' | 'provider.construct' | 'provider.method' | 'response' | 'dependency' | 'custom';
+export interface SerializedDevtoolsError {
+    readonly name?: string;
+    readonly message: string;
+    readonly stack?: string;
+}
+export interface RuntimeEventBase {
+    readonly runId: string;
+    readonly seq: number;
+    readonly timestamp: number;
+    readonly traceId?: string;
+    readonly spanId?: string;
+    readonly parentSpanId?: string;
+    readonly graphNodeId?: string;
+}
+export interface ExecutionStartedEvent extends RuntimeEventBase {
+    readonly type: 'execution.started';
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly executionId: string;
+    readonly executionKind: string;
+    readonly name: string;
+    readonly input?: DevtoolsValuePreview;
+    readonly capsuleId?: string;
+    readonly replayable?: boolean;
+    readonly replayModes?: readonly ('direct' | 'transport')[];
+    readonly replayedFromTraceId?: string;
+    readonly replayedFromCapsuleId?: string;
+}
+export interface ExecutionEndedEvent extends RuntimeEventBase {
+    readonly type: 'execution.ended';
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly executionId: string;
+    readonly durationMs: number;
+    readonly status: 'ok' | 'error' | 'cancelled';
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly result?: DevtoolsValuePreview;
+    readonly error?: SerializedDevtoolsError;
+}
+export interface SpanStartedEvent extends RuntimeEventBase {
+    readonly type: 'span.started';
+    readonly spanId: string;
+    readonly traceId: string;
+    readonly kind: RuntimeSpanKind;
+    readonly name: string;
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly input?: DevtoolsValuePreview;
+    readonly capsuleId?: string;
+    readonly replayable?: boolean;
+    readonly replayModes?: readonly ('direct' | 'transport')[];
+}
+export interface SpanEndedEvent extends RuntimeEventBase {
+    readonly type: 'span.ended';
+    readonly spanId: string;
+    readonly traceId: string;
+    readonly durationMs: number;
+    readonly status: 'ok' | 'error' | 'cancelled';
+    readonly attributes?: Readonly<Record<string, unknown>>;
+    readonly result?: DevtoolsValuePreview;
+    readonly error?: SerializedDevtoolsError;
+}
+export type RuntimeEvent = ExecutionStartedEvent | ExecutionEndedEvent | SpanStartedEvent | SpanEndedEvent;
+export interface RuntimeObserver {
+    readonly runId?: string;
+    executionStarted?(event: ExecutionStartedEvent): void;
+    executionEnded?(event: ExecutionEndedEvent): void;
+    spanStarted?(event: SpanStartedEvent): void;
+    spanEnded?(event: SpanEndedEvent): void;
+}
+export interface RuntimeExecutionContext extends RuntimeExecutionMetadata {
+    readonly traceId: string;
+    readonly spanId: string;
+}
+export declare function serializeDevtoolsError(error: unknown): SerializedDevtoolsError;

package/dist/devtools/observer.js

@@ -0,0 +1,10 @@
+export function serializeDevtoolsError(error) {
+    if (error instanceof Error) {
+        return {
+            name: error.name,
+            message: error.message,
+            ...(error.stack === undefined ? {} : { stack: error.stack }),
+        };
+    }
+    return { message: String(error) };
+}

package/dist/devtools/protocol.d.ts

@@ -0,0 +1 @@
+export declare const DEVTOOLS_PROTOCOL_VERSION = 1;

package/dist/devtools/protocol.js

@@ -0,0 +1 @@
+export const DEVTOOLS_PROTOCOL_VERSION = 1;

package/dist/devtools/provider-instrumentation.d.ts

@@ -0,0 +1,14 @@
+export interface ProviderMethodInvocation {
+    readonly key: PropertyKey;
+    readonly name: string;
+    readonly original: Function;
+    readonly receiver: unknown;
+    readonly args: readonly unknown[];
+}
+export interface ProviderMethodDefinition {
+    readonly key: PropertyKey;
+    readonly name: string;
+    readonly original: Function;
+}
+export declare function discoverProviderMethods(instance: object): readonly ProviderMethodDefinition[];
+export declare function instrumentProviderMethods(instance: object, invoke: (invocation: ProviderMethodInvocation) => unknown): () => void;

package/dist/devtools/provider-instrumentation.js

@@ -0,0 +1,117 @@
+export function discoverProviderMethods(instance) {
+    const methods = [];
+    const seen = new Set();
+    const collect = (target) => {
+        for (const key of Reflect.ownKeys(target)) {
+            if (key === 'constructor' || seen.has(key))
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(target, key);
+            if (!descriptor || !('value' in descriptor))
+                continue;
+            if (typeof descriptor.value !== 'function')
+                continue;
+            seen.add(key);
+            methods.push({
+                key,
+                name: methodName(key),
+                original: descriptor.value,
+            });
+        }
+    };
+    collect(instance);
+    let prototype = Object.getPrototypeOf(instance);
+    while (prototype && prototype !== Object.prototype) {
+        collect(prototype);
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return methods;
+}
+export function instrumentProviderMethods(instance, invoke) {
+    const seen = new Set();
+    const restore = [];
+    for (const key of Reflect.ownKeys(instance)) {
+        const descriptor = Object.getOwnPropertyDescriptor(instance, key);
+        if (!descriptor || !('value' in descriptor))
+            continue;
+        if (typeof descriptor.value !== 'function')
+            continue;
+        if (!descriptor.configurable && descriptor.writable !== true)
+            continue;
+        seen.add(key);
+        const cleanup = defineWrapper(instance, key, descriptor, descriptor.value, invoke);
+        if (cleanup)
+            restore.push(cleanup);
+    }
+    if (!Object.isExtensible(instance)) {
+        return () => {
+            for (const cleanup of restore.toReversed())
+                cleanup();
+        };
+    }
+    let prototype = Object.getPrototypeOf(instance);
+    while (prototype && prototype !== Object.prototype) {
+        for (const key of Reflect.ownKeys(prototype)) {
+            if (key === 'constructor' || seen.has(key))
+                continue;
+            const descriptor = Object.getOwnPropertyDescriptor(prototype, key);
+            if (!descriptor || !('value' in descriptor))
+                continue;
+            if (typeof descriptor.value !== 'function')
+                continue;
+            seen.add(key);
+            const cleanup = defineWrapper(instance, key, {
+                configurable: true,
+                enumerable: descriptor.enumerable ?? false,
+                writable: true,
+                value: descriptor.value,
+            }, descriptor.value, invoke, true);
+            if (cleanup)
+                restore.push(cleanup);
+        }
+        prototype = Object.getPrototypeOf(prototype);
+    }
+    return () => {
+        for (const cleanup of restore.toReversed())
+            cleanup();
+    };
+}
+function defineWrapper(instance, key, descriptor, original, invoke, shadowsPrototype = false) {
+    const wrapper = function (...args) {
+        return invoke({
+            key,
+            name: methodName(key),
+            original,
+            receiver: this,
+            args,
+        });
+    };
+    try {
+        Object.defineProperty(instance, key, {
+            ...descriptor,
+            value: wrapper,
+        });
+    }
+    catch {
+        // instrumentationのために変更不能なProviderを壊してはならない。
+        return undefined;
+    }
+    return () => {
+        try {
+            const current = Object.getOwnPropertyDescriptor(instance, key);
+            if (!current || !('value' in current) || current.value !== wrapper)
+                return;
+            if (shadowsPrototype)
+                delete instance[key];
+            else
+                Object.defineProperty(instance, key, descriptor);
+        }
+        catch {
+            // Application側の変更をcleanupで上書きしてはならない。
+        }
+    };
+}
+function methodName(key) {
+    if (typeof key === 'symbol')
+        return key.description ?? key.toString();
+    return String(key);
+}

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;
+}