feat: detect sharding mode

Author: twlite

apps/test-bot/src/app/commands/(general)/help.ts

@@ -32,7 +32,7 @@ export const chatInput: ChatInputCommand = async (ctx) => {
         title: 'Help',
         description: commands,
         footer: {
-          text: `Bot Version: ${botVersion}`,
+          text: `Bot Version: ${botVersion} | Shard ID ${interaction.guild?.shardId ?? 'N/A'}`,
         },
         color: 0x7289da,
         timestamp: new Date().toISOString(),

apps/test-bot/src/sharding-manager.ts

@@ -0,0 +1,14 @@
+import { ShardingManager } from 'discord.js';
+import { join } from 'node:path';
+
+process.loadEnvFile('./.env');
+
+const manager = new ShardingManager(join(import.meta.dirname, 'index.js'), {
+  token: process.env.DISCORD_TOKEN,
+  totalShards: 2,
+  mode: 'worker',
+});
+
+manager.on('shardCreate', (shard) => console.log(`Launched shard ${shard.id}`));
+
+await manager.spawn();

apps/website/docs/guide/08-sharding/01-sharding.mdx

@@ -0,0 +1,44 @@
+---
+title: Sharding your bot
+description: Learn how to shard your bot in CommandKit.
+---
+
+# Sharding your bot
+
+Sharding is a method of splitting your bot into multiple processes, or "shards". This is useful for large bots that have a lot of guilds, as it allows you to distribute the load across multiple processes. Discord actually requires sharding for bots in more than 2,500 guilds, so understanding how to implement it is crucial as your bot grows.
+
+Sharding is a built-in feature of discord.js, and CommandKit does not alter the way sharding works. In this guide, we will cover how to shard your bot using CommandKit. To learn more about sharding in discord.js, check out the [discord.js documentation](https://discordjs.guide/sharding).
+
+## When to use sharding
+
+You should consider implementing sharding in the following scenarios:
+
+- Your bot is in, or approaching, 2,500 guilds (required by Discord)
+- You're experiencing memory or performance issues with a single process
+- You want to distribute your bot's workload across multiple cores/machines
+- You're planning for future scaling of your bot
+
+## Creating a sharding manager file
+
+You can simply create a new file in your source directory named `sharding-manager.ts` and CommandKit will automatically detect it and use it as the sharding manager. This file will be responsible for creating the shards and managing them.
+
+```ts
+import { ShardingManager } from 'discord.js';
+import { join } from 'node:path';
+
+process.loadEnvFile('./.env');
+
+const manager = new ShardingManager(join(import.meta.dirname, 'index.js'), {
+  token: process.env.DISCORD_TOKEN,
+  totalShards: 2,
+  mode: 'worker',
+});
+
+manager.on('shardCreate', (shard) => console.log(`Launched shard ${shard.id}`));
+
+await manager.spawn();
+```
+
+:::info
+If you're confused about `index.js` being used, this is an autogenerated entrypoint file that sets up the CommandKit environment. When running `commandkit start` or `commandkit dev`, CommandKit automatically detects the entrypoint file (either `sharding-manager.js` or `index.js`) and loads it.
+:::

packages/cache/src/use-cache.ts

@@ -11,7 +11,7 @@ const fnStore = new Map<
   {
     key: string;
     hash: string;
-    ttl: number;
+    ttl?: number;
     original: GenericFunction;
     memo: GenericFunction;
   }
@@ -28,7 +28,7 @@ export interface CacheContext {
     /** Custom name for the cache entry */
     name?: string;
     /** Time-to-live in milliseconds */
-    ttl?: number;
+    ttl?: number | null;
   };
 }
 
@@ -84,7 +84,7 @@ function useCache<R extends any[], F extends AsyncFunction<R>>(
       {
         params: {
           name: keyHash,
-          ttl: resolvedTTL ?? DEFAULT_TTL,
+          ttl: resolvedTTL,
         },
       },
       async () => {
@@ -110,16 +110,16 @@ function useCache<R extends any[], F extends AsyncFunction<R>>(
         if (result != null) {
           // Get the final key name (might have been modified by cacheTag)
           const finalKey = context.params.name!;
-          const ttl = context.params.ttl ?? DEFAULT_TTL;
+          const ttl = context.params.ttl;
 
           // Store the result
-          await provider.set(finalKey, result, ttl);
+          await provider.set(finalKey, result, ttl ?? undefined);
 
           // Update function store
           fnStore.set(keyHash, {
             key: finalKey,
             hash: keyHash,
-            ttl,
+            ttl: ttl ?? undefined,
             original: fn,
             memo,
           });
@@ -210,7 +210,7 @@ export function cacheLife(ttl: number | string): void {
   }
 
   if (ttl == null || !['string', 'number'].includes(typeof ttl)) {
-    throw new Error('cacheLife() must be called with a ttl.');
+    throw new Error('cacheLife() must be called with a ttl value.');
   }
 
   context.params.ttl = typeof ttl === 'string' ? ms(ttl) : ttl;

packages/commandkit/src/cli/common.ts

@@ -13,6 +13,15 @@ export function write(message: any) {
   process.stdout.write('\n');
 }
 
+export function findEntrypoint(dir: string) {
+  const target = join(dir, 'sharding-manager.js');
+
+  // if sharding manager exists, return that file instead
+  if (fs.existsSync(target)) return target;
+
+  return join(dir, 'index.js');
+}
+
 /**
  * @returns {never}
  */

packages/commandkit/src/cli/development.ts

@@ -10,10 +10,11 @@ import { ChildProcess } from 'node:child_process';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { randomUUID } from 'node:crypto';
 import { HMREventType } from '../utils/constants';
+import { findEntrypoint } from './common';
 
 async function buildAndStart(configPath: string, skipStart = false) {
   const config = await loadConfigFile(configPath);
-  const mainFile = join('.commandkit', 'index.js');
+  const mainFile = findEntrypoint('.commandkit');
 
   await buildApplication({
     configPath,

packages/commandkit/src/cli/production.ts

@@ -2,7 +2,7 @@ import { join } from 'path';
 import { loadConfigFile } from '../config/loader';
 import { createAppProcess } from './app-process';
 import { existsSync } from 'fs';
-import { panic } from './common';
+import { findEntrypoint, panic } from './common';
 import { buildApplication } from './build';
 import { CompilerPlugin, isCompilerPlugin } from '../plugins';
 import { createSpinner } from './utils';
@@ -11,7 +11,7 @@ export async function bootstrapProductionServer(configPath?: string) {
   process.env.COMMANDKIT_BOOTSTRAP_MODE = 'production';
   const cwd = configPath || process.cwd();
   const config = await loadConfigFile(cwd);
-  const mainFile = join(config.distDir, 'index.js');
+  const mainFile = findEntrypoint(config.distDir);
 
   if (!existsSync(mainFile)) {
     panic(

packages/devtools/src/server/app.ts

@@ -2,9 +2,8 @@ import { join } from 'node:path';
 import { api } from './api';
 import express from 'express';
 import { Server } from 'node:http';
-import CommandKit from 'commandkit';
+import CommandKit, { Logger } from 'commandkit';
 import { setCommandKit, setConfig } from './store';
-import type { Client } from 'discord.js';
 import cors from 'cors';
 
 const staticDir = join(__dirname, '..', '..', 'ui');
@@ -26,9 +25,39 @@ export async function startServer(
 ) {
   setCommandKit(commandkit);
   setConfig({ credential });
-  return new Promise<Server>((resolve) => {
-    const server = app.listen(port, () => {
-      resolve(server);
-    });
+
+  let currentPort = port;
+  const maxRetries = 10; // Limit the number of retries to prevent infinite loop
+  let retries = 0;
+
+  return new Promise<Server>((resolve, reject) => {
+    function attemptToListen() {
+      try {
+        const server = app.listen(currentPort, () => {
+          resolve(server);
+        });
+
+        server.on('error', (error: NodeJS.ErrnoException) => {
+          // Handle specific error for port already in use
+          if (error.code === 'EADDRINUSE' && retries < maxRetries) {
+            Logger.warn(
+              `Port ${currentPort} is already in use, trying port ${currentPort + 1}`,
+            );
+            currentPort++;
+            retries++;
+            attemptToListen();
+          } else {
+            // For other errors or if we've exceeded max retries
+            Logger.error('Server failed to start:', error);
+            reject(error);
+          }
+        });
+      } catch (error) {
+        Logger.error('Unexpected error starting server:', error);
+        reject(error);
+      }
+    }
+
+    attemptToListen();
   });
 }

packages/redis/src/index.ts

@@ -68,7 +68,7 @@ export class RedisCache extends CacheProvider {
       return undefined;
     }
 
-    return JSON.parse(value) as T;
+    return this.deserialize(value) as T;
   }
 
   /**
@@ -78,12 +78,14 @@ export class RedisCache extends CacheProvider {
    * @param ttl The time-to-live for the cache entry in milliseconds.
    */
   public async set<T>(key: string, value: T, ttl?: number): Promise<void> {
-    const serialized = await this.serialize(value);
+    const serialized = this.serialize(value);
+    const finalValue =
+      serialized instanceof Promise ? await serialized : serialized;
 
     if (typeof ttl === 'number') {
-      await this.redis.set(key, serialized, 'PX', ttl);
+      await this.redis.set(key, finalValue, 'PX', ttl);
     } else {
-      await this.redis.set(key, serialized);
+      await this.redis.set(key, finalValue);
     }
   }