connectbase-client 5.10.0 → 5.12.0

package/CHANGELOG.md

@@ -3,6 +3,86 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [5.12.0] - 2026-08-05
+
+### Performance — `cb.endpoint.call()` 도 저지연 직결로 (5.11.0 의 누락 보완)
+
+5.11.0 은 `/v1/public/*` 데이터 평면만 옮겼습니다. **정작 지연에 가장 민감한
+`cb.endpoint.call()`(`/v1/proxy/*`)이 빠져 있었습니다** — 사용자 PC 의 모델 서버로
+오디오·이미지를 올리는 그 경로가, 왕복 지연 위에서 TCP slow-start 를 타 가장 크게
+손해를 보고 있었는데도 그대로 Cloudflare LAX 를 타고 있었습니다.
+
+실측 (서울, 187KB 업로드):
+
+| | 5.11.0 이하 | 5.12.0 |
+|---|---|---|
+| `cb.endpoint.call()` 187KB POST 왕복 | 1.24~1.74s | **0.13s** |
+
+음성 인식처럼 오디오를 올려 결과를 받는 흐름이 회당 1초 이상 줄어듭니다.
+5.11.0 과 마찬가지로 **설정할 것도, 코드를 고칠 것도 없습니다.**
+
+- `cb.endpoint.call()` 은 dumb pipe 라 SDK 인증 헤더를 주입하지 않습니다 — 호출자가
+  자기 모델 서버용으로 설정한 `Authorization` 이 그대로 유지됩니다(기존과 동일).
+- `cb.endpoint.url()` 은 **바뀌지 않습니다.** Service Worker·백엔드 워커·로깅으로
+  넘어가는 값이라 세션 중에 바뀌면 안 되고, 받는 쪽이 실패해도 폴백할 방법이 없습니다.
+- WebSocket(`cb.endpoint.connectWS()`)도 바뀌지 않습니다 — 티켓 발급 호스트와 연결
+  호스트를 갈라놓지 않기 위해서입니다.
+
+### Fixed — 프록시 요청에 쿠키가 실릴 수 있던 경로 차단
+
+`/v1/proxy/*` 의 `credentials` 모드를 `'omit'` 으로 명시했습니다. 이 경로의 요청 헤더는
+**사용자 PC 의 모델 서버로 그대로 전달**되므로, 부모 도메인(`.connectbase.world`)의 콘솔
+세션 쿠키가 실리면 남의 서버로 새어 나갑니다. 실제 유출은 없었지만(브라우저 기본
+`same-origin` 이 cross-origin 요청에서 쿠키를 막고 있었습니다) 규칙에 의존하지 않고
+명시적으로 잠갔습니다.
+
+플랫폼 이슈 `019fcc2d` 후속.
+
+## [5.11.0] - 2026-08-05
+
+### Performance — 한국에서 SDK 호출이 585ms → 45ms
+
+Cloudflare 가 `connectbase.world` 를 한국 사용자에게 **LAX(로스앤젤레스)** 엣지로 서빙합니다.
+존이 Free 플랜이라서인데, 서울(ICN) 엣지는 사실상 Enterprise 전용이고 Pro/Business 로 올려도
+열리지 않습니다. 오리진(춘천)도 사용자도 한국인데 **모든 SDK 호출이 태평양을 두 번 건너
+141ms 를 고정으로 물고 있었습니다.** 업로드가 있는 요청은 TCP slow-start 가 그 왕복 지연
+위에 곱해져 훨씬 커집니다.
+
+이 버전부터 SDK 는 서버가 알려주는 저지연 원본(`api-direct.connectbase.world`)으로 데이터
+평면 요청을 자동으로 옮깁니다. **설정할 것도, 코드를 고칠 것도 없습니다.**
+
+실측 (서울, 같은 요청 · 2026-08-05):
+
+| | 기존 (CF LAX) | 5.11.0 (직결) |
+|---|---|---|
+| TCP connect | 137ms | **13ms** |
+| TLS handshake | 283ms | **31ms** |
+| `GET /v1/public/auth-settings` TTFB | 585ms | **45ms** |
+| 187KB POST 왕복 | 1.24–1.74s | **0.13s** |
+
+음성 인식처럼 오디오를 올리는 흐름은 회당 1초 이상 줄어듭니다.
+
+**어떻게 동작하나.** Cloudflare 엣지는 요청이 어느 나라에서 왔는지 이미 알고 있습니다.
+서버가 한국 사용자의 응답에만 `X-CB-Direct-Base` 헤더를 실어 보내고, SDK 가 그걸 보고
+이후 요청을 옮깁니다. 다른 나라 사용자에게는 광고하지 않습니다 — 그들에게는 가까운
+Cloudflare 엣지가 춘천 오리진보다 훨씬 가깝기 때문입니다. 별도 프로브 요청이 없어
+왕복 낭비도 없습니다.
+
+**세션은 그대로입니다.** 로그인·가입·로그아웃·OAuth·회원 탈퇴처럼 세션 쿠키를 주고받는
+요청은 옮기지 않습니다. 멤버 refresh 쿠키가 host-only 라 호스트가 갈리면 세션이 끊기기
+때문입니다. 옮기는 것은 `X-Public-Key` 로만 인증하는 데이터 평면(DB CRUD, 스토리지, AI
+스트리밍, 함수 호출, 내 정보 조회 등)뿐입니다.
+
+**안 되는 환경에서도 안전합니다.** 직결 호스트로 가는 요청이 네트워크 레벨에서 실패하면
+(CSP `connect-src` 를 좁게 잡은 앱, 사내 프록시, DNS 미전파 등) **같은 요청을 즉시 원래
+원본으로 재시도**하고 그 세션에서는 다시 시도하지 않습니다. 호출자가 취소(AbortController)
+하거나 타임아웃 난 요청은 재시도하지 않습니다.
+
+> **CSP 를 쓰신다면** `connect-src` 에 `https://api-direct.connectbase.world` 를 추가하면
+> 첫 실패 왕복 한 번도 없앨 수 있습니다. 추가하지 않아도 동작에는 문제가 없습니다.
+
+플랫폼 이슈 `019fcc2d`.
+
 ## [5.10.0] - 2026-08-05
 
 ### Added — 회원 탈퇴(멤버 삭제)를 SDK 로 열었습니다