holesail-server/README.md

Proxy any server peer-to-peer using Holepunching.

# Holesail Server

[Join our Discord Support Server](https://discord.gg/TQVacE7Vnj)

Holesail Server enables you to reverse proxy any local server peer-to-peer (P2P) using HyperDHT, no signalling server
required.

---

Note: V2 has breaking changes, V2 is not compatible with V1 and will break infuture.

## Installation

Install the Holesail Server module via npm:

```bash
npm install holesail-server
```

---

## Usage

### Importing the Module

Require the module in your project:

```javascript
const HolesailServer = require('holesail-server')
```

### Creating an Instance

Create a new instance of the `HolesailServer` class:

```javascript
const server = new HolesailServer()
```

### Starting the Server

Start the server using the `start` method and retrieve its public key:

```javascript
await server.start({ port: 5000, host: '127.0.0.1' }, () => {
  console.log('Server started')
  console.log(server.key)

  setTimeout(() => {
    server.destroy()
    console.log('Server destroyed')
  }, 6000)
})
```

### Using a Fixed Connection Key

Optionally, you can set a `seed` to ensure the server generates the same connection key every time:

```javascript
await server.start(
  {
    port: 5000,
    host: '127.0.0.1',
    seed: '4917816487c1822049939ff1abbf515663275105d01361bbc84fe2000e594539'
  },
  () => {
    console.log('Server started')
    console.log(server.key)

    setTimeout(async () => {
      await server.destroy()
      console.log('Server destroyed')
    }, 6000)
  }
)

// Note: seed must be a 64-character long string.
```

### Destroying the Server

Use the `destroy` method to stop the server and clean up resources:

```javascript
await server.destroy()
```

---

## API Reference

### `await server.start(options, callback)`

Starts the server

#### Parameters:

- `options` (object):
  - `port` (number, required): The port to listen on.
  - `host` (string, required): The local address to bind to. Use `"0.0.0.0"` to listen on all interfaces.
  - `seed` (string, optional): A 64-character string used to generate a consistent connection key.
  - `secure` (boolean, optional, recommended): Prevents leaking access capability to HyperDHT by listening on a
    different seed than the one needed to connect.
  - `udp` (boolean, optional): Enables UDP instead of TCP connections.

- `callback` (function): A function that is called when the server successfully starts.

---

### `server.key`

Retrieves the server's connection key. Use this key to connect to the server from a client.

---

### `server.pause()`

Pause the server.

---

### `server.resume()`

Resume the server.

---

### `server.info`

Returns an object containing server information.

---

### `await server.destroy()`

Stops the server and cleans up resources.

---

### `await put(data)`

Put a mutable record on DHT. Max size 1 KB

---

## License

Holesail Server is released under the [GPL-v3 License](https://www.gnu.org/licenses/gpl-3.0.en.html).

For more details, see the [LICENSE](https://www.gnu.org/licenses/gpl-3.0.en.html) file.

---

## Community and Support

Join our [Discord Support Server](https://discord.gg/TQVacE7Vnj) for help, discussions, and updates.