diff options
Diffstat (limited to 'node_modules/discord.js/src/sharding')
| -rw-r--r-- | node_modules/discord.js/src/sharding/Shard.js | 475 | ||||
| -rw-r--r-- | node_modules/discord.js/src/sharding/ShardClientUtil.js | 291 | ||||
| -rw-r--r-- | node_modules/discord.js/src/sharding/ShardingManager.js | 335 |
3 files changed, 1101 insertions, 0 deletions
diff --git a/node_modules/discord.js/src/sharding/Shard.js b/node_modules/discord.js/src/sharding/Shard.js new file mode 100644 index 0000000..f833309 --- /dev/null +++ b/node_modules/discord.js/src/sharding/Shard.js @@ -0,0 +1,475 @@ +'use strict'; + +const EventEmitter = require('node:events'); +const path = require('node:path'); +const process = require('node:process'); +const { setTimeout, clearTimeout } = require('node:timers'); +const { setTimeout: sleep } = require('node:timers/promises'); +const { DiscordjsError, ErrorCodes } = require('../errors'); +const ShardEvents = require('../util/ShardEvents'); +const { makeError, makePlainError } = require('../util/Util'); +let childProcess = null; +let Worker = null; + +/** + * A self-contained shard created by the {@link ShardingManager}. Each one has a {@link ChildProcess} that contains + * an instance of the bot and its {@link Client}. When its child process/worker exits for any reason, the shard will + * spawn a new one to replace it as necessary. + * @extends {EventEmitter} + */ +class Shard extends EventEmitter { + constructor(manager, id) { + super(); + + switch (manager.mode) { + case 'process': + childProcess = require('node:child_process'); + break; + case 'worker': + Worker = require('node:worker_threads').Worker; + break; + } + + /** + * Manager that created the shard + * @type {ShardingManager} + */ + this.manager = manager; + + /** + * The shard's id in the manager + * @type {number} + */ + this.id = id; + + /** + * Whether to pass silent flag to the shard's process (only when {@link ShardingManager#mode} is `process`) + * @type {boolean} + */ + this.silent = manager.silent; + + /** + * Arguments for the shard's process (only when {@link ShardingManager#mode} is `process`) + * @type {string[]} + */ + this.args = manager.shardArgs ?? []; + + /** + * Arguments for the shard's process executable (only when {@link ShardingManager#mode} is `process`) + * @type {string[]} + */ + this.execArgv = manager.execArgv; + + /** + * Environment variables for the shard's process, or workerData for the shard's worker + * @type {Object} + */ + this.env = Object.assign({}, process.env, { + SHARDING_MANAGER: true, + SHARDS: this.id, + SHARD_COUNT: this.manager.totalShards, + DISCORD_TOKEN: this.manager.token, + }); + + /** + * Whether the shard's {@link Client} is ready + * @type {boolean} + */ + this.ready = false; + + /** + * Process of the shard (if {@link ShardingManager#mode} is `process`) + * @type {?ChildProcess} + */ + this.process = null; + + /** + * Worker of the shard (if {@link ShardingManager#mode} is `worker`) + * @type {?Worker} + */ + this.worker = null; + + /** + * Ongoing promises for calls to {@link Shard#eval}, mapped by the `script` they were called with + * @type {Map<string, Promise>} + * @private + */ + this._evals = new Map(); + + /** + * Ongoing promises for calls to {@link Shard#fetchClientValue}, mapped by the `prop` they were called with + * @type {Map<string, Promise>} + * @private + */ + this._fetches = new Map(); + + /** + * Listener function for the {@link ChildProcess}' `exit` event + * @type {Function} + * @private + */ + this._exitListener = null; + } + + /** + * Forks a child process or creates a worker thread for the shard. + * <warn>You should not need to call this manually.</warn> + * @param {number} [timeout=30000] The amount in milliseconds to wait until the {@link Client} has become ready + * before resolving (`-1` or `Infinity` for no wait) + * @returns {Promise<ChildProcess>} + */ + spawn(timeout = 30_000) { + if (this.process) throw new DiscordjsError(ErrorCodes.ShardingProcessExists, this.id); + if (this.worker) throw new DiscordjsError(ErrorCodes.ShardingWorkerExists, this.id); + + this._exitListener = this._handleExit.bind(this, undefined, timeout); + + switch (this.manager.mode) { + case 'process': + this.process = childProcess + .fork(path.resolve(this.manager.file), this.args, { + env: this.env, + execArgv: this.execArgv, + silent: this.silent, + }) + .on('message', this._handleMessage.bind(this)) + .on('exit', this._exitListener); + break; + case 'worker': + this.worker = new Worker(path.resolve(this.manager.file), { workerData: this.env }) + .on('message', this._handleMessage.bind(this)) + .on('exit', this._exitListener); + break; + } + + this._evals.clear(); + this._fetches.clear(); + + const child = this.process ?? this.worker; + + /** + * Emitted upon the creation of the shard's child process/worker. + * @event Shard#spawn + * @param {ChildProcess|Worker} process Child process/worker that was created + */ + this.emit(ShardEvents.Spawn, child); + + if (timeout === -1 || timeout === Infinity) return Promise.resolve(child); + return new Promise((resolve, reject) => { + const cleanup = () => { + clearTimeout(spawnTimeoutTimer); + this.off('ready', onReady); + this.off('disconnect', onDisconnect); + this.off('death', onDeath); + }; + + const onReady = () => { + cleanup(); + resolve(child); + }; + + const onDisconnect = () => { + cleanup(); + reject(new DiscordjsError(ErrorCodes.ShardingReadyDisconnected, this.id)); + }; + + const onDeath = () => { + cleanup(); + reject(new DiscordjsError(ErrorCodes.ShardingReadyDied, this.id)); + }; + + const onTimeout = () => { + cleanup(); + reject(new DiscordjsError(ErrorCodes.ShardingReadyTimeout, this.id)); + }; + + const spawnTimeoutTimer = setTimeout(onTimeout, timeout); + this.once('ready', onReady); + this.once('disconnect', onDisconnect); + this.once('death', onDeath); + }); + } + + /** + * Immediately kills the shard's process/worker and does not restart it. + */ + kill() { + if (this.process) { + this.process.removeListener('exit', this._exitListener); + this.process.kill(); + } else { + this.worker.removeListener('exit', this._exitListener); + this.worker.terminate(); + } + + this._handleExit(false); + } + + /** + * Options used to respawn a shard. + * @typedef {Object} ShardRespawnOptions + * @property {number} [delay=500] How long to wait between killing the process/worker and + * restarting it (in milliseconds) + * @property {number} [timeout=30000] The amount in milliseconds to wait until the {@link Client} + * has become ready before resolving (`-1` or `Infinity` for no wait) + */ + + /** + * Kills and restarts the shard's process/worker. + * @param {ShardRespawnOptions} [options] Options for respawning the shard + * @returns {Promise<ChildProcess>} + */ + async respawn({ delay = 500, timeout = 30_000 } = {}) { + this.kill(); + if (delay > 0) await sleep(delay); + return this.spawn(timeout); + } + + /** + * Sends a message to the shard's process/worker. + * @param {*} message Message to send to the shard + * @returns {Promise<Shard>} + */ + send(message) { + return new Promise((resolve, reject) => { + if (this.process) { + this.process.send(message, err => { + if (err) reject(err); + else resolve(this); + }); + } else { + this.worker.postMessage(message); + resolve(this); + } + }); + } + + /** + * Fetches a client property value of the shard. + * @param {string} prop Name of the client property to get, using periods for nesting + * @returns {Promise<*>} + * @example + * shard.fetchClientValue('guilds.cache.size') + * .then(count => console.log(`${count} guilds in shard ${shard.id}`)) + * .catch(console.error); + */ + fetchClientValue(prop) { + // Shard is dead (maybe respawning), don't cache anything and error immediately + if (!this.process && !this.worker) { + return Promise.reject(new DiscordjsError(ErrorCodes.ShardingNoChildExists, this.id)); + } + + // Cached promise from previous call + if (this._fetches.has(prop)) return this._fetches.get(prop); + + const promise = new Promise((resolve, reject) => { + const child = this.process ?? this.worker; + + const listener = message => { + if (message?._fetchProp !== prop) return; + child.removeListener('message', listener); + this.decrementMaxListeners(child); + this._fetches.delete(prop); + if (!message._error) resolve(message._result); + else reject(makeError(message._error)); + }; + + this.incrementMaxListeners(child); + child.on('message', listener); + + this.send({ _fetchProp: prop }).catch(err => { + child.removeListener('message', listener); + this.decrementMaxListeners(child); + this._fetches.delete(prop); + reject(err); + }); + }); + + this._fetches.set(prop, promise); + return promise; + } + + /** + * Evaluates a script or function on the shard, in the context of the {@link Client}. + * @param {string|Function} script JavaScript to run on the shard + * @param {*} [context] The context for the eval + * @returns {Promise<*>} Result of the script execution + */ + eval(script, context) { + // Stringify the script if it's a Function + const _eval = typeof script === 'function' ? `(${script})(this, ${JSON.stringify(context)})` : script; + + // Shard is dead (maybe respawning), don't cache anything and error immediately + if (!this.process && !this.worker) { + return Promise.reject(new DiscordjsError(ErrorCodes.ShardingNoChildExists, this.id)); + } + + // Cached promise from previous call + if (this._evals.has(_eval)) return this._evals.get(_eval); + + const promise = new Promise((resolve, reject) => { + const child = this.process ?? this.worker; + + const listener = message => { + if (message?._eval !== _eval) return; + child.removeListener('message', listener); + this.decrementMaxListeners(child); + this._evals.delete(_eval); + if (!message._error) resolve(message._result); + else reject(makeError(message._error)); + }; + + this.incrementMaxListeners(child); + child.on('message', listener); + + this.send({ _eval }).catch(err => { + child.removeListener('message', listener); + this.decrementMaxListeners(child); + this._evals.delete(_eval); + reject(err); + }); + }); + + this._evals.set(_eval, promise); + return promise; + } + + /** + * Handles a message received from the child process/worker. + * @param {*} message Message received + * @private + */ + _handleMessage(message) { + if (message) { + // Shard is ready + if (message._ready) { + this.ready = true; + /** + * Emitted upon the shard's {@link Client#event:shardReady} event. + * @event Shard#ready + */ + this.emit(ShardEvents.Ready); + return; + } + + // Shard has disconnected + if (message._disconnect) { + this.ready = false; + /** + * Emitted upon the shard's {@link Client#event:shardDisconnect} event. + * @event Shard#disconnect + */ + this.emit(ShardEvents.Disconnect); + return; + } + + // Shard is attempting to reconnect + if (message._reconnecting) { + this.ready = false; + /** + * Emitted upon the shard's {@link Client#event:shardReconnecting} event. + * @event Shard#reconnecting + */ + this.emit(ShardEvents.Reconnecting); + return; + } + + // Shard has resumed + if (message._resume) { + this.ready = true; + /** + * Emitted upon the shard's {@link Client#event:shardResume} event. + * @event Shard#resume + */ + this.emit(ShardEvents.Resume); + return; + } + + // Shard is requesting a property fetch + if (message._sFetchProp) { + const resp = { _sFetchProp: message._sFetchProp, _sFetchPropShard: message._sFetchPropShard }; + this.manager.fetchClientValues(message._sFetchProp, message._sFetchPropShard).then( + results => this.send({ ...resp, _result: results }), + err => this.send({ ...resp, _error: makePlainError(err) }), + ); + return; + } + + // Shard is requesting an eval broadcast + if (message._sEval) { + const resp = { _sEval: message._sEval, _sEvalShard: message._sEvalShard }; + this.manager._performOnShards('eval', [message._sEval], message._sEvalShard).then( + results => this.send({ ...resp, _result: results }), + err => this.send({ ...resp, _error: makePlainError(err) }), + ); + return; + } + + // Shard is requesting a respawn of all shards + if (message._sRespawnAll) { + const { shardDelay, respawnDelay, timeout } = message._sRespawnAll; + this.manager.respawnAll({ shardDelay, respawnDelay, timeout }).catch(() => { + // Do nothing + }); + return; + } + } + + /** + * Emitted upon receiving a message from the child process/worker. + * @event Shard#message + * @param {*} message Message that was received + */ + this.emit(ShardEvents.Message, message); + } + + /** + * Handles the shard's process/worker exiting. + * @param {boolean} [respawn=this.manager.respawn] Whether to spawn the shard again + * @param {number} [timeout] The amount in milliseconds to wait until the {@link Client} + * has become ready (`-1` or `Infinity` for no wait) + * @private + */ + _handleExit(respawn = this.manager.respawn, timeout) { + /** + * Emitted upon the shard's child process/worker exiting. + * @event Shard#death + * @param {ChildProcess|Worker} process Child process/worker that exited + */ + this.emit(ShardEvents.Death, this.process ?? this.worker); + + this.ready = false; + this.process = null; + this.worker = null; + this._evals.clear(); + this._fetches.clear(); + + if (respawn) this.spawn(timeout).catch(err => this.emit(ShardEvents.Error, err)); + } + + /** + * Increments max listeners by one for a given emitter, if they are not zero. + * @param {EventEmitter|process} emitter The emitter that emits the events. + * @private + */ + incrementMaxListeners(emitter) { + const maxListeners = emitter.getMaxListeners(); + if (maxListeners !== 0) { + emitter.setMaxListeners(maxListeners + 1); + } + } + + /** + * Decrements max listeners by one for a given emitter, if they are not zero. + * @param {EventEmitter|process} emitter The emitter that emits the events. + * @private + */ + decrementMaxListeners(emitter) { + const maxListeners = emitter.getMaxListeners(); + if (maxListeners !== 0) { + emitter.setMaxListeners(maxListeners - 1); + } + } +} + +module.exports = Shard; diff --git a/node_modules/discord.js/src/sharding/ShardClientUtil.js b/node_modules/discord.js/src/sharding/ShardClientUtil.js new file mode 100644 index 0000000..c1bd4a8 --- /dev/null +++ b/node_modules/discord.js/src/sharding/ShardClientUtil.js @@ -0,0 +1,291 @@ +'use strict'; + +const process = require('node:process'); +const { calculateShardId } = require('@discordjs/util'); +const { DiscordjsError, DiscordjsTypeError, ErrorCodes } = require('../errors'); +const Events = require('../util/Events'); +const { makeError, makePlainError } = require('../util/Util'); + +/** + * Helper class for sharded clients spawned as a child process/worker, such as from a {@link ShardingManager}. + * Utilises IPC to send and receive data to/from the master process and other shards. + */ +class ShardClientUtil { + constructor(client, mode) { + /** + * Client for the shard + * @type {Client} + */ + this.client = client; + + /** + * Mode the shard was spawned with + * @type {ShardingManagerMode} + */ + this.mode = mode; + + /** + * Message port for the master process (only when {@link ShardClientUtil#mode} is `worker`) + * @type {?MessagePort} + */ + this.parentPort = null; + + switch (mode) { + case 'process': + process.on('message', this._handleMessage.bind(this)); + client.on(Events.ShardReady, () => { + process.send({ _ready: true }); + }); + client.on(Events.ShardDisconnect, () => { + process.send({ _disconnect: true }); + }); + client.on(Events.ShardReconnecting, () => { + process.send({ _reconnecting: true }); + }); + client.on(Events.ShardResume, () => { + process.send({ _resume: true }); + }); + break; + case 'worker': + this.parentPort = require('node:worker_threads').parentPort; + this.parentPort.on('message', this._handleMessage.bind(this)); + client.on(Events.ShardReady, () => { + this.parentPort.postMessage({ _ready: true }); + }); + client.on(Events.ShardDisconnect, () => { + this.parentPort.postMessage({ _disconnect: true }); + }); + client.on(Events.ShardReconnecting, () => { + this.parentPort.postMessage({ _reconnecting: true }); + }); + client.on(Events.ShardResume, () => { + this.parentPort.postMessage({ _resume: true }); + }); + break; + } + } + + /** + * Array of shard ids of this client + * @type {number[]} + * @readonly + */ + get ids() { + return this.client.options.shards; + } + + /** + * Total number of shards + * @type {number} + * @readonly + */ + get count() { + return this.client.options.shardCount; + } + + /** + * Sends a message to the master process. + * @param {*} message Message to send + * @returns {Promise<void>} + * @emits Shard#message + */ + send(message) { + return new Promise((resolve, reject) => { + switch (this.mode) { + case 'process': + process.send(message, err => { + if (err) reject(err); + else resolve(); + }); + break; + case 'worker': + this.parentPort.postMessage(message); + resolve(); + break; + } + }); + } + + /** + * Fetches a client property value of each shard, or a given shard. + * @param {string} prop Name of the client property to get, using periods for nesting + * @param {number} [shard] Shard to fetch property from, all if undefined + * @returns {Promise<*|Array<*>>} + * @example + * client.shard.fetchClientValues('guilds.cache.size') + * .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`)) + * .catch(console.error); + * @see {@link ShardingManager#fetchClientValues} + */ + fetchClientValues(prop, shard) { + return new Promise((resolve, reject) => { + const parent = this.parentPort ?? process; + + const listener = message => { + if (message?._sFetchProp !== prop || message._sFetchPropShard !== shard) return; + parent.removeListener('message', listener); + this.decrementMaxListeners(parent); + if (!message._error) resolve(message._result); + else reject(makeError(message._error)); + }; + this.incrementMaxListeners(parent); + parent.on('message', listener); + + this.send({ _sFetchProp: prop, _sFetchPropShard: shard }).catch(err => { + parent.removeListener('message', listener); + this.decrementMaxListeners(parent); + reject(err); + }); + }); + } + + /** + * Evaluates a script or function on all shards, or a given shard, in the context of the {@link Client}s. + * @param {Function} script JavaScript to run on each shard + * @param {BroadcastEvalOptions} [options={}] The options for the broadcast + * @returns {Promise<*|Array<*>>} Results of the script execution + * @example + * client.shard.broadcastEval(client => client.guilds.cache.size) + * .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`)) + * .catch(console.error); + * @see {@link ShardingManager#broadcastEval} + */ + broadcastEval(script, options = {}) { + return new Promise((resolve, reject) => { + const parent = this.parentPort ?? process; + if (typeof script !== 'function') { + reject(new DiscordjsTypeError(ErrorCodes.ShardingInvalidEvalBroadcast)); + return; + } + script = `(${script})(this, ${JSON.stringify(options.context)})`; + + const listener = message => { + if (message?._sEval !== script || message._sEvalShard !== options.shard) return; + parent.removeListener('message', listener); + this.decrementMaxListeners(parent); + if (!message._error) resolve(message._result); + else reject(makeError(message._error)); + }; + this.incrementMaxListeners(parent); + parent.on('message', listener); + this.send({ _sEval: script, _sEvalShard: options.shard }).catch(err => { + parent.removeListener('message', listener); + this.decrementMaxListeners(parent); + reject(err); + }); + }); + } + + /** + * Requests a respawn of all shards. + * @param {MultipleShardRespawnOptions} [options] Options for respawning shards + * @returns {Promise<void>} Resolves upon the message being sent + * @see {@link ShardingManager#respawnAll} + */ + respawnAll({ shardDelay = 5_000, respawnDelay = 500, timeout = 30_000 } = {}) { + return this.send({ _sRespawnAll: { shardDelay, respawnDelay, timeout } }); + } + + /** + * Handles an IPC message. + * @param {*} message Message received + * @private + */ + async _handleMessage(message) { + if (!message) return; + if (message._fetchProp) { + try { + const props = message._fetchProp.split('.'); + let value = this.client; + for (const prop of props) value = value[prop]; + this._respond('fetchProp', { _fetchProp: message._fetchProp, _result: value }); + } catch (err) { + this._respond('fetchProp', { _fetchProp: message._fetchProp, _error: makePlainError(err) }); + } + } else if (message._eval) { + try { + this._respond('eval', { _eval: message._eval, _result: await this.client._eval(message._eval) }); + } catch (err) { + this._respond('eval', { _eval: message._eval, _error: makePlainError(err) }); + } + } + } + + /** + * Sends a message to the master process, emitting an error from the client upon failure. + * @param {string} type Type of response to send + * @param {*} message Message to send + * @private + */ + _respond(type, message) { + this.send(message).catch(err => { + const error = new Error(`Error when sending ${type} response to master process: ${err.message}`); + error.stack = err.stack; + /** + * Emitted when the client encounters an error. + * <warn>Errors thrown within this event do not have a catch handler, it is + * recommended to not use async functions as `error` event handlers. See the + * [Node.js docs](https://nodejs.org/api/events.html#capture-rejections-of-promises) for details.</warn> + * @event Client#error + * @param {Error} error The error encountered + */ + this.client.emit(Events.Error, error); + }); + } + + /** + * Creates/gets the singleton of this class. + * @param {Client} client The client to use + * @param {ShardingManagerMode} mode Mode the shard was spawned with + * @returns {ShardClientUtil} + */ + static singleton(client, mode) { + if (!this._singleton) { + this._singleton = new this(client, mode); + } else { + client.emit( + Events.Warn, + 'Multiple clients created in child process/worker; only the first will handle sharding helpers.', + ); + } + return this._singleton; + } + + /** + * Get the shard id for a given guild id. + * @param {Snowflake} guildId Snowflake guild id to get shard id for + * @param {number} shardCount Number of shards + * @returns {number} + */ + static shardIdForGuildId(guildId, shardCount) { + const shard = calculateShardId(guildId, shardCount); + if (shard < 0) throw new DiscordjsError(ErrorCodes.ShardingShardMiscalculation, shard, guildId, shardCount); + return shard; + } + + /** + * Increments max listeners by one for a given emitter, if they are not zero. + * @param {EventEmitter|process} emitter The emitter that emits the events. + * @private + */ + incrementMaxListeners(emitter) { + const maxListeners = emitter.getMaxListeners(); + if (maxListeners !== 0) { + emitter.setMaxListeners(maxListeners + 1); + } + } + + /** + * Decrements max listeners by one for a given emitter, if they are not zero. + * @param {EventEmitter|process} emitter The emitter that emits the events. + * @private + */ + decrementMaxListeners(emitter) { + const maxListeners = emitter.getMaxListeners(); + if (maxListeners !== 0) { + emitter.setMaxListeners(maxListeners - 1); + } + } +} + +module.exports = ShardClientUtil; diff --git a/node_modules/discord.js/src/sharding/ShardingManager.js b/node_modules/discord.js/src/sharding/ShardingManager.js new file mode 100644 index 0000000..288456a --- /dev/null +++ b/node_modules/discord.js/src/sharding/ShardingManager.js @@ -0,0 +1,335 @@ +'use strict'; + +const EventEmitter = require('node:events'); +const fs = require('node:fs'); +const path = require('node:path'); +const process = require('node:process'); +const { setTimeout: sleep } = require('node:timers/promises'); +const { Collection } = require('@discordjs/collection'); +const Shard = require('./Shard'); +const { DiscordjsError, DiscordjsTypeError, DiscordjsRangeError, ErrorCodes } = require('../errors'); +const { mergeDefault, fetchRecommendedShardCount } = require('../util/Util'); + +/** + * This is a utility class that makes multi-process sharding of a bot an easy and painless experience. + * It works by spawning a self-contained {@link ChildProcess} or {@link Worker} for each individual shard, each + * containing its own instance of your bot's {@link Client}. They all have a line of communication with the master + * process, and there are several useful methods that utilise it in order to simplify tasks that are normally difficult + * with sharding. It can spawn a specific number of shards or the amount that Discord suggests for the bot, and takes a + * path to your main bot script to launch for each one. + * @extends {EventEmitter} + */ +class ShardingManager extends EventEmitter { + /** + * The mode to spawn shards with for a {@link ShardingManager}. Can be either one of: + * * 'process' to use child processes + * * 'worker' to use [Worker threads](https://nodejs.org/api/worker_threads.html) + * @typedef {string} ShardingManagerMode + */ + + /** + * The options to spawn shards with for a {@link ShardingManager}. + * @typedef {Object} ShardingManagerOptions + * @property {string|number} [totalShards='auto'] Number of total shards of all shard managers or "auto" + * @property {string|number[]} [shardList='auto'] List of shards to spawn or "auto" + * @property {ShardingManagerMode} [mode='process'] Which mode to use for shards + * @property {boolean} [respawn=true] Whether shards should automatically respawn upon exiting + * @property {boolean} [silent=false] Whether to pass the silent flag to child process + * (only available when mode is set to 'process') + * @property {string[]} [shardArgs=[]] Arguments to pass to the shard script when spawning + * (only available when mode is set to 'process') + * @property {string[]} [execArgv=[]] Arguments to pass to the shard script executable when spawning + * (only available when mode is set to 'process') + * @property {string} [token] Token to use for automatic shard count and passing to shards + */ + + /** + * @param {string} file Path to your shard script file + * @param {ShardingManagerOptions} [options] Options for the sharding manager + */ + constructor(file, options = {}) { + super(); + options = mergeDefault( + { + totalShards: 'auto', + mode: 'process', + respawn: true, + silent: false, + shardArgs: [], + execArgv: [], + token: process.env.DISCORD_TOKEN, + }, + options, + ); + + /** + * Path to the shard script file + * @type {string} + */ + this.file = file; + if (!file) throw new DiscordjsError(ErrorCodes.ClientInvalidOption, 'File', 'specified.'); + if (!path.isAbsolute(file)) this.file = path.resolve(process.cwd(), file); + const stats = fs.statSync(this.file); + if (!stats.isFile()) throw new DiscordjsError(ErrorCodes.ClientInvalidOption, 'File', 'a file'); + + /** + * List of shards this sharding manager spawns + * @type {string|number[]} + */ + this.shardList = options.shardList ?? 'auto'; + if (this.shardList !== 'auto') { + if (!Array.isArray(this.shardList)) { + throw new DiscordjsTypeError(ErrorCodes.ClientInvalidOption, 'shardList', 'an array.'); + } + this.shardList = [...new Set(this.shardList)]; + if (this.shardList.length < 1) { + throw new DiscordjsRangeError(ErrorCodes.ClientInvalidOption, 'shardList', 'at least 1 id.'); + } + if ( + this.shardList.some( + shardId => typeof shardId !== 'number' || isNaN(shardId) || !Number.isInteger(shardId) || shardId < 0, + ) + ) { + throw new DiscordjsTypeError(ErrorCodes.ClientInvalidOption, 'shardList', 'an array of positive integers.'); + } + } + + /** + * Amount of shards that all sharding managers spawn in total + * @type {number} + */ + this.totalShards = options.totalShards || 'auto'; + if (this.totalShards !== 'auto') { + if (typeof this.totalShards !== 'number' || isNaN(this.totalShards)) { + throw new DiscordjsTypeError(ErrorCodes.ClientInvalidOption, 'Amount of shards', 'a number.'); + } + if (this.totalShards < 1) { + throw new DiscordjsRangeError(ErrorCodes.ClientInvalidOption, 'Amount of shards', 'at least 1.'); + } + if (!Number.isInteger(this.totalShards)) { + throw new DiscordjsRangeError(ErrorCodes.ClientInvalidOption, 'Amount of shards', 'an integer.'); + } + } + + /** + * Mode for shards to spawn with + * @type {ShardingManagerMode} + */ + this.mode = options.mode; + if (this.mode !== 'process' && this.mode !== 'worker') { + throw new DiscordjsRangeError(ErrorCodes.ClientInvalidOption, 'Sharding mode', '"process" or "worker"'); + } + + /** + * Whether shards should automatically respawn upon exiting + * @type {boolean} + */ + this.respawn = options.respawn; + + /** + * Whether to pass the silent flag to child process (only when {@link ShardingManager#mode} is `process`) + * @type {boolean} + */ + this.silent = options.silent; + + /** + * An array of arguments to pass to shards (only when {@link ShardingManager#mode} is `process`) + * @type {string[]} + */ + this.shardArgs = options.shardArgs; + + /** + * An array of arguments to pass to the executable (only when {@link ShardingManager#mode} is `process`) + * @type {string[]} + */ + this.execArgv = options.execArgv; + + /** + * Token to use for obtaining the automatic shard count, and passing to shards + * @type {?string} + */ + this.token = options.token?.replace(/^Bot\s*/i, '') ?? null; + + /** + * A collection of shards that this manager has spawned + * @type {Collection<number, Shard>} + */ + this.shards = new Collection(); + + process.env.SHARDING_MANAGER = true; + process.env.SHARDING_MANAGER_MODE = this.mode; + process.env.DISCORD_TOKEN = this.token; + } + + /** + * Creates a single shard. + * <warn>Using this method is usually not necessary if you use the spawn method.</warn> + * @param {number} [id=this.shards.size] Id of the shard to create + * <info>This is usually not necessary to manually specify.</info> + * @returns {Shard} Note that the created shard needs to be explicitly spawned using its spawn method. + */ + createShard(id = this.shards.size) { + const shard = new Shard(this, id); + this.shards.set(id, shard); + /** + * Emitted upon creating a shard. + * @event ShardingManager#shardCreate + * @param {Shard} shard Shard that was created + */ + this.emit('shardCreate', shard); + return shard; + } + + /** + * Options used to spawn multiple shards. + * @typedef {Object} MultipleShardSpawnOptions + * @property {number|string} [amount=this.totalShards] Number of shards to spawn + * @property {number} [delay=5500] How long to wait in between spawning each shard (in milliseconds) + * @property {number} [timeout=30000] The amount in milliseconds to wait until the {@link Client} has become ready + */ + + /** + * Spawns multiple shards. + * @param {MultipleShardSpawnOptions} [options] Options for spawning shards + * @returns {Promise<Collection<number, Shard>>} + */ + async spawn({ amount = this.totalShards, delay = 5500, timeout = 30_000 } = {}) { + // Obtain/verify the number of shards to spawn + if (amount === 'auto') { + amount = await fetchRecommendedShardCount(this.token); + } else { + if (typeof amount !== 'number' || isNaN(amount)) { + throw new DiscordjsTypeError(ErrorCodes.ClientInvalidOption, 'Amount of shards', 'a number.'); + } + if (amount < 1) throw new DiscordjsRangeError(ErrorCodes.ClientInvalidOption, 'Amount of shards', 'at least 1.'); + if (!Number.isInteger(amount)) { + throw new DiscordjsTypeError(ErrorCodes.ClientInvalidOption, 'Amount of shards', 'an integer.'); + } + } + + // Make sure this many shards haven't already been spawned + if (this.shards.size >= amount) throw new DiscordjsError(ErrorCodes.ShardingAlreadySpawned, this.shards.size); + if (this.shardList === 'auto' || this.totalShards === 'auto' || this.totalShards !== amount) { + this.shardList = [...Array(amount).keys()]; + } + if (this.totalShards === 'auto' || this.totalShards !== amount) { + this.totalShards = amount; + } + + if (this.shardList.some(shardId => shardId >= amount)) { + throw new DiscordjsRangeError( + ErrorCodes.ClientInvalidOption, + 'Amount of shards', + 'bigger than the highest shardId in the shardList option.', + ); + } + + // Spawn the shards + for (const shardId of this.shardList) { + const promises = []; + const shard = this.createShard(shardId); + promises.push(shard.spawn(timeout)); + if (delay > 0 && this.shards.size !== this.shardList.length) promises.push(sleep(delay)); + await Promise.all(promises); // eslint-disable-line no-await-in-loop + } + + return this.shards; + } + + /** + * Sends a message to all shards. + * @param {*} message Message to be sent to the shards + * @returns {Promise<Shard[]>} + */ + broadcast(message) { + const promises = []; + for (const shard of this.shards.values()) promises.push(shard.send(message)); + return Promise.all(promises); + } + + /** + * Options for {@link ShardingManager#broadcastEval} and {@link ShardClientUtil#broadcastEval}. + * @typedef {Object} BroadcastEvalOptions + * @property {number} [shard] Shard to run script on, all if undefined + * @property {*} [context] The JSON-serializable values to call the script with + */ + + /** + * Evaluates a script on all shards, or a given shard, in the context of the {@link Client}s. + * @param {Function} script JavaScript to run on each shard + * @param {BroadcastEvalOptions} [options={}] The options for the broadcast + * @returns {Promise<*|Array<*>>} Results of the script execution + */ + broadcastEval(script, options = {}) { + if (typeof script !== 'function') { + return Promise.reject(new DiscordjsTypeError(ErrorCodes.ShardingInvalidEvalBroadcast)); + } + return this._performOnShards('eval', [`(${script})(this, ${JSON.stringify(options.context)})`], options.shard); + } + + /** + * Fetches a client property value of each shard, or a given shard. + * @param {string} prop Name of the client property to get, using periods for nesting + * @param {number} [shard] Shard to fetch property from, all if undefined + * @returns {Promise<*|Array<*>>} + * @example + * manager.fetchClientValues('guilds.cache.size') + * .then(results => console.log(`${results.reduce((prev, val) => prev + val, 0)} total guilds`)) + * .catch(console.error); + */ + fetchClientValues(prop, shard) { + return this._performOnShards('fetchClientValue', [prop], shard); + } + + /** + * Runs a method with given arguments on all shards, or a given shard. + * @param {string} method Method name to run on each shard + * @param {Array<*>} args Arguments to pass through to the method call + * @param {number} [shard] Shard to run on, all if undefined + * @returns {Promise<*|Array<*>>} Results of the method execution + * @private + */ + _performOnShards(method, args, shard) { + if (this.shards.size === 0) return Promise.reject(new DiscordjsError(ErrorCodes.ShardingNoShards)); + + if (typeof shard === 'number') { + if (this.shards.has(shard)) return this.shards.get(shard)[method](...args); + return Promise.reject(new DiscordjsError(ErrorCodes.ShardingShardNotFound, shard)); + } + + if (this.shards.size !== this.shardList.length) { + return Promise.reject(new DiscordjsError(ErrorCodes.ShardingInProcess)); + } + + const promises = []; + for (const sh of this.shards.values()) promises.push(sh[method](...args)); + return Promise.all(promises); + } + + /** + * Options used to respawn all shards. + * @typedef {Object} MultipleShardRespawnOptions + * @property {number} [shardDelay=5000] How long to wait between shards (in milliseconds) + * @property {number} [respawnDelay=500] How long to wait between killing a shard's process and restarting it + * (in milliseconds) + * @property {number} [timeout=30000] The amount in milliseconds to wait for a shard to become ready before + * continuing to another (`-1` or `Infinity` for no wait) + */ + + /** + * Kills all running shards and respawns them. + * @param {MultipleShardRespawnOptions} [options] Options for respawning shards + * @returns {Promise<Collection<number, Shard>>} + */ + async respawnAll({ shardDelay = 5_000, respawnDelay = 500, timeout = 30_000 } = {}) { + let s = 0; + for (const shard of this.shards.values()) { + const promises = [shard.respawn({ delay: respawnDelay, timeout })]; + if (++s < this.shards.size && shardDelay > 0) promises.push(sleep(shardDelay)); + await Promise.all(promises); // eslint-disable-line no-await-in-loop + } + return this.shards; + } +} + +module.exports = ShardingManager; |