create-windy 0.5.1 → 0.6.0

package/template/apps/server/src/ai-output-artifact/routes-storage-error.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import {
+  ModuleStorageError,
+  type ModuleStorageErrorCode,
+  type ModuleStorageWritePortV1,
+} from "@southwind-ai/server-sdk";
+import { registerAiOutputArtifactRoutes } from "./routes.js";
+import {
+  outputRouteContext,
+  outputRouteHeaders,
+  outputRouteInternalToken,
+  OutputRouteHarness,
+} from "./routes.test-support.js";
+import {
+  createOutputArtifactFixture,
+  outputByteStream,
+  outputHash,
+  outputManifest,
+} from "./test-support.js";
+
+describe("AI Output Artifact Storage error mapping", () => {
+  test("Storage 错误稳定映射为 Output code/status 且不透传正文", async () => {
+    for (const item of errorCases) {
+      const fixture = createOutputArtifactFixture();
+      const begun = await fixture.begin(`storage-${item.storageCode}`);
+      const bytes = new Uint8Array([1]);
+      const receipt = await fixture.service.beginArtifact(
+        begun.scope.scopeId,
+        begun.grant!,
+        outputManifest(bytes),
+        new AbortController().signal,
+      );
+      fixture.writers.create = () =>
+        ({
+          appendUploadPart() {
+            throw new ModuleStorageError(
+              item.storageCode,
+              "secret storage locator",
+            );
+          },
+        }) as unknown as ModuleStorageWritePortV1;
+      const app = new OutputRouteHarness();
+      registerAiOutputArtifactRoutes(
+        app,
+        fixture.service,
+        fixture.cleanup,
+        outputRouteInternalToken,
+      );
+
+      const response = await app.call(
+        "PUT",
+        "/internal/ai/output-artifacts/scopes/:scope/artifacts/:artifactId/parts/:partNumber",
+        outputRouteContext({
+          params: {
+            scope: begun.scope.scopeId,
+            artifactId: receipt.artifactId,
+            partNumber: "0",
+          },
+          headers: outputRouteHeaders(begun.grant, {
+            "content-length": "1",
+            "x-upload-offset": "0",
+            "x-content-sha256": outputHash(bytes),
+          }),
+          stream: outputByteStream(bytes),
+        }),
+      );
+      const body = await response.text();
+      expect(response.status).toBe(item.status);
+      expect(JSON.parse(body).code).toBe(item.outputCode);
+      expect(body).not.toContain("secret storage locator");
+    }
+  });
+});
+
+const errorCases: readonly {
+  storageCode: ModuleStorageErrorCode;
+  outputCode: string;
+  status: number;
+}[] = [
+  {
+    storageCode: "INVALID_UPLOAD",
+    outputCode: "OUTPUT_ARTIFACT_INVALID",
+    status: 400,
+  },
+  {
+    storageCode: "PART_TOO_LARGE",
+    outputCode: "OUTPUT_ARTIFACT_LIMIT_EXCEEDED",
+    status: 413,
+  },
+  {
+    storageCode: "UPLOAD_OFFSET_CONFLICT",
+    outputCode: "OUTPUT_ARTIFACT_CONFLICT",
+    status: 409,
+  },
+  {
+    storageCode: "UPLOAD_NOT_ACTIVE",
+    outputCode: "OUTPUT_ARTIFACT_NOT_READY",
+    status: 409,
+  },
+  {
+    storageCode: "STORAGE_UNAVAILABLE",
+    outputCode: "OUTPUT_ARTIFACT_UNAVAILABLE",
+    status: 503,
+  },
+];

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

@@ -0,0 +1,84 @@
+import { expect } from "bun:test";
+import type { RouteApp } from "../system/route-types.js";
+import { outputByteStream } from "./test-support.js";
+
+export const outputRouteInternalToken =
+  "internal-token-for-output-artifact-tests";
+
+type Handler = (context: unknown) => unknown;
+
+export class OutputRouteHarness implements RouteApp {
+  readonly routes = new Map<string, Handler>();
+
+  get(path: string, handler: Handler) {
+    this.routes.set(`GET ${path}`, handler);
+  }
+
+  post(path: string, handler: Handler, options?: { parse?: "none" }) {
+    expect(options).toEqual({ parse: "none" });
+    this.routes.set(`POST ${path}`, handler);
+  }
+
+  put(path: string, handler: Handler, options?: { parse?: "none" }) {
+    expect(options).toEqual({ parse: "none" });
+    this.routes.set(`PUT ${path}`, handler);
+  }
+
+  delete(path: string, handler: Handler, options?: { parse?: "none" }) {
+    expect(options).toEqual({ parse: "none" });
+    this.routes.set(`DELETE ${path}`, handler);
+  }
+
+  async call(method: string, path: string, value: unknown): Promise<Response> {
+    const handler = this.routes.get(`${method} ${path}`);
+    if (!handler) throw new Error(`route missing: ${method} ${path}`);
+    return (await handler(value)) as Response;
+  }
+}
+
+export function outputRouteHeaders(
+  grant?: string,
+  values: Record<string, string> = {},
+): Headers {
+  return new Headers({
+    authorization: `Bearer ${outputRouteInternalToken}`,
+    ...(grant ? { "x-ai-output-artifact-grant": grant } : {}),
+    ...values,
+  });
+}
+
+export function outputRouteContext(input: {
+  body?: unknown;
+  params?: Record<string, string>;
+  headers: Headers;
+  stream?: ReadableStream<Uint8Array>;
+  autoContentLength?: boolean;
+}) {
+  const encoded =
+    input.body === undefined
+      ? undefined
+      : new TextEncoder().encode(JSON.stringify(input.body));
+  if (
+    encoded &&
+    input.autoContentLength !== false &&
+    !input.headers.has("content-length")
+  ) {
+    input.headers.set("content-length", String(encoded.byteLength));
+  }
+  return {
+    params: input.params ?? {},
+    request: {
+      headers: input.headers,
+      body: input.stream ?? (encoded ? outputByteStream(encoded) : null),
+      signal: new AbortController().signal,
+    } as Request,
+  };
+}
+
+export function cancellableOutputBody(cancelled: unknown[]) {
+  return new ReadableStream<Uint8Array>({
+    cancel(reason) {
+      cancelled.push(reason);
+    },
+  });
+}

package/template/apps/server/src/ai-output-artifact/routes.test.ts

@@ -0,0 +1,198 @@
+import { describe, expect, test } from "bun:test";
+import { registerAiOutputArtifactRoutes } from "./routes.js";
+import {
+  cancellableOutputBody as cancellable,
+  outputRouteContext as context,
+  outputRouteHeaders as authorized,
+  outputRouteInternalToken as internalToken,
+  OutputRouteHarness as RouteHarness,
+} from "./routes.test-support.js";
+import {
+  createOutputArtifactFixture,
+  outputByteStream,
+  outputHash,
+  outputManifest,
+} from "./test-support.js";
+
+describe("AI Output Artifact internal routes", () => {
+  test("grant 只走 Header，完整流式 lifecycle 可幂等 complete/seal", async () => {
+    const fixture = createOutputArtifactFixture();
+    const app = new RouteHarness();
+    registerAiOutputArtifactRoutes(
+      app,
+      fixture.service,
+      fixture.cleanup,
+      internalToken,
+    );
+    const begun = await fixture.begin("route-lifecycle");
+    const bytes = new TextEncoder().encode("%PDF-1.7\nroute");
+    const created = await app.call(
+      "POST",
+      "/internal/ai/output-artifacts/scopes/:scope/artifacts",
+      context({
+        body: outputManifest(bytes),
+        params: { scope: begun.scope.scopeId },
+        headers: authorized(begun.grant),
+      }),
+    );
+    expect(created.status).toBe(201);
+    const receipt = await created.json();
+    expect(JSON.stringify(receipt)).not.toContain(begun.grant!);
+
+    const part = await app.call(
+      "PUT",
+      "/internal/ai/output-artifacts/scopes/:scope/artifacts/:artifactId/parts/:partNumber",
+      context({
+        params: {
+          scope: begun.scope.scopeId,
+          artifactId: String(receipt.artifactId),
+          partNumber: "0",
+        },
+        headers: authorized(begun.grant, {
+          "content-length": String(bytes.byteLength),
+          "x-upload-offset": "0",
+          "x-content-sha256": outputHash(bytes),
+        }),
+        stream: outputByteStream(bytes),
+      }),
+    );
+    expect(part.status).toBe(200);
+
+    const completePath =
+      "/internal/ai/output-artifacts/scopes/:scope/artifacts/:artifactId/complete";
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const completed = await app.call(
+        "POST",
+        completePath,
+        context({
+          params: {
+            scope: begun.scope.scopeId,
+            artifactId: String(receipt.artifactId),
+          },
+          headers: authorized(begun.grant, { "content-length": "0" }),
+        }),
+      );
+      expect(completed.status).toBe(200);
+      expect(await completed.json()).toMatchObject({ status: "completed" });
+    }
+
+    const sealPath = "/internal/ai/output-artifacts/scopes/:scope/seal";
+    const references: string[] = [];
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const sealed = await app.call(
+        "POST",
+        sealPath,
+        context({
+          params: { scope: begun.scope.scopeId },
+          headers: authorized(begun.grant, { "content-length": "0" }),
+        }),
+      );
+      expect(sealed.status).toBe(200);
+      expect(sealed.headers.get("cache-control")).toBe("private, no-store");
+      const payload = await sealed.json();
+      expect(JSON.stringify(payload)).not.toContain(begun.grant!);
+      references.push(String(payload.artifacts[0].value));
+    }
+    expect(references[1]).not.toBe(references[0]);
+
+    const opened = await app.call(
+      "GET",
+      "/internal/ai/output-artifacts",
+      context({
+        headers: authorized(undefined, {
+          "x-ai-output-artifact-ref": references[0]!,
+        }),
+      }),
+    );
+    expect(opened.headers.get("cache-control")).toBe("private, no-store");
+    expect(new Uint8Array(await opened.arrayBuffer())).toEqual(bytes);
+  });
+
+  test("拒绝额外治理字段、错误 grant、query ref 与无效 chunk headers", async () => {
+    const fixture = createOutputArtifactFixture();
+    const app = new RouteHarness();
+    registerAiOutputArtifactRoutes(
+      app,
+      fixture.service,
+      fixture.cleanup,
+      internalToken,
+    );
+    const begun = await fixture.begin("route-invalid");
+    const bytes = new Uint8Array([1]);
+    const extra = await app.call(
+      "POST",
+      "/internal/ai/output-artifacts/scopes/:scope/artifacts",
+      context({
+        body: { ...outputManifest(bytes), actorId: "forged-user" },
+        params: { scope: begun.scope.scopeId },
+        headers: authorized(begun.grant),
+      }),
+    );
+    expect(extra.status).toBe(400);
+
+    const cancelled: unknown[] = [];
+    const rejected = await app.call(
+      "PUT",
+      "/internal/ai/output-artifacts/scopes/:scope/artifacts/:artifactId/parts/:partNumber",
+      context({
+        params: {
+          scope: begun.scope.scopeId,
+          artifactId: `outartifact_${"a".repeat(32)}`,
+          partNumber: "0",
+        },
+        headers: authorized("outgrant_v1_invalid", {
+          "content-length": "1",
+          "x-upload-offset": "0",
+          "x-content-sha256": outputHash(bytes),
+        }),
+        stream: cancellable(cancelled),
+      }),
+    );
+    expect(rejected.status).toBe(403);
+    expect(cancelled).toEqual(["ai-output-artifact-rejected"]);
+    expect(await rejected.text()).not.toContain("outgrant_v1_invalid");
+
+    const invalidHeaders: Array<Record<string, string>> = [
+      {
+        "content-length": String(8 * 1_024 * 1_024 + 1),
+        "x-upload-offset": "0",
+        "x-content-sha256": outputHash(bytes),
+      },
+      {
+        "content-length": "1",
+        "x-upload-offset": "0",
+        "x-content-sha256": "not-a-hash",
+      },
+      {
+        "transfer-encoding": "chunked",
+        "x-upload-offset": "0",
+        "x-content-sha256": outputHash(bytes),
+      },
+    ];
+    for (const headers of invalidHeaders) {
+      const bodyCancelled: unknown[] = [];
+      const response = await app.call(
+        "PUT",
+        "/internal/ai/output-artifacts/scopes/:scope/artifacts/:artifactId/parts/:partNumber",
+        context({
+          params: {
+            scope: begun.scope.scopeId,
+            artifactId: `outartifact_${"b".repeat(32)}`,
+            partNumber: "0",
+          },
+          headers: authorized(begun.grant, headers),
+          stream: cancellable(bodyCancelled),
+        }),
+      );
+      expect(response.status).toBe(400);
+      expect(bodyCancelled).toEqual(["ai-output-artifact-rejected"]);
+    }
+
+    const queryOnlyReference = await app.call(
+      "GET",
+      "/internal/ai/output-artifacts",
+      context({ headers: authorized() }),
+    );
+    expect(queryOnlyReference.status).toBe(403);
+  });
+});

package/template/apps/server/src/ai-output-artifact/routes.ts

@@ -0,0 +1,280 @@
+import { timingSafeEqual } from "node:crypto";
+import type { RouteApp } from "../system/route-types.js";
+import { AiOutputArtifactError } from "./contracts.js";
+import type { AiOutputArtifactCleanupService } from "./cleanup.js";
+import {
+  type AiOutputArtifactRouteContext as RouteContext,
+  outputPartInput,
+  readOutputManifest,
+  rejectOutputBody,
+  requireEmptyOutputRequest,
+} from "./route-input.js";
+import type { AiOutputArtifactService } from "./service.js";
+
+const grantHeader = "x-ai-output-artifact-grant";
+const referenceHeader = "x-ai-output-artifact-ref";
+const scopePattern = /^outscope_[a-f0-9]{32}$/;
+const artifactPattern = /^outartifact_[a-f0-9]{32}$/;
+
+export function registerAiOutputArtifactRoutes(
+  app: RouteApp,
+  service: AiOutputArtifactService,
+  cleanup: AiOutputArtifactCleanupService,
+  internalToken: string,
+): void {
+  app.post(
+    "/internal/ai/output-artifacts/scopes/:scope/grants/:generation/accept",
+    (raw) =>
+      execute(raw, internalToken, async (context) => {
+        await requireEmptyOutputRequest(context);
+        await service.acceptGrant(
+          scopeId(context),
+          credentialGeneration(context),
+          requiredGrant(context),
+        );
+        return new Response(null, {
+          status: 204,
+          headers: { "cache-control": "private, no-store" },
+        });
+      }),
+    { parse: "none" },
+  );
+
+  app.post(
+    "/internal/ai/output-artifacts/scopes/:scope/artifacts",
+    (raw) =>
+      execute(raw, internalToken, async (context) => {
+        const scope = scopeId(context);
+        const grant = requiredGrant(context);
+        await service.preauthorizeWrite(scope, grant);
+        const created = await service.beginArtifact(
+          scope,
+          grant,
+          await readOutputManifest(context),
+          context.request.signal,
+        );
+        return Response.json(created, { status: 201 });
+      }),
+    { parse: "none" },
+  );
+
+  app.put(
+    "/internal/ai/output-artifacts/scopes/:scope/artifacts/:artifactId/parts/:partNumber",
+    async (raw) => {
+      const context = raw as RouteContext;
+      try {
+        requireInternal(context, internalToken);
+        const input = outputPartInput(context);
+        const part = await service.appendPart(
+          scopeId(context),
+          requiredGrant(context),
+          {
+            artifactId: artifactId(context),
+            ...input,
+          },
+          context.request.signal,
+        );
+        return Response.json({
+          contractVersion: 1,
+          partNumber: part.partNumber,
+          byteOffset: part.byteOffset,
+          byteSize: part.byteSize,
+          sha256: part.sha256,
+        });
+      } catch (error) {
+        rejectOutputBody(context.request.body);
+        return errorResponse(error);
+      }
+    },
+    { parse: "none" },
+  );
+
+  app.post(
+    "/internal/ai/output-artifacts/scopes/:scope/artifacts/:artifactId/complete",
+    (raw) =>
+      execute(raw, internalToken, async (context) => {
+        await requireEmptyOutputRequest(context);
+        const result = await service.completeArtifact(
+          scopeId(context),
+          requiredGrant(context),
+          artifactId(context),
+          context.request.signal,
+        );
+        return Response.json(result);
+      }),
+    { parse: "none" },
+  );
+
+  app.post(
+    "/internal/ai/output-artifacts/scopes/:scope/seal",
+    (raw) =>
+      execute(raw, internalToken, async (context) => {
+        await requireEmptyOutputRequest(context);
+        return Response.json(
+          {
+            contractVersion: 1,
+            artifacts: await service.sealScope(
+              scopeId(context),
+              requiredGrant(context),
+            ),
+          },
+          { headers: { "cache-control": "private, no-store" } },
+        );
+      }),
+    { parse: "none" },
+  );
+
+  app.delete(
+    "/internal/ai/output-artifacts/scopes/:scope/open",
+    (raw) =>
+      execute(raw, internalToken, async (context) => {
+        await requireEmptyOutputRequest(context);
+        const aborted = await cleanup.abortOpenAuthorized(
+          service,
+          scopeId(context),
+          requiredGrant(context),
+          context.request.signal,
+        );
+        if (!aborted) throw unavailable();
+        return new Response(null, { status: 204 });
+      }),
+    { parse: "none" },
+  );
+
+  app.delete(
+    "/internal/ai/output-artifacts/scopes/:scope",
+    (raw) =>
+      execute(raw, internalToken, async (context) => {
+        await requireEmptyOutputRequest(context);
+        const aborted = await cleanup.abortAuthorized(
+          service,
+          scopeId(context),
+          requiredGrant(context),
+        );
+        if (!aborted) throw unavailable();
+        return new Response(null, { status: 204 });
+      }),
+    { parse: "none" },
+  );
+
+  app.get("/internal/ai/output-artifacts", (raw) =>
+    execute(raw, internalToken, async (context) => {
+      const reference = context.request.headers.get(referenceHeader);
+      if (!reference) throw forbidden();
+      const opened = await service.openReference(
+        reference,
+        context.request.signal,
+      );
+      return new Response(opened.body, {
+        headers: {
+          "cache-control": "private, no-store",
+          "content-type": opened.mimeType,
+          "content-length": String(opened.byteSize),
+          "x-content-sha256": opened.contentHash.value,
+        },
+      });
+    }),
+  );
+}
+
+async function execute(
+  raw: unknown,
+  token: string,
+  handler: (context: RouteContext) => Promise<Response>,
+): Promise<Response> {
+  const context = raw as RouteContext;
+  try {
+    requireInternal(context, token);
+    return await handler(context);
+  } catch (error) {
+    rejectOutputBody(context.request.body);
+    return errorResponse(error);
+  }
+}
+
+function requireInternal(context: RouteContext, expected: string): void {
+  const provided = context.request.headers
+    .get("authorization")
+    ?.replace(/^Bearer /, "");
+  if (!provided || !expected) throw forbidden();
+  const left = Buffer.from(provided);
+  const right = Buffer.from(expected);
+  if (left.length !== right.length || !timingSafeEqual(left, right)) {
+    throw forbidden();
+  }
+}
+
+function requiredGrant(context: RouteContext): string {
+  const value = context.request.headers.get(grantHeader);
+  if (!value) throw forbidden();
+  return value;
+}
+
+function scopeId(context: RouteContext): string {
+  const value = context.params.scope;
+  if (!value || !scopePattern.test(value)) throw forbidden();
+  return value;
+}
+
+function artifactId(context: RouteContext): string {
+  const value = context.params.artifactId;
+  if (!value || !artifactPattern.test(value)) throw forbidden();
+  return value;
+}
+
+function credentialGeneration(context: RouteContext): number {
+  const value = context.params.generation;
+  if (!value || !/^[1-9]\d*$/.test(value)) throw forbidden();
+  const generation = Number(value);
+  if (!Number.isSafeInteger(generation)) throw forbidden();
+  return generation;
+}
+
+function errorResponse(error: unknown): Response {
+  if (error instanceof AiOutputArtifactError) {
+    return Response.json(
+      {
+        code: error.code,
+        message: error.message,
+        retryable: error.retryable,
+      },
+      { status: errorStatus(error.code) },
+    );
+  }
+  return Response.json(
+    {
+      code: "OUTPUT_ARTIFACT_UNAVAILABLE",
+      message: "AI Output Artifact 暂时不可用",
+      retryable: true,
+    },
+    { status: 503 },
+  );
+}
+
+function errorStatus(code: AiOutputArtifactError["code"]): number {
+  if (code === "OUTPUT_ARTIFACT_INVALID") return 400;
+  if (code === "OUTPUT_ARTIFACT_FORBIDDEN") return 403;
+  if (code === "OUTPUT_ARTIFACT_LIMIT_EXCEEDED") return 413;
+  if (
+    code === "OUTPUT_ARTIFACT_CONFLICT" ||
+    code === "OUTPUT_ARTIFACT_NOT_READY"
+  ) {
+    return 409;
+  }
+  return 503;
+}
+
+function forbidden() {
+  return new AiOutputArtifactError(
+    "OUTPUT_ARTIFACT_FORBIDDEN",
+    "AI Output Artifact 当前不可访问",
+  );
+}
+
+function unavailable() {
+  return new AiOutputArtifactError(
+    "OUTPUT_ARTIFACT_UNAVAILABLE",
+    "AI Output Artifact 暂时不可用",
+    true,
+  );
+}