connectbase-client 3.5.3 → 3.7.0

package/CHANGELOG.md

@@ -3,6 +3,58 @@
 본 SDK 의 모든 주요 변경사항을 [Keep a Changelog](https://keepachangelog.com/ko/1.1.0/) 형식으로 기록합니다.
 버전은 [Semantic Versioning](https://semver.org/lang/ko/) 을 따릅니다.
 
+## [3.6.0] - 2026-05-01
+
+### Added — `cb.realtime.stream()` 멀티모달 메시지 (Vision) 지원
+
+`cb.realtime.stream()` 의 `content` 필드가 `string` 외에도 OpenAI Vision spec
+호환 array 형식 (`{ type: 'text', text }` 또는 `{ type: 'image_url', image_url: { url } }`
+파트 배열) 을 받을 수 있게 됐습니다. 이미지 첨부 채팅을 SDK 한 줄로 작성 가능.
+
+**예시:**
+
+```ts
+await cb.realtime.stream(
+    [{
+        role: 'user',
+        content: [
+            { type: 'text', text: '이 이미지에 보이는 동물은?' },
+            { type: 'image_url', image_url: { url: 'https://.../cat.jpg' } },
+        ],
+    }],
+    { onToken, onDone, onError },
+    { provider: 'openai_compatible' },
+)
+```
+
+**Provider 별 처리:**
+
+- **`openai` / `openai_compatible` (vLLM, LM Studio, Ollama 등)**: content array 를
+  그대로 passthrough — vLLM 의 Qwen-VL / LLaVA / InternVL 등 모든 OpenAI Vision
+  호환 비전 모델 즉시 동작.
+- **`claude`**: `data:image/...;base64,...` URI 는 Claude 의 `source.type=base64`
+  콘텐츠 블록으로 변환, `https://...` URL 은 `source.type=url` 로 위임 (Anthropic
+  API 가 fetch 담당). 텍스트 파트는 `type=text` 블록으로 변환.
+- **`gemini`**: Gemini API 가 외부 URL fetch 를 지원하지 않으므로 SDK 가 사전
+  fetch (timeout 30s, 20MB 사이즈 캡, image/* MIME 검증) → base64 `inline_data`
+  로 변환. data URI 는 즉시 분해.
+
+**SDK 타입 변경:**
+
+- `StreamMessage.content`: `string` → `string | StreamContentPart[]` (union, 하위 호환).
+- 신규 export: `StreamContentPart`, `StreamTextPart`, `StreamImageURLPart`.
+
+**서버 변경:**
+
+- socket-server `protocol.StreamMessage.Content` 를 `json.RawMessage` 로 변경 후
+  새 helper `protocol.ParseStreamContent()` 가 string/array 를 통일 디코드.
+- pkg/ai 의 `Message` 에 `Parts []ContentPart` 추가 — provider 별 wire format 으로
+  분기 직렬화. `Message.Content` (string) 는 기존과 동일하게 유지 → 모든 string-only
+  호출자 (core-server, mcp-server 등) 회귀 무영향.
+
+**회귀 가드:** 11 multimodal provider 직렬화 테스트 + 11 protocol/handler 검증
+테스트 + 3 convertMessages plumbing 테스트 추가.
+
 ## [3.5.3] - 2026-05-01
 
 ### Fixed — `connectbase tunnel --label` 의 `tunnel_id` 추출 실패

package/dist/cli.js

@@ -1431,10 +1431,36 @@ function createWsPongFrame() {
   header[1] = 128 | 0;
   return Buffer.concat([header, maskKey]);
 }
+function createWsBinaryFrame(payload) {
+  const len = payload.length;
+  const maskKey = crypto.randomBytes(4);
+  let header;
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = 130;
+    header[1] = 128 | len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 130;
+    header[1] = 128 | 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 130;
+    header[1] = 128 | 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+  const masked = Buffer.alloc(len);
+  for (let i = 0; i < len; i++) {
+    masked[i] = payload[i] ^ maskKey[i % 4];
+  }
+  return Buffer.concat([header, maskKey, masked]);
+}
 var WsFrameParser = class {
   constructor(handlers) {
     this.buffer = Buffer.alloc(0);
     this.onMessage = handlers.onMessage;
+    this.onBinary = handlers.onBinary;
     this.onClose = handlers.onClose;
     this.onPing = handlers.onPing;
   }
@@ -1479,6 +1505,13 @@ var WsFrameParser = class {
         case 1:
           this.onMessage(payload.toString("utf-8"));
           break;
+        case 2:
+          if (this.onBinary) {
+            const copy = Buffer.alloc(payload.length);
+            payload.copy(copy);
+            this.onBinary(copy);
+          }
+          break;
         case 8:
           this.onClose();
           break;
@@ -1664,7 +1697,7 @@ async function startTunnel(port, config, tunnelOpts) {
   const tunnelServerUrl = getTunnelServerUrl(config.baseUrl);
   const parsedUrl = new URL(tunnelServerUrl);
   const isHttps = parsedUrl.protocol === "https:";
-  let wsPath = `/v1/tunnel/connect?app_id=${encodeURIComponent(appId)}&local_port=${port}`;
+  let wsPath = `/v2/tunnel/connect?app_id=${encodeURIComponent(appId)}&local_port=${port}`;
   if (tunnelOpts?.timeout) {
     wsPath += `&timeout=${tunnelOpts.timeout}`;
   }
@@ -1741,6 +1774,15 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
             warn(`\uBA54\uC2DC\uC9C0 \uD30C\uC2F1 \uC2E4\uD328: ${e}`);
           }
         },
+        onBinary: (data) => {
+          if (data.length < 8) {
+            warn(`v2 binary frame too short (${data.length} bytes)`);
+            return;
+          }
+          const streamId = data.readBigUInt64BE(0).toString();
+          const payload = data.subarray(8);
+          routeStreamData(streamId, payload);
+        },
         onClose: () => {
           info("\uC11C\uBC84\uAC00 \uC5F0\uACB0\uC744 \uC885\uB8CC\uD588\uC2B5\uB2C8\uB2E4");
           sock.destroy();
@@ -1804,6 +1846,190 @@ ${colors.cyan}ConnectBase Tunnel${colors.reset}`);
     info(`${(delay / 1e3).toFixed(0)}\uCD08 \uD6C4 \uC7AC\uC5F0\uACB0 \uC2DC\uB3C4... (${reconnectAttempts}/${maxReconnectAttempts})`);
     setTimeout(connect, delay);
   }
+  const streams = /* @__PURE__ */ new Map();
+  function routeStreamData(streamId, payload) {
+    const f = streams.get(streamId);
+    if (!f) return;
+    f.feedBody(payload);
+  }
+  function sendControl(sock, msg) {
+    try {
+      sock.write(createWsTextFrame(JSON.stringify(msg)));
+    } catch {
+    }
+  }
+  function sendBinary(sock, streamIdStr, payload) {
+    try {
+      const header = Buffer.alloc(8);
+      header.writeBigUInt64BE(BigInt(streamIdStr), 0);
+      sock.write(createWsBinaryFrame(Buffer.concat([header, payload])));
+    } catch {
+    }
+  }
+  function startHTTPStream(sock, streamId, open, localPort) {
+    const method = open.method || "GET";
+    const reqPath = open.path || "/";
+    const query = open.query || "";
+    const headers = open.headers || {};
+    const fullPath = query ? `${reqPath}?${query}` : reqPath;
+    const localHeaders = {};
+    for (const [k, v] of Object.entries(headers)) {
+      if (k.toLowerCase() !== "host") localHeaders[k] = v;
+    }
+    localHeaders["host"] = `localhost:${localPort}`;
+    let started = false;
+    let cancelled = false;
+    const localReq = http.request(
+      { hostname: "127.0.0.1", port: localPort, path: fullPath, method, headers: localHeaders },
+      (res) => {
+        const respHeaders = {};
+        for (const [k, v] of Object.entries(res.headers)) {
+          if (v == null) continue;
+          respHeaders[k] = Array.isArray(v) ? v.join(", ") : v;
+        }
+        started = true;
+        sendControl(sock, {
+          type: "stream_response",
+          stream_id: streamId,
+          status: res.statusCode || 502,
+          headers: respHeaders
+        });
+        const methodColor = method === "GET" ? colors.green : method === "POST" ? colors.blue : colors.yellow;
+        log(`${colors.dim}${(/* @__PURE__ */ new Date()).toLocaleTimeString()}${colors.reset} ${methodColor}${method}${colors.reset} ${reqPath} \u2192 ${res.statusCode}`);
+        res.on("data", (chunk) => {
+          if (cancelled) return;
+          sendBinary(sock, streamId, chunk);
+        });
+        res.on("end", () => {
+          if (cancelled) return;
+          sendControl(sock, { type: "stream_eof", stream_id: streamId, side: "upstream" });
+          sendControl(sock, { type: "stream_close", stream_id: streamId });
+          streams.delete(streamId);
+        });
+        res.on("error", (err) => {
+          sendControl(sock, { type: "stream_close", stream_id: streamId, error: `upstream_error: ${err.message}` });
+          streams.delete(streamId);
+        });
+      }
+    );
+    localReq.on("error", (err) => {
+      warn(`\uB85C\uCEEC \uC11C\uBC84 \uC5F0\uACB0 \uC2E4\uD328 (${method} ${reqPath}): ${err.message}`);
+      if (!started) {
+        sendControl(sock, {
+          type: "stream_response",
+          stream_id: streamId,
+          status: 502,
+          headers: { "content-type": "application/json" }
+        });
+        sendBinary(sock, streamId, Buffer.from(JSON.stringify({ error: `Local server error: ${err.message}` })));
+      }
+      sendControl(sock, { type: "stream_close", stream_id: streamId, error: `upstream_error: ${err.message}` });
+      streams.delete(streamId);
+    });
+    const forwarder = {
+      kind: "http",
+      feedBody: (chunk) => {
+        if (!cancelled) localReq.write(chunk);
+      },
+      endBody: () => {
+        if (!cancelled) localReq.end();
+      },
+      cancel: () => {
+        cancelled = true;
+        try {
+          localReq.destroy();
+        } catch {
+        }
+      }
+    };
+    streams.set(streamId, forwarder);
+  }
+  function startWSStream(sock, streamId, open, localPort) {
+    const reqPath = open.path || "/";
+    const query = open.query || "";
+    const headers = open.headers || {};
+    const fullPath = query ? `${reqPath}?${query}` : reqPath;
+    const localHeaders = {};
+    for (const [k, v] of Object.entries(headers)) {
+      if (k.toLowerCase() !== "host") localHeaders[k] = v;
+    }
+    localHeaders["host"] = `localhost:${localPort}`;
+    let cancelled = false;
+    let upstream = null;
+    const req = http.request({
+      hostname: "127.0.0.1",
+      port: localPort,
+      path: fullPath,
+      method: "GET",
+      headers: localHeaders
+    });
+    req.on("upgrade", (res, sk) => {
+      upstream = sk;
+      const respHeaders = {};
+      for (const [k, v] of Object.entries(res.headers)) {
+        if (v == null) continue;
+        respHeaders[k] = Array.isArray(v) ? v.join(", ") : v;
+      }
+      sendControl(sock, {
+        type: "stream_response",
+        stream_id: streamId,
+        status: res.statusCode || 101,
+        headers: respHeaders,
+        websocket: true
+      });
+      log(`${colors.dim}${(/* @__PURE__ */ new Date()).toLocaleTimeString()}${colors.reset} ${colors.cyan}WS${colors.reset} ${reqPath} \u2192 101`);
+      sk.on("data", (chunk) => {
+        if (cancelled) return;
+        sendBinary(sock, streamId, chunk);
+      });
+      sk.on("close", () => {
+        if (cancelled) return;
+        sendControl(sock, { type: "stream_close", stream_id: streamId });
+        streams.delete(streamId);
+      });
+      sk.on("error", (err) => {
+        sendControl(sock, { type: "stream_close", stream_id: streamId, error: `upstream_error: ${err.message}` });
+        streams.delete(streamId);
+      });
+    });
+    req.on("response", (res) => {
+      const respHeaders = {};
+      for (const [k, v] of Object.entries(res.headers)) {
+        if (v == null) continue;
+        respHeaders[k] = Array.isArray(v) ? v.join(", ") : v;
+      }
+      sendControl(sock, {
+        type: "stream_response",
+        stream_id: streamId,
+        status: res.statusCode || 502,
+        headers: respHeaders,
+        websocket: false
+      });
+      sendControl(sock, { type: "stream_close", stream_id: streamId });
+      streams.delete(streamId);
+    });
+    req.on("error", (err) => {
+      sendControl(sock, { type: "stream_close", stream_id: streamId, error: `upstream_error: ${err.message}` });
+      streams.delete(streamId);
+    });
+    req.end();
+    const forwarder = {
+      kind: "ws",
+      feedBody: (chunk) => {
+        if (!cancelled && upstream) upstream.write(chunk);
+      },
+      endBody: () => {
+      },
+      cancel: () => {
+        cancelled = true;
+        try {
+          upstream?.destroy();
+        } catch {
+        }
+      }
+    };
+    streams.set(streamId, forwarder);
+  }
   async function handleMessage(msg, sock, localPort) {
     switch (msg.type) {
       case "tunnel_ready": {
@@ -1851,9 +2077,38 @@ ${colors.dim}Ctrl+C\uB85C \uC885\uB8CC${colors.reset}
 `);
         break;
       }
-      case "http_request":
-        forwardRequest(msg, sock, localPort);
+      case "stream_open": {
+        const sid = String(msg.stream_id ?? "");
+        if (!sid) {
+          warn("stream_open with empty stream_id");
+          break;
+        }
+        const kind = msg.kind || "http";
+        if (kind === "ws") {
+          startWSStream(sock, sid, msg, localPort);
+        } else {
+          startHTTPStream(sock, sid, msg, localPort);
+        }
         break;
+      }
+      case "stream_eof": {
+        const sid = String(msg.stream_id ?? "");
+        const side = msg.side;
+        if (side === "client") {
+          const f = streams.get(sid);
+          f?.endBody();
+        }
+        break;
+      }
+      case "stream_close": {
+        const sid = String(msg.stream_id ?? "");
+        const f = streams.get(sid);
+        if (f) {
+          f.cancel();
+          streams.delete(sid);
+        }
+        break;
+      }
       case "tunnel_error": {
         const result = handleTunnelError(msg, appId, localPort);
         error(result.message);
@@ -1868,121 +2123,6 @@ ${colors.dim}Ctrl+C\uB85C \uC885\uB8CC${colors.reset}
         break;
     }
   }
-  function forwardRequest(msg, sock, localPort) {
-    const requestId = msg.request_id;
-    const method = msg.method;
-    const reqPath = msg.path;
-    const query = msg.query || "";
-    const headers = msg.headers || {};
-    const bodyBase64 = msg.body;
-    const fullPath = query ? `${reqPath}?${query}` : reqPath;
-    const localHeaders = {};
-    for (const [key, value] of Object.entries(headers)) {
-      if (key.toLowerCase() !== "host") {
-        localHeaders[key] = value;
-      }
-    }
-    localHeaders["host"] = `localhost:${localPort}`;
-    const reqOptions = {
-      hostname: "127.0.0.1",
-      port: localPort,
-      path: fullPath,
-      method,
-      headers: localHeaders
-    };
-    const localReq = http.request(reqOptions, (res) => {
-      const responseHeaders = {};
-      for (const [key, value] of Object.entries(res.headers)) {
-        if (value) responseHeaders[key] = Array.isArray(value) ? value.join(", ") : value;
-      }
-      const contentType = (responseHeaders["content-type"] || "").toLowerCase();
-      const transferEncoding = (responseHeaders["transfer-encoding"] || "").toLowerCase();
-      const isStreaming = contentType.includes("text/event-stream") || transferEncoding.includes("chunked");
-      if (isStreaming) {
-        try {
-          sock.write(createWsTextFrame(JSON.stringify({
-            type: "http_response_start",
-            request_id: requestId,
-            status: res.statusCode || 200,
-            headers: responseHeaders
-          })));
-        } catch {
-          warn(`\uC2A4\uD2B8\uB9AC\uBC0D \uC2DC\uC791 \uC804\uC1A1 \uC2E4\uD328: ${requestId}`);
-          return;
-        }
-        const methodColor = method === "GET" ? colors.green : method === "POST" ? colors.blue : colors.yellow;
-        log(`${colors.dim}${(/* @__PURE__ */ new Date()).toLocaleTimeString()}${colors.reset} ${methodColor}${method}${colors.reset} ${reqPath} \u2192 ${res.statusCode} ${colors.cyan}[stream]${colors.reset}`);
-        res.on("data", (chunk) => {
-          try {
-            sock.write(createWsTextFrame(JSON.stringify({
-              type: "http_response_chunk",
-              request_id: requestId,
-              data: chunk.toString("base64")
-            })));
-          } catch {
-            warn(`\uC2A4\uD2B8\uB9AC\uBC0D \uCCAD\uD06C \uC804\uC1A1 \uC2E4\uD328: ${requestId}`);
-          }
-        });
-        res.on("end", () => {
-          try {
-            sock.write(createWsTextFrame(JSON.stringify({
-              type: "http_response_end",
-              request_id: requestId
-            })));
-          } catch {
-          }
-        });
-        res.on("error", (err) => {
-          try {
-            sock.write(createWsTextFrame(JSON.stringify({
-              type: "http_response_error",
-              request_id: requestId,
-              error: err.message
-            })));
-          } catch {
-          }
-        });
-      } else {
-        const chunks = [];
-        res.on("data", (chunk) => chunks.push(chunk));
-        res.on("end", () => {
-          const body = Buffer.concat(chunks);
-          const response = {
-            type: "http_response",
-            request_id: requestId,
-            status: res.statusCode || 200,
-            headers: responseHeaders,
-            body: body.length > 0 ? body.toString("base64") : ""
-          };
-          try {
-            sock.write(createWsTextFrame(JSON.stringify(response)));
-            const methodColor = method === "GET" ? colors.green : method === "POST" ? colors.blue : colors.yellow;
-            log(`${colors.dim}${(/* @__PURE__ */ new Date()).toLocaleTimeString()}${colors.reset} ${methodColor}${method}${colors.reset} ${reqPath} \u2192 ${res.statusCode}`);
-          } catch {
-            warn(`\uC751\uB2F5 \uC804\uC1A1 \uC2E4\uD328: ${requestId}`);
-          }
-        });
-      }
-    });
-    localReq.on("error", (err) => {
-      const response = {
-        type: "http_response",
-        request_id: requestId,
-        status: 502,
-        headers: { "content-type": "application/json" },
-        body: Buffer.from(JSON.stringify({ error: `Local server error: ${err.message}` })).toString("base64")
-      };
-      try {
-        sock.write(createWsTextFrame(JSON.stringify(response)));
-      } catch {
-      }
-      warn(`\uB85C\uCEEC \uC11C\uBC84 \uC5F0\uACB0 \uC2E4\uD328 (${method} ${reqPath}): ${err.message}`);
-    });
-    if (bodyBase64) {
-      localReq.write(Buffer.from(bodyBase64, "base64"));
-    }
-    localReq.end();
-  }
   connect();
   await new Promise(() => {
   });