galactic.ts 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 GalaxyBot
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+![Galactic Logo](https://s3.galaxybot.app/media/galactic/readmeBanner.png?v=2)
+
+galactic is a powerful scaling library for Discord bots, built to make distributed shard and cluster management simple, efficient, and highly flexible.
+
+## Overview
+
+galactic allows you to run multiple Discord shards within a single process and scale your bot seamlessly across multiple machines or containers. It’s designed to integrate smoothly with [discord.js](https://discord.js.org/), enabling developers to focus on building features instead of managing complex scaling setups.
+
+## Key Features
+
+- Run multiple **Discord shards** in one process
+- Automate **cluster distribution** across multiple machines or Docker containers
+- Utilize the **galactic Bridge** to synchronize shards and clusters
+- **Seamless integration** with discord.js
+- Optimized for both **small** and **large-scale** bot deployments
+- Easy configuration and setup
+- Open-source and actively maintained
+- Reclustering without downtime
+
+## Installation
+
+```bash
+npm install galactic.ts
+# or
+yarn add galactic.ts
+```
+
+## Quick Start Example
+
+```ts filename="index.ts"
+import {StandaloneInstance} from "galactic.ts";
+
+// Create a standalone instance running 2 clusters with 2 shards each
+const machine = new StandaloneInstance(
+    `${__dirname}/bot.js`,
+    2, 2, process.env.TEST_SA_BOT_TOKEN!, 
+    []
+);
+
+machine.start();
+```
+
+```ts filename="bot.ts"
+import {Cluster} from "galactic.ts";
+import {Client, ClientOptions} from "discord.js";
+
+// Extend the Discord Client to include a reference to its Cluster
+export class ExtendedClient extends Client {
+    cluster: Cluster<ExtendedClient>;
+
+    constructor(options: ClientOptions, cluster: Cluster<ExtendedClient>) {
+        super(options);
+        this.cluster = cluster;
+    }
+}
+
+// Initialize the Cluster
+const cluster = Cluster.initial<ExtendedClient>();
+
+const client = new ExtendedClient({
+    shards: cluster.shardList,
+    shardCount: cluster.totalShards,
+    intents: cluster.intents,
+}, cluster);
+
+cluster.client = client;
+
+client.login(cluster.token)
+```
+
+## Distributed Setup
+
+To scale your bot across multiple servers or containers, galactic uses the **galactic Bridge**.  
+Each instance connects to the same bridge to coordinate shard and cluster responsibilities.
+
+Typical setup:
+1. Deploy multiple galactic instances (e.g., on different VPS or Docker nodes)
+2. Configure each instance to connect to the same galactic Bridge
+3. galactic automatically balances shards across all connected nodes
+
+## Integration with Discord.js
+
+galactic is fully compatible with the latest version of discord.js.  
+You can integrate it without modifying your existing command or event handling structure.
+
+## Use Cases
+
+- Running high-traffic bots with thousands of guilds
+- Horizontal scaling using containers (Docker, Kubernetes)
+- Efficient utilization of hardware on a single machine
+
+## License
+
+MIT © 2025 GalaxyBot

package/dist/index.d.mts

@@ -0,0 +1,327 @@
+import { Connection, Server } from 'net-ipc';
+import { GatewayIntentsString, Client } from 'discord.js';
+import { ChildProcess } from 'child_process';
+
+type EventPayload = {
+    id: string;
+    type: 'message' | 'request' | 'response' | 'response_error';
+    data: unknown;
+};
+
+declare class EventManager {
+    private pendingPayloads;
+    private pendingTimeouts;
+    private readonly _send;
+    private readonly _on;
+    private readonly _request;
+    constructor(send: (payload: EventPayload) => Promise<void>, on: (message: unknown) => void, request: (message: unknown) => unknown);
+    send(data: unknown): Promise<void>;
+    request<T>(payload: unknown, timeout: number): Promise<T>;
+    receive(possiblePayload: unknown): void;
+    close(reason?: string): void;
+}
+
+declare enum BridgeClientConnectionStatus {
+    READY = "ready",
+    PENDING_STOP = "pending_stop"
+}
+declare class BridgeClientConnection {
+    readonly instanceID: number;
+    readonly eventManager: EventManager;
+    readonly connection: Connection;
+    readonly data: unknown;
+    connectionStatus: BridgeClientConnectionStatus;
+    readonly dev: boolean;
+    private _onMessage?;
+    private _onRequest?;
+    constructor(instanceID: number, connection: Connection, data: unknown, dev: boolean);
+    messageReceive(message: any): void;
+    onRequest(callback: (message: unknown) => unknown): void;
+    onMessage(callback: (message: unknown) => void): void;
+}
+
+declare enum BridgeClientClusterConnectionStatus {
+    REQUESTING = "requesting",
+    STARTING = "starting",
+    CONNECTED = "connected",
+    RECLUSTERING = "reclustering",
+    DISCONNECTED = "disconnected"
+}
+declare class BridgeClientCluster {
+    readonly clusterID: number;
+    readonly shardList: number[];
+    connectionStatus: BridgeClientClusterConnectionStatus;
+    connection?: BridgeClientConnection;
+    oldConnection?: BridgeClientConnection;
+    missedHeartbeats: number;
+    heartbeatResponse?: HeartbeatResponse;
+    heartbeatPending: boolean;
+    startedAt?: number;
+    constructor(clusterID: number, shardList: number[]);
+    setConnection(connection?: BridgeClientConnection): void;
+    setOldConnection(connection?: BridgeClientConnection): void;
+    isUsed(): boolean;
+    reclustering(connection: BridgeClientConnection): void;
+    addMissedHeartbeat(): void;
+    removeMissedHeartbeat(): void;
+    resetMissedHeartbeats(): void;
+}
+type HeartbeatResponse = {
+    cpu: {
+        raw: {
+            user: number;
+            system: number;
+        };
+        cpuPercent: string;
+    };
+    memory: {
+        raw: {
+            rss: number;
+            heapTotal: number;
+            heapUsed: number;
+            external: number;
+            arrayBuffers: number;
+        };
+        memoryPercent: string;
+        usage: number;
+    };
+    ping: number;
+    shardPings: {
+        id: number;
+        ping: number;
+        status: number;
+        guilds: number;
+        members: number;
+    }[];
+};
+
+declare class Bridge {
+    readonly port: number;
+    readonly server: Server;
+    readonly connectedClients: Map<string, BridgeClientConnection>;
+    private readonly token;
+    private readonly intents;
+    private readonly shardsPerCluster;
+    private readonly clusterToStart;
+    private readonly clusterCalculator;
+    private readonly eventMap;
+    constructor(port: number, token: string, intents: GatewayIntentsString[], shardsPerCluster: number, clusterToStart: number);
+    start(): void;
+    private interval;
+    private checkRecluster;
+    private heartbeat;
+    private checkCreate;
+    private createCluster;
+    startListening(): void;
+    sendMessageToClient(clientId: string, message: unknown): void;
+    private getTotalShards;
+    on<K extends keyof BridgeEventListeners>(event: K, listener: BridgeEventListeners[K]): void;
+    getClusters(): BridgeClientCluster[];
+    stopAllInstances(): Promise<void>;
+    stopAllInstancesWithRestart(): Promise<void>;
+    moveCluster(instance: BridgeClientConnection, cluster: BridgeClientCluster): Promise<void>;
+    stopInstance(instance: BridgeClientConnection, recluster?: boolean): Promise<void>;
+}
+type BridgeEventListeners = {
+    'CLUSTER_READY': ((cluster: BridgeClientCluster, guilds: number, members: number) => void) | undefined;
+    'CLUSTER_STOPPED': ((cluster: BridgeClientCluster) => void) | undefined;
+    'CLUSTER_SPAWNED': ((cluster: BridgeClientCluster, connection: BridgeClientConnection) => void) | undefined;
+    'CLUSTER_RECLUSTER': ((cluster: BridgeClientCluster, newConnection: BridgeClientConnection, oldConnection: BridgeClientConnection) => void) | undefined;
+    'CLUSTER_HEARTBEAT_FAILED': ((cluster: BridgeClientCluster, error: unknown) => void) | undefined;
+    'CLIENT_CONNECTED': ((client: BridgeClientConnection) => void) | undefined;
+    'CLIENT_DISCONNECTED': ((client: BridgeClientConnection, reason: string) => void) | undefined;
+    'ERROR': ((error: string) => void) | undefined;
+    'CLIENT_STOP': ((instance: BridgeClientConnection) => void) | undefined;
+};
+
+/**
+ * Manages the calculation and distribution of clusters for a Discord bot sharding system.
+ * This class is responsible for creating clusters with their assigned shards,
+ * tracking which clusters are in use, and providing methods to retrieve available clusters.
+ */
+declare class ClusterCalculator {
+    /** The total number of clusters to initialize */
+    private readonly clusterToStart;
+    /** The number of shards that each cluster will manage */
+    private readonly shardsPerCluster;
+    /** List of all clusters managed by this calculator */
+    readonly clusterList: BridgeClientCluster[];
+    /**
+     * Creates a new ClusterCalculator and initializes the clusters.
+     *
+     * @param clusterToStart - The number of clusters to create
+     * @param shardsPerCluster - The number of shards each cluster will manage
+     */
+    constructor(clusterToStart: number, shardsPerCluster: number);
+    /**
+     * Calculates and initializes all clusters with their assigned shards.
+     * Each cluster is assigned a sequential range of shard IDs based on its cluster index.
+     */
+    private calculateClusters;
+    /**
+     * Retrieves the next available (unused) cluster and marks it as used.
+     *
+     * @returns The next available cluster, or undefined if all clusters are in use
+     */
+    getNextCluster(): BridgeClientCluster | undefined;
+    /**
+     * Retrieves multiple available clusters up to the specified count.
+     * Each returned cluster is marked as used.
+     *
+     * @param count - The maximum number of clusters to retrieve
+     * @returns An array of available clusters (may be fewer than requested if not enough are available)
+     */
+    getNextClusters(count: number): BridgeClientCluster[];
+    /**
+     * Sets the used status of a specific cluster by its ID.
+     *
+     * @param clusterID - The ID of the cluster to update
+     * @param connection - The connection to associate with the cluster
+     */
+    clearClusterConnection(clusterID: number): void;
+    getClusterForConnection(connection: BridgeClientConnection): BridgeClientCluster[];
+    getOldClusterForConnection(connection: BridgeClientConnection): BridgeClientCluster[];
+    checkAllClustersConnected(): boolean;
+    findMostAndLeastClustersForConnections(connectedClients: BridgeClientConnection[]): {
+        most: BridgeClientConnection | undefined;
+        least: BridgeClientConnection | undefined;
+    };
+    getClusterWithLowestLoad(connectedClients: Map<string, BridgeClientConnection>): BridgeClientConnection | undefined;
+    getClusterOfShard(shardID: number): BridgeClientCluster | undefined;
+}
+
+declare class Cluster<T extends Client> {
+    readonly instanceID: number;
+    readonly clusterID: number;
+    readonly shardList: number[];
+    readonly totalShards: number;
+    readonly token: string;
+    readonly intents: GatewayIntentsString[];
+    eventManager: EventManager;
+    client: T;
+    private readonly eventMap;
+    constructor(instanceID: number, clusterID: number, shardList: number[], totalShards: number, token: string, intents: GatewayIntentsString[]);
+    static initial<T extends Client>(): Cluster<T>;
+    triggerReady(guilds: number, members: number): void;
+    triggerError(e: any): void;
+    private wait;
+    private _onMessage;
+    private _onRequest;
+    on<K extends keyof ClusterEventListeners>(event: K, listener: ClusterEventListeners[K]): void;
+    sendMessage(data: unknown): void;
+    sendRequest(data: unknown, timeout?: number): Promise<unknown>;
+    broadcastEval<Result>(fn: (cluster: T) => Result, timeout?: number): Promise<Result[]>;
+    sendMessageToClusterOfGuild(guildID: string, message: unknown): void;
+    sendRequestToClusterOfGuild(guildID: string, message: unknown, timeout?: number): Promise<unknown>;
+}
+type ClusterEventListeners = {
+    message: (message: unknown) => void;
+    request: (message: unknown, resolve: (data: unknown) => void, reject: (error: any) => void) => void;
+    CLUSTER_READY: () => void;
+};
+
+type ClusterProcessState = 'starting' | 'running' | 'stopped';
+declare class ClusterProcess {
+    readonly child: ChildProcess;
+    readonly eventManager: EventManager;
+    readonly id: number;
+    readonly shardList: number[];
+    readonly totalShards: number;
+    status: ClusterProcessState;
+    readonly createdAt: number;
+    private _onMessage?;
+    private _onRequest?;
+    constructor(id: number, child: ChildProcess, shardList: number[], totalShards: number);
+    onMessage(callback: (message: unknown) => void): void;
+    onRequest(callback: (message: unknown) => unknown): void;
+    sendMessage(data: unknown): void;
+    sendRequest(data: unknown, timeout?: number): Promise<unknown>;
+}
+
+declare class ShardingUtil {
+    static getShardIDForGuild(guildID: string, totalShards: number): number;
+}
+
+declare abstract class BotInstance {
+    private readonly entryPoint;
+    private readonly execArgv;
+    readonly clients: Map<number, ClusterProcess>;
+    protected constructor(entryPoint: string, execArgv?: string[]);
+    protected readonly eventMap: BotInstanceEventListeners;
+    protected startProcess(instanceID: number, clusterID: number, shardList: number[], totalShards: number, token: string, intents: GatewayIntentsString[]): void;
+    protected killProcess(client: ClusterProcess, reason: string): void;
+    protected abstract setClusterStopped(client: ClusterProcess, reason: string): void;
+    protected abstract setClusterReady(client: ClusterProcess, guilds: number, members: number): void;
+    protected abstract setClusterSpawned(client: ClusterProcess): void;
+    abstract start(): void;
+    private onMessage;
+    protected abstract onRequest(client: ClusterProcess, message: any): Promise<unknown>;
+    on<K extends keyof BotInstanceEventListeners>(event: K, listener: BotInstanceEventListeners[K]): void;
+    sendRequestToClusterOfGuild(guildID: string, message: unknown, timeout?: number): Promise<unknown>;
+    sendRequestToCluster(cluster: ClusterProcess, message: unknown, timeout?: number): Promise<unknown>;
+}
+type BotInstanceEventListeners = {
+    'message': ((client: ClusterProcess, message: unknown) => void) | undefined;
+    'request': ((client: ClusterProcess, message: unknown, resolve: (data: unknown) => void, reject: (error: any) => void) => void) | undefined;
+    'PROCESS_KILLED': ((client: ClusterProcess, reason: string, processKilled: boolean) => void) | undefined;
+    'PROCESS_SPAWNED': ((client: ClusterProcess) => void) | undefined;
+    'PROCESS_ERROR': ((client: ClusterProcess, error: unknown) => void) | undefined;
+    'CLUSTER_READY': ((client: ClusterProcess) => void) | undefined;
+    'CLUSTER_ERROR': ((client: ClusterProcess, error: unknown) => void) | undefined;
+    'CLUSTER_RECLUSTER': ((client: ClusterProcess) => void) | undefined;
+    'ERROR': ((error: string) => void) | undefined;
+    'BRIDGE_CONNECTION_ESTABLISHED': (() => void) | undefined;
+    'BRIDGE_CONNECTION_CLOSED': ((reason: string) => void) | undefined;
+    'BRIDGE_CONNECTION_STATUS_CHANGE': ((status: number) => void) | undefined;
+    'INSTANCE_STOP': (() => void) | undefined;
+    'INSTANCE_STOPPED': (() => void) | undefined;
+    'SELF_CHECK_SUCCESS': (() => void) | undefined;
+    'SELF_CHECK_ERROR': ((error: string) => void) | undefined;
+    'SELF_CHECK_RECEIVED': ((data: {
+        clusterList: number[];
+    }) => void) | undefined;
+};
+
+declare enum BridgeConnectionStatus {
+    CONNECTED = 0,
+    DISCONNECTED = 1
+}
+declare class ManagedInstance extends BotInstance {
+    private readonly host;
+    private readonly port;
+    private readonly instanceID;
+    private eventManager;
+    private connectionStatus;
+    private data;
+    private dev;
+    constructor(entryPoint: string, host: string, port: number, instanceID: number, data: unknown, execArgv?: string[], dev?: boolean);
+    start(): void;
+    private selfCheck;
+    protected setClusterStopped(client: ClusterProcess, reason: string): void;
+    protected setClusterReady(client: ClusterProcess, guilds: number, members: number): void;
+    protected setClusterSpawned(client: ClusterProcess): void;
+    private onClusterCreate;
+    private onClusterStop;
+    private onClusterRecluster;
+    protected onRequest(client: ClusterProcess, message: any): Promise<unknown>;
+    private onBridgeRequest;
+    stopInstance(): void;
+}
+
+declare class StandaloneInstance extends BotInstance {
+    private readonly totalClusters;
+    private readonly shardsPerCluster;
+    readonly token: string;
+    readonly intents: GatewayIntentsString[];
+    constructor(entryPoint: string, shardsPerCluster: number, totalClusters: number, token: string, intents: GatewayIntentsString[], execArgv?: string[]);
+    get totalShards(): number;
+    private calculateClusters;
+    start(): void;
+    protected setClusterStopped(client: ClusterProcess, reason: string): void;
+    protected setClusterReady(client: ClusterProcess): void;
+    protected setClusterSpawned(client: ClusterProcess): void;
+    private restartProcess;
+    protected onRequest(client: ClusterProcess, message: any): Promise<unknown>;
+}
+
+export { BotInstance, type BotInstanceEventListeners, Bridge, BridgeClientCluster, BridgeClientClusterConnectionStatus, BridgeClientConnection, BridgeClientConnectionStatus, BridgeConnectionStatus, type BridgeEventListeners, Cluster, ClusterCalculator, type ClusterEventListeners, ClusterProcess, type ClusterProcessState, EventManager, type EventPayload, type HeartbeatResponse, ManagedInstance, ShardingUtil, StandaloneInstance };