create-windy 0.5.1 → 0.6.0

package/template/apps/server/src/module-host/storage-port.ts

@@ -1,12 +1,20 @@
-import type {
-  ModuleActor,
-  ModuleResourceFileAccessPolicy,
-  ModuleResourceFileRequest,
-  ModuleStoragePort,
+import {
+  ModuleStorageError,
+  type ModuleActor,
+  type ModuleFileView,
+  type ModuleResourceFileAccessPolicy,
+  type ModuleResourceFileRequest,
+  type ModuleStoragePort,
+  type ModuleUploadPolicy,
+  type ModuleUploadSessionView,
 } from "@southwind-ai/server-sdk";
+import type { AuditOutcome } from "@southwind-ai/shared";
 import {
   UploadError,
+  type UploadAuthorizationBinding,
+  type FileMetadata,
   type FileService,
+  type UploadSession,
   type UploadService,
 } from "@southwind-ai/storage";
 
@@ -20,6 +28,10 @@ export interface ModuleStorageScope {
   ownerId: string;
   /** 本模块经 Host 注册的上传用途集合；跨模块与平台用途一律拒绝。 */
   purposes: ReadonlySet<string>;
+  /** Host 注册的用途策略；Writer 只从这里派生保留期。 */
+  uploadPolicies?: ReadonlyMap<string, ModuleUploadPolicy>;
+  /** Host 从不可伪造 ScopeContext 生成；业务输入不能提供或覆盖。 */
+  authorizationBinding?: UploadAuthorizationBinding;
   /** Host 颁发的 Actor 只读视图；资源文件访问策略不能从输入伪造 Actor。 */
   actor?: ModuleActor;
   requestId?: string;
@@ -33,6 +45,23 @@ export interface ModuleStorageScope {
     input: ModuleResourceFileRequest,
     outcome: "success" | "denied",
   ) => Promise<void> | void;
+  /** 流式写入由 Host 统一记录内置上传动作，不接受模块自定义 Action。 */
+  recordUploadDecision?: (decision: ModuleUploadDecision) => void;
+  /** Durable attempt 等 Host 事实；调用方不能覆盖。 */
+  uploadAuditMetadata?: Readonly<Record<string, string | number>>;
+}
+
+export interface ModuleUploadDecision {
+  readonly action:
+    | "file.upload.create"
+    | "file.upload.part.write"
+    | "file.upload.complete"
+    | "file.upload.abort"
+    | "security.denied";
+  readonly outcome: AuditOutcome;
+  readonly targetId?: string;
+  readonly purpose?: string;
+  readonly metadata?: Readonly<Record<string, string | number | boolean>>;
 }
 
 /**
@@ -51,7 +80,19 @@ export function createModuleStoragePort(
   return {
     async createUploadSession(input) {
       requireModulePurpose(scope, input.purpose);
-      return services.uploads.create({ ...input, ownerId: scope.ownerId });
+      if (!scope.authorizationBinding) {
+        throw new UploadError("UPLOAD_FORBIDDEN", "上传会话未授权");
+      }
+      return services.uploads.create({
+        ownerId: scope.ownerId,
+        purpose: input.purpose,
+        authorizationBinding: scope.authorizationBinding,
+        filename: input.filename,
+        mimeType: input.mimeType,
+        expectedByteSize: input.expectedByteSize,
+        expectedSha256: input.expectedSha256,
+        fileExpiresAt: input.fileExpiresAt,
+      });
     },
     async openFile(fileId) {
       const file = await services.files.open(fileId, scope.ownerId);
@@ -161,7 +202,7 @@ function findResourceFileAccessPolicy(
   return policy;
 }
 
-function requireModulePurpose(
+export function requireModulePurpose(
   scope: ModuleStorageScope,
   purpose: string,
 ): void {
@@ -173,6 +214,38 @@ function requireModulePurpose(
   }
 }
 
+export function projectUploadSession(
+  session: UploadSession,
+): ModuleUploadSessionView {
+  return {
+    id: session.id,
+    purpose: session.purpose,
+    filename: session.filename,
+    mimeType: session.mimeType,
+    expectedByteSize: session.expectedByteSize,
+    expectedSha256: session.expectedContentHash?.value,
+    receivedByteSize: session.receivedByteSize,
+    nextPartNumber: session.nextPartNumber,
+    status: session.status,
+    expiresAt: session.expiresAt,
+    fileExpiresAt: session.fileExpiresAt,
+    fileId: session.fileId,
+    createdAt: session.createdAt,
+    updatedAt: session.updatedAt,
+  };
+}
+
+export function projectFile(file: FileMetadata): ModuleFileView {
+  return {
+    id: file.id,
+    purpose: file.purpose,
+    filename: file.filename,
+    mimeType: file.mimeType,
+    byteSize: file.byteSize,
+    sha256: file.contentHash.value,
+  };
+}
+
 function forbiddenResourceFile(): UploadError {
   return new UploadError("UPLOAD_FORBIDDEN", "资源文件访问未授权");
 }
@@ -181,7 +254,10 @@ export function unavailableModuleStoragePort(
   moduleName: string,
 ): ModuleStoragePort {
   const fail = async (): Promise<never> => {
-    throw new Error(`模块 ${moduleName} 的存储 Port 未挂载`);
+    throw new ModuleStorageError(
+      "STORAGE_UNAVAILABLE",
+      `模块 ${moduleName} 的存储 Port 未挂载`,
+    );
   };
   return {
     createUploadSession: () => fail(),

package/template/apps/server/src/module-host/storage-restart-fixture.test-support.ts

@@ -0,0 +1,242 @@
+import type { ModuleManifest } from "@southwind-ai/modules";
+import {
+  ModuleStorageError,
+  requireModuleStorageWritePortV1,
+  type ModuleRequestContext,
+} from "@southwind-ai/server-sdk";
+import { featureKey } from "@southwind-ai/shared";
+import type { UploadPolicy } from "@southwind-ai/storage";
+import { buildActorScopeContexts } from "../data-access/context.js";
+import type { RequestActor } from "../guards.js";
+import { createPlatformHttpApp } from "../http-app.js";
+import { createPlatformObservability } from "../observability/bootstrap.js";
+import { createServerRuntime } from "../runtime.js";
+import type { StorageRuntime } from "../storage/runtime.js";
+import { initializeModuleHosts } from "./initialize.js";
+import { installModuleRoutes } from "./route-installer.js";
+
+export const restartUploadPolicy: UploadPolicy = {
+  purpose: "evidence.generated",
+  maxByteSize: 1024,
+  maxPartByteSize: 512,
+  sessionTtlMs: 60_000,
+  fileRetentionMs: 24 * 60 * 60_000,
+  allowedTypes: { "text/plain": ["txt"] },
+  signature: "none",
+};
+
+const feature = {
+  key: featureKey("evidence.generate"),
+  label: "生成物证",
+  module: "evidence",
+  visible: "visible" as const,
+  enabled: true,
+  stage: "stable" as const,
+};
+
+export const restartModuleManifest: ModuleManifest = {
+  name: "evidence",
+  version: "0.1.0",
+  label: "物证",
+  description: "Storage 重启验收模块",
+  menus: [],
+  adminRoutes: [],
+  permissions: [
+    {
+      key: "evidence.generate.manage",
+      label: "生成物证",
+      module: "evidence",
+      moduleLabel: "物证",
+      resource: "generate",
+      resourceLabel: "物证生成",
+      action: "manage",
+    },
+  ],
+  apiPermissions: [
+    api("POST", "/api/evidence/uploads", "crud.create"),
+    api("GET", "/api/evidence/uploads/:id", "data.read"),
+    api("PUT", "/api/evidence/uploads/:id/parts/:partNumber", "crud.update"),
+    api("POST", "/api/evidence/uploads/:id/complete", "crud.update"),
+  ],
+  features: [feature],
+  migrations: [],
+  schemaExports: [],
+  tasks: [
+    {
+      key: "evidence.generate.run",
+      label: "生成物证",
+      description: "生成物证文件。",
+      permissionKey: "evidence.generate.manage",
+      featureKey: "evidence.generate",
+      auditAction: "task.execute",
+      intervalSeconds: 60,
+      maxAttempts: 3,
+      retryDelaySeconds: 5,
+    },
+  ],
+  tools: [],
+  providers: [],
+  auditActions: ["crud.create", "crud.update", "data.read", "task.execute"],
+};
+
+export async function createRestartHosts() {
+  return initializeModuleHosts({
+    modules: [restartModuleManifest],
+    installations: [
+      {
+        manifest: restartModuleManifest,
+        setup(host) {
+          host.registerUploadPolicy(restartUploadPolicy);
+          host.registerRoutes([
+            {
+              method: "POST",
+              path: "/api/evidence/uploads",
+              permissionKey: "evidence.generate.manage",
+              handler: (context) =>
+                storageResponse(() => createSession(context)),
+            },
+            {
+              method: "GET",
+              path: "/api/evidence/uploads/:id",
+              permissionKey: "evidence.generate.manage",
+              handler: (context) =>
+                storageResponse(() =>
+                  requireModuleStorageWritePortV1(context).getUploadSession(
+                    String(context.params.id),
+                  ),
+                ),
+            },
+            {
+              method: "PUT",
+              path: "/api/evidence/uploads/:id/parts/:partNumber",
+              permissionKey: "evidence.generate.manage",
+              bodyMode: "stream",
+              handler: (context) => storageResponse(() => appendPart(context)),
+            },
+            {
+              method: "POST",
+              path: "/api/evidence/uploads/:id/complete",
+              permissionKey: "evidence.generate.manage",
+              handler: (context) =>
+                storageResponse(() =>
+                  requireModuleStorageWritePortV1(context).completeUpload(
+                    String(context.params.id),
+                  ),
+                ),
+            },
+          ]);
+          host.registerDurableHandler({
+            key: "evidence.generate.run",
+            featureKey: "evidence.generate",
+            permissionKey: "evidence.generate.manage",
+            auditAction: "task.execute",
+            payload: { parse: () => ({}) },
+            execute: () => undefined,
+          });
+        },
+      },
+    ],
+  });
+}
+
+export async function createRestartHttpServer(
+  storage: StorageRuntime,
+  actor: () => RequestActor,
+) {
+  const hosts = await createRestartHosts();
+  const runtime = createServerRuntime(
+    { NODE_ENV: "test" },
+    {
+      actorResolver: { resolve: actor },
+      featureCatalog: restartModuleManifest.features,
+    },
+  );
+  const observability = createPlatformObservability({
+    databaseRequired: false,
+    auditStatus: () => runtime.auditSink.status(),
+    logger: { info() {} },
+  });
+  const app = createPlatformHttpApp(runtime, observability);
+  installModuleRoutes(hosts, app, {
+    runtime,
+    features: restartModuleManifest.features,
+    storage: { uploads: storage.uploads, files: storage.files },
+  });
+  return { app, hosts, runtime };
+}
+
+export function restartActor(dataScope: "all" | "self" = "all"): RequestActor {
+  return {
+    id: "user-evidence",
+    type: "user",
+    name: "物证管理员",
+    roleCodes: ["investigator"],
+    permissionKeys: ["evidence.generate.manage"],
+    ...buildActorScopeContexts("user-evidence", "dept-case", [
+      {
+        id: `role-${dataScope}`,
+        code: "investigator",
+        dataScope,
+        departmentIds: [],
+      },
+    ]),
+  };
+}
+
+async function createSession(context: ModuleRequestContext) {
+  const body = record(context.body);
+  return requireModuleStorageWritePortV1(context).createUploadSession({
+    purpose: restartUploadPolicy.purpose,
+    filename: String(body.filename),
+    mimeType: String(body.mimeType),
+    expectedByteSize: Number(body.expectedByteSize),
+    expectedSha256:
+      typeof body.expectedSha256 === "string" ? body.expectedSha256 : undefined,
+  });
+}
+
+async function appendPart(context: ModuleRequestContext) {
+  if (!context.bodyStream) throw new Error("缺少上传流");
+  return requireModuleStorageWritePortV1(context).appendUploadPart({
+    sessionId: String(context.params.id),
+    partNumber: Number(context.params.partNumber),
+    byteOffset: Number(context.query.offset),
+    byteSize: Number(context.query.size),
+    sha256: String(context.query.sha256),
+    body: context.bodyStream,
+  });
+}
+
+async function storageResponse(operation: () => Promise<unknown>) {
+  try {
+    return await operation();
+  } catch (error) {
+    if (error instanceof ModuleStorageError) {
+      return Response.json(
+        { error: error.code, message: error.message },
+        { status: error.code === "UPLOAD_FORBIDDEN" ? 403 : 409 },
+      );
+    }
+    throw error;
+  }
+}
+
+function record(value: unknown): Record<string, unknown> {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : {};
+}
+
+function api(
+  method: "GET" | "POST" | "PUT",
+  path: string,
+  auditAction: string,
+) {
+  return {
+    method,
+    path,
+    permissionKey: "evidence.generate.manage",
+    featureKey: "evidence.generate",
+    auditAction,
+  };
+}

package/template/apps/server/src/module-host/storage-restart-postgres.integration.test.ts

@@ -0,0 +1,280 @@
+import { createHash } from "node:crypto";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import type { DurableHandlerContext } from "@southwind-ai/jobs";
+import {
+  requireModuleStorageWritePortV1,
+  type ModuleDurableHandlerContext,
+} from "@southwind-ai/server-sdk";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { migrate } from "drizzle-orm/node-postgres/migrator";
+import { Pool } from "pg";
+import { captureAuthorizationScope } from "../data-access/scope-snapshot.js";
+import { createStorageRuntime } from "../storage/runtime.js";
+import { createModuleDurableContextualizer } from "./durable-context.js";
+import {
+  createRestartHttpServer,
+  restartActor,
+  restartModuleManifest,
+  restartUploadPolicy,
+} from "./storage-restart-fixture.test-support.js";
+
+const databaseUrl = process.env.STORAGE_TEST_DATABASE_URL;
+const describePostgres = databaseUrl ? describe : describe.skip;
+let storageRoot = "";
+
+describePostgres("模块 Storage 真实 PostgreSQL 重启验收", () => {
+  beforeAll(async () => {
+    storageRoot = await mkdtemp(join(tmpdir(), "windy-storage-pg-"));
+    const pool = new Pool({ connectionString: databaseUrl });
+    try {
+      await migrate(drizzle(pool), {
+        migrationsFolder: resolve(
+          import.meta.dir,
+          "../../../../packages/database/drizzle",
+        ),
+        migrationsSchema: "public",
+        migrationsTable: "__storage_test_migrations",
+      });
+    } finally {
+      await pool.end();
+    }
+  });
+
+  afterAll(async () => {
+    if (storageRoot) {
+      await rm(storageRoot, { recursive: true, force: true });
+    }
+  });
+
+  test("真实 Elysia Server 重建后 HTTP resume、append 与 complete", async () => {
+    await clearStorageTables();
+    const actor = restartActor("all");
+    const whole = bytes("abcdef");
+    const first = await serverStack(join(storageRoot, "http"), actor);
+    let sessionId = "";
+    try {
+      const created = await first.app.handle(
+        new Request("http://localhost/api/evidence/uploads", {
+          method: "POST",
+          headers: { "content-type": "application/json" },
+          body: JSON.stringify({
+            filename: "evidence.txt",
+            mimeType: "text/plain",
+            expectedByteSize: whole.byteLength,
+            expectedSha256: digest(whole),
+          }),
+        }),
+      );
+      expect(created.status).toBe(200);
+      sessionId = ((await created.json()) as { id: string }).id;
+      const appended = await first.app.handle(
+        partRequest(sessionId, 0, 0, bytes("abc")),
+      );
+      expect(appended.status).toBe(200);
+    } finally {
+      await first.pool.end();
+    }
+
+    const restarted = await serverStack(join(storageRoot, "http"), actor);
+    try {
+      const resumed = await restarted.app.handle(
+        new Request(`http://localhost/api/evidence/uploads/${sessionId}`),
+      );
+      expect(resumed.status).toBe(200);
+      await expect(resumed.json()).resolves.toMatchObject({
+        receivedByteSize: 3,
+        nextPartNumber: 1,
+        status: "uploading",
+      });
+      expect(
+        await restarted.app.handle(partRequest(sessionId, 1, 3, bytes("def"))),
+      ).toMatchObject({ status: 200 });
+      const completed = await restarted.app.handle(
+        new Request(
+          `http://localhost/api/evidence/uploads/${sessionId}/complete`,
+          { method: "POST" },
+        ),
+      );
+      const replayed = await restarted.app.handle(
+        new Request(
+          `http://localhost/api/evidence/uploads/${sessionId}/complete`,
+          { method: "POST" },
+        ),
+      );
+      expect(completed.status).toBe(200);
+      expect(await replayed.json()).toEqual(await completed.clone().json());
+      const file = (await completed.json()) as { id: string };
+      const opened = await restarted.storage.files.open(file.id, actor.id);
+      expect(await new Response(opened.body).text()).toBe("abcdef");
+    } finally {
+      await restarted.pool.end();
+    }
+  });
+
+  test("生产 Drizzle/local wiring 重建后 Durable attempt 恢复完成", async () => {
+    await clearStorageTables();
+    const actor = restartActor("all");
+    const first = await serverStack(join(storageRoot, "durable"), actor);
+    let sessionId = "";
+    try {
+      const context = await durableContext(first, actor, 1);
+      const session = await requireModuleStorageWritePortV1(
+        context,
+      ).createUploadSession({
+        purpose: restartUploadPolicy.purpose,
+        filename: "durable.txt",
+        mimeType: "text/plain",
+        expectedByteSize: 6,
+        expectedSha256: digest(bytes("abcdef")),
+      });
+      sessionId = session.id;
+      expect(
+        Date.parse(session.fileExpiresAt!) - Date.parse(session.createdAt),
+      ).toBe(restartUploadPolicy.fileRetentionMs!);
+      await requireModuleStorageWritePortV1(context).appendUploadPart(
+        partInput(sessionId, 0, 0, bytes("abc")),
+      );
+    } finally {
+      await first.pool.end();
+    }
+
+    const restarted = await serverStack(join(storageRoot, "durable"), actor);
+    try {
+      const context = await durableContext(restarted, actor, 2);
+      await expect(
+        requireModuleStorageWritePortV1(context).getUploadSession(sessionId),
+      ).resolves.toMatchObject({
+        receivedByteSize: 3,
+        nextPartNumber: 1,
+      });
+      await requireModuleStorageWritePortV1(context).appendUploadPart(
+        partInput(sessionId, 1, 3, bytes("def")),
+      );
+      const completed =
+        await requireModuleStorageWritePortV1(context).completeUpload(
+          sessionId,
+        );
+      expect(
+        await requireModuleStorageWritePortV1(context).completeUpload(
+          sessionId,
+        ),
+      ).toEqual(completed);
+      const opened = await restarted.storage.files.open(completed.id, actor.id);
+      expect(await new Response(opened.body).text()).toBe("abcdef");
+    } finally {
+      await restarted.pool.end();
+    }
+  });
+});
+
+async function serverStack(
+  root: string,
+  actor: ReturnType<typeof restartActor>,
+) {
+  const pool = new Pool({ connectionString: databaseUrl });
+  const storage = createStorageRuntime(
+    { WINDY_BLOB_DRIVER: "local", WINDY_STORAGE_ROOT: root },
+    drizzle(pool),
+    [restartUploadPolicy],
+  );
+  const server = await createRestartHttpServer(storage, () => actor);
+  return { ...server, pool, storage };
+}
+
+async function durableContext(
+  stack: Awaited<ReturnType<typeof serverStack>>,
+  actor: ReturnType<typeof restartActor>,
+  attemptNumber: number,
+) {
+  const contextualize = createModuleDurableContextualizer({
+    hosts: stack.hosts,
+    runtime: stack.runtime,
+    features: restartModuleManifest.features,
+    storage: stack.storage,
+    resolveActor: async () => actor,
+  });
+  return (await contextualize({
+    claim: {
+      job: {
+        id: "job-evidence",
+        handlerKey: "evidence.generate.run",
+        requestedBy: actor.id,
+        authorizationScope: captureAuthorizationScope(actor.scopeContext)
+          .snapshot,
+      },
+    },
+    moduleName: "evidence",
+    context: baseDurableContext(attemptNumber),
+  })) as ModuleDurableHandlerContext;
+}
+
+async function clearStorageTables() {
+  const pool = new Pool({ connectionString: databaseUrl });
+  try {
+    await pool.query(
+      "truncate table file_upload_parts, file_metadata, file_upload_sessions",
+    );
+  } finally {
+    await pool.end();
+  }
+}
+
+function partRequest(
+  sessionId: string,
+  partNumber: number,
+  offset: number,
+  value: Uint8Array,
+) {
+  return new Request(
+    `http://localhost/api/evidence/uploads/${sessionId}/parts/${partNumber}?offset=${offset}&size=${value.byteLength}&sha256=${digest(value)}`,
+    { method: "PUT", body: stream(value) },
+  );
+}
+
+function partInput(
+  sessionId: string,
+  partNumber: number,
+  byteOffset: number,
+  value: Uint8Array,
+) {
+  return {
+    sessionId,
+    partNumber,
+    byteOffset,
+    byteSize: value.byteLength,
+    sha256: digest(value),
+    body: stream(value),
+  };
+}
+
+function stream(value: Uint8Array) {
+  return new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(Uint8Array.from(value));
+      controller.close();
+    },
+  });
+}
+
+function baseDurableContext(attemptNumber: number): DurableHandlerContext {
+  return {
+    jobId: "job-evidence",
+    stageKey: "main",
+    attemptNumber,
+    signal: new AbortController().signal,
+    heartbeat: async () => undefined,
+    progress: async () => undefined,
+    publishArtifact: async () => undefined,
+  };
+}
+
+function bytes(value: string) {
+  return new TextEncoder().encode(value);
+}
+
+function digest(value: Uint8Array) {
+  return createHash("sha256").update(value).digest("hex");
+}