target-supabase-sdk 0.1.8 → 0.1.9

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/log-manager";
+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, 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",
+        context: {
+            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/parcel/parcel-manager.ts

@@ -206,4 +206,4 @@ const ParcelManager = {
   reassembly,
 };
 
-export default ParcelManager;
+export { ParcelManager };

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

@@ -0,0 +1,111 @@
+import {
+    TASK_REPO_SCRIPT_CATEGORY,
+    type TaskRepoContext,
+    type TaskRepoScriptDetails,
+    type TaskRepoScriptRecord,
+} from "../task/task-repo-context";
+
+export { TASK_REPO_SCRIPT_CATEGORY };
+
+export interface LoadedRepoContext {
+    context: TaskRepoContext;
+    /** Cache key segment — typically repo hash or script hash */
+    contentHash: string;
+}
+
+export function isTaskRepoContext(value: unknown): value is TaskRepoContext {
+    if (value == null || typeof value !== "object") {
+        return false;
+    }
+    const record = value as TaskRepoContext;
+    return typeof record.taskParamsValidator === "function" && typeof record.taskFn === "function";
+}
+
+/**
+ * Normalize a dynamically imported module into {@link TaskRepoContext}.
+ * Supported shapes:
+ * - `export default { taskParamsValidator, taskFn }`
+ * - `export { taskParamsValidator, taskFn }`
+ * - `export default taskFn` (validator becomes `() => true`)
+ */
+export function normalizeRepoContextModule(
+    moduleExports: unknown,
+    taskTypeKey: string,
+    exportName?: string
+): TaskRepoContext | null {
+    if (moduleExports == null) {
+        return null;
+    }
+
+    const record = moduleExports as Record<string, unknown>;
+    const namedExport =
+        exportName != null && exportName !== "" ? record[exportName] : undefined;
+    const defaultExport = record.default;
+    const candidate = namedExport ?? defaultExport ?? moduleExports;
+
+    let taskParamsValidator: unknown;
+    let taskFn: unknown;
+
+    if (typeof candidate === "function") {
+        taskFn = candidate;
+        taskParamsValidator = record.taskParamsValidator;
+    } else if (typeof candidate === "object" && candidate != null) {
+        const ctx = candidate as Record<string, unknown>;
+        taskParamsValidator = ctx.taskParamsValidator;
+        taskFn = ctx.taskFn;
+    }
+
+    taskParamsValidator ??= record.taskParamsValidator;
+    taskFn ??= record.taskFn;
+
+    if (typeof taskFn !== "function") {
+        return null;
+    }
+
+    if (typeof taskParamsValidator !== "function") {
+        taskParamsValidator = () => true;
+    }
+
+    const fn = taskFn as TaskRepoContext["taskFn"];
+    if (fn.displayName == null || fn.displayName === "") {
+        fn.displayName = taskTypeKey;
+    }
+    if (fn.taskTypeKey == null || fn.taskTypeKey === "") {
+        fn.taskTypeKey = taskTypeKey;
+    }
+
+    return {
+        taskParamsValidator: taskParamsValidator as TaskRepoContext["taskParamsValidator"],
+        taskFn: fn,
+    };
+}
+
+export function pickEntryScript(scripts: TaskRepoScriptRecord[]): TaskRepoScriptRecord | null {
+    if (scripts.length === 0) {
+        return null;
+    }
+    const entry = scripts.find((script) => script.details.isEntry === true);
+    return entry ?? scripts[0];
+}
+
+export function getScriptLoadKey(script: TaskRepoScriptRecord): string {
+    const { source, modulePath, hash } = script.details;
+    if (hash != null && hash !== "") {
+        return hash;
+    }
+    if (source != null && source !== "") {
+        return `source:${source.length}:${source.slice(0, 64)}`;
+    }
+    if (modulePath != null && modulePath !== "") {
+        return `path:${modulePath}`;
+    }
+    return script.id;
+}
+
+export function assertScriptLoadable(
+    details: TaskRepoScriptDetails
+): details is TaskRepoScriptDetails & ({ source: string } | { modulePath: string }) {
+    const hasSource = details.source != null && details.source.trim() !== "";
+    const hasModulePath = details.modulePath != null && details.modulePath.trim() !== "";
+    return hasSource || hasModulePath;
+}

package/src/repo/repo-manager.ts

@@ -0,0 +1,217 @@
+import { getPossibleTarget } from "../core.api";
+import { SupabaseInitializer } from "../supabase";
+import { LoggerWithContext } from "../shared/log/log-manager";
+import type { TaskRepoContext, TaskRepoScriptRecord } from "../task/task-repo-context";
+import { TASK_REPO_SCRIPT_CATEGORY } from "../task/task-repo-context";
+import {
+    assertScriptLoadable,
+    isTaskRepoContext,
+    pickEntryScript,
+} from "./repo-context.utils";
+import { CategoryRepo, Repo } from "./repo.interface";
+import {
+    clearRepoScriptModuleCache,
+    loadRepoContextFromScript,
+    loadRepoContextFromUrl,
+} from "./repo.script-loader";
+
+const supabase = SupabaseInitializer.getInstance();
+
+type LocalRepoEntry =
+    | { kind: "context"; context: TaskRepoContext }
+    | { kind: "modulePath"; modulePath: string; exportName?: string };
+
+const localRepoRegistry = new Map<string, LocalRepoEntry>();
+const remoteContextCache = new Map<string, TaskRepoContext>();
+
+export interface GetRepoContextParams {
+    logger: LoggerWithContext;
+    /** Task type key (`task.value`) — matches {@link Repo.value} for remote lookup; local registry key */
+    taskTypeKey: string;
+}
+
+export interface GetRepoContextResult<T extends TaskRepoContext = TaskRepoContext> {
+    context: T | null;
+    /** Present when `context` is null — import / DB / format failure at repo layer */
+    error?: string;
+}
+
+function buildRemoteCacheKey(taskTypeKey: string, contentHash: string): string {
+    return `${taskTypeKey}@${contentHash}`;
+}
+
+async function fetchRemoteRepo(taskTypeKey: string): Promise<Repo | null> {
+    const { data } = await getPossibleTarget({
+        filterList: [
+            { field: "category", operator: "eq", value: CategoryRepo.REPO },
+            { field: "value", operator: "eq", value: taskTypeKey },
+        ],
+    });
+    return (data as Repo | null) ?? null;
+}
+
+async function fetchRemoteScripts(taskTypeKey: string): Promise<TaskRepoScriptRecord[]> {
+    const { data, error } = await supabase.client
+        .from("target")
+        .select("id, value, details")
+        .eq("category", TASK_REPO_SCRIPT_CATEGORY)
+        .eq("value", taskTypeKey);
+
+    if (error) {
+        throw error;
+    }
+
+    return (data ?? []) as TaskRepoScriptRecord[];
+}
+
+async function loadLocalEntry(
+    logger: LoggerWithContext,
+    entry: LocalRepoEntry,
+    taskTypeKey: string
+): Promise<TaskRepoContext | null> {
+    if (entry.kind === "context") {
+        return entry.context;
+    }
+
+    const loaded = await loadRepoContextFromScript({
+        logger,
+        script: {
+            id: `local:${taskTypeKey}`,
+            value: taskTypeKey,
+            details: {
+                manifestVersion: 0,
+                modulePath: entry.modulePath,
+                exportName: entry.exportName,
+                isEntry: true,
+            },
+        },
+        taskTypeKey,
+    });
+    return loaded?.context ?? null;
+}
+
+async function loadRemoteRepoContext(
+    logger: LoggerWithContext,
+    taskTypeKey: string
+): Promise<GetRepoContextResult> {
+    logger.info("從 Supabase 加載 Repo", { topic: "repo", context: { taskTypeKey } });
+
+    const remoteRepo = await fetchRemoteRepo(taskTypeKey);
+    if (remoteRepo == null) {
+        const error = `Supabase 未找到 Repo (value=${taskTypeKey})`;
+        logger.warn(error, { topic: "repo", context: { taskTypeKey } });
+        return { context: null, error };
+    }
+
+    const repoUrl = remoteRepo.details?.url?.trim() ?? "";
+    const repoHash = remoteRepo.details?.hash?.trim() ?? repoUrl;
+    const cacheKey = buildRemoteCacheKey(taskTypeKey, repoHash);
+    const cached = remoteContextCache.get(cacheKey);
+    if (cached != null) {
+        logger.info("命中遠程 Repo 上下文緩存", { topic: "repo", context: { cacheKey } });
+        return { context: cached };
+    }
+
+    const scripts = await fetchRemoteScripts(taskTypeKey);
+    const entryScript = pickEntryScript(scripts);
+
+    let loaded =
+        entryScript != null && assertScriptLoadable(entryScript.details)
+            ? await loadRepoContextFromScript({ logger, script: entryScript, taskTypeKey })
+            : null;
+
+    if (loaded == null && repoUrl !== "") {
+        logger.info("未找到 script 行，嘗試從 Repo.details.url 加載", {
+            topic: "repo",
+            context: { taskTypeKey, url: repoUrl },
+        });
+        loaded = await loadRepoContextFromUrl({ logger, url: repoUrl, taskTypeKey });
+    }
+
+    if (loaded == null) {
+        const error = `無法從 Repo 加載 TaskRepoContext (hasUrl=${repoUrl !== ""}, scriptCount=${scripts.length})`;
+        logger.warn(error, {
+            topic: "repo",
+            context: { taskTypeKey, hasUrl: repoUrl !== "", scriptCount: scripts.length },
+        });
+        return { context: null, error };
+    }
+
+    remoteContextCache.set(cacheKey, loaded.context);
+    return { context: loaded.context };
+}
+
+const getRepoContext = async <RepoContext extends TaskRepoContext>({
+    logger,
+    taskTypeKey,
+}: GetRepoContextParams): Promise<GetRepoContextResult<RepoContext>> => {
+    const localEntry = localRepoRegistry.get(taskTypeKey);
+    if (localEntry != null) {
+        logger.info("使用本地註冊的 Repo", { topic: "repo", context: { taskTypeKey } });
+        const context = await loadLocalEntry(logger, localEntry, taskTypeKey);
+        if (context != null && isTaskRepoContext(context)) {
+            return { context: context as RepoContext };
+        }
+        const error = "本地 Repo 模組加載失敗或未導出有效的 TaskRepoContext";
+        logger.warn(error, { topic: "repo", context: { taskTypeKey } });
+        return { context: null, error };
+    }
+
+    try {
+        const result = await loadRemoteRepoContext(logger, taskTypeKey);
+        if (result.context != null && isTaskRepoContext(result.context)) {
+            return { context: result.context as RepoContext };
+        }
+        return {
+            context: null,
+            error: result.error ?? "遠程 Repo 上下文無效",
+        };
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.error("從 Supabase 加載 Repo 失敗", {
+            topic: "repo",
+            context: { taskTypeKey, error: message },
+        });
+        return { context: null, error: message };
+    }
+};
+
+/** Register an in-process TaskRepoContext (highest priority — no Supabase fetch). */
+function registerLocalRepoContext(taskTypeKey: string, context: TaskRepoContext): void {
+    if (!isTaskRepoContext(context)) {
+        throw new Error("[RepoManager] Invalid TaskRepoContext");
+    }
+    localRepoRegistry.set(taskTypeKey, { kind: "context", context });
+}
+
+/** Register a local ESM module path; loaded via dynamic import when the task runs. */
+function registerLocalModule(taskTypeKey: string, modulePath: string, exportName?: string): void {
+    if (modulePath.trim() === "") {
+        throw new Error("[RepoManager] modulePath must not be empty");
+    }
+    localRepoRegistry.set(taskTypeKey, { kind: "modulePath", modulePath, exportName });
+}
+
+function unregisterLocalRepo(taskTypeKey: string): void {
+    localRepoRegistry.delete(taskTypeKey);
+}
+
+function getRegisteredLocalTaskTypeKeys(): string[] {
+    return [...localRepoRegistry.keys()];
+}
+
+function clearRemoteContextCache(): void {
+    remoteContextCache.clear();
+}
+
+const RepoManager = {
+    getRepoContext,
+    registerLocalRepoContext,
+    registerLocalModule,
+    unregisterLocalRepo,
+    getRegisteredLocalTaskTypeKeys,
+    clearRemoteContextCache,
+    clearRepoScriptModuleCache,
+};
+
+export { RepoManager };