create-windy 0.5.2 → 0.6.1

package/template/apps/server/src/speech/facade-output.test.ts

@@ -0,0 +1,299 @@
+import { describe, expect, test } from "bun:test";
+import type { RequestGuardContext } from "../guards.js";
+import type { SpeechRuntimePort } from "./contracts.js";
+import {
+  cancelSpeechRun,
+  rollbackSpeechOutput,
+  speechResultResponse,
+} from "./facade-output.js";
+import type {
+  SpeechOutputArtifactHost,
+  SpeechOutputArtifactStart,
+} from "./output-artifact-host.js";
+
+describe("Speech facade Output Artifact lifecycle", () => {
+  test("remote start 失败回滚 pending grant 并撤销 open scope", async () => {
+    const calls: string[] = [];
+    const host = {
+      rollbackPendingGrant: async () => {
+        calls.push("rollback");
+        return "rolled-back" as const;
+      },
+      abortOpenRun: async () => {
+        calls.push("abort-open");
+        return true;
+      },
+    } as unknown as SpeechOutputArtifactHost;
+
+    await rollbackSpeechOutput(host, outputStart());
+    expect(calls).toEqual(["rollback", "abort-open"]);
+  });
+
+  test("补偿清理连续失败会有界重试并返回 retryable unavailable", async () => {
+    let attempts = 0;
+    const host = {
+      rollbackPendingGrant: async () => {
+        attempts += 1;
+        throw new Error("storage down");
+      },
+    } as unknown as SpeechOutputArtifactHost;
+
+    await expect(
+      rollbackSpeechOutput(host, outputStart()),
+    ).rejects.toMatchObject({
+      code: "CAPABILITY_UNAVAILABLE",
+      retryable: true,
+    });
+    expect(attempts).toBe(3);
+  });
+
+  test("grant 已 active 时 rollback false 仍继续 abort open scope", async () => {
+    const calls: string[] = [];
+    const host = {
+      rollbackPendingGrant: async () => {
+        calls.push("rollback-not-pending");
+        return false;
+      },
+      abortOpenRun: async () => {
+        calls.push("abort-active");
+        return true;
+      },
+    } as unknown as SpeechOutputArtifactHost;
+
+    await rollbackSpeechOutput(host, outputStart());
+    expect(calls).toEqual(["rollback-not-pending", "abort-active"]);
+  });
+
+  test("cancelled 终态确认 open scope 清理", async () => {
+    const calls: string[] = [];
+    const host = {
+      abortOpenRun: async (runId: string) => {
+        calls.push(runId);
+        return true;
+      },
+    } as unknown as SpeechOutputArtifactHost;
+    const response = await cancelSpeechRun({
+      remote: remote({
+        cancel: async (runId) => Response.json({ runId, status: "cancelled" }),
+      }),
+      host,
+      runId: "speech-run",
+      signal: new AbortController().signal,
+      outputBound: true,
+    });
+
+    expect(await response.json()).toEqual({
+      runId: "speech-run",
+      status: "cancelled",
+    });
+    expect(calls).toEqual(["speech-run"]);
+  });
+
+  test("cancel 非 2xx 的非 JSON、超限与截断响应都会先 abort scope", async () => {
+    const aborted: string[] = [];
+    const host = {
+      abortOpenRun: async (runId: string) => {
+        aborted.push(runId);
+        return true;
+      },
+    } as unknown as SpeechOutputArtifactHost;
+    const responses = [
+      new Response("not-json", {
+        status: 503,
+        headers: { "content-type": "text/plain" },
+      }),
+      streamedResponse("x".repeat(65 * 1024), 503),
+      new Response(stream(JSON.stringify({ code: "failed" })), {
+        status: 503,
+        headers: {
+          "content-type": "application/json",
+          "content-length": "999",
+        },
+      }),
+    ];
+    for (const response of responses) {
+      await expect(
+        cancelSpeechRun({
+          remote: remote({ cancel: async () => response }),
+          host,
+          runId: "speech-run",
+          signal: new AbortController().signal,
+          outputBound: true,
+        }),
+      ).rejects.toMatchObject({ status: 503 });
+    }
+    expect(aborted).toEqual(["speech-run", "speech-run", "speech-run"]);
+  });
+
+  test("result 丢弃 Runtime 伪造引用，只返回 Host sealed claim", async () => {
+    const host = {
+      claimSealed: async () => [
+        {
+          contractVersion: 1,
+          outputKey: "normalized-audio",
+          value: "host-sealed-reference",
+          mediaType: "audio/wav",
+          byteSize: 48,
+          sha256: "a".repeat(64),
+          expiresAt: "2026-08-06T12:15:00.000Z",
+        },
+      ],
+    } as unknown as SpeechOutputArtifactHost;
+    const response = await speechResultResponse({
+      remote: remote({
+        result: async () =>
+          Response.json({
+            runId: "speech-run",
+            status: "completed",
+            output: {
+              durationMs: 100,
+              artifacts: [{ value: "runtime-forged-reference" }],
+            },
+          }),
+      }),
+      host,
+      runId: "speech-run",
+      context: context(),
+      signal: new AbortController().signal,
+      outputBound: true,
+      maxInlineOutputBytes: 32 * 1024 * 1024,
+    });
+    const body = await response.json();
+    expect(body.output.artifacts[0].value).toBe("host-sealed-reference");
+    expect(JSON.stringify(body)).not.toContain("runtime-forged-reference");
+  });
+
+  test("result 接受 Operation 上限内且超过旧 64KiB 的有界 JSON", async () => {
+    const text = "语".repeat(128 * 1024);
+    const response = await speechResultResponse({
+      remote: remote({
+        result: async () =>
+          Response.json({
+            runId: "speech-run",
+            status: "completed",
+            output: { text },
+          }),
+      }),
+      runId: "speech-run",
+      context: context(),
+      signal: new AbortController().signal,
+      outputBound: false,
+      maxInlineOutputBytes: 32 * 1024 * 1024,
+    });
+
+    expect((await response.json()).output.text).toBe(text);
+  });
+
+  test("result 无 Content-Length 时仍在流读取阶段执行硬上限", async () => {
+    const body = new TextEncoder().encode(
+      JSON.stringify({
+        runId: "speech-run",
+        status: "completed",
+        output: { text: "x".repeat(128 * 1024) },
+      }),
+    );
+    await expect(
+      speechResultResponse({
+        remote: remote({
+          result: async () =>
+            new Response(
+              new ReadableStream({
+                start(controller) {
+                  controller.enqueue(body);
+                  controller.close();
+                },
+              }),
+              { headers: { "content-type": "application/json" } },
+            ),
+        }),
+        runId: "speech-run",
+        context: context(),
+        signal: new AbortController().signal,
+        outputBound: false,
+        maxInlineOutputBytes: 1024,
+      }),
+    ).rejects.toMatchObject({ code: "INVALID_RESPONSE" });
+  });
+});
+
+function outputStart(): SpeechOutputArtifactStart {
+  return {
+    runId: "speech-run",
+    scopeId: `outscope_${"a".repeat(32)}`,
+    grantGeneration: 1,
+    grant: "output-grant",
+    descriptor: {
+      contractVersion: 1,
+      scope: `outscope_${"a".repeat(32)}`,
+      outputKind: "normalized-audio",
+      deploymentIdentity:
+        "windy-deployment-v1_7db61d8e-e50d-4f8a-9f3f-9b7a1d932e01",
+      releaseDigest: `sha256:${"b".repeat(64)}`,
+      offersDigest: `sha256:${"c".repeat(64)}`,
+      policyDigest: "d".repeat(64),
+      grantGeneration: 1,
+      allowedMediaTypes: ["audio/wav"],
+      expiresAt: "2026-08-06T12:02:00.000Z",
+      limits: {
+        maxArtifactBytes: 4_096,
+        maxArtifacts: 1,
+        maxTotalBytes: 4_096,
+      },
+    },
+  };
+}
+
+function remote(overrides: Partial<SpeechRuntimePort>): SpeechRuntimePort {
+  return {
+    async start() {
+      return { runId: "speech-run", status: "accepted", eventsUrl: "/events" };
+    },
+    async events() {
+      return new Response();
+    },
+    async result() {
+      return Response.json({});
+    },
+    async artifact() {
+      return new Response();
+    },
+    async cancel() {
+      return Response.json({ runId: "speech-run", status: "cancelled" });
+    },
+    async health() {
+      return Response.json({ status: "ready" });
+    },
+    ...overrides,
+  };
+}
+
+function context(): RequestGuardContext {
+  return {
+    requestId: "speech-output-test",
+    actor: {
+      id: "actor-1",
+      type: "user",
+      name: "分析员",
+      roleCodes: [],
+      permissionKeys: [],
+    },
+    startedAt: "2026-08-06T12:00:00.000Z",
+  };
+}
+
+function streamedResponse(padding: string, status: number) {
+  return new Response(stream(JSON.stringify({ padding })), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+}
+
+function stream(value: string) {
+  const bytes = new TextEncoder().encode(value);
+  return new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+}

package/template/apps/server/src/speech/facade-output.ts

@@ -0,0 +1,298 @@
+import { createHash } from "node:crypto";
+import type { RequestGuardContext } from "../guards.js";
+import { SpeechRuntimeError, type SpeechRuntimePort } from "./contracts.js";
+import { SpeechFacadeError } from "./errors.js";
+import type {
+  SpeechOutputArtifactHost,
+  SpeechOutputArtifactStart,
+} from "./output-artifact-host.js";
+import { SpeechOutputArtifactHostError } from "./output-artifact-error.js";
+import {
+  readBoundedSpeechJson,
+  speechControlResponseLimit,
+  speechStreamResponseLimit,
+} from "./remote-response.js";
+
+const jsonEnvelopeBytes = 64 * 1024;
+
+export function speechRunId(scopedKey: string) {
+  if (!/^[a-f0-9]{64}$/.test(scopedKey)) {
+    throw new SpeechFacadeError("INVALID_INPUT", "Speech 幂等键无效", 400);
+  }
+  return `speech_${scopedKey}`;
+}
+
+export async function confirmSpeechOutput(
+  host: SpeechOutputArtifactHost | undefined,
+  output: SpeechOutputArtifactStart | undefined,
+) {
+  if (
+    output?.grant &&
+    !(await host?.confirmGrant(
+      output.scopeId,
+      output.grantGeneration,
+      output.grant,
+    ))
+  ) {
+    throw new SpeechRuntimeError(
+      "INVALID_RESPONSE",
+      "Speech Runtime 未确认 Output Artifact Grant",
+      false,
+    );
+  }
+}
+
+export async function rollbackSpeechOutput(
+  host: SpeechOutputArtifactHost | undefined,
+  output: SpeechOutputArtifactStart | undefined,
+) {
+  if (output?.grant) {
+    await retry(async () => {
+      await host?.rollbackPendingGrant(
+        output.scopeId,
+        output.grantGeneration,
+        output.grant!,
+      );
+      return true;
+    });
+  }
+  if (output && !(await retry(() => host?.abortOpenRun(output.runId)))) {
+    throw cleanupUnavailable();
+  }
+}
+
+export async function cancelSpeechRun(input: {
+  remote: SpeechRuntimePort;
+  host?: SpeechOutputArtifactHost;
+  runId: string;
+  reason?: string;
+  signal: AbortSignal;
+  outputBound: boolean;
+}) {
+  let response: Response;
+  try {
+    response = await input.remote.cancel(
+      input.runId,
+      input.reason,
+      input.signal,
+    );
+  } catch (error) {
+    if (input.outputBound) await abortOpen(input.host, input.runId);
+    throw remoteFacadeError(error);
+  }
+  let aborted = false;
+  const abortBoundOutput = async () => {
+    if (input.outputBound && !aborted) {
+      await abortOpen(input.host, input.runId);
+      aborted = true;
+    }
+  };
+  if (!response.ok) await abortBoundOutput();
+  let value: unknown;
+  try {
+    value = await readBoundedSpeechJson(response, speechControlResponseLimit);
+  } catch {
+    await abortBoundOutput();
+    throw invalidResponse();
+  }
+  if (!response.ok || !isRecord(value) || value.runId !== input.runId) {
+    await abortBoundOutput();
+    throw new SpeechFacadeError(
+      "RUNTIME_UNAVAILABLE",
+      "Speech Runtime 取消响应无效",
+      503,
+    );
+  }
+  const status = value.status;
+  if (!["completed", "failed", "cancelled"].includes(String(status))) {
+    await abortBoundOutput();
+    throw new SpeechFacadeError(
+      "RUNTIME_UNAVAILABLE",
+      "Speech Runtime 取消状态不确定",
+      503,
+    );
+  }
+  if (input.outputBound && status !== "completed") {
+    await abortBoundOutput();
+  }
+  return Response.json(
+    { runId: input.runId, status },
+    { headers: { "cache-control": "private, no-store" } },
+  );
+}
+
+export async function speechResultResponse(input: {
+  remote: SpeechRuntimePort;
+  host?: SpeechOutputArtifactHost;
+  runId: string;
+  context: RequestGuardContext;
+  signal: AbortSignal;
+  outputBound: boolean;
+  maxInlineOutputBytes: number;
+  artifact?: boolean;
+}) {
+  let response: Response;
+  try {
+    response = await input.remote.result(input.runId, input.signal);
+  } catch (error) {
+    throw remoteFacadeError(error);
+  }
+  let value: unknown;
+  try {
+    value = await readBoundedSpeechJson(
+      response,
+      Math.min(
+        speechStreamResponseLimit,
+        input.maxInlineOutputBytes + jsonEnvelopeBytes,
+      ),
+    );
+  } catch {
+    throw invalidResponse();
+  }
+  if (!response.ok) {
+    if (
+      input.outputBound &&
+      isRecord(value) &&
+      ["failed", "cancelled"].includes(String(value.status))
+    ) {
+      await abortOpen(input.host, input.runId);
+    }
+    throw new SpeechFacadeError(
+      response.status === 409 ? "RUN_CONFLICT" : "RUNTIME_UNAVAILABLE",
+      response.status === 409
+        ? "Speech 结果尚未就绪"
+        : "Speech Runtime 暂时不可用",
+      response.status === 409 ? 409 : 503,
+    );
+  }
+  if (
+    !isRecord(value) ||
+    value.runId !== input.runId ||
+    value.status !== "completed" ||
+    !isRecord(value.output)
+  ) {
+    throw invalidResponse();
+  }
+  const output = input.outputBound
+    ? {
+        ...withoutArtifacts(value.output),
+        artifacts: await claimSpeechOutput(
+          input.host,
+          input.runId,
+          input.context,
+        ),
+      }
+    : value.output;
+  if (input.outputBound && !output.artifacts) throw invalidResponse();
+  const body = JSON.stringify({
+    runId: input.runId,
+    status: "completed",
+    output,
+  });
+  if (!input.artifact) {
+    return new Response(body, {
+      headers: {
+        "content-type": "application/json",
+        "cache-control": "private, no-store",
+      },
+    });
+  }
+  const bytes = new TextEncoder().encode(body);
+  return new Response(bytes, {
+    headers: {
+      "content-type": "application/json",
+      "content-length": String(bytes.byteLength),
+      "x-content-sha256": createHash("sha256").update(bytes).digest("hex"),
+      "cache-control": "private, no-store",
+    },
+  });
+}
+
+async function abortOpen(
+  host: SpeechOutputArtifactHost | undefined,
+  runId: string,
+) {
+  if (!host || !(await host.abortOpenRun(runId).catch(() => false))) {
+    throw new SpeechFacadeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Speech Output Artifact 无法确认清理",
+      503,
+    );
+  }
+}
+
+async function retry(action: () => Promise<unknown> | undefined) {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    try {
+      if (await action()) return true;
+    } catch {
+      // Retry a bounded number of times; callers receive a stable 503 on exhaustion.
+    }
+  }
+  return false;
+}
+
+function cleanupUnavailable() {
+  return new SpeechRuntimeError(
+    "CAPABILITY_UNAVAILABLE",
+    "Speech Output Artifact 补偿清理待重试",
+    true,
+  );
+}
+
+function withoutArtifacts(output: Record<string, unknown>) {
+  const { artifacts: _ignored, ...safe } = output;
+  return safe;
+}
+
+async function claimSpeechOutput(
+  host: SpeechOutputArtifactHost | undefined,
+  runId: string,
+  context: RequestGuardContext,
+) {
+  if (!host) throw invalidResponse();
+  try {
+    return await host.claimSealed(runId, context);
+  } catch (error) {
+    if (error instanceof SpeechOutputArtifactHostError) {
+      throw new SpeechFacadeError(
+        error.code,
+        error.message,
+        error.code === "FORBIDDEN"
+          ? 403
+          : error.code === "RUN_CONFLICT"
+            ? 409
+            : 503,
+      );
+    }
+    throw invalidResponse();
+  }
+}
+
+function remoteFacadeError(error: unknown) {
+  if (error instanceof SpeechRuntimeError) {
+    if (error.code === "FORBIDDEN") {
+      return new SpeechFacadeError("FORBIDDEN", "Speech Runtime 拒绝访问", 403);
+    }
+    if (error.code === "RUN_CONFLICT") {
+      return new SpeechFacadeError("RUN_CONFLICT", "Speech Run 状态冲突", 409);
+    }
+  }
+  return new SpeechFacadeError(
+    "RUNTIME_UNAVAILABLE",
+    "Speech Runtime 暂时不可用",
+    503,
+  );
+}
+
+function invalidResponse() {
+  return new SpeechFacadeError(
+    "INVALID_RESPONSE",
+    "Speech Runtime 响应无效",
+    503,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}