import * as _discordjs_util from '@discordjs/util';
import { Awaitable } from '@discordjs/util';
import { GatewayDispatchPayload, GatewayReadyDispatchData, GatewaySendPayload, GatewayOpcodes, GatewayIntentBits, GatewayIdentifyProperties, GatewayPresenceUpdateData, APIGatewayBotInfo } from 'discord-api-types/v10';
import * as _discordjs_collection from '@discordjs/collection';
import { Collection } from '@discordjs/collection';
import { AsyncEventEmitter } from '@vladfrangu/async_event_emitter';
import { REST } from '@discordjs/rest';
import { AsyncQueue } from '@sapphire/async-queue';
declare enum WebSocketShardEvents {
Closed = "closed",
Debug = "debug",
Dispatch = "dispatch",
Error = "error",
HeartbeatComplete = "heartbeat",
Hello = "hello",
Ready = "ready",
Resumed = "resumed"
}
declare enum WebSocketShardStatus {
Idle = 0,
Connecting = 1,
Resuming = 2,
Ready = 3
}
declare enum WebSocketShardDestroyRecovery {
Reconnect = 0,
Resume = 1
}
type WebSocketShardEventsMap = {
[WebSocketShardEvents.Closed]: [{
code: number;
}];
[WebSocketShardEvents.Debug]: [payload: {
message: string;
}];
[WebSocketShardEvents.Dispatch]: [payload: {
data: GatewayDispatchPayload;
}];
[WebSocketShardEvents.Error]: [payload: {
error: Error;
}];
[WebSocketShardEvents.Hello]: [];
[WebSocketShardEvents.Ready]: [payload: {
data: GatewayReadyDispatchData;
}];
[WebSocketShardEvents.Resumed]: [];
[WebSocketShardEvents.HeartbeatComplete]: [payload: {
ackAt: number;
heartbeatAt: number;
latency: number;
}];
};
interface WebSocketShardDestroyOptions {
code?: number;
reason?: string;
recover?: WebSocketShardDestroyRecovery;
}
declare enum CloseCodes {
Normal = 1000,
Resuming = 4200
}
interface SendRateLimitState {
remaining: number;
resetAt: number;
}
declare class WebSocketShard extends AsyncEventEmitter<WebSocketShardEventsMap> {
#private;
private connection;
private useIdentifyCompress;
private inflate;
private readonly textDecoder;
private replayedEvents;
private isAck;
private sendRateLimitState;
private initialHeartbeatTimeoutController;
private heartbeatInterval;
private lastHeartbeatAt;
private initialConnectResolved;
private failedToConnectDueToNetworkError;
private readonly sendQueue;
private readonly timeoutAbortControllers;
private readonly strategy;
readonly id: number;
get status(): WebSocketShardStatus;
constructor(strategy: IContextFetchingStrategy, id: number);
connect(): Promise<void>;
private internalConnect;
destroy(options?: WebSocketShardDestroyOptions): Promise<void>;
private waitForEvent;
send(payload: GatewaySendPayload): Promise<void>;
private identify;
private resume;
private heartbeat;
private unpackMessage;
private onMessage;
private onError;
private onClose;
private debug;
}
/**
* Strategies responsible for spawning, initializing connections, destroying shards, and relaying events
*/
interface IShardingStrategy {
/**
* Initializes all the shards
*/
connect(): Awaitable<void>;
/**
* Destroys all the shards
*/
destroy(options?: Omit<WebSocketShardDestroyOptions, 'recover'>): Awaitable<void>;
/**
* Fetches the status of all the shards
*/
fetchStatus(): Awaitable<Collection<number, WebSocketShardStatus>>;
/**
* Sends a payload to a shard
*/
send(shardId: number, payload: GatewaySendPayload): Awaitable<void>;
/**
* Spawns all the shards
*/
spawn(shardIds: number[]): Awaitable<void>;
}
/**
* IdentifyThrottlers are responsible for dictating when a shard is allowed to identify.
*
* @see {@link https://discord.com/developers/docs/topics/gateway#sharding-max-concurrency}
*/
interface IIdentifyThrottler {
/**
* Resolves once the given shard should be allowed to identify, or rejects if the operation was aborted.
*/
waitForIdentify(shardId: number, signal: AbortSignal): Promise<void>;
}
/**
* Simple strategy that just spawns shards in the current process
*/
declare class SimpleShardingStrategy implements IShardingStrategy {
private readonly manager;
private readonly shards;
constructor(manager: WebSocketManager);
/**
* {@inheritDoc IShardingStrategy.spawn}
*/
spawn(shardIds: number[]): Promise<void>;
/**
* {@inheritDoc IShardingStrategy.connect}
*/
connect(): Promise<void>;
/**
* {@inheritDoc IShardingStrategy.destroy}
*/
destroy(options?: Omit<WebSocketShardDestroyOptions, 'recover'>): Promise<void>;
/**
* {@inheritDoc IShardingStrategy.send}
*/
send(shardId: number, payload: GatewaySendPayload): Promise<void>;
/**
* {@inheritDoc IShardingStrategy.fetchStatus}
*/
fetchStatus(): Promise<Collection<number, WebSocketShardStatus>>;
}
/**
* The state of a rate limit key's identify queue.
*/
interface IdentifyState {
queue: AsyncQueue;
resetsAt: number;
}
/**
* Local, in-memory identify throttler.
*/
declare class SimpleIdentifyThrottler implements IIdentifyThrottler {
private readonly maxConcurrency;
private readonly states;
constructor(maxConcurrency: number);
/**
* {@inheritDoc IIdentifyThrottler.waitForIdentify}
*/
waitForIdentify(shardId: number, signal: AbortSignal): Promise<void>;
}
/**
* Valid encoding types
*/
declare enum Encoding {
JSON = "json"
}
/**
* Valid compression methods
*/
declare enum CompressionMethod {
ZlibStream = "zlib-stream"
}
declare const DefaultDeviceProperty: `@discordjs/ws ${string}`;
/**
* Default options used by the manager
*/
declare const DefaultWebSocketManagerOptions: {
readonly buildIdentifyThrottler: (manager: WebSocketManager) => Promise<SimpleIdentifyThrottler>;
readonly buildStrategy: (manager: WebSocketManager) => SimpleShardingStrategy;
readonly shardCount: null;
readonly shardIds: null;
readonly largeThreshold: null;
readonly initialPresence: null;
readonly identifyProperties: {
readonly browser: `@discordjs/ws ${string}`;
readonly device: `@discordjs/ws ${string}`;
readonly os: NodeJS.Platform;
};
readonly version: "10";
readonly encoding: Encoding;
readonly compression: null;
readonly retrieveSessionInfo: (shardId: number) => SessionInfo | null;
readonly updateSessionInfo: (shardId: number, info: SessionInfo | null) => void;
readonly handshakeTimeout: 30000;
readonly helloTimeout: 60000;
readonly readyTimeout: 15000;
};
declare const ImportantGatewayOpcodes: Set<GatewayOpcodes>;
declare function getInitialSendRateLimitState(): SendRateLimitState;
/**
* Represents a range of shard ids
*/
interface ShardRange {
end: number;
start: number;
}
/**
* Session information for a given shard, used to resume a session
*/
interface SessionInfo {
/**
* URL to use when resuming
*/
resumeURL: string;
/**
* The sequence number of the last message sent by the shard
*/
sequence: number;
/**
* Session id for this shard
*/
sessionId: string;
/**
* The total number of shards at the time of this shard identifying
*/
shardCount: number;
/**
* The id of the shard
*/
shardId: number;
}
/**
* Required options for the WebSocketManager
*/
interface RequiredWebSocketManagerOptions {
/**
* The intents to request
*/
intents: GatewayIntentBits | 0;
/**
* The REST instance to use for fetching gateway information
*/
rest: REST;
/**
* The token to use for identifying with the gateway
*/
token: string;
}
/**
* Optional additional configuration for the WebSocketManager
*/
interface OptionalWebSocketManagerOptions {
/**
* Builds an identify throttler to use for this manager's shards
*/
buildIdentifyThrottler(manager: WebSocketManager): Awaitable<IIdentifyThrottler>;
/**
* Builds the strategy to use for sharding
*
* @example
* ```ts
* const manager = new WebSocketManager({
* token: process.env.DISCORD_TOKEN,
* intents: 0, // for no intents
* rest,
* buildStrategy: (manager) => new WorkerShardingStrategy(manager, { shardsPerWorker: 2 }),
* });
* ```
*/
buildStrategy(manager: WebSocketManager): IShardingStrategy;
/**
* The compression method to use
*
* @defaultValue `null` (no compression)
*/
compression: CompressionMethod | null;
/**
* The encoding to use
*
* @defaultValue `'json'`
*/
encoding: Encoding;
/**
* How long to wait for a shard to connect before giving up
*/
handshakeTimeout: number | null;
/**
* How long to wait for a shard's HELLO packet before giving up
*/
helloTimeout: number | null;
/**
* Properties to send to the gateway when identifying
*/
identifyProperties: GatewayIdentifyProperties;
/**
* Initial presence data to send to the gateway when identifying
*/
initialPresence: GatewayPresenceUpdateData | null;
/**
* Value between 50 and 250, total number of members where the gateway will stop sending offline members in the guild member list
*/
largeThreshold: number | null;
/**
* How long to wait for a shard's READY packet before giving up
*/
readyTimeout: number | null;
/**
* Function used to retrieve session information (and attempt to resume) for a given shard
*
* @example
* ```ts
* const manager = new WebSocketManager({
* async retrieveSessionInfo(shardId): Awaitable<SessionInfo | null> {
* // Fetch this info from redis or similar
* return { sessionId: string, sequence: number };
* // Return null if no information is found
* },
* });
* ```
*/
retrieveSessionInfo(shardId: number): Awaitable<SessionInfo | null>;
/**
* The total number of shards across all WebsocketManagers you intend to instantiate.
* Use `null` to use Discord's recommended shard count
*/
shardCount: number | null;
/**
* The ids of the shards this WebSocketManager should manage.
* Use `null` to simply spawn 0 through `shardCount - 1`
*
* @example
* ```ts
* const manager = new WebSocketManager({
* shardIds: [1, 3, 7], // spawns shard 1, 3, and 7, nothing else
* });
* ```
* @example
* ```ts
* const manager = new WebSocketManager({
* shardIds: {
* start: 3,
* end: 6,
* }, // spawns shards 3, 4, 5, and 6
* });
* ```
*/
shardIds: number[] | ShardRange | null;
/**
* Function used to store session information for a given shard
*/
updateSessionInfo(shardId: number, sessionInfo: SessionInfo | null): Awaitable<void>;
/**
* The gateway version to use
*
* @defaultValue `'10'`
*/
version: string;
}
type WebSocketManagerOptions = OptionalWebSocketManagerOptions & RequiredWebSocketManagerOptions;
type ManagerShardEventsMap = {
[K in keyof WebSocketShardEventsMap]: [
WebSocketShardEventsMap[K] extends [] ? {
shardId: number;
} : WebSocketShardEventsMap[K][0] & {
shardId: number;
}
];
};
declare class WebSocketManager extends AsyncEventEmitter<ManagerShardEventsMap> {
/**
* The options being used by this manager
*/
readonly options: WebSocketManagerOptions;
/**
* Internal cache for a GET /gateway/bot result
*/
private gatewayInformation;
/**
* Internal cache for the shard ids
*/
private shardIds;
/**
* Strategy used to manage shards
*
* @defaultValue `SimpleShardingStrategy`
*/
private readonly strategy;
constructor(options: Partial<OptionalWebSocketManagerOptions> & RequiredWebSocketManagerOptions);
/**
* Fetches the gateway information from Discord - or returns it from cache if available
*
* @param force - Whether to ignore the cache and force a fresh fetch
*/
fetchGatewayInformation(force?: boolean): Promise<APIGatewayBotInfo>;
/**
* Updates your total shard count on-the-fly, spawning shards as needed
*
* @param shardCount - The new shard count to use
*/
updateShardCount(shardCount: number | null): Promise<this>;
/**
* Yields the total number of shards across for your bot, accounting for Discord recommendations
*/
getShardCount(): Promise<number>;
/**
* Yields the ids of the shards this manager should manage
*/
getShardIds(force?: boolean): Promise<number[]>;
connect(): Promise<void>;
destroy(options?: Omit<WebSocketShardDestroyOptions, 'recover'>): Awaitable<void>;
send(shardId: number, payload: GatewaySendPayload): Awaitable<void>;
fetchStatus(): Awaitable<_discordjs_collection.Collection<number, WebSocketShardStatus>>;
}
interface FetchingStrategyOptions extends Omit<WebSocketManagerOptions, 'buildIdentifyThrottler' | 'buildStrategy' | 'rest' | 'retrieveSessionInfo' | 'shardCount' | 'shardIds' | 'updateSessionInfo'> {
readonly gatewayInformation: APIGatewayBotInfo;
readonly shardCount: number;
}
/**
* Strategies responsible solely for making manager information accessible
*/
interface IContextFetchingStrategy {
readonly options: FetchingStrategyOptions;
retrieveSessionInfo(shardId: number): Awaitable<SessionInfo | null>;
updateSessionInfo(shardId: number, sessionInfo: SessionInfo | null): Awaitable<void>;
/**
* Resolves once the given shard should be allowed to identify, or rejects if the operation was aborted
*/
waitForIdentify(shardId: number, signal: AbortSignal): Promise<void>;
}
declare function managerToFetchingStrategyOptions(manager: WebSocketManager): Promise<FetchingStrategyOptions>;
declare class SimpleContextFetchingStrategy implements IContextFetchingStrategy {
private readonly manager;
readonly options: FetchingStrategyOptions;
private static throttlerCache;
private static ensureThrottler;
constructor(manager: WebSocketManager, options: FetchingStrategyOptions);
retrieveSessionInfo(shardId: number): Promise<SessionInfo | null>;
updateSessionInfo(shardId: number, sessionInfo: SessionInfo | null): _discordjs_util.Awaitable<void>;
waitForIdentify(shardId: number, signal: AbortSignal): Promise<void>;
}
declare class WorkerContextFetchingStrategy implements IContextFetchingStrategy {
readonly options: FetchingStrategyOptions;
private readonly sessionPromises;
private readonly waitForIdentifyPromises;
constructor(options: FetchingStrategyOptions);
retrieveSessionInfo(shardId: number): Promise<SessionInfo | null>;
updateSessionInfo(shardId: number, sessionInfo: SessionInfo | null): void;
waitForIdentify(shardId: number, signal: AbortSignal): Promise<void>;
}
interface WorkerData extends FetchingStrategyOptions {
shardIds: number[];
}
declare enum WorkerSendPayloadOp {
Connect = 0,
Destroy = 1,
Send = 2,
SessionInfoResponse = 3,
ShardIdentifyResponse = 4,
FetchStatus = 5
}
type WorkerSendPayload = {
nonce: number;
ok: boolean;
op: WorkerSendPayloadOp.ShardIdentifyResponse;
} | {
nonce: number;
op: WorkerSendPayloadOp.FetchStatus;
shardId: number;
} | {
nonce: number;
op: WorkerSendPayloadOp.SessionInfoResponse;
session: SessionInfo | null;
} | {
op: WorkerSendPayloadOp.Connect;
shardId: number;
} | {
op: WorkerSendPayloadOp.Destroy;
options?: WebSocketShardDestroyOptions;
shardId: number;
} | {
op: WorkerSendPayloadOp.Send;
payload: GatewaySendPayload;
shardId: number;
};
declare enum WorkerReceivePayloadOp {
Connected = 0,
Destroyed = 1,
Event = 2,
RetrieveSessionInfo = 3,
UpdateSessionInfo = 4,
WaitForIdentify = 5,
FetchStatusResponse = 6,
WorkerReady = 7,
CancelIdentify = 8
}
type WorkerReceivePayload = {
data: any;
event: WebSocketShardEvents;
op: WorkerReceivePayloadOp.Event;
shardId: number;
} | {
nonce: number;
op: WorkerReceivePayloadOp.CancelIdentify;
} | {
nonce: number;
op: WorkerReceivePayloadOp.FetchStatusResponse;
status: WebSocketShardStatus;
} | {
nonce: number;
op: WorkerReceivePayloadOp.RetrieveSessionInfo;
shardId: number;
} | {
nonce: number;
op: WorkerReceivePayloadOp.WaitForIdentify;
shardId: number;
} | {
op: WorkerReceivePayloadOp.Connected;
shardId: number;
} | {
op: WorkerReceivePayloadOp.Destroyed;
shardId: number;
} | {
op: WorkerReceivePayloadOp.UpdateSessionInfo;
session: SessionInfo | null;
shardId: number;
} | {
op: WorkerReceivePayloadOp.WorkerReady;
};
/**
* Options for a {@link WorkerShardingStrategy}
*/
interface WorkerShardingStrategyOptions {
/**
* Dictates how many shards should be spawned per worker thread.
*/
shardsPerWorker: number | 'all';
/**
* Path to the worker file to use. The worker requires quite a bit of setup, it is recommended you leverage the {@link WorkerBootstrapper} class.
*/
workerPath?: string;
}
/**
* Strategy used to spawn threads in worker_threads
*/
declare class WorkerShardingStrategy implements IShardingStrategy {
#private;
private readonly manager;
private readonly options;
private readonly connectPromises;
private readonly destroyPromises;
private readonly fetchStatusPromises;
private readonly waitForIdentifyControllers;
private throttler?;
constructor(manager: WebSocketManager, options: WorkerShardingStrategyOptions);
/**
* {@inheritDoc IShardingStrategy.spawn}
*/
spawn(shardIds: number[]): Promise<void>;
/**
* {@inheritDoc IShardingStrategy.connect}
*/
connect(): Promise<void>;
/**
* {@inheritDoc IShardingStrategy.destroy}
*/
destroy(options?: Omit<WebSocketShardDestroyOptions, 'recover'>): Promise<void>;
/**
* {@inheritDoc IShardingStrategy.send}
*/
send(shardId: number, data: GatewaySendPayload): void;
/**
* {@inheritDoc IShardingStrategy.fetchStatus}
*/
fetchStatus(): Promise<Collection<number, WebSocketShardStatus>>;
private setupWorker;
private resolveWorkerPath;
private waitForWorkerReady;
private onMessage;
private ensureThrottler;
}
/**
* Options for bootstrapping the worker
*/
interface BootstrapOptions {
/**
* Shard events to just arbitrarily forward to the parent thread for the manager to emit
* Note: By default, this will include ALL events
* you most likely want to handle dispatch within the worker itself
*/
forwardEvents?: WebSocketShardEvents[];
/**
* Function to call when a shard is created for additional setup
*/
shardCallback?(shard: WebSocketShard): Awaitable<void>;
}
/**
* Utility class for bootstrapping a worker thread to be used for sharding
*/
declare class WorkerBootstrapper {
/**
* The data passed to the worker thread
*/
protected readonly data: WorkerData;
/**
* The shards that are managed by this worker
*/
protected readonly shards: Collection<number, WebSocketShard>;
constructor();
/**
* Helper method to initiate a shard's connection process
*/
protected connect(shardId: number): Promise<void>;
/**
* Helper method to destroy a shard
*/
protected destroy(shardId: number, options?: WebSocketShardDestroyOptions): Promise<void>;
/**
* Helper method to attach event listeners to the parentPort
*/
protected setupThreadEvents(): void;
/**
* Bootstraps the worker thread with the provided options
*/
bootstrap(options?: Readonly<BootstrapOptions>): Promise<void>;
}
/**
* The {@link https://github.com/discordjs/discord.js/blob/main/packages/ws/#readme | @discordjs/ws} version
* that you are currently using.
*/
declare const version: string;
export { BootstrapOptions, CloseCodes, CompressionMethod, DefaultDeviceProperty, DefaultWebSocketManagerOptions, Encoding, FetchingStrategyOptions, IContextFetchingStrategy, IIdentifyThrottler, IShardingStrategy, IdentifyState, ImportantGatewayOpcodes, ManagerShardEventsMap, OptionalWebSocketManagerOptions, RequiredWebSocketManagerOptions, SendRateLimitState, SessionInfo, ShardRange, SimpleContextFetchingStrategy, SimpleIdentifyThrottler, SimpleShardingStrategy, WebSocketManager, WebSocketManagerOptions, WebSocketShard, WebSocketShardDestroyOptions, WebSocketShardDestroyRecovery, WebSocketShardEvents, WebSocketShardEventsMap, WebSocketShardStatus, WorkerBootstrapper, WorkerContextFetchingStrategy, WorkerData, WorkerReceivePayload, WorkerReceivePayloadOp, WorkerSendPayload, WorkerSendPayloadOp, WorkerShardingStrategy, WorkerShardingStrategyOptions, getInitialSendRateLimitState, managerToFetchingStrategyOptions, version };