create-windy 0.1.0

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

@@ -0,0 +1,260 @@
+import type {
+  ApiPermissionBinding,
+  AuditActionType,
+  AuditOutcome,
+  FeatureFlagDefinition,
+  ModuleConfigVersion,
+} from "@windy/shared";
+import { evaluateRouteGuards, findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { resourceEvent, routeContext } from "../system/route-helpers.js";
+import type { RouteApp } from "../system/route-types.js";
+import type { ModuleConfigurationService } from "./service.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export function registerModuleConfigurationRoutes(
+  app: Pick<RouteApp, "get" | "post">,
+  service: ModuleConfigurationService,
+  runtime: ServerRuntime,
+  features: FeatureFlagDefinition[],
+): void {
+  const feature = findFeature(features, "system.config");
+
+  app.get("/system/configurations", async (rawContext) => {
+    const context = routeContext(rawContext);
+    const denied = await guard(runtime, context.guardContext, "read", feature);
+    return denied || service.summaries();
+  });
+
+  app.get("/system/configurations/:moduleKey/versions", async (rawContext) => {
+    const context = routeContext(rawContext);
+    const denied = await guard(runtime, context.guardContext, "read", feature);
+    if (denied) return denied;
+    const versions = await service.list(context.params.moduleKey || "");
+    return versions || errorResponse("UNKNOWN_MODULE", "配置模块未注册", 404);
+  });
+
+  app.post("/system/configurations/:moduleKey/versions", async (rawContext) => {
+    const context = routeContext(rawContext);
+    const denied = await guard(
+      runtime,
+      context.guardContext,
+      "manage",
+      feature,
+    );
+    if (denied) return denied;
+    const input = parseCreateBody(context.body);
+    if (input instanceof Response) return input;
+    const moduleKey = context.params.moduleKey || "";
+    const changedPaths = Object.keys(input.values).sort();
+    const intent = await recordIntent(
+      runtime,
+      context.guardContext,
+      "config.update",
+      moduleKey,
+      { phase: "intent", moduleKey, changedPaths },
+    );
+    if (intent) return intent;
+
+    const result = await service.create(
+      moduleKey,
+      input.values,
+      context.guardContext.actor.id,
+      input.reason,
+    );
+    if (!result.ok) return serviceError(result.code, result.message);
+    recordResult(
+      runtime,
+      context.guardContext,
+      "config.update",
+      result.version,
+    );
+    return result.version;
+  });
+
+  app.post(
+    "/system/configurations/:moduleKey/versions/:version/rollback",
+    async (rawContext) => {
+      const context = routeContext(rawContext);
+      const denied = await guard(
+        runtime,
+        context.guardContext,
+        "manage",
+        feature,
+      );
+      if (denied) return denied;
+      const reason = parseRollbackBody(context.body);
+      if (reason instanceof Response) return reason;
+      const moduleKey = context.params.moduleKey || "";
+      const targetVersion = Number(context.params.version);
+      if (!Number.isSafeInteger(targetVersion) || targetVersion < 1) {
+        return errorResponse("INVALID_VERSION", "版本号必须为正整数", 400);
+      }
+      const intent = await recordIntent(
+        runtime,
+        context.guardContext,
+        "config.rollback",
+        moduleKey,
+        { phase: "intent", moduleKey, targetVersion },
+      );
+      if (intent) return intent;
+
+      const result = await service.rollback(
+        moduleKey,
+        targetVersion,
+        context.guardContext.actor.id,
+        reason,
+      );
+      if (!result.ok) return serviceError(result.code, result.message);
+      recordResult(
+        runtime,
+        context.guardContext,
+        "config.rollback",
+        result.version,
+      );
+      return result.version;
+    },
+  );
+}
+
+async function guard(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  action: "read" | "manage",
+  feature: FeatureFlagDefinition | undefined,
+): Promise<Response | undefined> {
+  const decision = await evaluateRouteGuards(runtime, context, {
+    permission: configBinding(action),
+    feature,
+  });
+  return decision.allowed
+    ? undefined
+    : errorResponse("FORBIDDEN", decision.reason, 403);
+}
+
+function configBinding(action: "read" | "manage"): ApiPermissionBinding {
+  return {
+    method: action === "read" ? "GET" : "POST",
+    path: "/api/system/configurations",
+    permissionKey: `system.config.${action}`,
+    featureKey: "system.config",
+  };
+}
+
+async function recordIntent(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  action: AuditActionType,
+  moduleKey: string,
+  metadata: Record<string, unknown>,
+): Promise<Response | undefined> {
+  try {
+    await runtime.auditSink.recordCriticalEvent(
+      resourceEvent(
+        context,
+        action,
+        "module-configuration",
+        moduleKey,
+        metadata,
+      ),
+    );
+    return undefined;
+  } catch {
+    return errorResponse(
+      "AUDIT_UNAVAILABLE",
+      "关键审计不可用，配置未变更",
+      503,
+    );
+  }
+}
+
+function recordResult(
+  runtime: ServerRuntime,
+  context: ReturnType<typeof routeContext>["guardContext"],
+  action: AuditActionType,
+  version: ModuleConfigVersion,
+): void {
+  const outcome: AuditOutcome =
+    version.applyStatus === "effective" ? "success" : "failure";
+  runtime.auditSink.recordEvent({
+    ...resourceEvent(
+      context,
+      action,
+      "module-configuration",
+      version.moduleKey,
+      {
+        phase: "result",
+        moduleKey: version.moduleKey,
+        version: version.version,
+        status: version.applyStatus,
+        changedPaths: version.diff.map((entry) => entry.path),
+        rollbackOfVersion: version.rollbackOfVersion,
+      },
+    ),
+    outcome,
+  });
+}
+
+function parseCreateBody(
+  body: unknown,
+): { values: Record<string, unknown>; reason?: string } | Response {
+  if (!isRecord(body) || !hasOnlyKeys(body, ["values", "reason"])) {
+    return errorResponse("INVALID_BODY", "请求体格式无效", 400);
+  }
+  if (!isRecord(body.values)) {
+    return errorResponse("INVALID_VALUES", "values 必须是对象", 400);
+  }
+  const reason = optionalReason(body.reason);
+  if (reason instanceof Response) return reason;
+  return { values: body.values, reason };
+}
+
+function parseRollbackBody(body: unknown): string | Response {
+  if (!isRecord(body) || !hasOnlyKeys(body, ["reason"])) {
+    return errorResponse("INVALID_BODY", "请求体格式无效", 400);
+  }
+  if (typeof body.reason !== "string") {
+    return errorResponse("INVALID_REASON", "回滚原因不能为空", 400);
+  }
+  const reason = body.reason.trim();
+  return reason.length >= 8 && reason.length <= 500
+    ? reason
+    : errorResponse(
+        "INVALID_REASON",
+        "回滚原因长度必须为 8 到 500 个字符",
+        400,
+      );
+}
+
+function optionalReason(value: unknown): string | undefined | Response {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") {
+    return errorResponse("INVALID_REASON", "变更原因必须是字符串", 400);
+  }
+  const reason = value.trim();
+  if (reason.length > 500) {
+    return errorResponse("INVALID_REASON", "变更原因不能超过 500 个字符", 400);
+  }
+  return reason || undefined;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOnlyKeys(value: Record<string, unknown>, keys: string[]): boolean {
+  return Object.keys(value).every((key) => keys.includes(key));
+}
+
+function serviceError(code: string, message: string): Response {
+  return errorResponse(code, message, code === "VERSION_NOT_FOUND" ? 404 : 400);
+}
+
+function errorResponse(
+  error: string,
+  message: string,
+  status: number,
+): Response {
+  return Response.json({ error, message }, { status });
+}

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

@@ -0,0 +1,128 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import type { ManagedModuleConfigDefinition } from "./definition.js";
+import { InMemoryModuleConfigVersionRepository } from "./repository.js";
+import { ModuleConfigurationService } from "./service.js";
+
+describe("模块配置版本服务", () => {
+  test("应用配置并将旧生效版本标记为已替代", async () => {
+    const fixture = createFixture();
+
+    const first = await fixture.service.create(
+      "test.runtime",
+      { enabled: true, timeoutMs: 500 },
+      "user-1",
+    );
+    const second = await fixture.service.create(
+      "test.runtime",
+      { enabled: false, timeoutMs: 800 },
+      "user-1",
+    );
+
+    expect(first.ok && first.version.applyStatus).toBe("effective");
+    expect(second.ok && second.version.version).toBe(2);
+    expect(fixture.current).toEqual({ enabled: false, timeoutMs: 800 });
+    expect(
+      (await fixture.service.list("test.runtime"))?.map(
+        (item) => item.applyStatus,
+      ),
+    ).toEqual(["effective", "superseded"]);
+  });
+
+  test("回滚复制历史值并创建新版本", async () => {
+    const fixture = createFixture();
+    await fixture.service.create(
+      "test.runtime",
+      { enabled: true, timeoutMs: 500 },
+      "user-1",
+    );
+    await fixture.service.create(
+      "test.runtime",
+      { enabled: false, timeoutMs: 800 },
+      "user-1",
+    );
+
+    const rolledBack = await fixture.service.rollback(
+      "test.runtime",
+      1,
+      "user-2",
+      "恢复已经验证的稳定配置",
+    );
+
+    expect(rolledBack).toMatchObject({
+      ok: true,
+      version: {
+        version: 3,
+        rollbackOfVersion: 1,
+        values: { enabled: true, timeoutMs: 500 },
+        applyStatus: "effective",
+      },
+    });
+    expect(fixture.current).toEqual({ enabled: true, timeoutMs: 500 });
+  });
+
+  test("应用异常保存稳定错误且不会泄露 Secret", async () => {
+    const fixture = createFixture(true);
+
+    const result = await fixture.service.create(
+      "test.runtime",
+      { enabled: true, timeoutMs: 500 },
+      "user-1",
+    );
+    const serialized = JSON.stringify(result);
+
+    expect(result).toMatchObject({
+      ok: true,
+      version: {
+        applyStatus: "failed",
+        applyError: "模块配置应用失败，请查看受控服务日志",
+      },
+    });
+    expect(serialized).not.toContain("secret-value-marker");
+    expect(serialized).not.toContain("SecretRef");
+  });
+});
+
+function createFixture(failApply = false) {
+  const current = { enabled: false, timeoutMs: 300 };
+  const schema = z.strictObject({
+    enabled: z.boolean(),
+    timeoutMs: z.number().int().min(50).max(10_000),
+  });
+  const definition: ManagedModuleConfigDefinition = {
+    moduleKey: "test.runtime",
+    label: "测试配置",
+    fields: [
+      {
+        path: "enabled",
+        label: "启用",
+        description: "测试布尔配置",
+        input: "boolean",
+      },
+      {
+        path: "timeoutMs",
+        label: "超时",
+        description: "测试整数配置",
+        input: "integer",
+      },
+    ],
+    validate(values) {
+      return schema.parse(values);
+    },
+    apply(values) {
+      if (failApply) throw new Error("token=secret-value-marker");
+      current.enabled = values.enabled as boolean;
+      current.timeoutMs = values.timeoutMs as number;
+    },
+    baseValues() {
+      return { ...current };
+    },
+  };
+  return {
+    current,
+    service: new ModuleConfigurationService(
+      new InMemoryModuleConfigVersionRepository(),
+      [definition],
+    ),
+  };
+}

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

@@ -0,0 +1,187 @@
+import type {
+  ModuleConfigDiffEntry,
+  ModuleConfigSummary,
+  ModuleConfigValues,
+  ModuleConfigVersion,
+} from "@windy/shared";
+import { ZodError } from "zod";
+import type { ManagedModuleConfigDefinition } from "./definition.js";
+import type { ModuleConfigVersionRepository } from "./repository.js";
+
+export type ConfigVersionResult =
+  | { ok: true; version: ModuleConfigVersion }
+  | {
+      ok: false;
+      code: "UNKNOWN_MODULE" | "INVALID_VALUES" | "VERSION_NOT_FOUND";
+      message: string;
+    };
+
+export class ModuleConfigurationService {
+  private readonly definitions = new Map<
+    string,
+    ManagedModuleConfigDefinition
+  >();
+
+  constructor(
+    private readonly repository: ModuleConfigVersionRepository,
+    definitions: ManagedModuleConfigDefinition[],
+  ) {
+    for (const definition of definitions) {
+      if (this.definitions.has(definition.moduleKey)) {
+        throw new Error(`动态配置模块重复注册：${definition.moduleKey}`);
+      }
+      this.definitions.set(definition.moduleKey, definition);
+    }
+  }
+
+  async initialize(): Promise<void> {
+    for (const definition of this.definitions.values()) {
+      const effective = await this.repository.effective(definition.moduleKey);
+      if (!effective) continue;
+      try {
+        const values = definition.validate(effective.values);
+        await definition.apply(values);
+      } catch (error) {
+        await this.repository.markFailed(
+          effective.id,
+          sanitizeApplyError(error),
+          new Date(),
+        );
+      }
+    }
+  }
+
+  async summaries(): Promise<ModuleConfigSummary[]> {
+    return Promise.all(
+      [...this.definitions.values()].map(async (definition) => {
+        const [effective, latest] = await Promise.all([
+          this.repository.effective(definition.moduleKey),
+          this.repository.latest(definition.moduleKey),
+        ]);
+        return {
+          moduleKey: definition.moduleKey,
+          label: definition.label,
+          fields: definition.fields.map((field) => ({ ...field })),
+          effectiveValues: {
+            ...(effective?.values || definition.baseValues()),
+          },
+          effectiveSource: effective ? "version" : "environment",
+          effectiveVersion: effective?.version,
+          latestVersion: latest?.version,
+          latestStatus: latest?.applyStatus,
+          latestApplyError: latest?.applyError,
+        };
+      }),
+    );
+  }
+
+  async list(moduleKey: string): Promise<ModuleConfigVersion[] | undefined> {
+    if (!this.definitions.has(moduleKey)) return undefined;
+    return this.repository.list(moduleKey);
+  }
+
+  async create(
+    moduleKey: string,
+    values: unknown,
+    actorId: string,
+    reason?: string,
+  ): Promise<ConfigVersionResult> {
+    const definition = this.definitions.get(moduleKey);
+    if (!definition) return unknownModule();
+    let parsed: ModuleConfigValues;
+    try {
+      parsed = definition.validate(values);
+    } catch (error) {
+      return invalidValues(error);
+    }
+    return this.applyVersion(definition, parsed, actorId, reason);
+  }
+
+  async rollback(
+    moduleKey: string,
+    targetVersion: number,
+    actorId: string,
+    reason: string,
+  ): Promise<ConfigVersionResult> {
+    const definition = this.definitions.get(moduleKey);
+    if (!definition) return unknownModule();
+    const target = await this.repository.find(moduleKey, targetVersion);
+    if (!target) {
+      return {
+        ok: false,
+        code: "VERSION_NOT_FOUND",
+        message: "目标配置版本不存在",
+      };
+    }
+    return this.applyVersion(
+      definition,
+      definition.validate(target.values),
+      actorId,
+      reason,
+      target.version,
+    );
+  }
+
+  private async applyVersion(
+    definition: ManagedModuleConfigDefinition,
+    values: ModuleConfigValues,
+    actorId: string,
+    reason?: string,
+    rollbackOfVersion?: number,
+  ): Promise<ConfigVersionResult> {
+    const effective = await this.repository.effective(definition.moduleKey);
+    const before = effective?.values || definition.baseValues();
+    const version = await this.repository.begin({
+      moduleKey: definition.moduleKey,
+      values,
+      diff: configDiff(before, values),
+      rollbackOfVersion,
+      reason,
+      actorId,
+    });
+    try {
+      await definition.apply(values);
+      return {
+        ok: true,
+        version: await this.repository.markEffective(version.id, new Date()),
+      };
+    } catch (error) {
+      return {
+        ok: true,
+        version: await this.repository.markFailed(
+          version.id,
+          sanitizeApplyError(error),
+          new Date(),
+        ),
+      };
+    }
+  }
+}
+
+export function configDiff(
+  before: ModuleConfigValues,
+  after: ModuleConfigValues,
+): ModuleConfigDiffEntry[] {
+  return [...new Set([...Object.keys(before), ...Object.keys(after)])]
+    .sort()
+    .filter((path) => before[path] !== after[path])
+    .map((path) => ({ path, before: before[path], after: after[path] }));
+}
+
+function sanitizeApplyError(error: unknown): string {
+  if (error instanceof ZodError) return "配置值不符合模块 schema";
+  return "模块配置应用失败，请查看受控服务日志";
+}
+
+function unknownModule(): ConfigVersionResult {
+  return { ok: false, code: "UNKNOWN_MODULE", message: "配置模块未注册" };
+}
+
+function invalidValues(error: unknown): ConfigVersionResult {
+  return {
+    ok: false,
+    code: "INVALID_VALUES",
+    message:
+      error instanceof ZodError ? "配置值不符合模块 schema" : "配置值无效",
+  };
+}