Holesail Client

Join our Discord Support Server

Node.js and Bare client for connecting to a holesail-server over HyperDHT - P2P reverse proxying, no signalling server required.

npm install holesail-client

Usage

const HolesailClient = require('holesail-client')

const client = new HolesailClient({
  invite: 'hs_...' // invite string printed by the server
})

await client.ready()

console.log('proxy listening on', client.proxy.address())

Local connections made to the proxy's address are tunneled through HyperDHT to whatever the server is forwarding.

If port/host/udp are omitted, the client asks the server for them first (a lightweight DHT round trip called probing) before starting the proxy. Pass them explicitly to skip that round trip and start faster:

const client = new HolesailClient({
  invite: 'hs_...',
  port: 8989,
  host: '127.0.0.1',
  udp: false
})

Closing

await client.close()

Pausing and resuming

await client.pause() // stop accepting new tunnels, keep existing ones alive
await client.resume()

API

HolesailClient extends ready-resource - ready() and close() are both idempotent and safe to call more than once.

const client = new HolesailClient(opts)

Creates a client. Nothing happens until ready() is called.

{
  invite: '<string>',    // required - invite string generated by the server
  port: 0,               // local port to listen on. Omit to auto-detect via probe
  host: '127.0.0.1',     // local host to bind. Omit to auto-detect via probe
  udp: false,            // true for a UDP tunnel, false for TCP. Omit to auto-detect via probe
  bootstrap: [],         // optional custom HyperDHT bootstrap nodes
  logger: undefined      // optional {debug, info, warn, error} logger
}

await client.ready()

Connects to the DHT, probes the server for port/host/udp if any of them were omitted, then starts the local proxy. Resolves once client.proxy is listening.

client.on('listening')

Emitted once the local proxy is bound and accepting connections.

client.on('connect')

Emitted every time a new tunnel is dialed to the server, i.e. once per new incoming local connection.

client.info

{
  state: 'listening', // 'starting' | 'listening' | 'paused' | 'destroyed'
  port: 8989,
  host: '127.0.0.1',
  udp: false,
  invite: '<string>'
}

await client.pause()

Suspends the underlying DHT node without tearing anything down. New local connections will queue but not tunnel until resume().

await client.resume()

Resumes a paused client.

await client.close()

Closes the local proxy, destroys any open tunnels, and destroys the DHT node.

await HolesailClient.probe(invite, [dht])

Static helper. Connects to the server named by invite and asks it for its { port, host, udp } without opening a tunnel. Pass an existing DHT instance to reuse it instead of spinning up (and tearing down) a fresh one - HolesailClient itself uses this internally when port/host/udp are omitted.

License

This project is licensed under the GNU AGPL v3 license - see the LICENSE and NOTICE files.

---

Community and Support

Join our Discord Support Server for help, discussions, and updates.