@actiondock/core 2.2.2 → 2.3.0

package/dist/process/output-log.js

@@ -0,0 +1,331 @@
+import { INVALID_CURSOR, OUTPUT_GAP, PROCESS_CANCELLED, QUOTA_EXCEEDED, ProcessError, } from "../errors.js";
+import { compareCursorPos, encodeCursor, parseCursor } from "./cursor.js";
+/**
+ * 基于内存有界环形缓冲区的受管进程原始字节输出日志。
+ *
+ * 职责与不变量：
+ * - 保留原始字节流，不做字符集猜测与跨流重排序。
+ * - 维护单调推进的游标系统，支持按记录切分与不透明游标寻址。
+ * - 缓冲区超额时淘汰最旧数据并更新最早保留游标。
+ * - 长轮询等待机制保证状态检查与等待者注册处于同一同步边界，杜绝漏唤醒。
+ * - 严格遵循等待者配额，超额抛出配额超限异常。
+ */
+export class ProcessOutputLog {
+    hostEpoch;
+    processId;
+    maxBufferBytes;
+    maxWaiters;
+    records = [];
+    totalBytes = 0;
+    nextSequence;
+    earliestCursorState;
+    tailCursorState;
+    outputClosedState = false;
+    outputEndReasonState;
+    waiters = new Set();
+    constructor(hostEpoch, processId, options = {}) {
+        this.hostEpoch = hostEpoch;
+        this.processId = processId;
+        this.maxBufferBytes = options.maxBufferBytes ?? 4 * 1024 * 1024;
+        this.maxWaiters = options.maxWaiters ?? 8;
+        this.nextSequence = options.initialSequence ?? 0;
+        const initial = encodeCursor(this.hostEpoch, this.processId, this.nextSequence, 0);
+        this.earliestCursorState = initial;
+        this.tailCursorState = initial;
+    }
+    /**
+     * 当前保留日志的最早可用游标。
+     */
+    get earliestCursor() {
+        return this.earliestCursorState;
+    }
+    /**
+     * 当前日志尾部的下一写入游标。
+     */
+    get tailCursor() {
+        return this.tailCursorState;
+    }
+    /**
+     * 输出通道是否已关闭。
+     */
+    get outputClosed() {
+        return this.outputClosedState;
+    }
+    /**
+     * 输出通道关闭原因。
+     */
+    get outputEndReason() {
+        return this.outputEndReasonState;
+    }
+    /**
+     * 当前缓冲区占用的原始字节总数。
+     */
+    get currentBytes() {
+        return this.totalBytes;
+    }
+    /**
+     * 当前正在挂起等待的读取者数量。
+     */
+    get waiterCount() {
+        return this.waiters.size;
+    }
+    /**
+     * 向输出日志追加新的原始字节数据。
+     *
+     * 行为约束：
+     * - 记录新数据并更新日志尾部游标。
+     * - 若总字节数超出缓冲区上限，淘汰最旧记录并更新最早保留游标。
+     * - 同步唤醒所有挂起等待者。
+     */
+    append(stream, data) {
+        if (data.byteLength === 0) {
+            return;
+        }
+        const sequence = this.nextSequence++;
+        const record = {
+            sequence,
+            stream,
+            data: new Uint8Array(data.buffer, data.byteOffset, data.byteLength),
+            offset: 0,
+            originalLength: data.byteLength,
+        };
+        this.records.push(record);
+        this.totalBytes += record.data.byteLength;
+        this.tailCursorState = encodeCursor(this.hostEpoch, this.processId, this.nextSequence, 0);
+        while (this.totalBytes > this.maxBufferBytes && this.records.length > 0) {
+            if (this.records.length > 1) {
+                const evicted = this.records.shift();
+                this.totalBytes -= evicted.data.byteLength;
+                const first = this.records[0];
+                this.earliestCursorState = encodeCursor(this.hostEpoch, this.processId, first.sequence, first.offset);
+            }
+            else {
+                const single = this.records[0];
+                const overflow = this.totalBytes - this.maxBufferBytes;
+                single.offset += overflow;
+                single.data = single.data.subarray(overflow);
+                this.totalBytes = single.data.byteLength;
+                this.earliestCursorState = encodeCursor(this.hostEpoch, this.processId, single.sequence, single.offset);
+                break;
+            }
+        }
+        this.notifyWaiters();
+    }
+    /**
+     * 标记输出通道关闭并唤醒所有等待者。
+     */
+    closeOutput(reason = "natural") {
+        if (this.outputClosedState) {
+            return;
+        }
+        this.outputClosedState = true;
+        this.outputEndReasonState = reason;
+        this.notifyWaiters();
+    }
+    /**
+     * 从指定游标处读取输出数据。
+     *
+     * 行为约束：
+     * - 校验游标是否超出当前日志末尾，超出则抛出 INVALID_CURSOR 异常。
+     * - 检查游标是否落后于最早保留游标：
+     *   - 若落后且 onGap 为 error，抛出 OUTPUT_GAP 异常并附带当前最早游标。
+     *   - 若落后且 onGap 为 skip，从最早可用游标开始读取，标记 truncated 为 true 并提供缺口范围。
+     * - 支持记录切分并生成带有内部偏移量的不透明推进游标。
+     */
+    read(cursor, maxBytes, onGap) {
+        const limitBytes = maxBytes !== undefined && maxBytes > 0 ? maxBytes : 64 * 1024;
+        const gapMode = onGap ?? "error";
+        const requestedPos = parseCursor(cursor, this.hostEpoch, this.processId);
+        const tailPos = parseCursor(this.tailCursorState, this.hostEpoch, this.processId);
+        const earliestPos = parseCursor(this.earliestCursorState, this.hostEpoch, this.processId);
+        if (compareCursorPos(requestedPos, tailPos) > 0) {
+            throw new ProcessError(INVALID_CURSOR, "Cursor is beyond tail cursor", {
+                cursor,
+                tailCursor: this.tailCursorState,
+            });
+        }
+        let readPos = requestedPos;
+        let skippedGap = false;
+        let gapInfo;
+        if (compareCursorPos(requestedPos, earliestPos) < 0) {
+            if (gapMode === "error") {
+                throw new ProcessError(OUTPUT_GAP, "Output log cursor has fallen behind earliest retained cursor", {
+                    cursor,
+                    earliestCursor: this.earliestCursorState,
+                });
+            }
+            skippedGap = true;
+            readPos = earliestPos;
+            gapInfo = {
+                fromCursor: cursor,
+                toCursor: this.earliestCursorState,
+            };
+        }
+        if (compareCursorPos(readPos, tailPos) === 0) {
+            const eof = Boolean(this.outputClosedState);
+            return {
+                chunks: [],
+                nextCursor: skippedGap ? this.earliestCursorState : cursor,
+                earliestCursor: this.earliestCursorState,
+                tailCursor: this.tailCursorState,
+                truncated: skippedGap,
+                gap: gapInfo,
+                eof,
+            };
+        }
+        let curSeq = readPos.sequence;
+        let curOffset = readPos.offset;
+        let remainingBytes = limitBytes;
+        const chunks = [];
+        for (const record of this.records) {
+            if (record.sequence < curSeq) {
+                continue;
+            }
+            if (record.sequence > curSeq) {
+                curSeq = record.sequence;
+                curOffset = record.offset;
+            }
+            if (remainingBytes <= 0) {
+                break;
+            }
+            if (curOffset > record.originalLength) {
+                throw new ProcessError(INVALID_CURSOR, "Cursor offset exceeds record length", {
+                    cursor,
+                    sequence: curSeq,
+                    offset: curOffset,
+                    recordLength: record.originalLength,
+                });
+            }
+            if (curOffset < record.offset) {
+                curOffset = record.offset;
+            }
+            const localOffset = curOffset - record.offset;
+            const availableInRecord = record.data.byteLength - localOffset;
+            if (availableInRecord > 0) {
+                const take = Math.min(availableInRecord, remainingBytes);
+                const chunkBytes = record.data.subarray(localOffset, localOffset + take);
+                chunks.push({
+                    stream: record.stream,
+                    data: chunkBytes,
+                });
+                remainingBytes -= take;
+                curOffset += take;
+            }
+            if (curOffset >= record.originalLength) {
+                curSeq = record.sequence + 1;
+                curOffset = 0;
+            }
+            if (remainingBytes <= 0) {
+                break;
+            }
+        }
+        const nextCursor = encodeCursor(this.hostEpoch, this.processId, curSeq, curOffset);
+        const currentEndPos = { sequence: curSeq, offset: curOffset };
+        const isAtTail = compareCursorPos(currentEndPos, tailPos) === 0;
+        const eof = Boolean(this.outputClosedState && isAtTail);
+        return {
+            chunks,
+            nextCursor,
+            earliestCursor: this.earliestCursorState,
+            tailCursor: this.tailCursorState,
+            truncated: skippedGap,
+            gap: gapInfo,
+            eof,
+        };
+    }
+    /**
+     * 长轮询等待输出数据或通道关闭。
+     *
+     * 行为约束：
+     * - 状态检查与等待者登记位于同一同步边界，杜绝漏唤醒竞态。
+     * - 若已有数据、通道已关闭或超时时长小于等于 0，立即返回读取结果。
+     * - 严格校验等待者配额，超额抛出 QUOTA_EXCEEDED 异常。
+     * - 外部信号中止时立即清理等待者并不修改日志游标状态。
+     * - 等待超时且无新数据时返回空分块结果。
+     */
+    waitForData(cursor, waitMs, signal, options) {
+        const requestedPos = parseCursor(cursor, this.hostEpoch, this.processId);
+        const tailPos = parseCursor(this.tailCursorState, this.hostEpoch, this.processId);
+        const earliestPos = parseCursor(this.earliestCursorState, this.hostEpoch, this.processId);
+        if (compareCursorPos(requestedPos, tailPos) > 0) {
+            throw new ProcessError(INVALID_CURSOR, "Cursor is beyond tail cursor", {
+                cursor,
+                tailCursor: this.tailCursorState,
+            });
+        }
+        const isBehind = compareCursorPos(requestedPos, earliestPos) < 0;
+        const hasData = compareCursorPos(requestedPos, tailPos) < 0;
+        if (isBehind || hasData || this.outputClosedState || waitMs <= 0) {
+            return Promise.resolve(this.read(cursor, options?.maxBytes, options?.onGap));
+        }
+        if (signal?.aborted) {
+            return Promise.reject(new ProcessError(PROCESS_CANCELLED, "Wait aborted", { reason: signal.reason }));
+        }
+        if (this.waiters.size >= this.maxWaiters) {
+            return Promise.reject(new ProcessError(QUOTA_EXCEEDED, `Read waiters quota exceeded: ${this.maxWaiters}`, {
+                maxWaiters: this.maxWaiters,
+                currentWaiters: this.waiters.size,
+            }));
+        }
+        return new Promise((resolve, reject) => {
+            let timer = null;
+            let abortHandler = null;
+            const cleanup = () => {
+                if (timer !== null) {
+                    clearTimeout(timer);
+                    timer = null;
+                }
+                if (signal && abortHandler) {
+                    signal.removeEventListener("abort", abortHandler);
+                    abortHandler = null;
+                }
+                this.waiters.delete(wake);
+            };
+            const wake = () => {
+                cleanup();
+                try {
+                    const result = this.read(cursor, options?.maxBytes, options?.onGap);
+                    resolve(result);
+                }
+                catch (err) {
+                    reject(err);
+                }
+            };
+            if (signal) {
+                abortHandler = () => {
+                    cleanup();
+                    reject(new ProcessError(PROCESS_CANCELLED, "Wait aborted by signal", {
+                        reason: signal.reason,
+                    }));
+                };
+                signal.addEventListener("abort", abortHandler, { once: true });
+            }
+            if (waitMs > 0 && waitMs !== Infinity) {
+                timer = setTimeout(() => {
+                    cleanup();
+                    try {
+                        const result = this.read(cursor, options?.maxBytes, options?.onGap);
+                        resolve(result);
+                    }
+                    catch (err) {
+                        reject(err);
+                    }
+                }, waitMs);
+                if (typeof timer?.unref === "function") {
+                    timer.unref();
+                }
+            }
+            this.waiters.add(wake);
+        });
+    }
+    notifyWaiters() {
+        if (this.waiters.size === 0) {
+            return;
+        }
+        const pending = Array.from(this.waiters);
+        this.waiters.clear();
+        for (const wake of pending) {
+            wake();
+        }
+    }
+}

package/dist/process/process-manager.d.ts

@@ -0,0 +1,279 @@
+import { type CallOptions, type ControlGrant, type Limits, type Logger, type OperationReceipt, type ProcessAcquireInput, type ProcessControlInput, type ProcessInfo, type ProcessListInput, type ProcessListResult, type ProcessReadInput, type ProcessRunInput, type ProcessRunResult, type ProcessStartInput, type ProcessStartResult, type ProcessStopInput, type ProcessWriteInput, type ReadResult } from "@actiondock/sdk";
+import { ContextProcessAPI } from "./context-process.js";
+import type { ProcessDriver } from "./driver.js";
+import { type ProcessMetadataStore } from "./metadata-store.js";
+/**
+ * 受管进程归属所有者身份。
+ */
+export interface ProcessOwner {
+    tenantId: string;
+    principalId: string;
+    packageInstanceId: string;
+    generationId: string;
+}
+/**
+ * 宿主与作用域资源配额配置。
+ */
+export interface ProcessManagerQuotas {
+    /** 每个作用域允许并发存在的活跃进程上限，默认 8 */
+    maxActiveProcessesPerScope: number;
+    /** 每个宿主允许并发存在的活跃进程上限，默认 64 */
+    maxActiveProcessesPerHost: number;
+    /** 单个进程输出缓冲区保留字节数上限，默认 4MB */
+    maxOutputBufferBytesPerProcess: number;
+    /** 宿主所有活跃进程累计输出缓冲区字节数总上限，默认 128MB */
+    maxOutputBufferBytesPerHost: number;
+    /** 单个进程待写入输入队列保留字节数上限，默认 1MB */
+    maxPendingQueueBytesPerProcess: number;
+    /** 宿主所有进程待写入输入队列累计字节数总上限，默认 16MB */
+    maxPendingQueueBytesPerHost: number;
+    /** 单个进程并发等待独占控制权或输出日志的长轮询等待者上限，默认 8 */
+    maxWaitersPerProcess: number;
+    /** 宿主所有长轮询等待者累计上限，默认 256 */
+    maxWaitersPerHost: number;
+}
+/**
+ * 进程管理器构造选项。
+ */
+export interface ProcessManagerOptions {
+    /** 宿主纪元代次标识，不传时自动生成 */
+    hostEpoch?: string;
+    /** 底层进程驱动实例 */
+    driver: ProcessDriver;
+    /** 元数据存储后端，默认采用内存存储 */
+    metadataStore?: ProcessMetadataStore;
+    /** 资源限额与配额覆盖 */
+    quotas?: Partial<ProcessManagerQuotas>;
+    /** 默认单进程硬性资源限额 */
+    defaultLimits?: Partial<Limits>;
+    /** 进程退出后输出排空宽限期（毫秒），默认 5000 */
+    drainDeadlineMs?: number;
+    /** 终态保留输出日志最大缓存保留时长（毫秒），默认 10 分钟 (600,000 毫秒) */
+    terminalLogRetentionMs?: number;
+    /** 可选结构化日志接口，用于透出持久化失败与驱动终止失败等诊断信息 */
+    logger?: Logger;
+}
+/**
+ * 格式化生成作用域唯一隔离字符串。
+ */
+export declare function formatProcessScope(owner: ProcessOwner): string;
+/**
+ * 受管进程核心管理器。
+ *
+ * 职责范畴：
+ * - 宿主身份与配额检查（每作用域活跃进程、每宿主进程、输出缓冲预算、等待者上限、输入队列容量）。
+ * - 严格归属所有者鉴权校验（基于 tenantId, principalId, packageInstanceId, generationId）。
+ * - 控制权状态机推进（free -> held -> quarantined -> closed）。
+ * - 输入队列去重与串行调度执行。
+ * - 资源生命周期定时器管理（idleTimeout, maxLifetime, drainDeadline）。
+ */
+export declare class ProcessManager {
+    readonly hostEpoch: string;
+    readonly driver: ProcessDriver;
+    readonly metadataStore: ProcessMetadataStore;
+    readonly quotas: ProcessManagerQuotas;
+    readonly defaultLimits: Required<Limits>;
+    readonly drainDeadlineMs: number;
+    readonly terminalLogRetentionMs: number;
+    private readonly logger?;
+    private processes;
+    /** 已驱逐进程的输出日志缓存：附带时间戳支撑 TTL 过期回收与 LRU 淘汰 */
+    private evictedOutputLogs;
+    /** 已淘汰输出日志的墓碑缓存：防止因日志淘汰静默丢失输出数据，支撑缺口明确告知与不可用异常 */
+    private evictedOutputTombstones;
+    /** 同步幂等预占表：以复合键在异步落盘窗口内锁定并发重复请求 */
+    private requestReservations;
+    private initPromise;
+    private isShutdown;
+    /** 内部诊断日志：未注入 logger 时保留最近的持久化与驱动错误，避免静默吞没异常 */
+    private diagnostics;
+    constructor(options: ProcessManagerOptions);
+    /**
+     * 初始化宿主环境，原子性收敛旧宿主遗留的非终态进程。
+     * 幂等：重复调用返回同一份缓存 Promise。
+     */
+    initialize(): Promise<number>;
+    /**
+     * 惰性收敛入口：所有公共操作前调用，确保崩溃恢复无需平台显式接线。
+     */
+    private ensureInitialized;
+    /**
+     * 记录内部诊断信息：优先写入注入的 logger，缺失时保留在内存环形缓冲区。
+     */
+    private recordDiagnostic;
+    /**
+     * 获取最近的内部诊断日志快照（最近条目在前）。
+     */
+    get recentDiagnostics(): string[];
+    /**
+     * 异步落盘进程状态：捕获并记录持久化失败，杜绝静默吞没异常。
+     */
+    private persistState;
+    /**
+     * 异步落盘请求凭据：捕获并记录持久化失败，杜绝静默吞没异常。
+     */
+    private persistReceipt;
+    /**
+     * 同步预占幂等请求：跨 await 的检查与落盘窗口内锁定同复合键并发调用。
+     * 返回 undefined 表示预占成功，调用方继续异步路径并在完成时调用 commit/cancel。
+     * 返回 RequestReservation 表示已有同请求进行中，调用方可等待其结果。
+     * 若已有请求负载或操作类型不同，立即抛出 REQUEST_CONFLICT 杜绝混用结果。
+     */
+    private reserveRequest;
+    private commitReservation;
+    private rejectReservation;
+    /**
+     * 停止全部受管进程、清理全部定时器并置为关闭态，供宿主优雅退出使用。
+     */
+    shutdown(): Promise<void>;
+    private assertNotShutdown;
+    /**
+     * 为指定所有者与运行上下文创建 ProcessAPI 代理适配器。
+     */
+    forOwner(owner: ProcessOwner, runId?: string, signal?: AbortSignal): ContextProcessAPI;
+    /**
+     * 启动新的受管进程资源。
+     */
+    start(owner: ProcessOwner, input: ProcessStartInput, call?: CallOptions): Promise<ProcessStartResult>;
+    /**
+     * 查看指定受管进程资源的当前最新状态。
+     */
+    inspect(owner: ProcessOwner, id: string, call?: CallOptions): Promise<ProcessInfo>;
+    /**
+     * 分页列出指定归属所有者可见的受管进程列表。
+     */
+    list(owner: ProcessOwner, input: ProcessListInput, call?: CallOptions): Promise<ProcessListResult>;
+    /**
+     * 申请指定受管进程的独占控制令牌。
+     */
+    acquire(owner: ProcessOwner, id: string, input: ProcessAcquireInput, call?: CallOptions, runId?: string): Promise<ControlGrant>;
+    /**
+     * 延长当前有效控制令牌的存活时间。
+     */
+    renew(owner: ProcessOwner, id: string, token: string, ttlMs: number, call?: CallOptions): Promise<ControlGrant>;
+    /**
+     * 显式释放控制令牌，允许后续控制者申请。
+     */
+    release(owner: ProcessOwner, id: string, token: string, call?: CallOptions): Promise<void>;
+    /**
+     * 向受管进程输入流写入原始字节数据。
+     */
+    write(owner: ProcessOwner, id: string, input: ProcessWriteInput, call?: CallOptions): Promise<OperationReceipt>;
+    /**
+     * 向受管进程发送结构化控制指令。
+     */
+    control(owner: ProcessOwner, id: string, input: ProcessControlInput, call?: CallOptions): Promise<OperationReceipt>;
+    /**
+     * 查询指定请求标识的操作执行收据。
+     */
+    operation(owner: ProcessOwner, id: string, requestId: string, call?: CallOptions): Promise<OperationReceipt>;
+    /**
+     * 按游标读取受管进程输出流。
+     */
+    read(owner: ProcessOwner, id: string, input: ProcessReadInput, call?: CallOptions): Promise<ReadResult>;
+    /**
+     * 独立鉴权紧急终止通道，强行回收资源。
+     */
+    stop(owner: ProcessOwner, id: string, input: ProcessStopInput, call?: CallOptions): Promise<ProcessInfo>;
+    /**
+     * 将进程置入隔离状态，撤销有效控制权并取消待 dispatch 的输入队列。
+     */
+    quarantineProcess(owner: ProcessOwner, processId: string, token?: string, reason?: string): Promise<void>;
+    /**
+     * 一次性运行外部命令，收集有限输出并支持协作式取消与超时回收。
+     */
+    run(owner: ProcessOwner, input: ProcessRunInput, call?: CallOptions): Promise<ProcessRunResult>;
+    /**
+     * 授予指定受管进程控制令牌。
+     */
+    private grantControl;
+    /**
+     * 控制权到期未释放时自动转为隔离状态。
+     */
+    private handleGrantTtlExpired;
+    /**
+     * 唤醒排队等待控制权的下一个调用者。
+     */
+    private wakeNextAcquireWaiter;
+    /**
+     * 串行调度执行输入队列操作。
+     */
+    private dispatchNext;
+    /**
+     * 操作提交前校验持有者令牌与授权。
+     */
+    private checkOperationAuth;
+    /**
+     * 启动空闲超时定时器。
+     */
+    private startIdleTimer;
+    /**
+     * 刷新空闲超时定时器（仅在成功输入与续租时刷新，输出不刷新）。
+     */
+    private refreshIdleTimer;
+    /**
+     * 启动硬性存活上限定时器。
+     */
+    private startLifetimeTimer;
+    /**
+     * 处理空闲超时到期。
+     */
+    private handleIdleTimeout;
+    /**
+     * 处理存活上限到期。
+     */
+    private handleLifetimeTimeout;
+    /**
+     * 处理驱动通知的自然退出或信号退出。
+     */
+    private handleProcessExit;
+    /**
+     * 处理驱动通知的输出流彻底关闭事件。
+     */
+    private handleOutputClosed;
+    /**
+     * 处理驱动通知的底层故障。
+     */
+    private handleProcessError;
+    /**
+     * 加载或读取受管进程记录并校验所有者鉴权。
+     */
+    private getOrLoadProcess;
+    /**
+     * 记录已淘汰输出日志的墓碑信息（保留最近 2048 条，防止内存无限积压）。
+     */
+    private recordTombstone;
+    /**
+     * 清理已过期的终态输出日志条目。
+     */
+    private cleanExpiredTerminalLogs;
+    /**
+     * 统计终态保留日志当前在内存中实际占用的输出缓冲字节总数。
+     */
+    private countRetainedOutputBufferBytes;
+    /**
+     * 将终态输出日志存入保留缓存，并根据宿主配额执行 LRU 与 TTL 淘汰。
+     */
+    private retainTerminalOutputLog;
+    /**
+     * 获取终态保留日志（附带过期清理与 LRU 触达更新）。
+     */
+    private getRetainedOutputLog;
+    /**
+     * 终态驱逐与驱动释放：进程到达终态且输出已关闭后移除内存记录，
+     * 并防御性释放底层驱动句柄（失败仅记录诊断不中断）。
+     */
+    private maybeEvictProcess;
+    /**
+     * 启动受管进程时的配额容量校验。
+     */
+    private checkSpawnQuotas;
+    /**
+     * 统计当前宿主所有活跃进程累计排队等待控制权的调用者总数。
+     */
+    private countHostAcquireWaiters;
+    /**
+     * 统计当前宿主所有活跃进程累计输入队列待写入字节总数。
+     */
+    private countHostPendingInputBytes;
+}