# @mimik/cluster

> cluster management for mimik microservices

Latest version **5.2.1** (published 2026-07-08) · MIT license · 0 weekly downloads

## Install

```sh
npm install @mimik/cluster
pnpm add @mimik/cluster
yarn add @mimik/cluster
bun add @mimik/cluster
```

## Health

**Score 50/100 (C)** — status: active.

Positive: esm support; no vulnerabilities.

Warnings: low downloads; no types.

## Facts

| | |
|---|---|
| Version | 5.2.1 |
| Published | 2026-07-08 |
| First published | 2018-06-29 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | ESM + CommonJS |
| Node | >=24.0.0 |
| Dependencies | 5 |
| Unpacked size | 36 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | mimik technology inc |
| Maintainers | mimik-npm-editor, hofachiang, miburger, mimikopensource, sasan.raisdana |
| Keywords | mimik, microservice, cluster |

## Links

- npm: https://www.npmjs.com/package/@mimik/cluster
- Repository: https://bitbucket.org/mimiktech/cluster
- Homepage: https://bitbucket.org/mimiktech/cluster#readme
- Issues: https://bitbucket.org/mimiktech/cluster/issues
- npm.io page: https://npm.io/package/@mimik/cluster

## Dependencies (5)

- [@mimik/oauth-helper](https://npm.io/package/@mimik/oauth-helper.md) ^4.1.3
- [@mimik/address-helper](https://npm.io/package/@mimik/address-helper.md) ^2.0.9
- [@mimik/swagger-helper](https://npm.io/package/@mimik/swagger-helper.md) ^5.0.5
- [@mimik/response-helper](https://npm.io/package/@mimik/response-helper.md) ^4.0.13
- [@mimik/sumologic-winston-logger](https://npm.io/package/@mimik/sumologic-winston-logger.md) ^2.2.4

## Recent versions

- 5.2.1 (latest) — 2026-07-08
- 5.1.4 — 2026-04-19
- 5.1.3 — 2026-03-25
- 5.1.2 — 2026-03-22
- 5.1.1 — 2026-03-19
- 5.1.0 — 2026-03-19
- 5.0.4 — 2025-09-19
- 5.0.3 — 2025-09-14
- 5.0.2 — 2025-09-14
- 5.0.1 — 2025-07-24
- 5.0.0 — 2025-07-22
- 4.0.2 — 2024-06-11
- 4.0.1 — 2024-02-15
- 4.0.0 — 2023-12-08
- 3.0.1 — 2023-12-05
- … 24 more at https://npm.io/package/@mimik/cluster/versions

## README

<a name="module_cluster"></a>

## cluster
The following environment variables are set:

| Env variable name | Description | Default | Comments |
| ----------------- | ----------- | ------- | -------- |
| REGISTRATION_STATUS | Status of the registration with mIT |  |  |
| CLUSTER_STATUS_SERVERS | Number of servers in the cluster |  |  |
| CLUSTER_STATUS_UPDATED_AT | Timestamp of the last cluster status update |  |  |
| CLUSTER_STATUS_LEASE_TIME | Lease time interval |  |  |

**Example**  
```js
import cluster from '@mimik/cluster';
```

* [cluster](#module_cluster)
    * [~cluster(config, metrics)](#module_cluster..cluster) ⇒ <code>object</code>
    * _async_
        * [~rpCluster(options)](#module_cluster..rpCluster) ⇒ <code>Promise</code>
        * [~createItResource(con, req, res)](#module_cluster..createItResource)
        * [~deleteServer(con, req, res)](#module_cluster..deleteServer)
        * [~register(correlationId, retry)](#module_cluster..register) ⇒ <code>Promise</code>
        * [~unRegister(correlationId)](#module_cluster..unRegister) ⇒ <code>Promise</code>

<a name="module_cluster..cluster"></a>

### cluster~cluster(config, metrics) ⇒ <code>object</code>
Create a cluster instance.

**Kind**: inner method of [<code>cluster</code>](#module_cluster)  
**Returns**: <code>object</code> - - An object exposing `rpCluster`, `createItResource`, `deleteServer`, `register`, and `unRegister`.  
**Requires**: <code>module:@mimik/oauth-helper</code>  

| Param | Type | Description |
| --- | --- | --- |
| config | <code>object</code> | Configuration object. Requires `cluster.management` (`'off'` disables cluster broadcasts), `cluster.timeout` (per-node request timeout), `registration.retry` (registration retry interval in ms), `serverSettings` (`id`, `type`, `port`, `basePath`, `public.location`, `ip.local`, optional `clusterStatus`), and optional `dependencies.mIT.url` (mIT base URL; `'n/a'` when absent). |
| metrics | <code>object</code> | Metrics object. Requires `HTTPRequestDuration` (the request-duration metric passed through to the underlying HTTP client). |

<a name="module_cluster..rpCluster"></a>

### cluster~rpCluster(options) ⇒ <code>Promise</code>
The response is an object with the following structure:
```javascript
{
  "data": [ 'array of all successful response payloads' ],
  "results": [
    {
      "result": (response from the underlying HTTP client),
      "server": (cluster node that produced the result)
    }
  ],
  "failures": [
    {
      "error": (error thrown for a request to a cluster node),
      "server": (cluster node that produced the error)
    }
  ]
}
```

**Kind**: inner method of [<code>cluster</code>](#module_cluster)  
**Category**: async  
**Requires**: <code>module:@mimik/sumologic-winston-logger</code>, <code>module:@mimik/oauth-helper</code>, <code>module:@mimik/response-helper</code>  
**Fulfil**: <code>object</code> - Aggregated response of the request.  

| Param | Type | Description |
| --- | --- | --- |
| options | <code>object</code> | Options for the request (similar to [axios](https://www.npmjs.com/package/axios) options). The `url` MUST be a path only; the base URL is supplied by each cluster node. If `options.token` is provided, it is augmented with `{ cluster: true }`; otherwise a `{ cluster: true }` token is attached. |

<a name="module_cluster..createItResource"></a>

### cluster~createItResource(con, req, res)
Create IT resource endpoint.

**Kind**: inner method of [<code>cluster</code>](#module_cluster)  
**Category**: async  
**Requires**: <code>module:@mimik/swagger-helper</code>, <code>module:@mimik/response-helper</code>, <code>module:@mimik/sumologic-winston-logger</code>  

| Param | Type | Description |
| --- | --- | --- |
| con | <code>object</code> | Request context (from OpenAPI). |
| req | <code>object</code> | The HTTP request. |
| res | <code>object</code> | The HTTP response. |

<a name="module_cluster..deleteServer"></a>

### cluster~deleteServer(con, req, res)
Delete server endpoint.

**Kind**: inner method of [<code>cluster</code>](#module_cluster)  
**Category**: async  
**Requires**: <code>module:@mimik/swagger-helper</code>, <code>module:@mimik/response-helper</code>  

| Param | Type | Description |
| --- | --- | --- |
| con | <code>object</code> | Request context (from OpenAPI). |
| req | <code>object</code> | The HTTP request. |
| res | <code>object</code> | The HTTP response. |

<a name="module_cluster..register"></a>

### cluster~register(correlationId, retry) ⇒ <code>Promise</code>
Register a server with mIT.

**Kind**: inner method of [<code>cluster</code>](#module_cluster)  
**Category**: async  
**Requires**: <code>module:@mimik/sumologic-winston-logger</code>, <code>module:@mimik/oauth-helper</code>, <code>module:@mimik/address-helper</code>  
**Fulfil**: <code>null</code>

Registration with mIT is retried at the interval defined by `config.registration.retry`.
When registration completes, a lease call is made to mIT at a regular interval.
The lease interval is defined by mIT; if unspecified, it defaults to 2 hours.
When cluster management is enabled, a concurrent registration is executed after
approximately 60 seconds to guarantee cluster integrity.  

| Param | Type | Description |
| --- | --- | --- |
| correlationId | <code>string</code> | Correlation ID to associate with the request. |
| retry | <code>boolean</code> | Pass `false` for the initial registration. Used internally when the module recursively invokes itself for concurrent registration (~60s after first success) to guarantee cluster integrity. |

<a name="module_cluster..unRegister"></a>

### cluster~unRegister(correlationId) ⇒ <code>Promise</code>
The returned object is:
``` javascript
{
  nbServers: "number of servers in the cluster",
  serverId: "server ID",
  errors: "optional array of errors that occurred while unregistering"
}
```

**Kind**: inner method of [<code>cluster</code>](#module_cluster)  
**Category**: async  
**Requires**: <code>module:@mimik/sumologic-winston-logger</code>, <code>module:@mimik/oauth-helper</code>  
**Fulfil**: An object containing the number of servers, the serverId, and any errors (if present).  

| Param | Type | Description |
| --- | --- | --- |
| correlationId | <code>string</code> | Correlation ID to associate with the request. |

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