create-windy 0.1.0

package/template/apps/server/src/jobs/repository.ts

@@ -0,0 +1,141 @@
+import type {
+  DurableJob,
+  DurableJobArtifact,
+  DurableJobAttempt,
+  DurableJobFailure,
+  DurableJobLease,
+  DurableJobProgress,
+  DurableJobRecovery,
+  DurableJobSnapshot,
+  DurableJobStage,
+  SubmitDurableJob,
+  SubmitDurableJobResult,
+} from "./types.js";
+import type { ArtifactRef } from "@windy/storage";
+
+export interface DurableJobRepository {
+  submit(input: SubmitDurableJob, now: Date): Promise<SubmitDurableJobResult>;
+  get(id: string): Promise<DurableJobSnapshot | undefined>;
+  list(requestedBy: string, limit?: number): Promise<DurableJob[]>;
+  putStage(stage: DurableJobStage): Promise<void>;
+  putAttempt(attempt: DurableJobAttempt): Promise<void>;
+  putLease(lease: DurableJobLease): Promise<void>;
+  appendProgress(progress: DurableJobProgress): Promise<void>;
+  putArtifact(artifact: DurableJobArtifact): Promise<void>;
+  listActiveArtifactRefs(now: Date): Promise<ArtifactRef[]>;
+  appendFailure(failure: DurableJobFailure): Promise<void>;
+}
+
+export class InMemoryDurableJobRepository implements DurableJobRepository {
+  protected readonly jobs = new Map<string, DurableJob>();
+  protected readonly stages = new Map<string, DurableJobStage>();
+  protected readonly attempts = new Map<string, DurableJobAttempt>();
+  protected readonly leases = new Map<string, DurableJobLease>();
+  protected readonly progress = new Map<string, DurableJobProgress>();
+  protected readonly artifacts = new Map<string, DurableJobArtifact>();
+  protected readonly failures = new Map<string, DurableJobFailure>();
+  protected readonly recoveries = new Map<string, DurableJobRecovery>();
+
+  async submit(input: SubmitDurableJob, now: Date) {
+    const existing = [...this.jobs.values()].find(
+      (job) =>
+        job.requestedBy === input.requestedBy &&
+        job.handlerKey === input.handlerKey &&
+        job.idempotencyKey === input.idempotencyKey,
+    );
+    if (existing) return { job: cloneJob(existing), created: false };
+    const timestamp = now.toISOString();
+    const job: DurableJob = {
+      id: Bun.randomUUIDv7(),
+      handlerKey: input.handlerKey,
+      queue: input.queue || "default",
+      status: "queued",
+      idempotencyKey: input.idempotencyKey,
+      payload: structuredClone(input.payload),
+      priority: input.priority || 0,
+      requestedBy: input.requestedBy,
+      maxAttempts: input.maxAttempts || 3,
+      timeoutSeconds: input.timeoutSeconds || 900,
+      availableAt: (input.availableAt || now).toISOString(),
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    };
+    this.jobs.set(job.id, job);
+    for (const [ordinal, key] of (input.stageKeys || ["main"]).entries()) {
+      const stage: DurableJobStage = {
+        id: Bun.randomUUIDv7(),
+        jobId: job.id,
+        key,
+        ordinal,
+        status: "pending",
+        currentAttempt: 0,
+        createdAt: timestamp,
+        updatedAt: timestamp,
+      };
+      this.stages.set(stage.id, stage);
+    }
+    return { job: cloneJob(job), created: true };
+  }
+
+  async get(id: string) {
+    const job = this.jobs.get(id);
+    if (!job) return undefined;
+    const byJob = <T extends { jobId: string }>(values: Iterable<T>) =>
+      [...values].filter((item) => item.jobId === id).map(clone);
+    return {
+      job: cloneJob(job),
+      stages: byJob(this.stages.values()).sort((a, b) => a.ordinal - b.ordinal),
+      attempts: byJob(this.attempts.values()),
+      leases: byJob(this.leases.values()),
+      progress: byJob(this.progress.values()).sort(
+        (a, b) => a.sequence - b.sequence,
+      ),
+      artifacts: byJob(this.artifacts.values()),
+      failures: byJob(this.failures.values()),
+      recoveries: byJob(this.recoveries.values()),
+    } satisfies DurableJobSnapshot;
+  }
+
+  async list(requestedBy: string, limit = 50) {
+    return [...this.jobs.values()]
+      .filter((job) => job.requestedBy === requestedBy)
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+      .slice(0, limit)
+      .map(cloneJob);
+  }
+
+  async putStage(stage: DurableJobStage) {
+    this.stages.set(stage.id, clone(stage));
+  }
+  async putAttempt(attempt: DurableJobAttempt) {
+    this.attempts.set(attempt.id, clone(attempt));
+  }
+  async putLease(lease: DurableJobLease) {
+    this.leases.set(lease.id, clone(lease));
+  }
+  async appendProgress(progress: DurableJobProgress) {
+    this.progress.set(progress.id, clone(progress));
+  }
+  async putArtifact(artifact: DurableJobArtifact) {
+    this.artifacts.set(`${artifact.jobId}:${artifact.kind}`, clone(artifact));
+  }
+  async listActiveArtifactRefs(now: Date) {
+    const timestamp = now.toISOString();
+    return [...this.artifacts.values()]
+      .filter(
+        (artifact) => !artifact.expiresAt || artifact.expiresAt > timestamp,
+      )
+      .map((artifact) => artifact.artifactRef);
+  }
+  async appendFailure(failure: DurableJobFailure) {
+    this.failures.set(failure.id, clone(failure));
+  }
+}
+
+function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+function cloneJob(job: DurableJob): DurableJob {
+  return { ...clone(job), payload: structuredClone(job.payload) };
+}

package/template/apps/server/src/jobs/service.test.ts

@@ -0,0 +1,64 @@
+import { describe, expect, test } from "bun:test";
+import { InMemoryDurableJobRepository } from "./repository.js";
+import { DurableJobService } from "./service.js";
+
+const now = new Date("2026-07-16T08:00:00.000Z");
+
+describe("DurableJobService", () => {
+  test("提交创建默认阶段并按 actor、handler 和幂等键复用", async () => {
+    const service = new DurableJobService(
+      new InMemoryDurableJobRepository(),
+      () => now,
+    );
+    const input = {
+      handlerKey: "dictionary.import",
+      idempotencyKey: "request-1",
+      payload: { resource: "gender" },
+      requestedBy: "user_1",
+    };
+
+    const first = await service.submit(input);
+    const duplicate = await service.submit({
+      ...input,
+      payload: { resource: "ignored-on-idempotent-replay" },
+    });
+
+    expect(first.created).toBe(true);
+    expect(duplicate).toEqual({ job: first.job, created: false });
+    expect(await service.get(first.job.id)).toMatchObject({
+      job: { status: "queued", availableAt: now.toISOString() },
+      stages: [{ key: "main", ordinal: 0, status: "pending" }],
+      attempts: [],
+      leases: [],
+      progress: [],
+      artifacts: [],
+      failures: [],
+    });
+  });
+
+  test("多阶段顺序持久化并拒绝重复阶段 key", async () => {
+    const service = new DurableJobService(
+      new InMemoryDurableJobRepository(),
+      () => now,
+    );
+    const submitted = await service.submit({
+      handlerKey: "report.export",
+      idempotencyKey: "report-1",
+      payload: {},
+      requestedBy: "user_1",
+      stageKeys: ["query", "render", "store"],
+    });
+    expect(
+      (await service.get(submitted.job.id))?.stages.map(({ key }) => key),
+    ).toEqual(["query", "render", "store"]);
+    expect(() =>
+      service.submit({
+        handlerKey: "report.export",
+        idempotencyKey: "report-2",
+        payload: {},
+        requestedBy: "user_1",
+        stageKeys: ["query", "query"],
+      }),
+    ).toThrow("任务阶段 key 不能重复");
+  });
+});

package/template/apps/server/src/jobs/service.ts

@@ -0,0 +1,44 @@
+import type { DurableJobRepository } from "./repository.js";
+import type { SubmitDurableJob } from "./types.js";
+
+export class DurableJobService {
+  constructor(
+    private readonly repository: DurableJobRepository,
+    private readonly now: () => Date = () => new Date(),
+  ) {}
+
+  submit(input: SubmitDurableJob) {
+    validateSubmit(input);
+    return this.repository.submit(
+      {
+        ...input,
+        stageKeys: input.stageKeys?.length ? input.stageKeys : ["main"],
+      },
+      this.now(),
+    );
+  }
+
+  get(id: string) {
+    return this.repository.get(id);
+  }
+
+  list(requestedBy: string, limit = 50) {
+    if (!requestedBy.trim()) throw new Error("任务发起人不能为空");
+    return this.repository.list(requestedBy, Math.min(Math.max(limit, 1), 100));
+  }
+}
+
+function validateSubmit(input: SubmitDurableJob) {
+  if (!input.handlerKey.trim()) throw new Error("任务 handlerKey 不能为空");
+  if (!input.idempotencyKey.trim()) throw new Error("任务幂等键不能为空");
+  if (!input.requestedBy.trim()) throw new Error("任务发起人不能为空");
+  if ((input.maxAttempts || 3) < 1) throw new Error("最大尝试次数必须大于 0");
+  if ((input.timeoutSeconds || 900) < 1) throw new Error("任务超时必须大于 0");
+  const stageKeys = input.stageKeys || ["main"];
+  if (!stageKeys.length || stageKeys.some((key) => !key.trim())) {
+    throw new Error("任务阶段 key 不能为空");
+  }
+  if (new Set(stageKeys).size !== stageKeys.length) {
+    throw new Error("任务阶段 key 不能重复");
+  }
+}

package/template/apps/server/src/jobs/types.ts

@@ -0,0 +1,180 @@
+import type { ArtifactRef } from "@windy/storage";
+
+export type DurableJobStatus =
+  | "queued"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "cancelled";
+export type DurableStageStatus =
+  | "pending"
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "cancelled"
+  | "skipped";
+export type DurableAttemptStatus =
+  | "running"
+  | "succeeded"
+  | "failed"
+  | "timed-out"
+  | "cancelled"
+  | "lease-expired";
+export type DurableLeaseStatus = "active" | "released" | "expired";
+
+export interface DurableJob {
+  id: string;
+  handlerKey: string;
+  queue: string;
+  status: DurableJobStatus;
+  idempotencyKey: string;
+  payload: Record<string, unknown>;
+  priority: number;
+  requestedBy: string;
+  maxAttempts: number;
+  timeoutSeconds: number;
+  availableAt: string;
+  cancelRequestedAt?: string;
+  startedAt?: string;
+  finishedAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface DurableJobStage {
+  id: string;
+  jobId: string;
+  key: string;
+  ordinal: number;
+  status: DurableStageStatus;
+  currentAttempt: number;
+  startedAt?: string;
+  finishedAt?: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface DurableJobAttempt {
+  id: string;
+  jobId: string;
+  stageId: string;
+  attemptNumber: number;
+  status: DurableAttemptStatus;
+  handlerKey: string;
+  workerId: string;
+  startedAt: string;
+  timeoutAt: string;
+  finishedAt?: string;
+  createdAt: string;
+}
+
+export interface DurableJobLease {
+  id: string;
+  jobId: string;
+  stageId: string;
+  attemptId: string;
+  workerId: string;
+  tokenHash: string;
+  fencingToken: number;
+  status: DurableLeaseStatus;
+  acquiredAt: string;
+  heartbeatAt: string;
+  expiresAt: string;
+  releasedAt?: string;
+}
+
+export interface DurableJobProgress {
+  id: string;
+  jobId: string;
+  stageId: string;
+  attemptId: string;
+  sequence: number;
+  completedUnits: number;
+  totalUnits?: number;
+  message?: string;
+  metadata?: Record<string, unknown>;
+  recordedAt: string;
+}
+
+export interface DurableJobArtifact {
+  id: string;
+  jobId: string;
+  stageId?: string;
+  kind: string;
+  artifactRef: ArtifactRef;
+  filename: string;
+  contentType: string;
+  byteSize: number;
+  sha256: string;
+  ownerId: string;
+  expiresAt?: string;
+  createdAt: string;
+}
+
+export interface DurableJobFailure {
+  id: string;
+  jobId: string;
+  stageId?: string;
+  attemptId?: string;
+  code: string;
+  message: string;
+  retryable: boolean;
+  details?: Record<string, unknown>;
+  occurredAt: string;
+}
+
+export interface DurableJobRecovery {
+  id: string;
+  jobId: string;
+  fromStatus: DurableJobStatus;
+  requestedBy: string;
+  reason: string;
+  idempotencyKey: string;
+  createdAt: string;
+}
+
+export interface DurableJobSnapshot {
+  job: DurableJob;
+  stages: DurableJobStage[];
+  attempts: DurableJobAttempt[];
+  leases: DurableJobLease[];
+  progress: DurableJobProgress[];
+  artifacts: DurableJobArtifact[];
+  failures: DurableJobFailure[];
+  recoveries: DurableJobRecovery[];
+}
+
+export interface DurableLeaseIdentity {
+  jobId: string;
+  stageId: string;
+  attemptId: string;
+  leaseId: string;
+  leaseToken: string;
+  fencingToken: number;
+  workerId: string;
+}
+
+export interface ClaimedDurableJob extends DurableLeaseIdentity {
+  job: DurableJob;
+  stage: DurableJobStage;
+  workerId: string;
+  leaseExpiresAt: string;
+}
+
+export interface SubmitDurableJob {
+  handlerKey: string;
+  idempotencyKey: string;
+  payload: Record<string, unknown>;
+  requestedBy: string;
+  queue?: string;
+  priority?: number;
+  maxAttempts?: number;
+  timeoutSeconds?: number;
+  availableAt?: Date;
+  stageKeys?: string[];
+}
+
+export interface SubmitDurableJobResult {
+  job: DurableJob;
+  created: boolean;
+}

package/template/apps/server/src/jobs/worker.ts

@@ -0,0 +1,258 @@
+import type {
+  DurableExecutionRepository,
+  LeaseResult,
+  ManualJobRecovery,
+} from "./execution-repository.js";
+import {
+  DurableHandlerError,
+  type DurableHandlerContext,
+  type DurableHandlerRegistry,
+} from "./handler-registry.js";
+import type { ClaimedDurableJob, DurableLeaseIdentity } from "./types.js";
+
+export type DurableRunResult =
+  | { status: "idle" }
+  | {
+      status: "succeeded" | "failed" | "cancelled" | "lease-lost";
+      jobId: string;
+    };
+
+export interface DurableWorkerOptions {
+  leaseDurationMs?: number;
+  retryDelayMs?: number;
+  now?: () => Date;
+}
+
+export class DurableJobWorker {
+  private readonly leaseDurationMs: number;
+  private readonly retryDelayMs: number;
+  private readonly now: () => Date;
+
+  constructor(
+    private readonly repository: DurableExecutionRepository,
+    private readonly handlers: DurableHandlerRegistry,
+    options: DurableWorkerOptions = {},
+  ) {
+    this.leaseDurationMs = options.leaseDurationMs || 30_000;
+    this.retryDelayMs = options.retryDelayMs || 1_000;
+    this.now = options.now || (() => new Date());
+  }
+
+  async runNext(queue: string, workerId: string): Promise<DurableRunResult> {
+    await this.repository.sweepExpired(this.now(), this.retryDelayMs);
+    const claim = await this.repository.claim({
+      queue,
+      workerId,
+      now: this.now(),
+      leaseDurationMs: this.leaseDurationMs,
+    });
+    if (!claim) return { status: "idle" };
+    const handler = this.handlers.get(claim.job.handlerKey);
+    if (!handler) {
+      await this.repository.fail(
+        claim,
+        {
+          code: "HANDLER_NOT_REGISTERED",
+          message: `任务 handler 未注册：${claim.job.handlerKey}`,
+          retryable: false,
+        },
+        this.now(),
+      );
+      return { status: "failed", jobId: claim.jobId };
+    }
+    return this.execute(claim, handler.execute);
+  }
+
+  cancel(jobId: string) {
+    return this.repository.requestCancel(jobId, this.now());
+  }
+
+  recover(input: Omit<ManualJobRecovery, "now">) {
+    if (input.reason.trim().length < 5)
+      throw new Error("人工恢复理由至少 5 个字符");
+    return this.repository.recover({ ...input, now: this.now() });
+  }
+
+  sweepExpired() {
+    return this.repository.sweepExpired(this.now(), this.retryDelayMs);
+  }
+
+  private async execute(
+    claim: ClaimedDurableJob,
+    handler: (
+      payload: Record<string, unknown>,
+      context: DurableHandlerContext,
+    ) => Promise<void>,
+  ): Promise<DurableRunResult> {
+    const abort = new AbortController();
+    const identity = identityOf(claim);
+    let rejectControl: (error: Error) => void = () => undefined;
+    const control = new Promise<never>((_, reject) => {
+      rejectControl = reject;
+    });
+    let heartbeatRunning = false;
+    const heartbeat = async () => {
+      const result = await this.repository.heartbeat(
+        identity,
+        this.now(),
+        this.leaseDurationMs,
+      );
+      assertLease(result, abort);
+    };
+    const interval = setInterval(
+      async () => {
+        if (heartbeatRunning) return;
+        heartbeatRunning = true;
+        try {
+          await heartbeat();
+        } catch (error) {
+          rejectControl(asError(error));
+        } finally {
+          heartbeatRunning = false;
+        }
+      },
+      Math.max(10, Math.floor(this.leaseDurationMs / 3)),
+    );
+    const timeout = setTimeout(() => {
+      abort.abort("timeout");
+      rejectControl(new JobTimeoutError());
+    }, claim.job.timeoutSeconds * 1_000);
+
+    try {
+      await Promise.race([
+        handler(claim.job.payload, {
+          jobId: claim.jobId,
+          stageKey: claim.stage.key,
+          attemptNumber: claim.stage.currentAttempt,
+          signal: abort.signal,
+          heartbeat,
+          progress: async (progress) => {
+            validateProgress(progress.completedUnits, progress.totalUnits);
+            const result = await this.repository.recordProgress(
+              identity,
+              progress.completedUnits,
+              progress.totalUnits,
+              progress.message,
+              progress.metadata,
+              this.now(),
+            );
+            assertLease(result, abort);
+          },
+          publishArtifact: async (artifact) => {
+            const result = await this.repository.publishArtifact(
+              identity,
+              {
+                id: Bun.randomUUIDv7(),
+                jobId: identity.jobId,
+                stageId: identity.stageId,
+                ...artifact,
+                createdAt: this.now().toISOString(),
+              },
+              this.now(),
+            );
+            assertLease(result, abort);
+          },
+        }),
+        control,
+      ]);
+      const result = await this.repository.complete(identity, this.now());
+      if (!result.ok) return { status: "lease-lost", jobId: claim.jobId };
+      return {
+        status: result.cancelRequested ? "cancelled" : "succeeded",
+        jobId: claim.jobId,
+      };
+    } catch (error) {
+      if (error instanceof LeaseLostError) {
+        return { status: "lease-lost", jobId: claim.jobId };
+      }
+      const failure = classifyFailure(error, this.now(), this.retryDelayMs);
+      const result = await this.repository.fail(identity, failure, this.now());
+      if (!result.ok) return { status: "lease-lost", jobId: claim.jobId };
+      return {
+        status: failure.attemptStatus === "cancelled" ? "cancelled" : "failed",
+        jobId: claim.jobId,
+      };
+    } finally {
+      clearInterval(interval);
+      clearTimeout(timeout);
+    }
+  }
+}
+
+class LeaseLostError extends Error {}
+class JobCancelledError extends Error {}
+class JobTimeoutError extends Error {}
+
+function assertLease(result: LeaseResult, abort: AbortController) {
+  if (!result.ok) {
+    abort.abort(result.reason);
+    throw new LeaseLostError(`任务租约失效：${result.reason}`);
+  }
+  if (result.cancelRequested) {
+    abort.abort("cancelled");
+    throw new JobCancelledError("任务已请求取消");
+  }
+}
+
+function classifyFailure(error: unknown, now: Date, retryDelayMs: number) {
+  if (error instanceof JobCancelledError) {
+    return {
+      code: "JOB_CANCELLED",
+      message: "任务已取消",
+      retryable: false,
+      attemptStatus: "cancelled" as const,
+    };
+  }
+  if (error instanceof JobTimeoutError) {
+    return {
+      code: "JOB_TIMEOUT",
+      message: "任务执行超时",
+      retryable: true,
+      retryAt: new Date(now.getTime() + retryDelayMs),
+      attemptStatus: "timed-out" as const,
+    };
+  }
+  if (error instanceof DurableHandlerError) {
+    return {
+      code: error.code,
+      message: error.message,
+      retryable: error.retryable,
+      details: error.details,
+      retryAt: new Date(now.getTime() + retryDelayMs),
+    };
+  }
+  return {
+    code: "HANDLER_FAILED",
+    message: asError(error).message.slice(0, 500),
+    retryable: true,
+    retryAt: new Date(now.getTime() + retryDelayMs),
+  };
+}
+
+function identityOf(claim: ClaimedDurableJob): DurableLeaseIdentity {
+  return {
+    jobId: claim.jobId,
+    stageId: claim.stageId,
+    attemptId: claim.attemptId,
+    leaseId: claim.leaseId,
+    leaseToken: claim.leaseToken,
+    fencingToken: claim.fencingToken,
+    workerId: claim.workerId,
+  };
+}
+
+function validateProgress(completed: number, total: number | undefined) {
+  if (!Number.isSafeInteger(completed) || completed < 0) {
+    throw new Error("任务进度必须是非负整数");
+  }
+  if (
+    total !== undefined &&
+    (!Number.isSafeInteger(total) || total < completed)
+  ) {
+    throw new Error("任务总量必须是不小于已完成量的整数");
+  }
+}
+
+function asError(value: unknown) {
+  return value instanceof Error ? value : new Error(String(value));
+}

package/template/apps/server/src/license/legacy-license-resolver.ts

@@ -0,0 +1,23 @@
+import type { LegacyPrototypeLicenseClaims } from "@windy/shared";
+
+export interface LegacyPrototypeLicenseState {
+  moduleGrantKeys: string[];
+}
+
+/**
+ * 仅用于读取迁移前原型数据；返回值不是 Entitlement，也不能进入正式 Guard。
+ */
+export function resolveLegacyPrototypeLicenseState(
+  claims: LegacyPrototypeLicenseClaims,
+  now = new Date(),
+): LegacyPrototypeLicenseState {
+  const moduleGrantKeys = claims.modules
+    .filter((module) => module.enabled)
+    .filter(
+      (module) =>
+        !module.expiresAt || Date.parse(module.expiresAt) > now.getTime(),
+    )
+    .map((module) => module.module);
+
+  return { moduleGrantKeys: [...new Set(moduleGrantKeys)].sort() };
+}