@whirlybird/gateway

Warning whirlybird is experimental software. Use at your own risk!

About

A low-level implementation for the Discord WebSocket API.

Ecosystem

Discover the rest of the whirlybird ecosystem!

Installing

Using Node.js

You will need Node.js v18.x.x or higher.

Install with the package manager of your choice:

$ npm i @whirlybird/gateway
$ pnpm i @whirlybird/gateway
$ yarn add @whirlybird/gateway

Enable ECMAScript modules (ESM) for your project:

{
  "type": "module"
}

Using Deno

You will need Deno v1.26.x or higher.

CLI Arguments: --allow-net

Import for GitHub:

export * from "https://github.com/apacheli/whirlybird/raw/dev/core/gateway/lib.js";

Getting Started

The WebSocket API allows you to receive data from Discord in real-time, e.g., a user sending a message or changing their status.

A simple example:

import { closeOnInterrupt, Gateway } from "@whirlybird/gateway";

const handleEvent = (event, data) => {
  console.log(event, data);
};

const gateway = new Gateway("wss://gateway.discord.gg", {
  handleEvent,
  identify: {
    intents: 512,
    token: Deno.env.get("BOT_TOKEN"),
  },
  shards: 1,
});

gateway.connect();

closeOnInterrupt(gateway);

Connect multiple shards using a single process:

const gateway = new Gateway(url, {
  // Tell Discord 6 shards are connecting.
  shards: 6,
});

gateway.connect({
  // Setting `firstShard` and `lastShard` gets 0-3 (4/6 shards)
  firstShard: 0,
  lastShard: 4,
});

You can distribute shards across multiple processes using Cluster. You will use another method called .listenForConnect() on Gateway.

import { Cluster, Gateway, IS_WORKER } from "@whirlybird/gateway";

if (IS_WORKER) {
  const gateway = new Gateway(
    globalThis.process?.env["BOT_TOKEN"] ?? Deno.env.get("BOT_TOKEN"),
    "wss://gateway.discord.gg",
    {
      identify: {
        intents: 512,
      },
      shards: 9,
    },
  );
  await gateway.listenForConnect();
} else {
  const cluster = new Cluster(import.meta.url, {
    processes: 3,
    shardsPerProcess: 3,
  });
  cluster.connect();
}

Note Notice shards: 9 in gateway. This is because shards is the total number of shards across all processes. You can calculate it by doing processes * shardsPerProcess.

Using this configuration, you should expect to see something like this:

cluster:
  workers:
    0:
      shards: [0, 1, 2]
    1:
      shards: [3, 4, 5]
    2:
      shards: [6, 7, 8]

For beefier systems, you should use the PROCESSORS export to determine how many processes should be created.

import { PROCESSES } from "@whirlybird/gateway";

new Cluster(import.meta.url, {
  processes: PROCESSES,
});

If your bot is not very large, sharding and clustering should probably not be a concern for you.