network-cluster
v1.0.4
Published
A Simple-To-Use Package For Communication Between Multiple Machines Using Network APIs
Downloads
15
Maintainers
Readme
NetworkCluster: Create Multi-Machine Network Clusters With A Simple-To-Use API
Powered by HyperExpress
Motivation
NetworkCluster aims to simplify the process of creating scalable clusters with streamlined logic. This package uses websockets under the hood to allow for consistently low latency communication between multiple machines and processes.
Installation
NetworkCluster can be installed using node package manager (npm
)
npm i network-cluster
Table Of Contents
- NetworkCluster: Create Multi-Machine Network Clusters With A Simple-To-Use API
- Powered by
HyperExpress
How To Use
NetworkCluster makes use of two components called a Provider and a Consumer to faciliate communication. A Provider can provide and thus communicate with as many consumers as the hardware can support. On the other hand, a Consumer instance can only consume and communicate with one Provider. Below are two blocks of code which demonstrate how to create a simple cluster.
Example Provider Code
const NetworkCluster = require('network-cluster');
// Create a provider instance to faciliate/manage a cluster
const Provider = new NetworkCluster.Provider({
port: 8080,
auth: {
parameters: {
key: 'SECRET_KEY' // This will authenticate incoming consumer connections
}
}
});
// Listen for incoming messages from connected consumers
Provider.on('message', (consumer, message) => {
console.log(`Consumer ${consumer.id} Sent: ${message}`);
// We can also send some message back
if(some_condition) consumer.send('SOME_REPLY');
});
Example Consumer Code
const NetworkCluster = require('network-cluster');
// Create a consumer instance to join a cluster
const Consumer = new NetworkCluster.Consumer({
host: 'IP_OF_PROVIDER_MACHINE',
port: 8080,
parameters: {
key: 'SECRET_KEY', // This is important as our provider above expects this parameter
something1: 'Some Value 1',
something2: 'Some Value 2' // You can also include other parameters as metadata
// Note! Parameters are sent as URL Parameters thus use according to URL limits
}
});
// Listen for incoming messages from provider
Consumer.on('message', (message) => {
console.log(`Provider Sent: ${message}`);
// We can also respond to the provider
if(some_condition) Provider.send('SOME_REPLY');
});
// Connect to the provider instance to initiate communication
Consumer.connect()
.then(() => {
console.log('Successfully Connected To Provider! Ready For Work!');
})
.catch((error) => {
console.log('Failed To Connect To Provider! Reason: ');
console.log(error);
});
// Send some message to provider to let it know we are ready
Provider.send('CONSUMER_READY');
Provider
Below is a breakdown of the Provider
object class generated while creating a new Provider instance.
Provider Constructor Options
port
[Number
]: Port for websocket server to listen for incoming consumer connections.- Default:
8080
.
- Default:
path
[String
]: URL path on which consumers can connect.- Default:
/connect
.
- Default:
ssl
[Object
]: SSL options to use TLS for websocket connections.key
[String
]: Path to SSL private key file to be used for SSL/TLS.- Example:
'misc/key.pm'
- Required for an SSL server.
- Example:
cert
[String
]: Path to SSL certificate file.- Example:
'misc/cert.pm'
- Required for an SSL server.
- Example:
passphrase
[String
]: Strong passphrase for SSL cryptographic purposes.- Example:
'SOME_RANDOM_PASSPHRASE'
- Required for an SSL server.
- Example:
dh_params
[String
]: Path to SSL Diffie-Hellman parameters file.- Example:
'misc/dhparam4096.pm'
- Optional for an SSL server.
- Example:
prefer_low_memory_usage
[Boolean
]: Specifies uWebsockets to prefer lower memory usage while serving SSL requests.
ws
[Object
]: Websocket server options.compressor
[Number
]: Must one of the presets fromNetworkCluster.COMPRESSORS
.- Default:
NetworkCluster.COMPRESSORS.DISABLED
- Default:
max_backpressure
[Number
]: Maximum length of backpressure before disconnecting connection.- Default:
1024 * 1024
- Default:
max_payload_length
[Number
]: Maximum payload length of incoming messages.- Default:
32 * 1024
- Default:
auth
[Object
]: Authentication options/requirements for incoming connections.parameters
[Object
]: URL parameters to send with connect/upgrade request.handler
[Function
]: Upgrade request handler. This can be used in collaboration withparameters
.- Format:
(HyperExpress.Request: request, Object: parameters) => {}
. - See HyperExpress.Request for all
request
object properties/methods. - Note: The handler can return a
Promise
which must resolve to aBoolean
verdict value.
- Format:
heartbeat
[Object
]: Ping-Pong cycle configuration.interval
[Number
]: Interval in milliseconds to cleanup inactive connections.- Default:
10 * 1000
(10 Seconds)
- Default:
max_strikes
[Number
]: Maximum number of strikes before disconnecting inactive consumer.- Default:
2
- Default:
Provider Instance Properties
| Property | Type | Description |
| :-------- | :------- | :------------------------- |
| connections
| Object
| Consumer connections represented by their unique id
. |
| port
| Number
| Port of underlying websocket server. |
| path
| String
| Path of websocket server connect route. |
| events
| EventEmitter
| Underlying instance event emitter. |
| server
| HyperExpress.Server
| Underlying instance HyperExpress server. |
Provider Instance Methods
on(String: event, Function: handler)
: Binds a handler to the underlyingEventEmitter
instance.open
: This event gets called wheneverProvider
receives a new consumer connection.- Format:
(Connection: consumer) => {}
- Format:
close
: This event gets called wheneverProvider
loses a consumer connection.- Format:
(Connection: consumer, Number: code, String: reason) => {}
- Format:
message
: This event gets called whenever a message is received from a consumer connection.- Format:
(Connection: consumer, String: message) => {}
- Format:
- See Connection for properties and methods.
set_error_handler(Function: handler)
: Sets a error handler forProvider
instance.- Format:
(Error: error) => {}
- Format:
set_debug_logger(Function: handler)
: Sets a debug logger forProvider
instance.- Format:
(String: message) => {}
- Note! Using this logger is not recommended in production.
- Format:
destroy()
: DestroysProvider
instance and cleans up underlying components.
Consumer
Below is a breakdown of the Consumer
object class generated while creating a new Consumer instance.
Consumer Constructor Options
ssl
[Boolean
]: Specifies whetherhttps
protocol should be used to create a secure SSL connection with theProvider
.- Default:
false
.
- Default:
host
[String
]: Host/IP address of theProvider
to connect.port
[Number
]: Port of theProvider
to connect.path
[String
]: Address path of theProvider
to connect.- Default:
/connect
- Note! This option should be left default unless the
Provider
was created on a different listening path.
- Default:
parameters
[Object
]: Parameters to specify when attempting to create a connection withProvider
.- Note! Any authentication values or metadata should be sent as parameters.
reconnect
[Object
]: Reconnect policy for connection dropouts.interval
[Number
]: Time in milliseconds to wait before attempting a reconnect with theProvider
.max_attempts
[Number
]: Maximum number of failed reconnect attempts before markingConsumer
instance as closed and unusable.
Consumer Properties
| Property | Type | Description |
| :-------- | :------- | :------------------------- |
| ws
| Websocket
| Underlying WebSocket object. See WebSocket for documentation. |
| events
| EventEmitter
| Underlying EventEmitter for instance. |
| in_flight
| Boolean
| Whether instance is currently connecting to Provider. |
| connected
| Boolean
| Whether instance is connected to Provider. |
| heartbeat_duration
| Number
| Expected interval between Provider heartbeat pings. |
| heartbeat_cutoff
| Number
| Maximum time in milliseconds allowed since last heart beat ping before disconnect. |
| last_heartbeat
| Number
| Timestamp in milliseconds of last heartbeat ping. |
Consumer Methods
connect()
: Initiates connection toProvider
and automatically reconnects during dropouts.- Returns a
Promise
similar toready()
method below. - Note! This method must be called once to initialize the connection cycle.
- Returns a
ready()
: Returns aPromise
which is resolved on successful connection or rejected with error on failure.set_error_handler(Function: handler)
: Sets a error handler forConsumer
instance.- Format:
(Error: error) => {}
- Format:
set_debug_logger(Function: handler)
: Sets a debug logger forConsumer
instance.- Format:
(String: message) => {}
- Note! Using this logger is not recommended in production.
- Format:
on(String: event, Function: handler)
: Binds a handler to the underlyingEventEmitter
instance.open
: This event gets emitted wheneverConsumer
connects to theProvider
.- Format:
() => {}
- Format:
disconnect
: This event gets emitted wheneverConsumer
gets disconnected from theProvider
.- Format:
(Number: code, String: reason) => {}
- Format:
message
: This event gets emitted whenever a message is received from theProvider
.- Format:
(String: message) => {}
- Format:
close
: This event gets emitted only once whenConsumer
instance has permanently disconnected/closed after exhausting reconnection policy.
once(String: event, Function: handler)
: Same ason
except only gets called once.send(String: message)
: Sends a message to theProvider
.- Returns
Boolean
based on successful message delivery.
- Returns
destroy()
: DestroysConsumer
instance and all underlying components.
Connection
Below is a breakdown of the Connection
(HyperExpress.Websocket) object made available through event emitters.
Connection Properties
| Property | Type | Description |
| :-------- | :------- | :------------------------- |
| id
| String
| Unique connection identifier (uuid v4). |
| ip
| String
| IP address of connection. |
| parameters
| Object
| Consumer parameters of connection. |
| last_ping
| Number
| Last heartbeat ping timestamp in milliseconds. |
| strikes
| Number
| Number of strikes due to missed heartbeats (pings). |
Connection Methods
See Websocket for all available methods for each Connection
instance.