@simplysm/storage 13.0.100 → 14.0.4

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

@@ -1,32 +1,35 @@
 import type { Bytes } from "@simplysm/core-common";
 import { SdError } from "@simplysm/core-common";
 import SftpClient from "ssh2-sftp-client";
+import fsP from "fs/promises";
+import os from "os";
+import pathMod from "path";
 import type { StorageClient, FileInfo } from "../types/storage";
 import type { StorageConnConfig } from "../types/storage-conn-config";
 
-// Buffer usage from ssh2-sftp-client library type definitions
+// ssh2-sftp-client 라이브러리 타입 정의에서의 Buffer 사용
 type SftpGetResult = string | NodeJS.WritableStream | Bytes;
 
 /**
- * Storage client using SFTP protocol.
+ * SFTP 프로토콜을 사용하는 스토리지 클라이언트.
  *
  * @remarks
- * Using {@link StorageFactory.connect} is recommended over direct usage.
+ * 직접 사용하기보다 {@link StorageFactory.connect} 사용을 권장합니다.
  */
 export class SftpStorageClient implements StorageClient {
   private _client: SftpClient | undefined;
 
   /**
-   * Connect to the SFTP server.
+   * SFTP 서버에 연결합니다.
    *
    * @remarks
-   * - Must close the connection with {@link close} after use.
-   * - Do not call multiple times on the same instance (connection leak).
-   * - Use {@link StorageFactory.connect} for automatic connection/close management (recommended).
+   * - 사용 후 {@link close}로 연결을 종료해야 합니다.
+   * - 동일 인스턴스에서 여러 번 호출하지 마세요 (연결 누수).
+   * - 자동 연결/종료 관리를 위해 {@link StorageFactory.connect} 사용을 권장합니다.
    */
   async connect(config: StorageConnConfig): Promise<void> {
     if (this._client !== undefined) {
-      throw new SdError("SFTP server is already connected. Please call close() first.");
+      throw new SdError("SFTP 서버에 이미 연결되어 있습니다. 먼저 close()를 호출해 주세요.");
     }
 
     const client = new SftpClient();
@@ -39,10 +42,7 @@ export class SftpStorageClient implements StorageClient {
           password: config.password,
         });
       } else {
-        // Authenticate with SSH agent + key file
-        const fsP = await import("fs/promises");
-        const os = await import("os");
-        const pathMod = await import("path");
+        // SSH agent + 키 파일로 인증
         const keyPath = pathMod.join(os.homedir(), ".ssh", "id_ed25519");
 
         const baseOptions = {
@@ -58,7 +58,7 @@ export class SftpStorageClient implements StorageClient {
             privateKey: await fsP.readFile(keyPath),
           });
         } catch {
-          // privateKey parsing failed (encrypted key, etc.) -> retry with agent only
+          // privateKey 파싱 실패 (암호화된 키 등) -> agent만으로 재시도
           await client.connect(baseOptions);
         }
       }
@@ -71,12 +71,12 @@ export class SftpStorageClient implements StorageClient {
 
   private _requireClient(): SftpClient {
     if (this._client === undefined) {
-      throw new SdError("Not connected to SFTP server.");
+      throw new SdError("SFTP 서버에 연결되어 있지 않습니다.");
     }
     return this._client;
   }
 
-  /** Create a directory. Creates parent directories if they do not exist. */
+  /** 디렉토리를 생성합니다. 부모 디렉토리가 없으면 함께 생성합니다. */
   async mkdir(dirPath: string): Promise<void> {
     await this._requireClient().mkdir(dirPath, true);
   }
@@ -86,16 +86,16 @@ export class SftpStorageClient implements StorageClient {
   }
 
   /**
-   * Check whether a file or directory exists.
+   * 파일 또는 디렉토리의 존재 여부를 확인합니다.
    *
    * @remarks
-   * Returns false even if the parent directory does not exist.
-   * Returns false for all exceptions including network errors and permission errors.
+   * 부모 디렉토리가 존재하지 않아도 false를 반환합니다.
+   * 네트워크 오류, 권한 오류 등 모든 예외에 대해 false를 반환합니다.
    */
   async exists(filePath: string): Promise<boolean> {
     try {
-      // ssh2-sftp-client's exists() returns false | 'd' | '-' | 'l'.
-      // false: does not exist, 'd': directory, '-': file, 'l': symbolic link
+      // ssh2-sftp-client의 exists()는 false | 'd' | '-' | 'l'을 반환합니다.
+      // false: 존재하지 않음, 'd': 디렉토리, '-': 파일, 'l': 심볼릭 링크
       const result = await this._requireClient().exists(filePath);
       return typeof result === "string";
     } catch {
@@ -112,24 +112,24 @@ export class SftpStorageClient implements StorageClient {
   }
 
   async readFile(filePath: string): Promise<Bytes> {
-    // ssh2-sftp-client's get() returns Buffer when dst is not provided.
-    // Despite the type definition (string | WritableStream | Buffer), only Buffer is actually returned.
+    // 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;
     }
-    // Defensive code since string is possible per type definition
+    // 타입 정의상 string도 가능하므로 방어 코드
     if (typeof result === "string") {
       return new TextEncoder().encode(result);
     }
-    throw new SdError("Unexpected response type.");
+    throw new SdError("예상하지 못한 응답 타입입니다.");
   }
 
   async remove(filePath: string): Promise<void> {
     await this._requireClient().delete(filePath);
   }
 
-  /** Upload a local file path or byte data to the remote path. */
+  /** 로컬 파일 경로 또는 바이트 데이터를 원격 경로에 업로드합니다. */
   async put(localPathOrBuffer: string | Bytes, storageFilePath: string): Promise<void> {
     if (typeof localPathOrBuffer === "string") {
       await this._requireClient().fastPut(localPathOrBuffer, storageFilePath);
@@ -144,11 +144,11 @@ export class SftpStorageClient implements StorageClient {
   }
 
   /**
-   * Close the connection.
+   * 연결을 종료합니다.
    *
    * @remarks
-   * Safe to call when already closed (no error thrown).
-   * After closing, you can reconnect by calling {@link connect} again on the same instance.
+   * 이미 종료된 상태에서 호출해도 안전합니다 (오류 미발생).
+   * 종료 후 동일 인스턴스에서 {@link connect}를 다시 호출하여 재연결할 수 있습니다.
    */
   async close(): Promise<void> {
     if (this._client === undefined) {

package/src/index.ts

@@ -1,11 +1,11 @@
-// Types
+// 타입
 export * from "./types/storage-conn-config";
 export * from "./types/storage";
 export * from "./types/storage-type";
 
-// Clients
+// 클라이언트
 export * from "./clients/ftp-storage-client";
 export * from "./clients/sftp-storage-client";
 
-// Factory
+// 팩토리
 export * from "./storage-factory";

package/src/storage-factory.ts

@@ -5,17 +5,17 @@ import { FtpStorageClient } from "./clients/ftp-storage-client";
 import { SftpStorageClient } from "./clients/sftp-storage-client";
 
 /**
- * Storage client factory
+ * 스토리지 클라이언트 팩토리
  *
- * Creates and manages FTP, FTPS, and SFTP storage connections.
+ * FTP, FTPS, SFTP 스토리지 연결을 생성하고 관리합니다.
  */
 export class StorageFactory {
   /**
-   * Connect to storage, execute the callback, and automatically close the connection.
+   * 스토리지에 연결하고, 콜백을 실행한 후, 자동으로 연결을 종료합니다.
    *
    * @remarks
-   * The callback pattern auto-manages connection/close, so this is preferred over direct client usage.
-   * The connection is automatically closed even if the callback throws an exception.
+   * 콜백 패턴으로 연결/종료를 자동 관리하므로 직접 클라이언트를 사용하는 것보다 권장됩니다.
+   * 콜백에서 예외가 발생해도 연결은 자동으로 종료됩니다.
    */
   static async connect<R>(
     type: StorageProtocol,
@@ -29,7 +29,7 @@ export class StorageFactory {
       return await fn(client);
     } finally {
       await client.close().catch(() => {
-        // Ignore if already closed
+        // 이미 종료된 경우 무시
       });
     }
   }

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

@@ -1,261 +0,0 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
-import { FtpStorageClient } from "../src/clients/ftp-storage-client";
-
-// Mock basic-ftp module
-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("Should connect with connection settings", async () => {
-      await client.connect({
-        host: "ftp.example.com",
-        port: 21,
-        user: "user",
-        password: "pass",
-      });
-
-      expect(mockAccess).toHaveBeenCalledWith({
-        host: "ftp.example.com",
-        port: 21,
-        user: "user",
-        password: "pass",
-        secure: false,
-      });
-    });
-
-    it("Should connect in secure mode", async () => {
-      const secureClient = new FtpStorageClient(true);
-      await secureClient.connect({ host: "ftp.example.com" });
-
-      expect(mockAccess).toHaveBeenCalledWith(expect.objectContaining({ secure: true }));
-    });
-
-    it("Should throw error when connect is called on already connected client", async () => {
-      await client.connect({ host: "test" });
-      await expect(client.connect({ host: "test" })).rejects.toThrow(
-        "FTP server is already connected. Please call close() first.",
-      );
-    });
-
-    it("Should clean up client on connection failure", async () => {
-      mockAccess.mockRejectedValueOnce(new Error("Auth failed"));
-      await expect(client.connect({ host: "test" })).rejects.toThrow("Auth failed");
-      expect(mockClose).toHaveBeenCalled();
-    });
-  });
-
-  describe("Method calls before connection", () => {
-    it("Should throw error when mkdir is called before connection", async () => {
-      await expect(client.mkdir("/test")).rejects.toThrow("Not connected to FTP server.");
-    });
-
-    it("Should throw error when rename is called before connection", async () => {
-      await expect(client.rename("/from", "/to")).rejects.toThrow(
-        "Not connected to FTP server.",
-      );
-    });
-
-    it("Should throw error when list is called before connection", async () => {
-      await expect(client.list("/")).rejects.toThrow("Not connected to FTP server.");
-    });
-  });
-
-  describe("mkdir", () => {
-    it("Should create directory", async () => {
-      await client.connect({ host: "test" });
-      await client.mkdir("/test/dir");
-
-      expect(mockEnsureDir).toHaveBeenCalledWith("/test/dir");
-    });
-  });
-
-  describe("rename", () => {
-    it("Should rename file/directory", async () => {
-      await client.connect({ host: "test" });
-      await client.rename("/from", "/to");
-
-      expect(mockRename).toHaveBeenCalledWith("/from", "/to");
-    });
-  });
-
-  describe("list", () => {
-    it("Should return directory list as FileInfo array", async () => {
-      await client.connect({ host: "test" });
-      const result = await client.list("/");
-
-      expect(result).toEqual([
-        { name: "file.txt", isFile: true },
-        { name: "dir", isFile: false },
-      ]);
-    });
-  });
-
-  describe("readFile", () => {
-    it("Should return file content as 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("Should return true if file exists (checked via 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("Should return true if directory exists (checked via 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("Should return false if file does not exist", 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("Should return false on error", 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("Should check file existence in root directory", 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("Should check file existence for paths without slashes", 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("Should delete file", async () => {
-      await client.connect({ host: "test" });
-      await client.remove("/file.txt");
-
-      expect(mockRemove).toHaveBeenCalledWith("/file.txt");
-    });
-  });
-
-  describe("put", () => {
-    it("Should upload from local path", 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("Should upload from 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("Should upload directory", async () => {
-      await client.connect({ host: "test" });
-      await client.uploadDir("/local/dir", "/remote/dir");
-
-      expect(mockUploadFromDir).toHaveBeenCalledWith("/local/dir", "/remote/dir");
-    });
-  });
-
-  describe("close", () => {
-    it("Should exit without error when close is called before connection", async () => {
-      await expect(client.close()).resolves.toBeUndefined();
-    });
-
-    it("Should close connection", async () => {
-      await client.connect({ host: "test" });
-      await client.close();
-
-      expect(mockClose).toHaveBeenCalled();
-    });
-
-    it("Should throw error when calling method after close", async () => {
-      await client.connect({ host: "test" });
-      await client.close();
-
-      await expect(client.mkdir("/test")).rejects.toThrow("Not connected to FTP server.");
-    });
-
-    it("Should allow reconnection after close", async () => {
-      await client.connect({ host: "test" });
-      await client.close();
-      await client.connect({ host: "test" });
-
-      expect(mockAccess).toHaveBeenCalledTimes(2);
-    });
-  });
-});