@simplysm/service-client 13.0.0-beta.6

package/src/features/file-client.ts

@@ -0,0 +1,56 @@
+import type { Bytes } from "@simplysm/core-common";
+import type { ServiceUploadResult } from "@simplysm/service-common";
+
+export class FileClient {
+  constructor(
+    private readonly _hostUrl: string,
+    private readonly _clientName: string,
+  ) {}
+
+  async download(relPath: string): Promise<Bytes> {
+    // URL 구성
+    const url = `${this._hostUrl}${relPath.startsWith("/") ? "" : "/"}${relPath}`;
+
+    const res = await fetch(url);
+    if (!res.ok) {
+      throw new Error(`Download failed: ${res.status} ${res.statusText}`);
+    }
+
+    // ArrayBuffer -> Uint8Array
+    return new Uint8Array(await res.arrayBuffer());
+  }
+
+  async upload(
+    files: File[] | FileList | { name: string; data: BlobPart }[],
+    authToken: string,
+  ): Promise<ServiceUploadResult[]> {
+    const formData = new FormData();
+    const fileList = files instanceof FileList ? Array.from(files) : files;
+
+    for (const file of fileList) {
+      if ("data" in file) {
+        // 커스텀 객체 ({ name, data })
+        const blob = file.data instanceof Blob ? file.data : new Blob([file.data]);
+        formData.append("files", blob, file.name);
+      } else {
+        // 브라우저 File 객체
+        formData.append("files", file, file.name);
+      }
+    }
+
+    const res = await fetch(`${this._hostUrl}/upload`, {
+      method: "POST",
+      headers: {
+        "x-sd-client-name": this._clientName,
+        "Authorization": `Bearer ${authToken}`,
+      },
+      body: formData,
+    });
+
+    if (!res.ok) {
+      throw new Error(`Upload failed: ${res.statusText}`);
+    }
+
+    return res.json();
+  }
+}

package/src/features/orm/orm-client-connector.ts

@@ -0,0 +1,50 @@
+import { OrmClientDbContextExecutor } from "./orm-client-db-context-executor";
+import type { OrmConnectConfig } from "./orm-connect-config";
+import type { DbContext } from "@simplysm/orm-common";
+import type { ServiceClient } from "../../service-client";
+
+export class OrmClientConnector {
+  constructor(private readonly _serviceClient: ServiceClient) {}
+
+  async connect<T extends DbContext, R>(
+    config: OrmConnectConfig<T>,
+    callback: (conn: T) => Promise<R> | R,
+  ): Promise<R> {
+    const executor = new OrmClientDbContextExecutor(this._serviceClient, config.connOpt);
+    const info = await executor.getInfo();
+    const db = new config.dbContextType(executor, {
+      dialect: info.dialect,
+      database: config.dbContextOpt?.database ?? info.database,
+      schema: config.dbContextOpt?.schema ?? info.schema,
+    });
+    return db.connect(async () => {
+      try {
+        return await callback(db);
+      } catch (err) {
+        if (
+          err instanceof Error &&
+          (err.message.includes("a parent row: a foreign key constraint") ||
+            err.message.includes("conflicted with the REFERENCE"))
+        ) {
+          err.message = "경고! 연결된 작업에 의한 처리 거부. 후속작업 확인요망";
+        }
+
+        throw err;
+      }
+    });
+  }
+
+  async connectWithoutTransaction<T extends DbContext, R>(
+    config: OrmConnectConfig<T>,
+    callback: (conn: T) => Promise<R> | R,
+  ): Promise<R> {
+    const executor = new OrmClientDbContextExecutor(this._serviceClient, config.connOpt);
+    const info = await executor.getInfo();
+    const db = new config.dbContextType(executor, {
+      dialect: info.dialect,
+      database: config.dbContextOpt?.database ?? info.database,
+      schema: config.dbContextOpt?.schema ?? info.schema,
+    });
+    return db.connectWithoutTransaction(async () => callback(db));
+  }
+}

package/src/features/orm/orm-client-db-context-executor.ts

@@ -0,0 +1,98 @@
+import type {
+  DbContextExecutor,
+  ColumnMeta,
+  ResultMeta,
+  IsolationLevel,
+  Dialect,
+  QueryDef,
+} from "@simplysm/orm-common";
+import type { OrmService, DbConnOptions } from "@simplysm/service-common";
+import type { ServiceClient } from "../../service-client";
+
+export class OrmClientDbContextExecutor implements DbContextExecutor {
+  private _connId?: number;
+  private readonly _ormService: OrmService;
+
+  constructor(
+    private readonly _client: ServiceClient,
+    private readonly _opt: DbConnOptions & { configName: string },
+  ) {
+    // "SdOrmService" → "OrmService" 변경
+    this._ormService = _client.getService<OrmService>("OrmService");
+  }
+
+  async getInfo(): Promise<{
+    dialect: Dialect;
+    database?: string;
+    schema?: string;
+  }> {
+    return this._ormService.getInfo(this._opt);
+  }
+
+  async connect(): Promise<void> {
+    this._connId = await this._ormService.connect(this._opt);
+  }
+
+  async beginTransaction(isolationLevel?: IsolationLevel): Promise<void> {
+    if (this._connId === undefined) {
+      throw new Error("DB에 연결되어있지 않습니다.");
+    }
+
+    await this._ormService.beginTransaction(this._connId, isolationLevel);
+  }
+
+  async commitTransaction(): Promise<void> {
+    if (this._connId === undefined) {
+      throw new Error("DB에 연결되어있지 않습니다.");
+    }
+
+    await this._ormService.commitTransaction(this._connId);
+  }
+
+  async rollbackTransaction(): Promise<void> {
+    if (this._connId === undefined) {
+      throw new Error("DB에 연결되어있지 않습니다.");
+    }
+
+    await this._ormService.rollbackTransaction(this._connId);
+  }
+
+  async close(): Promise<void> {
+    if (this._connId === undefined) {
+      throw new Error("DB에 연결되어있지 않습니다.");
+    }
+
+    await this._ormService.close(this._connId);
+  }
+
+  async executeDefs<T = Record<string, unknown>>(
+    defs: QueryDef[],
+    options?: (ResultMeta | undefined)[],
+  ): Promise<T[][]> {
+    if (this._connId === undefined) {
+      throw new Error("DB에 연결되어있지 않습니다.");
+    }
+
+    return (await this._ormService.executeDefs(this._connId, defs, options)) as T[][];
+  }
+
+  async executeParametrized(query: string, params?: unknown[]): Promise<unknown[][]> {
+    if (this._connId === undefined) {
+      throw new Error("DB에 연결되어있지 않습니다.");
+    }
+
+    return this._ormService.executeParametrized(this._connId, query, params);
+  }
+
+  async bulkInsert(
+    tableName: string,
+    columnDefs: Record<string, ColumnMeta>,
+    records: Record<string, unknown>[],
+  ): Promise<void> {
+    if (this._connId === undefined) {
+      throw new Error("DB에 연결되어있지 않습니다.");
+    }
+
+    return this._ormService.bulkInsert(this._connId, tableName, columnDefs, records);
+  }
+}

package/src/features/orm/orm-connect-config.ts

@@ -0,0 +1,11 @@
+import type { Type } from "@simplysm/core-common";
+import type { DbConnOptions } from "@simplysm/service-common";
+
+export interface OrmConnectConfig<T> {
+  dbContextType: Type<T>;
+  connOpt: DbConnOptions & { configName: string };
+  dbContextOpt?: {
+    database: string;
+    schema: string;
+  };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+// Types
+export * from "./types/connection-config";
+export * from "./types/progress.types";
+
+// Transport
+export * from "./transport/socket-provider";
+export * from "./transport/service-transport";
+
+// Protocol
+export * from "./protocol/client-protocol-wrapper";
+
+// Features
+export * from "./features/event-client";
+export * from "./features/file-client";
+export * from "./features/orm/orm-connect-config";
+export * from "./features/orm/orm-client-connector";
+export * from "./features/orm/orm-client-db-context-executor";
+
+// Main
+export * from "./service-client";

package/src/protocol/client-protocol-wrapper.ts

@@ -0,0 +1,132 @@
+import type { Bytes } from "@simplysm/core-common";
+import { LazyGcMap, transferableDecode, Uuid } from "@simplysm/core-common";
+import type { ServiceMessageDecodeResult, ServiceMessage } from "@simplysm/service-common";
+import { ServiceProtocol } from "@simplysm/service-common";
+
+export class ClientProtocolWrapper {
+  // 기준값: 30KB
+  private readonly _SIZE_THRESHOLD = 30 * 1024;
+
+  // 메인 스레드용 프로토콜 (가벼운 작업용)
+  private readonly _protocol = new ServiceProtocol();
+
+  // 워커 스레드 (무거운 작업용)
+  private static _worker?: Worker;
+  // 워커 요청 대기열 (Key: UUID)
+  private static readonly _workerResolvers = new LazyGcMap<
+    string,
+    { resolve: (res: unknown) => void; reject: (err: Error) => void }
+  >({
+    gcInterval: 5 * 1000, // 5초마다 만료 검사
+    expireTime: 60 * 1000, // 60초가 지나면 만료 (타임아웃)
+    onExpire: (key, item) => {
+      // 만료 시 reject 호출 (메모리 릭 방지 핵심)
+      item.reject(new Error(`Worker task timed out (uuid: ${key})`));
+    },
+  });
+
+  // Worker 사용 가능 여부 (브라우저 환경에서만 true)
+  private static _workerAvailable: boolean | undefined;
+
+  private static get workerAvailable(): boolean {
+    if (this._workerAvailable === undefined) {
+      this._workerAvailable = typeof Worker !== "undefined";
+    }
+    return this._workerAvailable;
+  }
+
+  private static get worker(): Worker | undefined {
+    if (!this.workerAvailable) {
+      return undefined;
+    }
+
+    if (!this._worker) {
+      // Vite/Esbuild/Webpack 등 모던 번들러는 이 문법을 통해 Worker를 별도 파일로 분리/로드함
+      // 주의: import.meta.resolve 대신 상대경로 사용 (Vite 호환)
+      this._worker = new Worker(new URL("../workers/client-protocol.worker.ts", import.meta.url), {
+        type: "module",
+      });
+
+      this._worker.onmessage = (event: MessageEvent) => {
+        const { id, type, result, error } = event.data as {
+          id: string;
+          type: "success" | "error";
+          result?: unknown;
+          error?: { message: string; stack?: string };
+        };
+
+        const resolver = this._workerResolvers.get(id);
+        if (resolver != null) {
+          if (type === "success") {
+            resolver.resolve(result);
+          } else {
+            const err = new Error(error?.message ?? "Unknown worker error");
+            err.stack = error?.stack;
+            resolver.reject(err);
+          }
+          this._workerResolvers.delete(id);
+        }
+      };
+    }
+    return this._worker;
+  }
+
+  /**
+   * Worker에 작업 위임 및 결과 대기
+   * 주의: workerAvailable이 true일 때만 호출해야 함
+   */
+  private async _runWorker(type: "encode" | "decode", data: unknown, transfer: Transferable[] = []): Promise<unknown> {
+    return new Promise((resolve, reject) => {
+      const id = Uuid.new().toString();
+
+      ClientProtocolWrapper._workerResolvers.set(id, { resolve, reject });
+      // workerAvailable 체크 후 호출되므로 worker는 항상 존재
+      ClientProtocolWrapper.worker!.postMessage({ id, type, data }, { transfer });
+    });
+  }
+
+  async encode(uuid: string, message: ServiceMessage): Promise<{ chunks: Bytes[]; totalSize: number }> {
+    // Worker가 없거나 작은 데이터는 메인 스레드에서 처리
+    if (!ClientProtocolWrapper.workerAvailable || !this._shouldUseWorkerForEncode(message)) {
+      return this._protocol.encode(uuid, message);
+    }
+
+    // [Worker]
+    // Encode는 객체를 보내야 하므로 Structured Clone이 발생함.
+    // 하지만 JSON.stringify 비용을 메인 스레드에서 제거하는 이득이 더 큼.
+    return (await this._runWorker("encode", { uuid, message })) as {
+      chunks: Bytes[];
+      totalSize: number;
+    };
+  }
+
+  async decode(bytes: Bytes): Promise<ServiceMessageDecodeResult<ServiceMessage>> {
+    const totalSize = bytes.length;
+
+    // Worker가 없거나 작은 데이터는 메인 스레드에서 처리
+    if (!ClientProtocolWrapper.workerAvailable || totalSize <= this._SIZE_THRESHOLD) {
+      return this._protocol.decode(bytes);
+    }
+
+    // [Worker]
+    // Zero-Copy 전송 (buffer의 소유권이 Worker로 넘어감)
+    const rawResult = await this._runWorker("decode", bytes, [bytes.buffer]);
+
+    // Worker에서 온 결과(Plain Object)를 클래스 인스턴스(DateTime 등)로 복원
+    return transferableDecode(rawResult) as ServiceMessageDecodeResult<ServiceMessage>;
+  }
+
+  private _shouldUseWorkerForEncode(msg: ServiceMessage): boolean {
+    if (!("body" in msg)) return false;
+    const body = msg.body;
+
+    // Uint8Array가 있거나, 배열 길이가 길면 워커 사용
+    if (body instanceof Uint8Array) return true;
+    if (typeof body === "string" && body.length > this._SIZE_THRESHOLD) return true;
+    if (Array.isArray(body)) {
+      return body.length > 100 || (body.length > 0 && body[0] instanceof Uint8Array);
+    }
+
+    return false;
+  }
+}

package/src/service-client.ts

@@ -0,0 +1,157 @@
+import { createConsola } from "consola";
+import type { Type } from "@simplysm/core-common";
+import { EventEmitter } from "@simplysm/core-common";
+import type { ServiceEventListener } from "@simplysm/service-common";
+
+import type { ServiceConnectionConfig } from "./types/connection-config";
+import type { ServiceProgress, ServiceProgressState } from "./types/progress.types";
+import { ServiceTransport } from "./transport/service-transport";
+import { SocketProvider } from "./transport/socket-provider";
+import { EventClient } from "./features/event-client";
+import { FileClient } from "./features/file-client";
+
+const logger = createConsola().withTag("service-client:ServiceClient");
+
+interface ServiceClientEvents {
+  "request-progress": ServiceProgressState;
+  "response-progress": ServiceProgressState;
+  "state": "connected" | "closed" | "reconnecting";
+  "reload": Set<string>;
+}
+
+export class ServiceClient extends EventEmitter<ServiceClientEvents> {
+  // 모듈들
+  private readonly _socket: SocketProvider;
+  private readonly _transport: ServiceTransport;
+  private readonly _eventClient: EventClient;
+  private readonly _fileClient: FileClient;
+
+  private _authToken?: string;
+
+  // 상태 접근자
+  get connected() {
+    return this._socket.connected;
+  }
+  get hostUrl() {
+    const hostProtocol = this.options.ssl ? "https" : "http";
+    return `${hostProtocol}://${this.options.host}:${this.options.port}`;
+  }
+
+  constructor(
+    public readonly name: string,
+    public readonly options: ServiceConnectionConfig,
+  ) {
+    super();
+
+    const wsProtocol = options.ssl ? "wss" : "ws";
+    const wsUrl = `${wsProtocol}://${options.host}:${options.port}/ws`;
+
+    // 모듈 초기화
+    this._socket = new SocketProvider(wsUrl, this.name, this.options.maxReconnectCount ?? 10);
+    this._transport = new ServiceTransport(this._socket);
+    this._eventClient = new EventClient(this._transport);
+    this._fileClient = new FileClient(this.hostUrl, this.name);
+
+    // 이벤트 바인딩
+    this._socket.on("state", async (state) => {
+      this.emit("state", state);
+
+      // 재연결 시 이벤트 리스너 자동 복구
+      if (state === "connected") {
+        try {
+          if (this._authToken != null) {
+            await this.auth(this._authToken); // 재인증
+          }
+          await this._eventClient.reRegisterAll();
+        } catch (err) {
+          logger.error("이벤트 리스너 복구 실패", err);
+        }
+      }
+    });
+
+    this._transport.on("reload", (changedFiles) => {
+      this.emit("reload", changedFiles);
+    });
+  }
+
+  // 타입 안전성을 위한 Proxy 생성 메소드
+  getService<T>(serviceName: string): RemoteService<T> {
+    return new Proxy({} as RemoteService<T>, {
+      get: (_target, prop) => {
+        const methodName = String(prop);
+        return async (...params: unknown[]) => {
+          return this.send(serviceName, methodName, params);
+        };
+      },
+    });
+  }
+
+  async connect(): Promise<void> {
+    await this._socket.connect();
+  }
+
+  async close(): Promise<void> {
+    await this._socket.close();
+  }
+
+  async send(serviceName: string, methodName: string, params: unknown[], progress?: ServiceProgress): Promise<unknown> {
+    return this._transport.send(
+      {
+        name: `${serviceName}.${methodName}`,
+        body: params,
+      },
+      {
+        request: (state) => {
+          this.emit("request-progress", state);
+          progress?.request?.(state);
+        },
+        response: (state) => {
+          this.emit("response-progress", state);
+          progress?.response?.(state);
+        },
+      },
+    );
+  }
+
+  async auth(token: string): Promise<void> {
+    await this._transport.send({ name: "auth", body: token });
+    this._authToken = token;
+  }
+
+  async addEventListener<T extends ServiceEventListener<unknown, unknown>>(
+    eventType: Type<T>,
+    info: T["$info"],
+    cb: (data: T["$data"]) => PromiseLike<void>,
+  ): Promise<string> {
+    if (!this.connected) throw new Error("서버와 연결되어있지 않습니다.");
+    return this._eventClient.addListener(eventType, info, cb);
+  }
+
+  async removeEventListener(key: string): Promise<void> {
+    await this._eventClient.removeListener(key);
+  }
+
+  async emitToServer<T extends ServiceEventListener<unknown, unknown>>(
+    eventType: Type<T>,
+    infoSelector: (item: T["$info"]) => boolean,
+    data: T["$data"],
+  ): Promise<void> {
+    await this._eventClient.emitToServer(eventType, infoSelector, data);
+  }
+
+  async uploadFile(files: File[] | FileList | { name: string; data: BlobPart }[]) {
+    if (this._authToken == null) {
+      throw new Error("인증 토큰이 없습니다. 파일 업로드를 위해서는 먼저 auth()를 호출하여 인증해야 합니다.");
+    }
+    return this._fileClient.upload(files, this._authToken);
+  }
+
+  async downloadFileBuffer(relPath: string) {
+    return this._fileClient.download(relPath);
+  }
+}
+
+// T의 모든 메소드 반환형을 Promise로 감싸주는 타입 변환기
+export type RemoteService<T> = {
+  [K in keyof T]: T[K] extends (...args: infer P) => infer R ? (...args: P) => Promise<Awaited<R>> : never; // 함수가 아닌 프로퍼티는 안씀
+};

package/src/transport/service-transport.ts

@@ -0,0 +1,155 @@
+import type { Bytes } from "@simplysm/core-common";
+import { EventEmitter, Uuid } from "@simplysm/core-common";
+import type { ServiceErrorMessage, ServiceResponseMessage, ServiceClientMessage } from "@simplysm/service-common";
+import { ClientProtocolWrapper } from "../protocol/client-protocol-wrapper";
+import type { ServiceProgress } from "../types/progress.types";
+import type { SocketProvider } from "./socket-provider";
+
+interface ServiceTransportEvents {
+  reload: Set<string>;
+  event: { keys: string[]; data: unknown };
+}
+
+export class ServiceTransport extends EventEmitter<ServiceTransportEvents> {
+  private readonly _protocol = new ClientProtocolWrapper();
+
+  private readonly _pendingRequests = new Map<
+    string,
+    {
+      resolve: (msg: ServiceResponseMessage) => void;
+      reject: (err: Error) => void;
+      progress?: ServiceProgress;
+    }
+  >();
+
+  // 응답 progress의 totalSize 저장 (complete 시 100% emit용)
+  private readonly _responseProgressTotalSize = new Map<string, number>();
+
+  constructor(private readonly _socket: SocketProvider) {
+    super();
+
+    this._socket.on("message", this._onMessage.bind(this));
+
+    // 소켓이 끊기면 대기 중인 모든 요청을 에러 처리하여 메모리 해제
+    this._socket.on("state", (state) => {
+      if (state === "closed" || state === "reconnecting") {
+        this._cancelAllRequests("Socket connection lost");
+      }
+    });
+  }
+
+  async send(message: ServiceClientMessage, progress?: ServiceProgress): Promise<unknown> {
+    const uuid = Uuid.new().toString();
+
+    // 응답 대기 시작 (요청 보내기 전에 리스너를 먼저 등록해야 안전함)
+    const responsePromise = new Promise((resolve, reject) => {
+      this._pendingRequests.set(uuid, { resolve, reject, progress });
+    });
+
+    // 요청 전송
+    try {
+      const { chunks, totalSize } = await this._protocol.encode(uuid, message);
+
+      // 진행률 초기화
+      if (chunks.length > 1) {
+        progress?.request?.({
+          uuid,
+          totalSize,
+          completedSize: 0,
+        });
+      }
+
+      // 전송
+      for (const chunk of chunks) {
+        await this._socket.send(chunk);
+      }
+    } catch (err) {
+      // 전송 실패 시 즉시 정리
+      this._pendingRequests.get(uuid)?.reject(err as Error);
+      this._pendingRequests.delete(uuid);
+      throw err;
+    }
+
+    // 응답 결과 반환
+    return responsePromise;
+  }
+
+  private async _onMessage(buf: Bytes): Promise<void> {
+    const decoded = await this._protocol.decode(buf);
+
+    const listenerInfo = this._pendingRequests.get(decoded.uuid);
+
+    try {
+      if (decoded.type === "progress") {
+        // totalSize 기억 (complete 시 100% emit용)
+        this._responseProgressTotalSize.set(decoded.uuid, decoded.totalSize);
+
+        listenerInfo?.progress?.response?.({
+          uuid: decoded.uuid,
+          totalSize: decoded.totalSize,
+          completedSize: decoded.completedSize,
+        });
+      } else {
+        if (decoded.message.name === "progress") {
+          const body = decoded.message.body as { totalSize: number; completedSize: number };
+          listenerInfo?.progress?.request?.({
+            uuid: decoded.uuid,
+            totalSize: body.totalSize,
+            completedSize: body.completedSize,
+          });
+        } else if (decoded.message.name === "response") {
+          // split된 메시지였으면 100% progress emit
+          const totalSize = this._responseProgressTotalSize.get(decoded.uuid);
+          if (totalSize != null) {
+            this._responseProgressTotalSize.delete(decoded.uuid);
+            listenerInfo?.progress?.response?.({
+              uuid: decoded.uuid,
+              totalSize,
+              completedSize: totalSize,
+            });
+          }
+
+          // 응답을 받았으므로 Map에서 제거
+          this._pendingRequests.delete(decoded.uuid);
+
+          listenerInfo?.resolve(decoded.message.body as ServiceResponseMessage);
+        } else if (decoded.message.name === "error") {
+          // progress totalSize 정리
+          this._responseProgressTotalSize.delete(decoded.uuid);
+
+          // 에러를 받았으므로 Map에서 제거
+          this._pendingRequests.delete(decoded.uuid);
+
+          listenerInfo?.reject(this._toError(decoded.message.body));
+        } else if (decoded.message.name === "reload") {
+          const body = decoded.message.body as { clientName: string; changedFileSet: Set<string> };
+          if (this._socket.clientName === body.clientName) {
+            this.emit("reload", body.changedFileSet);
+          }
+        } else if (decoded.message.name === "evt:on") {
+          const body = decoded.message.body as { keys: string[]; data: unknown };
+          this.emit("event", { keys: body.keys, data: body.data });
+        } else {
+          throw new Error("요청이 잘 못 되었습니다.");
+        }
+      }
+    } catch (err) {
+      listenerInfo?.reject(err instanceof Error ? err : new Error(String(err)));
+    }
+  }
+
+  // 모든 대기 요청 취소 처리
+  private _cancelAllRequests(reason: string): void {
+    for (const listenerInfo of this._pendingRequests.values()) {
+      listenerInfo.reject(new Error(`Request canceled: ${reason}`));
+    }
+    this._pendingRequests.clear();
+    this._responseProgressTotalSize.clear();
+  }
+
+  private _toError(body: ServiceErrorMessage["body"]): Error {
+    let err = new Error(body.message);
+    err = Object.assign(err, body);
+    return err;
+  }
+}