target-supabase-sdk 0.1.9 → 0.2.1

package/src/task/task-node.ts

@@ -0,0 +1,302 @@
+import { isOptimisticLockResponse } from "../core.api";
+import { BaseNodeRuntime, LOG_TOPIC_NODE, type NodeLoopContext } from "../node/node-runtime.base";
+import { createLogger, createScope, type LoggerWithScope, withModule } from "../shared/log";
+import { getErrorMessage, toError } from "../shared/utils/error.utils";
+import { patchChangeTaskStatus, patchClaimTask } from "./task.api";
+import { CRITICAL_UNKNOWN_TASK_TRACE_ID, LOG_TOPIC_TASK } from "./task.constant";
+import { TaskStatusAction } from "./task.interface";
+import { TaskManager, type TaskRunResult } from "./task-manager";
+
+/**
+ * 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> {
+        const { availableTaskList, includeRemote } = await TaskManager.registerTasks({ logger });
+        this._availableTaskList = availableTaskList;
+        this._includeRemote = includeRemote;
+    }
+
+    protected async runLoopSteps(ctx: NodeLoopContext, heartbeatOk: boolean): Promise<void> {
+        if (!heartbeatOk) {
+            const logger = createLogger({
+                scope: createScope({
+                    module: `${this.runtimeModule}-runLoopSteps`,
+                    traceId: ctx.loopTraceId,
+                    labels: { nodeId: ctx.nodeId },
+                }),
+            });
+            logger.warn("心跳失敗，本輪跳過任務認領", { topic: LOG_TOPIC_NODE });
+            return;
+        }
+        await this.runAsWorker(ctx);
+    }
+
+    private async runAsWorker(ctx: NodeLoopContext): Promise<void> {
+        const { loopTraceId, nodeId } = ctx;
+        const loopScope = createScope({ module: "runAsWorker", traceId: loopTraceId, labels: { nodeId } });
+        const logger = createLogger({ scope: loopScope });
+
+        const availableTaskList = this.availableTaskList;
+        if (availableTaskList.length === 0) {
+            logger.warn("未配置可認領任務類型，跳過本輪", { topic: LOG_TOPIC_TASK });
+            return;
+        }
+
+        logger.debug("向 Supabase 認領任務", {
+            topic: LOG_TOPIC_TASK,
+            data: { availableTaskList },
+        });
+        const { data: task, error: claimError } = await patchClaimTask({
+            nodeId,
+            availableTaskList: [...availableTaskList],
+            traceId: loopTraceId,
+        });
+        if (claimError) {
+            if (isOptimisticLockResponse(claimError)) {
+                logger.debug("認領競爭失敗，本輪無可認領任務", {
+                    topic: LOG_TOPIC_TASK,
+                    data: { availableTaskList },
+                });
+                return;
+            }
+            logger.error("認領任務失敗", {
+                topic: LOG_TOPIC_TASK,
+                data: {
+                    availableTaskList,
+                    error: claimError.message,
+                    code: claimError.code,
+                },
+            });
+            return;
+        }
+        if (task == null) {
+            logger.debug("本輪無匹配的 TODO 任務", {
+                topic: LOG_TOPIC_TASK,
+                data: { availableTaskList },
+            });
+            return;
+        }
+
+        const taskTraceId = task.details.traceId ?? CRITICAL_UNKNOWN_TASK_TRACE_ID;
+        const taskScope = createScope({
+            module: "runAsWorker",
+            traceId: loopTraceId,
+            labels: { nodeId },
+            traceParentId: taskTraceId,
+        });
+        const taskLogger = createLogger({ scope: taskScope });
+        taskLogger.success("認領任務成功，準備執行", {
+            topic: LOG_TOPIC_TASK,
+            data: {
+                taskId: task.id,
+                taskName: task.name,
+                taskTypeKey: task.value,
+                taskStatus: task.details.status,
+            },
+        });
+
+        const prepareLogger = createLogger({ scope: withModule(taskScope, "prepareTask") });
+        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: LOG_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;
+        }
+        logger.success("任務準備完成", {
+            topic: LOG_TOPIC_TASK,
+            data: {
+                taskId: task.id,
+                taskName: task.name,
+                taskTypeKey: task.value,
+                displayName: taskFn.displayName,
+            },
+        });
+
+        const executeLogger = createLogger({ scope: withModule(taskScope, "executeTask") });
+        const onExecuteAbort = async (error?: Error) => {
+            executeLogger.critical("任務執行遇到未知錯誤，中止任務並 RESET 為 OPEN", {
+                topic: LOG_TOPIC_TASK,
+                data: {
+                    taskId: task.id,
+                    taskTypeKey: task.value,
+                    taskName: task.name,
+                    displayName: taskFn.displayName,
+                    error: getErrorMessage(error),
+                },
+            });
+            await this.abortTaskRun({
+                logger: executeLogger,
+                taskId: task.id,
+                nodeId,
+                traceId: taskTraceId,
+            });
+        };
+
+        executeLogger.info("開始執行業務邏輯", {
+            topic: LOG_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;
+        }
+
+        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: LOG_TOPIC_TASK,
+            data: {
+                taskId: task.id,
+                taskName: task.name,
+                taskTypeKey: task.value,
+                displayName: taskFn.displayName,
+                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: LOG_TOPIC_TASK, data: logData });
+            return false;
+        }
+        logger.info("任務已中止並 RESET 為 OPEN", { topic: LOG_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["extra"];
+            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: LOG_TOPIC_TASK, data: logData });
+            // TODO: 需要處理孤兒 Task
+            throw new Error(upperMessage);
+        }
+        logger.info("更新 TaskStatus 成功", { topic: LOG_TOPIC_TASK, data: logData });
+        if (outcome === "success") {
+            logger.success("任務執行結束，業務邏輯成功", { topic: LOG_TOPIC_TASK, data: logData });
+        } else {
+            logger.warn("任務執行結束，業務邏輯失敗", { topic: LOG_TOPIC_TASK, data: logData });
+        }
+    }
+}
+
+export { TaskNode };

package/src/task/task-post-validated.api.ts

@@ -0,0 +1,47 @@
+import { validateWithSchema } from "../core.api";
+import { generateResponse, type SupabaseResponse } from "../core.interface";
+import { createLogger, logManager } from "../shared/log";
+import type { Task } from "./task.interface";
+import { createTaskRow, postTaskSchema } from "./task-post.api";
+import { TaskRepoValidation } from "./task-repo-validation";
+
+/**
+ * Create a task row with publish-time Repo + params validation.
+ * **Node entry only** — requires local Repo bootstrap and {@link TaskRepoValidation}.
+ *
+ * @see target-supabase-sdk/node
+ */
+export const postTaskWithValidation = validateWithSchema(
+    postTaskSchema,
+    "postTaskSchema",
+)(async ({ name, value, params, taskStatus, tagList, extra, traceId, traceParentId }) => {
+    const taskTraceId = traceId?.trim() || logManager.generateTraceId();
+    const logger = createLogger({
+        module: "postTaskWithValidation",
+        traceId: taskTraceId,
+        traceParentId: traceParentId ?? null,
+    });
+
+    const validation = await TaskRepoValidation.validate({
+        logger,
+        taskTypeKey: value,
+        params,
+        bootstrapLocal: true,
+    });
+    if (!validation.isValid) {
+        logger.warn(validation.message, {
+            topic: "task",
+            data: {
+                taskTypeKey: value,
+                reason: validation.reason,
+                step: validation.step,
+            },
+        });
+        return generateResponse.error(validation.message, undefined, String(validation.code)) as SupabaseResponse<Task>;
+    }
+
+    return createTaskRow(
+        { name, value, params, taskStatus, tagList, extra, traceId, traceParentId, taskTraceId },
+        logger,
+    );
+});

package/src/task/task-post.api.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { createTarget, validateWithSchema } from "../core.api";
+import type { SupabaseResponse } from "../core.interface";
+import { createLogger, type LoggerWithScope, logManager } from "../shared/log";
+import { CategoryTask, type Task, TaskStatus } from "./task.interface";
+
+const traceIdSchema = z.string().trim().min(1).optional();
+const traceParentIdSchema = z.string().trim().min(1).nullable().optional();
+
+/** Initial status for a new task — OPEN (draft) or TODO (claimable by workers). */
+const postTaskInitialStatusSchema = z
+    .union([z.literal(TaskStatus.OPEN), z.literal(TaskStatus.TODO)])
+    .optional()
+    .default(TaskStatus.TODO);
+
+export const postTaskSchema = z.object({
+    name: z.string().trim().min(1),
+    /** Task type key — matches `task.value`, {@link patchClaimTask}, {@link Repo.value}, and local Repo registry. */
+    value: z.string().trim().min(1),
+    params: z.unknown(),
+    taskStatus: postTaskInitialStatusSchema,
+    tagList: z.array(z.string()).optional().default([]),
+    extra: z.string().optional(),
+    traceId: traceIdSchema,
+    traceParentId: traceParentIdSchema,
+});
+
+export type PostTaskPayload = z.infer<typeof postTaskSchema>;
+
+export type CreateTaskRowInput = PostTaskPayload & {
+    taskTraceId: string;
+};
+
+/** Shared DB insert for {@link postTask} and {@link postTaskWithValidation}. */
+export async function createTaskRow(
+    { name, value, params, taskStatus, tagList, extra, taskTraceId, traceParentId }: CreateTaskRowInput,
+    logger: LoggerWithScope,
+): Promise<SupabaseResponse<Task>> {
+    const result = await createTarget<Task, PostTaskPayload>({
+        payload: {
+            name,
+            value,
+            params,
+            taskStatus,
+            tagList,
+            extra,
+            traceId: taskTraceId,
+            traceParentId,
+        },
+        createFn: () => ({
+            name,
+            value,
+            category: CategoryTask.TASK,
+            tagList,
+            extra,
+            details: {
+                manifestVersion: 0,
+                status: taskStatus,
+                params,
+                progress: 0,
+                nodeId: null,
+                traceId: taskTraceId,
+            },
+        }),
+    });
+
+    logger.info("任務已創建", {
+        topic: "task",
+        data: {
+            taskId: result.data?.id,
+            taskTypeKey: value,
+            status: taskStatus,
+            traceId: taskTraceId,
+        },
+    });
+
+    return result;
+}
+
+/**
+ * Create a task row (scheduler / admin). **Browser and Node** — no Repo or params validation.
+ * Execution-time checks live in {@link TaskManager.prepareTask}.
+ */
+export const postTask = validateWithSchema(
+    postTaskSchema,
+    "postTaskSchema",
+)(async ({ name, value, params, taskStatus, tagList, extra, traceId, traceParentId }) => {
+    const taskTraceId = traceId?.trim() || logManager.generateTraceId();
+    const logger = createLogger({
+        module: "postTask",
+        traceId: taskTraceId,
+        traceParentId: traceParentId ?? null,
+    });
+
+    return createTaskRow(
+        { name, value, params, taskStatus, tagList, extra, traceId, traceParentId, taskTraceId },
+        logger,
+    );
+});

package/src/task/task-queue.ts

@@ -0,0 +1,18 @@
+import type { Task, TaskStatus } from "./task.interface";
+
+export type TaskStatusCount = Partial<Record<TaskStatus, number>>;
+
+/** Count tasks of `taskType` grouped by each requested status. */
+export function countTasksByType(tasks: Task[], taskType: string, statuses: TaskStatus[]): TaskStatusCount {
+    const filtered = tasks.filter((task) => task.value === taskType);
+    const counts: TaskStatusCount = {};
+    for (const status of statuses) {
+        counts[status] = filtered.filter((task) => task.details.status === status).length;
+    }
+    return counts;
+}
+
+/** Total tasks of `taskType` whose status is in `statuses`. */
+export function summarizeTaskQueue(tasks: Task[], taskType: string, statuses: TaskStatus[]): number {
+    return tasks.filter((task) => task.value === taskType && statuses.includes(task.details.status)).length;
+}

package/src/task/task-repo-context.ts

@@ -86,6 +86,8 @@ export interface BootstrapLocalTasksResult {
     registered: string[];
     skipped: { taskDir: string; reason: string }[];
     errors: { taskDir: string; error: string }[];
+    /** True when scan was skipped due to unchanged config fingerprint */
+    cached?: boolean;
 }
 
 /** Host app config directory (relative to `cwd`) — recommended for library consumers */
@@ -94,7 +96,8 @@ export const TASK_RUNNER_CONFIG_DIR = "config" as const;
 export const TASK_RUNNER_ROOT_CONFIG_FILENAME = "task.config.js" as const;
 
 /** Default root config path: `config/task.config.js` */
-export const TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH = `${TASK_RUNNER_CONFIG_DIR}/${TASK_RUNNER_ROOT_CONFIG_FILENAME}` as const;
+export const TASK_RUNNER_ROOT_CONFIG_RELATIVE_PATH =
+    `${TASK_RUNNER_CONFIG_DIR}/${TASK_RUNNER_ROOT_CONFIG_FILENAME}` as const;
 
 /** Legacy fallback at project root */
 export const TASK_RUNNER_ROOT_CONFIG_LEGACY_RELATIVE_PATH = TASK_RUNNER_ROOT_CONFIG_FILENAME;

package/src/task/task-repo-validation.ts

@@ -0,0 +1,169 @@
+import { type RepoContextFailureReason, RepoManager } from "../repo/repo-manager";
+import type { LoggerWithScope } from "../shared/log";
+import { type BootstrapLocalTasksOptions, bootstrapLocalTasks } from "./local-task-registry";
+import { ResultCode } from "./task.interface";
+import type { TaskRepoContext } from "./task-repo-context";
+
+export type TaskRepoValidationFailureReason =
+    | "MISSING_PARAMS"
+    | RepoContextFailureReason
+    | "PARAMS_VALIDATION_FAILED"
+    | "TASK_TYPE_KEY_MISMATCH";
+
+export type ValidateTaskRepoAndParamsInput = {
+    logger: LoggerWithScope;
+    taskTypeKey: string;
+    params: unknown;
+    /**
+     * When true, run {@link bootstrapLocalTasks} before resolve (CLI / Trigger / postTaskWithValidation).
+     * Worker paths should omit — {@link TaskManager.registerTasks} already bootstrapped.
+     */
+    bootstrapLocal?: boolean;
+    bootstrapLocalOptions?: BootstrapLocalTasksOptions;
+    /**
+     * When false, do not fetch Repo from Supabase if the task type is not locally registered.
+     * Default `true`. Align with {@link RegisterTasksOptions.includeRemote}.
+     */
+    includeRemote?: boolean;
+};
+
+export type ValidateTaskRepoAndParamsFailure = {
+    isValid: false;
+    code: ResultCode;
+    message: string;
+    reason: TaskRepoValidationFailureReason;
+    step: string;
+};
+
+export type ValidateTaskRepoAndParamsSuccess = {
+    isValid: true;
+    repoContext: TaskRepoContext;
+};
+
+export type ValidateTaskRepoAndParamsResult = ValidateTaskRepoAndParamsFailure | ValidateTaskRepoAndParamsSuccess;
+
+function validateTaskParams(
+    validator: TaskRepoContext["taskParamsValidator"],
+    taskParams: unknown,
+    logger: LoggerWithScope,
+): boolean {
+    try {
+        return validator(taskParams) === true;
+    } catch (error) {
+        logger.warn("taskParamsValidator 拋出異常", {
+            topic: "task",
+            data: { error: error instanceof Error ? error.message : error },
+        });
+        return false;
+    }
+}
+
+function invalid(params: {
+    reason: TaskRepoValidationFailureReason;
+    code: ResultCode;
+    message: string;
+    step: string;
+}): ValidateTaskRepoAndParamsFailure {
+    return { isValid: false, ...params };
+}
+
+/**
+ * Resolve task Repo context and validate `params` via `taskParamsValidator`.
+ *
+ * Repo resolution uses {@link RepoManager.getRepoContext}:
+ * local registry first; when no local entry and `includeRemote`, loads from Supabase.
+ */
+async function validateTaskRepoAndParams({
+    logger,
+    taskTypeKey,
+    params,
+    bootstrapLocal = false,
+    bootstrapLocalOptions,
+    includeRemote = true,
+}: ValidateTaskRepoAndParamsInput): Promise<ValidateTaskRepoAndParamsResult> {
+    if (params == null) {
+        return invalid({
+            reason: "MISSING_PARAMS",
+            code: ResultCode.PARAMS_NOT_VALID,
+            message: "任務缺少 params",
+            step: "params",
+        });
+    }
+
+    if (bootstrapLocal) {
+        const bootstrap = await bootstrapLocalTasks({
+            ...bootstrapLocalOptions,
+            forTaskTypeKey: taskTypeKey,
+        });
+        logger.debug("本地任務 bootstrap 完成", {
+            topic: "task",
+            data: {
+                taskTypeKey,
+                step: "local_bootstrap",
+                status: bootstrap.status,
+                registered: bootstrap.registered,
+                cached: bootstrap.cached ?? false,
+                message: bootstrap.message,
+            },
+        });
+    }
+
+    logger.debug("開始解析 Repo 上下文", {
+        topic: "task",
+        data: { taskTypeKey, step: "repo_load", includeRemote },
+    });
+
+    const {
+        context: repoContext,
+        error: repoError,
+        failureReason,
+        resolvedVia,
+    } = await RepoManager.getRepoContext<TaskRepoContext>({
+        logger,
+        taskTypeKey,
+        includeRemote,
+    });
+
+    if (repoContext == null) {
+        return invalid({
+            reason: failureReason ?? "REMOTE_REPO_LOAD_FAILED",
+            code: ResultCode.REPO_NOT_VALID,
+            message: repoError ?? "無法加載 Repo 上下文",
+            step: "repo_load",
+        });
+    }
+
+    logger.debug("Repo 上下文解析完成", {
+        topic: "task",
+        data: { taskTypeKey, step: "repo_load", resolvedVia },
+    });
+
+    if (repoContext.taskFn.taskTypeKey !== taskTypeKey) {
+        return invalid({
+            reason: "TASK_TYPE_KEY_MISMATCH",
+            code: ResultCode.REPO_NOT_VALID,
+            message: `taskFn.taskTypeKey (${repoContext.taskFn.taskTypeKey}) 與 task.value (${taskTypeKey}) 不一致`,
+            step: "task_type_key",
+        });
+    }
+
+    logger.debug("開始校驗任務參數", { topic: "task", data: { taskTypeKey, step: "params_validation" } });
+    if (!validateTaskParams(repoContext.taskParamsValidator, params, logger)) {
+        return invalid({
+            reason: "PARAMS_VALIDATION_FAILED",
+            code: ResultCode.PARAMS_NOT_VALID,
+            message: "任務參數校驗失敗",
+            step: "params_validation",
+        });
+    }
+
+    logger.debug("任務參數校驗通過", { topic: "task", data: { taskTypeKey, step: "params_validation" } });
+
+    return { isValid: true, repoContext };
+}
+
+const TaskRepoValidation = {
+    validate: validateTaskRepoAndParams,
+};
+
+export { TaskRepoValidation, validateTaskRepoAndParams };