buncord-hybrid-sharding 1.0.0

package/src/Plugins/AutoResharderSystem.ts

@@ -0,0 +1,382 @@
+import {
+	arraysAreTheSame, ClusterClient, ClusterManager, DjsDiscordClient, fetchRecommendedShards,
+	messageType
+} from "../index.js";
+
+export interface AutoResharderSendData {
+    clusterId: number;
+    shardData: {
+        shardId: number;
+        guildCount: number;
+    }[];
+}
+
+interface sendDataMessage {
+    data: AutoResharderSendData;
+    _type: messageType;
+}
+
+interface AutoResharderClusterClientOptions {
+    /**
+     * How often to send the data (the faster the bot grows, the more often you should send the data)
+     * @default 60e3
+     */
+    sendDataIntervalMS: number;
+    /**
+     * Function to send the required Data for the AUTORESHARDING
+     * @param cluster
+     * @returns sendData can be either sync or async
+     *
+     * @example
+     * ```ts
+     * sendDataFunction: (cluster:ClusterClient<DjsDiscordClient>) => {
+     *       return {
+     *           clusterId: cluster.id,
+     *           shardData: cluster.info.SHARD_LIST.map(shardId => ({ shardId, guildCount: cluster.client.guilds.cache.filter(g => g.shardId === shardId).size }))
+     *       }
+     * }
+     * ```
+     */
+    sendDataFunction: (
+        cluster: ClusterClient<DjsDiscordClient>,
+    ) => Promise<AutoResharderSendData> | AutoResharderSendData;
+    debug?: boolean;
+}
+
+interface AutoResharderManagerOptions {
+    /**
+     * How many shards to be set per cluster
+     */
+    ShardsPerCluster: number | 'useManagerOption';
+    /**
+     * This Number declares how many new shards should spawn.
+     * if set to 1500 it aims to create as many shards that on avg. per shard 1500 guilds are set
+     * If set to "auto" it uses the recommendation amount of discord-gateway.
+     * If set to "auto" then MaxGuildsPerShard must be at least 2000
+     * @default 1500
+    */
+    MinGuildsPerShard: 'auto' | number;
+    /** If this number is reached, autoresharding starts */
+    MaxGuildsPerShard: number;
+    /** Restart Options for reclustering */
+    restartOptions?: {
+        /** The restartMode of the clusterManager, gracefulSwitch = waits until all new clusters have spawned with maintenance mode, rolling = Once the Cluster is Ready, the old cluster will be killed  */
+        restartMode?: 'gracefulSwitch' | 'rolling';
+        /** The delay to wait between each cluster spawn */
+        delay?: number;
+        /** The readyTimeout to wait until the cluster spawn promise is rejected */
+        timeout?: number;
+    };
+    debug?: boolean;
+}
+
+export class AutoResharderClusterClient {
+    private clusterClient: ClusterClient<DjsDiscordClient>;
+    /** The Options of the AutoResharderClusterClient */
+    private options: AutoResharderClusterClientOptions = {
+        sendDataIntervalMS: 60e3,
+        debug: false,
+        sendDataFunction: (cluster: ClusterClient<DjsDiscordClient>) => {
+            return {
+                clusterId: cluster.id,
+                shardData: cluster.info.SHARD_LIST.map(shardId => ({
+                    shardId,
+                    guildCount: cluster.client.guilds.cache.filter((g:{ shardId: number }) => g.shardId === shardId).size,
+                })),
+            };
+        },
+    };
+    /** The Stored Interval */
+    private interval: any | null = null;
+    /** Wether it is running or not */
+    private started = false;
+
+    /**
+     * The Cluster client and what it shold contain
+     * @param {ClusterClient<DjsDiscordClient>} clusterClient
+     * @param {Partial<AutoResharderClusterClientOptions>} [options] the Optional options
+     */
+    constructor(clusterClient: ClusterClient<DjsDiscordClient>, options?: Partial<AutoResharderClusterClientOptions>) {
+        this.clusterClient = clusterClient;
+        this.options = {
+            ...this.options,
+            ...options,
+        };
+        this.validate();
+        this.initialize();
+    }
+    private validate() {
+        if (
+            typeof this.clusterClient !== 'object' ||
+            typeof this.clusterClient.id !== 'number' ||
+            typeof this.clusterClient.info !== 'object' ||
+            !Array.isArray(this.clusterClient.info.SHARD_LIST) ||
+            typeof this.clusterClient.send !== 'function'
+        )
+            throw new SyntaxError(
+                'clusterClient must be provided with a valid clusterId, send function and info.SHARD_LISt',
+            );
+        if (typeof this.options.sendDataIntervalMS !== 'number' || this.options.sendDataIntervalMS < 1000)
+            throw new SyntaxError('CLIENT_AutoResharderOptions.sendDataIntervalMS must be a number >= 1000');
+        if (typeof this.options.sendDataFunction !== 'function')
+            throw new SyntaxError(
+                'CLIENT_AutoResharderOptions.sendDataFunction must be a function to return the sendData: { clusterId: number, shardData: { shardId: number; guildCount; number }[] }',
+            );
+    }
+
+    /**
+     * Stops the Function and interval
+     * @returns
+     */
+    public stop() {
+        // clear the interval just to be sure
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        if (this.started === false) throw new Error('Not running!');
+        return true;
+    }
+
+    /**
+     * Start it manually after you stopped it (on initialization it automatically starts the function)
+     * @param newOptions
+     * @param executeSendData Wether it should send the data immediately or as normal: after the interval is reached.
+     * @returns
+     */
+    public start(newOptions?: Partial<AutoResharderClusterClientOptions>, executeSendData = false) {
+        if (this.started === true) throw new Error('Already started');
+
+        // overide the options
+        this.options = {
+            ...this.options,
+            ...newOptions,
+        };
+
+        return this.initialize(executeSendData);
+    }
+
+    /**
+     * Restart the function and interval, if needed
+     * @param newOptions Optinally change the options to your new options
+     * @param executeSendData Wether it should send the data immediately or as normal: after the interval is reached.
+     * @returns
+     */
+    public reStart(newOptions?: Partial<AutoResharderClusterClientOptions>, executeSendData = false) {
+        // clear the interval just to be sure
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+
+        // overide the options
+        this.options = {
+            ...this.options,
+            ...newOptions,
+        };
+
+        return this.initialize(executeSendData);
+    }
+    /**
+     * Initializes the interval
+     * @param executeSendData Wether it should send the data immediately or as normal: after the interval is reached.
+     * @returns
+     */
+    private async initialize(executeSendData = false) {
+        // if interval exists
+        if (this.interval) clearInterval(this.interval);
+
+        if (executeSendData === true) {
+            await this.sendData();
+        }
+
+        this.interval = setInterval(() => this.sendData(), this.options.sendDataIntervalMS);
+
+        return true;
+    }
+
+    private async sendData() {
+        this.validate();
+
+        const sendData = await this.options.sendDataFunction(this.clusterClient);
+
+        if (
+            typeof sendData !== 'object' ||
+            typeof sendData.clusterId !== 'number' ||
+            sendData.clusterId < 0 ||
+            !Array.isArray(sendData.shardData) ||
+            sendData.shardData.some(
+                v =>
+                    typeof v.guildCount !== 'number' ||
+                    v.guildCount < 0 ||
+                    typeof v.shardId !== 'number' ||
+                    v.shardId < 0,
+            )
+        )
+            throw new SyntaxError(
+                'Invalid sendData, must be like this: { clusterId: number, shardData: { shardId: number; guildCount; number }[] }',
+            );
+
+        if (this.options.debug === true)
+            console.debug(` CLIENT-AUTORESHARDER :: Sending Data for Cluster #${sendData.clusterId}`);
+
+        return await this.clusterClient.send({
+            _type: messageType.CLIENT_AUTORESHARDER_SENDDATA,
+            data: sendData,
+        } as sendDataMessage);
+    }
+}
+
+export class AutoResharderManager {
+    public name: string = 'autoresharder';
+    private manager?: ClusterManager;
+    // private clustersListening = new Set<number>();
+    public clusterDatas: AutoResharderSendData[] = [];
+    public options: AutoResharderManagerOptions = {
+        ShardsPerCluster: 'useManagerOption',
+        MinGuildsPerShard: 1500,
+        MaxGuildsPerShard: 2400,
+        restartOptions: {
+            restartMode: 'gracefulSwitch',
+            delay: 7e3,
+            timeout: -1,
+        },
+        debug: false,
+    };
+    public isReClustering = false;
+
+    constructor(options?: Partial<AutoResharderManagerOptions>) {
+        this.name = 'autoresharder';
+        this.options = {
+            ...this.options,
+            ...options ,
+            restartOptions: {
+                ...this.options.restartOptions,
+                ...options?.restartOptions,
+            },
+        };
+    }
+    build(manager: ClusterManager) {
+        // @ts-ignore
+        manager[this.name] = this;
+        this.manager = manager;
+
+        this.validate();
+        this.initialize();
+
+        return this;
+    }
+    public async checkReCluster() {
+        if (!this.manager) throw new Error('Manager is missing on AutoResharderManager');
+        // check for cross-hosting max cluster amount
+        if (this.clusterDatas.length <= this.manager.clusterList.length) {
+            if (this.options.debug === true)
+                console.debug('MANAGER-AUTORESHARDER :: Not all cluster data(s) reached yet');
+            return;
+        }
+
+        if (this.isReClustering === true) {
+            if (this.options.debug === true) console.debug('MANAGER-AUTORESHARDER :: Already re-sharding');
+        }
+
+        if (!arraysAreTheSame(Array.from(Array(this.manager.totalShards).keys()), this.manager.shardList)) {
+            throw new RangeError(
+                "It seems that you are using 'discord-cross-hosting' or a custom shardList specification. With either of those you can't run this plugin (yet)",
+            );
+        }
+
+        const reachedCluster = this.clusterDatas.find(v =>
+            v?.shardData.some(x => x && x.guildCount >= this.options.MaxGuildsPerShard),
+        );
+        if (reachedCluster) {
+            if (typeof this.manager.recluster === 'undefined')
+                throw new RangeError('ClusterManager must be extended with the ReCluster Plugin!');
+            this.isReClustering = true;
+
+            const newShardsCount =
+                this.options.MinGuildsPerShard === 'auto'
+                    ? await fetchRecommendedShards(this.manager.token as string)
+                    : Math.ceil(
+                          this.clusterDatas
+                              .flatMap(v => v?.shardData)
+                              .filter(d => d !== undefined)
+                              .reduce((a, b) => (!isNaN(b?.guildCount) ? b?.guildCount : 0) + (a || 0), 0) /
+                              this.options.MinGuildsPerShard,
+                      );
+            const realShardCount =
+                newShardsCount > this.manager.totalShards ? newShardsCount : Math.ceil(this.manager.totalShards * 1.2);
+            if (this.options.debug)
+                console.debug(
+                    `MANAGER-AUTORESHARDER :: Reclustering from [${
+                        this.manager.totalShards
+                    } Shards] to [${realShardCount} Shards]`,
+                );
+
+            const finalShardsPerCluster =
+                this.options.ShardsPerCluster === 'useManagerOption'
+                    ? this.manager.shardsPerClusters ||
+                      Math.ceil(this.manager.shardList.length / this.manager.totalClusters)
+                    : this.options.ShardsPerCluster;
+
+            const data = await this.manager.recluster.start({
+                ...this.options.restartOptions,
+                shardsPerClusters: finalShardsPerCluster,
+                totalShards: realShardCount,
+                totalClusters: Math.ceil(realShardCount / finalShardsPerCluster),
+                shardList: Array.from(Array(realShardCount).keys()),
+            });
+
+            this.isReClustering = false;
+            if (this.options.debug === true)
+                console.debug(
+                    `MANAGER-AUTORESHARDER :: Finished Autoresharding`,
+                    data,
+                );
+        }
+    }
+    public getData(clusterData: AutoResharderSendData) {
+        const index = this.clusterDatas.findIndex(v => v && v.clusterId === clusterData.clusterId);
+        if (index < 0) this.clusterDatas.push(clusterData);
+        else this.clusterDatas[index] = clusterData;
+
+        if (this.options.debug === true)
+            console.debug(
+                `MANAGER-AUTORESHARDER :: Reached sendData of Cluster #${clusterData.clusterId}`,
+            );
+        this.checkReCluster();
+        return;
+    }
+    private initialize() {
+        if (!this.manager) throw new Error('Manager is missing on AutoResharderManager');
+    }
+    private validate() {
+        if (!this.manager) throw new Error('Manager is missing on AutoResharderManager');
+        if (typeof this.options.ShardsPerCluster === 'string' && this.options.ShardsPerCluster !== 'useManagerOption')
+            throw new SyntaxError("AutoResharderManagerOptions.ShardsPerCluster must be 'useManagerOption' or a number >= 1",);
+        else if (this.options.ShardsPerCluster !== 'useManagerOption' && (typeof this.options.ShardsPerCluster !== 'number' || this.options.ShardsPerCluster < 1))
+            throw new SyntaxError("AutoResharderManagerOptions.ShardsPerCluster must be 'useManagerOption' or a number >= 1",);
+        if (typeof this.options.MinGuildsPerShard === 'string' && this.options.MinGuildsPerShard !== 'auto')
+            throw new SyntaxError("AutoResharderManagerOptions.MinGuildsPerShard must be 'auto' or a number >= 500");
+        else if (this.options.MinGuildsPerShard !== 'auto' && (typeof this.options.MinGuildsPerShard !== 'number' || this.options.MinGuildsPerShard < 500))
+            throw new SyntaxError("AutoResharderManagerOptions.MinGuildsPerShard must be 'auto' or a number >= 500");
+        if (
+            typeof this.options.MaxGuildsPerShard !== 'number' ||
+            (typeof this.options.MinGuildsPerShard === 'number' &&
+                this.options.MaxGuildsPerShard <= this.options.MinGuildsPerShard) ||
+            this.options.MaxGuildsPerShard > 2500
+        )
+            throw new SyntaxError(
+                'AutoResharderManagerOptions.MinGuildsPerShard must be higher (if not auto) than AutoResharderManagerOptions.MaxGuildsPerShard and lower than 2500',
+            );
+        if (typeof this.manager.recluster === 'undefined')
+            throw new RangeError('ClusterManager must be extended with the ReCluster Plugin!');
+        if (
+            typeof this.options.MinGuildsPerShard === 'string' &&
+            this.options.MinGuildsPerShard === 'auto' &&
+            this.options.MaxGuildsPerShard <= 2000
+        )
+            throw new RangeError(
+                "If AutoResharderManagerOptions.MinGuildsPerShard is set to 'auto' than AutoResharderManagerOptions.MaxGuildsPerShard must be a number > 2000",
+            );
+    }
+}

package/src/Plugins/HeartbeatSystem.ts

@@ -0,0 +1,56 @@
+import { ClusterManager } from '../Core/ClusterManager.js';
+import { RedisClient } from '../Util/RedisClient.js';
+
+export interface HeartbeatOptions {
+    interval?: number;
+    timeout?: number;
+}
+
+export class HeartbeatManager {
+    public manager?: ClusterManager;
+    public redis: RedisClient;
+    public options: Required<HeartbeatOptions>;
+    private checkInterval?: any;
+
+    constructor(options: HeartbeatOptions = {}) {
+        this.options = {
+            interval: options.interval || 10000,
+            timeout: options.timeout || 30000
+        };
+        this.redis = new RedisClient();
+    }
+
+    public build(manager: ClusterManager) {
+        this.manager = manager;
+        // @ts-ignore
+        this.manager.heartbeat = this;
+        this.start();
+    }
+
+    public async start() {
+        await this.redis.connect().catch(() => {});
+        this.checkInterval = setInterval(() => this.checkClusters(), this.options.interval);
+        this.manager?._debug("[Heartbeat] Redis-backed monitoring started");
+    }
+
+    private async checkClusters() {
+        if (!this.manager) return;
+        try {
+            for (const [id, cluster] of this.manager.clusters) {
+                if (!cluster.thread) continue;
+                
+                const lastHeartbeat = await this.redis.get(`hb:cluster:${id}`);
+                if (!lastHeartbeat && cluster.ready) {
+                    this.manager._debug(`[Heartbeat] Cluster ${id} missed heartbeat, respawning...`);
+                    cluster.respawn();
+                }
+            }
+        } catch (error) {
+            this.manager._debug(`[Heartbeat] Error checking clusters: ${(error as Error).message}`);
+        }
+    }
+
+    public stop() {
+        if (this.checkInterval) clearInterval(this.checkInterval);
+    }
+}

package/src/Plugins/QueueManager.ts

@@ -0,0 +1,49 @@
+import { ClusterManager } from "../Core/ClusterManager.js";
+import { Plugin } from "../types/shared.js";
+
+export interface QueueManagerOptions {
+    maxParallelSpawns?: number;
+    spawnDelay?: number;
+}
+
+export class QueueManager implements Plugin {
+    public manager?: ClusterManager;
+    public options: QueueManagerOptions;
+    private queue: any[] = [];
+    private processing = false;
+
+    constructor(options: QueueManagerOptions = {}) {
+        this.options = options;
+    }
+
+    public build(manager: ClusterManager) {
+        this.manager = manager;
+        // @ts-ignore
+        this.manager.queueManager = this;
+        this.manager._debug("[QueueManager] Plugin initialized");
+    }
+
+    public add(task: () => Promise<any>) {
+        this.queue.push(task);
+        this.process();
+    }
+
+    private async process() {
+        if (this.processing || this.queue.length === 0) return;
+        this.processing = true;
+
+        while (this.queue.length > 0) {
+            const task = this.queue.shift();
+            try {
+                await task();
+            } catch (err) {
+                this.manager?._debug(`[QueueManager] Task failed: ${err}`);
+            }
+            if (this.options.spawnDelay) {
+                await new Promise(resolve => setTimeout(resolve, this.options.spawnDelay));
+            }
+        }
+
+        this.processing = false;
+    }
+}

package/src/Plugins/ReCluster.ts

@@ -0,0 +1,101 @@
+import { Cluster } from "../Core/Cluster.js";
+import { ClusterManager } from "../Core/ClusterManager.js";
+import { chunkArray, fetchRecommendedShards } from "../Util/Util.js";
+
+export type ReClusterRestartMode = 'rolling';
+
+export interface ReClusterOptions {
+    delay?: number;
+    timeout?: number;
+    totalShards?: number | 'auto';
+    totalClusters?: number;
+    shardsPerClusters?: number;
+    shardList?: number[];
+    shardClusterList?: number[][];
+}
+
+export class ReClusterManager {
+    options: ReClusterOptions;
+    onProgress: boolean = false;
+    manager?: ClusterManager;
+
+    constructor(options: ReClusterOptions = {}) {
+        this.options = options;
+    }
+
+    build(manager: ClusterManager) {
+        // @ts-ignore
+        manager.recluster = this;
+        this.manager = manager;
+        return this;
+    }
+
+    public async start(options?: ReClusterOptions) {
+        const {
+            delay = 7000,
+            timeout = 300000,
+            totalClusters,
+            shardsPerClusters,
+            shardClusterList,
+            shardList = this.manager?.shardList,
+        } = options || {};
+        let totalShards = options?.totalShards;
+
+        if (this.onProgress) throw new Error('Zero Downtime Reclustering is already in progress');
+        if (!this.manager) throw new Error('Manager is missing on ReClusterManager');
+
+        if (totalShards) {
+            if (totalShards === 'auto' || totalShards === -1) {
+                if (!this.manager?.token) throw new Error('Token must be defined on manager for auto totalShards');
+                totalShards = await fetchRecommendedShards(this.manager.token);
+            }
+            this.manager.totalShards = totalShards as number;
+        }
+
+        if (totalClusters) this.manager.totalClusters = totalClusters;
+        if (shardsPerClusters) {
+            this.manager.shardsPerClusters = shardsPerClusters;
+            this.manager.totalClusters = Math.ceil(this.manager.totalShards / this.manager.shardsPerClusters);
+        }
+
+        if (shardList) this.manager.shardList = shardList;
+        if (shardClusterList) this.manager.shardClusterList = shardClusterList;
+        else {
+            this.manager.shardClusterList = chunkArray(
+                this.manager.shardList,
+                Math.ceil(this.manager.shardList.length / this.manager.totalClusters),
+            );
+        }
+
+        this.onProgress = true;
+        this.manager._debug(`[ReCluster] Starting zero-downtime rolling restart...`);
+
+        try {
+            for (let i = 0; i < this.manager.totalClusters; i++) {
+                const clusterId = this.manager.clusterList[i] || i;
+                const newShards = this.manager.shardClusterList[i] as number[];
+                
+                this.manager._debug(`[ReCluster] Spawning replacement for cluster ${clusterId}...`);
+                const newCluster = this.manager.createCluster(clusterId, newShards, this.manager.totalShards, true);
+                
+                await newCluster.spawn(timeout);
+                
+                const oldCluster = this.manager.clusters.get(clusterId);
+                if (oldCluster) {
+                    oldCluster.kill({ force: true, reason: 'rolling restart replacement' });
+                }
+                
+                this.manager.clusters.set(clusterId, newCluster);
+                this.manager._debug(`[ReCluster] Cluster ${clusterId} replaced successfully`);
+                
+                if (delay > 0 && i < this.manager.totalClusters - 1) {
+                    await new Promise(r => globalThis.setTimeout(r, delay));
+                }
+            }
+        } finally {
+            this.onProgress = false;
+        }
+
+        return { success: true };
+    }
+}

package/src/Structures/Child.ts

@@ -0,0 +1,109 @@
+export interface ChildProcessOptions {
+    clusterData: Record<string, any> | undefined;
+    args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+    cwd?: string;
+}
+
+export class Child {
+    file: string;
+    process: import("bun").Subprocess | null;
+    options: ChildProcessOptions;
+    args: string[];
+
+    constructor(file: string, options: ChildProcessOptions) {
+        this.file = file;
+        this.process = null;
+        this.options = options;
+        this.args = options.args || [];
+    }
+
+    public spawn() {
+        const env = { 
+            ...process.env, 
+            ...this.options.env,
+            ...(this.options.clusterData as any)
+        };
+
+        // Convert all env values to string for Bun.spawn
+        const stringEnv: Record<string, string> = {};
+        for (const [key, value] of Object.entries(env)) {
+            stringEnv[key] = String(value);
+        }
+
+        this.process = Bun.spawn({
+            cmd: ["bun", "run", this.file, ...this.args],
+            env: stringEnv,
+            cwd: this.options.cwd,
+            stdout: "inherit",
+            stderr: "inherit",
+            ipc: (message) => {
+                this._onMessage(message);
+            },
+            onExit: (proc, exitCode, signalCode) => {
+                this._onExit(exitCode ?? 0);
+            }
+        });
+
+        return this;
+    }
+
+    private _messageListeners: ((message: any) => void)[] = [];
+    private _exitListeners: ((exitCode: number) => void)[] = [];
+    private _errorListeners: ((error: Error) => void)[] = [];
+
+    public on(event: 'message' | 'exit' | 'error', listener: (...args: any[]) => void) {
+        if (event === 'message') this._messageListeners.push(listener);
+        if (event === 'exit') this._exitListeners.push(listener);
+        if (event === 'error') this._errorListeners.push(listener);
+        return this;
+    }
+
+    private _onMessage(message: any) {
+        for (const listener of this._messageListeners) listener(message);
+    }
+
+    private _onExit(exitCode: number) {
+        for (const listener of this._exitListeners) listener(exitCode);
+    }
+
+    public kill() {
+        this.process?.kill();
+        this.process = null;
+        this._messageListeners = [];
+        this._exitListeners = [];
+        this._errorListeners = [];
+    }
+
+    public send(message: any) {
+        return new Promise<void>((resolve, reject) => {
+            try {
+                this.process?.send(message);
+                resolve();
+            } catch (err) {
+                reject(err);
+            }
+        });
+    }
+
+    public get killed() {
+        return !this.process || this.process.killed;
+    }
+}
+
+export class ChildClient {
+    public send(message: any) {
+        return new Promise<void>((resolve, reject) => {
+            try {
+                process.send?.(message);
+                resolve();
+            } catch (err) {
+                reject(err);
+            }
+        });
+    }
+
+    public getData() {
+        return process.env;
+    }
+}