Shard
Shard is responsible for managing a single WebSocket connection to Discord's Gateway API. Its key responsibilities include:
- Establishing and maintaining a WebSocket connection
- Handling incoming messages:
- Decompressing ZLIB-compressed messages
- Decoding JSON payloads
- Invoking callbacks for processed messages
- Sending outgoing messages, including heartbeats
- Managing the heartbeat mechanism:
- Sending periodic heartbeats to keep the connection alive
- Tracking heartbeat acknowledgements
- Initiating reconnection if heartbeats are not acknowledged
- Reconnecting through one reconnect loop that resumes the session when it can, identifies when it cannot,
backs off between attempts, and only reconnects on its own when
shouldReconnectis set - Providing an interface for other parts of the application to interact with the WebSocket connection
The Shard module is crucial for maintaining real-time communication with Discord's Gateway, ensuring the bot stays connected and can send and receive updates efficiently.
Summary
Properties
Shard.token :: SecretShard.intents :: numberShard.shardId :: numberShard.shardCount :: numberShard.shouldReconnect :: booleanShard.largeThreshold :: number?Shard.zlibBuffer :: AccumulatorShard.onSocketConnected :: Emitter<()>Shard.onSocketReconnected :: Emitter<number?>Shard.onSocketDisconnected :: Emitter<number?, boolean?>Shard.onSocketHeartbeat :: Emitter<number?>Shard.onSocketDispatch :: Emitter<apiTypes.Payload<unknown>>Shard.onSocketRawMessage :: Emitter<apiTypes.Payload<unknown>>Shard.onSocketReady :: Emitter<()>Shard.onSocketRateLimited :: Emitter<{ opcode: number, retryAfter: number, guildId: string? }>Shard.heartbeatAcknowledged :: boolean?Shard.heartbeatClockTime :: number?Shard.heartbeatInterval :: number?Shard.heartbeatThread :: thread?Shard.heartbeatJitter :: () -> numberShard.heartbeatPing :: number?Shard.lastSequence :: number?Shard.logger :: LoggerShard.socketActive :: booleanShard.socketReconnecting :: booleanShard.socketDisconnecting :: booleanShard.socketIdentified :: booleanShard.sessionId :: string?Shard.sessionGateway :: string?Shard.socketVersion :: number?Shard.socketUrl :: string?Shard.socketInstance :: any?Shard.socketThread :: thread?Shard.gatewaySendTimestamps :: { number }Shard.stayDisconnected :: booleanShard.sessionOutcome :: SessionOutcome?Shard.closeCode :: number?Shard.lastIdentifyTimestamp :: number?Shard.socketGeneration :: numberMethods
Shard:heartbeatAsync(requested: boolean?)Shard:identifyAsync()Shard:sendResumeAsync()Shard:forceClose(code: number?)Shard:disconnectAsync(code: number?)Shard:connectAsync(socketUrl: string, socketVersion: number)Shard:resumeAsync()Shard:reconnectAsync()Shard:sendAsync(data: string, ignoreRateLimit: boolean?, isStillWanted: (() -> boolean)?)Shard:reinstantiateAsync()Shard:heartbeatIn(milliseconds: number)Properties
Section titled “Properties”intents
Section titled “intents”shardId
Section titled “shardId”shardCount
Section titled “shardCount”shouldReconnect
Section titled “shouldReconnect”largeThreshold
Section titled “largeThreshold”zlibBuffer
Section titled “zlibBuffer”onSocketConnected
Section titled “onSocketConnected”onSocketReconnected
Section titled “onSocketReconnected”onSocketDisconnected
Section titled “onSocketDisconnected”onSocketHeartbeat
Section titled “onSocketHeartbeat”onSocketDispatch
Section titled “onSocketDispatch”onSocketRawMessage
Section titled “onSocketRawMessage”onSocketReady
Section titled “onSocketReady”onSocketRateLimited
Section titled “onSocketRateLimited”heartbeatAcknowledged
Section titled “heartbeatAcknowledged”heartbeatClockTime
Section titled “heartbeatClockTime”heartbeatInterval
Section titled “heartbeatInterval”heartbeatThread
Section titled “heartbeatThread”heartbeatJitter
Section titled “heartbeatJitter”Returns the jitter in [0, 1) that scales heartbeatInterval into the wait before the first heartbeat. Defaults to
math.random; tests replace it to pin the wait.
heartbeatPing
Section titled “heartbeatPing”lastSequence
Section titled “lastSequence”logger
Section titled “logger”socketActive
Section titled “socketActive”socketReconnecting
Section titled “socketReconnecting”socketDisconnecting
Section titled “socketDisconnecting”socketIdentified
Section titled “socketIdentified”sessionId
Section titled “sessionId”sessionGateway
Section titled “sessionGateway”socketVersion
Section titled “socketVersion”socketUrl
Section titled “socketUrl”socketInstance
Section titled “socketInstance”socketThread
Section titled “socketThread”gatewaySendTimestamps
Section titled “gatewaySendTimestamps”Rolling log of os.clock() timestamps for every non-heartbeat send, used to enforce Discord's 120-events-per-60s gateway send rate limit.
stayDisconnected
Section titled “stayDisconnected”true while the shard stays down until an explicit connectAsync or reconnectAsync: after disconnectAsync or forceClose, a failed connectAsync, a fatal close code, a reconnect loop that threw, or an automatic reconnect while shouldReconnect is off.
sessionOutcome
Section titled “sessionOutcome”What the gateway answered on the current socket (READY, RESUMED, op 7 or op 9); read by the reconnect loop.
closeCode
Section titled “closeCode”Close code the server sent when it last closed the shard's socket.
lastIdentifyTimestamp
Section titled “lastIdentifyTimestamp”Unix time in seconds of the last IDENTIFY, used to keep reconnects under Discord's daily IDENTIFY limit.
socketGeneration
Section titled “socketGeneration”Counts sockets opened; an automatic reconnect raised by a socket that has since been replaced is dropped.
Methods
Section titled “Methods”heartbeatAsync
Section titled “heartbeatAsync”Shard : heartbeatAsync ( requested ) -> ()
Sends a heartbeat to the Discord Gateway API. When the previous heartbeat was never acknowledged and no reconnect is running, the socket is treated as zombified: an automatic reconnect is raised instead.
Parameters
| requested: boolean? |
identifyAsync
Section titled “identifyAsync”Shard : identifyAsync ( ) -> ()
Identifies the current shard with the Discord Gateway, and records when it did so the reconnect loop can pace the next IDENTIFY.
sendResumeAsync
Section titled “sendResumeAsync”Shard : sendResumeAsync ( ) -> ()
Sends op 6 Resume for the current session, carrying the last sequence seen so Discord replays what was missed.
forceClose
Section titled “forceClose”Shard : forceClose ( code ) -> ()
Synchronously closes the shard's socket, ends its session and stops its threads, and keeps the shard down until
connectAsync or reconnectAsync is called. Safe to call from a signal handler or any context where yielding is
not permitted.
Parameters
| code: number? |
disconnectAsync
Section titled “disconnectAsync”Shard : disconnectAsync ( code ) -> ()
Disconnects the Shard from the Discord Gateway and keeps it down until connectAsync or reconnectAsync is
called.
Optionally, a WebSocket close code can be provided, websocket close code spec can be found here: https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/code
Parameters
| code: number? |
connectAsync
Section titled “connectAsync”Shard : connectAsync ( socketUrl , socketVersion ) -> ()
Connects the shard to a Discord Gateway with a fresh session; the shard identifies as soon as Hello arrives.
Expects both a Socket URL, and Socket Version to be provided. It will prepend the socket version to the socket URL, and then connect to the socket.
Resolves Err when the shard already has an open socket or the connection fails; a failed connection leaves the shard down. While a reconnect is running, it leaves the connection to that reconnect.
resumeAsync
Section titled “resumeAsync”Shard : resumeAsync ( ) -> ()
Reconnects the shard and resumes its session; the reconnect loop identifies instead when no session is left.
reconnectAsync
Section titled “reconnectAsync”Shard : reconnectAsync ( ) -> ()
Closes the WebSocket connection and reconnects the shard, resuming the session when one exists. Retries with
backoff until it succeeds, a fatal close code arrives, or the shard is closed. An explicit call always
reconnects, whatever shouldReconnect says.
sendAsync
Section titled “sendAsync”Shard : sendAsync ( data , ignoreRateLimit , isStillWanted ) -> ()
Sends a message through the WebSocket to Discords Gateway.
NOTE: Messages are expected to be JSON encoded strings.
Pass ignoreRateLimit = true to bypass the 120-events-per-60s send rate limit tracking.
This should only be used for op 1 (Heartbeat) sends, which Discord explicitly exempts.
Pass isStillWanted to cancel a send that is still waiting: it is called after any rate-limit wait, just before
the socket send, and a false result drops the send (logged at debug) and resolves Ok.
reinstantiateAsync
Section titled “reinstantiateAsync”Shard : reinstantiateAsync ( ) -> ()
Ends the session and reconnects the shard with a fresh IDENTIFY on the original gateway URL.
Any events between the disconnection and the new session will not be recovered. If this is
what you intend to avoid, use Shard:reconnectAsync instead.
heartbeatIn
Section titled “heartbeatIn”Shard : heartbeatIn ( milliseconds ) -> ()
Sends a heartbeat after milliseconds milliseconds, looping and continuing to heartbeat
until the socket it started on is closed or replaced, or the shard is told to stay disconnected.
Parameters
| milliseconds: number |
Functions
Section titled “Functions”Shard . new ( settings ) -> Shard
Will instantiate a new Shard class.