create-windy 0.3.2 → 0.3.5

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

@@ -0,0 +1,227 @@
+import {
+  SpeechRuntimeError,
+  type SpeechRuntimeOperation,
+  type SpeechRuntimePort,
+  type SpeechRuntimeStartResponse,
+} from "./contracts.js";
+
+export class RemoteSpeechRuntime implements SpeechRuntimePort {
+  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("Speech Runtime 内部 Token 不能为空");
+    }
+  }
+
+  async start(
+    request: SpeechRuntimeOperation,
+    idempotencyKey: string,
+    signal?: AbortSignal,
+  ): Promise<SpeechRuntimeStartResponse> {
+    const response = await this.request("/api/speech/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/speech/runs/${encodeURIComponent(runId)}/events?after=${cursor}`,
+      { signal },
+      false,
+    );
+  }
+
+  result(runId: string, signal?: AbortSignal) {
+    return this.request(
+      `/api/speech/runs/${encodeURIComponent(runId)}/result`,
+      {
+        signal,
+      },
+    );
+  }
+
+  artifact(runId: string, signal?: AbortSignal) {
+    return this.request(
+      `/api/speech/runs/${encodeURIComponent(runId)}/artifact`,
+      { signal },
+    );
+  }
+
+  cancel(runId: string, reason?: string, signal?: AbortSignal) {
+    return this.request(
+      `/api/speech/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 invalidResponse("Speech Runtime 响应超过上限");
+      }
+      return response;
+    });
+  }
+}
+
+export const unavailableSpeechRuntime: SpeechRuntimePort = {
+  async start() {
+    throw new SpeechRuntimeError(
+      "CAPABILITY_UNAVAILABLE",
+      "Speech Runtime 未安装或未配置",
+      true,
+    );
+  },
+  async events() {
+    throw unavailable();
+  },
+  async result() {
+    throw unavailable();
+  },
+  async artifact() {
+    throw unavailable();
+  },
+  async cancel() {
+    throw unavailable();
+  },
+  async health() {
+    return Response.json(
+      { status: "unavailable", capabilities: [] },
+      { status: 503 },
+    );
+  },
+};
+
+function parseStartResponse(value: unknown): SpeechRuntimeStartResponse {
+  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 };
+}
+
+function unavailable() {
+  return new SpeechRuntimeError(
+    "RUNTIME_UNAVAILABLE",
+    "Speech Runtime 暂不可用",
+    true,
+  );
+}
+
+function invalidResponse(message = "Speech Runtime 响应无效") {
+  return new SpeechRuntimeError("INVALID_RESPONSE", message, false);
+}
+
+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("Speech 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 SpeechRuntimeError(
+        knownRemoteCode(value.code),
+        value.message,
+        value.retryable,
+      );
+    }
+  } catch {
+    // 不透传远端正文。
+  }
+  return unavailable();
+}
+
+function knownRemoteCode(
+  code: string,
+): ConstructorParameters<typeof SpeechRuntimeError>[0] {
+  return [
+    "CAPABILITY_UNAVAILABLE",
+    "RUN_CONFLICT",
+    "FORBIDDEN",
+    "BUDGET_EXCEEDED",
+    "INVALID_INPUT",
+  ].includes(code)
+    ? (code as ConstructorParameters<typeof SpeechRuntimeError>[0])
+    : "RUNTIME_UNAVAILABLE";
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

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

@@ -0,0 +1,180 @@
+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 { SpeechRuntimePort } from "./contracts.js";
+import { SpeechFacadeError, type SpeechRunFacade } 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 registerSpeechRunRoutes(
+  app: RouteApp,
+  facade: SpeechRunFacade,
+  remote: SpeechRuntimePort,
+) {
+  app.post("/speech/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.source,
+          request.options,
+          idempotencyKey,
+          context.guardContext,
+          context.request.signal,
+        ),
+        { status: 202 },
+      );
+    } catch (error) {
+      return knownError(error);
+    }
+  });
+
+  app.get("/speech/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);
+    }
+  });
+
+  for (const resource of ["result", "artifact"] as const) {
+    app.get(`/speech/runs/:runId/${resource}`, async (raw) => {
+      const context = raw as RouteContext;
+      try {
+        const runId = required(context.params.runId);
+        facade.authorizeRun(runId, context.guardContext);
+        return await remote[resource](runId, context.request.signal);
+      } catch (error) {
+        return knownError(error);
+      }
+    });
+  }
+
+  app.post("/speech/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;
+  source: ModuleAiArtifactRef;
+  options: ModuleAiJsonValue;
+} {
+  if (
+    !isRecord(body) ||
+    Object.keys(body).some(
+      (key) => !["operationKey", "source", "options"].includes(key),
+    ) ||
+    typeof body.operationKey !== "string" ||
+    !body.operationKey.trim() ||
+    !isRecord(body.source)
+  ) {
+    throw invalid("Speech 请求格式无效");
+  }
+  const source = body.source;
+  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 无效");
+  }
+  assertJson(body.options ?? {});
+  return {
+    operationKey: body.operationKey,
+    source: {
+      value: source.value,
+      mediaType: source.mediaType,
+      byteSize: Number(source.byteSize),
+      sha256: source.sha256,
+      expiresAt: typeof source.expiresAt === "string" ? source.expiresAt : "",
+    },
+    options: (body.options ?? {}) as ModuleAiJsonValue,
+  };
+}
+
+function assertJson(value: unknown) {
+  try {
+    if (JSON.stringify(value) === undefined) throw new Error();
+  } catch {
+    throw invalid("Speech 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 SpeechFacadeError("INVALID_INPUT", message, 400);
+}
+
+function knownError(error: unknown) {
+  if (error instanceof SpeechFacadeError) {
+    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: "Speech 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/system/actor.ts

@@ -0,0 +1,39 @@
+import { buildActorScopeContexts } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+import type { SystemRepositories } from "./seed.js";
+
+export async function resolveCurrentSystemActor(
+  repositories: Pick<SystemRepositories, "users" | "roles">,
+  actorId: string,
+): Promise<RequestActor | undefined> {
+  const user = await repositories.users.get(actorId);
+  if (!user || user.status !== "active") return undefined;
+  const roles = (
+    await Promise.all(user.roleIds.map((id) => repositories.roles.get(id)))
+  ).filter(
+    (role): role is NonNullable<typeof role> => role?.status === "active",
+  );
+  return {
+    id: user.id,
+    type: "user",
+    name: user.displayName,
+    username: user.username,
+    displayName: user.displayName,
+    roleCodes: unique(roles.map((role) => role.code)),
+    permissionKeys: unique(roles.flatMap((role) => role.permissionKeys)),
+    ...buildActorScopeContexts(
+      user.id,
+      user.departmentId,
+      roles.map((role) => ({
+        id: role.id,
+        code: role.code,
+        dataScope: role.dataScope,
+        departmentIds: role.departmentIds || [],
+      })),
+    ),
+  };
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values)].sort();
+}

package/template/apps/server/src/system/route-helpers.ts

@@ -10,6 +10,7 @@ export type RouteContext = {
   guardContext: RequestGuardContext;
   params: Record<string, string | undefined>;
   query: Record<string, string | undefined>;
+  request: Request;
 };
 
 export function parseListQuery(query: RouteContext["query"]) {

package/template/apps/server/src/workflow/service.ts

@@ -19,6 +19,7 @@ export interface WorkflowEffects {
 }
 
 export interface CreateApprovalInput {
+  id?: string;
   title: string;
   candidateRoles: CandidateRole[];
   dueAt: string;
@@ -75,7 +76,7 @@ export class WorkflowService {
     const createdAt = this.now().toISOString();
     const item = await this.repository.create(
       {
-        id: Bun.randomUUIDv7(),
+        id: input.id ?? Bun.randomUUIDv7(),
         title: input.title,
         requesterId: actor.id,
         candidateRoles: input.candidateRoles,

package/template/apps/speech-server/Dockerfile

@@ -0,0 +1,22 @@
+# syntax=docker/dockerfile:1
+FROM python:3.12-slim AS runtime
+
+WORKDIR /app/apps/speech-server
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends ffmpeg \
+  && rm -rf /var/lib/apt/lists/* \
+  && pip install --no-cache-dir uv==0.9.27 \
+  && useradd --create-home --uid 10002 windy
+COPY apps/speech-server/pyproject.toml apps/speech-server/uv.lock ./
+RUN uv sync --frozen --no-dev --no-install-project
+COPY apps/speech-server/src ./src
+RUN uv sync --frozen --no-dev
+
+ENV PATH="/app/apps/speech-server/.venv/bin:${PATH}"
+ENV PYTHONUNBUFFERED=1
+EXPOSE 8091
+RUN mkdir -p /app/data/speech && chown -R windy:windy /app/data
+USER windy
+HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=4 \
+  CMD ["python", "-c", "import os,urllib.request; r=urllib.request.Request('http://127.0.0.1:8091/health/ready',headers={'Authorization':'Bearer '+os.environ['SPEECH_SERVER_INTERNAL_TOKEN']}); urllib.request.urlopen(r,timeout=3)"]
+CMD ["uvicorn", "southwind_speech_server.app:app", "--host", "0.0.0.0", "--port", "8091"]

package/template/apps/speech-server/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "southwind-speech-server"
+version = "0.1.0"
+description = "Southwind AI governed batch Speech Runtime server"
+requires-python = ">=3.12,<3.13"
+dependencies = [
+  "fastapi==0.139.2",
+  "httpx==0.28.1",
+  "pydantic==2.13.4",
+  "uvicorn==0.51.0",
+]
+
+[dependency-groups]
+dev = [
+  "mypy==2.3.0",
+  "pytest==9.1.1",
+  "pytest-asyncio==1.4.0",
+  "ruff==0.15.22",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = [".", "src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 88
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "ASYNC"]
+
+[tool.mypy]
+python_version = "3.12"
+strict = true
+files = ["src", "tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/southwind_speech_server"]

package/template/apps/speech-server/src/southwind_speech_server/__init__.py

@@ -0,0 +1 @@
+"""Southwind governed batch Speech Runtime."""