> ## Documentation Index
> Fetch the complete documentation index at: https://stars-components.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# @wolfstar/plugin-sharder

> Spread gateway shards across processes, cluster workers, worker threads, and machines.

```bash npm theme={"system"}
npm install @wolfstar/plugin-sharder
```

```bash pnpm theme={"system"}
pnpm add @wolfstar/plugin-sharder
```

```bash yarn theme={"system"}
yarn add @wolfstar/plugin-sharder
```

```bash bun theme={"system"}
bun add @wolfstar/plugin-sharder
```

> [card] [npm](https://npmx.dev/package/@wolfstar/plugin-sharder)

> [card] [Source](https://github.com/wolfstar-project/plugins/tree/main/packages/plugin-sharder)

> [!TIP]
>
> See the [Plugins guide](https://stars-components.js.org/documentation/guide/plugins.md) for how plugins from wolfstar-project/plugins fit alongside the core framework.

## Description

A `GatewayClient` connects its gateway shards from a single process. `@wolfstar/plugin-sharder` spreads them across
processes, cluster workers, worker threads, and machines. It implements the sharder RFC
[discordjs/discord.js#8084](https://github.com/discordjs/discord.js/issues/8084).

A shard is what the manager spawns, and it can connect several gateway shards. The package knows nothing about
Discord's gateway. A shard runs any script that uses `ShardClient`, so it works with
[`@wolfstar/plugin-gateway`](https://stars-components.js.org/documentation/packages/plugin-gateway), `@discordjs/ws`, or another library.

| Piece | Role |
| - | - |
| `ShardManager` | Spawns and supervises the shards, paces their identifies, carries their messages |
| `ShardChannel` | The manager's handle on one shard: status, pings, messages, requests, restarts |
| `ShardClient` | The shard's side: signals its status, sends messages and requests, answers requests |
| `ShardManagerProxy` | Runs shards on another machine for one or several managers |
| `ChannelStrategy` | How shards are spawned: `"fork"` (default), `"cluster"`, `"worker"`, `"network"`, or custom |
| `MessageHandler` | How packets are serialized: `"json"` (default), `"v8"`, `"raw"`, or custom |
| `MessageTransformer` | How serialized packets are transformed, composable: `"gzip"`, `"brotli"`, or custom |

## Usage

The manager and the shards can share one script, because `ShardClient.context` is `null` in the manager:

```ts theme={"system"}
import { GatewayClient } from '@wolfstar/plugin-gateway';
import { ShardClient, ShardManager } from '@wolfstar/plugin-sharder';

if (!ShardClient.context) {
	// Discord's recommended shard count, split across one process per CPU core, forking this script.
	const manager = new ShardManager({ spawn: { delay: 0 } });
	manager.on('shardReady', (channel) => console.log(`Shard ${channel.id} (${channel.shards}) is ready`));
	await manager.spawn();
} else {
	const shard = new ShardClient();
	const client = new GatewayClient({
		...options,
		...shard.gatewayOptions,
		// The manager paces identifies across every process, so the spawn delay can be 0.
		gateway: { buildIdentifyThrottler: () => shard.identifyThrottler }
	});
	// Reuse the manager's GET /gateway/bot instead of requesting it from every process.
	client.gateway.fetchGatewayInformation = () => shard.fetchGatewayInformation();

	shard.setCloseHandler(() => client.destroy());

	let pending = shard.shards.length;
	client.on('shardReady', () => {
		if (--pending === 0) void shard.ready();
	});
	await client.connect();
}
```

## Stars module

On framework 6.1 and later, list the `./module` entry in `modules` in `stars.config` to add the package to the auto
imports. It needs the optional [`@wolfstar/kit`](https://stars-components.js.org/documentation/packages/kit) peer dependency, at `^0.2.0 || ^0.3.0`.

```ts theme={"system"}
// stars.config.ts
export default defineConfig({
	modules: ['@wolfstar/plugin-sharder/module']
});
```

The module registers no plugin and takes no options. It reserves the `sharder` key of `stars.config` for future options,
so no other module can claim it. You still construct the `ShardManager` yourself.

## Layout

| Option | Meaning |
| - | - |
| `shards: 9` | 9 shards of one gateway shard each |
| `shards: [3, 3, 3]` | 3 shards of 3 gateway shards each: 0-2, 3-5, 6-8 |
| `shards: "auto"` | (default) the gateway shards split across `clusters` shards, one per CPU core by default |
| `totalShards` | the total across every manager; `"auto"` is Discord's recommendation |
| `shardList` | the gateway shards this manager runs, when several managers split them |

`"auto"` needs the bot token (`token`, or `DISCORD_TOKEN`) or `gatewayInformation.fetch`. The manager fetches
`GET /gateway/bot` once, caches it for `gatewayInformation.ttl`, and hands it to the shards.

## Messages and requests

Messages are raw data, and a request is a message waiting for a reply:

| From a shard | From the manager | Goes to |
| - | - | - |
| `shard.send(body)` | — | the manager's `message` event |
| `shard.send(body, 2)` | `manager.send(2, body)` | shard 2's `message` event |
| `shard.send(body, "all")` | `manager.broadcast(body)` | every shard |
| `shard.request(body)` | — | the manager's request handler |
| `shard.request(body, { to: 2 })` | `manager.request(2, body)` | shard 2's request handler |
| `shard.broadcastRequest(body)` | `manager.broadcastRequest(body)` | every shard, replies by shard ID |

`broadcastRequest` replaces `broadcastEval` and `fetchClientValues` from discord.js. To share gateway dispatches
between processes, pair it with [`@wolfstar/plugin-broker`](https://stars-components.js.org/documentation/packages/plugin-broker).

[![version](https://npmx.dev/api/registry/badge/version/@wolfstar/plugin-sharder)](https://npmx.dev/package/@wolfstar/plugin-sharder)
[![downloads](https://npmx.dev/api/registry/badge/downloads/@wolfstar/plugin-sharder)](https://npmx.dev/package/@wolfstar/plugin-sharder)
[![license](https://img.shields.io/github/license/wolfstar-project/plugins?style=flat-square\&color=informational)](https://github.com/wolfstar-project/plugins/blob/main/LICENSE)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.