https://github.com/nicojanssens/udp-hole-puncher-js
UDP hole punching library written in JavaScript
https://github.com/nicojanssens/udp-hole-puncher-js
Last synced: 5 months ago
JSON representation
UDP hole punching library written in JavaScript
- Host: GitHub
- URL: https://github.com/nicojanssens/udp-hole-puncher-js
- Owner: nicojanssens
- License: mit
- Created: 2016-01-05T20:45:06.000Z (over 9 years ago)
- Default Branch: master
- Last Pushed: 2024-11-11T19:40:43.000Z (7 months ago)
- Last Synced: 2025-01-03T03:11:57.084Z (6 months ago)
- Language: JavaScript
- Size: 1.25 MB
- Stars: 32
- Watchers: 6
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://circleci.com/gh/MicroMinion/udp-hole-puncher-js)
[](https://npmjs.org/package/udp-hole-puncher)
# UDP Hole Puncher
## Summary
JS library implementing a UDP hole punching protocol to connect two peers located behind NAT devices. Will not work when one or both peers are located behind a symmetric NAT box. In that case, you may need a relay server + a TURN lib (like [this one](https://github.com/nicojanssens/turn-js)) to facilitate communication between both peers.
## Features
- no rendez-vous server lock in
- verifies if bidirectional communication is possible
- can be browserified (to be used in chrome and cordova apps)
## Install
```
npm install udp-hole-puncher
```
## Usage
```js
const dgram = require('dgram');
const UdpHolePuncher = require('udp-hole-puncher');
// peer's public port and address
const peer = {
port: 1234,
addr: '1.2.3.4',
};
// local port
const myPort = 5678;
// socket config
const socket = dgram.createSocket('udp4');
socket.on('error', (error) => {...} );
socket.on('message', (message, rinfo) => {...} );
socket.on('listening', () => {
// puncher config
const puncher = new UdpHolePuncher(socket);
// when connection is established, send dummy message
puncher.on('connected', () => {
const message = Buffer.from('hello');
socket.send(message, 0, message.length, peer.port, peer.addr);
});
// error handling code
puncher.on('error', (error) => {
...
});
// connect to peer (using its public address and port)
puncher.connect(peer.addr, peer.port);
});
// bind socket
socket.bind(myPort);
```
## API
### `var puncher = new UdpHolePuncher(socket, args)`
Create a new udp-hole-puncher.
`socket` must be an operational datagram socket.
`args` specifies some optional config settings, including the maximum request attempts + timeout between every request attempt (ms). Default settings are `{
maxRequestAttempts: 10,
requestTimeout: 500
}`
### `puncher.connect(addr, port)`
Try to establish a connection with a peer using its public address and port. Note that to setup bidirectional communication, both peers must simultaneously execute a connect operation (initiating the punching protocol).
### `puncher.close()`
End execution of the hole punching protocol.
## Events
### `puncher.on('connected', () => {})`
Fired when the hole punching protocol completes and both peers can reach each other.
### `puncher.on('reachable', () => {})`
Called when the other peer was able to reach this peer. No guarantee yet that bidirectional communication can be established.
### `puncher.on('timeout', () => {})`
Fired when the hole punching protocol timeouts.
### `puncher.on('error', (error) => {})`
Fired when a fatal error occurs.
## Chrome and cordova apps
```
gulp browserify [--production]
```
Puts `udp-hole-puncher.debug.js` and `udp-hole-puncher.min.js` in `build` folder. Can be used in chrome and cordova app. When integrating udp-hole-puncher in a cordova app, use `cordova-plugin-chrome-apps-sockets-udp`:
```
cordova plugin add https://github.com/MobileChromeApps/cordova-plugin-chrome-apps-sockets-udp
```
## Examples
See examples directory. Note that both peers should _not_ be located behind the same NAT device. To test this lib, deploy one peer on your home network and another one outside of that network -- for instance on a public cloud infrastructure.
To run this test example, execute the following cmd on two machines A and B:
```
server-A$ npm run-script peer -- --bind=12345 --addr= --port=23456
server-B$ npm run-script peer -- --bind=23456 --addr= --port=12345
```