Nashville Plays Music


    1.0.1 • Public • Published


    When you need to transmit data over UDP you face its limitations: data must be transmitted in small chunks to fit in the MTU, packets could be lost with no notification, come duplicated or in the wrong order.

    uTP (micro transport protocol) was invented by torrent people to safely transmit files over UDP. Basically, it adds TCP features to UDP: lost packets are automatically retransmitted, the order is guaranteed, duplicates rejected.

    This library implements uTP over UDP so when connected you receive a socket object which behaves much like a Node.js tcp socket. It emits 'data' when receiving data, it has .write() method for you to send a Buffer. Much like TCP socket, this is a Node.js stream.

    The library, however, might not be compatible with other uTP implementations (so you need to use this very same library on both the peers) because it adds the following feature: the same instance of a class can be used both as a server and a client at the same time on the same port. So you can create a Node, bind it to a port and at the same time start listening for incoming connections and also make outgoing connections from it.

    General usage example

    npm install --save utp-punch
    const Node = require('utp-punch');
    let server = new Node(socket => {
      console.log('server: socket connected');
      socket.on('data', data => {
        console.log(`server: received '${data.toString()}'`);
      socket.on('end', () => {
        console.log('server: socket disconnected');
        server.close(); // this is how you terminate node
    server.bind(20000, ''); // bind to port 20000
    server.listen( // run
      () => console.log('server: ready')
    let client = new Node();
    client.bind(); // bind to any port
    client.connect(20000, '', socket => {
      console.log('client: socket connected');
      socket.on('data', data => console.log(`client: received '${data.toString()}'`));
      socket.on('end', () => {
        console.log('client: socket disconnected');
        client.close(); // this is how you terminate node

    UDP hole punching

    Another technique which is used here is UDP hole punching.

    When server and/or client are behind NAT they normally do not have an Internet IP address to bind to in order to receive incoming connections.

    UDP hole punching tricks firewalls into opening a temporary hole for its user, so a port on the NAT device becomes bound to the port of the server/client inside the LAN.

    In order for it to work both server and client must use a third-party server to find out each other's NATed IP addresses and to coordinate punching attempt (it must be done simultaneously on the server and on the client).

    But when the connection is established the third-party server is no longer needed and it is never used as a relay, all the data is transmitted directly between this NATed server and client.

    UDP hole punching example

    const Node = require('utp-punch');
    let server = new Node();
    let client = new Node();
    client.bind(30000); // client needs dedicated port
                        // just as the server
    // both server and client must contact a third party server
    // which will report their peer NATed address and port to them
    let serverAddress, serverPort;
    let clientAddress, clientPort;
    // up to ten punches:
    server.punch(10, clientPort, clientAddress, success => {
      // if success is true hole is punched from our side
      // nothing to do here as the client will try
      // to connect normally when he is also successful
    client.punch(10, serverPort, serverAddress, success => {
      if (success) {
      client.connect(serverPort, serverAddress, socket => {
        // if the server had also been successful in punching
        // this will succeed
      client.on('timeout', () => {
        // if the server had failed in punching we won't be
        // able to connect

    Please see the complete hole punching example in example/ directory.

    Node class

    The same class can be used as a server or as a client, the syntax is following:

    new Node([options,][onconnection]);

    options is the following:

      bufferSize: 64, // number of packets
      mtu: 1000, // bytes excluding uTP header
      timeout: 5000, // ms
      resend: 100, // ms
      keepAlive: 1000, // ms

    onConnection will be passed single argument - the socket. This is server's incoming connections


    Getter for maximum number of connections the Node can handle


    Getter for the number of incoming connections


    Getter for the number of outgoing connections


    Returns standard Node.js UDP socket which is used under the hood.


    Bound address of the socket (the same as in Node.js UDP .address())

    .bind([port,][host,] [onBound])

    Bind to host:port and execute onBound when done

    .punch(attempts, port, [host,][callback])

    Start punching attempts to the host:port and run callback when either successful or no attempts are left. Success or failure is passed to the callback as the first, boolean parameter


    Turn this Node into a server and execute this callback when ready to accept incoming connections

    .connect(port, [host,][onconnect])

    Connect to a server Node on host:port and execute callback with the socket object as the single parameter


    Terminate all connections and the Node, run callback.

    Socket object

    Socket object passed to Node constructor and .connect() callbacks is a stream emitting 'data' when receiving data. It has the usual methods: .write(), .end(), etc.


    Original 'utp' library was created by @mafintosh in This is a rewrite in modern JavaScript with bug fixing and additional features including use as a server and a client simultaneously on the same port and UDP hole punching support.


    npm i utp-punch

    DownloadsWeekly Downloads






    Unpacked Size

    50.7 kB

    Total Files


    Last publish


    • basarevych