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
Handling reconnection logic when the connection becomes unstable or “zombified”
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.

Properties

token

Shard.token :: Secret

intents

Shard.intents :: number

shardId

Shard.shardId :: number

shardCount

Shard.shardCount :: number

shouldReconnect

Shard.shouldReconnect :: boolean

largeThreshold

Shard.largeThreshold :: number?

zlibBuffer

Shard.zlibBuffer :: Buffer

onSocketConnected

Shard.onSocketConnected :: Emitter<()>

onSocketReconnected

Shard.onSocketReconnected :: Emitter<number?>

onSocketDisconnected

Shard.onSocketDisconnected :: Emitter<number?, boolean?>

onSocketHeartbeat

Shard.onSocketHeartbeat :: Emitter<number?>

onSocketDispatch

Shard.onSocketDispatch :: Emitter<apiTypes.Payload<unknown>

onSocketRawMessage

Shard.onSocketRawMessage :: Emitter<apiTypes.Payload<unknown>

onSocketReady

Shard.onSocketReady :: Emitter<()>

heartbeatAcknowledged

Shard.heartbeatAcknowledged :: boolean?

heartbeatClockTime

Shard.heartbeatClockTime :: number?

heartbeatInterval

Shard.heartbeatInterval :: number?

heartbeatThread

Shard.heartbeatThread :: thread?

heartbeatPing

Shard.heartbeatPing :: number?

lastSequence

Shard.lastSequence :: number?

logger

Shard.logger :: Logger

socketActive

Shard.socketActive :: boolean

socketReconnecting

Shard.socketReconnecting :: boolean

socketDisconnecting

Shard.socketDisconnecting :: boolean

socketIdentified

Shard.socketIdentified :: boolean

sessionId

Shard.sessionId :: string?

sessionGateway

Shard.sessionGateway :: string?

socketVersion

Shard.socketVersion :: number?

socketUrl

Shard.socketUrl :: string?

socketInstance

Shard.socketInstance :: any?

socketThread

Shard.socketThread :: thread?

Methods

The Shard instance has no set methods!

Functions

_handleMessage

Shard . _handleMessage (

self: Shard
message: string
) -> ()

Function responsible for handling incoming messages from the WebSocket connection.

It performs the following steps:

Decompresses the incoming message if it’s ZLIB-compressed i. It’s worth noting that payloads may not be complete, meaning we should add data to the buffer until we have a complete message
Decodes the JSON payload
Invokes the appropriate callback based on the received event type

Roughly based on the following documentation: https://discord.com/developers/docs/topics/gateway#zlibstream

heartbeatAsync

Shard . heartbeatAsync (

self: Shard
requested: boolean?
) -> ()

Sends a heartbeat to the Discord Gateway API.

identifyAsync

Shard . identifyAsync (

self: Shard
) -> ()

Identifies the current shard with the Discord Gateway.

disconnectAsync

Shard . disconnectAsync (

self: Shard
code: number?
) -> ()

Disconnects the Shard from the Discord Gateway.

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

connectAsync

Shard . connectAsync (

     self: Shard
     socketUrl: string
     socketVersion: number
) -> ()

Connects the shard to a Discord Gateway.

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.

Also responsible for spawning the thread that will be responsible for receiving messages from the socket.

resumeAsync

Shard . resumeAsync (

self: Shard
) -> ()

Resumes a shard session if for some reason the session has either become zombified, or the session has been invalidated by Discord.

reconnectAsync

Shard . reconnectAsync (

self: Shard
) -> ()

Closes the websocket connection and reconnects the shard. This is not a re-instantiation of the shard, but a re-connection of the shard.

sendAsync

Shard . sendAsync (

self: Shard
data: string
) -> ()

Sends a message through the WebSocket to Discords Gateway.

NOTE: Messages are expected to be JSON encoded strings.

reinstantiateAsync

Shard . reinstantiateAsync (

self: Shard
noFail: boolean?
) -> ()

Disconnects the Shard, and re-instantiats it.

Re-instantiation is the reconnection of the shard to the original socket passed, and not the session URL/ID that was passed.

Any events between the initial disconnection and reconnection will not be recovered. If this is what you intend to do, use Shard:reconnectAsync instead.

heartbeatIn

Shard . heartbeatIn (

self: Shard
milliseconds: number
) -> ()

Sends a heartbeat after milliseconds milliseconds, looping and continuing to heartbeat until the shard is disconnected.

new

Shard . new (

     settings: {
       token: string,
       intents: number,
       shardId: number,
       shardCount: number,
       shouldReconnect: boolean,
       logLevel: logger.LogLevel,
       largeThreshold: number?,
    }
) -> ()

Will instantiate a new Shard class.