@dungle-scrubs/tether-client 0.1.1

package/dist/observability.js

@@ -0,0 +1,223 @@
+import { randomUUID } from "node:crypto";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+/**
+ * Error thrown when a Tether module invariant breaks.
+ */
+export class TetherInvariantError extends Error {
+    code = "TETHER_INVARIANT_VIOLATION";
+    details;
+    moduleName;
+    operation;
+    /**
+     * Captures a violated invariant with machine-readable module and operation
+     * context.
+     */
+    constructor(input) {
+        super(input.message, input.cause === undefined ? undefined : { cause: input.cause });
+        this.details = input.details ?? {};
+        this.moduleName = input.moduleName;
+        this.name = "TetherInvariantError";
+        this.operation = input.operation;
+    }
+}
+/**
+ * JSON logger used when boundary logs are enabled through module options.
+ */
+export class ConsoleStructuredLogger {
+    /**
+     * Writes structured log entries to the matching console level.
+     */
+    log(entry) {
+        const encoded = JSON.stringify(entry);
+        if (entry.level === "error") {
+            console.error(encoded);
+            return;
+        }
+        if (entry.level === "warn") {
+            console.warn(encoded);
+            return;
+        }
+        console.log(encoded);
+    }
+}
+/**
+ * Boundary observability helper for deep modules.
+ */
+export class ModuleObservability {
+    activeOperations = 0;
+    boundaryCalls = 0;
+    boundaryFailures = 0;
+    boundaryLogsEnabled;
+    debugEnabled;
+    lastError = null;
+    lastOperation = null;
+    logger;
+    moduleName;
+    tracer;
+    /**
+     * Creates an observability boundary helper with optional logging and tracing
+     * dependencies.
+     */
+    constructor(options) {
+        this.boundaryLogsEnabled = options.boundaryLogsEnabled ?? false;
+        this.debugEnabled = options.debugEnabled ?? false;
+        this.logger = options.logger ?? new ConsoleStructuredLogger();
+        this.moduleName = options.moduleName;
+        this.tracer = trace.getTracer(options.tracerName ?? options.moduleName);
+    }
+    /**
+     * Snapshots boundary counters and the most recent failure.
+     */
+    debugInfo() {
+        return {
+            activeOperations: this.activeOperations,
+            boundaryCalls: this.boundaryCalls,
+            boundaryFailures: this.boundaryFailures,
+            boundaryLogsEnabled: this.boundaryLogsEnabled,
+            debugEnabled: this.debugEnabled,
+            lastError: this.lastError,
+            lastOperation: this.lastOperation,
+            moduleName: this.moduleName,
+        };
+    }
+    /**
+     * Runs one public boundary method inside logs and an OpenTelemetry span.
+     */
+    async traceBoundary(operation, input, action, summarize = () => ({})) {
+        const traceId = `trace_${randomUUID()}`;
+        this.activeOperations += 1;
+        this.boundaryCalls += 1;
+        this.lastOperation = operation;
+        this.logBoundary("debug", "boundary.enter", operation, traceId, input);
+        const startedAt = performance.now();
+        return this.tracer.startActiveSpan(`${this.moduleName}.${operation}`, { attributes: toSpanAttributes({ ...input, traceId }) }, async (span) => {
+            try {
+                const value = await action();
+                const durationMs = Math.round(performance.now() - startedAt);
+                const summary = summarize(value);
+                span.setAttributes(toSpanAttributes({ ...summary, durationMs }));
+                span.setStatus({ code: SpanStatusCode.OK });
+                this.logBoundary("info", "boundary.exit", operation, traceId, {
+                    ...summary,
+                    durationMs,
+                });
+                return value;
+            }
+            catch (error) {
+                const durationMs = Math.round(performance.now() - startedAt);
+                const errorInfo = toStructuredErrorInfo(error);
+                this.boundaryFailures += 1;
+                this.lastError = errorInfo;
+                span.recordException(error instanceof Error ? error : String(error));
+                span.setAttributes(toSpanAttributes({ durationMs, errorName: errorInfo.name }));
+                span.setStatus({ code: SpanStatusCode.ERROR, message: errorInfo.message });
+                this.logBoundary("error", "boundary.error", operation, traceId, {
+                    durationMs,
+                    error: errorInfo,
+                });
+                throw error;
+            }
+            finally {
+                span.end();
+                this.activeOperations -= 1;
+            }
+        });
+    }
+    /**
+     * Throws a typed invariant error when internal module assumptions break.
+     */
+    assertInvariant(condition, operation, message, details = {}) {
+        if (condition) {
+            return;
+        }
+        throw new TetherInvariantError({
+            details,
+            message,
+            moduleName: this.moduleName,
+            operation,
+        });
+    }
+    /**
+     * Emits scoped verbose data without turning on global logging.
+     */
+    debug(operation, message, data = {}) {
+        if (!this.debugEnabled) {
+            return;
+        }
+        this.logBoundary("debug", message, operation, `trace_${randomUUID()}`, data);
+    }
+    logBoundary(level, message, operation, traceId, data) {
+        if (!this.boundaryLogsEnabled && !this.debugEnabled) {
+            return;
+        }
+        this.logger.log({
+            at: new Date().toISOString(),
+            data,
+            level,
+            message,
+            moduleName: this.moduleName,
+            operation,
+            traceId,
+        });
+    }
+}
+/**
+ * Reads module observability toggles from environment variables.
+ */
+export function readModuleObservabilityOptions(moduleName, env = process.env) {
+    return {
+        boundaryLogsEnabled: parseBooleanEnv(env.OBSERVABILITY),
+        debugEnabled: parseBooleanEnv(env.DEBUG),
+        moduleName,
+    };
+}
+/**
+ * Parses truthy boolean environment values used by observability toggles.
+ */
+function parseBooleanEnv(value) {
+    return value === "1" || value === "true" || value === "yes";
+}
+/**
+ * Converts structured log fields into OpenTelemetry-compatible span attributes.
+ */
+function toSpanAttributes(fields) {
+    const attributes = {};
+    for (const [key, value] of Object.entries(fields)) {
+        const attribute = toSpanAttribute(value);
+        if (attribute !== null) {
+            attributes[key] = attribute;
+        }
+    }
+    return attributes;
+}
+/**
+ * Keeps only scalar and homogeneous scalar-array values supported by
+ * OpenTelemetry span attributes.
+ */
+function toSpanAttribute(value) {
+    if (typeof value === "boolean" || typeof value === "number" || typeof value === "string") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        if (value.every((item) => typeof item === "string")) {
+            return value;
+        }
+        if (value.every((item) => typeof item === "number")) {
+            return value;
+        }
+        if (value.every((item) => typeof item === "boolean")) {
+            return value;
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Normalizes unknown thrown values into structured error metadata.
+ */
+function toStructuredErrorInfo(error) {
+    if (error instanceof Error) {
+        return { message: error.message, name: error.name };
+    }
+    return { message: "Unknown error", name: "UnknownError" };
+}

package/dist/participant-claimable-task-runner.d.ts

@@ -0,0 +1,36 @@
+import { Effect } from "effect";
+import type { ParticipantRuntimeTaskLoopOptions, ParticipantTaskExecutor } from "./participant-runtime-client.js";
+import type { SessionEvent, TaskRecord } from "./types.js";
+/** Cancellation state passed from the claimable-task runner into one task flow. */
+export interface TaskCancellationContext {
+    /** Aborts the active executor signal for this task. */
+    readonly abortActive: () => void;
+    /** Returns whether cancellation has been observed for this task. */
+    readonly isCancelled: () => boolean;
+    /** Executor cancellation signal. */
+    readonly signal: AbortSignal;
+}
+/** Minimal participant client surface needed by the claimable-task runner. */
+export interface ParticipantClaimableTaskRunnerClient {
+    /** Intentionally closes the participant client. */
+    readonly close: () => void;
+    /** Returns whether the participant client is intentionally stopped. */
+    readonly isStopped: () => boolean;
+    /** Registers a live/replayed event handler. */
+    readonly onEvent: (handler: (event: SessionEvent) => void) => () => void;
+    /** Reconnects the participant stream using the client's configured backoff. */
+    readonly reconnectAfterClose: () => Promise<void>;
+    /** Runs one claimed task flow. */
+    readonly runTaskClaimFlow: (input: {
+        readonly cancellation: TaskCancellationContext;
+        readonly claimRefreshMs: number;
+        readonly executor: ParticipantTaskExecutor;
+        readonly task: TaskRecord;
+    }) => Promise<void>;
+    /** Resolves when the current socket closes. */
+    readonly waitForClose: () => Promise<void>;
+    /** Resolves after server replay is complete. */
+    readonly waitForReplayComplete: () => Promise<void>;
+}
+/** Builds the replay/live claimable-task loop for one participant runtime. */
+export declare function buildParticipantClaimableTaskLoop(client: ParticipantClaimableTaskRunnerClient, options: ParticipantRuntimeTaskLoopOptions): Effect.Effect<void, unknown>;

package/dist/participant-claimable-task-runner.js

@@ -0,0 +1,92 @@
+import { Effect } from "effect";
+import { taskFromClaimableEvent } from "./protocol.js";
+import { TaskCancellationRegistry } from "./task-cancellation-registry.js";
+/** Builds the replay/live claimable-task loop for one participant runtime. */
+export function buildParticipantClaimableTaskLoop(client, options) {
+    const cancellations = new TaskCancellationRegistry();
+    const processing = new Set();
+    const pendingWork = new Set();
+    const replayTasks = new Map();
+    let replayComplete = false;
+    const startTask = (task) => {
+        if (cancellations.isCancelled(task.taskId)) {
+            return;
+        }
+        const work = processTask(client, options.executor, options.claimRefreshMs, cancellations, processing, task);
+        pendingWork.add(work);
+        void work
+            .catch((error) => {
+            console.error(error);
+        })
+            .finally(() => pendingWork.delete(work));
+    };
+    const subscribe = () => client.onEvent((event) => {
+        const cancelledTaskId = cancellations.observe(event);
+        if (cancelledTaskId) {
+            replayTasks.delete(cancelledTaskId);
+            return;
+        }
+        const task = taskFromClaimableEvent(event);
+        if (!task || !isDispatchableClaimableTask(task) || !options.shouldClaimTask(task)) {
+            return;
+        }
+        if (!replayComplete) {
+            replayTasks.set(task.taskId, task);
+            return;
+        }
+        startTask(task);
+    });
+    const loop = Effect.gen(function* () {
+        while (!client.isStopped()) {
+            replayComplete = false;
+            const replayReady = Effect.tryPromise(() => client.waitForReplayComplete()).pipe(Effect.map(() => {
+                replayComplete = true;
+                for (const task of replayTasks.values()) {
+                    startTask(task);
+                }
+                replayTasks.clear();
+                return "replay_complete";
+            }));
+            const closeReady = Effect.tryPromise(() => client.waitForClose()).pipe(Effect.as("closed"));
+            const firstResult = yield* Effect.race(replayReady, closeReady);
+            if (firstResult === "replay_complete") {
+                if (options.once) {
+                    yield* Effect.promise(() => Promise.allSettled([...pendingWork]));
+                    client.close();
+                    return;
+                }
+                yield* closeReady;
+            }
+            if (!client.isStopped()) {
+                yield* Effect.tryPromise(() => client.reconnectAfterClose());
+            }
+        }
+    });
+    return Effect.acquireUseRelease(Effect.sync(subscribe), () => loop, (unsubscribe) => Effect.sync(unsubscribe));
+}
+function isDispatchableClaimableTask(task) {
+    return !task.completedAt && !task.failedAt && !task.cancelledAt;
+}
+async function processTask(client, executor, claimRefreshMs, cancellations, processing, task) {
+    if (processing.has(task.taskId) || cancellations.isCancelled(task.taskId)) {
+        return;
+    }
+    const signal = cancellations.begin(task.taskId);
+    processing.add(task.taskId);
+    try {
+        await client.runTaskClaimFlow({
+            cancellation: {
+                abortActive: () => cancellations.abortActive(task.taskId),
+                isCancelled: () => cancellations.isCancelled(task.taskId),
+                signal,
+            },
+            claimRefreshMs,
+            executor,
+            task,
+        });
+    }
+    finally {
+        cancellations.end(task.taskId);
+        processing.delete(task.taskId);
+    }
+}