create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,217 @@
+import { randomUUIDv7 } from "bun";
+import type {
+  ModuleAiOperationDefinition,
+  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 { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import { scopedRuntimeIdempotencyKey } from "../agent/idempotency-key.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 {
+  EmbeddingRuntimeError,
+  type EmbeddingBatchResponse,
+  type EmbeddingRuntimePort,
+} from "./contracts.js";
+import { EmbeddingFacadeError } from "./error.js";
+import {
+  governEmbeddingInput,
+  governedEmbeddingOptions,
+  runtimeItems,
+  type EmbeddingFacadeItem,
+} from "./input.js";
+
+export class EmbeddingFacade {
+  readonly #operations: Map<string, RegisteredEmbeddingOperation>;
+
+  constructor(
+    modules: readonly ModuleManifest[],
+    hosts: InitializedModuleHosts,
+    private readonly runtime: ReturnType<typeof createServerRuntime>,
+    private readonly remote: EmbeddingRuntimePort,
+    private readonly artifacts: AiArtifactRuntime,
+  ) {
+    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 === "embedding")
+          .map(
+            (definition) =>
+              [
+                definition.key,
+                {
+                  definition,
+                  feature: findFeature(features, definition.featureKey),
+                  ...handlers.get(definition.key),
+                },
+              ] as const,
+          ),
+      ),
+    );
+  }
+
+  async embed(
+    operationKey: string,
+    items: readonly EmbeddingFacadeItem[],
+    options: ModuleAiJsonValue,
+    idempotencyKey: string,
+    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(
+      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,
+      );
+    }
+    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,
+        },
+        scopedRuntimeIdempotencyKey(
+          context.actor.id,
+          operationKey,
+          idempotencyKey,
+        ),
+        signal,
+      );
+      this.audit(operation, context, result, prepared);
+      return result;
+    } catch (error) {
+      if (error instanceof EmbeddingRuntimeError) {
+        throw new EmbeddingFacadeError(
+          error.code,
+          error.message,
+          errorStatus(error.code),
+        );
+      }
+      throw error;
+    }
+  }
+
+  private async authorize(
+    operation: RegisteredEmbeddingOperation,
+    context: RequestGuardContext,
+  ) {
+    const access = await evaluateAccessGuards(this.runtime, context, {
+      permission: { permissionKey: operation.definition.permissionKey },
+      feature: operation.feature,
+    });
+    if (!access.decision.allowed) {
+      throw new EmbeddingFacadeError(
+        "FORBIDDEN",
+        "无权执行 Embedding Operation",
+        403,
+      );
+    }
+  }
+
+  private audit(
+    operation: RegisteredEmbeddingOperation,
+    context: RequestGuardContext,
+    result: EmbeddingBatchResponse,
+    items: readonly { id: string }[],
+  ) {
+    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,
+      },
+      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(),
+    });
+  }
+}
+
+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;
+}

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

@@ -0,0 +1,172 @@
+import type { ModuleAiOperationDefinition } from "@southwind-ai/modules";
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
+import type { AiArtifactRuntime } from "../ai-artifact/runtime.js";
+import type { RequestGuardContext } from "../guards.js";
+import {
+  governProviderInput,
+  ProviderInputGovernanceError,
+} from "../agent/provider-input-governance.js";
+import type { EmbeddingRuntimeItem } from "./contracts.js";
+import { EmbeddingFacadeError } from "./error.js";
+
+export type EmbeddingFacadeItem =
+  | { readonly id: string; readonly text: string }
+  | { readonly id: string; readonly source: ModuleAiArtifactRef };
+
+export function governEmbeddingInput(
+  items: readonly EmbeddingFacadeItem[],
+  options: ModuleAiJsonValue,
+  definition: ModuleAiOperationDefinition,
+) {
+  validateItems(items, options, definition);
+  const input: ModuleAiJsonValue = {
+    items: items.map(governanceItem),
+    options,
+  };
+  try {
+    return definition.providerDataPolicy
+      ? governProviderInput(input, definition.providerDataPolicy)
+      : input;
+  } catch (error) {
+    if (error instanceof ProviderInputGovernanceError) {
+      throw new EmbeddingFacadeError(
+        error.code,
+        error.message,
+        error.code === "FORBIDDEN" ? 403 : 400,
+      );
+    }
+    throw error;
+  }
+}
+
+function governanceItem(item: EmbeddingFacadeItem): ModuleAiJsonValue {
+  if ("text" in item) return { id: item.id, text: item.text };
+  return {
+    id: item.id,
+    mediaType: item.source.mediaType,
+    byteSize: item.source.byteSize,
+    sha256: item.source.sha256,
+  };
+}
+
+export function governedEmbeddingOptions(
+  governed: ModuleAiJsonValue,
+): ModuleAiJsonValue {
+  return isRecord(governed) && "options" in governed
+    ? (governed.options as ModuleAiJsonValue)
+    : {};
+}
+
+export async function runtimeItems(
+  original: readonly EmbeddingFacadeItem[],
+  governed: ModuleAiJsonValue,
+  definition: ModuleAiOperationDefinition,
+  moduleName: string,
+  artifacts: AiArtifactRuntime,
+  context: RequestGuardContext,
+  signal: AbortSignal,
+): Promise<readonly EmbeddingRuntimeItem[]> {
+  const governedItems =
+    isRecord(governed) && Array.isArray(governed.items)
+      ? governed.items
+      : undefined;
+  if (!governedItems || governedItems.length !== original.length) {
+    throw invalid("Embedding 治理后输入结构无效");
+  }
+  return Promise.all(
+    original.map(async (item, index) => {
+      const governedItem = governedItems[index];
+      if (!isRecord(governedItem) || governedItem.id !== item.id) {
+        throw invalid("Embedding 治理后输入顺序漂移");
+      }
+      if ("text" in item) {
+        if (
+          typeof governedItem.text !== "string" ||
+          !governedItem.text.trim()
+        ) {
+          throw invalid("Embedding 文本被治理为空");
+        }
+        return { id: item.id, text: governedItem.text };
+      }
+      const rotated = await artifacts.rotate(
+        item.source.value,
+        context.actor.id,
+        moduleName,
+        Math.min(definition.limits.maxDurationSeconds + 60, 3_600),
+        signal,
+      );
+      if (
+        item.source.mediaType !== rotated.mediaType ||
+        item.source.byteSize !== rotated.byteSize ||
+        item.source.sha256 !== rotated.sha256
+      ) {
+        throw new EmbeddingFacadeError(
+          "FORBIDDEN",
+          "Embedding Artifact 元数据不一致",
+          403,
+        );
+      }
+      return {
+        id: item.id,
+        source: {
+          value: rotated.value,
+          mediaType: rotated.mediaType,
+          byteSize: rotated.byteSize,
+          sha256: rotated.sha256,
+        },
+      };
+    }),
+  );
+}
+
+function validateItems(
+  items: readonly EmbeddingFacadeItem[],
+  options: ModuleAiJsonValue,
+  definition: ModuleAiOperationDefinition,
+) {
+  const maxUnits = definition.limits.maxUnits;
+  if (!maxUnits || !items.length || items.length > maxUnits) {
+    throw invalid("Embedding 批量数量超过 Operation 上限");
+  }
+  const ids = new Set<string>();
+  let artifactCount = 0;
+  let bytes = new TextEncoder().encode(JSON.stringify(options)).byteLength;
+  for (const item of items) {
+    if (!item.id.trim() || ids.has(item.id)) throw invalid("Embedding ID 无效");
+    ids.add(item.id);
+    if ("text" in item) {
+      if (!definition.inputModalities?.includes("text") || !item.text.trim()) {
+        throw invalid("Embedding Operation 未授权文本输入");
+      }
+      bytes += new TextEncoder().encode(item.text).byteLength;
+      continue;
+    }
+    artifactCount += 1;
+    bytes += item.source.byteSize;
+    if (
+      !definition.inputModalities?.includes("image") ||
+      !["image/jpeg", "image/png", "image/webp"].includes(
+        item.source.mediaType.toLowerCase(),
+      )
+    ) {
+      throw invalid("Embedding Operation 未授权该图片输入");
+    }
+  }
+  if (
+    bytes > definition.limits.maxInputBytes ||
+    artifactCount > (definition.limits.maxArtifacts ?? 0)
+  ) {
+    throw invalid("Embedding 输入资源超过 Operation 上限");
+  }
+}
+
+function invalid(message: string) {
+  return new EmbeddingFacadeError("INVALID_INPUT", message, 400);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

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

@@ -0,0 +1,66 @@
+import { describe, expect, test } from "bun:test";
+import {
+  RemoteEmbeddingRuntime,
+  unavailableEmbeddingRuntime,
+} from "./remote-runtime.js";
+
+const operation = {
+  kind: "embedding" as const,
+  operationKey: "analysis.embedding.text",
+  items: [{ id: "one", text: "测试" }],
+  options: {},
+  inputModalities: ["text"] as const,
+  requiredCapabilities: ["embedding.text"],
+  dataClassification: "sensitive" as const,
+  limits: {
+    maxDurationSeconds: 30,
+    maxInputBytes: 1024,
+    maxOutputBytes: 1024,
+    maxUnits: 10,
+  },
+  providerEgress: {
+    mode: "configured-endpoint" as const,
+    deploymentKey: "local",
+  },
+};
+
+describe("RemoteEmbeddingRuntime", () => {
+  test("校验向量维度与固定元数据", async () => {
+    const runtime = new RemoteEmbeddingRuntime({
+      baseUrl: "http://embedding.internal",
+      internalToken: "token",
+      fetch: async (_input, init) => {
+        expect(init?.headers).toMatchObject({
+          authorization: "Bearer token",
+          "idempotency-key": "batch-1",
+        });
+        return Response.json({
+          batchId: "embed_1",
+          items: [
+            {
+              id: "one",
+              vector: [1, 0],
+              inputSha256: "a".repeat(64),
+            },
+          ],
+          metadata: {
+            deploymentAlias: "local-v1",
+            model: "model",
+            version: "v1",
+            dimensions: 2,
+            normalized: true,
+          },
+        });
+      },
+    });
+
+    const result = await runtime.embed(operation, "batch-1");
+    expect(result.metadata.dimensions).toBe(2);
+  });
+
+  test("未配置时 fail closed", async () => {
+    await expect(
+      unavailableEmbeddingRuntime.embed(operation, "batch-1"),
+    ).rejects.toMatchObject({ code: "CAPABILITY_UNAVAILABLE" });
+  });
+});

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

@@ -0,0 +1,218 @@
+import {
+  EmbeddingRuntimeError,
+  type EmbeddingBatchResponse,
+  type EmbeddingRuntimeOperation,
+  type EmbeddingRuntimePort,
+} from "./contracts.js";
+
+export class RemoteEmbeddingRuntime implements EmbeddingRuntimePort {
+  readonly #baseUrl: string;
+  readonly #timeoutMs: number;
+
+  constructor(
+    private readonly options: {
+      baseUrl: string;
+      internalToken: string;
+      timeoutMs?: number;
+      fetch?: (
+        input: string | URL | Request,
+        init?: RequestInit,
+      ) => Promise<Response>;
+    },
+  ) {
+    this.#baseUrl = normalizeUrl(options.baseUrl);
+    this.#timeoutMs = options.timeoutMs ?? 30_000;
+    if (!options.internalToken.trim()) {
+      throw new Error("Embedding Runtime 内部 Token 不能为空");
+    }
+  }
+
+  async embed(
+    request: EmbeddingRuntimeOperation,
+    idempotencyKey: string,
+    signal?: AbortSignal,
+  ): Promise<EmbeddingBatchResponse> {
+    const response = await this.request("/api/embeddings", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "idempotency-key": idempotencyKey,
+      },
+      body: JSON.stringify(request),
+      signal,
+    });
+    if (!response.ok) throw await remoteError(response);
+    return parseResponse(await response.json());
+  }
+
+  health(signal?: AbortSignal) {
+    return this.request("/health/ready", { signal });
+  }
+
+  private request(path: string, init: RequestInit = {}) {
+    const timeout = AbortSignal.timeout(this.#timeoutMs);
+    const signal = init.signal
+      ? AbortSignal.any([init.signal, timeout])
+      : timeout;
+    const requestFetch = this.options.fetch ?? fetch;
+    return requestFetch(`${this.#baseUrl}${path}`, {
+      ...init,
+      signal,
+      headers: {
+        authorization: `Bearer ${this.options.internalToken}`,
+        ...init.headers,
+      },
+    }).then((response) => {
+      if (
+        Number(response.headers.get("content-length") || "0") >
+        64 * 1_024 * 1_024
+      ) {
+        throw invalidResponse("Embedding Runtime 响应超过上限");
+      }
+      return response;
+    });
+  }
+}
+
+export const unavailableEmbeddingRuntime: EmbeddingRuntimePort = {
+  async embed() {
+    throw new EmbeddingRuntimeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Embedding Runtime 未安装或未配置",
+      true,
+    );
+  },
+  async health() {
+    return Response.json(
+      { status: "unavailable", capabilities: [] },
+      { status: 503 },
+    );
+  },
+};
+
+function parseResponse(value: unknown): EmbeddingBatchResponse {
+  const root = record(value);
+  const metadata = record(root.metadata);
+  const dimensions = positiveInteger(metadata.dimensions);
+  if (dimensions > 65_536) {
+    throw invalidResponse("Embedding Runtime 向量维度超过上限");
+  }
+  if (!Array.isArray(root.items) || !root.items.length) throw invalidResponse();
+  const ids = new Set<string>();
+  const items = root.items.map((raw) => {
+    const item = record(raw);
+    if (
+      typeof item.id !== "string" ||
+      !item.id ||
+      ids.has(item.id) ||
+      typeof item.inputSha256 !== "string" ||
+      !/^[a-f0-9]{64}$/.test(item.inputSha256) ||
+      !Array.isArray(item.vector) ||
+      item.vector.length !== dimensions ||
+      item.vector.some(
+        (entry) => typeof entry !== "number" || !Number.isFinite(entry),
+      )
+    ) {
+      throw invalidResponse();
+    }
+    ids.add(item.id);
+    return {
+      id: item.id,
+      inputSha256: item.inputSha256,
+      vector: item.vector as number[],
+    };
+  });
+  if (
+    typeof root.batchId !== "string" ||
+    !root.batchId ||
+    typeof metadata.deploymentAlias !== "string" ||
+    typeof metadata.model !== "string" ||
+    typeof metadata.version !== "string" ||
+    typeof metadata.normalized !== "boolean"
+  ) {
+    throw invalidResponse();
+  }
+  return {
+    batchId: root.batchId,
+    items,
+    metadata: {
+      deploymentAlias: metadata.deploymentAlias,
+      model: metadata.model,
+      version: metadata.version,
+      dimensions,
+      normalized: metadata.normalized,
+    },
+  };
+}
+
+async function remoteError(response: Response) {
+  try {
+    const value = record(await response.json());
+    if (
+      typeof value.code === "string" &&
+      typeof value.message === "string" &&
+      typeof value.retryable === "boolean" &&
+      value.message.length <= 200
+    ) {
+      return new EmbeddingRuntimeError(
+        knownCode(value.code),
+        value.message,
+        value.retryable,
+      );
+    }
+  } catch {
+    // 不透传远端正文。
+  }
+  return new EmbeddingRuntimeError(
+    "RUNTIME_UNAVAILABLE",
+    "Embedding Runtime 暂不可用",
+    true,
+  );
+}
+
+function knownCode(
+  code: string,
+): ConstructorParameters<typeof EmbeddingRuntimeError>[0] {
+  return [
+    "CAPABILITY_UNAVAILABLE",
+    "RUN_CONFLICT",
+    "FORBIDDEN",
+    "BUDGET_EXCEEDED",
+    "INVALID_INPUT",
+    "OUTPUT_VALIDATION_FAILED",
+  ].includes(code)
+    ? (code as ConstructorParameters<typeof EmbeddingRuntimeError>[0])
+    : "RUNTIME_UNAVAILABLE";
+}
+
+function invalidResponse(message = "Embedding Runtime 响应无效") {
+  return new EmbeddingRuntimeError("INVALID_RESPONSE", message, false);
+}
+
+function record(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw invalidResponse();
+  }
+  return value as Record<string, unknown>;
+}
+
+function positiveInteger(value: unknown) {
+  if (!Number.isSafeInteger(value) || Number(value) < 1) {
+    throw invalidResponse();
+  }
+  return Number(value);
+}
+
+function normalizeUrl(raw: string) {
+  const url = new URL(raw);
+  if (
+    !["http:", "https:"].includes(url.protocol) ||
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash
+  ) {
+    throw new Error("Embedding Runtime URL 无效");
+  }
+  return url.toString().replace(/\/$/, "");
+}