@easytunnel/et-sdk 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 etunnel authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,47 @@
-# Temporary Holding Version
+# etunnel for Node.js
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Expose a local service through an etunnel reverse-tunnel server. Zero dependencies (Node >= 22 built-in WebSocket).
+
+Zero registration: every SDK client speaks the same tiny wire protocol
+([PROTOCOL.md](../../PROTOCOL.md)) against any etunnel server
+(default `wss://t.ggcode.uk/tunnel`).
+
+## Install
+
+```
+npm install @easytunnel/et-sdk
+```
+
+Requires Node >= 22.
+
+## CLI
+
+```
+npx @easytunnel/et-sdk 3000
+```
+
+Prints `TUNNEL_URL: https://<subdomain>.t.ggcode.uk` — that URL now routes to
+your local service. Ctrl-C closes the tunnel.
+
+## Embed
+
+```js
+const { connect } = require('@easytunnel/et-sdk');
+const t = await connect('wss://t.ggcode.uk/tunnel', 3000);
+console.log(t.url);
+```
+
+## Environment variables
+
+| Variable | Meaning | Default |
+|---|---|---|
+| `ETUNNEL_SERVER` | tunnel server WebSocket URL | `wss://t.ggcode.uk/tunnel` |
+| `ETUNNEL_LOCAL` | local port or `host:port` (or 1st CLI arg) | `3000` |
+| `ETUNNEL_TOKEN` | paid-plan API key (optional) | - |
+| `ETUNNEL_SUBDOMAIN` | custom subdomain (paid plans) | random |
+
+## License
+
+MIT — see [LICENSE](../../LICENSE). Buffer-based protocol client: request and
+response bodies are buffered per stream (fine for webhooks/dashboards/demos;
+use the [Go SDK](../../sdk) for streaming and WebSocket pass-through).

package/etunnel.js

@@ -0,0 +1,137 @@
+'use strict';
+// etunnel SDK for Node.js (>= 22, built-in WebSocket, zero dependencies).
+// Buffer-based protocol client: request/response bodies are buffered per
+// stream (fine for typical webhooks and demos; WebSocket upgrades are not
+// forwarded — use the Go SDK for full streaming/upgrades).
+//
+// const { connect } = require('./etunnel');
+// const t = await connect('wss://t.ggcode.uk/tunnel', 3000);
+// console.log(t.url);
+
+const MAXP = 32768;
+
+function frame(kind, id, payload) {
+  const p = payload || Buffer.alloc(0);
+  const b = Buffer.alloc(9 + p.length);
+  b.writeUInt8(kind, 0);
+  b.writeUInt32BE(id, 1);
+  b.writeUInt32BE(p.length, 5);
+  p.copy(b, 9);
+  return b;
+}
+
+const HOP = new Set(['connection', 'proxy-connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+
+function pickHostPort(local) {
+  if (/^\d+$/.test(String(local))) return { host: '127.0.0.1', port: Number(local) };
+  const m = /^(\[[^\]]+\]|[^:]+):(\d+)$/.exec(String(local));
+  if (m) return { host: m[1].replace(/^[\[\]]|$/g, ''), port: Number(m[2]) };
+  return { host: String(local), port: 80 };
+}
+
+async function connect(server, local, opts = {}) {
+  const { host, port } = pickHostPort(local);
+  const ws = new WebSocket(server, 'etunnel-v1');
+  ws.binaryType = 'arraybuffer';
+
+  await new Promise((res, rej) => {
+    ws.onopen = res;
+    ws.onerror = (e) => rej(new Error('ws: ' + (e.message || 'connect failed')));
+  });
+
+  ws.send(JSON.stringify({ type: 'hello', proto: 1, subdomain: opts.subdomain || undefined, token: opts.token || undefined, client: opts.client || 'etunnel-node/1.0' }));
+
+  const info = await new Promise((res, rej) => {
+    const to = setTimeout(() => rej(new Error('welcome timeout')), 15000);
+    ws.onmessage = (ev) => {
+      const m = JSON.parse(typeof ev.data === 'string' ? ev.data : Buffer.from(ev.data).toString());
+      if (m.type === 'welcome') { clearTimeout(to); res(m); }
+      else if (m.type === 'error') { clearTimeout(to); rej(Object.assign(new Error(m.code + ': ' + (m.message || '')), { code: m.code })); }
+    };
+  });
+
+  const state = { url: info.url, closed: false, streams: new Map() };
+  const send = (o) => ws.send(typeof o === 'string' ? o : o);
+  const sendBin = (buf) => ws.send(buf);
+
+  ws.onmessage = (ev) => {
+    if (typeof ev.data === 'string') {
+      const m = JSON.parse(ev.data);
+      if (m.type === 'req') {
+        state.streams.set(m.streamId, { req: m, body: [] });
+      } else if (m.type === 'ping') {
+        send(JSON.stringify({ type: 'pong', ts: m.ts }));
+      } else if (m.type === 'bye') {
+        state.closed = true;
+        if (opts.onClose) opts.onClose(m.reason);
+        try { ws.close(); } catch {}
+      }
+      return;
+    }
+    const b = Buffer.from(ev.data);
+    const kind = b.readUInt8(0);
+    const id = b.readUInt32BE(1);
+    const payload = b.subarray(9, 9 + b.readUInt32BE(5));
+    const st = state.streams.get(id);
+    if (!st) return;
+    if (kind === 0x01) st.body.push(payload);
+    else if (kind === 0x02) { state.streams.delete(id); handle(st, id).catch(() => trySend(frame(0x03, id))); }
+    else if (kind === 0x03) state.streams.delete(id);
+  };
+
+  async function handle(st, id) {
+    const body = Buffer.concat(st.body);
+    const headers = {};
+    let isHop = false;
+    for (const [k, vs] of Object.entries(st.req.headers || {})) {
+      const lk = k.toLowerCase();
+      if (HOP.has(lk)) { if (lk === 'connection' && /upgrade/i.test(String(vs))) isHop = true; continue; }
+      headers[k] = vs.join(', ');
+    }
+    let resp;
+    try {
+      resp = await fetch(`http://${host}:${port}${st.req.path}`, {
+        method: st.req.method,
+        headers,
+        body: ['GET', 'HEAD'].includes(st.req.method) ? undefined : body,
+      });
+    } catch (e) {
+      send(JSON.stringify({ type: 'res', streamId: id, status: 502, headers: { 'Content-Type': ['text/plain'] } }));
+      sendBin(frame(0x01, id, Buffer.from('etunnel: local service error: ' + e.message + '\n')));
+      sendBin(frame(0x02, id));
+      return;
+    }
+    const rh = {};
+    resp.headers.forEach((v, k) => { const lk = k.toLowerCase(); if (!HOP.has(lk)) (rh[k] = rh[k] || []).push(v); });
+    send(JSON.stringify({ type: 'res', streamId: id, status: resp.status, headers: rh }));
+    const buf = Buffer.from(await resp.arrayBuffer());
+    for (let i = 0; i < buf.length; i += MAXP) sendBin(frame(0x01, id, buf.subarray(i, Math.min(i + MAXP, buf.length))));
+    sendBin(frame(0x02, id));
+  }
+
+  function trySend(buf) { try { ws.send(buf); } catch {} }
+
+  return {
+    url: info.url,
+    hostname: info.hostname,
+    subdomain: info.subdomain,
+    plan: info.plan || '',
+    close(reason = 'client closed') {
+      if (state.closed) return;
+      state.closed = true;
+      try { send(JSON.stringify({ type: 'bye', reason })); } catch {}
+      try { ws.close(); } catch {}
+      if (opts.onClose) opts.onClose(reason);
+    },
+  };
+}
+
+module.exports = { connect };
+
+if (require.main === module) {
+  const server = process.env.ETUNNEL_SERVER || 'wss://t.ggcode.uk/tunnel';
+  const local = process.env.ETUNNEL_LOCAL || process.argv[2] || '3000';
+  connect(server, local, { token: process.env.ETUNNEL_TOKEN, subdomain: process.env.ETUNNEL_SUBDOMAIN })
+    .then((t) => { console.log('TUNNEL_URL: ' + t.url); })
+    .catch((e) => { console.error('etunnel:', e.message); process.exit(1); });
+}

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "@easytunnel/et-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Expose a local service through an etunnel reverse-tunnel server with one line of code. Zero dependencies, Node >= 22.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/topcheer/etunnel.git",
+    "directory": "sdks/node"
+  },
+  "homepage": "https://github.com/topcheer/etunnel#readme",
+  "bugs": {
+    "url": "https://github.com/topcheer/etunnel/issues"
+  },
+  "keywords": [
+    "tunnel",
+    "reverse-proxy",
+    "webhook",
+    "localhost",
+    "expose",
+    "ngrok",
+    "easytunnel"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "etunnel.js",
+  "bin": {
+    "etunnel": "etunnel.js"
+  },
+  "files": [
+    "etunnel.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}