create-windy 0.5.1 → 0.6.0

package/template/apps/server/src/document/output-artifact.test-support.ts

@@ -0,0 +1,350 @@
+import type {
+  ModuleAiJsonValue,
+  ModuleAiOperationReadinessV1,
+  ModuleAiOperationReadyV1,
+} from "@southwind-ai/server-sdk";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import { ExecutionGrantStore } from "../agent/execution-grants.js";
+import { buildScopeContext } from "../data-access/context.js";
+import { createRequestGuardContext, type RequestActor } from "../guards.js";
+import { initializeModuleHosts } from "../module-host.js";
+import { createServerRuntime } from "../runtime.js";
+import { createStorageRuntime } from "../storage/runtime.js";
+import type {
+  DocumentRuntimeOperation,
+  DocumentRuntimePort,
+} from "./contracts.js";
+import { DocumentRuntimeError } from "./contracts.js";
+import { DocumentRunFacade } from "./facade.js";
+import { createDocumentInvocation } from "./facade-invocation.js";
+import {
+  documentManifest,
+  operationKey,
+} from "./output-artifact-manifest.test-support.js";
+import { createDocumentOutputArtifactRuntime } from "./output-artifact-runtime.js";
+import { fakeDocumentRuntimeFingerprint } from "./output-artifact-runtime.test-support.js";
+
+export { documentManifest, operationKey };
+export const referenceSecret = "document-output-test-secret".repeat(2);
+
+export async function createDocumentOutputFixture(
+  inspect: () => ModuleAiOperationReadinessV1 = () => readyProjection(),
+) {
+  const module = documentManifest();
+  let actor = documentActor();
+  let featureEnabled = true;
+  let licenseRestricted = false;
+  const now = () => new Date("2026-07-31T12:00:00.000Z");
+  const runtime = createServerRuntime(
+    {},
+    {
+      featureCatalog: module.features,
+      featureResolver: {
+        resolve: (key) => ({
+          key,
+          enabled: featureEnabled,
+          visible: featureEnabled ? "visible" : "hidden",
+        }),
+      },
+      licenseResolver: {
+        resolve: () => ({
+          status: licenseRestricted ? "invalid" : "valid",
+          restricted: licenseRestricted,
+        }),
+      },
+    },
+  );
+  const output = createDocumentOutputArtifactRuntime({
+    modules: [module],
+    bindings: [{ operationKey, outputKind: "searchable-pdf" }],
+    readiness: { inspect: async () => inspect() },
+    runtime,
+    storage: createStorageRuntime({}, undefined, undefined, now),
+    resolveActor: async () => actor,
+    referenceSecret,
+    ephemeral: true,
+    now,
+  });
+  const hosts = await initializeModuleHosts({
+    modules: [module],
+    installations: [
+      {
+        manifest: module,
+        setup(host) {
+          host.registerAiOperationHandlers([
+            {
+              operationKey,
+              prepareDocument: (options) => ({ options }),
+            },
+          ]);
+        },
+      },
+    ],
+  });
+  const remote = new FakeDocumentRuntime();
+  remote.acceptOutputGrant = async (request, grant) => {
+    const sink = request.outputArtifactSink;
+    if (!sink || !grant) return;
+    await output.host.acceptGrant(sink.scope, sink.grantGeneration, grant);
+  };
+  const facade = new DocumentRunFacade(
+    [module],
+    hosts,
+    runtime,
+    remote,
+    fakeInputArtifacts(),
+    new ExecutionGrantStore(),
+    output.host,
+  );
+  return {
+    module,
+    runtime,
+    output,
+    facade,
+    remote,
+    context: () => documentContext(actor),
+    setActor(value: RequestActor) {
+      actor = value;
+    },
+    setFeatureEnabled(value: boolean) {
+      featureEnabled = value;
+    },
+    setLicenseRestricted(value: boolean) {
+      licenseRestricted = value;
+    },
+  };
+}
+
+export function documentActor(
+  permissionKeys: string[] = ["evidence.document.ocr.execute"],
+  scopeRole = "analyst",
+): RequestActor {
+  return {
+    id: "actor-1",
+    type: "user",
+    name: "分析员",
+    roleCodes: [scopeRole],
+    permissionKeys,
+    scopeContext: buildScopeContext("actor-1", undefined, [
+      {
+        id: scopeRole,
+        code: scopeRole,
+        dataScope: "self",
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+export function documentContext(actor = documentActor()) {
+  return createRequestGuardContext(
+    new Request("http://localhost/api/document/runs"),
+    {
+      resolveActor: () => actor,
+      resolveLicense: () => ({ status: "valid" }),
+    },
+  );
+}
+
+export function documentOutputInvocation(
+  runId: string,
+  options: ModuleAiJsonValue = {},
+) {
+  const definition = documentManifest().aiOperations![0]!;
+  return createDocumentInvocation({
+    runId,
+    operationKey,
+    options,
+    sources: [
+      {
+        value: "rotated:input-artifact",
+        mediaType: "application/pdf",
+        byteSize: 10,
+        sha256: "a".repeat(64),
+      },
+    ],
+    definition,
+    maxUnits: definition.limits.maxUnits!,
+    maxArtifacts: definition.limits.maxArtifacts ?? 1,
+  });
+}
+
+export function readyProjection(
+  changes: {
+    status?: "ready" | "unavailable";
+    validUntil?: string;
+    offerCount?: number;
+  } = {},
+): ModuleAiOperationReadinessV1 {
+  if (changes.status === "unavailable") {
+    return {
+      schemaVersion: 1,
+      operationKey,
+      runtimeKind: "document",
+      observedAt: "2026-07-31T12:00:00.000Z",
+      status: "unavailable",
+      deployment: null,
+      offers: [],
+      unavailableReasons: [
+        { code: "DOWNSTREAM_PROBE_FAILED", retryable: true },
+      ],
+    };
+  }
+  const offer: ModuleAiOperationReadyV1["offers"][number] = {
+    variant: "ocr",
+    capabilities: ["document.ocr", "document.output-artifact.v1"],
+    inputModalities: ["document"],
+    outputModalities: ["document", "text"],
+    limits: {
+      maxDurationSeconds: 30,
+      maxInputBytes: 4_096,
+      maxOutputBytes: 2_048,
+      maxUnits: 20,
+      maxArtifacts: 1,
+      maxConcurrentRuns: 2,
+      maxQueueDepth: 4,
+    },
+  };
+  return {
+    schemaVersion: 1,
+    operationKey,
+    runtimeKind: "document",
+    observedAt: "2026-07-31T12:00:00.000Z",
+    status: "ready",
+    validUntil: changes.validUntil ?? "2026-07-31T12:05:00.000Z",
+    deployment: {
+      key: "document.ocr",
+      identity: "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+      releaseDigest: `sha256:${"a".repeat(64)}`,
+      offersDigest: `sha256:${"b".repeat(64)}`,
+    },
+    offers: Array.from({ length: changes.offerCount ?? 1 }, (_, index) => ({
+      ...offer,
+      variant: `ocr-${index}`,
+    })) as unknown as ModuleAiOperationReadyV1["offers"],
+    unavailableReasons: [],
+  };
+}
+
+export class FakeDocumentRuntime implements DocumentRuntimePort {
+  readonly starts: Array<{
+    request: DocumentRuntimeOperation;
+    idempotencyKey: string;
+    outputArtifactGrant?: string;
+  }> = [];
+  readonly cancels: string[] = [];
+  readonly #idempotentRuns = new Map<
+    string,
+    { fingerprint: string; response: ReturnType<typeof startResponse> }
+  >();
+  useIdempotencyStore = false;
+  executions = 0;
+  startResult?: (request: DocumentRuntimeOperation) => {
+    runId: string;
+    status: string;
+    eventsUrl: string;
+  };
+  beforeStart?: (
+    request: DocumentRuntimeOperation,
+    outputArtifactGrant?: string,
+  ) => Promise<void> | void;
+  beforeGrantAccept?: (
+    request: DocumentRuntimeOperation,
+    outputArtifactGrant?: string,
+  ) => Promise<void> | void;
+  acceptOutputGrant?: (
+    request: DocumentRuntimeOperation,
+    outputArtifactGrant?: string,
+  ) => Promise<void>;
+  beforeCancel?: (runId: string) => Promise<void> | void;
+  cancelResult?: (runId: string) => Response;
+  cancelError?: Error;
+
+  async start(
+    request: DocumentRuntimeOperation,
+    idempotencyKey: string,
+    _signal?: AbortSignal,
+    outputArtifactGrant?: string,
+  ) {
+    this.starts.push({ request, idempotencyKey, outputArtifactGrant });
+    await this.beforeGrantAccept?.(request, outputArtifactGrant);
+    await this.acceptOutputGrant?.(request, outputArtifactGrant);
+    await this.beforeStart?.(request, outputArtifactGrant);
+    if (this.startResult) return this.startResult(request);
+    const fingerprint = fakeDocumentRuntimeFingerprint(request);
+    const existing = this.#idempotentRuns.get(idempotencyKey);
+    if (this.useIdempotencyStore && existing) {
+      if (existing.fingerprint !== fingerprint) {
+        throw new DocumentRuntimeError(
+          "RUN_CONFLICT",
+          "Document 幂等语义冲突",
+          false,
+        );
+      }
+      return existing.response;
+    }
+    if (
+      this.useIdempotencyStore &&
+      request.outputArtifactSink &&
+      !outputArtifactGrant
+    ) {
+      throw new DocumentRuntimeError(
+        "RUN_CONFLICT",
+        "Document Runtime 已丢失执行状态",
+        false,
+      );
+    }
+    this.executions += 1;
+    const response = startResponse(request);
+    if (this.useIdempotencyStore) {
+      this.#idempotentRuns.set(idempotencyKey, { fingerprint, response });
+    }
+    return response;
+  }
+  async events() {
+    return Response.json({ events: [] });
+  }
+  async result() {
+    return Response.json({ status: "completed" });
+  }
+  async cancel(runId: string) {
+    await this.beforeCancel?.(runId);
+    if (this.cancelError) throw this.cancelError;
+    this.cancels.push(runId);
+    return (
+      this.cancelResult?.(runId) ??
+      Response.json({ runId, status: "cancelled" })
+    );
+  }
+  async health() {
+    return Response.json({ status: "ready", capabilities: ["document.ocr"] });
+  }
+
+  loseState() {
+    this.#idempotentRuns.clear();
+  }
+}
+
+function fakeInputArtifacts(): AiArtifactRuntime {
+  return {
+    async rotate(value: string) {
+      const variant = value === "input-artifact-b";
+      return {
+        value: `rotated:${value}`,
+        mediaType: "application/pdf",
+        byteSize: variant ? 20 : 10,
+        sha256: (variant ? "b" : "a").repeat(64),
+        expiresAt: "2026-07-31T12:05:00.000Z",
+      };
+    },
+  } as unknown as AiArtifactRuntime;
+}
+
+function startResponse(request: DocumentRuntimeOperation) {
+  const runId = request.runId ?? "legacy-run";
+  return {
+    runId,
+    status: "accepted",
+    eventsUrl: `/api/document/runs/${runId}/events`,
+  };
+}

package/template/apps/server/src/document/remote-response.ts

@@ -0,0 +1,162 @@
+import {
+  DocumentRuntimeError,
+  type DocumentRuntimeStartResponse,
+} from "./contracts.js";
+
+export const documentResponseLimit = 64 * 1024;
+export const documentStreamLimit = 64 * 1024 * 1024;
+
+export function boundDocumentResponse(
+  response: Response,
+  maxBytes: number,
+): Response {
+  const declared = response.headers.get("content-length");
+  if (declared !== null) {
+    if (!/^(0|[1-9]\d*)$/.test(declared) || Number(declared) > maxBytes) {
+      void response.body?.cancel().catch(() => undefined);
+      throw invalidResponse();
+    }
+  }
+  if (!response.body) return response;
+  const reader = response.body.getReader();
+  let total = 0;
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const next = await reader.read();
+        if (next.done) {
+          controller.close();
+          return;
+        }
+        total += next.value.byteLength;
+        if (total > maxBytes) {
+          void reader.cancel("document-response-limit").catch(() => undefined);
+          controller.error(invalidResponse());
+          return;
+        }
+        controller.enqueue(next.value);
+      } catch (error) {
+        controller.error(error);
+      }
+    },
+    cancel(reason) {
+      return reader.cancel(reason);
+    },
+  });
+  return new Response(body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: response.headers,
+  });
+}
+
+export async function parseDocumentStartResponse(
+  response: Response,
+): Promise<DocumentRuntimeStartResponse> {
+  let value: unknown;
+  try {
+    value = await readBoundedDocumentJson(response, documentResponseLimit);
+  } catch (error) {
+    if (error instanceof DocumentRuntimeError) throw error;
+    throw invalidResponse();
+  }
+  if (!isRecord(value)) throw invalidResponse();
+  const { runId, status, eventsUrl } = value;
+  if (
+    typeof runId !== "string" ||
+    !runId.trim() ||
+    typeof status !== "string" ||
+    !["accepted", "running", "completed", "failed", "cancelled"].includes(
+      status,
+    ) ||
+    typeof eventsUrl !== "string" ||
+    !eventsUrl.startsWith("/")
+  ) {
+    throw invalidResponse();
+  }
+  return { runId, status, eventsUrl };
+}
+
+export async function safeDocumentRemoteError(
+  response: Response,
+): Promise<DocumentRuntimeError> {
+  try {
+    const value = (await readBoundedDocumentJson(
+      response,
+      documentResponseLimit,
+    )) as Record<string, unknown>;
+    return fixedRemoteError(typeof value.code === "string" ? value.code : "");
+  } catch (error) {
+    return error instanceof DocumentRuntimeError ? error : unavailable();
+  }
+}
+
+export async function readBoundedDocumentJson(
+  response: Response,
+  maxBytes: number,
+): Promise<unknown> {
+  const declared = response.headers.get("content-length");
+  const bounded = boundDocumentResponse(response, maxBytes);
+  const bytes = new Uint8Array(await bounded.arrayBuffer());
+  if (declared !== null && Number(declared) !== bytes.byteLength) {
+    throw invalidResponse();
+  }
+  try {
+    return JSON.parse(
+      new TextDecoder("utf-8", { fatal: true }).decode(bytes),
+    ) as unknown;
+  } catch {
+    throw invalidResponse();
+  }
+}
+
+function fixedRemoteError(code: string): DocumentRuntimeError {
+  if (code === "CAPABILITY_UNAVAILABLE") {
+    return new DocumentRuntimeError(
+      code,
+      "Document Runtime 缺少所需能力",
+      true,
+    );
+  }
+  if (code === "RUN_CONFLICT") {
+    return new DocumentRuntimeError(code, "Document 幂等语义冲突", false);
+  }
+  if (code === "FORBIDDEN") {
+    return new DocumentRuntimeError(code, "Document Runtime 拒绝访问", false);
+  }
+  if (code === "BUDGET_EXCEEDED") {
+    return new DocumentRuntimeError(
+      code,
+      "Document Runtime 执行预算超限",
+      false,
+    );
+  }
+  if (code === "INVALID_INPUT") {
+    return new DocumentRuntimeError(
+      code,
+      "Document Runtime 拒绝无效输入",
+      false,
+    );
+  }
+  return unavailable();
+}
+
+export function invalidResponse(): DocumentRuntimeError {
+  return new DocumentRuntimeError(
+    "INVALID_RESPONSE",
+    "Document Runtime 响应无效",
+    false,
+  );
+}
+
+function unavailable(): DocumentRuntimeError {
+  return new DocumentRuntimeError(
+    "RUNTIME_UNAVAILABLE",
+    "Document Runtime 暂不可用",
+    true,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/template/apps/server/src/document/remote-runtime.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, test } from "bun:test";
+import { parseAiRuntimeReadinessV1 } from "@southwind-ai/server-sdk";
 import { DocumentRuntimeError } from "./contracts.js";
-import { RemoteDocumentRuntime } from "./remote-runtime.js";
+import {
+  RemoteDocumentRuntime,
+  unavailableDocumentRuntime,
+} from "./remote-runtime.js";
 
 const request = {
   kind: "document" as const,
@@ -27,6 +31,22 @@ const request = {
 };
 
 describe("Remote Document Runtime", () => {
+  test("未安装 Runtime 也返回公共 V1 unavailable，不伪造 legacy ready", async () => {
+    const response = await unavailableDocumentRuntime.health();
+    const raw = await response.json();
+    const parsed = parseAiRuntimeReadinessV1(raw, "2026-07-31T00:00:00.000Z");
+
+    expect(response.status).toBe(503);
+    expect(parsed.ok).toBe(true);
+    if (!parsed.ok) return;
+    expect(parsed.value).toMatchObject({
+      runtimeKind: "document",
+      configured: false,
+      status: "unavailable",
+      unavailableReasons: [{ code: "RUNTIME_NOT_CONFIGURED", retryable: true }],
+    });
+  });
+
   test("只向受信任 Runtime 发送内部认证、作用域化幂等键和有界契约", async () => {
     const calls: Array<{ input: string; init?: RequestInit }> = [];
     const runtime = new RemoteDocumentRuntime({
@@ -54,6 +74,7 @@ describe("Remote Document Runtime", () => {
       authorization: "Bearer internal-token",
       "idempotency-key": "scoped-key",
     });
+    expect(calls[0]?.init?.redirect).toBe("error");
     expect(JSON.parse(String(calls[0]?.init?.body))).toEqual(request);
   });
 
@@ -74,7 +95,30 @@ describe("Remote Document Runtime", () => {
     );
   });
 
-  test("保留可信的幂等冲突错误码", async () => {
+  test("Output grant 只通过专用 Header，不进入 JSON body", async () => {
+    const calls: RequestInit[] = [];
+    const runtime = new RemoteDocumentRuntime({
+      baseUrl: "http://document.internal:8090",
+      internalToken: "internal-token",
+      fetch: async (_input, init) => {
+        calls.push(init ?? {});
+        return Response.json({
+          runId: "doc-1",
+          status: "accepted",
+          eventsUrl: "/api/document/runs/doc-1/events",
+        });
+      },
+    });
+    const grant = `outgrant_v1_${"a".repeat(43)}`;
+    await runtime.start(request, "scoped-key", undefined, grant);
+    expect(calls[0]?.headers).toMatchObject({
+      "x-ai-output-artifact-grant": grant,
+    });
+    expect(String(calls[0]?.body)).not.toContain(grant);
+  });
+
+  test("错误只保留可信 code 并改写固定文案与 retryability", async () => {
+    const echoedGrant = `outgrant_v1_${"z".repeat(43)}`;
     const runtime = new RemoteDocumentRuntime({
       baseUrl: "http://document.internal:8090",
       internalToken: "internal-token",
@@ -82,8 +126,8 @@ describe("Remote Document Runtime", () => {
         Response.json(
           {
             code: "RUN_CONFLICT",
-            message: "幂等键已用于不同输入",
-            retryable: false,
+            message: echoedGrant,
+            retryable: true,
           },
           { status: 409 },
         ),
@@ -91,6 +135,58 @@ describe("Remote Document Runtime", () => {
 
     await expect(runtime.start(request, "scoped-key")).rejects.toMatchObject({
       code: "RUN_CONFLICT",
+      message: "Document 幂等语义冲突",
+      retryable: false,
+    });
+  });
+
+  test("chunked 响应实际超限时失败关闭且不读取 Runtime 正文", async () => {
+    const runtime = new RemoteDocumentRuntime({
+      baseUrl: "http://document.internal:8090",
+      internalToken: "internal-token",
+      fetch: async () =>
+        new Response(
+          new ReadableStream({
+            start(controller) {
+              controller.enqueue(new Uint8Array(40 * 1_024));
+              controller.enqueue(new Uint8Array(40 * 1_024));
+              controller.close();
+            },
+          }),
+          { status: 409 },
+        ),
+    });
+
+    await expect(runtime.start(request, "scoped-key")).rejects.toMatchObject({
+      code: "INVALID_RESPONSE",
+      message: "Document Runtime 响应无效",
+      retryable: false,
+    });
+  });
+
+  test("307/308 不自动跟随，内部认证与 raw grant 不会跨源转发", async () => {
+    const calls: RequestInit[] = [];
+    const runtime = new RemoteDocumentRuntime({
+      baseUrl: "http://document.internal:8090",
+      internalToken: "internal-token",
+      fetch: async (_input, init) => {
+        calls.push(init ?? {});
+        return new Response(null, {
+          status: 307,
+          headers: { location: "https://evil.example/collect" },
+        });
+      },
+    });
+    const grant = `outgrant_v1_${"a".repeat(43)}`;
+
+    await expect(
+      runtime.start(request, "scoped-key", undefined, grant),
+    ).rejects.toMatchObject({ code: "INVALID_RESPONSE" });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]?.redirect).toBe("error");
+    expect(calls[0]?.headers).toMatchObject({
+      authorization: "Bearer internal-token",
+      "x-ai-output-artifact-grant": grant,
     });
   });
 });