create-windy 0.1.0

package/template/apps/server/src/system/redis-health.ts

@@ -0,0 +1,230 @@
+import { RedisClient } from "bun";
+import { loadPlatformConfig } from "@windy/config";
+
+export type RedisHealthStatus =
+  | "healthy"
+  | "timeout"
+  | "authentication-failed"
+  | "unavailable"
+  | "not-configured";
+
+export interface RedisCapacityMetrics {
+  connectedClients: number;
+  keyCount: number;
+  usedMemoryBytes: number;
+  maxMemoryBytes: number | null;
+  memoryUsagePercent: number | null;
+}
+
+export interface RedisHealthSnapshot {
+  status: RedisHealthStatus;
+  provider: "Redis";
+  message: string;
+  target?: string;
+  latencyMs?: number;
+  metrics?: RedisCapacityMetrics;
+}
+
+interface RedisCommandClient {
+  connect(): Promise<void>;
+  send(command: string, args: string[]): Promise<unknown>;
+  close(): void;
+}
+
+export interface RedisHealthProbeOptions {
+  url?: string;
+  timeoutMs?: number;
+  createClient?: (url: string, timeoutMs: number) => RedisCommandClient;
+}
+
+export type RedisHealthProbe = () => Promise<RedisHealthSnapshot>;
+
+const DEFAULT_TIMEOUT_MS = 1_500;
+
+export function createRedisHealthProbe(
+  options: RedisHealthProbeOptions = {},
+): RedisHealthProbe {
+  const url = options.url?.trim();
+  const timeoutMs = normalizeTimeout(options.timeoutMs);
+  const createClient = options.createClient ?? createBunRedisClient;
+
+  if (!url) {
+    return async () => ({
+      status: "not-configured",
+      provider: "Redis",
+      message: "未配置平台 Redis 连接。",
+    });
+  }
+
+  return async () => {
+    const startedAt = performance.now();
+    let client: RedisCommandClient | undefined;
+    try {
+      client = createClient(url, timeoutMs);
+      const result = await withinTimeout(readRedisMetrics(client), timeoutMs);
+      return {
+        status: "healthy",
+        provider: "Redis",
+        message: "平台 Redis 连接正常。",
+        target: redactRedisTarget(url),
+        latencyMs: roundMilliseconds(performance.now() - startedAt),
+        metrics: result,
+      };
+    } catch (error) {
+      const status = classifyRedisError(error);
+      return {
+        status,
+        provider: "Redis",
+        message: statusMessage(status),
+        target: redactRedisTarget(url),
+        latencyMs: roundMilliseconds(performance.now() - startedAt),
+      };
+    } finally {
+      try {
+        client?.close();
+      } catch {
+        // Closing a failed probe must not replace the health result.
+      }
+    }
+  };
+}
+
+export function createRedisHealthProbeFromEnv(
+  env: Record<string, string | undefined> = process.env,
+): RedisHealthProbe {
+  const cache = loadPlatformConfig(env).cache;
+  return createRedisHealthProbe({
+    url: cache.redisUrl,
+    timeoutMs: cache.healthTimeoutMs,
+  });
+}
+
+async function readRedisMetrics(
+  client: RedisCommandClient,
+): Promise<RedisCapacityMetrics> {
+  await client.connect();
+  const pong = await client.send("PING", []);
+  if (String(pong).toUpperCase() !== "PONG") {
+    throw new Error("REDIS_UNEXPECTED_PING_RESPONSE");
+  }
+
+  const [memory, clients, keyCount] = await Promise.all([
+    client.send("INFO", ["MEMORY"]),
+    client.send("INFO", ["CLIENTS"]),
+    client.send("DBSIZE", []),
+  ]);
+  const memoryInfo = parseRedisInfo(memory);
+  const clientInfo = parseRedisInfo(clients);
+  const usedMemoryBytes = readMetric(memoryInfo, "used_memory");
+  const configuredMaxMemory = readMetric(memoryInfo, "maxmemory");
+  const maxMemoryBytes = configuredMaxMemory > 0 ? configuredMaxMemory : null;
+
+  return {
+    connectedClients: readMetric(clientInfo, "connected_clients"),
+    keyCount: toNonNegativeNumber(keyCount),
+    usedMemoryBytes,
+    maxMemoryBytes,
+    memoryUsagePercent: maxMemoryBytes
+      ? Math.round((usedMemoryBytes / maxMemoryBytes) * 10_000) / 100
+      : null,
+  };
+}
+
+function createBunRedisClient(url: string, timeoutMs: number) {
+  return new RedisClient(url, {
+    connectionTimeout: timeoutMs,
+    idleTimeout: timeoutMs,
+    autoReconnect: false,
+    maxRetries: 0,
+    enableOfflineQueue: false,
+  });
+}
+
+function parseRedisInfo(value: unknown): Map<string, string> {
+  const info = new Map<string, string>();
+  for (const line of String(value).split("\n")) {
+    const separator = line.indexOf(":");
+    if (separator <= 0 || line.startsWith("#")) continue;
+    info.set(line.slice(0, separator), line.slice(separator + 1).trim());
+  }
+  return info;
+}
+
+function readMetric(info: Map<string, string>, key: string): number {
+  return toNonNegativeNumber(info.get(key));
+}
+
+function toNonNegativeNumber(value: unknown): number {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
+}
+
+function normalizeTimeout(value: number | undefined): number {
+  return Number.isFinite(value) && value && value > 0
+    ? Math.min(10_000, Math.max(50, Math.round(value)))
+    : DEFAULT_TIMEOUT_MS;
+}
+
+async function withinTimeout<T>(promise: Promise<T>, timeoutMs: number) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<never>((_, reject) => {
+    timer = setTimeout(() => reject(new RedisProbeTimeoutError()), timeoutMs);
+  });
+  try {
+    return await Promise.race([promise, timeout]);
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+class RedisProbeTimeoutError extends Error {
+  constructor() {
+    super("REDIS_PROBE_TIMEOUT");
+    this.name = "RedisProbeTimeoutError";
+  }
+}
+
+function classifyRedisError(error: unknown): RedisHealthStatus {
+  if (error instanceof RedisProbeTimeoutError) return "timeout";
+  const message = error instanceof Error ? error.message : String(error);
+  const code = readErrorCode(error);
+  if (
+    /WRONGPASS|NOAUTH|AUTHENTICATION|INVALID USERNAME-PASSWORD/i.test(message)
+  ) {
+    return "authentication-failed";
+  }
+  if (code === "ERR_REDIS_CONNECTION_CLOSED") {
+    return "authentication-failed";
+  }
+  if (/TIMEOUT|TIMED OUT/i.test(message)) return "timeout";
+  return "unavailable";
+}
+
+function readErrorCode(error: unknown): string | undefined {
+  if (!error || typeof error !== "object" || !("code" in error)) {
+    return undefined;
+  }
+  return typeof error.code === "string" ? error.code : undefined;
+}
+
+function statusMessage(status: RedisHealthStatus): string {
+  if (status === "timeout") return "平台 Redis 探活超时。";
+  if (status === "authentication-failed") return "平台 Redis 认证失败。";
+  if (status === "not-configured") return "未配置平台 Redis 连接。";
+  if (status === "healthy") return "平台 Redis 连接正常。";
+  return "平台 Redis 当前不可用。";
+}
+
+function redactRedisTarget(url: string): string {
+  try {
+    const parsed = new URL(url);
+    const database = parsed.pathname.replace(/^\/+/, "");
+    return `${parsed.protocol}//${parsed.host}${database ? `/${database}` : ""}`;
+  } catch {
+    return "已配置（地址格式无效）";
+  }
+}
+
+function roundMilliseconds(value: number): number {
+  return Math.round(value * 100) / 100;
+}

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

@@ -0,0 +1,234 @@
+import { randomUUIDv7 } from "bun";
+import type { LifecycleStatus, PageResult, SortRule } from "@windy/shared";
+import type { RequestActor } from "../guards.js";
+import type { ManagedEntity } from "./entities.js";
+
+export interface EntityListQuery {
+  page?: number;
+  pageSize?: number;
+  q?: string;
+  status?: LifecycleStatus;
+  includeDeleted?: boolean;
+  sort?: SortRule[];
+}
+
+export interface EntityImportResult<T extends ManagedEntity> {
+  created: number;
+  updated: number;
+  skipped: number;
+  items: T[];
+}
+
+export interface EntityBulkUpdate<T extends ManagedEntity> {
+  id: string;
+  input: Partial<T>;
+}
+
+export type MaybePromise<T> = T | Promise<T>;
+
+export interface EntityRepository<T extends ManagedEntity> {
+  list(
+    query?: EntityListQuery,
+    searchFields?: Array<keyof T>,
+  ): MaybePromise<PageResult<T>>;
+  all(
+    query?: EntityListQuery,
+    searchFields?: Array<keyof T>,
+  ): MaybePromise<T[]>;
+  get(id: string): MaybePromise<T | undefined>;
+  create(input: Partial<T>, actor: RequestActor): MaybePromise<T>;
+  update(
+    id: string,
+    input: Partial<T>,
+    actor: RequestActor,
+  ): MaybePromise<T | undefined>;
+  updateMany(
+    updates: Array<EntityBulkUpdate<T>>,
+    actor: RequestActor,
+  ): MaybePromise<T[]>;
+  softDelete(id: string, actor: RequestActor): MaybePromise<T | undefined>;
+  importMany(
+    inputs: Array<Partial<T>>,
+    actor: RequestActor,
+    mode?: "create" | "upsert",
+  ): MaybePromise<EntityImportResult<T>>;
+}
+
+export class InMemoryEntityRepository<
+  T extends ManagedEntity,
+> implements EntityRepository<T> {
+  private readonly items = new Map<string, T>();
+
+  constructor(initialItems: T[] = []) {
+    for (const item of initialItems) {
+      this.items.set(item.id, item);
+    }
+  }
+
+  list(
+    query: EntityListQuery = {},
+    searchFields: Array<keyof T> = [],
+  ): PageResult<T> {
+    const page = Math.max(1, query.page || 1);
+    const pageSize = Math.min(100, Math.max(1, query.pageSize || 20));
+    const normalizedKeyword = query.q?.trim().toLowerCase();
+    const filtered = Array.from(this.items.values()).filter((item) => {
+      if (!query.includeDeleted && item.deletedAt) {
+        return false;
+      }
+      if (query.status && item.status !== query.status) {
+        return false;
+      }
+      return normalizedKeyword
+        ? matchesKeyword(item, searchFields, normalizedKeyword)
+        : true;
+    });
+    const sorted = sortItems(filtered, query.sort);
+    const start = (page - 1) * pageSize;
+
+    return {
+      items: sorted.slice(start, start + pageSize),
+      total: sorted.length,
+      page,
+      pageSize,
+    };
+  }
+
+  all(query: EntityListQuery = {}, searchFields: Array<keyof T> = []): T[] {
+    const normalizedKeyword = query.q?.trim().toLowerCase();
+    const filtered = Array.from(this.items.values()).filter((item) => {
+      if (!query.includeDeleted && item.deletedAt) {
+        return false;
+      }
+      if (query.status && item.status !== query.status) {
+        return false;
+      }
+      return normalizedKeyword
+        ? matchesKeyword(item, searchFields, normalizedKeyword)
+        : true;
+    });
+    return sortItems(filtered, query.sort);
+  }
+
+  get(id: string): T | undefined {
+    const item = this.items.get(id);
+    return item && !item.deletedAt ? item : undefined;
+  }
+
+  create(input: Partial<T>, actor: RequestActor): T {
+    const now = new Date().toISOString();
+    const item = {
+      ...input,
+      id: input.id || randomUUIDv7(),
+      status: input.status || "active",
+      createdAt: now,
+      createdBy: actor.id,
+      updatedAt: now,
+      updatedBy: actor.id,
+    } as T;
+    this.items.set(item.id, item);
+    return item;
+  }
+
+  update(id: string, input: Partial<T>, actor: RequestActor): T | undefined {
+    const current = this.get(id);
+    if (!current) {
+      return undefined;
+    }
+    const updated = {
+      ...current,
+      ...input,
+      id,
+      updatedAt: new Date().toISOString(),
+      updatedBy: actor.id,
+    } as T;
+    this.items.set(id, updated);
+    return updated;
+  }
+
+  updateMany(updates: Array<EntityBulkUpdate<T>>, actor: RequestActor): T[] {
+    const current = updates.map(({ id }) => this.get(id));
+    if (current.some((item) => !item)) {
+      throw new Error("批量更新包含不存在的记录");
+    }
+    return updates.map(({ id, input }) => this.update(id, input, actor) as T);
+  }
+
+  softDelete(id: string, actor: RequestActor): T | undefined {
+    return this.update(
+      id,
+      {
+        status: "archived",
+        deletedAt: new Date().toISOString(),
+        deletedBy: actor.id,
+      } as Partial<T>,
+      actor,
+    );
+  }
+
+  importMany(
+    inputs: Array<Partial<T>>,
+    actor: RequestActor,
+    mode: "create" | "upsert" = "create",
+  ): EntityImportResult<T> {
+    const result: EntityImportResult<T> = {
+      created: 0,
+      updated: 0,
+      skipped: 0,
+      items: [],
+    };
+
+    for (const input of inputs) {
+      if (input.id && this.items.has(input.id)) {
+        if (mode === "upsert") {
+          const updated = this.update(input.id, input, actor);
+          if (updated) {
+            result.updated += 1;
+            result.items.push(updated);
+          }
+        } else {
+          result.skipped += 1;
+        }
+        continue;
+      }
+
+      const created = this.create(input, actor);
+      result.created += 1;
+      result.items.push(created);
+    }
+
+    return result;
+  }
+}
+
+function matchesKeyword<T extends ManagedEntity>(
+  item: T,
+  fields: Array<keyof T>,
+  keyword: string,
+): boolean {
+  return fields.some((field) =>
+    String(item[field] || "")
+      .toLowerCase()
+      .includes(keyword),
+  );
+}
+
+function sortItems<T extends ManagedEntity>(
+  items: T[],
+  sort: SortRule[] | undefined,
+): T[] {
+  const rules = sort?.length
+    ? sort
+    : [{ field: "updatedAt", order: "desc" as const }];
+  return [...items].sort((left, right) => {
+    for (const rule of rules) {
+      const leftValue = String(left[rule.field as keyof T] || "");
+      const rightValue = String(right[rule.field as keyof T] || "");
+      const comparison = leftValue.localeCompare(rightValue);
+      if (comparison !== 0) {
+        return rule.order === "asc" ? comparison : -comparison;
+      }
+    }
+    return 0;
+  });
+}

package/template/apps/server/src/system/resource-access-response.ts

@@ -0,0 +1,47 @@
+import { DataAccessDeniedError } from "../data-access/scoped-resource.js";
+import { forbidden } from "./route-helpers.js";
+import type { RequestActor } from "../guards.js";
+import type { ManagedEntity } from "./entities.js";
+import type { ResourceRouteConfig } from "./route-types.js";
+
+export function resourceConflict(message: string) {
+  return Response.json(
+    { error: "RESOURCE_POLICY_CONFLICT", message },
+    { status: 409 },
+  );
+}
+
+export function importNotSupported() {
+  return Response.json(
+    {
+      error: "IMPORT_NOT_SUPPORTED",
+      message: "身份与角色必须通过受控表单逐项维护",
+    },
+    { status: 405 },
+  );
+}
+
+export async function accessCall<T>(
+  handler: () => T | Promise<T>,
+): Promise<T | Response> {
+  try {
+    return await handler();
+  } catch (error) {
+    if (error instanceof DataAccessDeniedError) {
+      return forbidden("data-scope-denied");
+    }
+    throw error;
+  }
+}
+
+export function readAccessible<T extends ManagedEntity>(
+  config: ResourceRouteConfig<T>,
+  id: string,
+  actor: RequestActor,
+) {
+  return accessCall(() =>
+    config.dataAccess.mode === "request"
+      ? config.dataAccess.access.get(id, actor)
+      : config.repository.get(id),
+  );
+}

package/template/apps/server/src/system/resource-export-route.ts

@@ -0,0 +1,64 @@
+import type { createServerRuntime } from "../runtime.js";
+import type { ManagedEntity } from "./entities.js";
+import {
+  parseListQuery,
+  resourceEvent,
+  routeContext,
+} from "./route-helpers.js";
+import { withPermission } from "./resource-route-support.js";
+import { accessCall } from "./resource-access-response.js";
+import type { ResourceRouteConfig, RouteApp } from "./route-types.js";
+import { projectEntities } from "./response-projection.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export function registerResourceExportRoute<T extends ManagedEntity>(
+  app: RouteApp,
+  config: ResourceRouteConfig<T>,
+  runtime: ServerRuntime,
+) {
+  app.get(`/system/${config.path}/export`, (rawContext) => {
+    const { guardContext, query } = routeContext(rawContext);
+    return withPermission(
+      runtime,
+      guardContext,
+      "GET",
+      config.permissionResource,
+      "read",
+      config.feature,
+      async () => {
+        const listQuery = parseListQuery(query);
+        if (listQuery instanceof Response) return listQuery;
+        const items = await accessCall(() =>
+          config.dataAccess.mode === "request"
+            ? config.dataAccess.access.all(
+                listQuery,
+                config.searchFields,
+                guardContext.actor,
+              )
+            : config.repository.all(listQuery, config.searchFields),
+        );
+        if (items instanceof Response) return items;
+        runtime.auditSink.recordEvent(
+          resourceEvent(guardContext, "data.export", config.path, undefined, {
+            total: items.length,
+          }),
+        );
+        return Response.json(
+          {
+            resource: config.path,
+            exportedAt: new Date().toISOString(),
+            total: items.length,
+            items: projectEntities(config, items),
+          },
+          {
+            headers: {
+              "content-disposition": `attachment; filename="${config.path}.json"`,
+            },
+          },
+        );
+      },
+      "backup-export",
+    );
+  });
+}

package/template/apps/server/src/system/resource-route-support.ts

@@ -0,0 +1,50 @@
+import type { 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 type { ManagedEntity } from "./entities.js";
+import { forbidden } from "./route-helpers.js";
+import type { EntityRepository } from "./repository.js";
+import type { ResourceRouteConfig } from "./route-types.js";
+
+type ServerRuntime = ReturnType<typeof createServerRuntime>;
+
+export function resource<T extends ManagedEntity>(
+  path: string,
+  permissionResource: string,
+  repository: EntityRepository<T>,
+  features: FeatureFlagDefinition[],
+  searchFields: Array<keyof T>,
+  dataAccess: ResourceRouteConfig<T>["dataAccess"],
+): ResourceRouteConfig<T> {
+  return {
+    path,
+    permissionResource,
+    repository,
+    dataAccess,
+    searchFields,
+    feature: findSystemFeature(features, permissionResource),
+  };
+}
+
+export async function withPermission(
+  runtime: ServerRuntime,
+  context: RequestGuardContext,
+  method: HttpMethod,
+  resourceName: string,
+  action: "read" | "manage",
+  feature: FeatureFlagDefinition | undefined,
+  handler: () => unknown,
+  restrictedModeAccess?: "backup-export",
+) {
+  const decision = await evaluateRouteGuards(runtime, context, {
+    permission: {
+      method,
+      path: `/api/system/${resourceName}`,
+      permissionKey: `system.${resourceName}.${action}`,
+    },
+    feature,
+    restrictedModeAccess,
+  });
+  return decision.allowed ? handler() : forbidden(decision.reason);
+}

package/template/apps/server/src/system/response-projection.ts

@@ -0,0 +1,24 @@
+import type { ManagedEntity } from "./entities.js";
+import type { EntityImportResult } from "./repository.js";
+import type { ResourceRouteConfig } from "./route-types.js";
+
+export function projectEntity<T extends ManagedEntity>(
+  config: ResourceRouteConfig<T>,
+  entity: T,
+): T | Record<string, unknown> {
+  return config.projectResponse?.(entity) || entity;
+}
+
+export function projectEntities<T extends ManagedEntity>(
+  config: ResourceRouteConfig<T>,
+  entities: T[],
+): Array<T | Record<string, unknown>> {
+  return entities.map((entity) => projectEntity(config, entity));
+}
+
+export function projectImportResult<T extends ManagedEntity>(
+  config: ResourceRouteConfig<T>,
+  result: EntityImportResult<T>,
+) {
+  return { ...result, items: projectEntities(config, result.items) };
+}