create-windy 0.1.0

package/template/apps/server/src/scheduler/routes.test.ts

@@ -0,0 +1,347 @@
+import { describe, expect, test } from "bun:test";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { FakeRouteApp } from "../system/route-test-app.js";
+import { createPlatformTaskDefinitions } from "./definitions.js";
+import { InMemorySchedulerRepository } from "./repository.js";
+import { registerSchedulerRoutes } from "./routes.js";
+import { SchedulerService } from "./service.js";
+
+describe("scheduler routes", () => {
+  test("列表和手动触发均通过 Guard 并写入审计", async () => {
+    const fixture = await createFixture();
+    const context = await fixture.context();
+    const tasks = (await fixture.app.invoke("GET", "/system/scheduled-tasks", {
+      guardContext: context,
+      params: {},
+      query: {},
+    })) as unknown[];
+    const overview = (await fixture.app.invoke(
+      "GET",
+      "/system/operations/scheduler",
+      {
+        guardContext: context,
+        params: {},
+        query: {},
+      },
+    )) as { source: string; tasks: Array<{ definition: { source: string } }> };
+    const run = (await fixture.app.invoke(
+      "POST",
+      "/system/scheduled-tasks/:id/trigger",
+      {
+        guardContext: context,
+        params: { id: "system.scheduler.health-snapshot" },
+        query: {},
+      },
+    )) as { status: string };
+
+    expect(tasks).toHaveLength(1);
+    expect(overview).toMatchObject({
+      source: "scheduler",
+      tasks: [{ definition: { source: "code-registered" } }],
+    });
+    expect(run.status).toBe("succeeded");
+    expect(
+      fixture.runtime.auditSink.list().map(({ action }) => action),
+    ).toEqual(["task.read", "task.read", "task.trigger", "task.execute"]);
+  });
+
+  test("Feature 停用时列表和手动触发都返回 403", async () => {
+    const fixture = await createFixture({
+      featureResolver: {
+        resolve: (key) => ({ key, enabled: false, visible: "visible" }),
+      },
+    });
+    const context = await fixture.context();
+    const list = (await fixture.app.invoke("GET", "/system/scheduled-tasks", {
+      guardContext: context,
+      params: {},
+      query: {},
+    })) as Response;
+    const overview = (await fixture.app.invoke(
+      "GET",
+      "/system/operations/scheduler",
+      {
+        guardContext: context,
+        params: {},
+        query: {},
+      },
+    )) as Response;
+    const trigger = (await fixture.app.invoke(
+      "POST",
+      "/system/scheduled-tasks/:id/trigger",
+      {
+        guardContext: context,
+        params: { id: "system.scheduler.health-snapshot" },
+        query: {},
+      },
+    )) as Response;
+
+    expect(list.status).toBe(403);
+    expect(overview.status).toBe(403);
+    expect(trigger.status).toBe(403);
+    await expect(trigger.json()).resolves.toMatchObject({
+      reason: "feature-disabled",
+    });
+    expect(await fixture.scheduler.listRuns()).toHaveLength(0);
+  });
+
+  test("执行历史返回带任务名称的真实分页结果", async () => {
+    const fixture = await createFixture();
+    const context = await fixture.context();
+    for (let index = 0; index < 2; index += 1) {
+      await fixture.app.invoke("POST", "/system/scheduled-tasks/:id/trigger", {
+        guardContext: context,
+        params: { id: "system.scheduler.health-snapshot" },
+        query: {},
+      });
+    }
+
+    const first = (await fixture.app.invoke(
+      "GET",
+      "/system/scheduled-task-runs",
+      {
+        guardContext: context,
+        params: {},
+        query: { page: "1", pageSize: "1" },
+      },
+    )) as {
+      total: number;
+      page: number;
+      pageSize: number;
+      items: Array<{ taskKey: string; taskLabel: string }>;
+    };
+    const second = (await fixture.app.invoke(
+      "GET",
+      "/system/scheduled-task-runs",
+      {
+        guardContext: context,
+        params: {},
+        query: { page: "2", pageSize: "1" },
+      },
+    )) as typeof first;
+
+    expect(first).toMatchObject({ total: 2, page: 1, pageSize: 1 });
+    expect(first.items[0]).toMatchObject({
+      taskKey: "system.scheduler.health-snapshot",
+      taskLabel: "调度器健康快照",
+    });
+    expect(second).toMatchObject({ total: 2, page: 2, pageSize: 1 });
+    expect(second.items).toHaveLength(1);
+  });
+
+  test("手动触发使用关键可靠审计策略", async () => {
+    const writes: Array<{ action: string; policy?: string }> = [];
+    const fixture = await createFixture({
+      auditWriter: {
+        write(event, policy) {
+          writes.push({ action: event.action, policy });
+        },
+      },
+    });
+
+    const response = await fixture.app.invoke(
+      "POST",
+      "/system/scheduled-tasks/:id/trigger",
+      {
+        guardContext: await fixture.context(),
+        params: { id: "system.scheduler.health-snapshot" },
+        query: {},
+      },
+    );
+
+    expect(response).toMatchObject({ status: "succeeded" });
+    expect(writes).toContainEqual({
+      action: "task.trigger",
+      policy: "critical",
+    });
+  });
+
+  test("关键审计不可用时阻断执行且不遗留 running", async () => {
+    let executions = 0;
+    const fixture = await createFixture(
+      {
+        auditWriter: {
+          write(event) {
+            if (event.action === "task.trigger") {
+              throw new Error("审计队列不可用");
+            }
+          },
+        },
+      },
+      async () => {
+        executions += 1;
+      },
+    );
+
+    const response = (await fixture.app.invoke(
+      "POST",
+      "/system/scheduled-tasks/:id/trigger",
+      {
+        guardContext: await fixture.context(),
+        params: { id: "system.scheduler.health-snapshot" },
+        query: {},
+      },
+    )) as Response;
+
+    expect(response.status).toBe(503);
+    expect(executions).toBe(0);
+    expect(await fixture.scheduler.listRuns()).toEqual([
+      expect.objectContaining({
+        status: "blocked",
+        error: "关键审计不可用，手动执行已阻断",
+      }),
+    ]);
+  });
+
+  test("同一任务运行中时手动触发返回 409", async () => {
+    let release: () => void = () => undefined;
+    const barrier = new Promise<void>((resolve) => (release = resolve));
+    const fixture = await createFixture({}, async () => barrier);
+    const context = await fixture.context();
+    const first = fixture.app.invoke(
+      "POST",
+      "/system/scheduled-tasks/:id/trigger",
+      {
+        guardContext: context,
+        params: { id: "system.scheduler.health-snapshot" },
+        query: {},
+      },
+    );
+    await until(async () => (await fixture.scheduler.listRuns()).length === 1);
+    const duplicate = (await fixture.app.invoke(
+      "POST",
+      "/system/scheduled-tasks/:id/trigger",
+      {
+        guardContext: await fixture.context(),
+        params: { id: "system.scheduler.health-snapshot" },
+        query: {},
+      },
+    )) as Response;
+    release();
+    await first;
+
+    expect(duplicate.status).toBe(409);
+    await expect(duplicate.json()).resolves.toMatchObject({
+      error: "TASK_ALREADY_RUNNING",
+    });
+  });
+
+  test("只允许用 expectedStartedAt 和中文理由恢复 stale run", async () => {
+    const fixture = await createFixture();
+    const running = await fixture.repository.claimManual(
+      "system.scheduler.health-snapshot",
+      "crashed_worker",
+      new Date("2020-01-01T00:00:00.000Z"),
+    );
+    if (!running) throw new Error("应创建 stale run");
+    const path = "/system/scheduled-tasks/:id/runs/:runId/recover";
+
+    const invalid = (await fixture.app.invoke("POST", path, {
+      guardContext: await fixture.context(),
+      params: { id: running.taskKey, runId: running.id },
+      query: {},
+      body: { expectedStartedAt: running.startedAt, reason: "太短" },
+    })) as Response;
+    expect(invalid.status).toBe(400);
+
+    const response = (await fixture.app.invoke("POST", path, {
+      guardContext: await fixture.context(),
+      params: { id: running.taskKey, runId: running.id },
+      query: {},
+      body: {
+        expectedStartedAt: running.startedAt,
+        reason: "确认旧进程已经退出，不允许自动重跑",
+      },
+    })) as { recoveryId: string; run: { status: string } };
+    expect(response).toMatchObject({
+      recoveryId: expect.any(String),
+      run: { status: "blocked" },
+    });
+
+    const changed = (await fixture.app.invoke("POST", path, {
+      guardContext: await fixture.context(),
+      params: { id: running.taskKey, runId: running.id },
+      query: {},
+      body: {
+        expectedStartedAt: running.startedAt,
+        reason: "再次确认旧进程已经退出并尝试恢复",
+      },
+    })) as Response;
+    expect(changed.status).toBe(409);
+    await expect(changed.json()).resolves.toMatchObject({
+      error: "STALE_RUN_RECOVERY_CONFLICT",
+      reason: "not-running",
+    });
+  });
+
+  test("未达到 stale 阈值或版本令牌变化时恢复返回 409", async () => {
+    const fixture = await createFixture();
+    const running = await fixture.repository.claimManual(
+      "system.scheduler.health-snapshot",
+      "active_worker",
+      new Date(),
+    );
+    if (!running) throw new Error("应创建 running");
+    const path = "/system/scheduled-tasks/:id/runs/:runId/recover";
+    for (const expectedStartedAt of [
+      running.startedAt,
+      "2020-01-01T00:00:00.000Z",
+    ]) {
+      const response = (await fixture.app.invoke("POST", path, {
+        guardContext: await fixture.context(),
+        params: { id: running.taskKey, runId: running.id },
+        query: {},
+        body: {
+          expectedStartedAt,
+          reason: "确认当前状态后尝试受控人工恢复",
+        },
+      })) as Response;
+      expect(response.status).toBe(409);
+    }
+    expect(await fixture.scheduler.listRuns()).toEqual([
+      expect.objectContaining({ id: running.id, status: "running" }),
+    ]);
+  });
+});
+
+async function createFixture(
+  runtimeOptions: Parameters<typeof createServerRuntime>[1] = {},
+  handler?: () => Promise<void>,
+) {
+  const snapshot = createFoundationSnapshot();
+  const runtime = createServerRuntime(
+    {
+      WINDY_DEV_ADMIN_TOKEN: "token",
+      WINDY_LICENSE_ENTITLEMENTS: "capability.scheduler",
+    },
+    runtimeOptions,
+  );
+  const definitions = createPlatformTaskDefinitions(snapshot.features);
+  if (handler) definitions[0]!.handler = handler;
+  const repository = new InMemorySchedulerRepository();
+  const scheduler = new SchedulerService(repository, definitions, runtime);
+  await scheduler.initialize();
+  const app = new FakeRouteApp();
+  registerSchedulerRoutes(app, scheduler, runtime, snapshot.features);
+  return {
+    app,
+    repository,
+    runtime,
+    scheduler,
+    context: () =>
+      runtime.createGuardContext(
+        new Request("http://localhost/api/system/scheduled-tasks", {
+          headers: { authorization: "Bearer token" },
+        }),
+      ),
+  };
+}
+
+async function until(predicate: () => Promise<boolean>) {
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    if (await predicate()) return;
+    await Bun.sleep(1);
+  }
+  throw new Error("测试等待条件超时");
+}

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

@@ -0,0 +1,222 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  AuditEvent,
+  FeatureFlagDefinition,
+  HttpMethod,
+} from "@windy/shared";
+import type { RequestGuardContext } from "../guards.js";
+import { evaluateRouteGuards, findSystemFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { routeContext } from "../system/route-helpers.js";
+import { parsePagination } from "../pagination.js";
+import type { RouteApp } from "../system/routes.js";
+import type { SchedulerService } from "./service.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export function registerSchedulerRoutes(
+  app: RouteApp,
+  scheduler: SchedulerService,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[],
+) {
+  const feature = findSystemFeature(features, "scheduler");
+
+  app.get("/system/scheduled-tasks", async (rawContext) => {
+    const { guardContext } = routeContext(rawContext);
+    return guardedRead(runtime, guardContext, feature, "scheduled-tasks", () =>
+      scheduler.listTasks(),
+    );
+  });
+
+  app.get("/system/scheduled-task-runs", async (rawContext) => {
+    const { guardContext, query } = routeContext(rawContext);
+    const pagination = parsePagination(query);
+    if (pagination instanceof Response) return pagination;
+    return guardedRead(
+      runtime,
+      guardContext,
+      feature,
+      "scheduled-task-runs",
+      () => scheduler.listRunHistory(pagination.page, pagination.pageSize),
+    );
+  });
+
+  app.get("/system/operations/scheduler", async (rawContext) => {
+    const { guardContext } = routeContext(rawContext);
+    return guardedRead(
+      runtime,
+      guardContext,
+      feature,
+      "operations/scheduler",
+      () => scheduler.operationsSnapshot(),
+    );
+  });
+
+  app.post("/system/scheduled-tasks/:id/trigger", async (rawContext) => {
+    const { guardContext, params } = routeContext(rawContext);
+    const taskKey = params.id;
+    if (!taskKey) {
+      return Response.json({ error: "TASK_NOT_FOUND" }, { status: 404 });
+    }
+    const result = await scheduler.triggerManual(taskKey, guardContext);
+    if (result.ok) return result.run;
+    if (result.reason === "not-found") {
+      return Response.json(
+        { error: "TASK_NOT_FOUND", taskKey },
+        { status: 404 },
+      );
+    }
+    if (result.reason === "busy") {
+      return Response.json(
+        { error: "TASK_ALREADY_RUNNING", taskKey },
+        { status: 409 },
+      );
+    }
+    if (result.reason === "audit-unavailable") {
+      return Response.json(
+        { error: "AUDIT_UNAVAILABLE", taskKey },
+        { status: 503 },
+      );
+    }
+    return Response.json(
+      { error: "FORBIDDEN", reason: result.reason },
+      { status: 403 },
+    );
+  });
+
+  app.post(
+    "/system/scheduled-tasks/:id/runs/:runId/recover",
+    async (rawContext) => {
+      const { guardContext, params, body } = routeContext(rawContext);
+      const taskKey = params.id;
+      const runId = params.runId;
+      if (!taskKey || !runId) {
+        return Response.json({ error: "TASK_RUN_NOT_FOUND" }, { status: 404 });
+      }
+      const input = parseRecoveryBody(body);
+      if (!input.ok) {
+        return Response.json(
+          { error: "INVALID_RECOVERY_REQUEST", reason: input.reason },
+          { status: 400 },
+        );
+      }
+      const result = await scheduler.recoverStaleRun(
+        taskKey,
+        runId,
+        input.expectedStartedAt,
+        input.reason,
+        guardContext,
+      );
+      if (result.ok) return { recoveryId: result.recoveryId, run: result.run };
+      if (result.reason === "not-found") {
+        return Response.json(
+          { error: "TASK_NOT_FOUND", taskKey },
+          { status: 404 },
+        );
+      }
+      if (result.reason === "audit-unavailable") {
+        return Response.json(
+          {
+            error: "AUDIT_UNAVAILABLE",
+            taskKey,
+            runId,
+            recoveryId: result.recoveryId,
+          },
+          { status: 503 },
+        );
+      }
+      if (result.reason === "conflict") {
+        return Response.json(
+          {
+            error: "STALE_RUN_RECOVERY_CONFLICT",
+            reason: result.detail,
+            taskKey,
+            runId,
+            recoveryId: result.recoveryId,
+          },
+          { status: 409 },
+        );
+      }
+      return Response.json(
+        { error: "FORBIDDEN", reason: result.detail },
+        { status: 403 },
+      );
+    },
+  );
+
+  return app;
+}
+
+function parseRecoveryBody(
+  body: unknown,
+):
+  | { ok: true; expectedStartedAt: string; reason: string }
+  | { ok: false; reason: string } {
+  if (!body || typeof body !== "object") {
+    return { ok: false, reason: "请求体不能为空" };
+  }
+  const candidate = body as Record<string, unknown>;
+  if (typeof candidate.expectedStartedAt !== "string") {
+    return { ok: false, reason: "必须提交 expectedStartedAt 版本令牌" };
+  }
+  const startedAt = new Date(candidate.expectedStartedAt);
+  if (!Number.isFinite(startedAt.getTime())) {
+    return { ok: false, reason: "expectedStartedAt 必须是有效时间" };
+  }
+  if (typeof candidate.reason !== "string") {
+    return { ok: false, reason: "必须提交中文恢复理由" };
+  }
+  const length = Array.from(candidate.reason.trim()).length;
+  if (length < 8 || length > 500 || !/\p{Script=Han}/u.test(candidate.reason)) {
+    return { ok: false, reason: "恢复理由须含中文且为 8 至 500 字" };
+  }
+  return {
+    ok: true,
+    expectedStartedAt: startedAt.toISOString(),
+    reason: candidate.reason,
+  };
+}
+
+async function guardedRead<T>(
+  runtime: ServerRuntime,
+  context: RequestGuardContext,
+  feature: FeatureFlagDefinition | undefined,
+  resource: string,
+  read: () => Promise<T>,
+) {
+  const decision = await evaluateRouteGuards(runtime, context, {
+    permission: {
+      method: "GET" as HttpMethod,
+      path: `/api/system/${resource}`,
+      permissionKey: "system.scheduler.read",
+    },
+    feature,
+  });
+  if (!decision.allowed) {
+    return Response.json(
+      { error: "FORBIDDEN", reason: decision.reason },
+      { status: 403 },
+    );
+  }
+  const value = await read();
+  runtime.auditSink.recordEvent(readAudit(context, resource));
+  return value;
+}
+
+function readAudit(context: RequestGuardContext, resource: string): AuditEvent {
+  return {
+    id: randomUUIDv7(),
+    action: "task.read",
+    outcome: "success",
+    actor: {
+      id: context.actor.id,
+      type: context.actor.type === "anonymous" ? "user" : context.actor.type,
+      name: context.actor.name,
+      roleCodes: context.actor.roleCodes,
+    },
+    target: { type: resource },
+    requestId: context.requestId,
+    occurredAt: new Date().toISOString(),
+  };
+}

package/template/apps/server/src/scheduler/sensitive-text.ts

@@ -0,0 +1,20 @@
+const SENSITIVE_ASSIGNMENT =
+  /((?:authorization|cookie|password|private[_ -]?key|api[_ -]?key|(?:access|refresh|session|client)?[_ -]?(?:secret|token)|signature|license(?:body|file|key|payload)?)["']?\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;}]*)/gi;
+
+export function sanitizeSchedulerText(value: string, limit: number) {
+  return value
+    .replace(/\bBearer\s+\S+/gi, "Bearer [REDACTED]")
+    .replace(SENSITIVE_ASSIGNMENT, "$1[REDACTED]")
+    .replace(/\s+/g, " ")
+    .trim()
+    .slice(0, limit);
+}
+
+export function sanitizeRecoveryReason(value: string) {
+  return sanitizeSchedulerText(value, 500);
+}
+
+export function sanitizeExecutionError(error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.slice(0, 1_000) || "任务执行失败";
+}

package/template/apps/server/src/scheduler/service-idle.test.ts

@@ -0,0 +1,73 @@
+import { expect, test } from "bun:test";
+import { entitlementKey } from "@windy/shared";
+import { createFoundationSnapshot } from "../foundation.js";
+import { createServerRuntime } from "../runtime.js";
+import { InMemorySchedulerRepository } from "./repository.js";
+import { SchedulerService } from "./service.js";
+import type { SchedulerClock } from "./types.js";
+
+test("自动轮询没有领取任务时不写历史和审计，人工触发仍完整留痕", async () => {
+  const clock = new MutableClock(new Date("2026-07-10T00:00:00.000Z"));
+  const feature = createFoundationSnapshot().features.find(
+    ({ key }) => key === "system.scheduler",
+  );
+  if (!feature) throw new Error("测试缺少 system.scheduler Feature");
+  const runtime = createServerRuntime({
+    WINDY_DEV_ADMIN_TOKEN: "token",
+    WINDY_LICENSE_ENTITLEMENTS: "capability.scheduler",
+  });
+  const scheduler = new SchedulerService(
+    new InMemorySchedulerRepository(),
+    [
+      {
+        key: "test.task",
+        label: "测试任务",
+        intervalSeconds: 100,
+        maxAttempts: 3,
+        retryDelaySeconds: 10,
+        permissionKey: "system.scheduler.manage",
+        feature: {
+          ...feature,
+          requiredEntitlement: entitlementKey("capability.scheduler"),
+        },
+        handler: () => ({ claimed: false }),
+        isIdleResult: (value) => value?.claimed === false,
+      },
+    ],
+    runtime,
+    clock,
+  );
+  await scheduler.initialize();
+  clock.advance(100);
+
+  expect(await scheduler.tick()).toMatchObject({ scheduled: 1 });
+  expect(await scheduler.listRuns()).toHaveLength(0);
+  expect(runtime.auditSink.list()).toHaveLength(0);
+
+  const context = await runtime.createGuardContext(
+    new Request("http://localhost/api/system/scheduled-tasks/test.task/trigger", {
+      headers: { authorization: "Bearer token" },
+    }),
+  );
+  expect(await scheduler.triggerManual("test.task", context)).toMatchObject({
+    ok: true,
+    run: { status: "succeeded" },
+  });
+  expect(await scheduler.listRuns()).toHaveLength(1);
+  expect(runtime.auditSink.list().map(({ action }) => action)).toEqual([
+    "task.trigger",
+    "task.execute",
+  ]);
+});
+
+class MutableClock implements SchedulerClock {
+  constructor(private current: Date) {}
+
+  now() {
+    return new Date(this.current);
+  }
+
+  advance(seconds: number) {
+    this.current = new Date(this.current.getTime() + seconds * 1_000);
+  }
+}