connectbase-client 5.7.0 → 5.8.0

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [5.8.0] - 2026-08-02
+
+### Fixed — `sync_lost` 재동기화: 설계만 있고 한 번도 돌지 않던 복구 경로
+
+game-server 는 클라이언트 송신 버퍼가 넘쳐 delta 를 버리면 `sync_lost` 를 보내고,
+규약상 클라이언트가 `get_state` 로 전체 상태를 다시 받아 기준점을 맞추게 돼 있다.
+그런데 **이 메시지를 처리하는 분기가 SDK 에 없었다** — 타입에는 선언돼 있어서 더
+그럴듯했지만, `GameRoom` 의 switch 에는 없어 `onMessage`(커스텀 메시지) 로 흘렀다.
+
+delta 는 직전 상태에 누적 적용되므로 하나만 놓쳐도 이후 상태가 계속 어긋난다. 즉
+문서화된 desync 복구가 실제로는 한 번도 동작한 적이 없었다.
+
+```ts
+// 별도 설정 없이 동작한다. 복구된 상태는 평소처럼 onStateUpdate 로 온다.
+room.on("onSyncLost", ({ tick, hint }) => setResyncing(true)); // 선택 — 로딩 표시용
+```
+
+- `sync_lost` 수신 시 자동으로 전체 상태를 재요청한다. 서버는 버퍼가 계속 막혀 있으면
+  tick 마다(60Hz) 재시도하므로, in-flight 가드 + 최소 1초 간격으로 억제했다 — 안 그러면
+  이미 혼잡한 연결에 전체 상태 전송이 겹쳐 혼잡을 키운다.
+- `onSyncLost` 핸들러와 `SyncLostMessage` 타입 신설. **복구는 SDK 가 하므로 게임 쪽에서
+  할 일은 없다** — 이 콜백은 로딩 표시나 계측용이다.
+- `room_stale` 도 `GameRoom` 에서 발화한다. `onRoomStale` 핸들러와 `RoomStaleMessage`
+  타입이 이미 있었는데 다른 transport 모듈에만 배선돼 있어 실제 클라이언트에서는 죽어
+  있었다. 두 타입 모두 패키지 루트에서 export 한다.
+
+### Fixed — 연결 URL 이 조용히 깨지던 두 경로
+
+- `appId` 누락 시 `/v1/game//ws`(빈 path 세그먼트)를 만들던 문제. `GameRoom` 에는 이미
+  가드가 있었는데 transport 모듈만 `|| ""` 로 넘기고 있었고, 프로덕션 로그에 실제로
+  `GET /v1/game//ws?client_id=undefined` 가 찍혔다. 이제 명확한 에러로 즉시 실패한다.
+- `clientId` 누락 시 서버에 `client_id=undefined` 라는 그럴듯한 가짜 ID 가 가던 문제.
+  `URLSearchParams.set` 이 undefined 를 문자열 `"undefined"` 로 넣기 때문으로, 타입이
+  `string` 이라 컴파일은 통과하지만 JS 소비자에서는 실제로 비어서 들어온다.
+
+기존 API 변경 없음(추가만).
+
 ## [5.7.0] - 2026-08-01
 
 ### Added — `getScriptLogs` / `getScriptMetrics`: 서버 Lua 를 디버깅할 수 있다