udp-proxy

NOTE: This project was forked from gildean/node-udp-proxy.

UDP Proxy for Node.js version >=12.x

Supports both IPv4 and IPv6, and bridging in between (see example below).

Installation

yarn

yarn add @shnhrrsn/udp-proxy

npm

npm install @shnhrrsn/udp-proxy

udp-proxy has no dependencies beyond Node.js itself.

Usage

Example

// Let's create a DNS-proxy that proxies IPv4 udp-requests to googles IPv6 DNS-server
const proxy = require('udp-proxy')
const options = {
  address: '2001:4860:4860::8888',
  port: 53,
  ipv6: true,
  localaddress: '0.0.0.0',
  localport: 53535,
  localipv6: false,
  proxyaddress: '::0',
  timeOutTime: 10000,
}

// This is the function that creates the server, each connection is handled internally
const server = proxy.createServer(options)

// this should be obvious
server.on('listening', function (details) {
  console.log('DNS - IPv4 to IPv6 proxy }>=<{ by: ok 2012')
  console.log(
    'udp-proxy-server ready on ' +
      details.server.family +
      '  ' +
      details.server.address +
      ':' +
      details.server.port,
  )
  console.log(
    'traffic is forwarded to ' +
      details.target.family +
      '  ' +
      details.target.address +
      ':' +
      details.target.port,
  )
})

// 'bound' means the connection to server has been made and the proxying is in action
server.on('bound', function (details) {
  console.log('proxy is bound to ' + details.route.address + ':' + details.route.port)
  console.log('peer is bound to ' + details.peer.address + ':' + details.peer.port)
})

// 'message' is emitted when the server gets a message
server.on('message', function (message, sender) {
  console.log('message from ' + sender.address + ':' + sender.port)
})

// 'proxyMsg' is emitted when the bound socket gets a message and it's send back to the peer the socket was bound to
server.on('proxyMsg', function (message, sender, peer) {
  console.log('answer from ' + sender.address + ':' + sender.port)
})

// 'proxyClose' is emitted when the socket closes (from a timeout) without new messages
server.on('proxyClose', function (peer) {
  console.log('disconnecting socket from ' + peer.address)
})

server.on('proxyError', function (err) {
  console.log('ProxyError! ' + err)
})

server.on('error', function (err) {
  console.log('Error! ' + err)
})

Methods

const server = proxy.createServer( options );

• .createServer( options ) creates an instance of udp-proxy with the given options
  • options must be an object consisting of:
    • address: string (the address you want to proxy to)
      • default: 'localhost'
    • port: number (the port you want to proxy to)
      • default: 41234
    • ipv6: boolean (if the target uses IPv6)
      • default: false
    • localaddress: string (the interface-addresses to use for the server)
      • default: '0.0.0.0' ( ::0 if localipv6 is set to true)
    • localport: number (the port for the server to listen on)
      • default: 0 (random)
    • localipv6: boolean (if you want the server to use IPv6)
      • default: false
    • proxyaddress: string (if you want to set on which interface the proxy connects out)
      • default: 0.0.0.0 ( ::0 if ipv6 is set to true)
    • timeOutTime: number the time it takes for socket to time out (in ms)
      • default: 10000 (10s)
    • timeOutTime: number the time it takes for socket to time out (in ms)
      • default: 10000 (10s)
    • middleware: object apply a middleware to the proxy, see Middleware section below.
      • default: none

the proxy always connects outwards with a random port

server.close(callback) closes proxy server.

Events

server.on( 'event' , function ( args ) { });

• 'listening', details
  • details is an object with two objects:
    • target address
    • server address
• 'bound', details
  • details is an object with two objects:
    • route address
    • peer address
• 'message', message, sender
  • message is the payload from user using the proxy
  • sender is the user address
• 'proxyMsg', message, sender, peer
  • message is the answer to the message from the user
  • sender is the answerer address
  • peer is the requesting address
• 'error', err
  • in case of an error err has the error-messages
• 'proxyError', err
  • if the message could not be proxied err has the error-messages
• 'proxyClose', peer
  • when a socket is closed after no new messages in set timeout
  • peer is the address of the disconnected client
• 'close'
  • self-explanatory

address object contains:

• address: string ip-address
• family: string IPv6 or IPv4
• port: number udp-port

Middleware

Add a middleware object to the proxy to intercept any incoming or outgoing message. Use this if you need to potentially change the message content before it is relayed, or prevent it from sending altogether.

The middleware object must contain the following functions:

message( msg, sender, function next ( msg, sender ) { });

• will be invoked with every message from a peer sender to the server.
• proxy will only relay the message when nextis invoked.

proxyMsg( msg, sender, peer, function next ( msg, sender, peer ) { });

• will be invoked with every message from the server sender to a peer.
• proxy will only relay the message when nextis invoked.

Example:

The following example will block any message going from the client to the server that has length > 120.

// Following the first example, let's create a DNS-proxy that proxies IPv4 udp-requests to googles IPv6 DNS-server and provide a middleware.
const proxy = require('udp-proxy')
const options = {
  address: '2001:4860:4860::8888',
  port: 53,
  ipv6: true,
  localaddress: '0.0.0.0',
  localport: 53535,
  localipv6: false,
  proxyaddress: '::0',
  timeOutTime: 10000,
  middleware: {
    message: function (msg, sender, next) {
      // messages with longer length will not be relayed, because 'next' will not be invoked.
      if (msg.length <= 120) {
        next(msg, sender)
      }
    },
    proxyMsg: function (msg, sender, peer, next) {
      next(msg, sender, peer)
    },
  },
}

const server = proxy.createServer(options)

// ..

Tests

Tests are built with ava and can be triggered by running:

yarn test

Development

For a comprehensive end to end proxy flow, you can run proxy DNS lookups:

node dev/dns-ipv4.js # IPv4
node dev/dns-ipv6.js # IPv6