create-windy 0.5.1 → 0.6.0

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

@@ -4,6 +4,13 @@ import {
   type DocumentRuntimePort,
   type DocumentRuntimeStartResponse,
 } from "./contracts.js";
+import {
+  boundDocumentResponse,
+  documentResponseLimit,
+  documentStreamLimit,
+  parseDocumentStartResponse,
+  safeDocumentRemoteError,
+} from "./remote-response.js";
 
 export class RemoteDocumentRuntime implements DocumentRuntimePort {
   readonly #baseUrl: string;
@@ -31,25 +38,31 @@ export class RemoteDocumentRuntime implements DocumentRuntimePort {
     request: DocumentRuntimeOperation,
     idempotencyKey: string,
     signal?: AbortSignal,
+    outputArtifactGrant?: string,
   ): Promise<DocumentRuntimeStartResponse> {
     const response = await this.request("/api/document/runs", {
       method: "POST",
       headers: {
         "content-type": "application/json",
         "idempotency-key": idempotencyKey,
+        ...(outputArtifactGrant
+          ? {
+              "x-ai-output-artifact-grant": outputArtifactGrant,
+            }
+          : {}),
       },
       body: JSON.stringify(request),
       signal,
     });
-    if (!response.ok) throw await remoteError(response);
-    return parseStartResponse(await response.json());
+    if (!response.ok) throw await safeDocumentRemoteError(response);
+    return parseDocumentStartResponse(response);
   }
 
   events(runId: string, cursor: number, signal?: AbortSignal) {
     return this.request(
       `/api/document/runs/${encodeURIComponent(runId)}/events?after=${cursor}`,
       { signal },
-      false,
+      documentStreamLimit,
     );
   }
 
@@ -57,6 +70,7 @@ export class RemoteDocumentRuntime implements DocumentRuntimePort {
     return this.request(
       `/api/document/runs/${encodeURIComponent(runId)}/result`,
       { signal },
+      documentStreamLimit,
     );
   }
 
@@ -79,7 +93,7 @@ export class RemoteDocumentRuntime implements DocumentRuntimePort {
   private request(
     path: string,
     init: RequestInit = {},
-    bounded = true,
+    maxBytes = documentResponseLimit,
   ): Promise<Response> {
     const timeout = AbortSignal.timeout(this.#timeoutMs);
     const signal = init.signal
@@ -88,44 +102,14 @@ export class RemoteDocumentRuntime implements DocumentRuntimePort {
     const requestFetch = this.options.fetch ?? fetch;
     return requestFetch(`${this.#baseUrl}${path}`, {
       ...init,
+      redirect: "error",
       signal,
       headers: {
         authorization: `Bearer ${this.options.internalToken}`,
         ...init.headers,
       },
-    }).then((response) => {
-      if (
-        bounded &&
-        Number(response.headers.get("content-length") || "0") >
-          64 * 1_024 * 1_024
-      ) {
-        throw new DocumentRuntimeError(
-          "INVALID_RESPONSE",
-          "Document Runtime 响应超过上限",
-          false,
-        );
-      }
-      return response;
-    });
-  }
-}
-
-function parseStartResponse(value: unknown): DocumentRuntimeStartResponse {
-  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();
+    }).then((response) => boundDocumentResponse(response, maxBytes));
   }
-  return { runId, status, eventsUrl };
 }
 
 export const unavailableDocumentRuntime: DocumentRuntimePort = {
@@ -147,8 +131,23 @@ export const unavailableDocumentRuntime: DocumentRuntimePort = {
   },
   async health() {
     return Response.json(
-      { status: "unavailable", capabilities: [] },
-      { status: 503 },
+      {
+        schemaVersion: 1,
+        status: "unavailable",
+        configured: false,
+        runtimeKind: "document",
+        observedAt: new Date().toISOString(),
+        downstreamProbe: { status: "not-run", reason: "NOT_CONFIGURED" },
+        deployment: null,
+        offers: [],
+        unavailableReasons: [
+          { code: "RUNTIME_NOT_CONFIGURED", retryable: true },
+        ],
+      },
+      {
+        status: 503,
+        headers: { "cache-control": "private, no-store" },
+      },
     );
   },
 };
@@ -161,18 +160,6 @@ function unavailable() {
   );
 }
 
-function invalidResponse() {
-  return new DocumentRuntimeError(
-    "INVALID_RESPONSE",
-    "Document Runtime 响应无效",
-    false,
-  );
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return Boolean(value && typeof value === "object" && !Array.isArray(value));
-}
-
 function normalizeUrl(raw: string) {
   const url = new URL(raw);
   if (
@@ -186,38 +173,3 @@ function normalizeUrl(raw: string) {
   }
   return url.toString().replace(/\/$/, "");
 }
-
-async function remoteError(response: Response) {
-  try {
-    const value = (await response.json()) as Record<string, unknown>;
-    if (
-      typeof value.code === "string" &&
-      typeof value.message === "string" &&
-      typeof value.retryable === "boolean" &&
-      value.message.length <= 200
-    ) {
-      return new DocumentRuntimeError(
-        knownRemoteCode(value.code),
-        value.message,
-        value.retryable,
-      );
-    }
-  } catch {
-    // 不透传远端正文。
-  }
-  return unavailable();
-}
-
-function knownRemoteCode(
-  code: string,
-): ConstructorParameters<typeof DocumentRuntimeError>[0] {
-  return [
-    "CAPABILITY_UNAVAILABLE",
-    "RUN_CONFLICT",
-    "FORBIDDEN",
-    "BUDGET_EXCEEDED",
-    "INVALID_INPUT",
-  ].includes(code)
-    ? (code as ConstructorParameters<typeof DocumentRuntimeError>[0])
-    : "RUNTIME_UNAVAILABLE";
-}

package/template/apps/server/src/document/routes-read-response.test.ts

@@ -0,0 +1,267 @@
+import { describe, expect, test } from "bun:test";
+import type { RouteApp } from "../system/route-types.js";
+import { DocumentRuntimeError, type DocumentRuntimePort } from "./contracts.js";
+import type { DocumentRunFacade } from "./facade.js";
+import { registerDocumentRunRoutes } from "./routes.js";
+
+describe("Document events/result response boundary", () => {
+  test("2xx 只保留安全 Content-Type 与 no-store，剥离远端敏感 Header", async () => {
+    const runtime = documentRuntime({
+      events: async () =>
+        remoteSuccess("text/event-stream; charset=utf-8", "data: {}\n\n"),
+      result: async () =>
+        remoteSuccess("application/json; charset=utf-8", '{"status":"done"}'),
+    });
+    const app = routes(runtime);
+
+    for (const [path, contentType, body] of [
+      ["/document/runs/:runId/events", "text/event-stream", "data: {}\n\n"],
+      ["/document/runs/:runId/result", "application/json", '{"status":"done"}'],
+    ] as const) {
+      const response = await app.call(
+        "GET",
+        path,
+        routeContext(`request-${contentType}`),
+      );
+      expect(response.status).toBe(200);
+      expect(response.headers.get("content-type")).toBe(contentType);
+      expect(response.headers.get("cache-control")).toBe("private, no-store");
+      expect(response.headers.get("set-cookie")).toBeNull();
+      expect(response.headers.get("location")).toBeNull();
+      expect(response.headers.get("x-ai-output-artifact-grant")).toBeNull();
+      expect(response.headers.get("x-runtime-internal")).toBeNull();
+      expect(await response.text()).toBe(body);
+    }
+  });
+
+  test("non-2xx 正文不透传，永不完成的 cancel 不阻塞固定本地 envelope", async () => {
+    const rawGrant = `outgrant_v1_${"z".repeat(43)}`;
+    const cancelled: unknown[] = [];
+    const runtime = documentRuntime({
+      events: async () =>
+        new Response(neverResolvingBody(rawGrant, cancelled), {
+          status: 500,
+          headers: {
+            "content-type": "text/plain",
+            "set-cookie": `session=${rawGrant}`,
+            location: "https://evil.example/collect",
+            "x-runtime-internal": rawGrant,
+          },
+        }),
+    });
+    const response = await settlesWithin(
+      routes(runtime).call(
+        "GET",
+        "/document/runs/:runId/events",
+        routeContext("request-events-error"),
+      ),
+    );
+
+    expect(response.status).toBe(503);
+    const text = await response.text();
+    expect(text).not.toContain(rawGrant);
+    expect(JSON.parse(text)).toEqual({
+      code: "RUNTIME_UNAVAILABLE",
+      message: "Document Runtime 暂时不可用",
+      requestId: "request-events-error",
+      retryable: true,
+    });
+    expect(response.headers.get("set-cookie")).toBeNull();
+    expect(response.headers.get("location")).toBeNull();
+    expect(response.headers.get("x-runtime-internal")).toBeNull();
+    expect(cancelled).toEqual(["document-runtime-response-rejected"]);
+  });
+
+  test("2xx 声明超限时非阻塞取消，并返回固定 INVALID_RESPONSE", async () => {
+    const cancelled: unknown[] = [];
+    const runtime = documentRuntime({
+      result: async () =>
+        new Response(neverResolvingBody("{}", cancelled), {
+          headers: {
+            "content-type": "application/json",
+            "content-length": String(64 * 1024 + 1),
+          },
+        }),
+    });
+    const response = await settlesWithin(
+      routes(runtime).call(
+        "GET",
+        "/document/runs/:runId/result",
+        routeContext("request-result-limit"),
+      ),
+    );
+
+    expect(response.status).toBe(503);
+    expect(await response.json()).toEqual({
+      code: "INVALID_RESPONSE",
+      message: "Document Runtime 响应无效",
+      requestId: "request-result-limit",
+      retryable: false,
+    });
+    expect(cancelled).toEqual([undefined]);
+  });
+
+  test("3xx Location 与 Runtime 异常 message 都改写为固定本地错误", async () => {
+    const raw = `outgrant_v1_${"q".repeat(43)}`;
+    const redirect = routes(
+      documentRuntime({
+        events: async () =>
+          new Response(null, {
+            status: 302,
+            headers: { location: `https://evil.example/${raw}` },
+          }),
+      }),
+    );
+    const redirected = await redirect.call(
+      "GET",
+      "/document/runs/:runId/events",
+      routeContext("request-redirect"),
+    );
+    expect(redirected.status).toBe(503);
+    expect(redirected.headers.get("location")).toBeNull();
+    expect(await redirected.text()).not.toContain(raw);
+
+    const failed = routes(
+      documentRuntime({
+        result: async () => {
+          throw new DocumentRuntimeError("FORBIDDEN", raw, false);
+        },
+      }),
+    );
+    const response = await failed.call(
+      "GET",
+      "/document/runs/:runId/result",
+      routeContext("request-runtime-error"),
+    );
+    expect(response.status).toBe(403);
+    expect(await response.json()).toEqual({
+      code: "FORBIDDEN",
+      message: "Document Runtime 拒绝访问",
+      requestId: "request-runtime-error",
+      retryable: false,
+    });
+  });
+});
+
+type Handler = (context: unknown) => unknown;
+
+class RouteHarness implements RouteApp {
+  readonly routes = new Map<string, Handler>();
+  get(path: string, handler: Handler) {
+    this.routes.set(`GET ${path}`, handler);
+  }
+  post(path: string, handler: Handler) {
+    this.routes.set(`POST ${path}`, handler);
+  }
+  put(path: string, handler: Handler) {
+    this.routes.set(`PUT ${path}`, handler);
+  }
+  delete(path: string, handler: Handler) {
+    this.routes.set(`DELETE ${path}`, handler);
+  }
+  async call(method: string, path: string, context: unknown) {
+    const handler = this.routes.get(`${method} ${path}`);
+    if (!handler) throw new Error("route missing");
+    return (await handler(context)) as Response;
+  }
+}
+
+function routes(runtime: DocumentRuntimePort) {
+  const app = new RouteHarness();
+  registerDocumentRunRoutes(
+    app,
+    {
+      authorizeRun: async () => ({ operation: {} }),
+    } as unknown as DocumentRunFacade,
+    runtime,
+  );
+  return app;
+}
+
+function documentRuntime(
+  overrides: Partial<DocumentRuntimePort>,
+): DocumentRuntimePort {
+  return {
+    async start() {
+      return { runId: "run-1", status: "accepted", eventsUrl: "/events" };
+    },
+    async events() {
+      return new Response("data: {}\n\n", {
+        headers: { "content-type": "text/event-stream" },
+      });
+    },
+    async result() {
+      return Response.json({ status: "completed" });
+    },
+    async cancel() {
+      return Response.json({ status: "cancelled" });
+    },
+    async health() {
+      return Response.json({ status: "ready", capabilities: [] });
+    },
+    ...overrides,
+  };
+}
+
+function routeContext(requestId: string) {
+  return {
+    params: { runId: "run-1" },
+    query: {},
+    request: new Request("http://localhost:4317/api/document/runs/run-1"),
+    guardContext: {
+      requestId,
+      actor: {
+        id: "actor-1",
+        type: "user",
+        name: "分析员",
+        roleCodes: [],
+        permissionKeys: [],
+      },
+      startedAt: "2026-07-31T12:00:00.000Z",
+    },
+  };
+}
+
+function remoteSuccess(contentType: string, body: string) {
+  return new Response(body, {
+    headers: {
+      "content-type": contentType,
+      "cache-control": "public, max-age=3600",
+      "set-cookie": "runtime-session=secret",
+      location: "https://evil.example/collect",
+      "x-ai-output-artifact-grant": "outgrant_v1_secret",
+      "x-runtime-internal": "secret",
+    },
+  });
+}
+
+function neverResolvingBody(raw: string, cancelled: unknown[]) {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(new TextEncoder().encode(raw));
+    },
+    cancel(reason) {
+      cancelled.push(reason);
+      return new Promise<void>(() => undefined);
+    },
+  });
+}
+
+function settlesWithin(promise: Promise<Response>): Promise<Response> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new Error("response waited for remote body cancellation")),
+      100,
+    );
+    promise.then(
+      (response) => {
+        clearTimeout(timer);
+        resolve(response);
+      },
+      (error) => {
+        clearTimeout(timer);
+        reject(error);
+      },
+    );
+  });
+}

package/template/apps/server/src/document/routes.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, test } from "bun:test";
+import type { RouteApp } from "../system/route-types.js";
+import type { DocumentRuntimePort } from "./contracts.js";
+import { DocumentFacadeError, type DocumentRunFacade } from "./facade.js";
+import { registerDocumentRunRoutes } from "./routes.js";
+
+describe("Document public routes", () => {
+  test("错误响应使用真实 guard requestId", async () => {
+    const app = new RouteHarness();
+    registerDocumentRunRoutes(
+      app,
+      {} as DocumentRunFacade,
+      {} as DocumentRuntimePort,
+    );
+    const response = await app.call("POST", "/document/runs", {
+      body: null,
+      params: {},
+      query: {},
+      request: new Request("http://localhost/api/document/runs"),
+      guardContext: {
+        requestId: "request-document-route",
+        actor: {
+          id: "actor-1",
+          type: "user",
+          name: "分析员",
+          roleCodes: [],
+          permissionKeys: [],
+        },
+        startedAt: "2026-07-31T12:00:00.000Z",
+      },
+    });
+
+    expect(response.status).toBe(400);
+    expect(await response.json()).toMatchObject({
+      code: "INVALID_INPUT",
+      requestId: "request-document-route",
+      retryable: false,
+    });
+  });
+
+  test("cancel 本地错误 envelope 使用当前 guard requestId", async () => {
+    const app = new RouteHarness();
+    registerDocumentRunRoutes(
+      app,
+      {
+        async cancel() {
+          throw new DocumentFacadeError(
+            "RUNTIME_UNAVAILABLE",
+            "Document Runtime 暂时不可用",
+            503,
+            true,
+          );
+        },
+      } as unknown as DocumentRunFacade,
+      {} as DocumentRuntimePort,
+    );
+    const response = await app.call("POST", "/document/runs/:runId/cancel", {
+      body: {},
+      params: { runId: "run-test" },
+      query: {},
+      request: new Request(
+        "http://localhost/api/document/runs/run-test/cancel",
+      ),
+      guardContext: {
+        requestId: "request-document-cancel",
+        actor: {
+          id: "actor-1",
+          type: "user",
+          name: "分析员",
+          roleCodes: [],
+          permissionKeys: [],
+        },
+        startedAt: "2026-07-31T12:00:00.000Z",
+      },
+    });
+
+    expect(response.status).toBe(503);
+    expect(await response.json()).toEqual({
+      code: "RUNTIME_UNAVAILABLE",
+      message: "Document Runtime 暂时不可用",
+      requestId: "request-document-cancel",
+      retryable: true,
+    });
+  });
+});
+
+type Handler = (context: unknown) => unknown;
+
+class RouteHarness implements RouteApp {
+  readonly routes = new Map<string, Handler>();
+
+  get(path: string, handler: Handler) {
+    this.routes.set(`GET ${path}`, handler);
+  }
+  post(path: string, handler: Handler) {
+    this.routes.set(`POST ${path}`, handler);
+  }
+  put(path: string, handler: Handler) {
+    this.routes.set(`PUT ${path}`, handler);
+  }
+  delete(path: string, handler: Handler) {
+    this.routes.set(`DELETE ${path}`, handler);
+  }
+  async call(method: string, path: string, value: unknown) {
+    const handler = this.routes.get(`${method} ${path}`);
+    if (!handler) throw new Error("route missing");
+    return (await handler(value)) as Response;
+  }
+}

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

@@ -6,6 +6,10 @@ import type { RequestGuardContext } from "../guards.js";
 import type { RouteApp } from "../system/route-types.js";
 import type { DocumentRuntimePort } from "./contracts.js";
 import { DocumentFacadeError, type DocumentRunFacade } from "./facade.js";
+import {
+  documentEventsResponse,
+  documentResultResponse,
+} from "./facade-read-response.js";
 
 interface RouteContext {
   readonly body?: unknown;
@@ -38,7 +42,7 @@ export function registerDocumentRunRoutes(
         { status: 202 },
       );
     } catch (error) {
-      return knownError(error);
+      return knownError(error, context.guardContext.requestId);
     }
   });
 
@@ -46,14 +50,15 @@ export function registerDocumentRunRoutes(
     const context = raw as RouteContext;
     try {
       const runId = required(context.params.runId);
-      facade.authorizeRun(runId, context.guardContext);
-      return await remote.events(
+      await facade.authorizeRun(runId, context.guardContext);
+      return await documentEventsResponse(
+        remote,
         runId,
         cursor(context.query.after),
         context.request.signal,
       );
     } catch (error) {
-      return knownError(error);
+      return knownError(error, context.guardContext.requestId);
     }
   });
 
@@ -61,10 +66,14 @@ export function registerDocumentRunRoutes(
     const context = raw as RouteContext;
     try {
       const runId = required(context.params.runId);
-      facade.authorizeRun(runId, context.guardContext);
-      return await remote.result(runId, context.request.signal);
+      await facade.authorizeRun(runId, context.guardContext);
+      return await documentResultResponse(
+        remote,
+        runId,
+        context.request.signal,
+      );
     } catch (error) {
-      return knownError(error);
+      return knownError(error, context.guardContext.requestId);
     }
   });
 
@@ -72,15 +81,15 @@ export function registerDocumentRunRoutes(
     const context = raw as RouteContext;
     try {
       const runId = required(context.params.runId);
-      facade.authorizeRun(runId, context.guardContext);
       const body = isRecord(context.body) ? context.body : {};
-      return await remote.cancel(
+      return await facade.cancel(
         runId,
         typeof body.reason === "string" ? body.reason.slice(0, 200) : undefined,
+        context.guardContext,
         context.request.signal,
       );
     } catch (error) {
-      return knownError(error);
+      return knownError(error, context.guardContext.requestId);
     }
   });
 }
@@ -165,14 +174,14 @@ function invalid(message: string) {
   return new DocumentFacadeError("INVALID_INPUT", message, 400);
 }
 
-function knownError(error: unknown) {
+function knownError(error: unknown, requestId: string) {
   if (error instanceof DocumentFacadeError) {
     return Response.json(
       {
         code: error.code,
         message: error.message,
-        requestId: crypto.randomUUID(),
-        retryable: error.status >= 500,
+        requestId,
+        retryable: error.retryable,
       },
       { status: error.status },
     );
@@ -181,7 +190,7 @@ function knownError(error: unknown) {
     {
       code: "RUNTIME_UNAVAILABLE",
       message: "Document Runtime 暂不可用",
-      requestId: crypto.randomUUID(),
+      requestId,
       retryable: true,
     },
     { status: 503 },