Spectacles Gateway

Spawns shards and manages a bot's lifetime on the Discord WebSocket gateway.

Getting started

const { Cluster } = require('@spectacles/gateway');
const cluster = new Cluster('a token');
cluster.spawn();

You've just spawned the recommended number of shards. If you want to use a custom or fixed shard count:

const { Cluster, Gateway } = require('@spectacles/gateway');
const gateway = Gateway.from('token', 30);

const cluster = new Cluster(gateway);

This will spawn 30 shards for the given token. Providing shard count isn't necessary after the first call.

Events

The shard emits events in the form [event name], [data]. The cluster emits events in the form [event name], [data], [shard]. When using a cluster, events will only be emitted on shards that have event listeners. Available events:

open - WebSocket opened
close - WebSocket closures (follows the CloseEvent API)
error - proxied from the underlying WebSocket connection
send - before data is sent over the connection (emitted as unencoded packet, or buffer)
receive - data that is received from the connection (decoded prior to emission)
connect - explicit connections to the WebSocket (fired initially and upon any reconnections)
disconnect - explicit disconnections from the WebSocket (i.e. when the client requests a connection closure)
[Discord gateway event] - OP 0 data, keyed by t (only d is emitted)

For details about Discord Gateway events, check out their documentation.

shard.on('MESSAGE_CREATE', message => {
  // message = https://discordapp.com/developers/docs/resources/channel#message-object-message-structure
});

Properties

`Cluster`

gateway: Gateway - the gateway session to use with the cluster
token: string - your token
shards: Map<number, Shard> - a map of your shard connections, keyed by shard id
constructor(token: string | Gateway)
spawn(shards: number | number[]) - spawn shards number of shards (if number), or spawn the specified shard IDs (if array)

`Shard`

static readonly ZLIB_SUFFIX: UInt8Array - the zlib suffix
gateway: Gateway - the gateway session to use with this shard
client: Client - the client of this shard
shard: number - this shard id
version: 6 - the gateway version to use (locked at 6)
constructor(token: string | Gateway, shard: number)
readonly seq: number - the current sequence
readonly session?: string - the current session identifier
readonly ws: WebSocket - the raw websocket
connect(): Promise<void> - connect to the gateway
disconnect(code?: number): Promise<void> - disconnect
reconnect(code?: number): Promise<void> - reconnect
identify(pk?: Partial<Identify>): Promise<void> - identify
resume(): void - resume the session
heartbeat(): void - send a heartbeat
receive(data: WebSocket.Data): void - handle packets received
send(opOrPK: number | buffer | Payload | string, d?: any): void - send data to the gateway
- send(pk: Buffer) - just send a buffer
- send(pk: Payload) - send a pre-formatted payload object
- send(op: number | string, d: any) - send d to the gateway: if op is a number, send as that op; if op is a string, send as op 0 with op as t

`Gateway`

Represents connection information for a token.

static tokens: Map<string, Gateway> - map of tokens to instantiated gateway instances; used to ensure singletons per token
static fetch(tokenOrGateway: string | Gateway): Gateway - fetches the gateway for a given token
constructor(token: string, shardCount?: number)
token: string - the token of this gateway
shards: number - total shard count of this token; recommended count is set if no value is provided
readonly url: string - the gateway URL to connect to
readonly sessionStartLimit: null | { total: number, remaining: number, resetAfter: Date } - information about the session start ratelimits
identify(shard: Shard, packet: Partial<Identify>): Promise<void> - identify with the given shard; attempts to resume if a session is available on the shard
fetch(force = false): Promise<this> - fetch gateway information; automatically called when connecting