@simplysm/storage 1.0.138 → 13.0.0-beta.2

package/src/clients/sftp-storage-client.ts

@@ -0,0 +1,135 @@
+import type { Bytes } from "@simplysm/core-common";
+import { SdError } from "@simplysm/core-common";
+import SftpClient from "ssh2-sftp-client";
+import type { Storage, FileInfo } from "../types/storage";
+import type { StorageConnConfig } from "../types/storage-conn-config";
+
+// ssh2-sftp-client 라이브러리 타입 정의에서 Buffer 사용
+type SftpGetResult = string | NodeJS.WritableStream | Bytes;
+
+/**
+ * SFTP 프로토콜을 사용하는 스토리지 클라이언트.
+ *
+ * @remarks
+ * 직접 사용보다 {@link StorageFactory.connect}를 통한 사용을 권장합니다.
+ */
+export class SftpStorageClient implements Storage {
+  private _client: SftpClient | undefined;
+
+  /**
+   * SFTP 서버에 연결합니다.
+   *
+   * @remarks
+   * - 연결 후 반드시 {@link close}로 연결을 종료해야 합니다.
+   * - 동일 인스턴스에서 여러 번 호출하지 마세요. (연결 누수 발생)
+   * - 자동 연결/종료 관리가 필요하면 {@link StorageFactory.connect}를 사용하세요. (권장)
+   */
+  async connect(config: StorageConnConfig): Promise<void> {
+    if (this._client !== undefined) {
+      throw new SdError("이미 SFTP 서버에 연결되어 있습니다. 먼저 close()를 호출하세요.");
+    }
+
+    const client = new SftpClient();
+    try {
+      await client.connect({
+        host: config.host,
+        port: config.port,
+        username: config.user,
+        password: config.pass,
+      });
+      this._client = client;
+    } catch (err) {
+      await client.end();
+      throw err;
+    }
+  }
+
+  private _requireClient(): SftpClient {
+    if (this._client === undefined) {
+      throw new SdError("SFTP 서버에 연결되어있지 않습니다.");
+    }
+    return this._client;
+  }
+
+  /** 디렉토리를 생성합니다. 상위 디렉토리가 없으면 함께 생성합니다. */
+  async mkdir(dirPath: string): Promise<void> {
+    await this._requireClient().mkdir(dirPath, true);
+  }
+
+  async rename(fromPath: string, toPath: string): Promise<void> {
+    await this._requireClient().rename(fromPath, toPath);
+  }
+
+  /**
+   * 파일 또는 디렉토리 존재 여부를 확인합니다.
+   *
+   * @remarks
+   * 상위 디렉토리가 존재하지 않는 경우에도 false를 반환합니다.
+   * 네트워크 오류, 권한 오류 등 모든 예외도 false를 반환합니다.
+   */
+  async exists(filePath: string): Promise<boolean> {
+    try {
+      // ssh2-sftp-client의 exists()는 false | 'd' | '-' | 'l' 를 반환한다.
+      // false: 존재하지 않음, 'd': 디렉토리, '-': 파일, 'l': 심볼릭 링크
+      const result = await this._requireClient().exists(filePath);
+      return typeof result === "string";
+    } catch {
+      return false;
+    }
+  }
+
+  async readdir(dirPath: string): Promise<FileInfo[]> {
+    const list = await this._requireClient().list(dirPath);
+    return list.map((item) => ({
+      name: item.name,
+      isFile: item.type === "-",
+    }));
+  }
+
+  async readFile(filePath: string): Promise<Bytes> {
+    // ssh2-sftp-client의 get()은 dst 미전달 시 Buffer를 반환한다.
+    // 타입 정의(string | WritableStream | Buffer)와 달리 실제로는 Buffer만 반환된다.
+    const result = (await this._requireClient().get(filePath)) as SftpGetResult;
+    if (result instanceof Uint8Array) {
+      return result;
+    }
+    // 타입 정의상 string도 가능하므로 방어 코드
+    if (typeof result === "string") {
+      return new TextEncoder().encode(result);
+    }
+    throw new SdError("예상치 못한 응답 타입입니다.");
+  }
+
+  async remove(filePath: string): Promise<void> {
+    await this._requireClient().delete(filePath);
+  }
+
+  /** 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드합니다. */
+  async put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void> {
+    if (typeof localPathOrBuffer === "string") {
+      await this._requireClient().fastPut(localPathOrBuffer, storageFilePath);
+    } else {
+      // eslint-disable-next-line no-restricted-globals -- ssh2-sftp-client 라이브러리 요구사항
+      await this._requireClient().put(Buffer.from(localPathOrBuffer), storageFilePath);
+    }
+  }
+
+  async uploadDir(fromPath: string, toPath: string): Promise<void> {
+    await this._requireClient().uploadDir(fromPath, toPath);
+  }
+
+  /**
+   * 연결을 종료합니다.
+   *
+   * @remarks
+   * 이미 종료된 상태에서 호출해도 에러가 발생하지 않습니다.
+   * 종료 후에는 동일 인스턴스에서 {@link connect}를 다시 호출하여 재연결할 수 있습니다.
+   */
+  async close(): Promise<void> {
+    if (this._client === undefined) {
+      return;
+    }
+    await this._client.end();
+    this._client = undefined;
+  }
+}

package/src/index.ts

@@ -1,4 +1,14 @@
-import "@simplysm/common";
-export * from "./common/IStorage";
-export * from "./ftp/FtpStorage";
-export * from "./ftp/IFtpConnectionConfig";
+//#region Types
+export * from "./types/storage-conn-config";
+export * from "./types/storage";
+export * from "./types/storage-type";
+//#endregion
+
+//#region Clients
+export * from "./clients/ftp-storage-client";
+export * from "./clients/sftp-storage-client";
+//#endregion
+
+//#region Factory
+export * from "./storage-factory";
+//#endregion

package/src/storage-factory.ts

@@ -0,0 +1,47 @@
+import type { StorageConnConfig } from "./types/storage-conn-config";
+import type { Storage } from "./types/storage";
+import type { StorageType } from "./types/storage-type";
+import { FtpStorageClient } from "./clients/ftp-storage-client";
+import { SftpStorageClient } from "./clients/sftp-storage-client";
+
+/**
+ * 스토리지 클라이언트 팩토리
+ *
+ * FTP, FTPS, SFTP 스토리지 연결을 생성하고 관리한다.
+ */
+export class StorageFactory {
+  /**
+   * 스토리지에 연결하고 콜백을 실행한 후 자동으로 연결을 종료한다.
+   *
+   * @remarks
+   * 콜백 패턴으로 연결/종료가 자동 관리되므로, 직접 클라이언트를 사용하는 것보다 권장된다.
+   * 콜백에서 예외가 발생해도 연결은 자동으로 종료된다.
+   */
+  static async connect<R>(
+    type: StorageType,
+    config: StorageConnConfig,
+    fn: (storage: Storage) => R | Promise<R>,
+  ): Promise<R> {
+    const client = StorageFactory._createClient(type);
+
+    await client.connect(config);
+    try {
+      return await fn(client);
+    } finally {
+      await client.close().catch(() => {
+        // 이미 닫힌 경우 무시
+      });
+    }
+  }
+
+  private static _createClient(type: StorageType): Storage {
+    switch (type) {
+      case "sftp":
+        return new SftpStorageClient();
+      case "ftps":
+        return new FtpStorageClient(true);
+      case "ftp":
+        return new FtpStorageClient(false);
+    }
+  }
+}

package/src/types/storage-conn-config.ts

@@ -0,0 +1,6 @@
+export interface StorageConnConfig {
+  host: string;
+  port?: number;
+  user?: string;
+  pass?: string;
+}

package/src/types/storage-type.ts

@@ -0,0 +1 @@
+export type StorageType = "ftp" | "ftps" | "sftp";

package/src/types/storage.ts

@@ -0,0 +1,20 @@
+import type { Bytes } from "@simplysm/core-common";
+import type { StorageConnConfig } from "./storage-conn-config";
+
+export interface FileInfo {
+  name: string;
+  isFile: boolean;
+}
+
+export interface Storage {
+  connect(config: StorageConnConfig): Promise<void>;
+  mkdir(dirPath: string): Promise<void>;
+  rename(fromPath: string, toPath: string): Promise<void>;
+  readdir(dirPath: string): Promise<FileInfo[]>;
+  readFile(filePath: string): Promise<Bytes>;
+  exists(filePath: string): Promise<boolean>;
+  put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void>;
+  uploadDir(fromPath: string, toPath: string): Promise<void>;
+  remove(filePath: string): Promise<void>;
+  close(): Promise<void>;
+}

package/tests/ftp-storage-client.spec.ts

@@ -0,0 +1,259 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { FtpStorageClient } from "../src/clients/ftp-storage-client";
+
+// basic-ftp 모듈 모킹
+const mockAccess = vi.fn().mockResolvedValue(undefined);
+const mockEnsureDir = vi.fn().mockResolvedValue(undefined);
+const mockRename = vi.fn().mockResolvedValue(undefined);
+const mockSize = vi.fn().mockResolvedValue(100);
+const mockList = vi.fn().mockResolvedValue([
+  { name: "file.txt", isFile: true },
+  { name: "dir", isFile: false },
+]);
+const mockDownloadTo = vi.fn().mockImplementation((writable) => {
+  writable.emit("data", new TextEncoder().encode("test content"));
+  return Promise.resolve();
+});
+const mockRemove = vi.fn().mockResolvedValue(undefined);
+const mockUploadFrom = vi.fn().mockResolvedValue(undefined);
+const mockUploadFromDir = vi.fn().mockResolvedValue(undefined);
+const mockClose = vi.fn();
+
+vi.mock("basic-ftp", () => {
+  return {
+    default: {
+      Client: class MockClient {
+        access = mockAccess;
+        ensureDir = mockEnsureDir;
+        rename = mockRename;
+        size = mockSize;
+        list = mockList;
+        downloadTo = mockDownloadTo;
+        remove = mockRemove;
+        uploadFrom = mockUploadFrom;
+        uploadFromDir = mockUploadFromDir;
+        close = mockClose;
+      },
+    },
+  };
+});
+
+describe("FtpStorageClient", () => {
+  let client: FtpStorageClient;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    client = new FtpStorageClient();
+  });
+
+  describe("connect", () => {
+    it("연결 설정으로 접속해야 함", async () => {
+      await client.connect({
+        host: "ftp.example.com",
+        port: 21,
+        user: "user",
+        pass: "pass",
+      });
+
+      expect(mockAccess).toHaveBeenCalledWith({
+        host: "ftp.example.com",
+        port: 21,
+        user: "user",
+        password: "pass",
+        secure: false,
+      });
+    });
+
+    it("secure 모드로 접속해야 함", async () => {
+      const secureClient = new FtpStorageClient(true);
+      await secureClient.connect({ host: "ftp.example.com" });
+
+      expect(mockAccess).toHaveBeenCalledWith(expect.objectContaining({ secure: true }));
+    });
+
+    it("이미 연결된 상태에서 connect 호출 시 에러", async () => {
+      await client.connect({ host: "test" });
+      await expect(client.connect({ host: "test" })).rejects.toThrow(
+        "이미 FTP 서버에 연결되어 있습니다. 먼저 close()를 호출하세요.",
+      );
+    });
+
+    it("연결 실패 시 클라이언트를 정리해야 함", async () => {
+      mockAccess.mockRejectedValueOnce(new Error("Auth failed"));
+      await expect(client.connect({ host: "test" })).rejects.toThrow("Auth failed");
+      expect(mockClose).toHaveBeenCalled();
+    });
+  });
+
+  describe("연결 전 메서드 호출", () => {
+    it("연결 전 mkdir 호출 시 에러", async () => {
+      await expect(client.mkdir("/test")).rejects.toThrow("FTP 서버에 연결되어있지 않습니다.");
+    });
+
+    it("연결 전 rename 호출 시 에러", async () => {
+      await expect(client.rename("/from", "/to")).rejects.toThrow("FTP 서버에 연결되어있지 않습니다.");
+    });
+
+    it("연결 전 readdir 호출 시 에러", async () => {
+      await expect(client.readdir("/")).rejects.toThrow("FTP 서버에 연결되어있지 않습니다.");
+    });
+  });
+
+  describe("mkdir", () => {
+    it("디렉토리를 생성해야 함", async () => {
+      await client.connect({ host: "test" });
+      await client.mkdir("/test/dir");
+
+      expect(mockEnsureDir).toHaveBeenCalledWith("/test/dir");
+    });
+  });
+
+  describe("rename", () => {
+    it("파일/디렉토리 이름을 변경해야 함", async () => {
+      await client.connect({ host: "test" });
+      await client.rename("/from", "/to");
+
+      expect(mockRename).toHaveBeenCalledWith("/from", "/to");
+    });
+  });
+
+  describe("readdir", () => {
+    it("디렉토리 목록을 FileInfo 배열로 반환해야 함", async () => {
+      await client.connect({ host: "test" });
+      const result = await client.readdir("/");
+
+      expect(result).toEqual([
+        { name: "file.txt", isFile: true },
+        { name: "dir", isFile: false },
+      ]);
+    });
+  });
+
+  describe("readFile", () => {
+    it("파일 내용을 Uint8Array로 반환해야 함", async () => {
+      await client.connect({ host: "test" });
+      const result = await client.readFile("/file.txt");
+
+      expect(result).toBeInstanceOf(Uint8Array);
+      expect(new TextDecoder().decode(result)).toBe("test content");
+    });
+  });
+
+  describe("exists", () => {
+    it("파일이 존재하면 true 반환 (size로 확인)", async () => {
+      await client.connect({ host: "test" });
+      const result = await client.exists("/path/file.txt");
+
+      expect(mockSize).toHaveBeenCalledWith("/path/file.txt");
+      expect(result).toBe(true);
+    });
+
+    it("디렉토리가 존재하면 true 반환 (list로 확인)", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      await client.connect({ host: "test" });
+      const result = await client.exists("/path/dir");
+
+      expect(mockList).toHaveBeenCalledWith("/path");
+      expect(result).toBe(true);
+    });
+
+    it("파일이 존재하지 않으면 false 반환", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      mockList.mockResolvedValueOnce([]);
+      await client.connect({ host: "test" });
+      const result = await client.exists("/path/nonexistent.txt");
+
+      expect(result).toBe(false);
+    });
+
+    it("에러 발생 시 false 반환", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      mockList.mockRejectedValueOnce(new Error("Not found"));
+      await client.connect({ host: "test" });
+      const result = await client.exists("/path/error.txt");
+
+      expect(result).toBe(false);
+    });
+
+    it("루트 디렉토리 파일 존재 확인", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      await client.connect({ host: "test" });
+      const result = await client.exists("/file.txt");
+
+      expect(mockList).toHaveBeenCalledWith("/");
+      expect(result).toBe(true);
+    });
+
+    it("슬래시 없는 경로 존재 확인", async () => {
+      mockSize.mockRejectedValueOnce(new Error("Not a file"));
+      await client.connect({ host: "test" });
+      const result = await client.exists("file.txt");
+
+      expect(mockList).toHaveBeenCalledWith("/");
+      expect(result).toBe(true);
+    });
+  });
+
+  describe("remove", () => {
+    it("파일을 삭제해야 함", async () => {
+      await client.connect({ host: "test" });
+      await client.remove("/file.txt");
+
+      expect(mockRemove).toHaveBeenCalledWith("/file.txt");
+    });
+  });
+
+  describe("put", () => {
+    it("로컬 경로에서 업로드해야 함", async () => {
+      await client.connect({ host: "test" });
+      await client.put("/local/file.txt", "/remote/file.txt");
+
+      expect(mockUploadFrom).toHaveBeenCalledWith("/local/file.txt", "/remote/file.txt");
+    });
+
+    it("Uint8Array에서 업로드해야 함", async () => {
+      await client.connect({ host: "test" });
+      const bytes = new TextEncoder().encode("content");
+      await client.put(bytes, "/remote/file.txt");
+
+      expect(mockUploadFrom).toHaveBeenCalled();
+    });
+  });
+
+  describe("uploadDir", () => {
+    it("디렉토리를 업로드해야 함", async () => {
+      await client.connect({ host: "test" });
+      await client.uploadDir("/local/dir", "/remote/dir");
+
+      expect(mockUploadFromDir).toHaveBeenCalledWith("/local/dir", "/remote/dir");
+    });
+  });
+
+  describe("close", () => {
+    it("연결 전 close 호출 시 에러 없이 종료", async () => {
+      await expect(client.close()).resolves.toBeUndefined();
+    });
+
+    it("연결을 닫아야 함", async () => {
+      await client.connect({ host: "test" });
+      await client.close();
+
+      expect(mockClose).toHaveBeenCalled();
+    });
+
+    it("close 후 메서드 호출 시 에러", async () => {
+      await client.connect({ host: "test" });
+      await client.close();
+
+      await expect(client.mkdir("/test")).rejects.toThrow("FTP 서버에 연결되어있지 않습니다.");
+    });
+
+    it("close 후 재연결이 가능해야 함", async () => {
+      await client.connect({ host: "test" });
+      await client.close();
+      await client.connect({ host: "test" });
+
+      expect(mockAccess).toHaveBeenCalledTimes(2);
+    });
+  });
+});