create-windy 0.5.2 → 0.6.0

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

@@ -0,0 +1,33 @@
+import { readBoundedDocumentJson } from "./remote-response.js";
+
+export type DocumentCancelStatus =
+  | "cancelled"
+  | "completed"
+  | "failed"
+  | "unknown";
+
+export async function documentCancelStatus(
+  response: Response,
+  expectedRunId: string,
+): Promise<DocumentCancelStatus> {
+  try {
+    const value = await readBoundedDocumentJson(response, 4_096);
+    if (!response.ok) return "unknown";
+    if (
+      !record(value) ||
+      Object.keys(value).some((key) => !["runId", "status"].includes(key)) ||
+      Object.keys(value).length !== 2 ||
+      value.runId !== expectedRunId ||
+      !["cancelled", "completed", "failed"].includes(String(value.status))
+    ) {
+      return "unknown";
+    }
+    return value.status as Exclude<DocumentCancelStatus, "unknown">;
+  } catch {
+    return "unknown";
+  }
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/template/apps/server/src/document/contracts.ts

@@ -4,6 +4,7 @@ import type {
   AiProviderEgressPolicy,
 } from "@southwind-ai/modules";
 import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+import type { AiOutputArtifactSinkDescriptorV1 } from "../ai-output-artifact/contracts.js";
 
 export interface DocumentRuntimeArtifact {
   /** 仅供受信任 Runtime 通过专用 Header 回取，不能写入日志或转发 Adapter。 */
@@ -15,6 +16,8 @@ export interface DocumentRuntimeArtifact {
 
 export interface DocumentRuntimeOperation {
   readonly kind: "document";
+  /** Output Sink 启用时由 Host 预分配，Runtime 必须原样采用。 */
+  readonly runId?: string;
   readonly operationKey: string;
   readonly options: ModuleAiJsonValue;
   readonly sources: readonly DocumentRuntimeArtifact[];
@@ -29,6 +32,8 @@ export interface DocumentRuntimeOperation {
   };
   readonly providerEgress: AiProviderEgressPolicy;
   readonly providerDataPolicy?: AiProviderDataPolicy;
+  /** 不含 grant；grant 只允许通过内部 Header 转交。 */
+  readonly outputArtifactSink?: AiOutputArtifactSinkDescriptorV1;
 }
 
 export interface DocumentRuntimeStartResponse {
@@ -42,6 +47,7 @@ export interface DocumentRuntimePort {
     request: DocumentRuntimeOperation,
     idempotencyKey: string,
     signal?: AbortSignal,
+    outputArtifactGrant?: string,
   ): Promise<DocumentRuntimeStartResponse>;
   events(
     runId: string,

package/template/apps/server/src/document/errors.ts

@@ -0,0 +1,11 @@
+export class DocumentFacadeError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+    readonly retryable: boolean = status >= 500,
+  ) {
+    super(message);
+    this.name = "DocumentFacadeError";
+  }
+}

package/template/apps/server/src/document/facade-cancel.test.ts

@@ -0,0 +1,226 @@
+import { describe, expect, test } from "bun:test";
+import {
+  outputByteStream,
+  outputHash,
+  outputManifest,
+} from "../ai-output-artifact/test-support.js";
+import {
+  createDocumentOutputFixture,
+  operationKey,
+} from "./output-artifact.test-support.js";
+import type { DocumentRuntimePort } from "./contracts.js";
+import { cancelDocumentRun } from "./facade-cancel.js";
+
+const source = {
+  value: "input-artifact",
+  mediaType: "application/pdf",
+  byteSize: 10,
+  sha256: "a".repeat(64),
+  expiresAt: "2026-07-31T12:05:00.000Z",
+};
+
+describe("Document cancel response governance", () => {
+  test("只有目标 run 的严格 2xx DTO 才能完整撤销 sealed 产物", async () => {
+    for (const item of cancelCases()) {
+      const fixture = await createDocumentOutputFixture();
+      const started = await fixture.facade.start(
+        operationKey,
+        [source],
+        {},
+        `cancel-${item.name}`,
+        fixture.context(),
+        new AbortController().signal,
+      );
+      const call = fixture.remote.starts[0]!;
+      await publishOne(
+        fixture,
+        call.request.outputArtifactSink!.scope,
+        call.outputArtifactGrant!,
+      );
+      fixture.remote.cancelResult = () => item.response(started.runId);
+
+      const cancelled = fixture.facade.cancel(
+        started.runId,
+        "review",
+        fixture.context(),
+        new AbortController().signal,
+      );
+      await expect(cancelled).rejects.toMatchObject({
+        code: item.errorCode,
+        status: 503,
+      });
+      expect(
+        (
+          await fixture.output.service.options.repository.getScope(
+            call.request.outputArtifactSink!.scope,
+          )
+        )?.status,
+      ).toBe("sealed");
+    }
+  });
+
+  test("无 output binding 也只返回 Host 规范 DTO 与安全 Header", async () => {
+    const response = await cancelDocumentRun({
+      remote: cancelPort(
+        Response.json(
+          { runId: "run-safe", status: "completed" },
+          {
+            headers: {
+              "set-cookie": "runtime-secret=raw",
+              "x-runtime-secret": "outgrant_v1_sensitive",
+            },
+          },
+        ),
+      ),
+      runId: "run-safe",
+      signal: new AbortController().signal,
+      outputBound: false,
+      abortOutput: async () => true,
+      abortUnknownOutput: async () => true,
+    });
+
+    expect(await response.json()).toEqual({
+      runId: "run-safe",
+      status: "completed",
+    });
+    expect(response.headers.get("cache-control")).toBe("private, no-store");
+    expect(response.headers.get("set-cookie")).toBeNull();
+    expect(response.headers.get("x-runtime-secret")).toBeNull();
+  });
+
+  test("非 2xx 的 raw body/header 只映射为固定本地错误", async () => {
+    const cancellation = cancelDocumentRun({
+      remote: cancelPort(
+        new Response(
+          JSON.stringify({
+            code: "FORBIDDEN",
+            message: "leak outgrant_v1_sensitive",
+          }),
+          {
+            status: 500,
+            headers: { "set-cookie": "runtime-secret=raw" },
+          },
+        ),
+      ),
+      runId: "run-error",
+      signal: new AbortController().signal,
+      outputBound: false,
+      abortOutput: async () => true,
+      abortUnknownOutput: async () => true,
+    });
+
+    await expect(cancellation).rejects.toMatchObject({
+      code: "RUNTIME_UNAVAILABLE",
+      message: "Document Runtime 暂时不可用",
+      status: 503,
+      retryable: true,
+    });
+  });
+});
+
+function cancelCases() {
+  return [
+    {
+      name: "server-error",
+      errorCode: "RUNTIME_UNAVAILABLE",
+      response: (runId: string) =>
+        Response.json({ runId, status: "cancelled" }, { status: 500 }),
+    },
+    {
+      name: "wrong-run",
+      errorCode: "CAPABILITY_UNAVAILABLE",
+      response: () =>
+        Response.json({ runId: "other-run", status: "cancelled" }),
+    },
+    {
+      name: "missing-run",
+      errorCode: "CAPABILITY_UNAVAILABLE",
+      response: () => Response.json({ status: "cancelled" }),
+    },
+    {
+      name: "malformed",
+      errorCode: "CAPABILITY_UNAVAILABLE",
+      response: () => new Response("{not-json", { status: 200 }),
+    },
+    {
+      name: "chunked-over-limit",
+      errorCode: "CAPABILITY_UNAVAILABLE",
+      response: () =>
+        new Response(overLimitBody(), {
+          status: 200,
+          headers: { "transfer-encoding": "chunked" },
+        }),
+    },
+    {
+      name: "persistent-over-limit",
+      errorCode: "CAPABILITY_UNAVAILABLE",
+      response: () =>
+        new Response(persistentOverLimitBody(), {
+          status: 200,
+          headers: { "transfer-encoding": "chunked" },
+        }),
+    },
+  ] as const;
+}
+
+function overLimitBody() {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(new Uint8Array(4_097));
+      controller.close();
+    },
+  });
+}
+
+function persistentOverLimitBody() {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(new Uint8Array(4_097));
+    },
+    cancel() {
+      return new Promise<void>(() => undefined);
+    },
+  });
+}
+
+function cancelPort(response: Response): DocumentRuntimePort {
+  return {
+    async cancel() {
+      return response;
+    },
+  } as unknown as DocumentRuntimePort;
+}
+
+async function publishOne(
+  fixture: Awaited<ReturnType<typeof createDocumentOutputFixture>>,
+  scopeId: string,
+  grant: string,
+) {
+  const bytes = new TextEncoder().encode("%PDF-1.7\ncancel");
+  const receipt = await fixture.output.service.beginArtifact(
+    scopeId,
+    grant,
+    outputManifest(bytes),
+    new AbortController().signal,
+  );
+  await fixture.output.service.appendPart(
+    scopeId,
+    grant,
+    {
+      artifactId: receipt.artifactId,
+      partNumber: 0,
+      byteOffset: 0,
+      byteSize: bytes.byteLength,
+      sha256: outputHash(bytes),
+      body: outputByteStream(bytes),
+    },
+    new AbortController().signal,
+  );
+  await fixture.output.service.completeArtifact(
+    scopeId,
+    grant,
+    receipt.artifactId,
+    new AbortController().signal,
+  );
+  await fixture.output.service.sealScope(scopeId, grant);
+}

package/template/apps/server/src/document/facade-cancel.ts

@@ -0,0 +1,110 @@
+import { DocumentRuntimeError, type DocumentRuntimePort } from "./contracts.js";
+import { DocumentFacadeError } from "./errors.js";
+import { documentCancelStatus } from "./cancel-response.js";
+import { capabilityUnavailable } from "./facade-support.js";
+import type { DocumentOutputArtifactHost } from "./output-artifact-host.js";
+
+export async function cancelDocumentRun(input: {
+  readonly remote: DocumentRuntimePort;
+  readonly runId: string;
+  readonly reason?: string;
+  readonly signal: AbortSignal;
+  readonly outputBound: boolean;
+  readonly abortOutput: () => Promise<boolean>;
+  readonly abortUnknownOutput: () => Promise<boolean>;
+}): Promise<Response> {
+  let response: Response;
+  try {
+    response = await input.remote.cancel(
+      input.runId,
+      input.reason,
+      input.signal,
+    );
+  } catch (error) {
+    if (input.outputBound && !(await input.abortUnknownOutput())) {
+      throw capabilityUnavailable();
+    }
+    if (error instanceof DocumentRuntimeError) {
+      throw cancelRuntimeError(error.code);
+    }
+    throw capabilityUnavailable();
+  }
+  const status = await documentCancelStatus(response, input.runId);
+  if (!response.ok) {
+    if (input.outputBound && !(await input.abortUnknownOutput())) {
+      throw capabilityUnavailable();
+    }
+    throw cancelHttpError(response.status);
+  }
+  if (status === "unknown") {
+    if (input.outputBound && !(await input.abortUnknownOutput())) {
+      throw capabilityUnavailable();
+    }
+    throw capabilityUnavailable();
+  }
+  if (
+    input.outputBound &&
+    status !== "completed" &&
+    !(await input.abortOutput())
+  ) {
+    throw capabilityUnavailable();
+  }
+  return Response.json(
+    { runId: input.runId, status },
+    { headers: { "cache-control": "private, no-store" } },
+  );
+}
+
+export async function abortDocumentOutput(
+  host: DocumentOutputArtifactHost | undefined,
+  runId: string,
+  onlyOpen = false,
+): Promise<boolean> {
+  if (!host) return true;
+  try {
+    return onlyOpen
+      ? await host.abortOpenRun(runId)
+      : await host.abortRun(runId);
+  } catch {
+    return false;
+  }
+}
+
+function cancelHttpError(status: number) {
+  if (status === 401 || status === 403) {
+    return new DocumentFacadeError(
+      "FORBIDDEN",
+      "Document Runtime 拒绝取消请求",
+      403,
+      false,
+    );
+  }
+  if (status === 409) {
+    return new DocumentFacadeError(
+      "RUN_CONFLICT",
+      "Document 取消状态冲突",
+      409,
+      false,
+    );
+  }
+  return new DocumentFacadeError(
+    "RUNTIME_UNAVAILABLE",
+    "Document Runtime 暂时不可用",
+    503,
+    true,
+  );
+}
+
+function cancelRuntimeError(code: DocumentRuntimeError["code"]) {
+  if (code === "FORBIDDEN") return cancelHttpError(403);
+  if (code === "RUN_CONFLICT") return cancelHttpError(409);
+  if (code === "BUDGET_EXCEEDED" || code === "INVALID_INPUT") {
+    return new DocumentFacadeError(
+      "INVALID_INPUT",
+      "Document Runtime 拒绝取消请求",
+      400,
+      false,
+    );
+  }
+  return cancelHttpError(503);
+}

package/template/apps/server/src/document/facade-grant-handoff.test.ts

@@ -0,0 +1,113 @@
+import { describe, expect, test } from "bun:test";
+import { DocumentRuntimeError } from "./contracts.js";
+import { documentOutputSource } from "./output-artifact-publish.test-support.js";
+import {
+  createDocumentOutputFixture,
+  operationKey,
+} from "./output-artifact.test-support.js";
+
+describe("Document Facade grant handoff", () => {
+  test("pre-ACK loss 回滚 pending，随后相同语义以新 credential 重试", async () => {
+    const fixture = await createDocumentOutputFixture();
+    fixture.remote.beforeGrantAccept = () => {
+      throw unavailable("pre-ACK network loss with raw secret");
+    };
+
+    await expect(start(fixture, "facade-pre-ack")).rejects.toMatchObject({
+      code: "RUNTIME_UNAVAILABLE",
+      status: 503,
+    });
+    const firstCall = fixture.remote.starts[0]!;
+    const scopeId = firstCall.request.outputArtifactSink!.scope;
+    const rolledBack =
+      await fixture.output.service.options.repository.getScope(scopeId);
+    expect(rolledBack).toMatchObject({
+      status: "open",
+      grantSequence: 1,
+    });
+    expect(rolledBack).not.toHaveProperty("grantHash");
+    expect(rolledBack?.pendingGrantHash).toBeUndefined();
+
+    fixture.remote.beforeGrantAccept = () => undefined;
+    await expect(start(fixture, "facade-pre-ack")).resolves.toMatchObject({
+      status: "accepted",
+    });
+    expect(
+      fixture.remote.starts[1]?.request.outputArtifactSink?.grantGeneration,
+    ).toBe(2);
+    expect(
+      await fixture.output.service.options.repository.getScope(scopeId),
+    ).toMatchObject({
+      activeGrantGeneration: 2,
+      grantSequence: 2,
+    });
+  });
+
+  test("Runtime 未 ACK 时即使 start 返回也失败关闭并回滚 pending", async () => {
+    const fixture = await createDocumentOutputFixture();
+    fixture.remote.acceptOutputGrant = async () => undefined;
+
+    await expect(start(fixture, "facade-missing-ack")).rejects.toMatchObject({
+      code: "INVALID_RESPONSE",
+      status: 503,
+    });
+    const scopeId = fixture.remote.starts[0]!.request.outputArtifactSink!.scope;
+    const scope =
+      await fixture.output.service.options.repository.getScope(scopeId);
+    expect(scope?.status).toBe("open");
+    expect(scope).not.toHaveProperty("grantHash");
+    expect(scope?.pendingGrantHash).toBeUndefined();
+  });
+
+  test("ACK 后响应丢失保留 current，重试只在新 ACK 后完成交接", async () => {
+    const fixture = await createDocumentOutputFixture();
+    fixture.remote.beforeStart = () => {
+      throw unavailable("post-ACK response lost with raw secret");
+    };
+
+    await expect(start(fixture, "facade-post-ack")).rejects.toMatchObject({
+      code: "RUNTIME_UNAVAILABLE",
+      status: 503,
+    });
+    const scopeId = fixture.remote.starts[0]!.request.outputArtifactSink!.scope;
+    expect(
+      await fixture.output.service.options.repository.getScope(scopeId),
+    ).toMatchObject({
+      status: "open",
+      activeGrantGeneration: 1,
+      grantSequence: 1,
+    });
+
+    fixture.remote.beforeStart = () => undefined;
+    await expect(start(fixture, "facade-post-ack")).resolves.toMatchObject({
+      status: "accepted",
+    });
+    expect(
+      fixture.remote.starts[1]?.request.outputArtifactSink?.grantGeneration,
+    ).toBe(2);
+    expect(
+      await fixture.output.service.options.repository.getScope(scopeId),
+    ).toMatchObject({
+      activeGrantGeneration: 2,
+      grantSequence: 2,
+    });
+  });
+});
+
+function start(
+  fixture: Awaited<ReturnType<typeof createDocumentOutputFixture>>,
+  idempotencyKey: string,
+) {
+  return fixture.facade.start(
+    operationKey,
+    [documentOutputSource],
+    {},
+    idempotencyKey,
+    fixture.context(),
+    new AbortController().signal,
+  );
+}
+
+function unavailable(message: string) {
+  return new DocumentRuntimeError("RUNTIME_UNAVAILABLE", message, true);
+}