wasmnet 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # wasmnet
 
-Browser client for [wasmnet](https://github.com/anistark/wasmnet) — a networking proxy that bridges WASI socket APIs to real TCP via WebSocket.
+Browser client for [wasmnet](https://github.com/anistark/wasmnet) — a networking proxy that bridges WASI socket APIs to real TCP/UDP/TLS via WebSocket.
 
 ## Install
 
@@ -16,28 +16,28 @@ import { WasmnetClient } from 'wasmnet';
 const client = new WasmnetClient('ws://localhost:9000');
 await client.ready();
 
-// Outbound TCP connection
-const id = await client.connect('api.example.com', 443);
+// TCP
+const id = await client.connect('example.com', 80);
+client.onData(id, (data) => console.log(new TextDecoder().decode(data)));
+client.send(id, 'GET / HTTP/1.1\r\nHost: example.com\r\n\r\n');
 
-client.onData(id, (data) => {
-  console.log('received:', new TextDecoder().decode(data));
-});
+// TLS (server handles handshake)
+const tls = await client.connectTls('api.example.com', 443);
+client.onData(tls, (data) => console.log('tls:', data));
 
-client.onClose(id, () => {
-  console.log('connection closed');
-});
+// UDP
+const udp = await client.connectUdp('8.8.8.8', 53);
+client.onDataFrom(udp.id, (data, addr, port) => console.log(data));
+client.send(udp.id, packet);
+client.sendTo(udp.id, '8.8.4.4', 53, packet); // different target
 
-client.send(id, 'GET / HTTP/1.1\r\nHost: api.example.com\r\n\r\n');
+// DNS resolve
+const ips = await client.resolve('example.com');
 
-// Inbound TCP (bind a port)
+// Inbound TCP
 const listener = await client.bind('0.0.0.0', 3000);
-console.log(`listening on port ${listener.port}`);
-
 client.onAccept(listener.id, (connId, remote) => {
-  console.log(`accepted connection from ${remote}`);
-  client.onData(connId, (data) => {
-    client.send(connId, data); // echo
-  });
+  client.onData(connId, (data) => client.send(connId, data));
 });
 
 // Cleanup
@@ -45,20 +45,36 @@ client.close(id);
 client.disconnect();
 ```
 
+### Binary framing
+
+Pass `{ binary: true }` to skip JSON + base64 overhead on data frames. Raw bytes are sent directly in WebSocket binary messages.
+
+```javascript
+const client = new WasmnetClient('ws://localhost:9000', { binary: true });
+```
+
 ## API
 
-### `new WasmnetClient(url: string)`
+### `new WasmnetClient(url: string, options?: { binary?: boolean })`
 
-Creates a client connecting to the wasmnet server at the given WebSocket URL.
+Creates a client connecting to the wasmnet server. Set `binary: true` for binary framing mode.
 
 ### `ready(): Promise<void>`
 
-Resolves when the WebSocket connection is established.
+Resolves when the WebSocket connection is open.
 
 ### `connect(addr: string, port: number): Promise<number>`
 
 Opens an outbound TCP connection. Returns the socket ID.
 
+### `connectTls(addr: string, port: number): Promise<number>`
+
+Opens an outbound TCP connection with TLS. The wasmnet server handles the TLS handshake (using system CA roots). Returns the socket ID. Data sent/received through this socket is plaintext — encryption is handled transparently.
+
+### `connectUdp(addr: string, port: number): Promise<{ id: number, port: number }>`
+
+Creates a UDP socket connected to the given address. Returns the socket ID and local port. Use `send()` to send to the connected address, or `sendTo()` for arbitrary targets.
+
 ### `bind(addr: string, port: number): Promise<{ id: number, port: number }>`
 
 Binds a TCP listener. Returns the listener ID and actual bound port.
@@ -69,7 +85,15 @@ Starts accepting connections on a bound listener.
 
 ### `send(id: number, data: string | Uint8Array | ArrayBuffer): void`
 
-Sends data on a socket. Strings are UTF-8 encoded, binary data is sent as-is.
+Sends data on a TCP, TLS, or connected UDP socket.
+
+### `sendTo(id: number, addr: string, port: number, data: string | Uint8Array | ArrayBuffer): void`
+
+Sends a UDP datagram to a specific target address, regardless of the socket's connected address.
+
+### `resolve(name: string): Promise<string[]>`
+
+Resolves a hostname to an array of IP address strings (both IPv4 and IPv6).
 
 ### `close(id: number): void`
 
@@ -77,7 +101,11 @@ Closes a socket or listener.
 
 ### `onData(id: number, callback: (data: Uint8Array) => void): void`
 
-Registers a data handler. Any buffered data is flushed immediately.
+Registers a data handler for TCP/TLS sockets. Any data buffered before the handler was set is flushed immediately.
+
+### `onDataFrom(id: number, callback: (data: Uint8Array, addr: string, port: number) => void): void`
+
+Registers a data handler for UDP sockets. Each callback includes the source address and port.
 
 ### `onClose(id: number, callback: () => void): void`
 
@@ -85,10 +113,12 @@ Registers a close handler.
 
 ### `onAccept(id: number, callback: (connId: number, remote: string) => void): void`
 
-Registers an accept handler for a listener.
+Registers an accept handler for a TCP listener. `connId` is the new socket ID for the accepted connection.
 
 ### `disconnect(): void`
 
 Closes the WebSocket connection and all sockets.
 
-## MIT License
+## License
+
+MIT

package/dist/wasmnet-client.d.ts

@@ -3,20 +3,56 @@ export interface ListenResult {
   port: number;
 }
 
+export interface ClientOptions {
+  /** Use binary framing instead of JSON (lower overhead for data). */
+  binary?: boolean;
+}
+
 export type DataCallback = (data: Uint8Array) => void;
+export type DataFromCallback = (
+  data: Uint8Array,
+  addr: string,
+  port: number,
+) => void;
 export type CloseCallback = () => void;
 export type AcceptCallback = (connId: number, remote: string) => void;
 
 export class WasmnetClient {
-  constructor(url: string);
+  constructor(url: string, options?: ClientOptions);
 
   ready(): Promise<void>;
+
+  /** TCP connect to a remote host. */
   connect(addr: string, port: number): Promise<number>;
+
+  /** TCP connect with TLS (server handles TLS handshake). */
+  connectTls(addr: string, port: number): Promise<number>;
+
+  /** Create a UDP socket connected to a remote host. */
+  connectUdp(addr: string, port: number): Promise<ListenResult>;
+
+  /** Bind a TCP listener. */
   bind(addr: string, port: number): Promise<ListenResult>;
+
   listen(id: number, backlog?: number): void;
+
+  /** Send data on a TCP or connected-UDP socket. */
   send(id: number, data: string | Uint8Array | ArrayBuffer): void;
+
+  /** Send a UDP datagram to a specific address. */
+  sendTo(
+    id: number,
+    addr: string,
+    port: number,
+    data: string | Uint8Array | ArrayBuffer,
+  ): void;
+
+  /** Resolve a hostname to IP addresses. */
+  resolve(name: string): Promise<string[]>;
+
   close(id: number): void;
   onData(id: number, callback: DataCallback): void;
+  onDataFrom(id: number, callback: DataFromCallback): void;
   onClose(id: number, callback: CloseCallback): void;
   onAccept(id: number, callback: AcceptCallback): void;
   disconnect(): void;

package/dist/wasmnet-client.js

@@ -1,13 +1,48 @@
+const BINARY_HEADER = 9; // 1 byte type + 8 byte id
+
+const MSG = {
+  // requests
+  CONNECT: 0x01,
+  BIND: 0x02,
+  LISTEN: 0x03,
+  SEND: 0x04,
+  CLOSE: 0x05,
+  CONNECT_UDP: 0x06,
+  SEND_TO: 0x07,
+  RESOLVE: 0x08,
+  CONNECT_TLS: 0x09,
+  // events
+  CONNECTED: 0x81,
+  DATA: 0x82,
+  LISTENING: 0x83,
+  ACCEPTED: 0x84,
+  CLOSED: 0x85,
+  ERROR: 0x86,
+  DENIED: 0x87,
+  DATA_FROM: 0x88,
+  RESOLVED: 0x89,
+  UDP_BOUND: 0x8a,
+};
+
 export class WasmnetClient {
-  constructor(url) {
+  constructor(url, options = {}) {
     this.ws = new WebSocket(url);
+    this.ws.binaryType = "arraybuffer";
     this.sockets = new Map();
     this.nextId = 1;
+    this.binary = options.binary === true;
+    this._resolves = new Map();
     this._ready = new Promise((resolve, reject) => {
       this.ws.onopen = () => resolve();
       this.ws.onerror = (e) => reject(e);
     });
-    this.ws.onmessage = (e) => this._handleEvent(JSON.parse(e.data));
+    this.ws.onmessage = (e) => {
+      if (e.data instanceof ArrayBuffer) {
+        this._handleBinaryEvent(new Uint8Array(e.data));
+      } else {
+        this._handleEvent(JSON.parse(e.data));
+      }
+    };
     this.ws.onclose = () => this._handleClose();
   }
 
@@ -18,8 +53,63 @@ export class WasmnetClient {
   connect(addr, port) {
     const id = this.nextId++;
     return new Promise((resolve, reject) => {
-      this.sockets.set(id, { resolve, reject, buffer: [], onData: null, onClose: null });
-      this._send({ op: "connect", id, addr, port });
+      this.sockets.set(id, {
+        resolve,
+        reject,
+        buffer: [],
+        onData: null,
+        onClose: null,
+      });
+      if (this.binary) {
+        this._sendBinary(MSG.CONNECT, id, this._addrPortPayload(addr, port));
+      } else {
+        this._send({ op: "connect", id, addr, port });
+      }
+    });
+  }
+
+  connectTls(addr, port) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.sockets.set(id, {
+        resolve,
+        reject,
+        buffer: [],
+        onData: null,
+        onClose: null,
+      });
+      if (this.binary) {
+        this._sendBinary(
+          MSG.CONNECT_TLS,
+          id,
+          this._addrPortPayload(addr, port),
+        );
+      } else {
+        this._send({ op: "connect_tls", id, addr, port });
+      }
+    });
+  }
+
+  connectUdp(addr, port) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this.sockets.set(id, {
+        resolve,
+        reject,
+        buffer: [],
+        onData: null,
+        onDataFrom: null,
+        onClose: null,
+      });
+      if (this.binary) {
+        this._sendBinary(
+          MSG.CONNECT_UDP,
+          id,
+          this._addrPortPayload(addr, port),
+        );
+      } else {
+        this._send({ op: "connect_udp", id, addr, port });
+      }
     });
   }
 
@@ -27,21 +117,81 @@ export class WasmnetClient {
     const id = this.nextId++;
     return new Promise((resolve, reject) => {
       this.sockets.set(id, { resolve, reject, onAccept: null });
-      this._send({ op: "bind", id, addr, port });
+      if (this.binary) {
+        this._sendBinary(MSG.BIND, id, this._addrPortPayload(addr, port));
+      } else {
+        this._send({ op: "bind", id, addr, port });
+      }
     });
   }
 
   listen(id, backlog = 128) {
-    this._send({ op: "listen", id, backlog });
+    if (this.binary) {
+      const p = new Uint8Array(4);
+      new DataView(p.buffer).setUint32(0, backlog);
+      this._sendBinary(MSG.LISTEN, id, p);
+    } else {
+      this._send({ op: "listen", id, backlog });
+    }
   }
 
   send(id, data) {
-    const encoded = typeof data === "string" ? btoa(data) : this._encodeBinary(data);
-    this._send({ op: "send", id, data: encoded });
+    if (this.binary) {
+      const bytes =
+        data instanceof Uint8Array
+          ? data
+          : typeof data === "string"
+            ? new TextEncoder().encode(data)
+            : new Uint8Array(data);
+      this._sendBinary(MSG.SEND, id, bytes);
+    } else {
+      const encoded =
+        typeof data === "string" ? btoa(data) : this._encodeBinary(data);
+      this._send({ op: "send", id, data: encoded });
+    }
+  }
+
+  sendTo(id, addr, port, data) {
+    if (this.binary) {
+      const addrBytes = new TextEncoder().encode(addr);
+      const raw =
+        data instanceof Uint8Array
+          ? data
+          : typeof data === "string"
+            ? new TextEncoder().encode(data)
+            : new Uint8Array(data);
+      const payload = new Uint8Array(4 + addrBytes.length + raw.length);
+      const dv = new DataView(payload.buffer);
+      dv.setUint16(0, port);
+      dv.setUint16(2, addrBytes.length);
+      payload.set(addrBytes, 4);
+      payload.set(raw, 4 + addrBytes.length);
+      this._sendBinary(MSG.SEND_TO, id, payload);
+    } else {
+      const encoded =
+        typeof data === "string" ? btoa(data) : this._encodeBinary(data);
+      this._send({ op: "send_to", id, addr, port, data: encoded });
+    }
+  }
+
+  resolve(name) {
+    const id = this.nextId++;
+    return new Promise((resolve, reject) => {
+      this._resolves.set(id, { resolve, reject });
+      if (this.binary) {
+        this._sendBinary(MSG.RESOLVE, id, new TextEncoder().encode(name));
+      } else {
+        this._send({ op: "resolve", id, name });
+      }
+    });
   }
 
   close(id) {
-    this._send({ op: "close", id });
+    if (this.binary) {
+      this._sendBinary(MSG.CLOSE, id, new Uint8Array(0));
+    } else {
+      this._send({ op: "close", id });
+    }
     this.sockets.delete(id);
   }
 
@@ -55,6 +205,11 @@ export class WasmnetClient {
     sock.buffer = [];
   }
 
+  onDataFrom(id, callback) {
+    const sock = this.sockets.get(id);
+    if (sock) sock.onDataFrom = callback;
+  }
+
   onClose(id, callback) {
     const sock = this.sockets.get(id);
     if (sock) sock.onClose = callback;
@@ -69,6 +224,8 @@ export class WasmnetClient {
     this.ws.close();
   }
 
+  // ── JSON transport ───────────────────────────────────
+
   _send(msg) {
     this.ws.send(JSON.stringify(msg));
   }
@@ -91,7 +248,168 @@ export class WasmnetClient {
     return bytes;
   }
 
+  // ── Binary transport ─────────────────────────────────
+
+  _sendBinary(type_, id, payload) {
+    const frame = new Uint8Array(BINARY_HEADER + payload.length);
+    frame[0] = type_;
+    const dv = new DataView(frame.buffer);
+    dv.setBigUint64(1, BigInt(id));
+    frame.set(payload, BINARY_HEADER);
+    this.ws.send(frame.buffer);
+  }
+
+  _addrPortPayload(addr, port) {
+    const addrBytes = new TextEncoder().encode(addr);
+    const payload = new Uint8Array(2 + addrBytes.length);
+    new DataView(payload.buffer).setUint16(0, port);
+    payload.set(addrBytes, 2);
+    return payload;
+  }
+
+  _handleBinaryEvent(data) {
+    if (data.length < BINARY_HEADER) return;
+    const type_ = data[0];
+    const dv = new DataView(data.buffer, data.byteOffset, data.byteLength);
+    const id = Number(dv.getBigUint64(1));
+    const payload = data.subarray(BINARY_HEADER);
+
+    switch (type_) {
+      case MSG.CONNECTED:
+        this._dispatch(id, "connected", {});
+        break;
+      case MSG.DATA:
+        this._dispatch(id, "data", { raw: payload });
+        break;
+      case MSG.LISTENING:
+        this._dispatch(id, "listening", {
+          port: new DataView(
+            payload.buffer,
+            payload.byteOffset,
+            payload.byteLength,
+          ).getUint16(0),
+        });
+        break;
+      case MSG.ACCEPTED: {
+        const connId = Number(
+          new DataView(
+            payload.buffer,
+            payload.byteOffset,
+            payload.byteLength,
+          ).getBigUint64(0),
+        );
+        const remote = new TextDecoder().decode(payload.subarray(8));
+        this._dispatch(id, "accepted", { conn_id: connId, remote });
+        break;
+      }
+      case MSG.CLOSED:
+        this._dispatch(id, "closed", {});
+        break;
+      case MSG.ERROR:
+        this._dispatch(id, "error", {
+          msg: new TextDecoder().decode(payload),
+        });
+        break;
+      case MSG.DENIED:
+        this._dispatch(id, "denied", {
+          msg: new TextDecoder().decode(payload),
+        });
+        break;
+      case MSG.DATA_FROM: {
+        const pdv = new DataView(
+          payload.buffer,
+          payload.byteOffset,
+          payload.byteLength,
+        );
+        const port = pdv.getUint16(0);
+        const addrLen = pdv.getUint16(2);
+        const addr = new TextDecoder().decode(payload.subarray(4, 4 + addrLen));
+        const raw = payload.subarray(4 + addrLen);
+        this._dispatch(id, "data_from", { addr, port, raw });
+        break;
+      }
+      case MSG.RESOLVED: {
+        const addrs = JSON.parse(new TextDecoder().decode(payload));
+        this._dispatchResolve(id, addrs);
+        break;
+      }
+      case MSG.UDP_BOUND:
+        this._dispatch(id, "udp_bound", {
+          port: new DataView(
+            payload.buffer,
+            payload.byteOffset,
+            payload.byteLength,
+          ).getUint16(0),
+        });
+        break;
+    }
+  }
+
+  _dispatch(id, ev, extra) {
+    const sock = this.sockets.get(id);
+    if (!sock && ev !== "resolved") return;
+
+    switch (ev) {
+      case "connected":
+        sock.resolve?.(id);
+        break;
+      case "listening":
+        sock.resolve?.({ id, port: extra.port });
+        break;
+      case "udp_bound":
+        sock.resolve?.({ id, port: extra.port });
+        break;
+      case "data": {
+        const decoded = extra.raw || this._decodeBinary(extra.b64);
+        if (sock.onData) {
+          sock.onData(decoded);
+        } else {
+          sock.buffer.push(decoded);
+        }
+        break;
+      }
+      case "data_from":
+        sock.onDataFrom?.(extra.raw, extra.addr, extra.port);
+        break;
+      case "accepted":
+        this.sockets.set(extra.conn_id, {
+          buffer: [],
+          onData: null,
+          onClose: null,
+        });
+        sock.onAccept?.(extra.conn_id, extra.remote);
+        break;
+      case "closed":
+        sock.onClose?.();
+        this.sockets.delete(id);
+        break;
+      case "error":
+        sock.reject?.(new Error(extra.msg));
+        this.sockets.delete(id);
+        break;
+      case "denied":
+        sock.reject?.(new Error(extra.msg));
+        this.sockets.delete(id);
+        break;
+    }
+  }
+
+  _dispatchResolve(id, addrs) {
+    const entry = this._resolves.get(id);
+    if (entry) {
+      entry.resolve(addrs);
+      this._resolves.delete(id);
+    }
+  }
+
+  // ── JSON event handler ───────────────────────────────
+
   _handleEvent(ev) {
+    if (ev.ev === "resolved") {
+      this._dispatchResolve(ev.id, ev.addrs);
+      return;
+    }
+
     const sock = this.sockets.get(ev.id);
     if (!sock) return;
 
@@ -102,6 +420,9 @@ export class WasmnetClient {
       case "listening":
         sock.resolve({ id: ev.id, port: ev.port });
         break;
+      case "udp_bound":
+        sock.resolve({ id: ev.id, port: ev.port });
+        break;
       case "data": {
         const decoded = this._decodeBinary(ev.data);
         if (sock.onData) {
@@ -111,8 +432,17 @@ export class WasmnetClient {
         }
         break;
       }
+      case "data_from": {
+        const decoded = this._decodeBinary(ev.data);
+        sock.onDataFrom?.(decoded, ev.addr, ev.port);
+        break;
+      }
       case "accepted":
-        this.sockets.set(ev.conn_id, { buffer: [], onData: null, onClose: null });
+        this.sockets.set(ev.conn_id, {
+          buffer: [],
+          onData: null,
+          onClose: null,
+        });
         sock.onAccept?.(ev.conn_id, ev.remote);
         break;
       case "closed":
@@ -131,9 +461,13 @@ export class WasmnetClient {
   }
 
   _handleClose() {
-    for (const [id, sock] of this.sockets) {
+    for (const [, sock] of this.sockets) {
       sock.onClose?.();
     }
     this.sockets.clear();
+    for (const [, entry] of this._resolves) {
+      entry.reject?.(new Error("connection closed"));
+    }
+    this._resolves.clear();
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wasmnet",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Browser client for wasmnet — networking proxy for WASM",
   "type": "module",
   "main": "dist/wasmnet-client.js",