sonamu 0.13.2 → 0.13.3

package/src/storage/__tests__/storage-manager.test.ts

@@ -0,0 +1,64 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { type MultipartFile } from "@fastify/multipart";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { Sonamu } from "../../api/sonamu";
+import { BufferedFile, drivers, StorageManager, StreamedFile } from "../index";
+
+describe("이름 붙인 디스크", () => {
+  const originalStorage = Sonamu["storageValue"];
+  let directory: string;
+
+  beforeEach(async () => {
+    directory = await mkdtemp(path.join(tmpdir(), "sonamu-storage-"));
+  });
+
+  afterEach(async () => {
+    Reflect.set(Sonamu, "storageValue", originalStorage);
+    await rm(directory, { recursive: true, force: true });
+  });
+
+  it("버퍼 업로드와 스트림 파일 다운로드가 같은 이름의 디스크를 사용한다", async () => {
+    const factory = vi.fn(
+      drivers.fs({
+        location: directory,
+        visibility: "public",
+        urlBuilder: {
+          async generateURL(key) {
+            return `https://cdn.example.com/${key}`;
+          },
+          async generateSignedURL(key) {
+            return `https://cdn.example.com/${key}?signed`;
+          },
+        },
+      }),
+    );
+    const manager = new StorageManager({ drivers: { images: factory } });
+    Reflect.set(Sonamu, "storageValue", manager);
+    expect(factory).not.toHaveBeenCalled();
+
+    // SAFETY: BufferedFile 생성자가 읽는 필드는 filename과 mimetype뿐이며 raw는 이 테스트에서 사용하지 않는다.
+    const multipart = { filename: "hello.txt", mimetype: "text/plain" } as MultipartFile;
+    const buffer = new BufferedFile(multipart, Buffer.from("hello"));
+    expect(await buffer.saveToDisk("images", "hello.txt")).toBe(
+      "https://cdn.example.com/hello.txt",
+    );
+    expect(await readFile(path.join(directory, "hello.txt"), "utf8")).toBe("hello");
+    const streamed = new StreamedFile({
+      filename: "hello.txt",
+      mimetype: "text/plain",
+      size: 5,
+      key: "hello.txt",
+      diskName: "images",
+      url: "https://cdn.example.com/hello.txt",
+      signedUrl: "https://cdn.example.com/hello.txt?signed",
+    });
+    expect(streamed.diskName).toBe("images");
+    expect(await streamed.download()).toEqual(Buffer.from("hello"));
+    expect(factory).toHaveBeenCalledTimes(1);
+    expect(() => manager.use("missing")).toThrow('Unknown disk: "missing". Available: images');
+  });
+});

package/src/storage/buffered-file.ts

@@ -3,7 +3,7 @@ import { createHash } from "crypto";
 import { type MultipartFile } from "@fastify/multipart";
 
 import { BaseFile } from "./base-file";
-import { type DriverKey } from "./drivers";
+import { type DiskName } from "./types";
 
 /**
  * Buffer 모드로 업로드된 파일
@@ -35,11 +35,11 @@ export class BufferedFile extends BaseFile {
 
   /**
    * 파일을 디스크에 저장
-   * @param diskName 디스크 이름 ("fs" 또는 "s3")
+   * @param diskName 설정에 등록한 디스크 이름
    * @param key 저장 경로 (예: 'uploads/avatar.png')
    * @returns 저장된 파일의 URL
    */
-  async saveToDisk(diskName: DriverKey, key: string): Promise<string> {
+  async saveToDisk(diskName: DiskName, key: string): Promise<string> {
     // 순환 의존성 방지를 위해 동적 import
     const { Sonamu } = await import("../api/sonamu");
     const disk = Sonamu.storage.use(diskName);

package/src/storage/index.ts

@@ -3,5 +3,5 @@ export { BaseFile } from "./base-file";
 export { BufferedFile } from "./buffered-file";
 export { type DriverKey, drivers } from "./drivers";
 export { StorageManager } from "./storage-manager";
-export type { KeyGenerator, StorageConfig } from "./types";
+export type { DiskName, KeyGenerator, StorageConfig } from "./types";
 export { UploadedFile as StreamedFile } from "./uploaded-file";

package/src/storage/storage-manager.ts

@@ -1,22 +1,21 @@
 import { Disk } from "flydrive";
 
 import { assertDefined } from "../utils/utils";
-import { type DriverKey } from "./drivers";
-import { type StorageConfig } from "./types";
+import { type DiskName, type StorageConfig } from "./types";
 
 /**
  * 여러 디스크를 관리하는 매니저
  */
 export class StorageManager {
-  private disks: Map<DriverKey, Disk> = new Map();
+  private disks: Map<DiskName, Disk> = new Map();
 
   constructor(private config: StorageConfig) {}
 
   /**
    * 디스크 인스턴스 반환 (lazy initialization)
-   * @param diskName 디스크 이름 (없으면 default)
+   * @param diskName 설정에 등록한 디스크 이름
    */
-  use(diskName: DriverKey): Disk {
+  use(diskName: DiskName): Disk {
     if (!this.disks.has(diskName)) {
       const factory = this.config.drivers[diskName];
       if (!factory) {

package/src/storage/storage.test-d.ts

@@ -0,0 +1,47 @@
+import { describe, expectTypeOf, it } from "vitest";
+
+import { type SonamuConfig } from "../api/config";
+import { type UploadDecoratorOptions } from "../api/decorators";
+import { Sonamu } from "../api/sonamu";
+import {
+  type BufferedFile,
+  type DriverKey,
+  drivers,
+  StorageManager,
+  type StorageConfig,
+  StreamedFile,
+} from "./index";
+
+describe("스토리지 디스크 이름", () => {
+  it("드라이버 종류와 독립적인 디스크 이름을 모든 업로드 경로에서 허용한다", () => {
+    const factory = drivers.fs({ location: "/tmp", visibility: "public" });
+    const storage = { drivers: { images: factory, private: factory } } satisfies StorageConfig;
+    expectTypeOf(storage).toExtend<NonNullable<SonamuConfig["server"]["storage"]>>();
+    const manager = new StorageManager(storage);
+    expectTypeOf(manager.use).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf(Sonamu.storage.use).parameter(0).toEqualTypeOf<string>();
+    expectTypeOf<BufferedFile["saveToDisk"]>().parameter(0).toEqualTypeOf<string>();
+    expectTypeOf<StreamedFile["diskName"]>().toEqualTypeOf<string>();
+    expectTypeOf<DriverKey>().toEqualTypeOf<"fs" | "s3">();
+    const options = { consume: "stream", destination: "images" } satisfies UploadDecoratorOptions;
+    expectTypeOf(options).toExtend<UploadDecoratorOptions>();
+    expectTypeOf(
+      new StreamedFile({
+        filename: "image.jpg",
+        mimetype: "image/jpeg",
+        size: 1,
+        url: "https://cdn.example.com/image.jpg",
+        signedUrl: "",
+        key: "image.jpg",
+        diskName: "images",
+      }),
+    ).toEqualTypeOf<StreamedFile>();
+  });
+
+  it("fs나 s3라는 이름의 디스크를 반드시 설정할 필요가 없다", () => {
+    const factory = drivers.fs({ location: "/tmp", visibility: "public" });
+    expectTypeOf({ drivers: { images: factory } }).toExtend<StorageConfig>();
+    expectTypeOf({ drivers: { fs: factory } }).toExtend<StorageConfig>();
+    expectTypeOf({ drivers: { s3: factory } }).toExtend<StorageConfig>();
+  });
+});

package/src/storage/types.ts

@@ -1,6 +1,7 @@
 import { type DriverContract } from "flydrive/types";
 
-import { type DriverKey } from "./drivers";
+/** storage.drivers에 등록한 디스크 이름. 드라이버 종류(fs·s3)와는 독립적이다. */
+export type DiskName = string;
 
 /**
  * Stream 모드에서 파일 키 생성 함수 타입
@@ -15,7 +16,7 @@ export type KeyGenerator = (file: {
  */
 export type StorageConfig = {
   /** 디스크별 드라이버 팩토리 */
-  drivers: Record<DriverKey, () => DriverContract>;
+  drivers: Record<DiskName, () => DriverContract>;
   /** stream 모드의 전역 키 생성 함수 (생략 시 timestamp-random 기본값) */
   keyGenerator?: KeyGenerator;
 };

package/src/storage/uploaded-file.ts

@@ -1,5 +1,5 @@
 import { BaseFile } from "./base-file";
-import { type DriverKey } from "./drivers";
+import { type DiskName } from "./types";
 
 /**
  * Stream 모드로 업로드된 파일
@@ -7,7 +7,7 @@ import { type DriverKey } from "./drivers";
  */
 export class UploadedFile extends BaseFile {
   private keyValue: string;
-  private diskNameValue: DriverKey;
+  private diskNameValue: DiskName;
 
   constructor(params: {
     filename: string;
@@ -16,7 +16,7 @@ export class UploadedFile extends BaseFile {
     url: string;
     signedUrl: string;
     key: string;
-    diskName: DriverKey;
+    diskName: DiskName;
   }) {
     super({
       filename: params.filename,
@@ -35,7 +35,7 @@ export class UploadedFile extends BaseFile {
   }
 
   /** 저장된 디스크 이름 */
-  get diskName(): DriverKey {
+  get diskName(): DiskName {
     return this.diskNameValue;
   }