create-windy 0.5.2 → 0.6.0

package/template/apps/server/src/embedding/facade.ts

@@ -1,17 +1,10 @@
 import { randomUUIDv7 } from "bun";
-import type {
-  ModuleAiOperationDefinition,
-  ModuleManifest,
-} from "@southwind-ai/modules";
+import type { ModuleManifest } from "@southwind-ai/modules";
 import { resolveProviderEgress } from "@southwind-ai/modules";
-import type {
-  ModuleAiJsonValue,
-  ModuleAiOperationHandlerRegistration,
-} from "@southwind-ai/server-sdk";
-import { evaluateAccessGuards } from "../access-guards.js";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
 import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
 import { scopedRuntimeIdempotencyKey } from "../agent/idempotency-key.js";
-import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { RequestGuardContext } from "../guards.js";
 import type { InitializedModuleHosts } from "../module-host.js";
 import { toModuleActor } from "../module-host.js";
 import { findFeature } from "../route-guards.js";
@@ -28,6 +21,16 @@ import {
   runtimeItems,
   type EmbeddingFacadeItem,
 } from "./input.js";
+import { EmbeddingRunAuthorizations } from "./run-authorization.js";
+import { recordEmbeddingAudit } from "./audit.js";
+import { embeddingRunFingerprint } from "./run-fingerprint.js";
+import { observeEmbeddingTerminal } from "./terminal-observer.js";
+import { authorizeEmbeddingOperation } from "./operation-authorization.js";
+import { runArtifact, unavailableArtifact } from "./run-artifact.js";
+import {
+  embeddingErrorStatus,
+  type RegisteredEmbeddingOperation,
+} from "./facade-types.js";
 
 export class EmbeddingFacade {
   readonly #operations: Map<string, RegisteredEmbeddingOperation>;
@@ -38,6 +41,7 @@ export class EmbeddingFacade {
     private readonly runtime: ReturnType<typeof createServerRuntime>,
     private readonly remote: EmbeddingRuntimePort,
     private readonly artifacts: AiArtifactRuntime,
+    private readonly runs: EmbeddingRunAuthorizations,
   ) {
     const handlers = new Map(
       hosts.aiOperationHandlers.map(({ registration, moduleName }) => [
@@ -73,67 +77,16 @@ export class EmbeddingFacade {
     context: RequestGuardContext,
     signal: AbortSignal,
   ): Promise<EmbeddingBatchResponse> {
-    const operation = this.#operations.get(operationKey);
-    if (!operation?.registration?.prepareEmbedding || !operation.moduleName) {
-      throw new EmbeddingFacadeError(
-        "OPERATION_NOT_FOUND",
-        "Embedding Operation 不存在",
-        404,
-      );
-    }
-    await this.authorize(operation, context);
-    const governed = governEmbeddingInput(items, options, operation.definition);
-    const plan = await operation.registration.prepareEmbedding(governed, {
-      actor: toModuleActor(context.actor),
-      requestId: context.requestId,
-    });
-    const prepared = await runtimeItems(
+    const prepared = await this.prepare(
+      operationKey,
       items,
-      governed,
-      operation.definition,
-      operation.moduleName,
-      this.artifacts,
+      options,
       context,
       signal,
     );
-    const maxUnits = operation.definition.limits.maxUnits;
-    if (!maxUnits) {
-      throw new EmbeddingFacadeError(
-        "INVALID_CONFIGURATION",
-        "Embedding Operation 未声明批量上限",
-        503,
-      );
-    }
     try {
       const result = await this.remote.embed(
-        {
-          kind: "embedding",
-          operationKey,
-          items: prepared,
-          options: plan.options ?? governedEmbeddingOptions(governed),
-          inputModalities: operation.definition.inputModalities ?? ["text"],
-          requiredCapabilities: operation.definition.requiredCapabilities,
-          dataClassification: operation.definition.dataClassification,
-          limits: {
-            maxDurationSeconds: operation.definition.limits.maxDurationSeconds,
-            maxInputBytes: operation.definition.limits.maxInputBytes,
-            maxOutputBytes: operation.definition.limits.maxOutputBytes,
-            maxUnits,
-            ...(operation.definition.limits.maxArtifacts
-              ? {
-                  maxArtifacts: operation.definition.limits.maxArtifacts,
-                }
-              : {}),
-            ...(operation.definition.limits.maxPixelsPerArtifact
-              ? {
-                  maxPixelsPerArtifact:
-                    operation.definition.limits.maxPixelsPerArtifact,
-                }
-              : {}),
-          },
-          providerEgress: resolveProviderEgress(operation.definition),
-          providerDataPolicy: operation.definition.providerDataPolicy,
-        },
+        prepared.request,
         scopedRuntimeIdempotencyKey(
           context.actor.id,
           operationKey,
@@ -141,77 +94,255 @@ export class EmbeddingFacade {
         ),
         signal,
       );
-      this.audit(operation, context, result, prepared);
+      recordEmbeddingAudit({
+        runtime: this.runtime,
+        operation: prepared.operation,
+        context,
+        result,
+        itemCount: prepared.items.length,
+      });
       return result;
     } catch (error) {
       if (error instanceof EmbeddingRuntimeError) {
         throw new EmbeddingFacadeError(
           error.code,
           error.message,
-          errorStatus(error.code),
+          embeddingErrorStatus(error.code),
         );
       }
       throw error;
     }
   }
 
-  private async authorize(
-    operation: RegisteredEmbeddingOperation,
+  async start(
+    operationKey: string,
+    items: readonly EmbeddingFacadeItem[],
+    options: ModuleAiJsonValue,
+    idempotencyKey: string,
     context: RequestGuardContext,
+    signal: AbortSignal,
   ) {
-    const access = await evaluateAccessGuards(this.runtime, context, {
-      permission: { permissionKey: operation.definition.permissionKey },
-      feature: operation.feature,
+    const prepared = await this.prepare(
+      operationKey,
+      items,
+      options,
+      context,
+      signal,
+    );
+    const fingerprint = await embeddingRunFingerprint(
+      operationKey,
+      prepared.items,
+      prepared.request.options,
+    );
+    const binding = await this.runs.issue({
+      operationKey,
+      moduleName: prepared.moduleName,
+      idempotencyKey,
+      fingerprint,
+      artifactRefs: prepared.items.flatMap(runArtifact),
+      context,
     });
-    if (!access.decision.allowed) {
+    const runId = binding.runId ?? `embedding_${randomUUIDv7()}`;
+    await this.runs.bind(binding, runId);
+    try {
+      const created = await this.remote.start(
+        prepared.request,
+        scopedRuntimeIdempotencyKey(
+          context.actor.id,
+          operationKey,
+          idempotencyKey,
+        ),
+        runId,
+        signal,
+      );
+      if (created.runId !== runId)
+        throw new EmbeddingFacadeError(
+          "RUNTIME_UNAVAILABLE",
+          "Embedding Runtime 返回了未绑定的 Run",
+          503,
+        );
+      return {
+        runId,
+        status: "accepted" as const,
+        eventsUrl: `/api/embeddings/runs/${created.runId}/events`,
+      };
+    } catch (error) {
+      if (error instanceof EmbeddingRuntimeError)
+        throw new EmbeddingFacadeError(
+          error.code,
+          error.message,
+          embeddingErrorStatus(error.code),
+        );
+      throw error;
+    }
+  }
+
+  async authorizeRun(runId: string, context: RequestGuardContext) {
+    const binding = await this.runs.require(runId, context);
+    const operation = this.#operations.get(binding.operationKey);
+    if (!operation || operation.moduleName !== binding.moduleName)
       throw new EmbeddingFacadeError(
         "FORBIDDEN",
-        "无权执行 Embedding Operation",
+        "Embedding Run 不存在或不可访问",
         403,
       );
-    }
+    await authorizeEmbeddingOperation(this.runtime, operation, context);
+    return binding;
+  }
+  async remoteResult(
+    runId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    const binding = await this.authorizeRun(runId, context);
+    const result = await this.remote.result(runId, signal);
+    await this.auditTerminal(binding, context, "completed", result);
+    return result;
+  }
+  async remoteEvents(
+    runId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    const binding = await this.authorizeRun(runId, context);
+    const response = await this.remote.events(runId, signal);
+    void observeEmbeddingTerminal({
+      response: response.clone(),
+      binding,
+      context,
+      signal,
+      remote: this.remote,
+      audit: (status, result) =>
+        this.auditTerminal(binding, context, status, result),
+    });
+    return response;
+  }
+  async remoteCancel(
+    runId: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ) {
+    const binding = await this.authorizeRun(runId, context);
+    await this.remote.cancel(runId, undefined, signal);
+    await this.auditTerminal(binding, context, "cancelled");
   }
 
-  private audit(
-    operation: RegisteredEmbeddingOperation,
+  async openRunArtifact(runId: string, itemId: string, signal: AbortSignal) {
+    const initial = await this.runs.find(runId);
+    if (!initial) throw unavailableArtifact();
+    const context = await this.artifacts.currentGuardContext(
+      initial.actorId,
+      signal,
+    );
+    const binding = await this.runs.require(runId, context);
+    const operation = this.#operations.get(binding.operationKey);
+    if (!operation || operation.moduleName !== binding.moduleName)
+      throw unavailableArtifact();
+    await authorizeEmbeddingOperation(this.runtime, operation, context);
+    const artifact = binding.artifactRefs.find(
+      (item) => item.itemId === itemId,
+    );
+    if (!artifact) throw unavailableArtifact();
+    return this.artifacts.openRunBound(
+      { ...artifact, expiresAt: "" },
+      binding.actorId,
+      binding.moduleName,
+      signal,
+    );
+  }
+
+  private async prepare(
+    operationKey: string,
+    items: readonly EmbeddingFacadeItem[],
+    options: ModuleAiJsonValue,
     context: RequestGuardContext,
-    result: EmbeddingBatchResponse,
-    items: readonly { id: string }[],
+    signal: AbortSignal,
   ) {
-    this.runtime.auditSink.recordEvent({
-      id: randomUUIDv7(),
-      action: operation.definition.auditAction,
-      outcome: "success",
-      actor: auditActor(context),
-      target: {
-        type: "embedding-batch",
-        id: result.batchId,
-        label: operation.definition.key,
-      },
+    const operation = this.#operations.get(operationKey);
+    if (!operation?.registration?.prepareEmbedding || !operation.moduleName)
+      throw new EmbeddingFacadeError(
+        "OPERATION_NOT_FOUND",
+        "Embedding Operation 不存在",
+        404,
+      );
+    await authorizeEmbeddingOperation(this.runtime, operation, context);
+    const governed = governEmbeddingInput(items, options, operation.definition);
+    const plan = await operation.registration.prepareEmbedding(governed, {
+      actor: toModuleActor(context.actor),
       requestId: context.requestId,
-      metadata: {
-        itemCount: items.length,
-        deploymentAlias: result.metadata.deploymentAlias,
-        model: result.metadata.model,
-        version: result.metadata.version,
-        dimensions: result.metadata.dimensions,
-        normalized: result.metadata.normalized,
-      },
-      occurredAt: new Date().toISOString(),
     });
+    const prepared = await runtimeItems(
+      items,
+      governed,
+      operation.definition,
+      operation.moduleName,
+      this.artifacts,
+      context,
+      signal,
+    );
+    const maxUnits = operation.definition.limits.maxUnits;
+    if (!maxUnits)
+      throw new EmbeddingFacadeError(
+        "INVALID_CONFIGURATION",
+        "Embedding Operation 未声明批量上限",
+        503,
+      );
+    return {
+      operation,
+      moduleName: operation.moduleName,
+      items: prepared,
+      request: {
+        kind: "embedding" as const,
+        operationKey,
+        items: prepared,
+        options: plan.options ?? governedEmbeddingOptions(governed),
+        inputModalities: operation.definition.inputModalities ?? ["text"],
+        requiredCapabilities: operation.definition.requiredCapabilities,
+        dataClassification: operation.definition.dataClassification,
+        limits: {
+          maxDurationSeconds: operation.definition.limits.maxDurationSeconds,
+          maxInputBytes: operation.definition.limits.maxInputBytes,
+          maxOutputBytes: operation.definition.limits.maxOutputBytes,
+          maxUnits,
+          ...(operation.definition.limits.maxArtifacts
+            ? { maxArtifacts: operation.definition.limits.maxArtifacts }
+            : {}),
+          ...(operation.definition.limits.maxPixelsPerArtifact
+            ? {
+                maxPixelsPerArtifact:
+                  operation.definition.limits.maxPixelsPerArtifact,
+              }
+            : {}),
+        },
+        providerEgress: resolveProviderEgress(operation.definition),
+        providerDataPolicy: operation.definition.providerDataPolicy,
+      },
+    };
   }
-}
-
-interface RegisteredEmbeddingOperation {
-  definition: ModuleAiOperationDefinition;
-  feature: ReturnType<typeof findFeature>;
-  registration?: ModuleAiOperationHandlerRegistration;
-  moduleName?: string;
-}
 
-function errorStatus(code: EmbeddingRuntimeError["code"]) {
-  if (code === "FORBIDDEN") return 403;
-  if (code === "RUN_CONFLICT") return 409;
-  if (code === "INVALID_INPUT" || code === "BUDGET_EXCEEDED") return 400;
-  return 503;
+  private async auditTerminal(
+    binding: Awaited<ReturnType<EmbeddingRunAuthorizations["require"]>>,
+    context: RequestGuardContext,
+    terminalStatus: "completed" | "failed" | "cancelled",
+    result?: EmbeddingBatchResponse,
+  ) {
+    const claimedAt = await this.runs.claimTerminalAudit(binding.runId!);
+    if (!claimedAt) return;
+    try {
+      const operation = this.#operations.get(binding.operationKey);
+      if (!operation) throw new Error("Embedding Operation 不存在");
+      recordEmbeddingAudit({
+        runtime: this.runtime,
+        operation,
+        context,
+        terminalStatus,
+        runId: binding.runId,
+        result,
+        itemCount: 0,
+      });
+    } catch (error) {
+      await this.runs.releaseTerminalAudit(binding.runId!, claimedAt);
+      throw error;
+    }
+  }
 }

package/template/apps/server/src/embedding/operation-authorization.ts

@@ -0,0 +1,23 @@
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { RequestGuardContext } from "../guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import { EmbeddingFacadeError } from "./error.js";
+import type { RegisteredEmbeddingOperation } from "./facade-types.js";
+
+export async function authorizeEmbeddingOperation(
+  runtime: ReturnType<typeof createServerRuntime>,
+  operation: RegisteredEmbeddingOperation,
+  context: RequestGuardContext,
+) {
+  const access = await evaluateAccessGuards(runtime, context, {
+    permission: { permissionKey: operation.definition.permissionKey },
+    feature: operation.feature,
+  });
+  if (!access.decision.allowed) {
+    throw new EmbeddingFacadeError(
+      "FORBIDDEN",
+      "无权执行 Embedding Operation",
+      403,
+    );
+  }
+}

package/template/apps/server/src/embedding/remote-runtime.test.ts

@@ -63,4 +63,22 @@ describe("RemoteEmbeddingRuntime", () => {
       unavailableEmbeddingRuntime.embed(operation, "batch-1"),
     ).rejects.toMatchObject({ code: "CAPABILITY_UNAVAILABLE" });
   });
+
+  test("durable start 仅接受 Server 预绑定的 Run ID", async () => {
+    const runtime = new RemoteEmbeddingRuntime({
+      baseUrl: "http://embedding.internal",
+      internalToken: "token",
+      fetch: async (_input, init) => {
+        expect(init?.headers).toMatchObject({
+          authorization: "Bearer token",
+          "idempotency-key": "run-key",
+          "x-embedding-run-id": "embedding_server_bound",
+        });
+        return Response.json({ runId: "embedding_server_bound" });
+      },
+    });
+    await expect(
+      runtime.start(operation, "run-key", "embedding_server_bound"),
+    ).resolves.toEqual({ runId: "embedding_server_bound" });
+  });
 });

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

@@ -49,6 +49,59 @@ export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
     return this.request("/health/ready", { signal });
   }
 
+  async start(
+    request: EmbeddingRuntimeOperation,
+    idempotencyKey: string,
+    runId: string,
+    signal?: AbortSignal,
+  ) {
+    const response = await this.request("/api/embeddings/runs", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "idempotency-key": idempotencyKey,
+        "x-embedding-run-id": runId,
+      },
+      body: JSON.stringify(request),
+      signal,
+    });
+    if (!response.ok) throw await remoteError(response);
+    const body = record(await response.json());
+    if (typeof body.runId !== "string" || !body.runId)
+      throw invalidResponse("Embedding Run 响应无效");
+    return { runId: body.runId };
+  }
+  async events(runId: string, signal?: AbortSignal) {
+    return this.request(
+      `/api/embeddings/runs/${encodeURIComponent(runId)}/events`,
+      { signal },
+    );
+  }
+  async result(runId: string, signal?: AbortSignal) {
+    const response = await this.request(
+      `/api/embeddings/runs/${encodeURIComponent(runId)}/result`,
+      { signal },
+    );
+    if (!response.ok) throw await remoteError(response);
+    return parseResponse(record(await response.json()).output);
+  }
+  async cancel(
+    runId: string,
+    reason: string | undefined,
+    signal?: AbortSignal,
+  ) {
+    const response = await this.request(
+      `/api/embeddings/runs/${encodeURIComponent(runId)}/cancel`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(reason ? { reason } : {}),
+        signal,
+      },
+    );
+    if (!response.ok) throw await remoteError(response);
+  }
+
   private request(path: string, init: RequestInit = {}) {
     const timeout = AbortSignal.timeout(this.#timeoutMs);
     const signal = init.signal
@@ -88,6 +141,30 @@ export const unavailableEmbeddingRuntime: EmbeddingRuntimePort = {
       { status: 503 },
     );
   },
+  async start() {
+    throw new EmbeddingRuntimeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Embedding Runtime 未安装或未配置",
+      true,
+    );
+  },
+  async events() {
+    return Response.json({ code: "CAPABILITY_UNAVAILABLE" }, { status: 503 });
+  },
+  async result() {
+    throw new EmbeddingRuntimeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Embedding Runtime 未安装或未配置",
+      true,
+    );
+  },
+  async cancel() {
+    throw new EmbeddingRuntimeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Embedding Runtime 未安装或未配置",
+      true,
+    );
+  },
 };
 
 function parseResponse(value: unknown): EmbeddingBatchResponse {

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

@@ -0,0 +1,118 @@
+import { expect, test } from "bun:test";
+import type { RouteApp } from "../system/route-types.js";
+import type { EmbeddingFacade } from "./facade.js";
+import { EmbeddingFacadeError } from "./error.js";
+import {
+  registerEmbeddingRoutes,
+  registerEmbeddingRunArtifactRoutes,
+} from "./routes.js";
+
+test("Embedding Run 读取与取消在授权拒绝时不触达远端", async () => {
+  const app = new Harness();
+  let remote = 0;
+  registerEmbeddingRoutes(app, {
+    async authorizeRun() {
+      throw new EmbeddingFacadeError(
+        "FORBIDDEN",
+        "Embedding Run 不存在或不可访问",
+        403,
+      );
+    },
+    async remoteResult() {
+      remote += 1;
+      throw new Error("unreachable");
+    },
+    async remoteCancel() {
+      remote += 1;
+      throw new Error("unreachable");
+    },
+  } as unknown as EmbeddingFacade);
+  const context = {
+    params: { runId: "embedding_1" },
+    request: new Request("http://windy/api"),
+    guardContext: {
+      requestId: "request-1",
+      startedAt: "2026-08-06T00:00:00.000Z",
+      actor: {
+        id: "other",
+        type: "user" as const,
+        name: "其他用户",
+        roleCodes: [],
+        permissionKeys: [],
+      },
+    },
+  };
+  for (const key of [
+    "GET /embeddings/runs/:runId/result",
+    "POST /embeddings/runs/:runId/cancel",
+  ]) {
+    const response = await app.call(key, context);
+    expect(response.status).toBe(403);
+    expect(await response.json()).toMatchObject({ code: "FORBIDDEN" });
+  }
+  expect(remote).toBe(0);
+});
+
+test("Run-bound Artifact 仅允许内部 worker 在当前 Server 授权后读取", async () => {
+  const app = new Harness();
+  let opened = 0;
+  registerEmbeddingRunArtifactRoutes(
+    app,
+    {
+      async openRunArtifact(runId: string, itemId: string) {
+        opened += 1;
+        expect({ runId, itemId }).toEqual({
+          runId: "embedding_1",
+          itemId: "image",
+        });
+        return {
+          opened: {
+            body: new ReadableStream({
+              start(controller) {
+                controller.enqueue(new TextEncoder().encode("image"));
+                controller.close();
+              },
+            }),
+            mimeType: "image/png",
+            byteSize: 5,
+            sha256: "a".repeat(64),
+          },
+        };
+      },
+    } as unknown as EmbeddingFacade,
+    "internal-token",
+  );
+  const route = "GET /internal/embeddings/runs/:runId/artifacts/:itemId";
+  const denied = await app.call(route, {
+    params: { runId: "embedding_1", itemId: "image" },
+    request: new Request("http://windy/api"),
+  });
+  expect(denied.status).toBe(403);
+  expect(opened).toBe(0);
+  const accepted = await app.call(route, {
+    params: { runId: "embedding_1", itemId: "image" },
+    request: new Request("http://windy/api", {
+      headers: { authorization: "Bearer internal-token" },
+    }),
+  });
+  expect(accepted.status).toBe(200);
+  expect(accepted.headers.get("cache-control")).toBe("private, no-store");
+  expect(await accepted.text()).toBe("image");
+  expect(opened).toBe(1);
+});
+class Harness implements RouteApp {
+  readonly routes = new Map<string, (value: unknown) => unknown>();
+  get(path: string, handler: (value: unknown) => unknown) {
+    this.routes.set(`GET ${path}`, handler);
+  }
+  post(path: string, handler: (value: unknown) => unknown) {
+    this.routes.set(`POST ${path}`, handler);
+  }
+  put() {}
+  delete() {}
+  async call(key: string, value: unknown) {
+    const route = this.routes.get(key);
+    if (!route) throw new Error("route missing");
+    return (await route(value)) as Response;
+  }
+}