target-supabase-sdk 0.1.7 → 0.1.9

package/src/node/node.api.ts

@@ -0,0 +1,139 @@
+import { createTarget, QueryFilter, updateTargetDetails, validateWithSchema } from "../core.api";
+import { generateResponse } from "../core.interface";
+import { createApiLogger } from "../shared/log/log-manager";
+import { z } from "zod";
+import { CategoryNode, Node, NodeDetails, NodeStatus } from "./node.interface";
+
+const NODE_STATUS_FIELD = "details->>status" as const;
+
+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>;
+
+// ─── 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,
+        createFn: () => {
+            const details: NodeDetails = {
+                manifestVersion: 0,
+                status: NodeStatus.READY,
+                lastHeartBeat: Date.now(),
+            };
+            return {
+                name: "",
+                category: CategoryNode.NODE,
+                value: "",
+                tagList: [],
+                details,
+            };
+        },
+    });
+});
+
+// ─── patchNodeHeartBeat ──────────────────────────────────────────────────────
+
+export const patchNodeHeartBeat = validateWithSchema(
+    patchNodeHeartBeatSchema,
+    "patchNodeHeartBeatSchema"
+)(async ({ nodeId }) => {
+    const lastHeartBeat = Date.now();
+    await updateTargetDetails<Node, NodeDetails>({
+        id: nodeId,
+        updateFn: (details) => ({
+            ...details,
+            lastHeartBeat,
+        }),
+    });
+    return generateResponse.success(lastHeartBeat);
+});
+
+// ─── patchStopNode ───────────────────────────────────────────────────────────
+
+export const patchStopNode = validateWithSchema(
+    patchStopNodeSchema,
+    "patchStopNodeSchema"
+)(async ({ nodeId }) => {
+    const lastHeartBeat = Date.now();
+    // TODO 等待任務全部完成才下綫 應該先使用NodeStatus.DRAINING
+    await updateTargetDetails<Node, NodeDetails>({
+        id: nodeId,
+        updateFn: (details) => ({
+            ...details,
+            lastHeartBeat,
+            status: NodeStatus.LOST,
+        }),
+    });
+    return generateResponse.success(lastHeartBeat);
+});
+
+// ─── patchChangeNodeStatus ───────────────────────────────────────────────────
+
+export const patchChangeNodeStatus = validateWithSchema(
+    patchChangeNodeStatusSchema,
+    "patchChangeNodeStatusSchema"
+)(async ({ nodeId, status, fromStatus, traceId }) => {
+    const logger = createApiLogger("patchChangeNodeStatus", { traceId, nodeId });
+
+    const data = await updateTargetDetails<Node, NodeDetails>({
+        id: nodeId,
+        optimisticLockFilterList: fromStatus != null ? lockOnNodeStatus(fromStatus) : [],
+        updateFn: (details) => ({
+            ...details,
+            status,
+            lastHeartBeat: Date.now(),
+        }),
+    });
+
+    logger.info("节点状态更新成功", {
+        topic: "node",
+        context: {
+            nodeId,
+            status,
+            fromStatus,
+        },
+    });
+
+    return generateResponse.success(data);
+});

package/src/node/node.interface.ts

@@ -0,0 +1,40 @@
+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",
+    /** TODO Gracefully draining: not accepting new tasks, waiting for in-flight tasks to complete. */
+    DRAINING = "DRAINING",
+    /** TODO Disabled by an administrator; excluded from scheduling. */
+    DISABLED = "DISABLED",
+}
+
+export enum CategoryNode {
+    NODE = "node",
+}
+
+export interface Node extends Target {
+    /** Empty */
+    name: string;
+    /** Empty */
+    value: string;
+    details: NodeDetails;
+    category: CategoryNode;
+}
+
+export interface NodeDetails {
+    manifestVersion: number;
+    status: NodeStatus;
+    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/question-list/question-list.api.ts

@@ -9,7 +9,7 @@ export class PostCreateQuestionListValidator extends BaseValidator<PostCreateQue
   constructor() {
     super();
     // Add custom
-    this.addValidator((val) => {
+    this.addCustomValidator((val) => {
       return true;
     });
   }

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 };

package/src/repo/repo.api.ts

@@ -0,0 +1,50 @@
+import { scanTargetList, validateWithSchema } from "../core.api";
+import { generateResponse, SupabaseResponse } from "../core.interface";
+import { z } from "zod";
+import { CategoryRepo, Repo } from "./repo.interface";
+
+const REPO_USAGE_FIELD = "details->>usage" as const;
+
+export const getScanRemoteRepoValuesSchema = z.object({
+    usage: z.string().trim().min(1),
+});
+
+export type GetScanRemoteRepoValuesPayload = z.infer<typeof getScanRemoteRepoValuesSchema>;
+
+/**
+ * Scan `Repo.value` keys for `category=repo` with matching `details.usage`.
+ * Returns `{ data: string[] }` on success; validation and DB failures use `{ error }` (never throws).
+ */
+export const getScanRemoteRepoValues = async (
+    payload: GetScanRemoteRepoValuesPayload
+): Promise<SupabaseResponse<string[]>> => {
+    try {
+        return await getScanRemoteRepoValuesValidated(payload);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message) as SupabaseResponse<string[]>;
+    }
+};
+
+const getScanRemoteRepoValuesValidated = validateWithSchema(
+    getScanRemoteRepoValuesSchema,
+    "getScanRemoteRepoValuesSchema"
+)(async ({ usage }): Promise<SupabaseResponse<string[]>> => {
+    try {
+        const { data } = await scanTargetList<Repo>({
+            category: CategoryRepo.REPO,
+            selectFields: "value",
+            orderBy: { field: "value", ascending: true },
+            filterList: [{ field: REPO_USAGE_FIELD, operator: "eq", value: usage }],
+        });
+
+        const values = (data ?? [])
+            .map((row) => row.value?.trim())
+            .filter((value): value is string => value != null && value !== "");
+
+        return generateResponse.success([...new Set(values)]);
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return generateResponse.error(message) as SupabaseResponse<string[]>;
+    }
+});

package/src/repo/repo.interface.ts

@@ -0,0 +1,31 @@
+import { Target } from "../core.interface";
+
+export enum CategoryRepo {
+    /** Project */
+    REPO = "repo",
+}
+
+/** `Repo.details.usage` for task worker remote discovery ({@link registerTasks}). */
+export const TASK_REPO_USAGE = "task";
+
+export interface Repo extends Target {
+    /** Human readable name */
+    name: string;
+    /** Unique key, consumers use this to determine which repo to use */
+    value: string;
+    details: RepoDetails;
+    category: CategoryRepo;
+}
+
+export interface RepoDetails {
+    manifestVersion: number;
+    /**
+     * Business usage partition for discovery and load (caller-defined string, e.g. `"task"`).
+     * Used by {@link getScanRemoteRepoValues} to narrow scan scope; validity is the caller's responsibility.
+     */
+    usage: string;
+    /** Repo entry module URL or filesystem path — used to dynamic-import TaskRepoContext. */
+    url: string;
+    hash: string;
+}
+