create-windy 0.1.0

package/template/apps/server/src/scheduler/definitions.ts

@@ -0,0 +1,79 @@
+import { systemModuleManifests } from "@windy/modules";
+import type { FeatureFlagDefinition } from "@windy/shared";
+import type { ScheduledTaskDefinition } from "./types.js";
+
+export interface PlatformTaskHandlers {
+  bulkDataDispatch?: ScheduledTaskDefinition["handler"];
+  bulkDataCleanup?: ScheduledTaskDefinition["handler"];
+  storageCleanup?: ScheduledTaskDefinition["handler"];
+  workflowTimeoutDispatch?: ScheduledTaskDefinition["handler"];
+  governedExportDispatch?: ScheduledTaskDefinition["handler"];
+}
+
+export function createPlatformTaskDefinitions(
+  features: FeatureFlagDefinition[],
+  handlers: PlatformTaskHandlers = {},
+): ScheduledTaskDefinition[] {
+  const handlerByKey = new Map<string, ScheduledTaskDefinition["handler"]>([
+    ["system.scheduler.health-snapshot", () => ({ healthy: true })],
+  ]);
+  if (handlers.bulkDataDispatch)
+    handlerByKey.set("system.bulk-data.dispatch", handlers.bulkDataDispatch);
+  if (handlers.bulkDataCleanup)
+    handlerByKey.set("system.bulk-data.cleanup", handlers.bulkDataCleanup);
+  if (handlers.storageCleanup)
+    handlerByKey.set("system.storage.cleanup", handlers.storageCleanup);
+  if (handlers.workflowTimeoutDispatch)
+    handlerByKey.set(
+      "system.workflow.timeout-dispatch",
+      handlers.workflowTimeoutDispatch,
+    );
+  if (handlers.governedExportDispatch)
+    handlerByKey.set(
+      "system.governed-export.dispatch",
+      handlers.governedExportDispatch,
+    );
+
+  return systemModuleManifests()
+    .flatMap((module) => module.tasks)
+    .flatMap((task) => {
+      const handler = handlerByKey.get(task.key);
+      if (!handler) return [];
+      const feature = features.find(({ key }) => key === task.featureKey);
+      if (!feature) throw new Error(`缺少 ${task.featureKey} Feature 定义`);
+      return [
+        {
+          ...task,
+          feature,
+          handler,
+          isIdleResult:
+            task.key === "system.bulk-data.dispatch" ||
+            task.key === "system.workflow.timeout-dispatch" ||
+            task.key === "system.governed-export.dispatch"
+              ? (value) => value?.claimed === false
+              : undefined,
+        },
+      ];
+    });
+}
+
+export function validateTaskDefinitions(
+  definitions: ScheduledTaskDefinition[],
+) {
+  const keys = new Set<string>();
+  for (const definition of definitions) {
+    if (keys.has(definition.key)) {
+      throw new Error(`重复定时任务 Key：${definition.key}`);
+    }
+    keys.add(definition.key);
+    for (const [label, value] of [
+      ["intervalSeconds", definition.intervalSeconds],
+      ["maxAttempts", definition.maxAttempts],
+      ["retryDelaySeconds", definition.retryDelaySeconds],
+    ] as const) {
+      if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`定时任务 ${definition.key} 的 ${label} 必须为正整数`);
+      }
+    }
+  }
+}

package/template/apps/server/src/scheduler/drizzle-durable-links.ts

@@ -0,0 +1,52 @@
+import { scheduledTaskRuns } from "@windy/database";
+import { and, asc, eq, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { mapRun } from "./drizzle-mappers.js";
+
+export async function getScheduledRun(db: NodePgDatabase, runId: string) {
+  const [row] = await db
+    .select()
+    .from(scheduledTaskRuns)
+    .where(eq(scheduledTaskRuns.id, runId))
+    .limit(1);
+  return row ? mapRun(row) : undefined;
+}
+
+export async function listUnlinkedScheduledRuns(
+  db: NodePgDatabase,
+  limit: number,
+) {
+  const rows = await db
+    .select()
+    .from(scheduledTaskRuns)
+    .where(
+      and(
+        eq(scheduledTaskRuns.status, "running"),
+        sql`${scheduledTaskRuns.durableJobId} is null`,
+      ),
+    )
+    .orderBy(asc(scheduledTaskRuns.startedAt))
+    .limit(limit);
+  return rows.map(mapRun);
+}
+
+export async function linkScheduledRun(
+  db: NodePgDatabase,
+  runId: string,
+  attempt: number,
+  durableJobId: string,
+) {
+  const [row] = await db
+    .update(scheduledTaskRuns)
+    .set({ durableJobId })
+    .where(
+      and(
+        eq(scheduledTaskRuns.id, runId),
+        eq(scheduledTaskRuns.status, "running"),
+        eq(scheduledTaskRuns.attempt, attempt),
+        sql`(${scheduledTaskRuns.durableJobId} is null or ${scheduledTaskRuns.durableJobId} = ${durableJobId})`,
+      ),
+    )
+    .returning({ id: scheduledTaskRuns.id });
+  return Boolean(row);
+}

package/template/apps/server/src/scheduler/drizzle-mappers.ts

@@ -0,0 +1,36 @@
+import { scheduledTaskRuns, scheduledTasks } from "@windy/database";
+import type { ScheduledTaskRun, StoredScheduledTask } from "./types.js";
+
+export function mapTask(
+  row: typeof scheduledTasks.$inferSelect,
+): StoredScheduledTask {
+  return {
+    ...row,
+    description: row.description || undefined,
+    status: row.status as StoredScheduledTask["status"],
+    nextRunAt: row.nextRunAt.toISOString(),
+    lastRunAt: row.lastRunAt?.toISOString(),
+  };
+}
+
+export function mapRun(
+  row: typeof scheduledTaskRuns.$inferSelect,
+): ScheduledTaskRun {
+  return {
+    ...row,
+    trigger: row.trigger as ScheduledTaskRun["trigger"],
+    status: row.status as ScheduledTaskRun["status"],
+    retryOfRunId: row.retryOfRunId || undefined,
+    scheduledFor: row.scheduledFor.toISOString(),
+    startedAt: row.startedAt.toISOString(),
+    finishedAt: row.finishedAt?.toISOString(),
+    nextAttemptAt: row.nextAttemptAt?.toISOString(),
+    error: row.error || undefined,
+    result: row.result || undefined,
+    durableJobId: row.durableJobId || undefined,
+  };
+}
+
+export function addSeconds(date: Date, seconds: number): Date {
+  return new Date(date.getTime() + seconds * 1_000);
+}

package/template/apps/server/src/scheduler/drizzle-repository.integration.test.ts

@@ -0,0 +1,174 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { resolve } from "node:path";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { Pool } from "pg";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createPlatformTaskDefinitions } from "./definitions.js";
+import { DrizzleSchedulerRepository } from "./drizzle-repository.js";
+
+const databaseUrl = process.env.SCHEDULER_TEST_DATABASE_URL;
+const describePostgres = databaseUrl ? describe : describe.skip;
+
+describePostgres("PostgreSQL scheduler repository", () => {
+  let pool: Pool;
+  let repository: DrizzleSchedulerRepository;
+  const baseTime = new Date("2026-07-10T00:00:00.000Z");
+
+  beforeAll(async () => {
+    pool = new Pool({ connectionString: databaseUrl });
+    const db = drizzle(pool);
+    await migrate(db, {
+      migrationsFolder: resolve(
+        import.meta.dir,
+        "../../../../packages/database/drizzle",
+      ),
+      migrationsSchema: "public",
+      migrationsTable: "__ops02_test_migrations",
+    });
+    await pool.query("truncate table scheduled_task_runs, scheduled_tasks");
+    repository = new DrizzleSchedulerRepository(db);
+    await repository.syncDefinitions(
+      createPlatformTaskDefinitions(createFoundationSnapshot().features),
+      baseTime,
+    );
+  });
+
+  afterAll(async () => {
+    await pool?.end();
+  });
+
+  test("并发手动触发只允许一个 running，完成后可再次领取", async () => {
+    const taskKey = "system.scheduler.health-snapshot";
+    const claims = await Promise.all([
+      repository.claimManual(taskKey, "user_1", baseTime),
+      repository.claimManual(taskKey, "user_2", baseTime),
+    ]);
+    expect(claims.filter(Boolean)).toHaveLength(1);
+    const claimed = claims.find(Boolean);
+    if (!claimed) throw new Error("应有一次手动执行领取成功");
+    await repository.complete(claimed.id, {
+      status: "succeeded",
+      finishedAt: baseTime,
+      result: { ok: true },
+    });
+
+    expect(
+      await repository.claimManual(
+        taskKey,
+        "user_3",
+        new Date("2026-07-10T00:00:01.000Z"),
+      ),
+    ).toMatchObject({ trigger: "manual", requestedBy: "user_3" });
+    const running = (await repository.listRuns()).find(
+      ({ status }) => status === "running",
+    );
+    if (running) {
+      await repository.complete(running.id, {
+        status: "succeeded",
+        finishedAt: new Date("2026-07-10T00:00:01.000Z"),
+      });
+    }
+  });
+
+  test("失败重试由持久化到期时间领取且不会重复领取", async () => {
+    const taskKey = "system.scheduler.health-snapshot";
+    const failed = await repository.claimManual(
+      taskKey,
+      "user_retry",
+      baseTime,
+    );
+    if (!failed) throw new Error("应领取待失败执行");
+    await repository.complete(failed.id, {
+      status: "retry-pending",
+      finishedAt: baseTime,
+      nextAttemptAt: new Date("2026-07-10T00:00:10.000Z"),
+      error: "模拟失败",
+    });
+
+    expect(
+      await repository.listRetryable(new Date("2026-07-10T00:00:09.999Z")),
+    ).toHaveLength(0);
+    const retries = await Promise.all([
+      repository.claimRetry(failed.id, new Date("2026-07-10T00:00:10.000Z")),
+      repository.claimRetry(failed.id, new Date("2026-07-10T00:00:10.000Z")),
+    ]);
+    expect(retries.filter(Boolean)).toHaveLength(1);
+    expect(retries.find(Boolean)).toMatchObject({
+      trigger: "retry",
+      attempt: 2,
+    });
+    const retry = retries.find(Boolean);
+    if (retry) {
+      await repository.complete(retry.id, {
+        status: "succeeded",
+        finishedAt: new Date("2026-07-10T00:00:11.000Z"),
+      });
+    }
+  });
+
+  test("stale run 并发恢复只成功一次并释放 running 唯一索引", async () => {
+    const taskKey = "system.scheduler.health-snapshot";
+    const running = await repository.claimManual(
+      taskKey,
+      "crashed_worker",
+      baseTime,
+    );
+    if (!running) throw new Error("应创建崩溃遗留执行");
+    const recovery = {
+      recoveryId: Bun.randomUUIDv7(),
+      runId: running.id,
+      taskKey,
+      expectedStartedAt: running.startedAt,
+      staleBefore: new Date("2026-07-10T00:05:00.000Z"),
+      recoveredAt: new Date("2026-07-10T00:20:00.000Z"),
+      recoveredBy: "ops_user",
+      reason: "确认旧进程已经退出，不允许自动重跑",
+    };
+
+    const results = await Promise.all([
+      repository.recoverStaleRun(recovery),
+      repository.recoverStaleRun({
+        ...recovery,
+        recoveryId: Bun.randomUUIDv7(),
+      }),
+    ]);
+    expect(results.filter(({ ok }) => ok)).toHaveLength(1);
+    expect(results.filter(({ ok }) => !ok)).toHaveLength(1);
+    expect(await repository.listRetryable(recovery.recoveredAt)).toHaveLength(
+      0,
+    );
+
+    const restarted = new DrizzleSchedulerRepository(drizzle(pool));
+    expect(await restarted.listRuns()).toContainEqual(
+      expect.objectContaining({
+        id: running.id,
+        status: "blocked",
+        error: "人工确认恢复：确认旧进程已经退出，不允许自动重跑",
+      }),
+    );
+    const next = await restarted.claimManual(
+      taskKey,
+      "ops_user",
+      new Date("2026-07-10T00:20:01.000Z"),
+    );
+    expect(next).toMatchObject({ status: "running" });
+    if (next) {
+      await restarted.complete(next.id, {
+        status: "succeeded",
+        finishedAt: new Date("2026-07-10T00:20:02.000Z"),
+      });
+    }
+  });
+
+  test("重建 Repository 后定义和执行历史仍可观察", async () => {
+    const restarted = new DrizzleSchedulerRepository(drizzle(pool));
+    expect(await restarted.listTasks()).toEqual([
+      expect.objectContaining({
+        key: "system.scheduler.health-snapshot",
+        status: "active",
+      }),
+    ]);
+    expect((await restarted.listRuns()).length).toBeGreaterThanOrEqual(4);
+  });
+});

package/template/apps/server/src/scheduler/drizzle-repository.ts

@@ -0,0 +1,348 @@
+import { scheduledTaskRuns, scheduledTasks } from "@windy/database";
+import { and, asc, desc, eq, lte, notInArray, sql } from "drizzle-orm";
+import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import { addSeconds, mapRun, mapTask } from "./drizzle-mappers.js";
+import type { SchedulerRepository } from "./repository.js";
+import { staleRecoveryConflict } from "./recovery-conflict.js";
+import type {
+  ScheduledTaskDefinition,
+  StaleRunRecovery,
+  StaleRunRecoveryResult,
+  TaskRunCompletion,
+  TaskRunTrigger,
+} from "./types.js";
+import { recoveryError, recoveryResult } from "./repository.js";
+import {
+  getScheduledRun,
+  linkScheduledRun,
+  listUnlinkedScheduledRuns,
+} from "./drizzle-durable-links.js";
+
+export class DrizzleSchedulerRepository implements SchedulerRepository {
+  constructor(private readonly db: NodePgDatabase) {}
+
+  async syncDefinitions(definitions: ScheduledTaskDefinition[], now: Date) {
+    await this.db.transaction(async (tx) => {
+      await tx.execute(
+        sql`select pg_advisory_xact_lock(hashtext('windy_scheduler_sync'))`,
+      );
+      if (definitions.length) {
+        await tx
+          .update(scheduledTasks)
+          .set({
+            status: "archived",
+            enabled: false,
+            updatedAt: now,
+            updatedBy: "system",
+          })
+          .where(
+            notInArray(
+              scheduledTasks.key,
+              definitions.map(({ key }) => key),
+            ),
+          );
+      }
+      for (const definition of definitions) {
+        await tx
+          .insert(scheduledTasks)
+          .values({
+            key: definition.key,
+            label: definition.label,
+            description: definition.description,
+            featureKey: definition.feature.key,
+            permissionKey: definition.permissionKey,
+            intervalSeconds: definition.intervalSeconds,
+            maxAttempts: definition.maxAttempts,
+            retryDelaySeconds: definition.retryDelaySeconds,
+            nextRunAt: addSeconds(now, definition.intervalSeconds),
+            createdBy: "system",
+            updatedBy: "system",
+          })
+          .onConflictDoUpdate({
+            target: scheduledTasks.key,
+            set: {
+              label: definition.label,
+              description: definition.description,
+              featureKey: definition.feature.key,
+              permissionKey: definition.permissionKey,
+              intervalSeconds: definition.intervalSeconds,
+              maxAttempts: definition.maxAttempts,
+              retryDelaySeconds: definition.retryDelaySeconds,
+              enabled: true,
+              status: "active",
+              updatedAt: now,
+              updatedBy: "system",
+            },
+          });
+      }
+      if (!definitions.length) {
+        await tx.update(scheduledTasks).set({
+          status: "archived",
+          enabled: false,
+          updatedAt: now,
+          updatedBy: "system",
+        });
+      }
+    });
+  }
+
+  async listTasks() {
+    const rows = await this.db
+      .select()
+      .from(scheduledTasks)
+      .orderBy(asc(scheduledTasks.key));
+    return rows.map(mapTask);
+  }
+
+  async listRuns(limit = 100) {
+    const rows = await this.db
+      .select()
+      .from(scheduledTaskRuns)
+      .orderBy(desc(scheduledTaskRuns.startedAt))
+      .limit(limit);
+    return rows.map(mapRun);
+  }
+
+  async getRun(runId: string) {
+    return getScheduledRun(this.db, runId);
+  }
+
+  async listUnlinkedRunning(limit = 100) {
+    return listUnlinkedScheduledRuns(this.db, limit);
+  }
+
+  async listRunsPage(page: number, pageSize: number) {
+    const [rows, [{ count = 0 } = { count: 0 }]] = await Promise.all([
+      this.db
+        .select()
+        .from(scheduledTaskRuns)
+        .orderBy(desc(scheduledTaskRuns.startedAt))
+        .limit(pageSize)
+        .offset((page - 1) * pageSize),
+      this.db
+        .select({ count: sql<number>`count(*)::int` })
+        .from(scheduledTaskRuns),
+    ]);
+    return { items: rows.map(mapRun), total: count, page, pageSize };
+  }
+
+  async listRetryable(now: Date) {
+    const rows = await this.db
+      .select()
+      .from(scheduledTaskRuns)
+      .where(
+        and(
+          eq(scheduledTaskRuns.status, "retry-pending"),
+          lte(scheduledTaskRuns.nextAttemptAt, now),
+        ),
+      )
+      .orderBy(asc(scheduledTaskRuns.nextAttemptAt))
+      .limit(100);
+    return rows.map(mapRun);
+  }
+
+  claimScheduled(taskKey: string, now: Date) {
+    return this.db.transaction(async (tx) => {
+      await lockTask(tx, taskKey);
+      const task = await loadTask(tx, taskKey);
+      if (!claimable(task) || task.nextRunAt > now) return undefined;
+      if (await hasRunning(tx, taskKey)) return undefined;
+      await tx
+        .update(scheduledTasks)
+        .set({
+          nextRunAt: addSeconds(now, task.intervalSeconds),
+          lastRunAt: now,
+          updatedAt: now,
+          updatedBy: "system_scheduler",
+        })
+        .where(eq(scheduledTasks.key, taskKey));
+      return insertRun(tx, taskKey, "scheduled", "system_scheduler", now, {
+        scheduledFor: task.nextRunAt,
+      });
+    });
+  }
+
+  claimManual(taskKey: string, actorId: string, now: Date) {
+    return this.db.transaction(async (tx) => {
+      await lockTask(tx, taskKey);
+      const task = await loadTask(tx, taskKey);
+      if (!claimable(task) || (await hasRunning(tx, taskKey))) return undefined;
+      return insertRun(tx, taskKey, "manual", actorId, now);
+    });
+  }
+
+  claimRetry(runId: string, now: Date) {
+    return this.db.transaction(async (tx) => {
+      const [initial] = await tx
+        .select()
+        .from(scheduledTaskRuns)
+        .where(eq(scheduledTaskRuns.id, runId))
+        .limit(1);
+      if (!initial) return undefined;
+      await lockTask(tx, initial.taskKey);
+      const [previous] = await tx
+        .select()
+        .from(scheduledTaskRuns)
+        .where(eq(scheduledTaskRuns.id, runId))
+        .limit(1);
+      const task = await loadTask(tx, initial.taskKey);
+      if (
+        !previous ||
+        previous.status !== "retry-pending" ||
+        !previous.nextAttemptAt ||
+        previous.nextAttemptAt > now ||
+        !claimable(task) ||
+        (await hasRunning(tx, initial.taskKey))
+      ) {
+        return undefined;
+      }
+      await tx
+        .update(scheduledTaskRuns)
+        .set({ status: "failed" })
+        .where(eq(scheduledTaskRuns.id, runId));
+      return insertRun(
+        tx,
+        initial.taskKey,
+        "retry",
+        previous.requestedBy,
+        now,
+        {
+          attempt: previous.attempt + 1,
+          retryOfRunId: previous.id,
+          scheduledFor: previous.nextAttemptAt,
+        },
+      );
+    });
+  }
+
+  async complete(runId: string, completion: TaskRunCompletion) {
+    const [row] = await this.db
+      .update(scheduledTaskRuns)
+      .set({
+        status: completion.status,
+        finishedAt: completion.finishedAt,
+        nextAttemptAt: completion.nextAttemptAt,
+        error: completion.error,
+        result: completion.result,
+      })
+      .where(
+        and(
+          eq(scheduledTaskRuns.id, runId),
+          eq(scheduledTaskRuns.status, "running"),
+        ),
+      )
+      .returning();
+    if (!row) throw new Error(`任务执行记录不可完成：${runId}`);
+    return mapRun(row);
+  }
+
+  async discardRun(runId: string) {
+    await this.db
+      .delete(scheduledTaskRuns)
+      .where(eq(scheduledTaskRuns.id, runId));
+  }
+
+  async linkDurableJob(runId: string, attempt: number, durableJobId: string) {
+    return linkScheduledRun(this.db, runId, attempt, durableJobId);
+  }
+
+  recoverStaleRun(recovery: StaleRunRecovery): Promise<StaleRunRecoveryResult> {
+    return this.db.transaction(async (tx) => {
+      await lockTask(tx, recovery.taskKey);
+      const [current] = await tx
+        .select()
+        .from(scheduledTaskRuns)
+        .where(eq(scheduledTaskRuns.id, recovery.runId))
+        .limit(1);
+      const conflict = staleRecoveryConflict(current, recovery);
+      if (conflict) return { ok: false, reason: conflict };
+
+      const [row] = await tx
+        .update(scheduledTaskRuns)
+        .set({
+          status: "blocked",
+          finishedAt: recovery.recoveredAt,
+          error: recoveryError(recovery.reason),
+          result: recoveryResult(recovery),
+        })
+        .where(
+          and(
+            eq(scheduledTaskRuns.id, recovery.runId),
+            eq(scheduledTaskRuns.taskKey, recovery.taskKey),
+            eq(scheduledTaskRuns.status, "running"),
+            eq(
+              scheduledTaskRuns.startedAt,
+              new Date(recovery.expectedStartedAt),
+            ),
+            lte(scheduledTaskRuns.startedAt, recovery.staleBefore),
+          ),
+        )
+        .returning();
+      return row
+        ? { ok: true, run: mapRun(row) }
+        : { ok: false, reason: "version-mismatch" };
+    });
+  }
+}
+
+type Transaction = Parameters<Parameters<NodePgDatabase["transaction"]>[0]>[0];
+
+async function lockTask(tx: Transaction, taskKey: string) {
+  await tx.execute(sql`select pg_advisory_xact_lock(hashtext(${taskKey}))`);
+}
+
+async function loadTask(tx: Transaction, taskKey: string) {
+  const [row] = await tx
+    .select()
+    .from(scheduledTasks)
+    .where(eq(scheduledTasks.key, taskKey))
+    .limit(1);
+  return row;
+}
+
+async function hasRunning(tx: Transaction, taskKey: string) {
+  const [row] = await tx
+    .select({ id: scheduledTaskRuns.id })
+    .from(scheduledTaskRuns)
+    .where(
+      and(
+        eq(scheduledTaskRuns.taskKey, taskKey),
+        eq(scheduledTaskRuns.status, "running"),
+      ),
+    )
+    .limit(1);
+  return Boolean(row);
+}
+
+function claimable(task: typeof scheduledTasks.$inferSelect | undefined) {
+  return Boolean(task && task.enabled && task.status === "active");
+}
+
+async function insertRun(
+  tx: Transaction,
+  taskKey: string,
+  trigger: TaskRunTrigger,
+  requestedBy: string,
+  now: Date,
+  options: {
+    attempt?: number;
+    retryOfRunId?: string;
+    scheduledFor?: Date;
+  } = {},
+) {
+  const [row] = await tx
+    .insert(scheduledTaskRuns)
+    .values({
+      id: Bun.randomUUIDv7(),
+      taskKey,
+      trigger,
+      status: "running",
+      attempt: options.attempt ?? 1,
+      requestedBy,
+      retryOfRunId: options.retryOfRunId,
+      scheduledFor: options.scheduledFor || now,
+      startedAt: now,
+    })
+    .returning();
+  return row ? mapRun(row) : undefined;
+}