create-windy 0.3.4 → 0.3.5

package/template/apps/server/src/data-governance/export/renderer-runtime.ts

@@ -0,0 +1,293 @@
+import type {
+  GovernedExportRenderedArtifact,
+  GovernedExportWatermarkContext,
+  ModuleGovernedExportRendererRegistration,
+} from "@southwind-ai/server-sdk";
+import type { JsonValue } from "@southwind-ai/shared";
+import type { GovernedExportSource } from "./source.js";
+import { createWatermarkedNdjsonStream } from "./ndjson-stream.js";
+import type {
+  GovernedExportRendererSnapshot,
+  GovernedExportRequest,
+} from "./types.js";
+
+export interface GovernedExportRendererBinding {
+  readonly resourceType: string;
+  readonly renderer: ModuleGovernedExportRendererRegistration;
+}
+
+interface RenderContext {
+  readonly request: GovernedExportRequest;
+  readonly source: GovernedExportSource;
+  readonly jobId: string;
+  readonly generatedAt: string;
+  readonly signal: AbortSignal;
+  readonly heartbeat: () => Promise<void>;
+  readonly beforePage: () => Promise<void>;
+  readonly pageCompleted: (completed: number) => Promise<void>;
+}
+
+export interface GovernedExportRenderSession {
+  readonly body: ReadableStream<Uint8Array>;
+  readonly contentMetadata?: Readonly<Record<string, JsonValue>>;
+  assertRecordsConsumed(): void;
+  dispose(): void;
+}
+
+export async function createGovernedExportRenderSession(
+  input: RenderContext,
+  bindings: readonly GovernedExportRendererBinding[],
+): Promise<GovernedExportRenderSession> {
+  const watermark = watermarkOf(input);
+  const binding = bindings.find(
+    ({ resourceType, renderer }) =>
+      resourceType === input.request.resourceType &&
+      renderer.formatKey === input.request.renderer.formatKey,
+  );
+  if (!binding) {
+    if (!isLegacyNdjson(input.request.renderer)) {
+      throw new Error("EXPORT_RENDERER_NOT_REGISTERED");
+    }
+    const body = createWatermarkedNdjsonStream({
+      ...input,
+      watermark,
+      maxRecords: input.request.renderer.maxRecords,
+    });
+    return {
+      body: limitOutput(
+        body,
+        input.request.renderer.maxOutputBytes,
+        input.signal,
+      ),
+      assertRecordsConsumed() {},
+      dispose() {},
+    };
+  }
+  assertRendererSnapshot(binding.renderer, input.request.renderer);
+  const abort = linkedAbort(
+    input.signal,
+    binding.renderer.limits.timeoutSeconds,
+  );
+  const records = governedRecords(
+    input,
+    binding.renderer.limits.maxRecords,
+    abort.signal,
+  );
+  let artifact: GovernedExportRenderedArtifact;
+  let body: ReadableStream<Uint8Array>;
+  try {
+    artifact = await raceAbort(
+      Promise.resolve(
+        binding.renderer.render(
+          { records: records.iterable, watermark },
+          { signal: abort.signal, heartbeat: input.heartbeat },
+        ),
+      ),
+      abort.signal,
+    );
+    validateContentMetadata(artifact.contentMetadata);
+    body = limitOutput(
+      artifact.body,
+      binding.renderer.limits.maxOutputBytes,
+      abort.signal,
+    );
+  } catch (error) {
+    abort.dispose();
+    throw error;
+  }
+  return {
+    body,
+    contentMetadata: artifact.contentMetadata,
+    assertRecordsConsumed() {
+      if (!records.consumed()) throw new Error("EXPORT_RECORDS_NOT_CONSUMED");
+    },
+    dispose: abort.dispose,
+  };
+}
+
+function governedRecords(
+  input: RenderContext,
+  maxRecords: number,
+  signal: AbortSignal,
+) {
+  let completed = 0;
+  let finished = false;
+  async function* stream() {
+    const pageStream = input.source.pages(input.request, signal);
+    const pages = pageStream[Symbol.asyncIterator]();
+    try {
+      while (true) {
+        throwIfAborted(signal);
+        await input.beforePage();
+        const page = await raceAbort(pages.next(), signal);
+        if (page.done) {
+          finished = true;
+          return;
+        }
+        for (const record of page.value) {
+          completed += 1;
+          if (completed > maxRecords) {
+            throw new Error("EXPORT_RECORD_LIMIT_EXCEEDED");
+          }
+          yield record as Readonly<Record<string, JsonValue>>;
+        }
+        await input.pageCompleted(completed);
+      }
+    } finally {
+      await pages.return?.();
+    }
+  }
+  return { iterable: stream(), consumed: () => finished };
+}
+
+function limitOutput(
+  body: ReadableStream<Uint8Array>,
+  maxBytes: number,
+  signal: AbortSignal,
+) {
+  const reader = body.getReader();
+  let bytes = 0;
+  return new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await raceAbort(reader.read(), signal);
+        if (result.done) return controller.close();
+        bytes += result.value.byteLength;
+        if (bytes > maxBytes) throw new Error("EXPORT_OUTPUT_LIMIT_EXCEEDED");
+        controller.enqueue(result.value);
+      } catch (error) {
+        await reader.cancel(error).catch(() => undefined);
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+}
+
+function linkedAbort(parent: AbortSignal, timeoutSeconds: number) {
+  const controller = new AbortController();
+  const onAbort = () => controller.abort(parent.reason ?? "cancelled");
+  parent.addEventListener("abort", onAbort, { once: true });
+  if (parent.aborted) onAbort();
+  const timeout = setTimeout(
+    () => controller.abort("renderer-timeout"),
+    timeoutSeconds * 1_000,
+  );
+  return {
+    signal: controller.signal,
+    dispose() {
+      clearTimeout(timeout);
+      parent.removeEventListener("abort", onAbort);
+    },
+  };
+}
+
+function raceAbort<T>(promise: Promise<T>, signal: AbortSignal): Promise<T> {
+  throwIfAborted(signal);
+  return new Promise<T>((resolve, reject) => {
+    const aborted = () => reject(new Error("EXPORT_RENDERER_ABORTED"));
+    signal.addEventListener("abort", aborted, { once: true });
+    promise.then(
+      (value) => {
+        signal.removeEventListener("abort", aborted);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", aborted);
+        reject(error);
+      },
+    );
+  });
+}
+
+function throwIfAborted(signal: AbortSignal) {
+  if (signal.aborted) throw new Error("EXPORT_RENDERER_ABORTED");
+}
+
+function assertRendererSnapshot(
+  renderer: ModuleGovernedExportRendererRegistration,
+  snapshot: GovernedExportRendererSnapshot,
+) {
+  if (
+    snapshot.formatKey !== renderer.formatKey ||
+    snapshot.templateKey !== renderer.templateKey ||
+    snapshot.templateVersion !== renderer.templateVersion ||
+    snapshot.inputSchemaKey !== renderer.inputSchemaKey ||
+    snapshot.contentType !== renderer.contentType ||
+    snapshot.filenameExtension !== renderer.filenameExtension ||
+    snapshot.maxRecords !== renderer.limits.maxRecords ||
+    snapshot.maxOutputBytes !== renderer.limits.maxOutputBytes ||
+    snapshot.timeoutSeconds !== renderer.limits.timeoutSeconds
+  ) {
+    throw new Error("EXPORT_RENDERER_VERSION_DRIFT");
+  }
+}
+
+function isLegacyNdjson(snapshot: GovernedExportRendererSnapshot) {
+  return (
+    snapshot.formatKey === "ndjson" &&
+    snapshot.templateKey === "system.governed-export.ndjson" &&
+    snapshot.templateVersion === "1" &&
+    snapshot.inputSchemaKey === "system.governed-export.record.v1" &&
+    snapshot.contentType === "application/x-ndjson" &&
+    snapshot.filenameExtension === "ndjson" &&
+    snapshot.maxRecords === 50_000 &&
+    snapshot.maxOutputBytes === 10 * 1024 * 1024 &&
+    snapshot.timeoutSeconds === 900
+  );
+}
+
+function validateContentMetadata(
+  metadata: Readonly<Record<string, JsonValue>> | undefined,
+) {
+  if (
+    metadata &&
+    (!isJsonObject(metadata) || JSON.stringify(metadata).length > 16_000)
+  ) {
+    throw new Error("EXPORT_CONTENT_METADATA_TOO_LARGE");
+  }
+}
+
+function isJsonObject(value: unknown, depth = 0): boolean {
+  if (
+    depth > 8 ||
+    !value ||
+    Array.isArray(value) ||
+    typeof value !== "object"
+  ) {
+    return false;
+  }
+  return Object.entries(value).every(
+    ([key, item]) => key.length <= 160 && isJson(item, depth + 1),
+  );
+}
+
+function isJson(value: unknown, depth: number): boolean {
+  if (depth > 8) return false;
+  if (
+    value === null ||
+    typeof value === "string" ||
+    typeof value === "boolean"
+  ) {
+    return true;
+  }
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) {
+    return (
+      value.length <= 1_000 && value.every((item) => isJson(item, depth + 1))
+    );
+  }
+  return isJsonObject(value, depth);
+}
+
+function watermarkOf(input: RenderContext): GovernedExportWatermarkContext {
+  return {
+    actorId: input.request.requesterId,
+    generatedAt: input.generatedAt,
+    scopeHash: input.request.scopeHash,
+    jobId: input.jobId,
+    requestId: input.request.id,
+  };
+}

package/template/apps/server/src/data-governance/export/renderer-selection.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import {
+  GovernedExportServiceError,
+  legacyNdjsonRenderer,
+  selectRenderer,
+  type CreateGovernedExportInput,
+  type GovernedExportTarget,
+} from "./service-support.js";
+
+const input: CreateGovernedExportInput = {
+  idempotencyKey: "request-1",
+  reason: "生成正式治理报告",
+  query: {},
+};
+const target: GovernedExportTarget = {
+  resourceType: "reports.official",
+  policyKey: "reports.official.fields",
+  policyVersion: "1",
+  fieldKeys: ["content"],
+};
+
+describe("governed export renderer selection", () => {
+  test("未声明 Renderer 的资源保持 NDJSON 兼容", () => {
+    expect(selectRenderer(input, target)).toEqual(legacyNdjsonRenderer);
+    expect(
+      selectRenderer({ ...input, formatKey: "ndjson" }, target),
+    ).toEqual(legacyNdjsonRenderer);
+  });
+
+  test("声明 Renderer 后必须显式选择已注册格式", () => {
+    const configured = {
+      ...target,
+      renderers: [
+        {
+          formatKey: "pdf",
+          templateKey: "reports.official.pdf",
+          templateVersion: "1",
+          inputSchemaKey: "reports.official.input.v1",
+          contentType: "application/pdf",
+          filenameExtension: "pdf",
+          maxRecords: 100,
+          maxOutputBytes: 1_000_000,
+          timeoutSeconds: 60,
+        },
+      ],
+    };
+    expectSelectionError(configured, undefined, "EXPORT_FORMAT_REQUIRED");
+    expectSelectionError(configured, "docx", "EXPORT_FORMAT_NOT_REGISTERED");
+    expect(selectRenderer({ ...input, formatKey: "pdf" }, configured)).toEqual(
+      configured.renderers[0],
+    );
+  });
+});
+
+function expectSelectionError(
+  configured: GovernedExportTarget,
+  formatKey: string | undefined,
+  code: string,
+) {
+  try {
+    selectRenderer({ ...input, formatKey }, configured);
+    throw new Error("应拒绝 Renderer 选择");
+  } catch (error) {
+    expect(error).toBeInstanceOf(GovernedExportServiceError);
+    expect((error as GovernedExportServiceError).code).toBe(code);
+  }
+}

package/template/apps/server/src/data-governance/export/repository.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { InMemoryGovernedExportRepository } from "./repository.js";
+import { legacyGovernedExportRendererSnapshot } from "./types.js";
 
 const now = new Date("2026-07-16T01:00:00.000Z");
 
@@ -25,6 +26,7 @@ describe("governed export repository", () => {
       },
       scopeHash: "a".repeat(64),
       querySnapshot: { includeDeleted: false },
+      renderer: legacyGovernedExportRendererSnapshot,
       approvalRequired: true,
       expiresAt: "2026-07-17T01:00:00.000Z",
     } satisfies Parameters<typeof repository.create>[0];

package/template/apps/server/src/data-governance/export/request-fingerprint.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { fingerprintGovernedExportRequest } from "./request-fingerprint.js";
+import { legacyGovernedExportRendererSnapshot } from "./types.js";
 
 const request = {
   resourceType: "system.user",
@@ -10,6 +11,7 @@ const request = {
   reason: "合规复核用户字段",
   scopeHash: "a".repeat(64),
   querySnapshot: { includeDeleted: false, q: "审计" },
+  renderer: legacyGovernedExportRendererSnapshot,
   approvalRequired: true,
 };
 
@@ -29,6 +31,17 @@ describe("governed export request fingerprint", () => {
         reason: "另一项合规复核用途",
       }),
     ).not.toBe(first);
+    expect(
+      fingerprintGovernedExportRequest({
+        ...request,
+        renderer: {
+          ...legacyGovernedExportRendererSnapshot,
+          formatKey: "pdf",
+          contentType: "application/pdf",
+          filenameExtension: "pdf",
+        },
+      }),
+    ).not.toBe(first);
   });
 
   test("数据库标识和到期时间不参与同一业务请求的摘要", () => {

package/template/apps/server/src/data-governance/export/request-fingerprint.ts

@@ -11,6 +11,7 @@ type FingerprintedRequest = Pick<
   | "reason"
   | "scopeHash"
   | "querySnapshot"
+  | "renderer"
   | "approvalRequired"
 >;
 
@@ -26,6 +27,7 @@ export function fingerprintGovernedExportRequest(
     reason: request.reason,
     scopeHash: request.scopeHash,
     querySnapshot: request.querySnapshot,
+    renderer: request.renderer,
     approvalRequired: request.approvalRequired,
   };
   return createHash("sha256").update(stableJson(payload)).digest("hex");

package/template/apps/server/src/data-governance/export/routes.ts

@@ -112,7 +112,12 @@ async function guarded<T>(
 }
 
 function parseCreate(body: unknown) {
-  const value = strictObject(body, ["idempotencyKey", "reason", "query"]);
+  const value = strictObject(body, [
+    "idempotencyKey",
+    "reason",
+    "query",
+    "formatKey",
+  ]);
   const query = strictObject(value.query || {}, [
     "q",
     "status",
@@ -126,9 +131,11 @@ function parseCreate(body: unknown) {
   ) {
     throw new GovernedExportServiceError("EXPORT_QUERY_INVALID", 400);
   }
+  const formatKey = optionalString(value.formatKey);
   return {
     idempotencyKey: requiredString(value.idempotencyKey),
     reason: requiredString(value.reason),
+    ...(formatKey === undefined ? {} : { formatKey }),
     query: {
       q: optionalString(query.q),
       status: status as LifecycleStatus | undefined,
@@ -200,6 +207,9 @@ function project(request: GovernedExportRequest) {
     expiresAt: request.expiresAt,
     createdAt: request.createdAt,
     updatedAt: request.updatedAt,
+    formatKey: request.renderer.formatKey,
+    templateKey: request.renderer.templateKey,
+    templateVersion: request.renderer.templateVersion,
   };
 }
 

package/template/apps/server/src/data-governance/export/service-support.ts

@@ -2,12 +2,17 @@ import type { GovernedExportQuerySnapshot } from "@southwind-ai/database";
 import type { AuditEvent } from "@southwind-ai/shared";
 import { auditActor, type RequestGuardContext } from "../../guards.js";
 import type { DurableArtifactService } from "../../jobs/artifact-service.js";
-import type { GovernedExportRequest, GovernedExportStatus } from "./types.js";
+import {
+  legacyGovernedExportRendererSnapshot,
+  type GovernedExportRequest,
+  type GovernedExportStatus,
+} from "./types.js";
 
 export interface CreateGovernedExportInput {
   idempotencyKey: string;
   reason: string;
   query: GovernedExportQuerySnapshot;
+  formatKey?: string;
 }
 
 export interface GovernedExportPolicy {
@@ -22,8 +27,25 @@ export interface GovernedExportTarget {
   readonly fieldKeys: readonly string[];
   readonly approvalRequired?: boolean;
   readonly retentionSeconds?: number;
+  readonly renderers?: readonly GovernedExportRendererTarget[];
 }
 
+export interface GovernedExportRendererTarget {
+  readonly formatKey: string;
+  readonly templateKey: string;
+  readonly templateVersion: string;
+  readonly inputSchemaKey: string;
+  readonly contentType: string;
+  readonly filenameExtension: string;
+  readonly maxRecords: number;
+  readonly maxOutputBytes: number;
+  readonly timeoutSeconds: number;
+}
+
+export const legacyNdjsonRenderer: GovernedExportRendererTarget = {
+  ...legacyGovernedExportRendererSnapshot,
+};
+
 export const governedUserTarget: GovernedExportTarget = {
   resourceType: "system.user",
   policyKey: "system.user.fields",
@@ -50,6 +72,29 @@ export function validateCreate(input: CreateGovernedExportInput) {
   }
 }
 
+export function selectRenderer(
+  input: CreateGovernedExportInput,
+  target: GovernedExportTarget,
+): GovernedExportRendererTarget {
+  const renderers = target.renderers;
+  if (!renderers?.length) {
+    if (input.formatKey !== undefined && input.formatKey !== "ndjson") {
+      throw new GovernedExportServiceError("EXPORT_FORMAT_NOT_REGISTERED", 400);
+    }
+    return legacyNdjsonRenderer;
+  }
+  if (!input.formatKey?.trim()) {
+    throw new GovernedExportServiceError("EXPORT_FORMAT_REQUIRED", 400);
+  }
+  const renderer = renderers.find(
+    ({ formatKey }) => formatKey === input.formatKey,
+  );
+  if (!renderer) {
+    throw new GovernedExportServiceError("EXPORT_FORMAT_NOT_REGISTERED", 400);
+  }
+  return renderer;
+}
+
 export function validateTarget(target: GovernedExportTarget) {
   if (
     !target.resourceType.trim() ||
@@ -83,8 +128,14 @@ export function assertArtifactMetadata(
   if (
     artifact.jobId !== request.durableJobId ||
     artifact.ownerId !== request.requesterId ||
-    artifact.contentType !== "application/x-ndjson" ||
+    artifact.contentType !== request.renderer.contentType ||
+    !artifact.filename.endsWith(`.${request.renderer.filenameExtension}`) ||
+    artifact.metadata?.formatKey !== request.renderer.formatKey ||
+    artifact.metadata?.templateKey !== request.renderer.templateKey ||
+    artifact.metadata?.templateVersion !== request.renderer.templateVersion ||
+    artifact.metadata?.inputSchemaKey !== request.renderer.inputSchemaKey ||
     artifact.byteSize < 0 ||
+    artifact.byteSize > request.renderer.maxOutputBytes ||
     !/^[a-f0-9]{64}$/.test(artifact.sha256)
   ) {
     throw new GovernedExportServiceError("EXPORT_ARTIFACT_INVALID", 409);
@@ -113,7 +164,7 @@ export function exportEvent(
 export function downloadEvent(
   context: RequestGuardContext,
   request: GovernedExportRequest,
-  sha256: string,
+  artifact: Awaited<ReturnType<DurableArtifactService["inspect"]>>,
   phase: "intent" | "authorized",
 ) {
   return exportEvent(
@@ -124,7 +175,13 @@ export function downloadEvent(
       phase,
       scopeHash: request.scopeHash,
       jobId: request.durableJobId,
-      sha256,
+      sha256: artifact.sha256,
+      byteSize: artifact.byteSize,
+      filename: artifact.filename,
+      contentType: artifact.contentType,
+      formatKey: request.renderer.formatKey,
+      templateKey: request.renderer.templateKey,
+      templateVersion: request.renderer.templateVersion,
     },
     request.resourceType,
   );

package/template/apps/server/src/data-governance/export/service.ts

@@ -19,6 +19,7 @@ import {
   exportEvent,
   GovernedExportServiceError,
   governedUserTarget,
+  selectRenderer,
   validateCreate,
   validateTarget,
   type CreateGovernedExportInput,
@@ -54,6 +55,7 @@ export class GovernedExportService {
   ) {
     validateCreate(input);
     validateTarget(target);
+    const renderer = selectRenderer(input, target);
     const scope = captureGovernedExportScope(context.actor.scopeContext);
     const id = Bun.randomUUIDv7();
     const retentionSeconds = Math.min(
@@ -76,6 +78,7 @@ export class GovernedExportService {
       scopeSnapshot: scope.snapshot,
       scopeHash: scope.hash,
       querySnapshot: structuredClone(input.query),
+      renderer: structuredClone(renderer),
       approvalRequired: target.approvalRequired ?? this.policy.approvalRequired,
       expiresAt,
     };
@@ -99,6 +102,9 @@ export class GovernedExportService {
           policyVersion: created.request.policyVersion,
           scopeHash: created.request.scopeHash,
           requestFingerprint: created.request.requestFingerprint,
+          formatKey: created.request.renderer.formatKey,
+          templateKey: created.request.renderer.templateKey,
+          templateVersion: created.request.renderer.templateVersion,
           replayed: !created.created,
         },
         created.request.resourceType,
@@ -173,12 +179,12 @@ export class GovernedExportService {
     );
     assertArtifactMetadata(artifact, request);
     await this.audit.recordCriticalEvent(
-      downloadEvent(context, request, artifact.sha256, "intent"),
+      downloadEvent(context, request, artifact, "intent"),
     );
     const opened = await this.artifacts.openInspected(artifact);
     try {
       await this.audit.recordCriticalEvent(
-        downloadEvent(context, request, artifact.sha256, "authorized"),
+        downloadEvent(context, request, artifact, "authorized"),
       );
     } catch (error) {
       await opened.body.cancel().catch(() => undefined);

package/template/apps/server/src/data-governance/export/types.ts

@@ -26,6 +26,7 @@ export interface GovernedExportRequest {
   scopeSnapshot: GovernedExportScopeSnapshot;
   scopeHash: string;
   querySnapshot: GovernedExportQuerySnapshot;
+  renderer: GovernedExportRendererSnapshot;
   status: GovernedExportStatus;
   approvalRequired: boolean;
   approvalId?: string;
@@ -49,7 +50,33 @@ export interface CreateGovernedExportRequest {
   scopeSnapshot: GovernedExportScopeSnapshot;
   scopeHash: string;
   querySnapshot: GovernedExportQuerySnapshot;
+  renderer: GovernedExportRendererSnapshot;
   approvalRequired: boolean;
   approvalId?: string;
   expiresAt: string;
 }
+
+export interface GovernedExportRendererSnapshot {
+  formatKey: string;
+  templateKey: string;
+  templateVersion: string;
+  inputSchemaKey: string;
+  contentType: string;
+  filenameExtension: string;
+  maxRecords: number;
+  maxOutputBytes: number;
+  timeoutSeconds: number;
+}
+
+export const legacyGovernedExportRendererSnapshot: GovernedExportRendererSnapshot =
+  {
+    formatKey: "ndjson",
+    templateKey: "system.governed-export.ndjson",
+    templateVersion: "1",
+    inputSchemaKey: "system.governed-export.record.v1",
+    contentType: "application/x-ndjson",
+    filenameExtension: "ndjson",
+    maxRecords: 50_000,
+    maxOutputBytes: 10 * 1024 * 1024,
+    timeoutSeconds: 900,
+  };

package/template/apps/server/src/index.ts

@@ -307,6 +307,7 @@ installModuleHttpRuntime(moduleHosts, app, {
   features,
   // @windy-module system.scheduler begin
   jobs: durableJobRuntime.service,
+  jobWorker: durableJobRuntime.worker,
   // @windy-module system.scheduler end
   // @windy-module system.storage begin
   storage: storageRuntime,