Merge pull request #14 from chipmk/feat/bridge

Bridge interface

Author: gregnr

README.md

@@ -4,8 +4,9 @@
 
 ## Features
 
-- **Portable:** User-space network stack implemented on top of [`lwIP` + WASM](#why-lwip)
+- **Portable:** User-space network stack built on [`lwIP` + WASM](#why-lwip)
 - **Tun/Tap:** L3 and L2 hooks using virtual [`TunInterface`](#tun-interface) and [`TapInterface`](#tap-interface)
+- **Bridge:** Create a virtual switch/LAN by [`bridging`](#bridge-interface) multiple interfaces together
 - **TCP API:** Establish TCP connections over the virtual network stack using [clients](#connecttcp) and [servers](#listentcp)
 - **UDP API:** Send and receive UDP datagrams over the virtual network stack using [sockets](#openudp)
 - **Cross platform**: Built on web standard APIs (`ReadableStream`, `WritableStream`, etc)
@@ -152,19 +153,22 @@ for await (const connection of listener) {
 
 For more info, see [`TcpListener`](#tcplistener).
 
+The above example connects a single VM to the `NetworkStack`. If you wish to connect multiple VMs together on a shared LAN (ie. a virtual switch), you can create a [`BridgeInterface`](#bridge-interface) to join multiple tap interfaces together.
+
 ## Network interfaces
 
-3 types of interfaces are available:
+4 types of interfaces are available:
 
 - [Loopback](#loopback-interface): Loop packets back onto itself (ie. `localhost`)
 - [Tun](#tun-interface): Hook into IP packets (L3)
 - [Tap](#tap-interface): Hook into ethernet frames (L2)
+- [Bridge](#bridge-interface): Bridge multiple tap interfaces together to create a virtual switch
 
-These interfaces are designed to resemble their counterparts in a traditional host network stack.
+These interfaces are designed to resemble their counterparts in a real network stack.
 
 ### Loopback interface
 
-A loopback interface simply forwards packets back on to itself. It's akin to 127.0.0.1 (`localhost`) on a traditional network stack.
+A loopback interface simply forwards packets back on to itself. It's akin to 127.0.0.1 (`localhost`) on a typical network stack.
 
 ```ts
 const loopbackInterface = await stack.createLoopbackInterface({
@@ -193,8 +197,6 @@ const connection = await stack.connectTcp({
 });
 ```
 
-You can create as many loopback interfaces as you wish.
-
 ### Tun interface
 
 A tun interface hooks into inbound and outbound IP packets (L3).
@@ -255,15 +257,12 @@ const connection = await stack.connectTcp({
 ...
 ```
 
-You can create as many tun interfaces as you wish.
-
 ### Tap interface
 
 A tap interface hooks into inbound and outbound ethernet frames (L2).
 
 ```ts
 const tapInterface = await stack.createTapInterface({
-  mac: '01:23:45:67:89:ab',
   ip: '196.168.1.1/24',
 });
 ```
@@ -326,11 +325,71 @@ const connection = await stack.connectTcp({
 ...
 ```
 
-You can create as many tap interfaces as you wish.
+Note that `mac` and `ip` are optional parameters for `createTapInterface()`. If you don't provide a MAC address, a random one will be generated. If you don't provide an IP address, the interface will not respond to ARP requests or send ARP requests for unknown IP addresses. Typically you would only omit the IP address if you are using the tap interface as part of a [bridge](#bridge-interface).
+
+### Bridge interface
+
+A bridge interface bridges two or more tap interfaces together into a single logical interface with its own MAC and IP address. It operates at the ethernet level (L2) and will automatically forward frames between the interfaces based on the destination MAC address.
+
+```ts
+const port1 = await stack.createTapInterface();
+const port2 = await stack.createTapInterface();
+
+const bridge = await stack.createBridgeInterface({
+  ports: [port1, port2],
+  ip: '192.168.1.1/24',
+});
+```
+
+A bridge is what you would use to connect multiple VMs together into a virtual LAN.
+
+```ts
+import { createV86NetworkStream } from '@tcpip/v86';
+
+// ...
+
+const vm1 = new V86();
+const vm2 = new V86();
+const vm1Nic = createV86NetworkStream(vm1);
+const vm2Nic = createV86NetworkStream(vm2);
+
+const port1 = await stack.createTapInterface();
+const port2 = await stack.createTapInterface();
+
+// Connect port1 to vm1
+port1.readable.pipeTo(vm1Nic.writable);
+vm1Nic.readable.pipeTo(port1.writable);
+
+// Connect port2 to vm2
+port2.readable.pipeTo(vm2Nic.writable);
+vm2Nic.readable.pipeTo(port2.writable);
+
+// Bridge the two ports together
+const bridge = await stack.createBridgeInterface({
+  ports: [port1, port2],
+  ip: '192.168.1.1/24',
+});
+```
+
+In the above example, `vm1` and `vm2` are attached together via a shared LAN. We treat the tcpip.js stack as the virtual router/switch where each VM connects to their own [tap interface](#tap-interface) (`port1` and `port2`) which are then bridged together. The bridge interface has its own MAC and IP address (`192.168.1.1`), representing the address of the virtual router. This follows the exact same bridging pattern that a physical router would in a real network.
+
+Notice that we intentionally don't set IP addresses on the tap interfaces - they are only used to forward ethernet frames to/from the bridge. The bridge interface itself is where we set the IP address that the VMs can communicate with.
+
+This allows you to, for example, host a TCP server on the router itself in order to communicate with the VMs from JavaScript. You would simply create a TCP server on the stack like so:
+
+```ts
+const listener = await stack.listenTcp({
+  port: 80,
+});
+```
+
+The server would be accessible to any VM connected to the bridge via `192.168.1.1:80`. For more information on TCP, see the [TCP API](#tcp-api).
+
+Note that `BridgeInterface` does not expose its own `readable` or `writable` stream - instead you would send and receive frames through each `TapInterface` port that is part of the bridge.
 
 ### Other interfaces
 
-Looking for another type of interface? See [Future plans](#future-plans).
+Looking for another type of network interface? See [Future plans](#future-plans).
 
 ### Removing interfaces
 
@@ -591,7 +650,6 @@ _Background:_ Vite optimizes dependencies during development to improve build ti
 - [ ] DNS API
 - [ ] mDNS API
 - [ ] Hosts file
-- [ ] Bridge interface
 - [ ] Experimental Wireguard interface
 - [ ] Node.js net polyfill
 - [ ] Deno net polyfill

packages/tcpip/src/bindings/base.ts

@@ -20,8 +20,9 @@ export abstract class Bindings<Imports, Exports> {
     return new UniquePointer(this.exports.malloc(size), this.exports.free);
   }
 
-  copyToMemory(data: Uint8Array) {
-    const length = data.length;
+  copyToMemory(data: ArrayBuffer) {
+    const bytes = new Uint8Array(data);
+    const length = bytes.length;
     const pointer = this.smartMalloc(length);
 
     const memoryView = new Uint8Array(
@@ -30,7 +31,7 @@ export abstract class Bindings<Imports, Exports> {
       length
     );
 
-    memoryView.set(data);
+    memoryView.set(bytes);
 
     return pointer;
   }

packages/tcpip/src/bindings/bridge-interface.ts

@@ -0,0 +1,79 @@
+import { serializeMacAddress, type MacAddress } from '../protocols/ethernet.js';
+import { serializeIPv4Cidr, type IPv4Cidr } from '../protocols/ipv4.js';
+import type { Pointer } from '../types.js';
+import { generateMacAddress } from '../util.js';
+import { Bindings } from './base.js';
+import { tapInterfaceHooks, type TapInterface } from './tap-interface.js';
+
+type BridgeInterfaceHandle = Pointer;
+
+export type BridgeImports = {};
+
+export type BridgeExports = {
+  create_bridge_interface(
+    macAddress: Pointer,
+    ipAddress: Pointer,
+    netmask: Pointer,
+    ports: Pointer,
+    ports_length: number
+  ): BridgeInterfaceHandle;
+  remove_bridge_interface(handle: BridgeInterfaceHandle): void;
+};
+
+export class BridgeBindings extends Bindings<BridgeImports, BridgeExports> {
+  interfaces = new Map<BridgeInterfaceHandle, BridgeInterface>();
+
+  imports = {};
+
+  async create(options: BridgeInterfaceOptions) {
+    const macAddress = options.mac
+      ? serializeMacAddress(options.mac)
+      : generateMacAddress();
+
+    const { ipAddress, netmask } = options.ip
+      ? serializeIPv4Cidr(options.ip)
+      : {};
+
+    using macAddressPtr = this.copyToMemory(macAddress);
+    using ipAddressPtr = ipAddress ? this.copyToMemory(ipAddress) : undefined;
+    using netmaskPtr = netmask ? this.copyToMemory(netmask) : undefined;
+    const portHandles = new Uint32Array(
+      options.ports.map((port) =>
+        Number(tapInterfaceHooks.getOuter(port).handle)
+      )
+    );
+
+    using portHandlesPtr = this.copyToMemory(portHandles.buffer);
+
+    const handle = this.exports.create_bridge_interface(
+      macAddressPtr,
+      ipAddressPtr ?? 0,
+      netmaskPtr ?? 0,
+      portHandlesPtr,
+      options.ports.length
+    );
+
+    const bridgeInterface = new BridgeInterface();
+    this.interfaces.set(handle, bridgeInterface);
+
+    return bridgeInterface;
+  }
+
+  async remove(bridgeInterface: BridgeInterface) {
+    for (const [handle, loopback] of this.interfaces.entries()) {
+      if (loopback === bridgeInterface) {
+        this.exports.remove_bridge_interface(handle);
+        this.interfaces.delete(handle);
+        return;
+      }
+    }
+  }
+}
+
+export type BridgeInterfaceOptions = {
+  ports: TapInterface[];
+  mac?: MacAddress;
+  ip?: IPv4Cidr;
+};
+
+export class BridgeInterface {}

packages/tcpip/src/bindings/loopback-interface.ts

@@ -30,14 +30,16 @@ export class LoopbackBindings extends Bindings<
   };
 
   async create(options: LoopbackInterfaceOptions) {
-    const { ipAddress, netmask } = serializeIPv4Cidr(options.ip);
+    const { ipAddress, netmask } = options.ip
+      ? serializeIPv4Cidr(options.ip)
+      : {};
 
-    using ipAddressPtr = this.copyToMemory(ipAddress);
-    using netmaskPtr = this.copyToMemory(netmask);
+    using ipAddressPtr = ipAddress ? this.copyToMemory(ipAddress) : undefined;
+    using netmaskPtr = netmask ? this.copyToMemory(netmask) : undefined;
 
     const handle = this.exports.create_loopback_interface(
-      ipAddressPtr,
-      netmaskPtr
+      ipAddressPtr ?? 0,
+      netmaskPtr ?? 0
     );
 
     const loopbackInterface = this.interfaces.get(handle);
@@ -61,6 +63,6 @@ export class LoopbackBindings extends Bindings<
 }
 
 export type LoopbackInterfaceOptions = {
-  ip: IPv4Cidr;
+  ip?: IPv4Cidr;
 };
 export class LoopbackInterface {}

packages/tcpip/src/bindings/tap-interface.ts

@@ -1,25 +1,28 @@
-import { Bindings } from './base.js';
+import { LwipError } from '../lwip/errors.js';
 import { serializeMacAddress, type MacAddress } from '../protocols/ethernet.js';
 import { serializeIPv4Cidr, type IPv4Cidr } from '../protocols/ipv4.js';
 import type { Pointer } from '../types.js';
 import {
   ExtendedReadableStream,
   fromReadable,
+  generateMacAddress,
   Hooks,
   nextMicrotask,
 } from '../util.js';
+import { Bindings } from './base.js';
 
 type TapInterfaceHandle = Pointer;
 
 type TapInterfaceOuterHooks = {
+  handle: TapInterfaceHandle;
   sendFrame(frame: Uint8Array): void;
 };
 
 type TapInterfaceInnerHooks = {
   receiveFrame(frame: Uint8Array): void;
 };
 
-const tapInterfaceHooks = new Hooks<
+export const tapInterfaceHooks = new Hooks<
   TapInterface,
   TapInterfaceOuterHooks,
   TapInterfaceInnerHooks
@@ -45,7 +48,9 @@ export type TapExports = {
     handle: TapInterfaceHandle,
     frame: Pointer,
     length: number
-  ): void;
+  ): number;
+  enable_tap_interface(handle: TapInterfaceHandle): void;
+  disable_tap_interface(handle: TapInterfaceHandle): void;
 };
 
 export class TapBindings extends Bindings<TapImports, TapExports> {
@@ -56,9 +61,18 @@ export class TapBindings extends Bindings<TapImports, TapExports> {
       const tapInterface = new TapInterface();
 
       tapInterfaceHooks.setOuter(tapInterface, {
+        handle,
         sendFrame: (frame) => {
           const framePtr = this.copyToMemory(frame);
-          this.exports.send_tap_interface(handle, framePtr, frame.length);
+          const result = this.exports.send_tap_interface(
+            handle,
+            framePtr,
+            frame.length
+          );
+
+          if (result !== LwipError.ERR_OK) {
+            throw new Error(`failed to send frame: ${result}`);
+          }
         },
       });
 
@@ -89,17 +103,22 @@ export class TapBindings extends Bindings<TapImports, TapExports> {
   };
 
   async create(options: TapInterfaceOptions) {
-    const macAddress = serializeMacAddress(options.mac);
-    const { ipAddress, netmask } = serializeIPv4Cidr(options.ip);
+    const macAddress = options.mac
+      ? serializeMacAddress(options.mac)
+      : generateMacAddress();
+
+    const { ipAddress, netmask } = options.ip
+      ? serializeIPv4Cidr(options.ip)
+      : {};
 
     using macAddressPtr = this.copyToMemory(macAddress);
-    using ipAddressPtr = this.copyToMemory(ipAddress);
-    using netmaskPtr = this.copyToMemory(netmask);
+    using ipAddressPtr = ipAddress ? this.copyToMemory(ipAddress) : undefined;
+    using netmaskPtr = netmask ? this.copyToMemory(netmask) : undefined;
 
     const handle = this.exports.create_tap_interface(
       macAddressPtr,
-      ipAddressPtr,
-      netmaskPtr
+      ipAddressPtr ?? 0,
+      netmaskPtr ?? 0
     );
 
     const tapInterface = this.interfaces.get(handle);
@@ -123,8 +142,8 @@ export class TapBindings extends Bindings<TapImports, TapExports> {
 }
 
 export type TapInterfaceOptions = {
-  mac: MacAddress;
-  ip: IPv4Cidr;
+  mac?: MacAddress;
+  ip?: IPv4Cidr;
 };
 
 export class TapInterface {
@@ -147,7 +166,7 @@ export class TapInterface {
           throw new Error('readable stream not initialized');
         }
 
-        this.#readableController?.enqueue(frame);
+        this.#readableController.enqueue(frame);
       },
     });
 
@@ -164,7 +183,11 @@ export class TapInterface {
 
     this.writable = new WritableStream({
       write: (packet) => {
-        tapInterfaceHooks.getOuter(this).sendFrame(packet);
+        try {
+          tapInterfaceHooks.getOuter(this).sendFrame(packet);
+        } catch (err) {
+          console.error('tap interface send failed', err);
+        }
       },
     });
   }