A simple network tunneling mechanism for Pub/Sub transports

Usage no npm install needed!

<script type="module">
  import akirozPubsubTunnel from 'https://cdn.skypack.dev/@akiroz/pubsub-tunnel';


PubSub Tunnel


A simple network tunneling mechanism for Pub/Sub transports

Tunnels traffic at layer 3 (IP) of the OSI model


See tests for a basic use case that simply uses an EventEmitter as the Pub/Sub mechanism.


  • Dependencies
    • Linux: iproute2 (Included in most modern distros)
    • Windows: WSL (Included with Windows 10)
    • MacOS: libpcap (Included in MacOS)
  • Special privileges
    • Linux: /dev/net/tun + CAP_NET_ADMIN
    • Windows: Same as Linux
    • MacOS: /dev/bpf*


On Linux: uses TUN interfaces to communicate with the host.

On MacOS: uses libpcap internally to capture/inject packets from the loopback interface.

The tunneling mechanism has 2 roles: server and client.

  1. Server subscribes to a topic and is ready for tunneling sessions
  2. Client generates a session ID (128 bit) and start forwarding packets from a preconfigured address on the loopback interface to topic prepended by the session ID
  3. Client subscribes to topic/${base64(id)} and performs NAT on received IP packets to first loopback address ( before injecting it
  4. Server upon receiving a new session ID allocates an IP in the loopback block ( in a preconfigured range and performs NAT on the IP packet to the first loopback address ( before injecting it in the interface
  5. Server starts forwarding packets from the allocated address to topic/${base64(id)}

Note that IPs in the preconfigured range on the loopback block will be reused in a LRU fasion, make sure the range is large enough such that new sessions will not override existing ones.

Network diagram