SpikeyBot-Discord

Class: ShardingMaster

ShardingMaster

new ShardingMaster( [port] [, address] [, path])

The master that manages the shards below it. This is what specifies how many shards may start, which shard has which ID, as well as manages inter-shard communication. Shutdown, start, reboot, and update commands may be issued to individual shards with updated information on how they are expected to be configured. Shards are expected to communicate with this master via websockets once they are ready to receive their role.
Parameters:
Name Type Argument Default Description
port number <optional>
 8024 Port to listen for shard connections.
address string <optional>
 '127.0.0.1' Address to listen for shard connections.
path string <optional>
 '/socket.io/' Path prefix to watch for socket connections.
Source:

Classes

ShardInfo
ShardStatus

Members

<private> _app :http.Server

Webserver instance.
Type:
  • http.Server
Source:

<private, nullable> _auth :object

The current authentication information.
Type:
  • object
Source:

<private, nullable> _config :ShardMasterConfig

The current config for sharding.
Type:
  • ShardMasterConfig
Source:

<private> _detectedNumShards :number

The number of shards recommended by Discord from our last request.
Type:
  • number
Source:

<private, nullable> _hbTimeout :number

Timeout for heartbeat interval loop.
Type:
  • number
Source:

<private, nullable> _hbWaitID :string

ID of the shard we last sent a heartbeat request to that has not been resolved. This is only used for 'pull' style updating for debugging heartbeats that don't get replies.
Type:
  • string
Source:

<private> _heartbeatLoopStartTime :number

The timestamp at which the heartbeat interval loop was most recently started. This is used when ShardingMaster.ShardMasterConfig.HeartbeatConfig~disperse is being used in order to only update one shard for each heartbeat event.
Type:
  • number
Source:

<private, nullable> _historySaveTimeout :number

Timeout used to prevent multiple calls to _writeStatsHistory within a short time.
Type:
  • number
Source:

<private> _io :socketIo.Server

Socket.io instance.
Type:
  • socketIo.Server
Source:

<private> _ipConnectHistory :Array.<Array.<string, number>>

History of recent connections ordered by oldest to latest. Each index contains an array of length 2, storing the IP address and the timestamp of a connection attempt. This is used to start ignoring an IP address if too many connection attempts are made within a short time.
Type:
  • Array.<Array.<string, number>>
Default Value:
  • []
Source:

<private, nullable> _knownUsers :object.<ShardInfo>

The currently known shards mapped by their name, containing some information about them including their public key.
Type:
  • object.<ShardInfo>
Source:

<private, nullable> _masterShardSocket :Socket

The socket that the master shard is currently connected on, or null if disconnected.
Type:
  • Socket
Source:

<private> _nextHeartbeatTime :number

The timestamp at which the next heartbeat event is to fire.
Type:
  • number
Source:

<private, nullable> _privKey :string

The string representation of the private key used for signing initial handshake to shard.
Type:
  • string
Source:
See:
  • ShardingMaster~_loadMasterKeys

<private, nullable> _pubKey :string

The string representation of the public key used for signing initial handshake to shard.
Type:
  • string
Source:
See:
  • ShardingMaster~_loadMasterKeys

<private> _shardNumTimestamp :number

The timestamp the last time the recommended shard count was requested.
Type:
  • number
Source:

<private> _shardSockets :object.<Socket>

Map of the currently connected sockets for each shard, mapped by the shard names.
Type:
  • object.<Socket>
Source:

<private> _sockets :object.<Socket>

Map of all currently connected sockets mapped by socket.id.
Type:
  • object.<Socket>
Source:

<private, nullable> _userSaveTimeout :number

Timeout used to prevent multiple calls to _saveUsers within a short time.
Type:
  • number
Source:

<private> _usersIgnoreNext :boolean

Toggle for when we write known users to file to not re-read them again.
Type:
  • boolean
Source:

<private> _usersStatsHistory :object.<Array.<ShardStatus>>

History for each known user of the received stats for showing graphs and analysis. Mapped by user ID, then array in chronological order.
Type:
  • object.<Array.<ShardStatus>>
Default Value:
  • {}
Source:

Methods

<private, static> _sendEmail(cmd, args, opts, stdin)

Sends an email given the raw inputs.
Parameters:
Name Type Description
cmd string The command to run to start the mail process.
args Array.<string> The arguments to pass.
opts object Options to pass to spawn.
stdin string The data to write to stdin of the process.
Source:

<private, static> _sendShardCreateEmail(conf, filename [, info])

Send the newly created config to sysadmins.
Parameters:
Name Type Argument Description
conf ShardingMaster.ShardMasterConfig.MailConfig Mail config object.
filename string The path to the file of the shard's configuration to send to sysadmins.
info ShardingMaster.ShardInfo <optional>
 Shard info of created shard for additional information to sysadmins.
Source:

<private, static> _sendShardCreateFailEmail(conf [, errs])

Send an email to sysadmins alerting them that a new shard must be created, but we were unable to for some reason.
Parameters:
Name Type Argument Description
conf ShardingMaster.ShardMasterConfig.MailConfig Mail config object.
errs Error | string <optional>
<repeatable>
 The error generated with information as to why creation failed.
Source:

<static> generateKeyPair(cb)

Generates a key pair using configured settings for either the master or its shards. The settings used cannot differ between any parties involved, otherwise all keys must be changed. https://nodejs.org/api/crypto.html#crypto_crypto_generatekeypair_type_options_callback.
Parameters:
Name Type Description
cb function Callback with optional error, then public key, then private key.
Source:

<private> _generateShardName()

Generate a unique name for a new shard.
Source:
Returns:
New unique shard name.
Type
string

<private> _getCurrentConfigured( [goal])

Get references to all shards currently configured for the given goal number of shards, and are connected and controllable.
Parameters:
Name Type Argument Description
goal number <optional>
 The goal number of shards. If not specified, getGoalShardCount will be used.
Source:
Returns:
Array of the shards that are configured correctly and don't need updating.
Type
Array.<ShardInfo>

<private> _getCurrentUnboundIds( [goal])

Get list of IDs for shards that do not exist, but need to.
Parameters:
Name Type Argument Description
goal number <optional>
 The goal number of shards. If not specified, getGoalShardCount will be used.
Source:
Returns:
Array of the shard IDs that need to be configured.
Type
Array.<number>

<private> _getCurrentUnconfigured( [goal])

Get references to all shards currently NOT configured for the given goal number of shards, but ARE connected and controllable.
Parameters:
Name Type Argument Description
goal number <optional>
 The goal number of shards. If not specified, getGoalShardCount will be used.
Source:
Returns:
Array of the shards that are NOT configured correctly and DO need updating.
Type
Array.<ShardInfo>

<private> _getMasterUser()

Get the master shard from the known users. Assumes only one master exists.
Source:
Returns:
The matched shard info, or null if it couldn't be found.
Type
ShardInfo

<private> _getShardById(shardId)

Get a reference to a ShardInfo object using its shard ID.
Parameters:
Name Type Description
shardId number The shard ID used by Discord.
Source:
Returns:
The matched shard info, or null if it couldn't be found.
Type
ShardInfo

<private> _handler(req, res)

Handler for all http requests. This may get used in the future for API requests. Currently unused and always replies with a "501 Not Implemented" response.
Parameters:
Name Type Description
req http.IncomingMessage The client's request.
res http.ServerResponse Our response to the client.
Source:

<private> _loadMasterKeys()

Check if key-pair exists for this master. If not, they will be generated, and the newly generated keys will be used.
Source:

<private> _makeSerializableError(err)

Convert an Error object into a serializable object format that can be send easily over a socket.
Parameters:
Name Type Description
err Error | string The error to make into a basic object. If falsey, returns null. If string, the string is returned unmodified.
Source:
Returns:
A simple object or null if falsey value passed or string if string was passed.
Type
object | string

<private> _readStatsHistory()

Read stats history from save file on disk.
Source:

<private> _receiveFile(filename, data)

We received a file from a shard that it intends for us to write to disk at the given filename relative to the project root.
Parameters:
Name Type Description
filename string Filename relative to project directory.
data string | Buffer The data to write to the file.
Source:

<private> _refreshShardStatus()

The config was changed or may differ from the current setup, attempt to make changes to match the current setup the requested configuration.
Source:

<private> _runBotUpdate()

Fetch the latest bot version from GitHub.
Source:

<private> _saveUsers( [force])

Write updated known list of users to disk.
Parameters:
Name Type Argument Default Description
force boolean <optional>
 false Force saving immediately. False otherwise waits a moment for multiple calls, then saves once all calls have subsided.
Source:

<private> _sendFile(filename, cb)

Shard has requested one of our files.
Parameters:
Name Type Description
filename string Filename relative to project directory.
cb function Callback to send the error or file back on.
Source:

<private> _sendHeartbeatRequest(user)

Format and send the request for a shard heartbeat.
Parameters:
Name Type Description
user number | ShardingMaster.ShardInfo Either the goal shard ID, or the shard user information.
Source:

<private> _sendSlaveFile(socket, req, cb)

Send the specified file to the ShardingSlave.
Parameters:
Name Type Description
socket Socket | number | ShardingMaster.ShardInfo Socket.io socket to send file to, or shard info to find socket from.
req string | object.<string> Filename relative to project directory, or object with both filename and last modified time.
cb function Callback with optional error argument.
Source:

<private> _serverError(err)

Server has encountered an error, and must close.
This:
Parameters:
Name Type Description
err Error The emitted error event.
Source:

<private> _setHBTimeout()

Reset the heartbeat timeout interval for refreshing shard statuses.
Source:

<private> _socketConnection(socket)

Handler for a new socket connecting.
This:
Parameters:
Name Type Description
socket socketIo~Socket The socket.io socket that connected.
Source:

<private> _updateAuth()

Update the authentication tokens from file.
Source:

<private> _updateConfig()

Update the configuration from file.
Source:

<private> _updateUsers()

Update known list of users and their associated keys.
Source:

<private> _writeStatsHistory( [force])

Write current stats history to file.
Parameters:
Name Type Argument Default Description
force boolean <optional>
 false Force saving immediately. False otherwise waits a moment for multiple calls, then saves once all calls have subsided.
Source:

broadcastEvalToShards(script, cb)

Broadcast a message to all connected shards, except for the master.
Parameters:
Name Type Description
script string Text for each shard to evaluate.
cb function Callback once all shards have replied. First argument is optional error message, second will be an array of responses, indexed by shard ID.
Source:

exit()

Cleanup and fully shutdown gracefully.
Source:

generateShardConfig( [isMaster])

Creates a configuration for a new shard. This config contains the shard's key-pair, name, and the host information to find this master. This file will be saved directly to disk, as well as emailed to sysadmins.
Parameters:
Name Type Argument Default Description
isMaster boolean <optional>
 false Is this config for a master shard.
Source:

getCurrentConfiguredCount( [goal])

Fetches the current number of shards that are configured for the goal number of shards.
Parameters:
Name Type Argument Description
goal number <optional>
 The goal number of shards. If not specified, getGoalShardCount will be used.
Source:
Returns:
The number of shards configured.
Type
number

getCurrentShardCount()

Fetches the current number of shards connected to us that we are controlling.
Source:
Returns:
The current number of shards we are controlling.
Type
number

getGoalShardCount()

Fetch the current goal number of shards we are attempting to keep alive. Returns -1 if goal has not been set yet, or is otherwise unavailable.
Source:
Returns:
The number of shards we are attempting to create, -1 if the value is otherwise unknown.
Type
number

getKnownShardCount()

Fetches the current number of shards that we know about and may talk to us.
Source:
Returns:
The number of shards allowed to startup.
Type
number

getNumClients()

Returns the number of connected clients.
Source:
Returns:
Number of sockets.
Type
number

getRegisteredShardCount()

Fetches the number of shards that have ever successfully connected to us.
Source:
Returns:
The number of shards we will probably be startable.
Type
number

rebootRequest(msg)

A reboot of some form has been requested. Parse, and comply.
Parameters:
Name Type Description
msg string The reboot command.
Source:

respawnAll( [cb])

Kills all running shards and respawns them.
Parameters:
Name Type Argument Description
cb function <optional>
 Callback once all shards have been rebooted or an error has occurred.
Source:

sendSQL(query, cb)

Send an SQL query to our database.
Parameters:
Name Type Description
query string The query to send to database.
cb function First argument is optional error, otherwise query response.
Source:

writeFile(filename, data, cb)

Write a given file to disk, or unlink.
Parameters:
Name Type Argument Description
filename string The name of the file to update, relative to project directory.
data * <nullable>
 The data to write to file, or null to unlink the file.
cb function First argument is optional error.
Source: