connectbase-client 3.39.0 → 3.41.0

package/CHANGELOG.md

@@ -3,6 +3,72 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.41.0] - 2026-07-02
+
+### Added — 웹 배포 파일당 크기 한도 사전 검증 (fail-fast)
+
+`connectbase deploy` 가 파일을 수집한 직후, 서버로 업로드하기 **전에** 각 파일이 웹 스토리지
+파일당 크기 한도를 넘는지 검사한다(플랫폼 이슈 019f221b). 기존에는 전량 수집·업로드를 마친
+뒤에야 서버에서 원시 DB 오류(`Error 8025 (HY000): entry too large`)로 실패해 원인 파악이
+어려웠다.
+
+- 초과 파일이 있으면 **어떤 파일이 얼마나 큰지**(바이너리는 원본→base64 크기까지) 나열하고,
+  파일 스토리지(`cb.storage`) 사용을 안내한 뒤 업로드 없이 즉시 종료한다.
+- 검사 기준: 파일 내용은 DB(TiDB Text 컬럼)에 저장되며 단일 엔트리 한도 6 MiB 를 넘을 수 없다.
+  바이너리는 base64(약 1.33x)로 저장되므로 원본 기준 실질 상한은 약 4.5 MB.
+- 텍스트 파일은 UTF-8 바이트 기준으로 정확히 계산(멀티바이트 문자 포함).
+
+## [3.40.0] - 2026-06-28
+
+### Added — KB 하이브리드(시맨틱) 검색 지원
+
+지식베이스 검색에 BM25 키워드 + 벡터 의미 검색을 RRF(Reciprocal Rank Fusion)로 융합하는
+하이브리드 검색을 추가했다. 콘솔 > **AI** 에서 임베딩을 켠 앱(gemini / openai BYOK)에서
+동작하며, 오타·동의어·의역에 강하다.
+
+- **\`KnowledgeSearchRequest.hybrid?: boolean\`** — \`cb.knowledge.search()\` 에 hybrid 옵션 추가.
+  미설정(기본)이면 임베딩을 켠 앱에서 자동 적용, \`false\` 면 키워드 전용 검색을 강제.
+- **\`AIChatRequest.hybrid?: boolean\`** — \`cb.ai.chat()\` / \`cb.ai.chatStream()\` 의 RAG 검색에도
+  동일 옵션 적용. 미설정이면 임베딩을 켠 앱에서 자동 적용된다.
+- 임베딩 미설정 앱에서는 무시되며 기존 BM25 검색으로 동작한다(하위호환, 회귀 없음).
+
+## [3.39.2] - 2026-06-26
+
+### Performance — 터널 프록시 응답 지연 제거 (TCP_NODELAY / keep-alive)
+
+`connectbase tunnel` 프록시 경유가 직접 호출 대비 **~2.4초 고정 지연**을 추가하던 문제를
+수정했다(플랫폼 이슈 019f01c3 — 실시간 TTS 음성에서 "첫 음성까지 ~3.5초"). 원인은 응답
+본문을 tunnel-server 로 되돌리는 영구 WebSocket 소켓에 Nagle 알고리즘이 켜져 있던 것이다.
+
+- **TCP_NODELAY (핵심)**: tunnel-server 로의 영구 WS 소켓에 `setNoDelay(true)` 적용. 프록시
+  응답 본문은 CLI→tunnel-server 방향으로 CLI 가 송신하는데, 업스트림(사이드카)이 본문을
+  여러 작은 청크로 흘리면 각 WS 프레임 write 가 직전 세그먼트의 ACK 를 기다리며 묶였다.
+  tunnel-server 가 지리적으로 먼 경우(예: 한국↔싱가포르 ~45ms RTT) 이 Nagle×delayed-ACK
+  상호작용이 프레임당 수십 ms 스톨을 만들고, 청크 수에 비례해 고정 수초로 누적됐다.
+- **로컬 keep-alive**: 사이드카(로컬 업스트림) HTTP 호출에 keep-alive Agent 적용 — 요청마다
+  TCP 핸드셰이크를 새로 맺지 않고 소켓을 재사용한다(순차 호출 시 이득).
+- **로컬·업스트림 WS 소켓 NoDelay**: 사이드카 HTTP/WS 소켓에도 `setNoDelay(true)` 적용
+  (인터랙티브 WS — noVNC·실시간 프레임 — 프레임당 지연 감소).
+
+연계: core-server 도 프록시 forward 를 공개 도메인(`tunnel.connectbase.world`, 클러스터
+밖 ingress 헤어핀)이 아니라 tunnel-server 내부 ClusterIP 로 직결하도록 함께 수정됐다.
+
+## [3.39.1] - 2026-06-26
+
+### Fixed — 터널 인증 4xx 를 재시도하지 않고 즉시 원인 표시
+
+`connectbase tunnel` 이 인증 단계에서 받은 **클라이언트 오류(4xx)** 를 일시 장애처럼 10회
+재시도하던 것을 수정했다. 서버가 4xx 로 명확히 거부하면 재시도 없이 즉시 원인을 출력하고 종료한다.
+
+- **403 (앱 접근 거부)**: `app_id` 오설정(공개키 UUID·storageId 입력)이 대부분 — 서버 메시지와
+  함께 "`app_id` 가 콘솔의 앱/프로젝트 ID 인지 확인" 안내를 출력하고 즉시 종료.
+- **그 외 4xx (400/404 등)**: 설정 문제라 재시도해도 동일하게 실패 → 즉시 종료.
+- **5xx · 429 · 네트워크 오류**: 기존대로 지수 백오프 재시도(일시적 장애).
+- 서버 응답 본문의 `{"error":"..."}` 메시지를 파싱해 표시.
+
+연계: tunnel-server 가 core 인증 4xx(403/401)를 503 "auth service unavailable" 로 뭉개던
+서버측 문제도 함께 수정됐다(설정 오류가 서비스 장애로 오진단되던 것 해소).
+
 ## [3.39.0] - 2026-06-25
 
 ### Removed (BREAKING) — 게스트/익명 로그인 제거

package/dist/cli.js

@@ -215,6 +215,7 @@ var BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
   ".zip",
   ".wasm"
 ]);
+var WEB_FILE_MAX_STORED_BYTES = 6 * 1024 * 1024 - 64 * 1024;
 function sha256Hex(value) {
   return crypto.createHash("sha256").update(value, "utf8").digest("hex");
 }
@@ -281,6 +282,29 @@ function collectFiles(dir, baseDir = dir) {
   }
   return files;
 }
+function formatSize(bytes) {
+  if (bytes >= 1024 * 1024) return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+  return `${(bytes / 1024).toFixed(1)} KB`;
+}
+function validateFileSizes(files) {
+  const oversized = files.map((f) => {
+    const storedBytes = Buffer.byteLength(f.content, "utf8");
+    const originalBytes = f.isBinary ? Math.round(f.content.length * 3 / 4) : storedBytes;
+    return { path: f.path, isBinary: f.isBinary, storedBytes, originalBytes };
+  }).filter((f) => f.storedBytes > WEB_FILE_MAX_STORED_BYTES);
+  if (oversized.length === 0) return;
+  error(`\uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0 \uD30C\uC77C\uB2F9 \uD06C\uAE30 \uD55C\uB3C4(\uC57D ${formatSize(WEB_FILE_MAX_STORED_BYTES)})\uB97C \uCD08\uACFC\uD55C \uD30C\uC77C\uC774 \uC788\uC5B4 \uBC30\uD3EC\uD560 \uC218 \uC5C6\uC2B5\uB2C8\uB2E4:`);
+  for (const f of oversized) {
+    const detail = f.isBinary ? `${formatSize(f.originalBytes)} \u2192 base64 ${formatSize(f.storedBytes)}` : formatSize(f.storedBytes);
+    error(`  \u2022 ${f.path} (${detail})`);
+  }
+  log("");
+  warn("\uC815\uC801 \uD638\uC2A4\uD305 \uD30C\uC77C\uC740 DB \uB2E8\uC77C \uC5D4\uD2B8\uB9AC(6 MiB)\uC5D0 \uC800\uC7A5\uB418\uBA70, \uBC14\uC774\uB108\uB9AC\uB294 base64(\uC57D 1.33x)\uB85C");
+  warn("\uBD80\uD480\uC5B4 \uC6D0\uBCF8 \uAE30\uC900 \uC57D 4.5 MB \uAC00 \uC2E4\uC9C8 \uC0C1\uD55C\uC785\uB2C8\uB2E4.");
+  warn(`\uB300\uC6A9\uB7C9 \uC5D0\uC14B(3D \uBAA8\uB378\xB7\uB3D9\uC601\uC0C1\xB7\uD070 \uD3F0\uD2B8 \uB4F1)\uC740 \uD30C\uC77C \uC2A4\uD1A0\uB9AC\uC9C0(${colors.cyan}cb.storage${colors.reset}, presigned URL)\uC5D0`);
+  warn("\uC62C\uB9AC\uACE0 URL \uB85C \uCC38\uC870\uD558\uC138\uC694. \uD30C\uC77C \uC2A4\uD1A0\uB9AC\uC9C0\uB294 \uD30C\uC77C\uB2F9 \uACE0\uC815 \uC0C1\uD55C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4.");
+  process.exit(1);
+}
 var DEFAULT_REQUEST_TIMEOUT_MS = 6e4;
 async function makeRequest(url, method, headers, body, reqOpts = {}) {
   return new Promise((resolve2, reject) => {
@@ -378,6 +402,7 @@ async function deploy(directory, config, isDev = false, deployOpts = {}) {
     error("\uBC30\uD3EC\uD560 \uD30C\uC77C\uC774 \uC5C6\uC2B5\uB2C8\uB2E4");
     process.exit(1);
   }
+  validateFileSizes(files);
   const totalSize = files.reduce((sum, f) => sum + f.content.length, 0);
   const sizeKB = (totalSize / 1024).toFixed(1);
   log(`${colors.green}\u2713${colors.reset} ${files.length}\uAC1C \uD30C\uC77C \uBC1C\uACAC (${sizeKB} KB)`);
@@ -1933,6 +1958,7 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
     req.on("upgrade", (_res, sock, _head) => {
       socket = sock;
       reconnectAttempts = 0;
+      sock.setNoDelay(true);
       const parser = new WsFrameParser({
         onMessage: (data) => {
           try {
@@ -1988,16 +2014,32 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
       let body = "";
       res.on("data", (chunk) => body += chunk.toString());
       res.on("end", () => {
-        if (res.statusCode === 401) {
-          error("\uC778\uC99D \uC2E4\uD328: API Key\uAC00 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4");
+        const status = res.statusCode ?? 0;
+        let serverMsg = body;
+        try {
+          const j = JSON.parse(body);
+          if (j && typeof j.error === "string") serverMsg = j.error;
+        } catch {
+        }
+        if (status === 401) {
+          error("\uC778\uC99D \uC2E4\uD328: Secret Key\uAC00 \uC62C\uBC14\uB974\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4");
           shouldReconnect = false;
           process.exit(1);
-        } else if (res.statusCode === 402) {
+        } else if (status === 402) {
           error("\uD560\uB2F9\uB7C9 \uCD08\uACFC: \uD50C\uB79C\uC744 \uC5C5\uADF8\uB808\uC774\uB4DC\uD558\uC138\uC694");
           shouldReconnect = false;
           process.exit(1);
+        } else if (status === 403) {
+          error(`\uC811\uADFC \uAC70\uBD80: ${serverMsg}`);
+          error("\u2192 app_id \uAC00 \uCF58\uC194\uC758 \uC571/\uD504\uB85C\uC81D\uD2B8 ID \uC778\uC9C0 \uD655\uC778\uD558\uC138\uC694 (\uACF5\uAC1C\uD0A4 UUID \uB098 storageId \uAC00 \uC544\uB2D9\uB2C8\uB2E4).");
+          shouldReconnect = false;
+          process.exit(1);
+        } else if (status >= 400 && status < 500 && status !== 429) {
+          error(`\uD130\uB110 \uC5F0\uACB0 \uAC70\uBD80 (${status}): ${serverMsg}`);
+          shouldReconnect = false;
+          process.exit(1);
         } else {
-          error(`\uD130\uB110 \uC11C\uBC84 \uC751\uB2F5 \uC624\uB958 (${res.statusCode}): ${body}`);
+          error(`\uD130\uB110 \uC11C\uBC84 \uC751\uB2F5 \uC624\uB958 (${status}): ${serverMsg}`);
           if (shouldReconnect) {
             scheduleReconnect();
           }
@@ -2017,6 +2059,7 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
     setTimeout(connect, delay);
   }
   const streams = /* @__PURE__ */ new Map();
+  const localAgent = new http.Agent({ keepAlive: true, maxSockets: 64 });
   function routeStreamData(streamId, payload) {
     const f = streams.get(streamId);
     if (!f) return;
@@ -2050,7 +2093,7 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
     let started = false;
     let cancelled = false;
     const localReq = http.request(
-      { hostname: "127.0.0.1", port: localPort, path: fullPath, method, headers: localHeaders },
+      { hostname: "127.0.0.1", port: localPort, path: fullPath, method, headers: localHeaders, agent: localAgent },
       (res) => {
         const respHeaders = {};
         for (const [k, v] of Object.entries(res.headers)) {
@@ -2082,6 +2125,12 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
         });
       }
     );
+    localReq.on("socket", (s) => {
+      try {
+        s.setNoDelay(true);
+      } catch {
+      }
+    });
     localReq.on("error", (err) => {
       warn(`\uB85C\uCEEC \uC11C\uBC84 \uC5F0\uACB0 \uC2E4\uD328 (${method} ${reqPath}): ${err.message}`);
       if (!started) {
@@ -2140,6 +2189,10 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
     });
     req.on("upgrade", (res, sk) => {
       upstream = sk;
+      try {
+        upstream.setNoDelay(true);
+      } catch {
+      }
       const respHeaders = {};
       for (const [k, v] of Object.entries(res.headers)) {
         if (v == null) continue;

package/dist/index.d.mts

@@ -2402,14 +2402,15 @@ declare class StorageAPI {
      * 파일 목록 조회
      *
      * @param storageId - 파일 스토리지 ID
-     * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+     * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+     *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
      *
      * @example
      * ```ts
-     * // 루트 폴더의 파일 목록
+     * // 스토리지 전체 파일 목록 (flat 트리)
      * const files = await cb.storage.getFiles('storage-id')
      *
-     * // 특정 폴더의 하위 파일 목록
+     * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
      * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
      * ```
      */
@@ -7370,6 +7371,12 @@ interface KnowledgeSearchRequest {
     top_k?: number;
     /** Agentic Search 활성화 — AI 가 쿼리를 자동 생성하여 다중 검색 수행 */
     agentic?: boolean;
+    /**
+     * Hybrid 검색 — BM25 키워드 + 벡터 시맨틱 검색을 RRF 로 융합.
+     * 미설정(기본): 콘솔 > AI 에서 embedding 을 켠 앱은 자동 적용.
+     * `false`: 키워드 전용 검색 강제. embedding 미설정 앱에서는 무시(BM25 only).
+     */
+    hybrid?: boolean;
     /**
      * metadata 기반 필터 (옵셔널). 키 형식 `metadata.<path>` 또는 raw key.
      * 값에 `AUTH_MEMBER_ID_TOKEN` 사용 시 서버가 인증된 AppMember ID 로 치환.
@@ -7655,6 +7662,11 @@ interface AIChatRequest {
     knowledgeBaseId?: string;
     topK?: number;
     agentic?: boolean;
+    /**
+     * KB 검색 hybrid(BM25 + 벡터 시맨틱, RRF 융합) 제어. 미설정(기본)이면 콘솔 > AI 에서
+     * embedding 을 켠 앱은 자동 적용, `false` 면 키워드 전용 검색 강제.
+     */
+    hybrid?: boolean;
     toolGroupId?: string;
     /**
      * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에

package/dist/index.d.ts

@@ -2402,14 +2402,15 @@ declare class StorageAPI {
      * 파일 목록 조회
      *
      * @param storageId - 파일 스토리지 ID
-     * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+     * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+     *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
      *
      * @example
      * ```ts
-     * // 루트 폴더의 파일 목록
+     * // 스토리지 전체 파일 목록 (flat 트리)
      * const files = await cb.storage.getFiles('storage-id')
      *
-     * // 특정 폴더의 하위 파일 목록
+     * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
      * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
      * ```
      */
@@ -7370,6 +7371,12 @@ interface KnowledgeSearchRequest {
     top_k?: number;
     /** Agentic Search 활성화 — AI 가 쿼리를 자동 생성하여 다중 검색 수행 */
     agentic?: boolean;
+    /**
+     * Hybrid 검색 — BM25 키워드 + 벡터 시맨틱 검색을 RRF 로 융합.
+     * 미설정(기본): 콘솔 > AI 에서 embedding 을 켠 앱은 자동 적용.
+     * `false`: 키워드 전용 검색 강제. embedding 미설정 앱에서는 무시(BM25 only).
+     */
+    hybrid?: boolean;
     /**
      * metadata 기반 필터 (옵셔널). 키 형식 `metadata.<path>` 또는 raw key.
      * 값에 `AUTH_MEMBER_ID_TOKEN` 사용 시 서버가 인증된 AppMember ID 로 치환.
@@ -7655,6 +7662,11 @@ interface AIChatRequest {
     knowledgeBaseId?: string;
     topK?: number;
     agentic?: boolean;
+    /**
+     * KB 검색 hybrid(BM25 + 벡터 시맨틱, RRF 융합) 제어. 미설정(기본)이면 콘솔 > AI 에서
+     * embedding 을 켠 앱은 자동 적용, `false` 면 키워드 전용 검색 강제.
+     */
+    hybrid?: boolean;
     toolGroupId?: string;
     /**
      * 0 보다 크면, 서버측 도구 그룹 실행(`toolGroupId` 사용 시)에서 각 도구 결과를 모델에

package/dist/index.js

@@ -2279,14 +2279,15 @@ var StorageAPI = class {
    * 파일 목록 조회
    *
    * @param storageId - 파일 스토리지 ID
-   * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+   * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+   *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
    *
    * @example
    * ```ts
-   * // 루트 폴더의 파일 목록
+   * // 스토리지 전체 파일 목록 (flat 트리)
    * const files = await cb.storage.getFiles('storage-id')
    *
-   * // 특정 폴더의 하위 파일 목록
+   * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
    * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
    * ```
    */

package/dist/index.mjs

@@ -2234,14 +2234,15 @@ var StorageAPI = class {
    * 파일 목록 조회
    *
    * @param storageId - 파일 스토리지 ID
-   * @param parentId - 부모 폴더 ID (미지정 시 루트 폴더)
+   * @param parentId - 부모 폴더 ID. 지정 시 해당 폴더의 **직계 자식만** 반환한다.
+   *   미지정 시 스토리지 **전체 파일 트리**를 flat 배열로 반환한다.
    *
    * @example
    * ```ts
-   * // 루트 폴더의 파일 목록
+   * // 스토리지 전체 파일 목록 (flat 트리)
    * const files = await cb.storage.getFiles('storage-id')
    *
-   * // 특정 폴더의 하위 파일 목록
+   * // 특정 폴더의 직계 자식만 (대용량 버킷에서 전체 트리 전송 회피)
    * const subFiles = await cb.storage.getFiles('storage-id', 'folder-id')
    * ```
    */

package/package.json

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