create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,223 @@
+import {
+  DocumentRuntimeError,
+  type DocumentRuntimeOperation,
+  type DocumentRuntimePort,
+  type DocumentRuntimeStartResponse,
+} from "./contracts.js";
+
+export class RemoteDocumentRuntime implements DocumentRuntimePort {
+  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 ?? 10_000;
+    if (!options.internalToken.trim()) {
+      throw new Error("Document Runtime 内部 Token 不能为空");
+    }
+  }
+
+  async start(
+    request: DocumentRuntimeOperation,
+    idempotencyKey: string,
+    signal?: AbortSignal,
+  ): Promise<DocumentRuntimeStartResponse> {
+    const response = await this.request("/api/document/runs", {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "idempotency-key": idempotencyKey,
+      },
+      body: JSON.stringify(request),
+      signal,
+    });
+    if (!response.ok) throw await remoteError(response);
+    return parseStartResponse(await response.json());
+  }
+
+  events(runId: string, cursor: number, signal?: AbortSignal) {
+    return this.request(
+      `/api/document/runs/${encodeURIComponent(runId)}/events?after=${cursor}`,
+      { signal },
+      false,
+    );
+  }
+
+  result(runId: string, signal?: AbortSignal) {
+    return this.request(
+      `/api/document/runs/${encodeURIComponent(runId)}/result`,
+      { signal },
+    );
+  }
+
+  cancel(runId: string, reason?: string, signal?: AbortSignal) {
+    return this.request(
+      `/api/document/runs/${encodeURIComponent(runId)}/cancel`,
+      {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ reason }),
+        signal,
+      },
+    );
+  }
+
+  health(signal?: AbortSignal) {
+    return this.request("/health/ready", { signal });
+  }
+
+  private request(
+    path: string,
+    init: RequestInit = {},
+    bounded = true,
+  ): Promise<Response> {
+    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 (
+        bounded &&
+        Number(response.headers.get("content-length") || "0") >
+          64 * 1_024 * 1_024
+      ) {
+        throw new DocumentRuntimeError(
+          "INVALID_RESPONSE",
+          "Document Runtime 响应超过上限",
+          false,
+        );
+      }
+      return response;
+    });
+  }
+}
+
+function parseStartResponse(value: unknown): DocumentRuntimeStartResponse {
+  if (!isRecord(value)) throw invalidResponse();
+  const { runId, status, eventsUrl } = value;
+  if (
+    typeof runId !== "string" ||
+    !runId.trim() ||
+    typeof status !== "string" ||
+    !["accepted", "running", "completed", "failed", "cancelled"].includes(
+      status,
+    ) ||
+    typeof eventsUrl !== "string" ||
+    !eventsUrl.startsWith("/")
+  ) {
+    throw invalidResponse();
+  }
+  return { runId, status, eventsUrl };
+}
+
+export const unavailableDocumentRuntime: DocumentRuntimePort = {
+  async start() {
+    throw new DocumentRuntimeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Document Runtime 未安装或未配置",
+      true,
+    );
+  },
+  async events() {
+    throw unavailable();
+  },
+  async result() {
+    throw unavailable();
+  },
+  async cancel() {
+    throw unavailable();
+  },
+  async health() {
+    return Response.json(
+      { status: "unavailable", capabilities: [] },
+      { status: 503 },
+    );
+  },
+};
+
+function unavailable() {
+  return new DocumentRuntimeError(
+    "RUNTIME_UNAVAILABLE",
+    "Document Runtime 暂不可用",
+    true,
+  );
+}
+
+function invalidResponse() {
+  return new DocumentRuntimeError(
+    "INVALID_RESPONSE",
+    "Document Runtime 响应无效",
+    false,
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(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("Document Runtime URL 无效");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+async function remoteError(response: Response) {
+  try {
+    const value = (await response.json()) as Record<string, unknown>;
+    if (
+      typeof value.code === "string" &&
+      typeof value.message === "string" &&
+      typeof value.retryable === "boolean" &&
+      value.message.length <= 200
+    ) {
+      return new DocumentRuntimeError(
+        knownRemoteCode(value.code),
+        value.message,
+        value.retryable,
+      );
+    }
+  } catch {
+    // 不透传远端正文。
+  }
+  return unavailable();
+}
+
+function knownRemoteCode(
+  code: string,
+): ConstructorParameters<typeof DocumentRuntimeError>[0] {
+  return [
+    "CAPABILITY_UNAVAILABLE",
+    "RUN_CONFLICT",
+    "FORBIDDEN",
+    "BUDGET_EXCEEDED",
+    "INVALID_INPUT",
+  ].includes(code)
+    ? (code as ConstructorParameters<typeof DocumentRuntimeError>[0])
+    : "RUNTIME_UNAVAILABLE";
+}

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

@@ -0,0 +1,193 @@
+import type {
+  ModuleAiArtifactRef,
+  ModuleAiJsonValue,
+} from "@southwind-ai/server-sdk";
+import type { RequestGuardContext } from "../guards.js";
+import type { RouteApp } from "../system/route-types.js";
+import type { DocumentRuntimePort } from "./contracts.js";
+import { DocumentFacadeError, type DocumentRunFacade } from "./facade.js";
+
+interface RouteContext {
+  readonly body?: unknown;
+  readonly params: Record<string, string | undefined>;
+  readonly query: Record<string, string | undefined>;
+  readonly request: Request;
+  readonly guardContext: RequestGuardContext;
+}
+
+export function registerDocumentRunRoutes(
+  app: RouteApp,
+  facade: DocumentRunFacade,
+  remote: DocumentRuntimePort,
+) {
+  app.post("/document/runs", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const request = parseStart(context.body);
+      const idempotencyKey = context.request.headers.get("idempotency-key");
+      if (!idempotencyKey?.trim()) throw invalid("幂等键不能为空");
+      return Response.json(
+        await facade.start(
+          request.operationKey,
+          request.sources,
+          request.options,
+          idempotencyKey,
+          context.guardContext,
+          context.request.signal,
+        ),
+        { status: 202 },
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+
+  app.get("/document/runs/:runId/events", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const runId = required(context.params.runId);
+      facade.authorizeRun(runId, context.guardContext);
+      return await remote.events(
+        runId,
+        cursor(context.query.after),
+        context.request.signal,
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+
+  app.get("/document/runs/:runId/result", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const runId = required(context.params.runId);
+      facade.authorizeRun(runId, context.guardContext);
+      return await remote.result(runId, context.request.signal);
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+
+  app.post("/document/runs/:runId/cancel", async (raw) => {
+    const context = raw as RouteContext;
+    try {
+      const runId = required(context.params.runId);
+      facade.authorizeRun(runId, context.guardContext);
+      const body = isRecord(context.body) ? context.body : {};
+      return await remote.cancel(
+        runId,
+        typeof body.reason === "string" ? body.reason.slice(0, 200) : undefined,
+        context.request.signal,
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+}
+
+function parseStart(body: unknown): {
+  operationKey: string;
+  sources: readonly ModuleAiArtifactRef[];
+  options: ModuleAiJsonValue;
+} {
+  if (
+    !isRecord(body) ||
+    Object.keys(body).some(
+      (key) => !["operationKey", "source", "sources", "options"].includes(key),
+    ) ||
+    typeof body.operationKey !== "string" ||
+    !body.operationKey.trim()
+  ) {
+    throw invalid("Document 请求格式无效");
+  }
+  if (body.source && body.sources) {
+    throw invalid("Document source 与 sources 不能同时提供");
+  }
+  const values = body.source
+    ? [body.source]
+    : Array.isArray(body.sources)
+      ? body.sources
+      : [];
+  if (!values.length || values.length > 100) {
+    throw invalid("Document 输入文件数量必须为 1 至 100");
+  }
+  const sources = values.map((value) => artifact(value));
+  assertJson(body.options ?? {});
+  return {
+    operationKey: body.operationKey,
+    sources,
+    options: (body.options ?? {}) as ModuleAiJsonValue,
+  };
+}
+
+function artifact(value: unknown): ModuleAiArtifactRef {
+  const source = isRecord(value) ? value : {};
+  if (
+    typeof source.value !== "string" ||
+    !source.value ||
+    typeof source.mediaType !== "string" ||
+    !Number.isSafeInteger(source.byteSize) ||
+    Number(source.byteSize) < 0 ||
+    typeof source.sha256 !== "string" ||
+    !/^[a-f0-9]{64}$/.test(source.sha256)
+  ) {
+    throw invalid("ArtifactRef 无效");
+  }
+  return {
+    value: source.value,
+    mediaType: source.mediaType,
+    byteSize: Number(source.byteSize),
+    sha256: source.sha256,
+    expiresAt: typeof source.expiresAt === "string" ? source.expiresAt : "",
+  };
+}
+
+function assertJson(value: unknown) {
+  try {
+    if (JSON.stringify(value) === undefined) throw new Error();
+  } catch {
+    throw invalid("Document options 必须是 JSON");
+  }
+}
+
+function cursor(value: string | undefined) {
+  if (value === undefined) return 0;
+  if (!/^\d+$/.test(value)) throw invalid("事件游标无效");
+  return Number(value);
+}
+
+function required(value: string | undefined) {
+  if (!value) throw invalid("Run ID 无效");
+  return value;
+}
+
+function invalid(message: string) {
+  return new DocumentFacadeError("INVALID_INPUT", message, 400);
+}
+
+function knownError(error: unknown) {
+  if (error instanceof DocumentFacadeError) {
+    return Response.json(
+      {
+        code: error.code,
+        message: error.message,
+        requestId: crypto.randomUUID(),
+        retryable: error.status >= 500,
+      },
+      { status: error.status },
+    );
+  }
+  return Response.json(
+    {
+      code: "RUNTIME_UNAVAILABLE",
+      message: "Document Runtime 暂不可用",
+      requestId: crypto.randomUUID(),
+      retryable: true,
+    },
+    { status: 503 },
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

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

@@ -0,0 +1,83 @@
+import type {
+  AiOperationDataClassification,
+  AiOperationInputModality,
+  AiProviderDataPolicy,
+  AiProviderEgressPolicy,
+} from "@southwind-ai/modules";
+import type { ModuleAiJsonValue } from "@southwind-ai/server-sdk";
+
+export type EmbeddingRuntimeItem =
+  | { readonly id: string; readonly text: string }
+  | {
+      readonly id: string;
+      readonly source: {
+        readonly value: string;
+        readonly mediaType: string;
+        readonly byteSize: number;
+        readonly sha256: string;
+      };
+    };
+
+export interface EmbeddingRuntimeOperation {
+  readonly kind: "embedding";
+  readonly operationKey: string;
+  readonly items: readonly EmbeddingRuntimeItem[];
+  readonly options: ModuleAiJsonValue;
+  readonly inputModalities: readonly AiOperationInputModality[];
+  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 maxPixelsPerArtifact?: number;
+  };
+  readonly providerEgress: AiProviderEgressPolicy;
+  readonly providerDataPolicy?: AiProviderDataPolicy;
+}
+
+export interface EmbeddingBatchResponse {
+  readonly batchId: string;
+  readonly items: readonly {
+    readonly id: string;
+    readonly vector: readonly number[];
+    readonly inputSha256: string;
+  }[];
+  readonly metadata: {
+    readonly deploymentAlias: string;
+    readonly model: string;
+    readonly version: string;
+    readonly dimensions: number;
+    readonly normalized: boolean;
+  };
+}
+
+export interface EmbeddingRuntimePort {
+  embed(
+    request: EmbeddingRuntimeOperation,
+    idempotencyKey: string,
+    signal?: AbortSignal,
+  ): Promise<EmbeddingBatchResponse>;
+  health(signal?: AbortSignal): Promise<Response>;
+}
+
+export class EmbeddingRuntimeError extends Error {
+  constructor(
+    readonly code:
+      | "CAPABILITY_UNAVAILABLE"
+      | "RUNTIME_UNAVAILABLE"
+      | "RUN_CONFLICT"
+      | "FORBIDDEN"
+      | "BUDGET_EXCEEDED"
+      | "INVALID_INPUT"
+      | "OUTPUT_VALIDATION_FAILED"
+      | "INVALID_RESPONSE",
+    message: string,
+    readonly retryable: boolean,
+  ) {
+    super(message);
+    this.name = "EmbeddingRuntimeError";
+  }
+}

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

@@ -0,0 +1,10 @@
+export class EmbeddingFacadeError extends Error {
+  constructor(
+    readonly code: string,
+    message: string,
+    readonly status: number,
+  ) {
+    super(message);
+    this.name = "EmbeddingFacadeError";
+  }
+}