connectbase-client 0.2.0 → 0.3.1

package/README.md

@@ -52,7 +52,7 @@ const state = await gameClient.createRoom({
 - **WebRTC**: Real-time audio/video communication
 - **Payments**: Subscription and one-time payment support
 - **AI Streaming**: Real-time AI text generation via WebSocket (Gemini)
-- **CLI**: Command-line tool for deploying web storage
+- **CLI**: Command-line tool for deploying web storage and tunneling local services
 
 ## CLI
 
@@ -81,6 +81,7 @@ The `init` command will:
 |---------|-------------|
 | `init` | Interactive project setup (creates config, adds deploy script) |
 | `deploy <dir>` | Deploy files to web storage |
+| `tunnel <port>` | Expose a local service to the internet via WebSocket tunnel |
 
 ### Manual Usage
 
@@ -97,9 +98,45 @@ npx connectbase-client deploy ./dist -s <storage-id> -k <api-key>
 | `--storage <id>` | `-s` | Storage ID |
 | `--api-key <key>` | `-k` | API Key |
 | `--base-url <url>` | `-u` | Custom server URL |
+| `--timeout <sec>` | `-t` | Tunnel request timeout in seconds (tunnel only) |
+| `--max-body <MB>` | | Tunnel max body size in MB (tunnel only) |
 | `--help` | `-h` | Show help |
 | `--version` | `-v` | Show version |
 
+### Tunnel
+
+Expose a local server to the internet through a secure WebSocket tunnel. Useful for sharing local MCP servers, development servers, or any HTTP service.
+
+```bash
+# Expose local port 8084 to the internet
+npx connectbase-client tunnel 8084 -k <api-key>
+
+# With environment variable
+export CONNECTBASE_API_KEY=your-api-key
+npx connectbase-client tunnel 8084
+
+# For GPU servers or long-running tasks (e.g., image generation)
+npx connectbase-client tunnel 7860 --timeout 300 --max-body 50
+```
+
+The tunnel creates a public URL like `https://tunnel.connectbase.world/<tunnel-id>/` that proxies all HTTP requests to your local service.
+
+**Plan-based limits:** Timeout and body size are clamped to your plan's maximum:
+
+| Plan | Max Timeout | Max Body |
+|------|-------------|----------|
+| Free | 60s | 10MB |
+| Starter | 120s | 25MB |
+| Pro | 300s | 50MB |
+| Business | 600s | 100MB |
+
+Features:
+- Per-tunnel timeout and body size configuration
+- Automatic reconnection with exponential backoff
+- Request/response logging in terminal
+- Graceful shutdown with Ctrl+C
+- No external dependencies (uses Node.js built-in modules)
+
 ### Configuration File
 
 The `init` command creates `.connectbaserc` automatically. You can also create it manually:

package/dist/cli.js

@@ -26,6 +26,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 // src/cli.ts
 var fs = __toESM(require("fs"));
 var path = __toESM(require("path"));
+var crypto = __toESM(require("crypto"));
 var https = __toESM(require("https"));
 var http = __toESM(require("http"));
 var readline = __toESM(require("readline"));
@@ -431,6 +432,347 @@ function addDeployScript(deployDir) {
     warn("package.json \uC218\uC815\uC5D0 \uC2E4\uD328\uD588\uC2B5\uB2C8\uB2E4");
   }
 }
+function createWsTextFrame(payload) {
+  const data = Buffer.from(payload, "utf-8");
+  const len = data.length;
+  const maskKey = crypto.randomBytes(4);
+  let header;
+  if (len < 126) {
+    header = Buffer.alloc(2);
+    header[0] = 129;
+    header[1] = 128 | len;
+  } else if (len < 65536) {
+    header = Buffer.alloc(4);
+    header[0] = 129;
+    header[1] = 128 | 126;
+    header.writeUInt16BE(len, 2);
+  } else {
+    header = Buffer.alloc(10);
+    header[0] = 129;
+    header[1] = 128 | 127;
+    header.writeBigUInt64BE(BigInt(len), 2);
+  }
+  const masked = Buffer.alloc(data.length);
+  for (let i = 0; i < data.length; i++) {
+    masked[i] = data[i] ^ maskKey[i % 4];
+  }
+  return Buffer.concat([header, maskKey, masked]);
+}
+function createWsCloseFrame(code) {
+  const maskKey = crypto.randomBytes(4);
+  const payload = Buffer.alloc(2);
+  payload.writeUInt16BE(code, 0);
+  const masked = Buffer.alloc(2);
+  masked[0] = payload[0] ^ maskKey[0];
+  masked[1] = payload[1] ^ maskKey[1];
+  const header = Buffer.alloc(2);
+  header[0] = 136;
+  header[1] = 128 | 2;
+  return Buffer.concat([header, maskKey, masked]);
+}
+function createWsPongFrame() {
+  const maskKey = crypto.randomBytes(4);
+  const header = Buffer.alloc(2);
+  header[0] = 138;
+  header[1] = 128 | 0;
+  return Buffer.concat([header, maskKey]);
+}
+var WsFrameParser = class {
+  constructor(handlers) {
+    this.buffer = Buffer.alloc(0);
+    this.onMessage = handlers.onMessage;
+    this.onClose = handlers.onClose;
+    this.onPing = handlers.onPing;
+  }
+  feed(chunk) {
+    this.buffer = Buffer.concat([this.buffer, chunk]);
+    this.parse();
+  }
+  parse() {
+    while (this.buffer.length >= 2) {
+      const firstByte = this.buffer[0];
+      const secondByte = this.buffer[1];
+      const opcode = firstByte & 15;
+      const isMasked = (secondByte & 128) !== 0;
+      let payloadLen = secondByte & 127;
+      let offset = 2;
+      if (payloadLen === 126) {
+        if (this.buffer.length < 4) return;
+        payloadLen = this.buffer.readUInt16BE(2);
+        offset = 4;
+      } else if (payloadLen === 127) {
+        if (this.buffer.length < 10) return;
+        payloadLen = Number(this.buffer.readBigUInt64BE(2));
+        offset = 10;
+      }
+      let maskKey = null;
+      if (isMasked) {
+        if (this.buffer.length < offset + 4) return;
+        maskKey = this.buffer.subarray(offset, offset + 4);
+        offset += 4;
+      }
+      if (this.buffer.length < offset + payloadLen) return;
+      let payload = this.buffer.subarray(offset, offset + payloadLen);
+      if (maskKey) {
+        const unmasked = Buffer.alloc(payloadLen);
+        for (let i = 0; i < payloadLen; i++) {
+          unmasked[i] = payload[i] ^ maskKey[i % 4];
+        }
+        payload = unmasked;
+      }
+      this.buffer = this.buffer.subarray(offset + payloadLen);
+      switch (opcode) {
+        case 1:
+          this.onMessage(payload.toString("utf-8"));
+          break;
+        case 8:
+          this.onClose();
+          break;
+        case 9:
+          this.onPing();
+          break;
+        case 10:
+          break;
+      }
+    }
+  }
+};
+function getTunnelServerUrl(baseUrl) {
+  if (baseUrl.includes("api.connectbase.world")) {
+    return baseUrl.replace("api.connectbase.world", "tunnel.connectbase.world");
+  }
+  if (baseUrl.includes("localhost:8080")) {
+    return baseUrl.replace("localhost:8080", "localhost:8090");
+  }
+  return baseUrl.replace(/:\d+/, ":8090");
+}
+async function startTunnel(port, config, tunnelOpts) {
+  if (!config.apiKey) {
+    error("API Key\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. -k \uC635\uC158 \uB610\uB294 CONNECTBASE_API_KEY \uD658\uACBD\uBCC0\uC218\uB97C \uC124\uC815\uD558\uC138\uC694");
+    process.exit(1);
+  }
+  const tunnelServerUrl = getTunnelServerUrl(config.baseUrl);
+  const parsedUrl = new URL(tunnelServerUrl);
+  const isHttps = parsedUrl.protocol === "https:";
+  let wsPath = `/v1/tunnel/connect?api_key=${encodeURIComponent(config.apiKey)}`;
+  if (tunnelOpts?.timeout) {
+    wsPath += `&timeout=${tunnelOpts.timeout}`;
+  }
+  if (tunnelOpts?.maxBody) {
+    wsPath += `&max_body=${tunnelOpts.maxBody}`;
+  }
+  let reconnectAttempts = 0;
+  const maxReconnectAttempts = 10;
+  let shouldReconnect = true;
+  let socket = null;
+  const cleanup = () => {
+    shouldReconnect = false;
+    if (socket) {
+      try {
+        socket.write(createWsCloseFrame(1e3));
+      } catch {
+      }
+      setTimeout(() => {
+        socket?.destroy();
+        process.exit(0);
+      }, 500);
+    } else {
+      process.exit(0);
+    }
+  };
+  process.on("SIGINT", cleanup);
+  process.on("SIGTERM", cleanup);
+  log(`
+${colors.cyan}ConnectBase Tunnel${colors.reset}`);
+  log(`${colors.dim}\uB85C\uCEEC \uD3EC\uD2B8 ${port}\uB97C \uC778\uD130\uB137\uC5D0 \uB178\uCD9C\uD569\uB2C8\uB2E4${colors.reset}
+`);
+  function connect() {
+    const lib = isHttps ? https : http;
+    const wsKey = crypto.randomBytes(16).toString("base64");
+    const reqOptions = {
+      hostname: parsedUrl.hostname,
+      port: parsedUrl.port || (isHttps ? 443 : 80),
+      path: wsPath,
+      method: "GET",
+      family: 4,
+      autoSelectFamily: false,
+      headers: {
+        "Upgrade": "websocket",
+        "Connection": "Upgrade",
+        "Sec-WebSocket-Key": wsKey,
+        "Sec-WebSocket-Version": "13"
+      }
+    };
+    const req = lib.request(reqOptions);
+    req.on("upgrade", (_res, sock, _head) => {
+      socket = sock;
+      reconnectAttempts = 0;
+      const parser = new WsFrameParser({
+        onMessage: (data) => {
+          try {
+            const msg = JSON.parse(data);
+            handleMessage(msg, sock, port);
+          } catch (e) {
+            warn(`\uBA54\uC2DC\uC9C0 \uD30C\uC2F1 \uC2E4\uD328: ${e}`);
+          }
+        },
+        onClose: () => {
+          info("\uC11C\uBC84\uAC00 \uC5F0\uACB0\uC744 \uC885\uB8CC\uD588\uC2B5\uB2C8\uB2E4");
+          sock.destroy();
+        },
+        onPing: () => {
+          sock.write(createWsPongFrame());
+        }
+      });
+      sock.on("data", (chunk) => parser.feed(chunk));
+      sock.on("close", () => {
+        socket = null;
+        if (shouldReconnect) {
+          scheduleReconnect();
+        }
+      });
+      sock.on("error", (err) => {
+        warn(`\uC5F0\uACB0 \uC5D0\uB7EC: ${err.message}`);
+        socket = null;
+        if (shouldReconnect) {
+          scheduleReconnect();
+        }
+      });
+    });
+    req.on("error", (err) => {
+      if (reconnectAttempts === 0) {
+        error(`\uD130\uB110 \uC11C\uBC84 \uC5F0\uACB0 \uC2E4\uD328: ${err.message}`);
+      }
+      if (shouldReconnect) {
+        scheduleReconnect();
+      }
+    });
+    req.on("response", (res) => {
+      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");
+          shouldReconnect = false;
+          process.exit(1);
+        } else if (res.statusCode === 402) {
+          error("\uD560\uB2F9\uB7C9 \uCD08\uACFC: \uD50C\uB79C\uC744 \uC5C5\uADF8\uB808\uC774\uB4DC\uD558\uC138\uC694");
+          shouldReconnect = false;
+          process.exit(1);
+        } else {
+          error(`\uD130\uB110 \uC11C\uBC84 \uC751\uB2F5 \uC624\uB958 (${res.statusCode}): ${body}`);
+          if (shouldReconnect) {
+            scheduleReconnect();
+          }
+        }
+      });
+    });
+    req.end();
+  }
+  function scheduleReconnect() {
+    reconnectAttempts++;
+    if (reconnectAttempts > maxReconnectAttempts) {
+      error("\uCD5C\uB300 \uC7AC\uC5F0\uACB0 \uC2DC\uB3C4 \uD69F\uC218 \uCD08\uACFC");
+      process.exit(1);
+    }
+    const delay = Math.min(2e3 * Math.pow(2, reconnectAttempts - 1), 3e4);
+    info(`${(delay / 1e3).toFixed(0)}\uCD08 \uD6C4 \uC7AC\uC5F0\uACB0 \uC2DC\uB3C4... (${reconnectAttempts}/${maxReconnectAttempts})`);
+    setTimeout(connect, delay);
+  }
+  function handleMessage(msg, sock, localPort) {
+    switch (msg.type) {
+      case "tunnel_ready":
+        success(`\uD130\uB110 \uD65C\uC131\uD654!`);
+        log(`${colors.green}\u2192${colors.reset} URL: ${colors.cyan}${msg.url}${colors.reset}`);
+        log(`${colors.green}\u2192${colors.reset} \uB85C\uCEEC: ${colors.cyan}http://localhost:${localPort}${colors.reset}`);
+        if (msg.timeout || msg.max_body) {
+          log(`${colors.green}\u2192${colors.reset} \uC124\uC815: timeout=${colors.cyan}${msg.timeout}s${colors.reset}, max-body=${colors.cyan}${msg.max_body}MB${colors.reset}`);
+        }
+        log(`
+${colors.dim}Ctrl+C\uB85C \uC885\uB8CC${colors.reset}
+`);
+        break;
+      case "http_request":
+        forwardRequest(msg, sock, localPort);
+        break;
+      case "tunnel_error":
+        error(`\uD130\uB110 \uC5D0\uB7EC: ${msg.message}`);
+        break;
+      case "ping":
+        sock.write(createWsTextFrame(JSON.stringify({ type: "pong" })));
+        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 chunks = [];
+      res.on("data", (chunk) => chunks.push(chunk));
+      res.on("end", () => {
+        const body = Buffer.concat(chunks);
+        const responseHeaders = {};
+        for (const [key, value] of Object.entries(res.headers)) {
+          if (value) responseHeaders[key] = Array.isArray(value) ? value.join(", ") : value;
+        }
+        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(() => {
+  });
+}
 function showHelp() {
   log(`
 ${colors.cyan}connectbase-client${colors.reset} - Connect Base SDK & CLI
@@ -441,11 +783,14 @@ ${colors.yellow}\uC0AC\uC6A9\uBC95:${colors.reset}
 ${colors.yellow}\uBA85\uB839\uC5B4:${colors.reset}
   init                  \uD504\uB85C\uC81D\uD2B8 \uCD08\uAE30\uD654 (\uC124\uC815 \uD30C\uC77C \uC0DD\uC131)
   deploy <directory>    \uC6F9 \uC2A4\uD1A0\uB9AC\uC9C0\uC5D0 \uD30C\uC77C \uBC30\uD3EC
+  tunnel <port>         \uB85C\uCEEC \uC11C\uBE44\uC2A4\uB97C \uC778\uD130\uB137\uC5D0 \uB178\uCD9C
 
 ${colors.yellow}\uC635\uC158:${colors.reset}
   -s, --storage <id>    \uC2A4\uD1A0\uB9AC\uC9C0 ID
   -k, --api-key <key>   API Key
   -u, --base-url <url>  \uC11C\uBC84 URL (\uAE30\uBCF8: ${DEFAULT_BASE_URL})
+  -t, --timeout <sec>   \uD130\uB110 \uC694\uCCAD \uD0C0\uC784\uC544\uC6C3 (\uCD08, tunnel \uC804\uC6A9)
+  --max-body <MB>       \uD130\uB110 \uCD5C\uB300 \uBC14\uB514 \uD06C\uAE30 (MB, tunnel \uC804\uC6A9)
   -h, --help            \uB3C4\uC6C0\uB9D0 \uD45C\uC2DC
   -v, --version         \uBC84\uC804 \uD45C\uC2DC
 
@@ -456,6 +801,12 @@ ${colors.yellow}\uBE60\uB978 \uC2DC\uC791:${colors.reset}
   ${colors.dim}# 2. \uBC30\uD3EC${colors.reset}
   npm run deploy
 
+  ${colors.dim}# 3. \uD130\uB110 (\uAE30\uBCF8)${colors.reset}
+  npx connectbase-client tunnel 3000
+
+  ${colors.dim}# 4. \uD130\uB110 (GPU \uC11C\uBC84 \uB4F1 \uAE34 \uC751\uB2F5 \uC2DC)${colors.reset}
+  npx connectbase-client tunnel 7860 --timeout 300 --max-body 50
+
 ${colors.yellow}\uD658\uACBD\uBCC0\uC218:${colors.reset}
   CONNECTBASE_API_KEY       API Key
   CONNECTBASE_STORAGE_ID    \uC2A4\uD1A0\uB9AC\uC9C0 ID
@@ -483,6 +834,10 @@ function parseArgs(args) {
       result.options.apiKey = args[++i];
     } else if (arg === "-u" || arg === "--base-url") {
       result.options.baseUrl = args[++i];
+    } else if (arg === "-t" || arg === "--timeout") {
+      result.options.timeout = args[++i];
+    } else if (arg === "--max-body") {
+      result.options.maxBody = args[++i];
     } else if (arg === "-h" || arg === "--help") {
       result.options.help = "true";
     } else if (arg === "-v" || arg === "--version") {
@@ -527,6 +882,27 @@ async function main() {
       process.exit(1);
     }
     await deploy(directory, config);
+  } else if (parsed.command === "tunnel") {
+    const portStr = parsed.args[0];
+    if (!portStr) {
+      error("\uD3EC\uD2B8 \uBC88\uD638\uAC00 \uD544\uC694\uD569\uB2C8\uB2E4. \uC608: npx connectbase-client tunnel 8084");
+      process.exit(1);
+    }
+    const port = parseInt(portStr, 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+      error("\uC720\uD6A8\uD55C \uD3EC\uD2B8 \uBC88\uD638\uB97C \uC785\uB825\uD558\uC138\uC694 (1-65535)");
+      process.exit(1);
+    }
+    const tunnelOpts = {};
+    if (parsed.options.timeout) {
+      const t = parseInt(parsed.options.timeout, 10);
+      if (!isNaN(t) && t > 0) tunnelOpts.timeout = t;
+    }
+    if (parsed.options.maxBody) {
+      const m = parseInt(parsed.options.maxBody, 10);
+      if (!isNaN(m) && m > 0) tunnelOpts.maxBody = m;
+    }
+    await startTunnel(port, config, tunnelOpts);
   } else {
     error(`\uC54C \uC218 \uC5C6\uB294 \uBA85\uB839\uC5B4: ${parsed.command}`);
     showHelp();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "connectbase-client",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Connect Base JavaScript/TypeScript SDK for browser and Node.js",
   "repository": {
     "type": "git",
@@ -45,7 +45,8 @@
     "deploy",
     "ai",
     "streaming",
-    "realtime"
+    "realtime",
+    "tunnel"
   ],
   "author": "",
   "license": "MIT",