sonamu 0.10.11 → 0.10.13

package/src/storage/base-file.ts

@@ -17,46 +17,46 @@ export abstract class BaseFile {
     url?: string;
     signedUrl?: string;
   }) {
-    this._filename = params.filename;
-    this._mimetype = params.mimetype;
-    this._size = params.size;
-    this._url = params.url;
-    this._signedUrl = params.signedUrl;
+    this["_filename"] = params.filename;
+    this["_mimetype"] = params.mimetype;
+    this["_size"] = params.size;
+    this["_url"] = params.url;
+    this["_signedUrl"] = params.signedUrl;
   }
 
   /** 원본 파일명 */
   get filename(): string {
-    return this._filename;
+    return this["_filename"];
   }
 
   /** MIME 타입 */
   get mimetype(): string {
-    return this._mimetype;
+    return this["_mimetype"];
   }
 
   /** 파일 크기 (bytes) */
   get size(): number {
-    return this._size;
+    return this["_size"];
   }
 
   /** 확장자 (점 제외) */
   get extname(): string | false {
-    return mime.extension(this._mimetype);
+    return mime.extension(this["_mimetype"]);
   }
 
   /** 저장된 URL (Unsigned) */
   get url(): string {
-    if (this._url === undefined) {
+    if (this["_url"] === undefined) {
       throw new Error("url이 설정되지 않았습니다.");
     }
-    return this._url;
+    return this["_url"];
   }
 
   /** 저장된 URL (Signed) */
   get signedUrl(): string {
-    if (this._signedUrl === undefined) {
+    if (this["_signedUrl"] === undefined) {
       throw new Error("signedUrl이 설정되지 않았습니다.");
     }
-    return this._signedUrl;
+    return this["_signedUrl"];
   }
 }

package/src/storage/buffered-file.ts

@@ -10,8 +10,8 @@ import { type DriverKey } from "./drivers";
  * 메모리에 로드된 상태로, md5 계산이나 이미지 처리 등 유연한 작업이 가능합니다.
  */
 export class BufferedFile extends BaseFile {
-  private _file: MultipartFile;
-  private _buffer: Buffer;
+  private fileValue: MultipartFile;
+  private bufferValue: Buffer;
 
   constructor(file: MultipartFile, buffer: Buffer) {
     super({
@@ -19,18 +19,18 @@ export class BufferedFile extends BaseFile {
       mimetype: file.mimetype,
       size: buffer.length,
     });
-    this._file = file;
-    this._buffer = buffer;
+    this.fileValue = file;
+    this.bufferValue = buffer;
   }
 
   /** 파일 Buffer */
   get buffer(): Buffer {
-    return this._buffer;
+    return this.bufferValue;
   }
 
   /** MD5 해시 계산 */
   async md5(): Promise<string> {
-    return createHash("md5").update(this._buffer).digest("hex");
+    return createHash("md5").update(this.bufferValue).digest("hex");
   }
 
   /**
@@ -44,19 +44,19 @@ export class BufferedFile extends BaseFile {
     const { Sonamu } = await import("../api/sonamu");
     const disk = Sonamu.storage.use(diskName);
 
-    await disk.put(key, new Uint8Array(this._buffer), {
+    await disk.put(key, new Uint8Array(this.bufferValue), {
       contentType: this.mimetype,
     });
 
-    this._url = await disk.getUrl(key);
-    this._signedUrl = await disk.getSignedUrl(key);
+    this["_url"] = await disk.getUrl(key);
+    this["_signedUrl"] = await disk.getSignedUrl(key);
 
     // signed url은 만료 시간이 있기 때문에, unsigned url을 반환합니다.
-    return this._url;
+    return this["_url"];
   }
 
   /** 원본 MultipartFile 접근 */
   get raw(): MultipartFile {
-    return this._file;
+    return this.fileValue;
   }
 }

package/src/storage/s3-driver.ts

@@ -62,7 +62,10 @@ export class SonamuS3Driver extends S3Driver {
 
     // ACL 지원 시에만 설정
     if (this.sonamuSupportsACL) {
-      uploadParams.ACL = (visibility === "public" ? "public-read" : "private") as ObjectCannedACL;
+      uploadParams.ACL =
+        /* SAFETY: 호출 경계의 선행 검증과 소유 타입 계약이 이 값의 타입을 보장한다. */ (
+          visibility === "public" ? "public-read" : "private"
+        ) as ObjectCannedACL;
     }
 
     const upload = new Upload({

package/src/storage/uploaded-file.ts

@@ -6,8 +6,8 @@ import { type DriverKey } from "./drivers";
  * 이미 저장소에 스트리밍 완료된 상태로, url/key 등 메타데이터만 접근 가능합니다.
  */
 export class UploadedFile extends BaseFile {
-  private _key: string;
-  private _diskName: DriverKey;
+  private keyValue: string;
+  private diskNameValue: DriverKey;
 
   constructor(params: {
     filename: string;
@@ -25,18 +25,18 @@ export class UploadedFile extends BaseFile {
       url: params.url,
       signedUrl: params.signedUrl,
     });
-    this._key = params.key;
-    this._diskName = params.diskName;
+    this.keyValue = params.key;
+    this.diskNameValue = params.diskName;
   }
 
   /** 저장소 내 키 */
   get key(): string {
-    return this._key;
+    return this.keyValue;
   }
 
   /** 저장된 디스크 이름 */
   get diskName(): DriverKey {
-    return this._diskName;
+    return this.diskNameValue;
   }
 
   /**
@@ -45,9 +45,9 @@ export class UploadedFile extends BaseFile {
    */
   async download(): Promise<Buffer> {
     const { Sonamu } = await import("../api/sonamu");
-    const disk = Sonamu.storage.use(this._diskName);
+    const disk = Sonamu.storage.use(this.diskNameValue);
 
-    const uint8Array = await disk.get(this._key);
+    const uint8Array = await disk.get(this.keyValue);
     return Buffer.from(uint8Array);
   }
 }

package/src/stream/__tests__/ws-contracts.test.ts

@@ -13,6 +13,8 @@ import { WebSocketDeliveryEngine } from "../ws-delivery";
 import { WebSocketLocalConnectionStore } from "../ws-local-connection-store";
 import { InMemoryWebSocketPresenceStore } from "../ws-presence-store";
 
+type PublishedData = Parameters<ManagedWebSocketConnection["publishUntyped"]>[1];
+
 async function waitForAsyncQueue(rounds: number = 3): Promise<void> {
   for (let index = 0; index < rounds; index += 1) {
     await new Promise<void>((resolve) => {
@@ -48,7 +50,7 @@ class ContractClusterBus implements WebSocketClusterBus {
 }
 
 class ContractConnection implements ManagedWebSocketConnection {
-  readonly sent: Array<{ event: string; data: unknown }> = [];
+  readonly sent: Array<{ event: string; data: PublishedData }> = [];
   closed = false;
 
   constructor(
@@ -56,7 +58,7 @@ class ContractConnection implements ManagedWebSocketConnection {
     readonly namespace: string,
   ) {}
 
-  publishUntyped(event: string, data: unknown): void {
+  publishUntyped<Data>(event: string, data: Data): void {
     this.sent.push({ event, data });
   }
 

package/src/stream/__tests__/ws-telemetry.test.ts

@@ -562,7 +562,7 @@ describe("metric source", () => {
     };
 
     const unsubscribe = controller.registerMetricSource(source);
-    expect(typeof unsubscribe).toBe("function");
+    expect(unsubscribe).toBeInstanceOf(Function);
 
     const snapshotBefore = controller.getMetricsSnapshot();
     expect(snapshotBefore.activeConnections).toBe(7);

package/src/stream/__tests__/ws.test.ts

@@ -1,10 +1,9 @@
 import { EventEmitter } from "node:events";
 
 import { describe, expect, it, vi } from "vitest";
-import { type WebSocket } from "ws";
 import { z } from "zod";
 
-import { createWebSocketRuntime } from "../ws";
+import { createWebSocketRuntime, type WebSocketTransport } from "../ws";
 import { WebSocketAudience } from "../ws-audience";
 import {
   type WebSocketClusterBus,
@@ -48,8 +47,33 @@ class FakeWebSocket extends EventEmitter {
   }
 }
 
-function asWebSocket(socket: FakeWebSocket): WebSocket {
-  return socket as unknown as WebSocket;
+function asWebSocket(socket: FakeWebSocket): WebSocketTransport {
+  return {
+    get bufferedAmount() {
+      return socket.bufferedAmount;
+    },
+    get readyState() {
+      return socket.readyState;
+    },
+    close(code, reason) {
+      socket.close(code, reason?.toString());
+    },
+    off(...args) {
+      socket.off(...args);
+    },
+    on(...args) {
+      socket.on(...args);
+    },
+    ping() {
+      socket.ping();
+    },
+    send(data) {
+      socket.send(data.toString());
+    },
+    terminate() {
+      socket.terminate();
+    },
+  };
 }
 
 class FakeClusterBus implements WebSocketClusterBus {
@@ -665,8 +689,8 @@ describe("WebSocketRuntime", () => {
       namespace: "chat",
     });
 
-    let unhandled: unknown = null;
-    const handleUnhandledRejection = (reason: unknown) => {
+    let unhandled: Error | null = null;
+    const handleUnhandledRejection = (reason: Error) => {
       unhandled = reason;
     };
     process.once("unhandledRejection", handleUnhandledRejection);

package/src/stream/sse.ts

@@ -29,26 +29,26 @@ export interface SSEConnection<T extends z.ZodObject> {
 }
 
 class SSEConnectionImpl<T extends z.ZodObject> implements SSEConnection<T> {
-  private _closed = false;
-  private _closeCallbacks: Array<() => void> = [];
+  private closedState = false;
+  private closeCallbacks: Array<() => void> = [];
 
   private readonly markClosed = () => {
-    this._closed = true;
+    this.closedState = true;
     this.fireCloseCallbacks();
   };
 
   get closed(): boolean {
-    return this._closed;
+    return this.closedState;
   }
 
   onClose(callback: () => void): void {
-    this._closeCallbacks.push(callback);
+    this.closeCallbacks.push(callback);
   }
 
   // 콜백을 한 번만 실행하고 배열을 비워 중복 호출을 방지
   private fireCloseCallbacks(): void {
-    const callbacks = this._closeCallbacks;
-    this._closeCallbacks = [];
+    const callbacks = this.closeCallbacks;
+    this.closeCallbacks = [];
     for (const cb of callbacks) {
       cb();
     }
@@ -63,22 +63,23 @@ class SSEConnectionImpl<T extends z.ZodObject> implements SSEConnection<T> {
   }
 
   publish<K extends keyof z.infer<T>>(event: K, data: z.infer<T>[K]): void {
-    if (this._closed) {
+    if (this.closedState) {
       return;
     }
 
     this.reply.sse({
-      event: event as string,
+      event:
+        /* SAFETY: 등록된 WebSocket 이벤트 스키마가 이 값의 타입을 보장한다. */ event as string,
       data: JSON.stringify(data),
     });
   }
 
   async end(): Promise<void> {
-    if (this._closed) {
+    if (this.closedState) {
       return;
     }
 
-    this._closed = true;
+    this.closedState = true;
     this.socket.off("close", this.markClosed);
     this.socket.off("error", this.markClosed);
     this.fireCloseCallbacks();

package/src/stream/ws-core.ts

@@ -7,7 +7,7 @@ export interface ManagedWebSocketConnection {
   closed: boolean;
   // setUserId/clearUserId 호출로 갱신됨. telemetry emit 사이트에서 hot path lookup을 피하기 위해 connection에 캐싱한다
   readonly userId?: string;
-  publishUntyped(event: string, data: unknown): void;
+  publishUntyped<Data>(event: string, data: Data): void;
   close(code?: number, reason?: string): void;
 }
 

package/src/stream/ws-delivery.ts

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 
+import { runtimeTypeOf } from "../runtime-type";
 import { type WebSocketAudience } from "./ws-audience";
 import { type WebSocketAudienceResolver } from "./ws-audience-resolver";
 import { type WebSocketClusterBus, type WebSocketClusterEnvelope } from "./ws-cluster-bus";
@@ -43,7 +44,7 @@ export class WebSocketDeliveryEngine {
     });
   }
 
-  publishToAudience(audience: WebSocketAudience, event: string, data: unknown): void {
+  publishToAudience<Data>(audience: WebSocketAudience, event: string, data: Data): void {
     const routingPlan = this.options.audienceResolver.resolve(audience);
     const localTargets = this.options.localConnections.getConnections(routingPlan.localSessionIds);
 
@@ -99,7 +100,7 @@ export class WebSocketDeliveryEngine {
           },
         });
       })
-      .catch((error: unknown) => {
+      .catch((cause: unknown) => {
         const durationMs = performance.now() - publishStartedAt;
         this.telemetry.emit({
           name: "ws.cluster.envelope.failed",
@@ -112,7 +113,7 @@ export class WebSocketDeliveryEngine {
           durationMs,
           status: "error",
           attributes: { event },
-          errorType: error instanceof Error ? error.name : typeof error,
+          errorType: cause instanceof Error ? cause.name : runtimeTypeOf(cause),
         });
       });
   }
@@ -123,7 +124,7 @@ export class WebSocketDeliveryEngine {
     await this.options.clusterBus.shutdown();
   }
 
-  getTelemetrySnapshot(): { pendingFanOutJobs: number; pendingFanOutTargets: number } {
+  getTelemetrySnapshot() {
     let pendingFanOutTargets = 0;
 
     for (const job of this.pendingFanOutJobs) {
@@ -183,7 +184,11 @@ export class WebSocketDeliveryEngine {
     });
   }
 
-  private enqueueFanOut(targets: ManagedWebSocketConnection[], event: string, data: unknown): void {
+  private enqueueFanOut<Data>(
+    targets: ManagedWebSocketConnection[],
+    event: string,
+    data: Data,
+  ): void {
     if (targets.length === 0) {
       return;
     }
@@ -236,7 +241,7 @@ export class WebSocketDeliveryEngine {
       }
     } catch (error) {
       status = "error";
-      errorType = error instanceof Error ? error.name : typeof error;
+      errorType = error instanceof Error ? error.name : runtimeTypeOf(error);
       throw error;
     } finally {
       const durationMs = performance.now() - startedAt;
@@ -260,7 +265,11 @@ export class WebSocketDeliveryEngine {
     }
   }
 
-  private safePublish(connection: ManagedWebSocketConnection, event: string, data: unknown): void {
+  private safePublish<Data>(
+    connection: ManagedWebSocketConnection,
+    event: string,
+    data: Data,
+  ): void {
     try {
       if (!connection.closed) {
         connection.publishUntyped(event, data);

package/src/stream/ws-local-connection-store.ts

@@ -1,3 +1,4 @@
+import { isFunctionValue } from "../utils/runtime-value";
 import { type ManagedWebSocketConnection } from "./ws-core";
 import {
   type WebSocketTelemetryConnectionSnapshot,
@@ -71,7 +72,5 @@ export class WebSocketLocalConnectionStore {
 function isTelemetryInspectableConnection(
   connection: ManagedWebSocketConnection,
 ): connection is ManagedWebSocketConnection & TelemetryInspectableConnection {
-  return (
-    "getTelemetrySnapshot" in connection && typeof connection.getTelemetrySnapshot === "function"
-  );
+  return "getTelemetrySnapshot" in connection && isFunctionValue(connection.getTelemetrySnapshot);
 }

package/src/stream/ws-presence-store.ts

@@ -317,7 +317,12 @@ function getBindingKey(namespace: string, id: string): string {
   return `${namespace}::${id}`;
 }
 
-function parseBindingKey(key: string): { namespace: string; id: string } {
+interface PresenceBinding {
+  namespace: string;
+  id: string;
+}
+
+function parseBindingKey(key: string): PresenceBinding {
   const [namespace, ...rest] = key.split("::");
   return {
     namespace,

package/src/stream/ws-registry.ts

@@ -1,3 +1,4 @@
+import { isFunctionValue } from "../utils/runtime-value";
 import { WebSocketAudience, type WebSocketAudience as WebSocketAudienceSpec } from "./ws-audience";
 import { WebSocketAudienceResolver } from "./ws-audience-resolver";
 import { NoopWebSocketClusterBus, type WebSocketClusterBus } from "./ws-cluster-bus";
@@ -253,19 +254,29 @@ export class WebSocketRegistry {
     });
   }
 
-  broadcast(event: string, data: unknown, namespace?: string): void {
+  broadcast<Data>(event: string, data: Data, namespace?: string): void {
     this.publishToAudience(WebSocketAudience.all(namespace), event, data);
   }
 
-  publishToRoom(roomId: WebSocketRoomId, event: string, data: unknown, namespace?: string): void {
+  publishToRoom<Data>(
+    roomId: WebSocketRoomId,
+    event: string,
+    data: Data,
+    namespace?: string,
+  ): void {
     this.publishToAudience(WebSocketAudience.room(roomId, namespace), event, data);
   }
 
-  publishToUser(userId: WebSocketUserId, event: string, data: unknown, namespace?: string): void {
+  publishToUser<Data>(
+    userId: WebSocketUserId,
+    event: string,
+    data: Data,
+    namespace?: string,
+  ): void {
     this.publishToAudience(WebSocketAudience.user(userId, namespace), event, data);
   }
 
-  publishToAudience(audience: WebSocketAudienceSpec, event: string, data: unknown): void {
+  publishToAudience<Data>(audience: WebSocketAudienceSpec, event: string, data: Data): void {
     this.deliveryEngine.publishToAudience(audience, event, data);
   }
 
@@ -313,7 +324,5 @@ function formatUserId(userId: WebSocketUserId | undefined): string | undefined {
 function isTelemetryContextProvider(
   connection: ManagedWebSocketConnection,
 ): connection is ManagedWebSocketConnection & TelemetryContextProvider {
-  return (
-    "getTelemetryContext" in connection && typeof connection.getTelemetryContext === "function"
-  );
+  return "getTelemetryContext" in connection && isFunctionValue(connection.getTelemetryContext);
 }