connectbase-client 5.6.4 → 5.8.0

package/CHANGELOG.md

@@ -3,14 +3,66 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
-## [5.6.4] - 2026-08-01
+## [5.8.0] - 2026-08-02
 
-### Fixed —  이  을 놓치던 문제
+### Fixed — `sync_lost` 재동기화: 설계만 있고 한 번도 돌지 않던 복구 경로
 
-5.6.3 의 집계가 결과 메타를 "종료 청크" 에서만 집었는데, 실제 와이어에서는 한 청크에 모여
-오지 않는다 —  은 마지막 토큰 다음 청크에, // 은 그
-다음  청크에 실린다(프로덕션 SSE 5,827개 이벤트 실측). 이제 실린 청크마다 그때그때
-누적한다. 회귀 테스트도 실제 와이어 순서를 그대로 옮겼다.
+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 를 디버깅할 수 있다
+
+서버는 훅 에러에 진단 정보를 실어 보내고 있었지만(훅 이름 + setup/hook 실측 + Lua
+traceback 의 파일:줄), **SDK 에는 그걸 읽는 메서드가 없었다.** 업로드/활성화는 되는데
+실패 원인을 볼 수 없어, 서버 Lua 작성 루프가 SDK 쪽에서만 닫히지 않는 상태였다.
+
+```ts
+const { entries } = await cb.game.getScriptLogs(appId, "main", { limit: 50 });
+// [onTick] onTick error: <string>:12: attempt to index a nil value (setup 3ms / hook 5ms)
+```
+
+- `getScriptLogs(appId, name, { since?, limit? })` — 훅 에러 + Lua `log()` 출력.
+  `since` 에 직전 응답의 최신 `ts` 를 넣으면 증분 폴링이 된다. 버퍼는 스크립트당 최근
+  ~500 엔트리이며 서버 파드 로컬이라 재시작 시 소실된다.
+- `getScriptMetrics(appId, name)` — 호출 수/에러율과 **setup vs hook 분리 레이턴시**.
+  `max_hook_latency_ms` 가 frame 훅 예산(기본 100ms)에 근접하면 무거운 작업을
+  `onInit`(5s 예산)으로 옮기라는 신호다. 반대로 `max_setup_latency_ms` 가 크면 룸
+  state 가 큰 것이라 사용자 코드를 고쳐도 낫지 않는다.
+- 타입 `ScriptLogEntry` / `ScriptLogsResponse` / `ScriptMetricsResponse` 신설.
+
+기존 API 변경 없음(추가만).
 
 ## [5.6.4] - 2026-08-01