connectbase-client 6.4.0 → 6.5.0

package/dist/index.mjs

@@ -232,6 +232,30 @@ var GameError = class extends Error {
     };
   }
 };
+var RealtimeConnectionError = class extends Error {
+  constructor(init) {
+    super(init.message || init.code || "Realtime connection rejected");
+    this.name = "RealtimeConnectionError";
+    this.code = init.code || "unknown";
+    this.closeCode = init.closeCode;
+    this.retryable = init.retryable ?? isRetryableRealtimeRejection(this.code);
+    this.details = init.details;
+  }
+  /** `JSON.stringify(err)` 가 `{}` 가 되지 않도록 한다 (ApiError.toJSON 참조). */
+  toJSON() {
+    return {
+      name: this.name,
+      code: this.code,
+      message: this.message,
+      closeCode: this.closeCode,
+      retryable: this.retryable,
+      details: this.details
+    };
+  }
+};
+function isRetryableRealtimeRejection(code) {
+  return code === "connection_limit_exceeded" || code === "server_at_capacity" || code === "auth_unavailable" || code === "internal_error";
+}
 
 // src/api/ai.ts
 function aiErrorToApiError(err) {
@@ -7874,6 +7898,18 @@ var QueueAPI = class {
 
 // src/api/realtime.ts
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function toConnectionRejection(msg) {
+  if (msg.event !== "error" || msg.request_id) return null;
+  const data = msg.data;
+  if (!data || typeof data.close_code !== "number") return null;
+  return new RealtimeConnectionError({
+    code: data.code,
+    message: data.message || msg.error,
+    closeCode: data.close_code,
+    retryable: data.retryable,
+    details: data.details
+  });
+}
 var RealtimeAPI = class {
   constructor(http, socketUrl) {
     this.ws = null;
@@ -7901,6 +7937,16 @@ var RealtimeAPI = class {
       fallback: "sse"
     };
     this.retryCount = 0;
+    /**
+     * 재연결 뒤 복구할 구독 상태. 연결이 끊긴 첫 순간에 떠 두고, 재연결이 성공해 복구한 뒤 비운다.
+     *
+     * 재연결 시도가 실패할 때마다 onclose → handleDisconnect 가 다시 불린다. 예전에는 그때마다 구독 맵을
+     * 새로 떴는데, 첫 끊김에서 이미 비워진 맵이라 빈 스냅샷으로 덮였다 — 첫 재연결 시도가 실패하면
+     * (서버 롤링 재시작 등) 재연결에 성공해도 구독이 하나도 복구되지 않았다.
+     */
+    this.pendingRestore = null;
+    /** 첫 연결 전에 direct 원본 힌트를 한 번 물었는지 (primeDirectRealtime). */
+    this.directRealtimePrimed = false;
     this.pendingRequests = /* @__PURE__ */ new Map();
     this.subscriptions = /* @__PURE__ */ new Map();
     this.streamSessions = /* @__PURE__ */ new Map();
@@ -7944,7 +7990,7 @@ var RealtimeAPI = class {
     if (this.state === "connected") {
       return;
     }
-    if (this.state === "connecting" && this.connectPromise) {
+    if (this.connectPromise) {
       return this.connectPromise;
     }
     this.options = { ...this.options, ...options };
@@ -7956,10 +8002,15 @@ var RealtimeAPI = class {
         `Invalid userId: "${this.userId}" looks like a UUID, which is reserved for authenticated members. Pass that member's accessToken (JWT) instead of userId+publicKey, or use a non-UUID identifier for anonymous/guest connections.`
       );
     }
-    this.connectPromise = this.doConnect();
+    this.connectPromise = this.primeDirectRealtime().then(
+      () => this.doConnect()
+    );
     try {
       await this.connectPromise;
     } catch (e) {
+      if (e instanceof RealtimeConnectionError) {
+        throw e;
+      }
       const hasAuth = !!(this.options.accessToken || this.http.getPublicKey());
       if (this.options.fallback !== "none" && hasAuth) {
         this.activateSseFallback(e);
@@ -7988,6 +8039,7 @@ var RealtimeAPI = class {
     this.activeTransport = "sse";
     this.state = "connected";
     this.retryCount = 0;
+    this.pendingRestore = null;
     this.log(
       `WS unavailable (${causeMsg}); using SSE fallback transport for AI streaming`
     );
@@ -8044,6 +8096,7 @@ var RealtimeAPI = class {
     this._appId = null;
     this.retryCount = 0;
     this.connectPromise = null;
+    this.pendingRestore = null;
   }
   /**
    * 카테고리 구독
@@ -8826,6 +8879,30 @@ var RealtimeAPI = class {
     };
   }
   // Private methods
+  /**
+   * direct(저지연) 원본을 아직 모르면 첫 연결 전에 한 번 묻는다 — `GET /v1/public/edge-hints`.
+   *
+   * direct 원본은 core-server 응답 헤더(`X-CB-Realtime-Direct-Base`)로만 배운다. realtime 만 쓰는
+   * 페이지는 WS 를 열기 전에 REST 를 부르지 않아 배울 기회가 없었고, 첫 연결이 늘 Cloudflare 를 타
+   * 한국 사용자는 미국(LAX)을 거친 ~270ms 로 붙었다(platform-issue 01a15d9d 의 273ms). 응답 헤더는
+   * HttpClient 가 평소처럼 학습한다. 광고 대상이 아니면(해외, 킬 스위치) 빈 응답이라 원래 소켓
+   * URL 로 간다. 실패하거나 느리면(1.5초) 그냥 넘어간다 — 최적화일 뿐 연결의 전제가 아니다.
+   * 세션당 한 번만 묻는다.
+   */
+  async primeDirectRealtime() {
+    if (this.directRealtimePrimed) return;
+    this.directRealtimePrimed = true;
+    if (this.http.getDirectRealtimeBaseUrl() || !this.http.getPublicKey()) {
+      return;
+    }
+    try {
+      await this.http.get("/v1/public/edge-hints", { timeout: 1500 });
+    } catch (e) {
+      this.log(
+        `edge hint lookup failed, using default socket URL: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
+  }
   async doConnect() {
     return new Promise((resolve, reject) => {
       this.state = "connecting";
@@ -8854,7 +8931,9 @@ var RealtimeAPI = class {
       if (this.userId) {
         url += `&user_id=${encodeURIComponent(this.userId)}`;
       }
+      url += "&reject_mode=close";
       let settled = false;
+      let rejection = null;
       const timeoutId = setTimeout(() => {
         if (!settled) {
           settled = true;
@@ -8882,6 +8961,11 @@ var RealtimeAPI = class {
           for (const line of messages) {
             try {
               const msg = JSON.parse(line);
+              const rejected = toConnectionRejection(msg);
+              if (rejected && !settled) {
+                rejection = rejected;
+                continue;
+              }
               this.handleServerMessage(msg, () => {
                 if (!settled) {
                   settled = true;
@@ -8899,6 +8983,30 @@ var RealtimeAPI = class {
           this.log(
             `WebSocket closed: code=${event.code}, reason=${event.reason}`
           );
+          if (event.code >= 4e3 && event.code <= 4999) {
+            const err = rejection ?? new RealtimeConnectionError({
+              code: event.reason || void 0,
+              closeCode: event.code
+            });
+            const wasConnected = this.state === "connected";
+            if (!settled) {
+              settled = true;
+              clearTimeout(timeoutId);
+            }
+            this.ws = null;
+            if (wasConnected) {
+              if (err.retryable) {
+                this.handleDisconnect();
+              } else {
+                this.failRealtime(err);
+              }
+              return;
+            }
+            this.state = "disconnected";
+            this.notifyStateChange();
+            reject(err);
+            return;
+          }
           if (!settled && this.state === "connecting") {
             settled = true;
             clearTimeout(timeoutId);
@@ -9145,20 +9253,23 @@ var RealtimeAPI = class {
       }
     });
     this.streamSessions.clear();
-    const previousSubscriptions = /* @__PURE__ */ new Map();
-    for (const [category, sub] of this.subscriptions) {
-      previousSubscriptions.set(category, [...sub.handlers]);
+    if (!this.pendingRestore) {
+      const subscriptions = /* @__PURE__ */ new Map();
+      for (const [category, sub] of this.subscriptions) {
+        subscriptions.set(category, [...sub.handlers]);
+      }
+      const presence = /* @__PURE__ */ new Map();
+      for (const [userId, handlers] of this.presenceSubscriptions) {
+        presence.set(userId, [...handlers]);
+      }
+      const typing = /* @__PURE__ */ new Map();
+      for (const [roomId, handlers] of this.typingHandlers) {
+        typing.set(roomId, [...handlers]);
+      }
+      this.pendingRestore = { subscriptions, presence, typing };
     }
     this.subscriptions.clear();
-    const previousPresenceSubscriptions = /* @__PURE__ */ new Map();
-    for (const [userId, handlers] of this.presenceSubscriptions) {
-      previousPresenceSubscriptions.set(userId, [...handlers]);
-    }
     this.presenceSubscriptions.clear();
-    const previousTypingHandlers = /* @__PURE__ */ new Map();
-    for (const [roomId, handlers] of this.typingHandlers) {
-      previousTypingHandlers.set(roomId, [...handlers]);
-    }
     this.typingHandlers.clear();
     if (this.retryCount < this.options.maxRetries) {
       this.state = "reconnecting";
@@ -9170,16 +9281,29 @@ var RealtimeAPI = class {
       );
       setTimeout(async () => {
         if (this.sseFallbackActive) return;
+        if (this.state !== "reconnecting") return;
         try {
           await this.doConnect();
           this.log("Reconnected successfully, restoring subscriptions...");
-          await this.restoreSubscriptions(
-            previousSubscriptions,
-            previousPresenceSubscriptions,
-            previousTypingHandlers
-          );
+          const snapshot = this.pendingRestore;
+          this.pendingRestore = null;
+          if (snapshot) {
+            await this.restoreSubscriptions(
+              snapshot.subscriptions,
+              snapshot.presence,
+              snapshot.typing
+            );
+          }
         } catch (e) {
           this.logError("Reconnect failed", e);
+          if (e instanceof RealtimeConnectionError) {
+            if (e.retryable && this.retryCount < this.options.maxRetries) {
+              this.handleDisconnect();
+            } else {
+              this.failRealtime(e);
+            }
+            return;
+          }
           if (this.retryCount >= this.options.maxRetries && this.options.fallback !== "none" && !this.sseFallbackActive) {
             this.activateSseFallback(e);
           }
@@ -9197,6 +9321,18 @@ var RealtimeAPI = class {
       }
     }
   }
+  /**
+   * 재연결을 멈추고 앱에 알린다 — 서버가 재시도해도 소용없는 이유(자격증명, 할당량)로 거부했거나
+   * 재시도할 수 있는 거부가 maxRetries 를 다 썼다.
+   */
+  failRealtime(err) {
+    this.pendingRestore = null;
+    this.ws = null;
+    this._connectionId = null;
+    this.state = "disconnected";
+    this.notifyStateChange();
+    this.notifyError(err);
+  }
   /**
    * 이전 구독 상태를 복구합니다.
    * 재연결 성공 후 호출됩니다.
@@ -14173,6 +14309,7 @@ export {
   GameRoomTransport,
   NativeAPI,
   OrganizationsAPI,
+  RealtimeConnectionError,
   RolesAPI,
   SessionManager,
   VideoProcessingError,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "connectbase-client",
-	"version": "6.4.0",
+	"version": "6.5.0",
 	"description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
 	"repository": {
 		"type": "git",