target-supabase-sdk 0.1.8 → 0.1.9

package/src/node/node-manager.ts

@@ -0,0 +1,673 @@
+import { MAX_POLL_TARGET_LIST_SIZE } from "../core.api";
+import { getPollCommandList } from "../command/command.api";
+import { CommandType } from "../command/command.interface";
+import { logManager, type LoggerWithContext } from "../shared/log/log-manager";
+import { getErrorMessage, toError } from "../shared/utils/error.utils";
+import { TaskManager, type TaskRunResult } from "../task/task-manager";
+import { patchChangeTaskStatus, patchClaimTask } from "../task/task.api";
+import { TaskStatusAction } from "../task/task.interface";
+import { patchChangeNodeStatus, patchNodeHeartBeat, patchStopNode, postRegisterNode } from "./node.api";
+import { NodeLoopContext, NodeStatus } from "./node.interface";
+import { formatHeartbeat, getRandomInterval } from "./node.utils";
+
+class NodeManager {
+    private static readonly HEARTBEAT_FAILURE_THRESHOLD = 3;
+
+    private _localNodeId: string | null = null;
+    private _isNodeIdLocked: boolean = false;
+    private _availableTaskList: string[] = [];
+
+    private isRunning: boolean;
+    private loopCount: number;
+    private consecutiveHeartbeatFailures = 0;
+    /** 進程生命週期 traceId — bootstrap / register / shutdown 共用 */
+    private readonly startupTraceId: string;
+    /** 進行中的 shutdown；並發/重複調用復用同一 Promise。 */
+    private shutdownPromise: Promise<void> | null = null;
+    /** start() 冪等：重複調用復用同一 Promise。 */
+    private startPromise: Promise<void> | null = null;
+
+    get availableTaskList(): readonly string[] {
+        return [...this._availableTaskList];
+    }
+
+    get localNodeId(): string | null {
+        return this._localNodeId;
+    }
+    set localNodeId(value: string) {
+        if (this._isNodeIdLocked) {
+            throw new Error("Node ID cannot be modified after initial assignment");
+        }
+        if (typeof value !== "string" || value.trim() === "") {
+            throw new Error("Invalid node ID");
+        }
+
+        this._localNodeId = value;
+        this._isNodeIdLocked = true;
+    }
+
+    constructor() {
+        this.isRunning = true;
+        this.loopCount = 0;
+        this.startupTraceId = logManager.generateTraceId();
+    }
+
+    private getLogNodeId(): string {
+        return this.localNodeId ?? "bootstrap";
+    }
+
+    private isShuttingDown(): boolean {
+        return this.shutdownPromise != null;
+    }
+
+    /** Fire-and-forget：供信號/致命路徑調用；shutdown Promise 內部吞掉 rejection，避免 unhandledRejection 遞迴。 */
+    private requestShutdown(trigger: string): void {
+        void this.shutdown({ trigger });
+    }
+
+    /** 啟動日誌 + SIGTERM/SIGINT/uncaughtException/unhandledRejection → shutdown */
+    private registerProcessLifecycle(logger: LoggerWithContext): void {
+        process.on("SIGTERM", () => {
+            logger.warn("收到 SIGTERM 信號，準備關閉節點", { topic: "process" });
+            this.requestShutdown("SIGTERM");
+        });
+        process.on("SIGINT", () => {
+            logger.warn("收到 SIGINT 信號，準備關閉節點", { topic: "process" });
+            this.requestShutdown("SIGINT");
+        });
+        process.on("uncaughtException", (error) => {
+            if (this.shutdownPromise != null) {
+                logger.critical("shutdown 進行中發生未捕獲異常", {
+                    topic: "process",
+                    context: {
+                        name: error.name,
+                        message: error.message,
+                        stack: error.stack,
+                    },
+                });
+                process.exit(1);
+                return;
+            }
+            logger.error("未捕獲的異常，準備關閉節點", {
+                topic: "process",
+                context: {
+                    name: error.name,
+                    message: error.message,
+                    stack: error.stack,
+                },
+            });
+            this.requestShutdown("uncaughtException");
+        });
+        process.on("unhandledRejection", (reason) => {
+            if (this.shutdownPromise != null) {
+                logger.error("shutdown 進行中發生未處理的 Promise 拒絕", {
+                    topic: "process",
+                    context: {
+                        reason: getErrorMessage(reason),
+                        stack: reason instanceof Error ? reason.stack : undefined,
+                    },
+                });
+                return;
+            }
+            logger.error("未處理的 Promise 拒絕，準備關閉節點", {
+                topic: "process",
+                context: {
+                    reason: getErrorMessage(reason),
+                    stack: reason instanceof Error ? reason.stack : undefined,
+                },
+            });
+            this.requestShutdown("unhandledRejection");
+        });
+    }
+
+    async start(): Promise<void> {
+        if (this.startPromise != null) {
+            return this.startPromise;
+        }
+        this.startPromise = this.runStart();
+        return this.startPromise;
+    }
+
+    private async runStart(): Promise<void> {
+        const { logger } = logManager.withContext({
+            module: "nodeManager",
+            traceId: this.startupTraceId,
+            nodeId: this.getLogNodeId(),
+        });
+
+        logger.info("節點進程啟動中", {
+            topic: "node",
+            context: {
+                pid: process.pid,
+                env: process.env.NODE_ENV ?? "development",
+            },
+        });
+        this.registerProcessLifecycle(logger);
+
+        logger.info("開始註冊任務", { topic: "node" });
+        try {
+            const { availableTaskList } = await TaskManager.registerTasks({ logger });
+            this._availableTaskList = availableTaskList;
+        } catch (error) {
+            logger.error("任務註冊失敗", {
+                topic: "node",
+                context: { error: getErrorMessage(error) },
+            });
+            this.requestShutdown("bootstrap:register-tasks");
+            return;
+        }
+
+        logger.info("開始向 Supabase 註冊節點", { topic: "node" });
+        try {
+            const { data, error } = await postRegisterNode({ traceId: this.startupTraceId });
+            if (data == null || error) {
+                throw error ?? new Error("postRegisterNode 失敗");
+            }
+            this.localNodeId = data.id;
+            logger.resetContext({ nodeId: data.id });
+            logger.success("節點註冊成功", {
+                topic: "node",
+                context: {
+                    nodeId: data.id,
+                    details: data.details,
+                },
+            });
+        } catch (error) {
+            logger.error("節點註冊失敗", {
+                topic: "node",
+                context: { error: getErrorMessage(error) },
+            });
+            this.requestShutdown("bootstrap:register-node");
+            return;
+        }
+
+        const nodeId = this.localNodeId!;
+        logger.info("節點準備進入主循環", { topic: "node" });
+        const { error: enterBusyError } = await patchChangeNodeStatus({
+            nodeId,
+            status: NodeStatus.BUSY,
+            fromStatus: NodeStatus.READY,
+            traceId: this.startupTraceId,
+        });
+        if (enterBusyError) {
+            logger.error("節點進入主循環失敗，無法更新節點狀態為 BUSY", {
+                topic: "node",
+                context: { error: enterBusyError.message },
+            });
+            this.requestShutdown("bootstrap:enter-busy");
+            return;
+        }
+        logger.info("節點狀態已設為 BUSY，進入主循環", { topic: "node", context: { nodeId } });
+
+        while (this.isRunning) {
+            this.loopCount++;
+            const loopTraceId = logManager.generateTraceId();
+            const loopCtx: NodeLoopContext = { loopTraceId, nodeId };
+            const { logger: iterLogger } = logManager.withContext({
+                module: "nodeManager-loop-iteration",
+                traceId: loopTraceId,
+                nodeId,
+            });
+
+            iterLogger.info(`主循環第 ${this.loopCount} 輪開始`, {
+                topic: "node",
+                context: { nodeId, loopCount: this.loopCount, },
+            });
+            try {
+                // 每輪三步：1. 控制指令  2. 心跳  3. 認領並執行任務
+                await this.batchCommand(loopCtx);
+                if (this.isShuttingDown()) {
+                    iterLogger.info("節點關閉中，跳過本輪剩餘步驟", { topic: "node" });
+                    break;
+                }
+                const heartbeatOk = await this.heartbeat(loopCtx);
+                if (this.isShuttingDown()) {
+                    iterLogger.info("節點關閉中，跳過本輪剩餘步驟", { topic: "node" });
+                    break;
+                }
+                if (!heartbeatOk) {
+                    iterLogger.warn("心跳失敗，本輪跳過任務認領", { topic: "node" });
+                } else {
+                    await this.runAsWorker(loopCtx);
+                }
+            } catch (error) {
+                iterLogger.critical(`主循環第 ${this.loopCount} 輪遇到未知錯誤`, {
+                    topic: "node",
+                    context: { error: getErrorMessage(error) },
+                });
+            }
+            if (this.isShuttingDown()) {
+                iterLogger.debug("節點關閉中，跳過等待間隔", { topic: "node" });
+                break;
+            }
+            const interval = getRandomInterval();
+            iterLogger.debug(`主循環第 ${this.loopCount} 輪完成，等待下一輪`, {
+                topic: "node",
+                context: { intervalMs: interval },
+            });
+            await new Promise((resolve) => setTimeout(resolve, interval));
+        }
+    }
+
+    async runAsWorker(ctx: NodeLoopContext) {
+        const { loopTraceId, nodeId } = ctx;
+        const { logger } = logManager.withContext({
+            module: "runAsWorker",
+            traceId: loopTraceId,
+            nodeId,
+        });
+
+        const availableTaskList = this.availableTaskList;
+        if (availableTaskList.length === 0) {
+            logger.warn("未配置可認領任務類型，跳過本輪", { topic: "task" });
+            return;
+        }
+
+        logger.info("向 Supabase 認領任務", {
+            topic: "task",
+            context: { availableTaskList },
+        });
+        const { data: task, error: claimError } = await patchClaimTask({
+            nodeId,
+            availableTaskList: [...availableTaskList],
+            traceId: loopTraceId,
+        });
+        if (claimError) {
+            logger.error("認領任務 API 失敗", {
+                topic: "task",
+                context: {
+                    availableTaskList,
+                    error: claimError.message,
+                },
+            });
+            return;
+        }
+        if (task == null) {
+            logger.info("本輪無匹配的 TODO 任務", {
+                topic: "task",
+                context: { availableTaskList },
+            });
+            return;
+        }
+
+        logger.info("認領任務成功，準備執行", {
+            topic: "task",
+            context: {
+                taskId: task.id,
+                taskName: task.name,
+                taskTypeKey: task.value,
+                taskStatus: task.details.status,
+            },
+        });
+
+        const { logger: prepareLogger } = logManager.withContext({
+            module: "prepareTask",
+            traceId: loopTraceId,
+            nodeId,
+        });
+        const prepareResult = await TaskManager.prepareTask({ logger: prepareLogger, task });
+        const { isSuccess: isPrepareSuccess, taskFn, code, message, reason, step } = prepareResult;
+        if (!isPrepareSuccess || taskFn == null) {
+            prepareLogger.critical("任務準備失敗，無法繼續執行，中止任務並 RESET 為 OPEN", {
+                topic: "task",
+                context: {
+                    taskId: task.id,
+                    taskTypeKey: task.value,
+                    code,
+                    message,
+                    reason,
+                    step,
+                },
+            });
+            await this.abortTaskRun({
+                logger: prepareLogger,
+                taskId: task.id,
+                nodeId,
+                traceId: loopTraceId,
+            });
+            return
+        }
+
+        const { logger: executeLogger } = logManager.withContext({
+            module: "executeTask",
+            traceId: loopTraceId,
+            nodeId,
+        });
+        const onExecuteAbort = async (error?: Error) => {
+            logger.critical("任務執行遇到未知錯誤，中止任務並 RESET 為 OPEN", {
+                topic: "task",
+                context: {
+                    taskId: task.id,
+                    taskName: task.name,
+                    taskTypeKey: task.value,
+                    error: getErrorMessage(error),
+                },
+            });
+            await this.abortTaskRun({
+                logger: executeLogger,
+                taskId: task.id,
+                nodeId,
+                traceId: loopTraceId,
+            });
+        }
+
+        executeLogger.info("開始執行業務邏輯", {
+            topic: "task",
+            context: { taskId: task.id, displayName: taskFn.displayName },
+        });
+        const startTime = Date.now();
+        let result: TaskRunResult | null = null;
+        try {
+            result = await taskFn();
+        } catch (error) {
+            await onExecuteAbort(toError(error));
+            return
+        }
+        if (result == null) {
+            await onExecuteAbort(new Error("任務執行結果為空"));
+            return
+        }
+
+        executeLogger.info("任務執行完成", {
+            topic: "task",
+            context: { taskId: task.id, displayName: taskFn.displayName },
+        });
+        const { isSuccess: isTaskSuccess, cost, extra } = result ?? { isSuccess: false, cost: 0, extra: null };
+        if (isTaskSuccess) {
+            await this.finalizeTaskRun("success", { logger: executeLogger, taskId: task.id, taskTypeKey: task.value, nodeId, cost, extra, traceId: loopTraceId });
+        } else {
+            await this.finalizeTaskRun("failure", { logger: executeLogger, taskId: task.id, taskTypeKey: task.value, nodeId, cost, extra, traceId: loopTraceId });
+        }
+        const duration = Date.now() - startTime;
+        executeLogger.info("業務邏輯執行完成", {
+            topic: "task",
+            context: { taskId: task.id, durationMs: duration, },
+        });
+    }
+
+    /** 執行過程遇到未知錯誤以至於無法繼續執行時：DOING → OPEN（RESET），釋放已認領的任務。 */
+    private async abortTaskRun(params: {
+        logger: LoggerWithContext;
+        taskId: string;
+        nodeId: string;
+        traceId: string;
+        extra?: TaskRunResult["extra"];
+    }): Promise<boolean> {
+        const { logger, taskId, nodeId, traceId, extra } = params;
+        const logContext = { taskId, nodeId };
+        const extraValue = typeof extra === "string" ? extra : undefined;
+
+        const { error } = await patchChangeTaskStatus({
+            id: taskId,
+            action: TaskStatusAction.RESET,
+            nodeId,
+            extra: extraValue,
+            traceId,
+        });
+
+        if (error) {
+            logger.error(error.message, {
+                topic: "task",
+                context: logContext,
+            });
+            return false;
+        }
+        logger.info("任務已中止並 RESET 為 OPEN", { topic: "task", context: logContext });
+        return true;
+    }
+
+    /** Task 執行結束後更新 TaskStatus */
+    private async finalizeTaskRun(
+        outcome: "success" | "failure",
+        params: {
+            logger: LoggerWithContext;
+            taskId: string;
+            taskTypeKey: string;
+            nodeId: string;
+            cost: TaskRunResult["cost"];
+            extra: TaskRunResult["extra"];
+            traceId: string;
+        }
+    ): Promise<void> {
+        const { logger, taskId, nodeId, taskTypeKey, cost, extra, traceId } = params;
+        const outcomePrefix = outcome === "success" ? "任務成功" : "任務失敗";
+        const logContext = { taskTypeKey, taskId, nodeId, };
+        const extraValue = typeof extra === "string" ? extra : undefined;
+
+        const { error: changeTaskStatusError } =
+            outcome === "success"
+                ? await patchChangeTaskStatus({
+                    id: taskId,
+                    action: TaskStatusAction.FINISH,
+                    nodeId,
+                    cost,
+                    extra: extraValue,
+                    traceId,
+                })
+                : await patchChangeTaskStatus({
+                    id: taskId,
+                    action: TaskStatusAction.RESET,
+                    nodeId,
+                    extra: extraValue,
+                    traceId,
+                });
+        // TODO retry
+        if (changeTaskStatusError) {
+            // This should NOT happen
+            const upperMessage = `${outcomePrefix}但是更新 TaskStatus 失敗，產生孤兒 Task，請儘快排查問題`;
+            logger.critical(upperMessage, {
+                topic: "task",
+                context: logContext,
+            });
+            throw new Error(upperMessage);
+        }
+        logger.info("更新 TaskStatus 成功", { topic: "task", context: logContext });
+        if (outcome === "success") {
+            logger.success("任務執行結束，業務邏輯成功", { topic: "task", context: logContext });
+        } else {
+            logger.warn("任務執行結束，業務邏輯失敗", { topic: "task", context: logContext });
+        }
+    }
+
+    /**
+     * 關閉節點並退出進程。冪等：並發或重複調用復用同一進行中的 Promise，
+     * 避免重複 patchStopNode / process.exit。
+     */
+    async shutdown(options?: { trigger?: string }): Promise<void> {
+        if (this.shutdownPromise != null) {
+            const { logger } = logManager.withContext({
+                module: "nodeManager",
+                traceId: this.startupTraceId,
+                nodeId: this.getLogNodeId(),
+            });
+            logger.debug("shutdown 已在進行，跳過重複調用", {
+                topic: "node",
+                context: { trigger: options?.trigger ?? "unknown" },
+            });
+            return this.shutdownPromise;
+        }
+
+        this.isRunning = false;
+        this.shutdownPromise = this.runShutdown(options?.trigger).catch((error) => {
+            const { logger } = logManager.withContext({
+                module: "nodeManager",
+                traceId: this.startupTraceId,
+                nodeId: this.getLogNodeId(),
+            });
+            logger.error("shutdown 流程異常", {
+                topic: "node",
+                context: {
+                    trigger: options?.trigger ?? "explicit",
+                    error: getErrorMessage(error),
+                },
+            });
+            process.exit(1);
+        });
+        return this.shutdownPromise;
+    }
+
+    private async runShutdown(trigger?: string): Promise<void> {
+        const { logger } = logManager.withContext({
+            module: "nodeManager",
+            traceId: this.startupTraceId,
+            nodeId: this.getLogNodeId(),
+        });
+
+        logger.info("正在關閉節點進程", {
+            topic: "node",
+            context: { trigger: trigger ?? "explicit" },
+        });
+
+        if (this.localNodeId == null) {
+            logger.info("本地節點未註冊，直接退出", { topic: "node" });
+            process.exit(0);
+            return;
+        }
+
+        logger.info("正在登出節點", { topic: "node", context: { nodeId: this.localNodeId } });
+        try {
+            const { error } = await patchStopNode({
+                nodeId: this.localNodeId,
+                traceId: this.startupTraceId,
+            });
+            if (error) {
+                throw new Error(`patchStopNode 失敗: ${error.message}`);
+            }
+            logger.success("節點已登出", { topic: "node" });
+        } catch (error) {
+            logger.critical("登出節點失敗", {
+                topic: "node",
+                context: { error: getErrorMessage(error) },
+            });
+        } finally {
+            logger.info("節點進程退出", { topic: "node" });
+            process.exit(0);
+        }
+    }
+
+    /** @returns 心跳是否成功 */
+    async heartbeat(ctx: NodeLoopContext): Promise<boolean> {
+        const { loopTraceId, nodeId } = ctx;
+        const { logger } = logManager.withContext({
+            module: "heartbeat",
+            traceId: loopTraceId,
+            nodeId,
+        });
+
+        logger.info("開始發送心跳", { topic: "node" });
+        let error: { message: string } | undefined;
+        let lastHeartBeat: number | null | undefined;
+        try {
+            const response = await patchNodeHeartBeat({ nodeId, traceId: loopTraceId });
+            error = response.error;
+            lastHeartBeat = response.data;
+        } catch (caught) {
+            error = { message: getErrorMessage(caught) };
+            lastHeartBeat = null;
+        }
+        if (error || lastHeartBeat == null) {
+            this.consecutiveHeartbeatFailures++;
+            const failureCount = this.consecutiveHeartbeatFailures;
+            const logContext = {
+                error: getErrorMessage(error),
+                consecutiveFailures: failureCount,
+                threshold: NodeManager.HEARTBEAT_FAILURE_THRESHOLD,
+            };
+            if (failureCount >= NodeManager.HEARTBEAT_FAILURE_THRESHOLD) {
+                logger.critical("連續心跳失敗達上限，準備關閉節點", {
+                    topic: "node",
+                    context: logContext,
+                });
+                this.requestShutdown("heartbeat:consecutive-failures");
+            } else {
+                logger.warn("心跳更新失敗", { topic: "node", context: logContext });
+            }
+            return false;
+        }
+
+        this.consecutiveHeartbeatFailures = 0;
+        logger.success("心跳更新成功", {
+            topic: "node",
+            context: { lastHeartBeat: formatHeartbeat(lastHeartBeat) },
+        });
+        return true;
+    }
+
+    async batchCommand(ctx: NodeLoopContext) {
+        const { loopTraceId, nodeId } = ctx;
+        const { logger } = logManager.withContext({
+            module: "batchCommand",
+            traceId: loopTraceId,
+            nodeId,
+        });
+
+        logger.debug("開始檢查控制指令", { topic: "node" });
+
+        const { data: commandList = [], error: pollError } = await getPollCommandList({
+            nodeId,
+            traceId: loopTraceId,
+            size: MAX_POLL_TARGET_LIST_SIZE,
+        });
+        if (pollError) {
+            logger.warn("獲取指令失敗", {
+                topic: "node",
+                context: { error: pollError.message }
+            });
+            return;
+        }
+        if (commandList.length === 0) {
+            logger.info("獲取指令數量為 0", {
+                topic: "node",
+            });
+            return;
+        }
+
+        logger.info("獲取到控制指令", {
+            topic: "node",
+            context: { count: commandList.length },
+        });
+
+        for (const command of commandList) {
+            const cmd = command.name;
+            logger.info("執行控制指令", {
+                topic: "node",
+                context: { commandId: command.id, cmd },
+            });
+            try {
+                await this.executeCommand(cmd);
+                logger.success("控制指令執行成功", {
+                    topic: "node",
+                    context: { commandId: command.id, cmd },
+                });
+            } catch (error) {
+                logger.warn("控制指令執行失敗", {
+                    topic: "node",
+                    context: {
+                        commandId: command.id,
+                        cmd,
+                        error: getErrorMessage(error),
+                    },
+                });
+            }
+        }
+
+        logger.info("控制指令批次處理完成", {
+            topic: "node",
+            context: { totalDequeued: commandList.length },
+        });
+    }
+
+    async executeCommand(cmd: CommandType) {
+        switch (cmd) {
+            case CommandType.STOP_NODE:
+                this.requestShutdown("cmd:STOP_NODE");
+                return;
+            default: {
+                const unknownCmd: never = cmd;
+                throw new Error(`無法解析的cmd: ${unknownCmd}`);
+            }
+        }
+    }
+}
+
+export { NodeManager };

package/src/node/node-task.preset.ts

@@ -0,0 +1,13 @@
+// export const generateControllerTaskPreset = () => {
+//     return {
+//         category: CategoryTask.TASK_CONTROLLER,
+//         taskTypeFilterList: CONTROLLER_TASK_TYPE_ALLOW_LIST,
+//     };
+// };
+
+// export const getWorkerTaskPreset = () => {
+//     return {
+//         category: CategoryTask.TASK,
+//         taskTypeFilterList: WORKER_TASK_TYPE_ALLOW_LIST,
+//     };
+// };