@actiondock/core 2.0.12 → 2.2.0

package/dist/storage/data-dir-lock.d.ts

@@ -0,0 +1,119 @@
+/**
+ * 数据目录排他锁元数据契约。
+ */
+export interface DataDirLockInfo {
+    /** 持有锁的宿主进程标识符 */
+    pid: number;
+    /** 宿主主机名 */
+    hostname: string;
+    /** 宿主会话令牌 */
+    sessionToken: string;
+    /** 内部排他锁令牌（用于防护伪造 sessionToken 的所有权隔离） */
+    lockToken?: string;
+    /** 创建时间戳（ISO 8601 格式） */
+    createdAt: string;
+    /** 关联存活的受管子进程列表 */
+    childPids?: number[];
+    /** 宿主会话标识 */
+    hostSessionId?: string;
+}
+/**
+ * 检查目标进程是否处于存活状态。
+ *
+ * @param pid 待检测的进程标识符
+ */
+export declare function isProcessAlive(pid: number): boolean;
+/**
+ * 安全清理陈旧接管守卫（reclaim guard）。
+ * 采用原子重命名检疫并严格核对 guardToken 与持有者存活状态，确保仅删除目标陈旧 guard，严禁误删活跃守卫或并发新守卫。
+ *
+ * @param reclaimPath 目标守卫路径
+ * @param expectedGuardToken 预期持有的守卫令牌（必填，拒绝未指定令牌的盲目清理）
+ */
+export declare function safeRemoveStaleReclaimGuard(reclaimPath: string, expectedGuardToken: string): void;
+/**
+ * 从隔离或回滚临时目录名称中解析操作者 PID 与隔离生成时间戳。
+ * 命名规范：*.(quarantine|rollback|release).<pid>.<timestamp>.<uuid>
+ */
+export declare function parseQuarantineTimestamp(entryName: string): {
+    operatorPid?: number;
+    timestamp?: number;
+};
+/**
+ * 清理过期的隔离目录（GC 回收机制）。
+ * 实施分流存活校验，防止误删活跃持锁者与回滚中目录，同时防止孤儿目录无限泄漏：
+ * - 共同前置条件：存活年龄必须超过 maxAgeMs（默认 10000ms），未超期前严禁清理（保持宽限期）。
+ * - 活跃隔离目录（quarantine / rollback / release）：若 operatorPid 存活或内部 metadata.json 记录的 pid 与 childPids 存活，跳过不予清理。
+ * - 孤儿脱离目录（orphan）：内部旧 metadata.pid 不再作为续命依据；提取其内部 orphanToken，仅当当前规范主路径（主锁目录与 reclaim 目录）依然持有该凭证时保守跳过；规范路径不存在或已变更凭据时直接安全清理。
+ */
+export declare function cleanStaleQuarantines(parentDir: string, basePrefix: string, maxAgeMs?: number, deadline?: number): void;
+/**
+ * 安全回滚当前进程创建的主锁。
+ * 优先核对 lockToken，回退核对 sessionToken，防止误删接管者或并发新锁。
+ */
+export declare function safeRollbackLock(lockPath: string, expectedSessionToken: string, expectedLockToken?: string): void;
+/**
+ * 安全释放主锁。
+ * 仅当锁目录中持有当前 lockToken / sessionToken 时才删除，杜绝删除他人新锁。
+ */
+export declare function safeReleaseLock(lockPath: string, expectedSessionToken: string, expectedLockToken?: string): void;
+/**
+ * 数据目录排他文件锁管理器。
+ * 负责在数据目录下维护 .actiondock.data.lock 排他文件锁，记录宿主进程与子进程运行状态，
+ * 防止多个无协调宿主并发冲突，并在非正常退出时提供故障恢复检测。
+ */
+export declare class DataDirLock {
+    private readonly lockDirPath;
+    private readonly info;
+    private released;
+    constructor(lockDirPath: string, info: DataDirLockInfo);
+    /**
+     * 获取当前排他锁元数据信息。
+     */
+    get lockInfo(): DataDirLockInfo;
+    /**
+     * 检查当前锁是否已被释放。
+     */
+    get isReleased(): boolean;
+    /**
+     * 登记受管子进程标识符。
+     */
+    registerChildPid(pid: number): void;
+    /**
+     * 注销受管子进程标识符。
+     */
+    unregisterChildPid(pid: number): void;
+    /**
+     * 将当前锁元数据刷新持久化至磁盘文件。
+     * 先写入临时文件再通过 renameSync 原子替换，消除 truncate 空文件窗口。
+     */
+    private flush;
+    /**
+     * 释放排他锁并移除锁目录或文件。
+     */
+    release(): void;
+    /**
+     * 尝试获取指定数据目录的排他锁。
+     *
+     * 仲裁规则：
+     * - 引入所有竞争者均遵守的原子 reclaim guard 机制（lockDirPath.reclaim），每个 guard 具备全局唯一 guardToken。
+     * - 基于原子目录创建 mkdirSync(lockDirPath, { mode: 0o700 }) 确立所有权，并在其下存放 metadata.json。
+     * - 兼容已有常规文件锁（如老版本或测试 mock 场景）。
+     * - 若检测到 reclaim guard 存在且处于宽限期内或持有者存活，必须等待，禁止抢先创建主锁。
+     * - 若锁目录已存在，通过宽限期机制防止将并发写入中的元数据误判为锁死亡。
+     * - 若主进程仍处于存活状态，抛出 DATA_DIR_IN_USE 错误拒绝并发启动。
+     * - 若主进程已退出但仍有子进程存活，抛出 DATA_DIR_RECOVERY_REQUIRED 错误。
+     * - 当识别到主锁为陈旧锁时，竞争者必须先原子竞争获取 reclaim guard。
+     * - 仅成功获取 reclaim guard 的唯一胜利者获准执行：复核主锁陈旧性 -> 验证并清理陈旧主锁 -> 原子创建新主锁并写入自身元数据 -> 清理 reclaim guard。
+     * - 竞争失败者等待并 continue 重试；若 reclaim guard 持有者意外崩溃，其他竞争者在超过宽限期且 PID 已死后通过 safeRemoveStaleReclaimGuard 核对 guardToken 并清理。
+     * - 严禁在获取新主锁遇到 EEXIST 时盲目 rmSync；后检发现他人活跃 guard 时，仅通过 safeRollbackLock 核对自身 sessionToken 回滚自身锁。
+     *
+     * @param dataDir 目标数据存储目录物理绝对路径
+     * @param options 锁配置参数
+     */
+    static acquire(dataDir: string, options?: {
+        sessionToken?: string;
+        hostSessionId?: string;
+        acquireTimeoutMs?: number;
+    }): DataDirLock;
+}