The documentation has moved as well: https://danclay.github.io/wumpus-navy/
A spin-off of eris-sharder and megane with services and configurable logging.
For detailed documentation check the docs.
eris-fleet currently supports Eris v0.16.x.
- Clustering across cores
- Sharding
- Recalculate shards with minimal downtime
- Update a bot with minimal downtime using soft restarts
- Customizable logging
- Fetch data from across clusters easily
- Services (non-eris workers)
- IPC to communicate between clusters, other clusters, and services
- Detailed stats collection
- Soft cluster and service restarts where the old worker is killed after the new one is ready
- Graceful shutdowns
- Central request handler
- Central data store
- Can use a modified version of Eris
- Concurrency support
A very basic diagram:
If you still have questions, you can join the support server on Discord: Discord server
Run npm install eris-fleet or with yarn: yarn add eris-fleet.
To use a less refined, but more up-to-date branch, use npm install danclay/eris-fleet#dev or yarn add danclay/eris-fleet#dev. Documentation for the dev branch.
Some working examples are in test/.
| Term | Description |
|---|---|
| "fleet" | All the components below |
| "admiral" | A single sharding manager |
| "worker" | A worker for node clustering |
| "cluster" | A worker containing Eris shards |
| "service" | A worker that does not contain Eris shards, but can interact with clusters |
To get started, you will need at least 2 files:
- Your file which will create the fleet. This will be called "index.js" for now.
- Your file containing your bot code. This will be called "bot.js" for now. This file will extend
BaseClusterWorker
In the example below, the variable options is passed to the admiral. Read the docs for what options you can pass.
Here is an example of index.js:
const { isMaster } = require('cluster');
const { Fleet } = require('eris-fleet');
const path = require('path');
const { inspect } = require('util');
require('dotenv').config();
const options = {
path: path.join(__dirname, "./bot.js"),
token: process.env.token
}
const Admiral = new Fleet(options);
if (isMaster) {
// Code to only run for your master process
Admiral.on('log', m => console.log(m));
Admiral.on('debug', m => console.debug(m));
Admiral.on('warn', m => console.warn(m));
Admiral.on('error', m => console.error(inspect(m)));
// Logs stats when they arrive
Admiral.on('stats', m => console.log(m));
}This creates a new Admiral that will manage bot.js running in other processes. More details
The following is an example of bot.js. Read the IPC docs for what you can access and do with clusters.
const { BaseClusterWorker } = require('eris-fleet');
module.exports = class BotWorker extends BaseClusterWorker {
constructor(setup) {
// Do not delete this super.
super(setup);
this.bot.on('messageCreate', this.handleMessage.bind(this));
// Demonstration of the properties the cluster has (Keep reading for info on IPC):
this.ipc.log(this.workerID); // ID of the worker
this.ipc.log(this.clusterID); // The ID of the cluster
}
async handleMessage(msg) {
if (msg.content === "!ping" && !msg.author.bot) {
this.bot.createMessage(msg.channel.id, "Pong!");
}
}
handleCommand(dataSentInCommand) {
// Optional function to return data from this cluster when requested
return "hello!"
}
shutdown(done) {
// Optional function to gracefully shutdown things if you need to.
done(); // Use this function when you are done gracefully shutting down.
}
}Make sure your bot file extends BaseClusterWorker! The bot above will respond with "Pong!" when it receives the command "!ping".
You can create services for your bot. Services are workers which do not interact directly with Eris. Services are useful for processing tasks, a central location to get the latest version of languages for your bot, custom statistics, and more! Read the IPC docs for what you can access and do with services. Note that services always start before the clusters. Clusters will only start after all the services have started. More details
To add a service, add the following to the options you pass to the fleet:
const options = {
// Your other options...
services: [{name: "myService", path: path.join(__dirname, "./service.js")}]
}Add a new array element for each service you want to register. Make sure each service has a unique name or else the fleet will crash.
Here is an example of service.js:
const { BaseServiceWorker } = require('eris-fleet');
module.exports = class ServiceWorker extends BaseServiceWorker {
constructor(setup) {
// Do not delete this super.
super(setup);
// Run this function when your service is ready for use. This MUST be run for the worker spawning to continue.
this.serviceReady();
// Demonstration of the properties the service has (Keep reading for info on IPC):
this.ipc.log(this.workerID); // ID of the worker
this.ipc.log(this.serviceName); // The name of the service
}
// This is the function which will handle commands
async handleCommand(dataSentInCommand) {
// Return a response if you want to respond
return dataSentInCommand.smileyFace;
}
shutdown(done) {
// Optional function to gracefully shutdown things if you need to.
done(); // Use this function when you are done gracefully shutting down.
}
}Make sure your service file extends BaseServiceWorker! This service will simply return a value within an object sent to it within the command message called "smileyFace". Services can be used for much more than this though. To send a command to this service, you could use this:
const reply = await this.ipc.command("myService", {smileyFace: ":)"}, true);
this.bot.createMessage(msg.channel.id, reply);This command is being sent using the IPC. In this command, the first argument is the name of the service to send the command to, the second argument is the message to send it (in this case a simple object), and the third argument is whether you want a response (this will default to false unless you specify "true"). If you want a response, you must await the command or use .then().
If you encounter an error while starting your service, run this.serviceStartingError('error here') instead of this.serviceReady(). Using this will report an error and restart the worker. Note that services always start before the clusters, so if your service keeps having starting errors your bot will be stuck in a loop. This issue may be fixed in the future from some sort of maxRestarts option, but this is currently not a functionality.
If you encounter an error when processing a command within your service, you can do the following to reject the promise:
// handleCommand function within the ServiceWorker class
async handleCommand(dataSentInCommand) {
// Rejects the promise
return {err: "Uh oh.. an error!"};
}When sending the command, you can do the following to deal with the error:
this.ipc.command("myService", {smileyFace: ":)"}, true).then((reply) => {
// A successful response
this.bot.createMessage(msg.channel.id, reply);
}).catch((e) => {
// Do whatever you want with the error
console.error(e);
});Below is more in-depth documentation.
Visit the docs for a complete list of options.
Visit the docs for a complete list of events.
The central request handler forwards Eris requests to the master process where the request is sent to a single Eris request handler instance. This helps to prevent 429 errors from occurring when you have x number of clusters keeping track of ratelimiting separately. When a response is received, it is sent back to the cluster's Eris client.
If you are using a "very large bot," Discord's special gateway settings apply. Ensure your shard count is a multiple of the number set by Discord or set options.shards and options.guildsPerShard to "auto". You may also be able to use concurrency (see below).
Eris-fleet supports concurrency by starting clusters at the same time based on your bot's max_concurrency value. The clusters are started together in groups. The max_concurrency value can be overridden with options.maxConcurrencyOverride
Visit the docs to view the Typescript interfaces.
You can choose what to log by using the whatToLog property in the options object. You can choose either a whitelist or a blacklist of what to log. You can select what to log by using an array. To possible array elements are shown on the docs. Here is an example of choosing what to log:
const options = {
// Your other options
whatToLog: {
// This will only log when the admiral starts, when clusters are ready, and when services are ready.
whitelist: ['admiral_start', 'cluster_ready', 'service_ready']
}
};Change whitelist to blacklist if you want to use a blacklist. Change the array as you wish. Errors and warnings will always be sent.
Clusters and services can use IPC to interact with other clusters, the Admiral, and services. Visit the IPC docs to view available methods.
Stats are given in this format.
You can use an extended Eris client by passing it to the Options. (see the options.customClient section).
Eris-fleet is able to use packages such as eris-additions if you desire. To do so, modify your bot file to match the following template:
// Example using eris-additions
const { Fleet } = require("eris-fleet");
const Eris = require("eris-additions")(require("eris"));
const options = {
// other options
customClient: Eris
}
const Admiral = new Fleet(options);Instead of using the file path, you can use ES Modules by passing your BotWorker class to options.BotWorker and your ServiceWorker class to ServiceWorker in the options.services array. See test/ for examples.
![dependabot-preview[bot] avatar](https://avatars.githubusercontent.com/in/2141?v=4 "dependabot-preview[bot]")
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent