target-supabase-sdk 0.1.8 → 0.2.0

package/src/node/node.api.ts

@@ -1,161 +1,139 @@
-import { CategoryTask, Task, TaskDetails, TaskStatus } from "../task/task.interface";
-import { createTarget, getPossibleTarget, updateTargetDetails } from "../core.api";
+import { createTarget, QueryFilter, updateTargetDetails, validateWithSchema } from "../core.api";
 import { generateResponse } from "../core.interface";
-import { BaseValidator } from "../core.utils";
+import { createApiLogger } from "../shared/log";
+import { z } from "zod";
 import { CategoryNode, Node, NodeDetails, NodeStatus } from "./node.interface";
 
-export interface PostRegisterNodePayload {
-}
+const NODE_STATUS_FIELD = "details->>status" as const;
 
-export class PostListValidator extends BaseValidator<PostRegisterNodePayload> {
-    protected requiredFields: (keyof PostRegisterNodePayload)[] = [];
-    protected optionalFields: (keyof PostRegisterNodePayload)[] = [];
-
-    constructor() {
-        super();
-        // Add custom
-        this.addCustomValidator((val) => {
-            return true;
-        });
-    }
-}
+const nodeIdSchema = z.string().trim().min(1);
+const traceIdSchema = z.string().trim().min(1).optional();
+
+// ─── Zod schemas ─────────────────────────────────────────────────────────────
+
+export const postRegisterNodeSchema = z.object({
+    traceId: traceIdSchema,
+});
+
+export type PostRegisterNodePayload = z.infer<typeof postRegisterNodeSchema>;
+
+export const patchNodeHeartBeatSchema = z.object({
+    nodeId: nodeIdSchema,
+    traceId: traceIdSchema,
+});
+
+export type PatchNodeHeartBeatPayload = z.infer<typeof patchNodeHeartBeatSchema>;
+
+export const patchStopNodeSchema = z.object({
+    nodeId: nodeIdSchema,
+    traceId: traceIdSchema,
+});
+
+export type PatchStopNodePayload = z.infer<typeof patchStopNodeSchema>;
 
+export const patchChangeNodeStatusSchema = z.object({
+    nodeId: nodeIdSchema,
+    status: z.nativeEnum(NodeStatus),
+    /** When set, UPDATE only if current status matches (optimistic lock). */
+    fromStatus: z.nativeEnum(NodeStatus).optional(),
+    traceId: traceIdSchema,
+});
 
+export type PatchChangeNodeStatusPayload = z.infer<typeof patchChangeNodeStatusSchema>;
 
-export const postRegisterNode = async (payload: PostRegisterNodePayload) => {
+// ─── Optimistic lock helpers ─────────────────────────────────────────────────
+
+function lockOnNodeStatus(status: NodeStatus): QueryFilter[] {
+    return [{ field: NODE_STATUS_FIELD, operator: "eq", value: status }];
+}
+
+// ─── postRegisterNode ────────────────────────────────────────────────────────
+
+export const postRegisterNode = validateWithSchema(
+    postRegisterNodeSchema,
+    "postRegisterNodeSchema"
+)(async (payload) => {
     return createTarget<Node, PostRegisterNodePayload>({
-        payload: payload,
-        validator: PostListValidator,
-        createFn: (validPayload) => {
+        payload,
+        createFn: () => {
             const details: NodeDetails = {
                 manifestVersion: 0,
                 status: NodeStatus.READY,
                 lastHeartBeat: Date.now(),
             };
             return {
-                name: '',
+                name: "",
                 category: CategoryNode.NODE,
-                value: '',
+                value: "",
                 tagList: [],
                 details,
             };
         },
     });
-};
+});
+
+// ─── patchNodeHeartBeat ──────────────────────────────────────────────────────
 
-export const patchNodeHeartBeat = async ({ nodeId }: { nodeId: string }) => {
+export const patchNodeHeartBeat = validateWithSchema(
+    patchNodeHeartBeatSchema,
+    "patchNodeHeartBeatSchema"
+)(async ({ nodeId }) => {
     const lastHeartBeat = Date.now();
     await updateTargetDetails<Node, NodeDetails>({
         id: nodeId,
-        updateFn: (details) => {
-            return {
-                ...details,
-                lastHeartBeat,
-            };
-        },
+        updateFn: (details) => ({
+            ...details,
+            lastHeartBeat,
+        }),
     });
     return generateResponse.success(lastHeartBeat);
-};
+});
+
+// ─── patchStopNode ───────────────────────────────────────────────────────────
 
-export const patchStopNode = async ({ nodeId }: { nodeId: string }) => {
+export const patchStopNode = validateWithSchema(
+    patchStopNodeSchema,
+    "patchStopNodeSchema"
+)(async ({ nodeId }) => {
     const lastHeartBeat = Date.now();
     // TODO 等待任務全部完成才下綫 應該先使用NodeStatus.DRAINING
     await updateTargetDetails<Node, NodeDetails>({
         id: nodeId,
-        updateFn: (details) => {
-            return {
-                ...details,
-                lastHeartBeat,
-                status: NodeStatus.LOST,
-            };
-        },
+        updateFn: (details) => ({
+            ...details,
+            lastHeartBeat,
+            status: NodeStatus.LOST,
+        }),
     });
     return generateResponse.success(lastHeartBeat);
-};
+});
 
-export interface PatchClaimTaskPayload {
-    nodeId: string;
-    availableTaskList: string[];
-}
-
-/**
- * Atomically claim one TODO task for this node.
- *
- * Flow: find a candidate (TODO + value in availableTaskList) → UPDATE with optimistic lock
- * (status must still be TODO) → return the updated Task row for the executor to run.
- *
- * Returns `data: null` when no TODO task matches. On optimistic lock conflict,
- * `updateTargetDetails` throws — callers may catch `isOptimisticLockError` to retry.
- */
-export const patchClaimTask = async ({
-    nodeId,
-    availableTaskList,
-}: PatchClaimTaskPayload) => {
-    if (availableTaskList.length === 0) {
-        console.log("[patchClaimTask] skipped: availableTaskList is empty", { nodeId });
-        return generateResponse.success(null);
-    }
-
-    // Step 1: Pick one matching TODO task (not locked; another node may claim the same row next).
-    const { data: possibleTask } = await getPossibleTarget({
-        filterList: [
-            {
-                field: "category",
-                operator: "eq",
-                value: CategoryTask.TASK,
-            },
-            {
-                field: "details->>status",
-                operator: "eq",
-                value: TaskStatus.TODO,
-            },
-            {
-                field: "value",
-                operator: "in",
-                value: availableTaskList,
-            },
-        ],
-    });
+// ─── patchChangeNodeStatus ───────────────────────────────────────────────────
 
-    if (possibleTask == null) {
-        console.log("[patchClaimTask] no TODO task for node capabilities", {
-            nodeId,
-            availableTaskList,
-        });
-        return generateResponse.success(null);
-    }
-
-    const todoTask = possibleTask as Task;
-    console.log("[patchClaimTask] attempting claim", {
-        nodeId,
-        taskId: todoTask.id,
-        taskValue: todoTask.value,
-    });
+export const patchChangeNodeStatus = validateWithSchema(
+    patchChangeNodeStatusSchema,
+    "patchChangeNodeStatusSchema"
+)(async ({ nodeId, status, fromStatus, traceId }) => {
+    const logger = createApiLogger("patchChangeNodeStatus", { traceId, labels: { nodeId } });
 
-    // Step 2: Claim with DB optimistic lock — UPDATE only if status is still TODO.
-    const data = await updateTargetDetails<Task, TaskDetails>({
-        id: todoTask.id,
-        optimisticLockFilterList: [
-            {
-                field: "details->>status",
-                operator: "eq",
-                value: TaskStatus.TODO,
-            },
-        ],
+    const data = await updateTargetDetails<Node, NodeDetails>({
+        id: nodeId,
+        optimisticLockFilterList: fromStatus != null ? lockOnNodeStatus(fromStatus) : [],
         updateFn: (details) => ({
             ...details,
-            status: TaskStatus.DOING,
-            nodeId,
+            status,
+            lastHeartBeat: Date.now(),
         }),
     });
 
-    console.log("[patchClaimTask] claim succeeded", {
-        nodeId,
-        taskId: data.id,
-        taskValue: data.value,
-        status: (data as Task).details.status,
+    logger.info("节点状态更新成功", {
+        topic: "node",
+        data: {
+            nodeId,
+            status,
+            fromStatus,
+        },
     });
 
-    // Return full updated row so executor can read repo/params without another fetch.
     return generateResponse.success(data);
-};
+});

package/src/node/node.interface.ts

@@ -1,7 +1,9 @@
 import { Target } from "../core.interface";
 
 export enum NodeStatus {
+    /** Registered, not yet in worker loop. */
     READY = "READY",
+    /** Worker main loop is running (accepts tasks until shutdown). */
     BUSY = "BUSY",
     /** Heartbeat lost or voluntarily offline; considered unavailable by the scheduler. */
     LOST = "LOST",
@@ -30,3 +32,9 @@ export interface NodeDetails {
     lastHeartBeat: number;
 };
 
+/** 主循环单轮运行时上下文 — 由 start() 创建并向下传递 */
+export interface NodeLoopContext {
+    loopTraceId: string;
+    nodeId: string;
+}
+

package/src/node/node.utils.ts

@@ -0,0 +1,36 @@
+export const formatTimestamp = (timestamp: number): string => {
+    return new Intl.DateTimeFormat("zh-CN", {
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hour12: false,
+        fractionalSecondDigits: 3,
+    }).format(timestamp);
+};
+
+export const formatRelativeTime = (timestamp: number): string => {
+    const now = Date.now();
+    const diff = now - timestamp;
+
+    if (diff < 1000) return "刚刚";
+    if (diff < 60000) return `${Math.floor(diff / 1000)}秒前`;
+    if (diff < 3600000) return `${Math.floor(diff / 60000)}分钟前`;
+    if (diff < 86400000) return `${Math.floor(diff / 3600000)}小时前`;
+
+    return formatTimestamp(timestamp);
+};
+
+export const getRandomInterval = (): number => {
+    const min = 15 * 1000;
+    const max = 1 * 60 * 1000;
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+};
+
+export const formatHeartbeat = (timestamp: number): string => {
+    const absolute = formatTimestamp(timestamp);
+    const relative = formatRelativeTime(timestamp);
+    return `${absolute} (${relative})`;
+};

package/src/node/task-node.ts

@@ -0,0 +1,284 @@
+import {
+    logManager,
+    withModule,
+    type LoggerWithScope,
+} from "../shared/log";
+import { scopeForNodeLoop } from "./node-log-scope";
+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 { NodeLoopContext } from "./node.interface";
+import { BaseNodeRuntime } from "./node-runtime.base";
+
+/**
+ * Task worker node: commands → heartbeat → claim & execute tasks.
+ * Built on {@link BaseNodeRuntime}.
+ */
+class TaskNode extends BaseNodeRuntime {
+    private _availableTaskList: string[] = [];
+    private _includeRemote = true;
+
+    get availableTaskList(): readonly string[] {
+        return [...this._availableTaskList];
+    }
+
+    constructor() {
+        super("taskNode");
+    }
+
+    protected async onBeforeRegisterNode(logger: LoggerWithScope): Promise<void> {
+        logger.info("開始註冊任務", { topic: "node" });
+        const { availableTaskList, includeRemote } = await TaskManager.registerTasks({ logger });
+        this._availableTaskList = availableTaskList;
+        this._includeRemote = includeRemote;
+    }
+
+    protected async runLoopSteps(ctx: NodeLoopContext, heartbeatOk: boolean): Promise<void> {
+        const loopScope = scopeForNodeLoop({
+            module: `${this.runtimeModule}-loop-iteration`,
+            traceId: ctx.loopTraceId,
+            nodeId: ctx.nodeId,
+        });
+        if (!heartbeatOk) {
+            const { logger } = logManager.withScope(loopScope);
+            logger.warn("心跳失敗，本輪跳過任務認領", { topic: "node" });
+            return;
+        }
+        await this.runAsWorker(ctx);
+    }
+
+    async runAsWorker(ctx: NodeLoopContext) {
+        const { loopTraceId, nodeId } = ctx;
+        const loopScope = scopeForNodeLoop({ module: "runAsWorker", traceId: loopTraceId, nodeId });
+        const { logger } = logManager.withScope(loopScope);
+
+        const availableTaskList = this.availableTaskList;
+        if (availableTaskList.length === 0) {
+            logger.warn("未配置可認領任務類型，跳過本輪", { topic: "task" });
+            return;
+        }
+
+        logger.info("向 Supabase 認領任務", {
+            topic: "task",
+            data: { availableTaskList },
+        });
+        const { data: task, error: claimError } = await patchClaimTask({
+            nodeId,
+            availableTaskList: [...availableTaskList],
+            traceId: loopTraceId,
+        });
+        if (claimError) {
+            logger.error("認領任務 API 失敗", {
+                topic: "task",
+                data: {
+                    availableTaskList,
+                    error: claimError.message,
+                },
+            });
+            return;
+        }
+        if (task == null) {
+            logger.info("本輪無匹配的 TODO 任務", {
+                topic: "task",
+                data: { availableTaskList },
+            });
+            return;
+        }
+
+        logger.info("認領任務成功，準備執行", {
+            topic: "task",
+            data: {
+                taskId: task.id,
+                taskName: task.name,
+                taskTypeKey: task.value,
+                taskStatus: task.details.status,
+            },
+        });
+
+        const taskTraceId = task.details.traceId ?? loopTraceId;
+        const taskScope = scopeForNodeLoop({
+            module: "prepareTask",
+            traceId: taskTraceId,
+            nodeId,
+            traceParentId: loopTraceId,
+        });
+        const { logger: prepareLogger } = logManager.withScope(taskScope);
+        const prepareResult = await TaskManager.prepareTask({
+            logger: prepareLogger,
+            task,
+            includeRemote: this._includeRemote,
+        });
+        const { isSuccess: isPrepareSuccess, taskFn, code, message, reason, step } = prepareResult;
+        if (!isPrepareSuccess || taskFn == null) {
+            prepareLogger.critical("任務準備失敗，無法繼續執行，中止任務並 RESET 為 OPEN", {
+                topic: "task",
+                data: {
+                    taskId: task.id,
+                    taskTypeKey: task.value,
+                    code,
+                    message,
+                    reason,
+                    step,
+                },
+            });
+            await this.abortTaskRun({
+                logger: prepareLogger,
+                taskId: task.id,
+                nodeId,
+                traceId: taskTraceId,
+            });
+            return;
+        }
+
+        const { logger: executeLogger } = logManager.withScope(withModule(taskScope, "executeTask"));
+        const onExecuteAbort = async (error?: Error) => {
+            logger.critical("任務執行遇到未知錯誤，中止任務並 RESET 為 OPEN", {
+                topic: "task",
+                data: {
+                    taskId: task.id,
+                    taskName: task.name,
+                    taskTypeKey: task.value,
+                    error: getErrorMessage(error),
+                },
+            });
+            await this.abortTaskRun({
+                logger: executeLogger,
+                taskId: task.id,
+                nodeId,
+                traceId: taskTraceId,
+            });
+        };
+
+        executeLogger.info("開始執行業務邏輯", {
+            topic: "task",
+            data: { 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",
+            data: { 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: taskTraceId,
+            });
+        } else {
+            await this.finalizeTaskRun("failure", {
+                logger: executeLogger,
+                taskId: task.id,
+                taskTypeKey: task.value,
+                nodeId,
+                cost,
+                extra,
+                traceId: taskTraceId,
+            });
+        }
+        const duration = Date.now() - startTime;
+        executeLogger.info("業務邏輯執行完成", {
+            topic: "task",
+            data: { taskId: task.id, durationMs: duration },
+        });
+    }
+
+    private async abortTaskRun(params: {
+        logger: LoggerWithScope;
+        taskId: string;
+        nodeId: string;
+        traceId: string;
+        extra?: TaskRunResult["extra"];
+    }): Promise<boolean> {
+        const { logger, taskId, nodeId, traceId, extra } = params;
+        const logData = { 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", data: logData });
+            return false;
+        }
+        logger.info("任務已中止並 RESET 為 OPEN", { topic: "task", data: logData });
+        return true;
+    }
+
+    private async finalizeTaskRun(
+        outcome: "success" | "failure",
+        params: {
+            logger: LoggerWithScope;
+            taskId: string;
+            taskTypeKey: string;
+            nodeId: string;
+            cost: TaskRunResult["cost"];
+            extra: TaskRunResult["extr\a"];
+            traceId: string;
+        }
+    ): Promise<void> {
+        const { logger, taskId, nodeId, taskTypeKey, cost, extra, traceId } = params;
+        const outcomePrefix = outcome === "success" ? "任務成功" : "任務失敗";
+        const logData = {
+            taskTypeKey,
+            taskId,
+            nodeId,
+            ...(extra != null && extra !== "" ? { extra } : {}),
+        };
+        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,
+                });
+
+        if (changeTaskStatusError) {
+            const upperMessage = `${outcomePrefix}但是更新 TaskStatus 失敗，產生孤兒 Task，請儘快排查問題`;
+            logger.critical(upperMessage, { topic: "task", data: logData });
+            throw new Error(upperMessage);
+        }
+        logger.info("更新 TaskStatus 成功", { topic: "task", data: logData });
+        if (outcome === "success") {
+            logger.success("任務執行結束，業務邏輯成功", { topic: "task", data: logData });
+        } else {
+            logger.warn("任務執行結束，業務邏輯失敗", { topic: "task", data: logData });
+        }
+    }
+}
+
+export { TaskNode };