feat: tunnel package (#115)

Author: hugodutka

.gitignore

@@ -5,3 +5,4 @@ dist/
 .sonda
 .next
 **/tsconfig.tsbuildinfo
+.wrangler

biome.json

@@ -0,0 +1,49 @@
+{
+  "$schema": "https://biomejs.dev/schemas/2.3.2/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git",
+    "useIgnoreFile": true
+  },
+  "files": {
+    "ignoreUnknown": false
+  },
+  "formatter": {
+    "enabled": false
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true,
+      "suspicious": {
+        "noConsole": "warn"
+      }
+    }
+  },
+  "overrides": [
+    {
+      "includes": ["**/*.test.ts", "**/*.test-suite.ts"],
+      "linter": {
+        "rules": {
+          "style": {
+            "noNonNullAssertion": "off"
+          }
+        }
+      }
+    }
+  ],
+
+  "javascript": {
+    "formatter": {
+      "quoteStyle": "double"
+    }
+  },
+  "assist": {
+    "enabled": true,
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}

bun.lock

@@ -0,0 +1,67 @@
+/**
+ * Example tunnel client that proxies HTTP and WebSocket requests to localhost:8000.
+ *
+ * Run with: npx tsx examples/client.ts
+ *
+ * Make sure you have:
+ * 1. The tunnel server running (npx tsx examples/server.ts)
+ * 2. A local server running on port 8000 (e.g., python -m http.server 8000)
+ *
+ * For WebSocket testing, you can use a simple WebSocket server like:
+ *   npx wscat -l 8000
+ * Then connect via the tunnel URL using wscat or a browser.
+ */
+/** biome-ignore-all lint/suspicious/noConsole: this is an example file */
+
+import { TunnelClient } from "../src/client";
+
+const SERVER_URL = "http://localhost:8080";
+const CLIENT_SECRET = crypto.randomUUID();
+const LOCAL_SERVER_PORT = 8000;
+
+const client = new TunnelClient({
+  serverUrl: SERVER_URL,
+  secret: CLIENT_SECRET,
+  transformRequest: async ({ method, url, headers }) => {
+    url.protocol = "http";
+    url.host = `localhost:${LOCAL_SERVER_PORT}`;
+    return { method, url, headers };
+  },
+  onConnect: ({ url, id }) => {
+    console.log(`Connected to tunnel server!`);
+    console.log(`Client secret: ${CLIENT_SECRET}`);
+    console.log(`Public URL: ${url}`);
+    console.log(`Tunnel ID: ${id}`);
+    console.log(
+      `\nHTTP requests to ${url}/* will be proxied to http://localhost:${LOCAL_SERVER_PORT}/*`
+    );
+    console.log(
+      `WebSocket connections to ${url.replace("http", "ws")}/* will be proxied to ws://localhost:${LOCAL_SERVER_PORT}/*`
+    );
+  },
+  onDisconnect: () => {
+    console.log("Disconnected from tunnel server");
+  },
+  onError: (error) => {
+    console.error("Tunnel error:", error);
+  },
+});
+
+console.log(`Connecting to tunnel server at ${SERVER_URL}...`);
+console.log(
+  `Will proxy HTTP and WebSocket requests to localhost:${LOCAL_SERVER_PORT}`
+);
+
+const disposable = client.connect();
+
+// Handle graceful shutdown
+process.on("SIGINT", () => {
+  console.log("\nDisconnecting...");
+  disposable.dispose();
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  disposable.dispose();
+  process.exit(0);
+});

packages/tunnel/examples/client.ts

@@ -0,0 +1,41 @@
+/**
+ * Example tunnel server for local testing.
+ *
+ * Run with: npx tsx examples/server.ts
+ */
+/** biome-ignore-all lint/suspicious/noConsole: this is an example file */
+
+import { createLocalServer } from "../src/server/local";
+
+const PORT = 8080;
+const SERVER_SECRET = "example-server-secret";
+
+const { close } = createLocalServer({
+  port: PORT,
+  secret: SERVER_SECRET,
+  baseUrl: `http://localhost:${PORT}`,
+  mode: "subpath",
+  onReady: (port) => {
+    console.log(`Tunnel server running on http://localhost:${port}`);
+    console.log(`Waiting for clients to connect...`);
+  },
+  onClientConnect: (id) => {
+    console.log(`Client connected: ${id}`);
+    console.log(`Public URL: http://localhost:${PORT}/tunnel/${id}`);
+  },
+  onClientDisconnect: (id) => {
+    console.log(`Client disconnected: ${id}`);
+  },
+});
+
+// Handle graceful shutdown
+process.on("SIGINT", () => {
+  console.log("\nShutting down server...");
+  close();
+  process.exit(0);
+});
+
+process.on("SIGTERM", () => {
+  close();
+  process.exit(0);
+});

packages/tunnel/examples/server.ts

@@ -0,0 +1,50 @@
+{
+  "name": "@blink-sdk/tunnel",
+  "description": "Tunnel - expose local servers via a public URL",
+  "version": "0.0.1",
+  "type": "module",
+  "keywords": [
+    "blink",
+    "tunnel",
+    "proxy",
+    "webhook"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Coder",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/coder/blink.git"
+  },
+  "homepage": "https://github.com/coder/blink/tree/main/packages/tunnel",
+  "bugs": {
+    "url": "https://github.com/coder/blink/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsgo --noEmit"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "@blink-sdk/events": "workspace:*",
+    "@blink-sdk/multiplexer": "workspace:*",
+    "ws": "^8.18.0"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "^4.20250109.0",
+    "@types/ws": "^8.5.10",
+    "hono": "^4.7.10",
+    "tsdown": "^0.11.12",
+    "wrangler": "^4.22.0"
+  }
+}