connectbase-client 5.6.4 → 5.8.0

package/dist/index.mjs

@@ -3693,6 +3693,7 @@ function parseGameError(msg) {
     available: get("available") || msg.available
   });
 }
+var SYNC_LOST_RESYNC_MIN_INTERVAL_MS = 1e3;
 var getDefaultGameServerUrl = () => {
   if (typeof window !== "undefined") {
     const hostname = window.location.hostname;
@@ -3727,6 +3728,9 @@ var GameRoom = class {
     this._scriptVersion = null;
     this._isConnected = false;
     this.msgIdCounter = 0;
+    /** sync_lost 자동 재동기화 억제 상태 — handleSyncLost 참고. */
+    this.resyncInFlight = false;
+    this.lastResyncAt = 0;
     this.config = {
       gameServerUrl: getDefaultGameServerUrl(),
       autoReconnect: true,
@@ -4037,6 +4041,11 @@ var GameRoom = class {
     const baseUrl = this.config.gameServerUrl;
     const wsUrl = baseUrl.replace(/^http/, "ws");
     const params = new URLSearchParams();
+    if (!this.config.clientId) {
+      throw new Error(
+        "cb.game: clientId is required to build a game connection URL. Pass it via `cb.game.createClient({ appId, clientId })`."
+      );
+    }
     params.set("client_id", this.config.clientId);
     if (roomId) {
       params.set("room_id", roomId);
@@ -4127,6 +4136,25 @@ var GameRoom = class {
         case "error":
           this.handlers.onError?.(parseGameError(msg));
           break;
+        case "sync_lost":
+          this.handleSyncLost(msg);
+          break;
+        case "room_stale":
+          if (this.handlers.onRoomStale) {
+            this.handlers.onRoomStale({
+              reason: msg.reason || "unknown",
+              roomId: msg.room_id || "",
+              scriptId: msg.script_id,
+              scriptVersion: msg.script_version,
+              serverTime: msg.server_time || 0
+            });
+          } else {
+            console.warn(
+              "[connect-base game] room_stale received but onRoomStale handler not set:",
+              msg.reason
+            );
+          }
+          break;
         default:
           this.handlers.onMessage?.(
             msg
@@ -4137,6 +4165,34 @@ var GameRoom = class {
       console.error("Failed to parse game message:", data);
     }
   }
+  /**
+   * `sync_lost` 처리 — broadcaster 가 이 클라이언트로 보내는 버퍼가 넘쳐서 delta 를
+   * 몇 개 버렸다는 서버의 통지다. delta 는 이전 상태에 누적 적용되므로, 하나라도
+   * 놓치면 이후 모든 상태가 어긋난 채로 계속 간다. 그래서 전체 상태를 다시 받아
+   * 기준점을 맞춘다 (서버 규약: `app/game/room.go` 의 emitSyncLostHintIfNeeded).
+   *
+   * 서버는 버퍼가 계속 막혀 있으면 tick 마다 재시도하므로 두 겹으로 억제한다 —
+   * 이미 재동기화가 진행 중이면 건너뛰고, 최소 간격 안의 중복 통지도 무시한다.
+   * 안 그러면 혼잡한 상황에서 get_state 폭풍이 혼잡을 더 키운다.
+   */
+  handleSyncLost(msg) {
+    this.handlers.onSyncLost?.({
+      roomId: msg.room_id || "",
+      tick: msg.tick || 0,
+      hint: msg.hint || "",
+      serverTime: msg.server_time || 0
+    });
+    if (this.resyncInFlight) return;
+    const now = Date.now();
+    if (now - this.lastResyncAt < SYNC_LOST_RESYNC_MIN_INTERVAL_MS) return;
+    this.resyncInFlight = true;
+    this.lastResyncAt = now;
+    this.requestState().catch((err) => {
+      console.warn("[connect-base game] sync_lost resync failed:", err);
+    }).finally(() => {
+      this.resyncInFlight = false;
+    });
+  }
   handleDelta(msg) {
     const raw = msg.delta;
     if (!raw) return;
@@ -4774,6 +4830,54 @@ var GameAPI = class {
       "GAME_DELETE_SCRIPT_FAILED"
     );
   }
+  /**
+   * 스크립트 로그 조회 — 훅 에러 + Lua `log()` 출력.
+   *
+   * **서버 Lua 를 디버깅하는 유일한 경로다.** 업로드 → 활성화 후 게임을 돌려보고
+   * 이 메서드로 실패 원인을 확인한다. 에러 줄에는 훅 이름, setup/hook 실측 시간,
+   * Lua traceback 의 파일:줄이 함께 실린다:
+   *
+   * ```
+   * [onTick] onTick error: <string>:12: attempt to index a nil value
+   * (setup 3ms / hook 5ms)
+   * ```
+   *
+   * 예산 초과(`SCRIPT_TIMEOUT`)면 한도와 조치 방향까지 덧붙는다.
+   *
+   * @param since epoch ms. 직전 호출의 최신 timestamp 를 넣어 증분 폴링한다.
+   * @param limit 1~1000 (기본 100)
+   *
+   * 버퍼는 스크립트당 최근 ~500 엔트리이며 파드 로컬이라 재시작 시 소실된다.
+   */
+  async getScriptLogs(appId, name, options = {}) {
+    const params = new URLSearchParams();
+    if (typeof options.since === "number")
+      params.set("since", String(options.since));
+    if (typeof options.limit === "number")
+      params.set("limit", String(options.limit));
+    const qs = params.toString();
+    return this.gameFetch(
+      "GET",
+      `/v1/game/${appId}/scripts/${name}/logs${qs ? `?${qs}` : ""}`,
+      void 0,
+      "GAME_GET_SCRIPT_LOGS_FAILED"
+    );
+  }
+  /**
+   * 스크립트 메트릭 조회 — 호출 수, 에러율, setup/hook 레이턴시.
+   *
+   * `SCRIPT_TIMEOUT` 진단에 쓴다. `maxHookLatencyMs` 가 frame 훅 예산(기본 100ms)에
+   * 근접하면 무거운 작업을 `onInit`(5s 예산)으로 옮겨야 한다는 신호다.
+   * `entity.*` 같은 primitive 는 블로킹 I/O 라 호출한 훅의 예산을 소모한다.
+   */
+  async getScriptMetrics(appId, name) {
+    return this.gameFetch(
+      "GET",
+      `/v1/game/${appId}/scripts/${name}/metrics`,
+      void 0,
+      "GAME_GET_SCRIPT_METRICS_FAILED"
+    );
+  }
 };
 
 // src/api/knowledge.ts
@@ -11938,6 +12042,14 @@ var HttpClient = class {
 };
 
 // src/api/game-transport.ts
+function requireClientId(clientId) {
+  if (!clientId) {
+    throw new Error(
+      "cb.game: clientId is required to build a game connection URL. Pass it via `cb.game.createClient({ appId, clientId })`."
+    );
+  }
+  return clientId;
+}
 var WebTransportTransport = class {
   constructor(config, onMessage, onClose, onError) {
     this.type = "webtransport";
@@ -11968,7 +12080,7 @@ var WebTransportTransport = class {
     const baseUrl = this.config.gameServerUrl || "https://game.connectbase.world";
     const httpsUrl = baseUrl.replace(/^ws/, "http").replace(/^http:/, "https:");
     const params = new URLSearchParams();
-    params.set("client_id", this.config.clientId);
+    params.set("client_id", requireClientId(this.config.clientId));
     if (this.config.publicKey) {
       params.set("public_key", this.config.publicKey);
     }
@@ -12093,15 +12205,19 @@ var WebSocketTransport = class {
     const baseUrl = this.config.gameServerUrl || "wss://game.connectbase.world";
     const wsUrl = baseUrl.replace(/^http/, "ws");
     const params = new URLSearchParams();
-    params.set("client_id", this.config.clientId);
+    params.set("client_id", requireClientId(this.config.clientId));
     if (this.config.publicKey) {
       params.set("public_key", this.config.publicKey);
     }
     if (this.config.accessToken) {
       params.set("token", this.config.accessToken);
     }
-    const appId = this.config.appId || "";
-    return `${wsUrl}/v1/game/${appId}/ws?${params.toString()}`;
+    if (!this.config.appId) {
+      throw new Error(
+        "cb.game: appId is required to build a game connection URL. Pass it to `new ConnectBase({ appId })` or per-client via `cb.game.createClient({ appId, clientId })`."
+      );
+    }
+    return `${wsUrl}/v1/game/${this.config.appId}/ws?${params.toString()}`;
   }
   disconnect() {
     if (this.ws) {

package/package.json

@@ -1,77 +1,77 @@
 {
-	"name": "connectbase-client",
-	"version": "5.6.4",
-	"description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
-	"repository": {
-		"type": "git",
-		"url": "git+https://github.com/connectbase-world/connectbase.git",
-		"directory": "frontend/package/public/connect-base-client"
-	},
-	"homepage": "https://github.com/connectbase-world/connectbase/tree/release/frontend/package/public/connect-base-client#readme",
-	"bugs": {
-		"url": "https://github.com/connectbase-world/connectbase/issues"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"sideEffects": false,
-	"main": "dist/index.js",
-	"module": "dist/index.mjs",
-	"types": "dist/index.d.ts",
-	"browser": "dist/connect-base.umd.js",
-	"unpkg": "dist/connect-base.umd.js",
-	"bin": {
-		"connectbase": "dist/cli.js",
-		"connectbase-client": "dist/cli.js"
-	},
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.mjs",
-			"require": "./dist/index.js"
-		}
-	},
-	"files": [
-		"dist",
-		"LICENSE",
-		"CHANGELOG.md",
-		"README.md",
-		"MIGRATION-v2.md"
-	],
-	"scripts": {
-		"build": "tsup",
-		"dev": "tsup --watch",
-		"typecheck": "tsc --noEmit",
-		"test": "vitest run",
-		"test:types": "tsc --noEmit -p test/tsconfig.json",
-		"release": "pnpm build && npm publish --access public",
-		"lint": "biome lint .",
-		"format": "biome format --write .",
-		"check": "biome check ."
-	},
-	"keywords": [
-		"connect-base",
-		"baas",
-		"backend-as-a-service",
-		"database",
-		"storage",
-		"sdk",
-		"cli",
-		"deploy",
-		"ai",
-		"streaming",
-		"realtime",
-		"tunnel"
-	],
-	"author": "Connect Base",
-	"license": "MIT",
-	"devDependencies": {
-		"@types/node": "^22.15.18",
-		"tsup": "^8.5.1",
-		"typescript": "^5.9.3",
-		"vitest": "^3.2.4"
-	},
-	"engines": {
-		"node": ">=16"
-	}
+  "name": "connectbase-client",
+  "version": "5.8.0",
+  "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/connectbase-world/connectbase.git",
+    "directory": "frontend/package/public/connect-base-client"
+  },
+  "homepage": "https://github.com/connectbase-world/connectbase/tree/release/frontend/package/public/connect-base-client#readme",
+  "bugs": {
+    "url": "https://github.com/connectbase-world/connectbase/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "browser": "dist/connect-base.umd.js",
+  "unpkg": "dist/connect-base.umd.js",
+  "bin": {
+    "connectbase": "dist/cli.js",
+    "connectbase-client": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "CHANGELOG.md",
+    "README.md",
+    "MIGRATION-v2.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:types": "tsc --noEmit -p test/tsconfig.json",
+    "release": "pnpm build && npm publish --access public",
+    "lint": "biome lint .",
+    "format": "biome format --write .",
+    "check": "biome check ."
+  },
+  "keywords": [
+    "connect-base",
+    "baas",
+    "backend-as-a-service",
+    "database",
+    "storage",
+    "sdk",
+    "cli",
+    "deploy",
+    "ai",
+    "streaming",
+    "realtime",
+    "tunnel"
+  ],
+  "author": "Connect Base",
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.15.18",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=16"
+  }
 }