# clusterduck

Latest version **0.1.110** (published 2021-05-21) · GPL-3.0-only license · 0 weekly downloads

## Install

```sh
npm install clusterduck
pnpm add clusterduck
yarn add clusterduck
bun add clusterduck
```

Provides the command `clusterduck`.

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.1.110 |
| Published | 2021-05-21 |
| First published | 2021-03-09 |
| Weekly downloads | 0 |
| License | GPL-3.0-only |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 36 |
| Unpacked size | 159.1 KB |
| Known vulnerabilities | 0 (+11 in 4 direct dependencies) |
| Install scripts | yes |
| Author | Vasily Zorin |
| Maintainers | kakserpom |
| Keywords | clustering, monitoring, balancing, balancer, raft |

## Links

- npm: https://www.npmjs.com/package/clusterduck
- Repository: https://github.com/kakserpom/clusterduck
- Homepage: https://npmjs.com/package/clusterduck
- Issues: https://github.com/kakserpom/clusterduck/issues
- npm.io page: https://npm.io/package/clusterduck

## Dependencies (36)

- [md5](https://npm.io/package/md5.md) ^2.3.0
- [ora](https://npm.io/package/ora.md) ^5.3.0
- [sha3](https://npm.io/package/sha3.md) ^2.1.4
- [uuid](https://npm.io/package/uuid.md) ^8.3.2
- [chalk](https://npm.io/package/chalk.md) ^4.1.0
- [yargs](https://npm.io/package/yargs.md) ^16.2.0
- [is-obj](https://npm.io/package/is-obj.md) ^2.0.0
- [jayson](https://npm.io/package/jayson.md) ^3.4.4
- [fastify](https://npm.io/package/fastify.md) ^3.14.1
- [js-yaml](https://npm.io/package/js-yaml.md) ^4.0.0
- [treeify](https://npm.io/package/treeify.md) ^1.1.0
- [axon-tls](https://npm.io/package/axon-tls.md) ^2.2.1
- [dot-prop](https://npm.io/package/dot-prop.md) ^6.0.1
- [hashring](https://npm.io/package/hashring.md) ^3.2.0
- [majority](https://npm.io/package/majority.md) ^1.0.3
- [node-pty](https://npm.io/package/node-pty.md) ^0.10.1
- [deep-copy](https://npm.io/package/deep-copy.md) ^1.4.2
- [deep-diff](https://npm.io/package/deep-diff.md) ^1.0.2
- [is-scalar](https://npm.io/package/is-scalar.md) ^1.0.2
- [clone-deep](https://npm.io/package/clone-deep.md) ^4.0.1
- [diagnostics](https://npm.io/package/diagnostics.md) ^2.0.2
- [shell-quote](https://npm.io/package/shell-quote.md) ^1.7.2
- [tmp-promise](https://npm.io/package/tmp-promise.md) ^3.0.2
- [ensure-array](https://npm.io/package/ensure-array.md) ^1.0.0
- [pretty-bytes](https://npm.io/package/pretty-bytes.md) ^5.6.0
- [eventemitter2](https://npm.io/package/eventemitter2.md) ^6.4.4
- [patch-package](https://npm.io/package/patch-package.md) ^6.4.7
- [parse-duration](https://npm.io/package/parse-duration.md) ^0.4.4
- [promise-timeout](https://npm.io/package/promise-timeout.md) ^1.3.0
- [liferaft-patched](https://npm.io/package/liferaft-patched.md) ^1.0.0
- [daemonize-process](https://npm.io/package/daemonize-process.md) ^3.0.0
- [fastify-websocket](https://npm.io/package/fastify-websocket.md) ^3.1.0
- [throttle-callback](https://npm.io/package/throttle-callback.md) ^1.1.0
- [write-file-atomic](https://npm.io/package/write-file-atomic.md) ^3.0.3
- [fastify-basic-auth](https://npm.io/package/fastify-basic-auth.md) ^1.0.1
- [json-to-pretty-yaml](https://npm.io/package/json-to-pretty-yaml.md) ^1.2.2

## Recent versions

- 0.1.110 (latest) — 2021-05-21
- 0.1.109 — 2021-04-28
- 0.1.108 — 2021-04-26
- 0.1.107 — 2021-04-26
- 0.1.106 — 2021-04-25
- 0.1.105 — 2021-04-25
- 0.1.104 — 2021-04-24
- 0.1.103 — 2021-04-24
- 0.1.102 — 2021-04-22
- 0.1.101 — 2021-04-22
- 0.1.100 — 2021-04-22
- 0.1.99 — 2021-04-21
- 0.1.98 — 2021-04-21
- 0.1.97 — 2021-04-21
- 0.1.96 — 2021-04-21
- … 93 more at https://npm.io/package/clusterduck/versions

## README

<img src="https://raw.githubusercontent.com/kakserpom/clusterduck/master/clusterduck-dashboard/public/clusterduck.png" width=220 align=left />

clusterduck
=======
[![total downloads of clusterduck](https://img.shields.io/npm/dt/clusterduck.svg)](https://www.npmjs.com/package/clusterduck)
[![clusterduck's License](https://img.shields.io/npm/l/clusterduck.svg)](https://www.npmjs.com/package/clusterduck)
[![latest version of clusterduck](https://img.shields.io/npm/v/clusterduck.svg)](https://www.npmjs.com/package/clusterduck)

*A better way to supervise your clusters and services.*
<br /><br />
*The project is recently hatched and in the stage of active development.*

**Clusterduck** is a robust solution for real-time distributed monitoring and self-healing clustering.

- **[Raft] consensus algorithm. Ducks love them rafts 😉**
  [liferaft] is running over a robust TLS transport with **peer discovery** and **HMAC-based authentication**.


- **Health checks, real-time and voting-based.**


- **Self-healing clusters.** When the number of active nodes in a cluster falls below a given threshold, new nodes will
  be started automatically on the least loaded server(s) in a split second.
  **Spare pools are supported.**


- **Events and triggers**
  Just about everything is an event that you can hook up your trigger to.


- **KISS.**
  Hacking up your own plugin is definitely not a rocket science.

### Featured extensions

🚀 [clusterduck-dashboard](https://www.npmjs.com/package/clusterduck-dashboard) — A full-fledged dashboard built with **React** and
**Websocket**.

<img src="https://cdn.cdnlogo.com/logos/r/3/redis.svg" width=20 style="display:inline"></img> [clusterduck-redis](https://www.npmjs.com/package/clusterduck-redis)
— Redis health checks and **envoy**-based balancing

🚀 [clusterduck-http](https://www.npmjs.com/package/clusterduck-http) — HTTP/Websocket health checks and **haproxy/nginx**
support.

## Table Of Contents

- [Installation](#installation)
- [Command-line interface](#command-line)
- [Configuration](#configuration)
- [Events](#events)
    - [Node events](#node-events)
    - [Cluster events](#cluster-events)
- [Transports](#transports)

## Installation

*Node 15.x is recommended.*

```bash
npm i -g clusterduck
```

Alternatively, you can clone the repo and link the dependencies which is useful for development purposes:

```bash
git clone git@github.com:kakserpom/clusterduck.git
cd clusterduck
node link
```

### TLS

If you want to enable TLS for Raft, run this to generate certificates:

`clusterduck gen-tls`

## Command-line interface

Run the  `clusterduck` command to see if it all works for you.

If you want to daemonize it, run `clusterduck -d`

If you want to stop a running daemon, run `clusterduck stop`

For debugging purposes use `DEBUG` environmental variable:
`DEBUG=* clusterduck`

## Configuration

The default config file path is `/etc/clusterduck/clusterduck.yaml`

### Clusters

Let's define a Redis cluster named `my_redis_cluster`:

```yaml
clusters:
  
  my_redis_cluster:
    type: clusterduck-redis
```

### Nodes

Then let's define some nodes:

```yaml
    # List of nodes
    nodes:
      - addr: 127.0.0.1:6379
      - addr: 127.0.0.1:6380
```

*Note that you can omit this altogether if you want to only add nodes dynamically.*

### Health checks

Now let's set up a simple __health check__.

```yaml
    health_checks:
      - type: basic
        timeout: 1s
        interval: 10s
        interval_after_fail: 1s
        commands:
          - [ 'SET', 'x', 'y' ]
```

*Now every 10 secs each node in the cluster will get checked on. If the check fails, a retry happens after 1 sec.*

### Triggers

Now let's live export the list of active nodes:

```yaml
    triggers:
      - on: [ active ]
        do:
          - type: shell
            cwd: /tmp
            commands:
              - "echo $nodes_active_addrs > active_nodes.json"
```

*This will make sure that `/tmp/nodes_list` always contains a current list of alive nodes*.

## Events

### Cluster events

Event               | Description
--------------------|------------------------------------------------------
`changed`             | Set of nodes has changed

### Node events

Event               | Description
--------------------|------------------------------------------------------
`state`             | Node state has changed

## Transports

```yaml
transports:
````

### Raft

```yaml
  - type: raft
    address: tls://127.0.0.1:9911
    bootstrap: [ tls://127.0.0.1:9910 ]
```

Parameter           | Description
--------------------|------------------------------------------------------
`address` *         | Address to listen
`tls`               | Path pattern to key/cert files. Default is `clusterduck.%s` (relative to the config file directory)
`bootstrap`         | List of node addresses to connect with.

> Clusterduck instances will exchange peers and update `bootstrap` accordingly, but initial address is necessary.

### HTTP

```yaml
  - type: http
    listen: 8880
```

Parameter           | Description
--------------------|------------------------------------------------------
`listen`            | Port to listen

## Roadmap

- CLI
- Live config updates (i.e. more Commands)
- REST API

### Transports

- [express](https://www.npmjs.com/package/express)
- [jayson](https://www.npmjs.com/package/jayson), [jayson-promise](https://www.npmjs.com/package/jayson-promise)

[Raft]: https://ramcloud.stanford.edu/raft.pdf

[Liferaft]: https://github.com/unshiftio/liferaft

---
_Source: https://npm.io/package/clusterduck · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._