create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,76 @@
+import type {
+  AiOperationDataClassification,
+  AiProviderDataPolicy,
+  AiProviderEgressPolicy,
+} from "@southwind-ai/modules";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+
+export interface DocumentRuntimeArtifact {
+  /** 仅供受信任 Runtime 通过专用 Header 回取，不能写入日志或转发 Adapter。 */
+  readonly value: string;
+  readonly mediaType: string;
+  readonly byteSize: number;
+  readonly sha256: string;
+}
+
+export interface DocumentRuntimeOperation {
+  readonly kind: "document";
+  readonly operationKey: string;
+  readonly options: ModuleAiJsonValue;
+  readonly sources: readonly DocumentRuntimeArtifact[];
+  readonly requiredCapabilities: readonly string[];
+  readonly dataClassification: AiOperationDataClassification;
+  readonly limits: {
+    readonly maxDurationSeconds: number;
+    readonly maxInputBytes: number;
+    readonly maxOutputBytes: number;
+    readonly maxUnits: number;
+    readonly maxArtifacts: number;
+  };
+  readonly providerEgress: AiProviderEgressPolicy;
+  readonly providerDataPolicy?: AiProviderDataPolicy;
+}
+
+export interface DocumentRuntimeStartResponse {
+  readonly runId: string;
+  readonly status: string;
+  readonly eventsUrl: string;
+}
+
+export interface DocumentRuntimePort {
+  start(
+    request: DocumentRuntimeOperation,
+    idempotencyKey: string,
+    signal?: AbortSignal,
+  ): Promise<DocumentRuntimeStartResponse>;
+  events(
+    runId: string,
+    cursor: number,
+    signal?: AbortSignal,
+  ): Promise<Response>;
+  result(runId: string, signal?: AbortSignal): Promise<Response>;
+  cancel(
+    runId: string,
+    reason?: string,
+    signal?: AbortSignal,
+  ): Promise<Response>;
+  health(signal?: AbortSignal): Promise<Response>;
+}
+
+export class DocumentRuntimeError extends Error {
+  constructor(
+    readonly code:
+      | "CAPABILITY_UNAVAILABLE"
+      | "RUNTIME_UNAVAILABLE"
+      | "INVALID_RESPONSE"
+      | "RUN_CONFLICT"
+      | "FORBIDDEN"
+      | "BUDGET_EXCEEDED"
+      | "INVALID_INPUT",
+    message: string,
+    readonly retryable: boolean,
+  ) {
+    super(message);
+    this.name = "DocumentRuntimeError";
+  }
+}

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

@@ -0,0 +1,339 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  ModuleAiOperationDefinition,
+  ModuleManifest,
+} from "@southwind-ai/modules";
+import { resolveProviderEgress } from "@southwind-ai/modules";
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+  ModuleAiOperationHandlerRegistration,
+} from "@southwind-ai/server-sdk";
+import { evaluateAccessGuards } from "../access-guards.js";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import { ExecutionGrantStore } from "../agent/execution-grants.js";
+import { scopedRuntimeIdempotencyKey } from "../agent/idempotency-key.js";
+import {
+  governProviderInput,
+  ProviderInputGovernanceError,
+} from "../agent/provider-input-governance.js";
+import { auditActor, type RequestGuardContext } from "../guards.js";
+import type { InitializedModuleHosts } from "../module-host.js";
+import { toModuleActor } from "../module-host.js";
+import { findFeature } from "../route-guards.js";
+import type { createServerRuntime } from "../runtime.js";
+import {
+  DocumentRuntimeError,
+  type DocumentRuntimePort,
+  type DocumentRuntimeStartResponse,
+} from "./contracts.js";
+
+export class DocumentRunFacade {
+  readonly #operations: Map<string, RegisteredDocumentOperation>;
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    hosts: InitializedModuleHosts,
+    private readonly runtime: ReturnType<typeof createServerRuntime>,
+    private readonly remote: DocumentRuntimePort,
+    private readonly artifacts: AiArtifactRuntime,
+    private readonly grants: ExecutionGrantStore,
+  ) {
+    const handlers = new Map(
+      hosts.aiOperationHandlers.map(({ registration, moduleName }) => [
+        registration.operationKey,
+        { registration, moduleName },
+      ]),
+    );
+    const features = modules.flatMap(({ features }) => features);
+    this.#operations = new Map(
+      modules.flatMap((module) =>
+        (module.aiOperations ?? [])
+          .filter(({ kind }) => kind === "document")
+          .map(
+            (definition) =>
+              [
+                definition.key,
+                {
+                  definition,
+                  feature: findFeature(features, definition.featureKey),
+                  ...handlers.get(definition.key),
+                },
+              ] as const,
+          ),
+      ),
+    );
+  }
+
+  async start(
+    operationKey: string,
+    sources: readonly ModuleAiArtifactRef[],
+    input: ModuleAiJsonValue,
+    idempotencyKey: string,
+    context: RequestGuardContext,
+    signal: AbortSignal,
+  ): Promise<DocumentRuntimeStartResponse> {
+    const operation = this.#operations.get(operationKey);
+    if (!operation?.registration?.prepareDocument || !operation.moduleName) {
+      throw new DocumentFacadeError(
+        "OPERATION_NOT_FOUND",
+        "Document Operation 不存在",
+        404,
+      );
+    }
+    await this.authorize(operation, context);
+    await this.requireCapabilities(
+      operation.definition.requiredCapabilities,
+      signal,
+    );
+    assertInputSize(input, operation.definition.limits.maxInputBytes);
+    const maxArtifacts = operation.definition.limits.maxArtifacts ?? 1;
+    if (!sources.length || sources.length > maxArtifacts) {
+      throw new DocumentFacadeError(
+        "BUDGET_EXCEEDED",
+        "Document Artifact 数量超过 Operation 上限",
+        400,
+      );
+    }
+    if (
+      sources.reduce((total, source) => total + source.byteSize, 0) >
+      operation.definition.limits.maxInputBytes
+    ) {
+      throw new DocumentFacadeError(
+        "BUDGET_EXCEEDED",
+        "Document Artifact 超过 Operation 输入上限",
+        400,
+      );
+    }
+    const maxUnits = operation.definition.limits.maxUnits;
+    if (!maxUnits) {
+      throw new DocumentFacadeError(
+        "OPERATION_DISABLED",
+        "Document Operation 未声明页数上限",
+        503,
+      );
+    }
+    const governed = governOptions(input, operation.definition);
+    const plan = await operation.registration.prepareDocument(governed, {
+      actor: toModuleActor(context.actor),
+      requestId: context.requestId,
+    });
+    const rotated = await Promise.all(
+      sources.map((source) =>
+        this.artifacts.rotate(
+          source.value,
+          context.actor.id,
+          operation.moduleName!,
+          Math.min(operation.definition.limits.maxDurationSeconds + 60, 3_600),
+          signal,
+        ),
+      ),
+    );
+    sources.forEach((source, index) =>
+      assertArtifactMetadata(source, rotated[index]!),
+    );
+    const grant = this.grants.issue(operation.definition, context, 3_600);
+    try {
+      const created = await this.remote.start(
+        {
+          kind: "document",
+          operationKey,
+          options: plan.options ?? governed,
+          sources: rotated.map(({ value, mediaType, byteSize, sha256 }) => ({
+            value,
+            mediaType,
+            byteSize,
+            sha256,
+          })),
+          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,
+            maxArtifacts,
+          },
+          providerEgress: resolveProviderEgress(operation.definition),
+          providerDataPolicy: operation.definition.providerDataPolicy,
+        },
+        scopedRuntimeIdempotencyKey(
+          context.actor.id,
+          operationKey,
+          idempotencyKey,
+        ),
+        signal,
+      );
+      this.grants.bindRun(grant.token, created.runId);
+      this.runtime.auditSink.recordEvent({
+        id: randomUUIDv7(),
+        action: operation.definition.auditAction,
+        outcome: "success",
+        actor: auditActor(context),
+        target: {
+          type: "document-run",
+          id: created.runId,
+          label: operationKey,
+        },
+        requestId: context.requestId,
+        metadata: {
+          artifactCount: rotated.length,
+          totalByteSize: rotated.reduce(
+            (total, artifact) => total + artifact.byteSize,
+            0,
+          ),
+          sha256: rotated.map(({ sha256 }) => sha256),
+          requiredCapabilities: operation.definition.requiredCapabilities,
+        },
+        occurredAt: new Date().toISOString(),
+      });
+      return {
+        ...created,
+        eventsUrl: `/api/document/runs/${created.runId}/events`,
+      };
+    } catch (error) {
+      this.grants.discard(grant.token);
+      if (error instanceof DocumentRuntimeError) {
+        throw new DocumentFacadeError(
+          error.code,
+          error.message,
+          runtimeErrorStatus(error.code),
+        );
+      }
+      throw error;
+    }
+  }
+
+  authorizeRun(runId: string, context: RequestGuardContext) {
+    this.grants.requireRun(runId, context.actor.id);
+  }
+
+  private async authorize(
+    operation: RegisteredDocumentOperation,
+    context: RequestGuardContext,
+  ) {
+    const access = await evaluateAccessGuards(this.runtime, context, {
+      permission: { permissionKey: operation.definition.permissionKey },
+      feature: operation.feature,
+    });
+    if (!access.decision.allowed) {
+      throw new DocumentFacadeError(
+        "FORBIDDEN",
+        "无权执行 Document Operation",
+        403,
+      );
+    }
+  }
+
+  private async requireCapabilities(
+    required: readonly string[],
+    signal: AbortSignal,
+  ) {
+    let response: Response;
+    try {
+      response = await this.remote.health(signal);
+    } catch {
+      throw capabilityUnavailable();
+    }
+    if (!response.ok) throw capabilityUnavailable();
+    try {
+      const value = (await response.json()) as Record<string, unknown>;
+      const capabilities = Array.isArray(value.capabilities)
+        ? value.capabilities.filter(
+            (item): item is string => typeof item === "string",
+          )
+        : [];
+      if (
+        value.status !== "ready" ||
+        required.some((capability) => !capabilities.includes(capability))
+      ) {
+        throw capabilityUnavailable();
+      }
+    } catch (error) {
+      if (error instanceof DocumentFacadeError) throw error;
+      throw capabilityUnavailable();
+    }
+  }
+}
+
+interface RegisteredDocumentOperation {
+  definition: ModuleAiOperationDefinition;
+  feature: ReturnType<typeof findFeature>;
+  registration?: ModuleAiOperationHandlerRegistration;
+  moduleName?: string;
+}
+
+export class DocumentFacadeError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "DocumentFacadeError";
+  }
+}
+
+function governOptions(
+  input: ModuleAiJsonValue,
+  definition: ModuleAiOperationDefinition,
+) {
+  try {
+    return definition.providerDataPolicy
+      ? governProviderInput(input, definition.providerDataPolicy)
+      : input;
+  } catch (error) {
+    if (error instanceof ProviderInputGovernanceError) {
+      throw new DocumentFacadeError(
+        error.code,
+        error.message,
+        error.code === "FORBIDDEN" ? 403 : 400,
+      );
+    }
+    throw error;
+  }
+}
+
+function assertInputSize(value: ModuleAiJsonValue, maxBytes: number) {
+  if (new TextEncoder().encode(JSON.stringify(value)).byteLength > maxBytes) {
+    throw new DocumentFacadeError(
+      "INVALID_INPUT",
+      "Document 输入超过上限",
+      400,
+    );
+  }
+}
+
+function assertArtifactMetadata(
+  submitted: ModuleAiArtifactRef,
+  resolved: ModuleAiArtifactRef,
+) {
+  if (
+    submitted.mediaType !== resolved.mediaType ||
+    submitted.byteSize !== resolved.byteSize ||
+    submitted.sha256 !== resolved.sha256
+  ) {
+    throw new DocumentFacadeError(
+      "ARTIFACT_UNAVAILABLE",
+      "Artifact 元数据不一致",
+      403,
+    );
+  }
+}
+
+function capabilityUnavailable() {
+  return new DocumentFacadeError(
+    "CAPABILITY_UNAVAILABLE",
+    "Document Runtime 缺少 Operation 所需能力",
+    503,
+  );
+}
+
+function runtimeErrorStatus(code: DocumentRuntimeError["code"]) {
+  if (code === "FORBIDDEN") return 403;
+  if (code === "RUN_CONFLICT") return 409;
+  if (code === "BUDGET_EXCEEDED" || code === "INVALID_INPUT") {
+    return 400;
+  }
+  return 503;
+}

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

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import { DocumentRuntimeError } from "./contracts.js";
+import { RemoteDocumentRuntime } from "./remote-runtime.js";
+
+const request = {
+  kind: "document" as const,
+  operationKey: "evidence.transcript.ocr",
+  options: { outputs: ["pages"] },
+  sources: [
+    {
+      value: "opaque-artifact-ref",
+      mediaType: "application/pdf",
+      byteSize: 128,
+      sha256: "a".repeat(64),
+    },
+  ],
+  requiredCapabilities: ["document.ocr"],
+  dataClassification: "sensitive" as const,
+  limits: {
+    maxDurationSeconds: 60,
+    maxInputBytes: 1024,
+    maxOutputBytes: 4096,
+    maxUnits: 20,
+    maxArtifacts: 1,
+  },
+  providerEgress: { mode: "forbidden" as const },
+};
+
+describe("Remote Document Runtime", () => {
+  test("只向受信任 Runtime 发送内部认证、作用域化幂等键和有界契约", async () => {
+    const calls: Array<{ input: string; init?: RequestInit }> = [];
+    const runtime = new RemoteDocumentRuntime({
+      baseUrl: "http://document.internal:8090",
+      internalToken: "internal-token",
+      fetch: async (input, init) => {
+        calls.push({ input: String(input), init });
+        return Response.json({
+          runId: "doc-1",
+          status: "accepted",
+          eventsUrl: "/api/document/runs/doc-1/events",
+        });
+      },
+    });
+
+    await expect(runtime.start(request, "scoped-key")).resolves.toEqual({
+      runId: "doc-1",
+      status: "accepted",
+      eventsUrl: "/api/document/runs/doc-1/events",
+    });
+    expect(calls[0]?.input).toBe(
+      "http://document.internal:8090/api/document/runs",
+    );
+    expect(calls[0]?.init?.headers).toMatchObject({
+      authorization: "Bearer internal-token",
+      "idempotency-key": "scoped-key",
+    });
+    expect(JSON.parse(String(calls[0]?.init?.body))).toEqual(request);
+  });
+
+  test("拒绝形状错误的创建响应", async () => {
+    const runtime = new RemoteDocumentRuntime({
+      baseUrl: "http://document.internal:8090",
+      internalToken: "internal-token",
+      fetch: async () =>
+        Response.json({
+          runId: "doc-1",
+          status: "unknown",
+          eventsUrl: "https://evil.example/events",
+        }),
+    });
+
+    await expect(runtime.start(request, "scoped-key")).rejects.toBeInstanceOf(
+      DocumentRuntimeError,
+    );
+  });
+
+  test("保留可信的幂等冲突错误码", async () => {
+    const runtime = new RemoteDocumentRuntime({
+      baseUrl: "http://document.internal:8090",
+      internalToken: "internal-token",
+      fetch: async () =>
+        Response.json(
+          {
+            code: "RUN_CONFLICT",
+            message: "幂等键已用于不同输入",
+            retryable: false,
+          },
+          { status: 409 },
+        ),
+    });
+
+    await expect(runtime.start(request, "scoped-key")).rejects.toMatchObject({
+      code: "RUN_CONFLICT",
+    });
+  });
+});