create-windy 0.5.2 → 0.6.1

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

@@ -0,0 +1,283 @@
+import { describe, expect, test } from "bun:test";
+import { ModuleStorageError } from "@southwind-ai/server-sdk";
+import { AiOutputArtifactError } from "./contracts.js";
+import {
+  createOutputArtifactFixture as createFixture,
+  outputByteStream as byteStream,
+  outputHash as hash,
+  outputManifest as manifest,
+} from "./test-support.js";
+
+describe("AI Output Artifact Sink", () => {
+  test("流式发布、seal 后重检授权并返回同一字节", async () => {
+    const fixture = createFixture();
+    const begun = await fixture.begin("request-1");
+    expect(begun.descriptor).toBeDefined();
+    expect(begun.descriptor).toMatchObject({
+      contractVersion: 1,
+      outputKind: "searchable-pdf",
+      allowedMediaTypes: ["application/pdf"],
+      limits: {
+        maxArtifactBytes: 1024 * 1024,
+        maxArtifacts: 2,
+        maxTotalBytes: 1024 * 1024,
+      },
+    });
+    expect(begun.descriptor).not.toHaveProperty("url");
+    expect(begun.descriptor).not.toHaveProperty("actorId");
+    expect(begun.descriptor).not.toHaveProperty("grant");
+    expect(begun.grant).toMatch(/^outgrant_/);
+    expect(begun.scope.grantHash).toMatch(/^[a-f0-9]{64}$/);
+    expect(JSON.stringify(begun.scope)).not.toContain(begun.grant!);
+    expect(JSON.stringify(begun.descriptor)).not.toContain(begun.grant!);
+
+    const bytes = new TextEncoder().encode("%PDF-1.7\nsearchable");
+    const artifact = await fixture.service.beginArtifact(
+      begun.scope.scopeId,
+      begun.grant!,
+      manifest(bytes),
+      new AbortController().signal,
+    );
+    expect(artifact.status).toBe("uploading");
+    await fixture.service.appendPart(
+      begun.scope.scopeId,
+      begun.grant!,
+      {
+        artifactId: artifact.artifactId,
+        partNumber: 0,
+        byteOffset: 0,
+        byteSize: bytes.byteLength,
+        sha256: hash(bytes),
+        body: byteStream(bytes),
+      },
+      new AbortController().signal,
+    );
+    const completion = await fixture.service.completeArtifact(
+      begun.scope.scopeId,
+      begun.grant!,
+      artifact.artifactId,
+      new AbortController().signal,
+    );
+    expect(completion).toMatchObject({
+      contractVersion: 1,
+      artifactId: artifact.artifactId,
+      status: "completed",
+    });
+    expect(completion).not.toHaveProperty("value");
+
+    const sealed = await fixture.service.sealScope(
+      begun.scope.scopeId,
+      begun.grant!,
+    );
+    const opened = await fixture.service.openReference(
+      sealed[0]!.value,
+      new AbortController().signal,
+    );
+    expect(
+      new Uint8Array(await new Response(opened.body).arrayBuffer()),
+    ).toEqual(bytes);
+    const originalOpen = fixture.storage.files.open.bind(fixture.storage.files);
+    fixture.storage.files.open = async (...args) => ({
+      ...(await originalOpen(...args)),
+      purpose: "forged-purpose",
+    });
+    await expect(
+      fixture.service.openReference(
+        sealed[0]!.value,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+    expect(fixture.readOutcomes).toEqual(["success", "denied"]);
+  });
+
+  test("幂等重放轮换 grant，旧 token 立即失效且语义漂移冲突", async () => {
+    const fixture = createFixture();
+    const first = await fixture.begin("same-key");
+    const replay = await fixture.begin("same-key");
+    expect(replay.scope.runId).toBe(first.scope.runId);
+    expect(replay.grant).not.toBe(first.grant);
+    await expect(
+      fixture.service.beginArtifact(
+        first.scope.scopeId,
+        first.grant!,
+        manifest(new Uint8Array([1])),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+    await expect(fixture.begin("same-key", "internal")).rejects.toBeInstanceOf(
+      AiOutputArtifactError,
+    );
+  });
+
+  test("run 与 idempotency 双向绑定，既不跨 run 串 scope 也不换 key 重放", async () => {
+    const fixture = createFixture();
+    const first = await fixture.begin("reusable-key", "sensitive", {
+      runId: "run_first",
+    });
+    const second = await fixture.begin("reusable-key", "sensitive", {
+      runId: "run_second",
+    });
+    expect(second.scope.runId).toBe("run_second");
+    expect(second.scope.scopeId).not.toBe(first.scope.scopeId);
+    await expect(
+      fixture.begin("changed-key", "sensitive", { runId: "run_first" }),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_CONFLICT" });
+  });
+
+  test("取消先撤销引用，再幂等清理文件和上传会话", async () => {
+    const fixture = createFixture();
+    const begun = await fixture.begin("cancel-1");
+    const bytes = new TextEncoder().encode("%PDF-1.7\ncancel");
+    const artifact = await fixture.service.beginArtifact(
+      begun.scope.scopeId,
+      begun.grant!,
+      manifest(bytes),
+      new AbortController().signal,
+    );
+    await fixture.service.appendPart(
+      begun.scope.scopeId,
+      begun.grant!,
+      {
+        artifactId: artifact.artifactId,
+        partNumber: 0,
+        byteOffset: 0,
+        byteSize: bytes.byteLength,
+        sha256: hash(bytes),
+        body: byteStream(bytes),
+      },
+      new AbortController().signal,
+    );
+    await fixture.service.completeArtifact(
+      begun.scope.scopeId,
+      begun.grant!,
+      artifact.artifactId,
+      new AbortController().signal,
+    );
+    const [reference] = await fixture.service.sealScope(
+      begun.scope.scopeId,
+      begun.grant!,
+    );
+    expect(await fixture.cleanup.abortRun(begun.scope.runId)).toBe(true);
+    await expect(
+      fixture.service.openReference(
+        reference!.value,
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_FORBIDDEN" });
+    expect(
+      (await fixture.repository.getScope(begun.scope.scopeId))?.status,
+    ).toBe("aborted");
+    expect(await fixture.cleanup.abortRun(begun.scope.runId)).toBe(true);
+  });
+
+  test("manifest 的类型、大小和总数由 Host 策略失败关闭", async () => {
+    const fixture = createFixture();
+    const begun = await fixture.begin("limit-1");
+    await expect(
+      fixture.service.beginArtifact(
+        begun.scope.scopeId,
+        begun.grant!,
+        {
+          ...manifest(new Uint8Array([1])),
+          mediaType: "text/html",
+        },
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_INVALID" });
+  });
+
+  test("文件名、扩展名与 MIME 在 claim 前按 Storage 同一规则 canonicalize", async () => {
+    const canonical = createFixture();
+    const begun = await canonical.begin("canonical-file");
+    const receipt = await canonical.service.beginArtifact(
+      begun.scope.scopeId,
+      begun.grant!,
+      {
+        ...manifest(new Uint8Array([1])),
+        filename: " searchable.pdf ",
+        mediaType: "APPLICATION/PDF; charset=binary",
+      },
+      new AbortController().signal,
+    );
+    const stored = await canonical.repository.getArtifact(receipt.artifactId);
+    const session = await canonical.storage.repository.getSession(
+      stored!.uploadSessionId!,
+    );
+    expect(stored).toMatchObject({
+      filename: "searchable.pdf",
+      mimeType: "application/pdf",
+    });
+    expect(session).toMatchObject({
+      filename: "searchable.pdf",
+      mimeType: "application/pdf",
+    });
+
+    for (const [key, filename] of [
+      ["path", "foo/bar.pdf"],
+      ["extension", "searchable.txt"],
+    ] as const) {
+      const invalid = createFixture();
+      const invalidScope = await invalid.begin(`invalid-${key}`);
+      await expect(
+        invalid.service.beginArtifact(
+          invalidScope.scope.scopeId,
+          invalidScope.grant!,
+          { ...manifest(new Uint8Array([1])), filename },
+          new AbortController().signal,
+        ),
+      ).rejects.toMatchObject({ code: "OUTPUT_ARTIFACT_INVALID" });
+      expect(
+        await invalid.repository.listArtifacts(invalidScope.scope.scopeId),
+      ).toEqual([]);
+      expect(
+        (await invalid.repository.getScope(invalidScope.scope.scopeId))
+          ?.artifactCount,
+      ).toBe(0);
+    }
+  });
+
+  test("Storage create 短暂失败保留 creating claim，重试可恢复", async () => {
+    const fixture = createFixture();
+    const begun = await fixture.begin("storage-create-retry");
+    const create = fixture.writers.create.bind(fixture.writers);
+    let unavailable = true;
+    fixture.writers.create = (...args) => {
+      const writer = create(...args);
+      return {
+        ...writer,
+        createUploadSession: unavailable
+          ? async () => {
+              throw new ModuleStorageError(
+                "STORAGE_UNAVAILABLE",
+                "temporary failure",
+              );
+            }
+          : writer.createUploadSession,
+      };
+    };
+    await expect(
+      fixture.service.beginArtifact(
+        begun.scope.scopeId,
+        begun.grant!,
+        manifest(new Uint8Array([1])),
+        new AbortController().signal,
+      ),
+    ).rejects.toMatchObject({
+      code: "OUTPUT_ARTIFACT_UNAVAILABLE",
+      retryable: true,
+    });
+    expect(
+      (await fixture.repository.listArtifacts(begun.scope.scopeId))[0]?.status,
+    ).toBe("creating");
+
+    unavailable = false;
+    await expect(
+      fixture.service.beginArtifact(
+        begun.scope.scopeId,
+        begun.grant!,
+        manifest(new Uint8Array([1])),
+        new AbortController().signal,
+      ),
+    ).resolves.toMatchObject({ contractVersion: 1, status: "uploading" });
+  });
+});

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

@@ -0,0 +1,334 @@
+import type {
+  AiOutputArtifactBeginResultV1,
+  AiOutputArtifactCompletionV1,
+  AiOutputArtifactManifestItemV1,
+  AiOutputArtifactReferenceV1,
+} from "./contracts.js";
+import { matchesAiOutputArtifactGrant } from "./grant.js";
+import type { AiOutputArtifactRepository } from "./repository.js";
+import { AiOutputArtifactRepositoryError } from "./repository.js";
+import {
+  opaque,
+  outputArtifactFingerprint,
+  type BeginAiOutputArtifactScopeInput,
+} from "./service-input.js";
+import type { AiOutputArtifactStorageWriterFactory } from "./storage-writer.js";
+import { completeOutputArtifact } from "./service-completion.js";
+import {
+  openOutputArtifactReference,
+  type AiOutputArtifactReadDependencies,
+} from "./service-read.js";
+import {
+  outputArtifactReceipt,
+  outputArtifactCompletion,
+  outputArtifactReference,
+  outputConflict,
+  outputForbidden,
+  outputLimitExceeded,
+  outputNotReady,
+  outputInvalid,
+  outputStorageError,
+  validateOutputManifestItem,
+} from "./service-support.js";
+import {
+  acceptOutputGrant,
+  confirmOutputGrant,
+  prepareOutputScope,
+  rollbackPendingOutputGrant,
+} from "./service-grants.js";
+
+export type { AiOutputArtifactReadAuthorization } from "./service-read.js";
+
+export interface AiOutputArtifactServiceOptions extends AiOutputArtifactReadDependencies {
+  readonly repository: AiOutputArtifactRepository;
+  readonly writers: AiOutputArtifactStorageWriterFactory;
+  readonly now?: () => Date;
+}
+
+export class AiOutputArtifactService {
+  readonly #now: () => Date;
+
+  constructor(readonly options: AiOutputArtifactServiceOptions) {
+    this.#now = options.now ?? (() => new Date());
+  }
+
+  async beginScope(input: BeginAiOutputArtifactScopeInput) {
+    return prepareOutputScope({ ...this.options, now: this.#now }, input);
+  }
+
+  async acceptGrant(scopeId: string, generation: number, token: string) {
+    return acceptOutputGrant(
+      { ...this.options, now: this.#now },
+      scopeId,
+      generation,
+      token,
+    );
+  }
+
+  async confirmGrant(scopeId: string, generation: number, token: string) {
+    return confirmOutputGrant(
+      { ...this.options, now: this.#now },
+      scopeId,
+      generation,
+      token,
+    );
+  }
+
+  async rollbackPendingGrant(
+    scopeId: string,
+    generation: number,
+    token: string,
+  ) {
+    return rollbackPendingOutputGrant(
+      { ...this.options, now: this.#now },
+      scopeId,
+      generation,
+      token,
+    );
+  }
+
+  async beginArtifact(
+    scopeId: string,
+    grant: string,
+    input: AiOutputArtifactManifestItemV1,
+    signal: AbortSignal,
+  ): Promise<AiOutputArtifactBeginResultV1> {
+    const scope = await this.requireWritable(scopeId, grant);
+    const manifest = validateOutputManifestItem(scope, input);
+    const createdAt = this.#now().toISOString();
+    let claim;
+    try {
+      claim = await this.options.repository.claimArtifact({
+        artifactId: opaque("outartifact"),
+        scopeId,
+        outputKey: manifest.outputKey,
+        fingerprint: outputArtifactFingerprint({
+          outputKey: manifest.outputKey,
+          outputKind: manifest.outputKind,
+          filename: manifest.filename,
+          mediaType: manifest.mediaType,
+          byteSize: manifest.byteSize,
+          sha256: manifest.sha256,
+        }),
+        filename: manifest.filename,
+        mimeType: manifest.mediaType,
+        expectedByteSize: manifest.byteSize,
+        expectedSha256: manifest.sha256,
+        createdAt,
+      });
+    } catch (error) {
+      if (error instanceof AiOutputArtifactRepositoryError) {
+        if (error.code === "LIMIT") throw outputLimitExceeded();
+        throw outputConflict();
+      }
+      throw error;
+    }
+    if (!claim.claimed) {
+      if (
+        claim.artifact.fingerprint !==
+        outputArtifactFingerprint({
+          outputKey: manifest.outputKey,
+          outputKind: manifest.outputKind,
+          filename: manifest.filename,
+          mediaType: manifest.mediaType,
+          byteSize: manifest.byteSize,
+          sha256: manifest.sha256,
+        })
+      ) {
+        throw outputConflict();
+      }
+      return outputArtifactReceipt(claim.artifact);
+    }
+    const writer = this.options.writers.create(scope, signal);
+    let session;
+    try {
+      session = await writer.createUploadSession({
+        purpose: scope.purpose,
+        filename: manifest.filename,
+        mimeType: manifest.mediaType,
+        expectedByteSize: manifest.byteSize,
+        expectedSha256: manifest.sha256,
+      });
+    } catch (error) {
+      throw outputStorageError(error);
+    }
+    const bound = await this.options.repository.bindUploadSession(
+      claim.artifact.artifactId,
+      claim.artifact.generation,
+      session.id,
+      this.#now().toISOString(),
+    );
+    if (!bound) {
+      await writer.abortUpload(session.id).catch(() => undefined);
+      throw outputConflict();
+    }
+    return outputArtifactReceipt(bound);
+  }
+
+  async appendPart(
+    scopeId: string,
+    grant: string,
+    input: {
+      artifactId: string;
+      partNumber: number;
+      byteOffset: number;
+      byteSize: number;
+      sha256: string;
+      body: ReadableStream<Uint8Array>;
+    },
+    signal: AbortSignal,
+  ) {
+    const scope = await this.requireWritable(scopeId, grant);
+    if (
+      !Number.isSafeInteger(input.partNumber) ||
+      input.partNumber < 0 ||
+      !Number.isSafeInteger(input.byteOffset) ||
+      input.byteOffset < 0 ||
+      !Number.isSafeInteger(input.byteSize) ||
+      input.byteSize <= 0 ||
+      input.byteSize > 8 * 1_024 * 1_024 ||
+      !/^[a-f0-9]{64}$/.test(input.sha256)
+    ) {
+      throw outputInvalid();
+    }
+    const artifact = await this.requireArtifact(scopeId, input.artifactId);
+    if (artifact.status !== "uploading" || !artifact.uploadSessionId) {
+      throw outputNotReady();
+    }
+    try {
+      return await this.options.writers.create(scope, signal).appendUploadPart({
+        sessionId: artifact.uploadSessionId,
+        partNumber: input.partNumber,
+        byteOffset: input.byteOffset,
+        byteSize: input.byteSize,
+        sha256: input.sha256,
+        body: input.body,
+      });
+    } catch (error) {
+      throw outputStorageError(error);
+    }
+  }
+
+  async completeArtifact(
+    scopeId: string,
+    grant: string,
+    artifactId: string,
+    signal: AbortSignal,
+  ): Promise<AiOutputArtifactCompletionV1> {
+    const scope = await this.requireWritable(scopeId, grant);
+    const artifact = await this.requireArtifact(scopeId, artifactId);
+    const completed = await completeOutputArtifact(
+      { ...this.options, now: this.#now },
+      scope,
+      artifact,
+      signal,
+    );
+    return outputArtifactCompletion(completed);
+  }
+
+  async sealScope(
+    scopeId: string,
+    grant: string,
+  ): Promise<readonly AiOutputArtifactReferenceV1[]> {
+    const existing = await this.options.repository.getScope(scopeId);
+    if (
+      existing?.status === "sealed" &&
+      existing.grantHash &&
+      existing.refExpiresAt > this.#now().toISOString() &&
+      matchesAiOutputArtifactGrant(grant, existing.grantHash)
+    ) {
+      const artifacts = await this.options.repository.listArtifacts(scopeId);
+      return artifacts.map((artifact) =>
+        outputArtifactReference(existing, artifact, this.options.references),
+      );
+    }
+    const scope = await this.requireWritable(scopeId, grant);
+    const referenceTtlMs =
+      Date.parse(scope.refExpiresAt) - Date.parse(scope.scopeExpiresAt);
+    const refExpiresAt = new Date(
+      this.#now().getTime() + referenceTtlMs,
+    ).toISOString();
+    const sealed = await this.options.repository.sealScope(
+      scopeId,
+      scope.revision,
+      refExpiresAt,
+      this.#now().toISOString(),
+    );
+    if (!sealed) throw outputNotReady();
+    const artifacts = await this.options.repository.listArtifacts(scopeId);
+    return artifacts.map((artifact) =>
+      outputArtifactReference(sealed, artifact, this.options.references),
+    );
+  }
+
+  async claimSealedScope(scopeId: string) {
+    const scope = await this.options.repository.getScope(scopeId);
+    if (
+      !scope ||
+      scope.status !== "sealed" ||
+      scope.refExpiresAt <= this.#now().toISOString()
+    ) {
+      throw outputNotReady();
+    }
+    const artifacts = await this.options.repository.listArtifacts(scopeId);
+    if (
+      !artifacts.length ||
+      artifacts.length !== scope.artifactCount ||
+      artifacts.some(({ status }) => status !== "completed")
+    ) {
+      throw outputNotReady();
+    }
+    return artifacts.map((artifact) =>
+      outputArtifactReference(scope, artifact, this.options.references),
+    );
+  }
+
+  async openReference(token: string, signal: AbortSignal) {
+    return openOutputArtifactReference(
+      this.options,
+      token,
+      this.#now().toISOString(),
+      signal,
+    );
+  }
+
+  async preauthorizeWrite(scopeId: string, token: string) {
+    await this.requireWritable(scopeId, token);
+  }
+
+  async requireWritable(scopeId: string, token: string) {
+    const scope = await this.options.repository.getScope(scopeId);
+    if (
+      !scope ||
+      scope.status !== "open" ||
+      !scope.grantHash ||
+      scope.scopeExpiresAt <= this.#now().toISOString() ||
+      !matchesAiOutputArtifactGrant(token, scope.grantHash)
+    ) {
+      throw outputForbidden();
+    }
+    return scope;
+  }
+
+  async requireRevocable(scopeId: string, token: string) {
+    const scope = await this.options.repository.getScope(scopeId);
+    if (
+      !scope ||
+      !["open", "sealed", "aborting", "cleanup-pending", "aborted"].includes(
+        scope.status,
+      ) ||
+      !scope.grantHash ||
+      scope.refExpiresAt <= this.#now().toISOString() ||
+      !matchesAiOutputArtifactGrant(token, scope.grantHash)
+    ) {
+      throw outputForbidden();
+    }
+    return scope;
+  }
+
+  private async requireArtifact(scopeId: string, artifactId: string) {
+    const artifact = await this.options.repository.getArtifact(artifactId);
+    if (!artifact || artifact.scopeId !== scopeId) throw outputForbidden();
+    return artifact;
+  }
+}

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

@@ -0,0 +1,33 @@
+import type { StorageRuntime } from "../storage/runtime.js";
+import type {
+  AiOutputArtifactRecord,
+  AiOutputArtifactScope,
+} from "./contracts.js";
+
+export async function purgeCompletedOutputUpload(
+  storage: StorageRuntime,
+  scope: AiOutputArtifactScope,
+  artifact: AiOutputArtifactRecord,
+  signal: AbortSignal,
+): Promise<boolean> {
+  if (!artifact.uploadSessionId) return false;
+  return storage.uploads.purgeCompletedBound(
+    {
+      sessionId: artifact.uploadSessionId,
+      ownerId: scope.actorId,
+      purpose: scope.purpose,
+      authorizationBinding: {
+        moduleName: scope.moduleName,
+        scopeHash: scope.scopeHash,
+      },
+      filename: artifact.filename,
+      mimeType: artifact.mimeType,
+      expectedByteSize: artifact.expectedByteSize,
+      expectedSha256: artifact.expectedSha256,
+      fileExpiresAfter: scope.refExpiresAt,
+      fileExpiresAt: scope.fileExpiresAt,
+      expectedFileId: artifact.fileId,
+    },
+    signal,
+  );
+}