@wolfstar/plugin-sharder 0.0.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,344 @@
+<div align="center">
+
+<img src="https://cdn.wolfstar.rocks/wolfstar-assets/wolfstar.png" alt="WolfStar" width="100" />
+
+# @wolfstar/plugin-sharder
+
+**Multi-process and multi-machine sharding for `@wolfstar/plugin-gateway`, or any bot.**
+
+[![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)
+
+</div>
+
+## Description
+
+A `GatewayClient` connects its gateway shards from a single process. This package spreads them
+across processes, cluster workers, worker threads, and machines. It implements the sharder RFC of
+discord.js, [discordjs/discord.js#8084](https://github.com/discordjs/discord.js/issues/8084), with
+the answers given in its thread, and the two implementations drafted for it,
+[discordjs/discord.js#7204](https://github.com/discordjs/discord.js/pull/7204) and
+[discordjs/discord.js#8859](https://github.com/discordjs/discord.js/pull/8859). See
+[RFC alignment](#rfc-alignment) for how each point maps to this package.
+
+As in the RFC, a **shard** is what the manager spawns (a process, a cluster worker, a worker
+thread, or a process on another machine), and it may connect several gateway shards. The manager
+talks to each shard through a `ShardChannel`. The package knows nothing about Discord's gateway:
+a shard runs any script using `ShardClient`, so it works with `@wolfstar/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, messages and requests, answers requests                      |
+| `ShardManagerProxy`  | Runs shards on another machine for one or several managers, and talks to other proxies             |
+| `ChannelStrategy`    | How shards are spawned: `"fork"` (default), `"cluster"`, `"worker"`, `"network"`, or your own      |
+| `MessageHandler`     | How packets are serialized: `"json"` (default), `"v8"`, `"raw"`, or your own                       |
+| `MessageTransformer` | How serialized packets are transformed, composable: `"gzip"`, `"brotli"`, or your own (encryption) |
+
+## Installation
+
+```bash
+pnpm add @wolfstar/plugin-sharder
+```
+
+## Usage
+
+The manager and the shards can share one script: `ShardClient.context` is `null` in the manager.
+
+```ts
+// bot.ts
+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,
+    // Identifies are paced by the manager across every process, so the spawn delay can be 0.
+    gateway: { buildIdentifyThrottler: () => shard.identifyThrottler },
+  });
+  // Reuse the manager's GET /gateway/bot rather than requesting it again from every process.
+  client.gateway.fetchGatewayInformation = () => shard.fetchGatewayInformation();
+
+  const guilds = new Set<string>();
+  client.on("guildCreate", (guild) => guilds.add(guild.id));
+  client.on("guildDelete", (_guild, data) => guilds.delete(data.id));
+  shard.setRequestHandler((body: { type: string }) => {
+    if (body.type === "guildCount") return guilds.size;
+    throw new Error(`Unknown request ${body.type}`);
+  });
+  shard.setCloseHandler(() => client.destroy());
+
+  let pending = shard.shards.length;
+  client.on("shardReady", () => {
+    if (--pending === 0) void shard.ready();
+  });
+  await client.connect();
+}
+```
+
+### 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 (default: one per CPU core)        |
+| `totalShards`       | the total across every manager; `"auto"` is Discord's recommendation (`recommended` rounds it) |
+| `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 and caches it for `gatewayInformation.ttl`, keeping its
+session start limit up to date with the identifies it grants, and hands it to the shards
+(`shard.fetchGatewayInformation()`). A `token` given to the manager is passed to the shards as
+`DISCORD_TOKEN`.
+
+### 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 discord.js's `broadcastEval` and `fetchClientValues`. With
+`{ partial: true }` it resolves with the outcome of every shard, like `Promise.allSettled`, so the
+replies that came before a timeout or a failure are kept.
+
+A request rejects with a `ShardRequestTimeoutError` past its timeout (the manager's
+`requestTimeout`, by default the ping timeout), and with the reason of its `signal` when aborted.
+Either way the other side is told, and the `signal` of its handler aborts, e.g. to cancel an HTTP
+request. A request aborted while it waits for a shard to be ready never leaves the queue. A
+throwing or missing handler rejects the request with a `ShardRequestError` carrying the remote
+error's name and message.
+
+A message or request for a shard that is not ready waits for it, within its timeout. With
+`spawn.readyHint` (or, without it, the average time the shards took so far), a request for a
+starting shard that is not expected to be ready before its timeout fails right away, and a shard
+slower than the estimate is emitted as `shardSlowStart`.
+
+The sharder has no command format and no `eval`, as the RFC settled. `createCommandHandler` and
+`command` are an optional, typed layer on top:
+
+```ts
+const commands = { guildCount: () => guilds.size, guild: (id: string) => guilds.has(id) };
+shard.setRequestHandler(createCommandHandler(commands));
+
+const counts = await manager.broadcastRequest<CommandReply<typeof commands, "guildCount">>(
+  command<typeof commands>("guildCount"),
+);
+```
+
+### `Result<T, E>`
+
+Every operation that can fail has a `try*` twin resolving with a `Result` of
+[`@sapphire/result`](https://www.npmjs.com/package/@sapphire/result) (re-exported as `Result`)
+rather than rejecting, as suggested in the RFC thread: `trySend`, `tryRequest`, and
+`tryBroadcastRequest` on the manager, channels, and shards, and `tryControl` on shards. The error is
+a `ShardError`. `tryBroadcastRequest` resolves with one `Result` per shard. A request handler may
+return a `Result` as well: `Ok` is the reply, and `Err` the error the requester gets.
+
+```ts
+shard.setRequestHandler((id: string) =>
+  guilds.has(id) ? Result.ok(guilds.get(id)) : Result.err(new RangeError("Unknown guild")),
+);
+
+const guild = await manager.tryRequest(0, guildId);
+guild.match({ ok: (value) => console.log(value), err: (error) => console.error(error.message) });
+const counts = await manager.tryBroadcastRequest<number>({ type: "guildCount" });
+const total = counts.reduce((sum, count) => sum + count.unwrapOr(0), 0);
+```
+
+### Lifecycle and supervision
+
+A shard signals its status, and the manager emits it:
+
+| Status         | Set by                            | When the process stops              |
+| -------------- | --------------------------------- | ----------------------------------- |
+| `Starting`     | `new ShardClient()`               | restarted, if the supervisor allows |
+| `Ready`        | `shard.ready()`                   | restarted, if the supervisor allows |
+| `Disconnected` | `shard.disconnected()`            | restarted, if the supervisor allows |
+| `Reconnecting` | `shard.reconnecting()`            | restarted, if the supervisor allows |
+| `Exiting`      | `shard.exit()`                    | not restarted                       |
+| `Restarting`   | `shard.restart()`                 | restarted, always                   |
+| `Idle`         | the manager, when no process runs | —                                   |
+
+Crashes go through a supervisor modelled on Erlang/OTP's: a shard crashing more than
+`supervisor.intensity` times within `supervisor.period` milliseconds is given up on and emitted as
+`shardGiveUp` (with `period: 0`, the default, the crashes are counted in a row until the shard is
+ready again, and `intensity: -1`, the default, never gives up). `supervisor.strategy` picks what
+else restarts: `"one-for-one"` (the default), `"one-for-all"`, or `"rest-for-one"`. A shard that
+fails before it is ready (the RFC's `error` signal) is emitted as `shardError` with a
+`ShardSpawnError`.
+
+Shards start one at a time, `spawn.delay` apart. One that is not ready within `spawn.timeout` is
+killed and tried again at the end of the queue. The manager pings every ready shard each
+`ping.interval` (`delaySinceReceived` counts from the last answer instead); one that stops
+answering for `ping.timeout` is emitted as `shardUnresponsive`, or restarted when nothing listens.
+`channel.ping` has the latency and the timestamps.
+
+`manager.restart(id)` and `manager.destroy()` first ask the shard to close, which runs its close
+handler, and kill it past the timeout. `manager.restart(id, { rolling: true })` spawns the new shard
+first and closes the old one once the new one is ready, for close to no downtime;
+`manager.reshard(layout)` does the same for a whole new layout. When the manager dies, a process
+shard emits `disconnect` and exits when nothing listens to it; a worker thread stops with it.
+
+### Gateway shards
+
+The manager paces identifies across every process: `shard.identifyThrottler` is `@discordjs/ws`'s
+`IIdentifyThrottler`, and the manager grants one identify per `max_concurrency` bucket every
+`identify.delay` (5 seconds). Within a shard, `setShardHandler({ start, close })` lets the manager
+start and close single gateway shards (`manager.startShard(id)`, `closeShard`, `restartShard`), and
+`shard.control()` asks the manager to start, close, or restart shards or gateway shards:
+
+```ts
+shard.setShardHandler({ start: (id) => connect(id), close: (id) => disconnect(id) });
+await shard.control({ action: "restart", target: { shard: 12 } });
+await shard.control({ action: "restart", target: { channel: "all" } });
+```
+
+### Strategies
+
+| Strategy                  | Shards are                        | Notes                                                                      |
+| ------------------------- | --------------------------------- | -------------------------------------------------------------------------- |
+| `ForkStrategy` (`"fork"`) | child processes                   | The default. Ports must differ per shard. Defaults to the manager's script |
+| `ClusterStrategy`         | `node:cluster` workers            | Ports are shared and balanced. Defaults to the manager's script            |
+| `WorkerStrategy`          | worker threads                    | Fastest messages, but one crash of the process stops every shard           |
+| `NetworkStrategy`         | processes of `ShardManagerProxy`s | Other machines, over TLS (or plain TCP on trusted networks)                |
+
+A strategy can be given by name, built with `strategyOptions`, and custom ones are registered with
+`registerStrategy`. `channel.pid`, `channel.threadId`, and `channel.host` identify each shard.
+
+### Several machines
+
+The manager listens with a `NetworkStrategy`, and a `ShardManagerProxy` on each machine connects to
+it, spawns the shards it is given with its own strategy, and carries their messages:
+
+```ts
+// On the manager's machine.
+const manager = new ShardManager({
+  strategy: new NetworkStrategy({
+    port: 7000,
+    token: process.env.SHARDER_TOKEN!,
+    tls: { key, cert },
+  }),
+  totalShards: "auto",
+  clusters: 16,
+});
+await manager.spawn();
+
+// On every other machine.
+const proxy = new ShardManagerProxy({
+  managers: ["manager.internal:7000", "manager-backup.internal:7000"],
+  token: process.env.SHARDER_TOKEN!,
+  tls: { ca },
+  capacity: 8,
+  strategy: new ForkStrategy({ path: "./bot.js" }),
+});
+await proxy.connect();
+```
+
+Spawns go to the connected proxy with the most room, as the proxies report it, and wait when every
+proxy is full or none is connected. A proxy losing a manager keeps its shards (`managerLoss:
+"keep"`, the default, or `"exit"`) and reconnects; back within the manager's `reconnectGrace`, it
+keeps its shards, and past it they are spawned elsewhere and its stale ones killed. Proxies coming
+back are not rebalanced: they take the next spawns.
+
+A proxy serves its managers in one of two modes:
+
+- `mode: "failover"` (the default): one manager at a time, the first reachable of `managers`,
+  failing over to the next ones when it loses it, e.g. a primary and a standby manager.
+- `mode: "all"`: every manager of `managers` at once, sharing its `capacity` between them, e.g.
+  managers each running part of the gateway shards (`shardList`). Each manager can have its own
+  `token` and `tls`, and gets its own `id` (`NetworkStrategy`'s `id` option), which keeps the
+  shards of different managers apart.
+
+Messages and requests between two shards of the same manager and the same proxy never go through
+the manager. With `peer`, proxies also talk to each other: each listens for peer connections, the
+manager tells every proxy which proxy runs which ready shard, and the messages and requests between
+shards of different proxies go from one proxy to the other directly. The first one to a new proxy
+goes through the manager while the peer connection opens; a packet for a shard that moved or is not
+ready is sent back and goes through the manager; a peer connection lost fails the requests waiting
+on it right away.
+
+```ts
+const proxy = new ShardManagerProxy({
+  managers: ["north.internal:7000", "south.internal:7000"],
+  mode: "all",
+  token: process.env.SHARDER_TOKEN!,
+  capacity: 16,
+  strategy: new ForkStrategy({ path: "./bot.js" }),
+  peer: { port: 7001, advertise: "den.internal", tls: { key, cert }, connectTls: { ca } },
+});
+```
+
+### Serialization and transformers
+
+The manager tells its shards the names of its message handler and transformers, and they build the
+same ones from the registry: custom ones must be registered on both sides, with
+`registerMessageHandler` / `registerMessageTransformer` (or `ShardClient.registerMessageHandler` /
+`ShardClient.registerMessageTransformer`, as in the RFC). Transformers write in their order and read
+in the reverse one, so `["gzip", "aes"]` compresses then encrypts; they are async, and get the
+channel they work for. `"v8"` keeps `Map`s, `Set`s, `Date`s, `BigInt`s, and typed arrays, which
+JSON loses; `"raw"` passes values as they are to channels that clone them (worker threads, process
+IPC), without transformers or the network.
+
+```ts
+ShardClient.registerMessageTransformer("aes", () => new AesTransformer(process.env.SHARDER_KEY!));
+const manager = new ShardManager({ messageHandler: "v8", transformers: ["gzip", "aes"] });
+```
+
+## RFC alignment
+
+| Source         | Point                                                                   | Here                                                                                  |
+| -------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
+| RFC            | `ShardManager` with a strategy, by instance or name                     | `strategy` (instance or name) and `registerStrategy`                                  |
+| RFC            | Worker, Fork (default), Cluster, Network strategies                     | `WorkerStrategy`, `ForkStrategy`, `ClusterStrategy`, `NetworkStrategy`                |
+| RFC            | Manager configures the clients through the environment                  | `ShardContext` in `WOLFSTAR_SHARDER` (or worker data), `DISCORD_TOKEN`                |
+| RFC            | Lifecycle events, invalid messages printed when unhandled               | `shardCreate` … `shardInvalidMessage`, `console.error` fallbacks                      |
+| RFC            | Missing pings restart the shard when unhandled                          | `shardUnresponsive`, restart without listeners                                        |
+| RFC            | Requests time out within the ping timeout, globally or per request      | `requestTimeout` (defaults to `ping.timeout`), `timeout` per request                  |
+| RFC            | `ShardClient` signals: Starting, Ready, Exit, Restarting                | `ShardStatus` (plus #7204's `Disconnected` and `Reconnecting`)                        |
+| RFC            | `registerMessageHandler` / `registerMessageTransformer`                 | `ShardClient.register*` and the module-level registries                               |
+| RFC            | JSON and V8 message handlers                                            | `JsonMessageHandler`, `V8MessageHandler` (plus #7204's `RawMessageHandler`)           |
+| RFC            | Composable transformers, reverse order when reading, Gzip and Brotli    | `MessageTransformer` with its channel context, `GzipTransformer`, `BrotliTransformer` |
+| RFC            | `ShardManagerProxy` over an encrypted network, local routing            | `ShardManagerProxy`, TLS, messages between its shards routed locally                  |
+| RFC answers    | Raw data, no `eval`; opt-in replies with timeouts; async transformers   | Messages vs requests, `RequestOptions`, async `write`/`read`                          |
+| RFC answers    | Cancel requests, dequeue them, `AbortController` in shards              | `signal`, dropped from the ready queue, `signal` in handlers                          |
+| RFC answers    | Partial results of aborted broadcasts                                   | `broadcastRequest(body, { partial: true })`                                           |
+| RFC answers    | Enqueue messages for shards not ready, with a ready-time hint           | `waitForReady`, `spawn.readyHint` (or measured), early failure, `shardSlowStart`      |
+| RFC answers    | `error` signal when a shard fails before ready                          | `shardError` with `ShardSpawnError`                                                   |
+| RFC answers    | Configurable restart limits, alerts, Erlang supervisors                 | `supervisor` intensity, period, strategy; `shardGiveUp`                               |
+| RFC answers    | Manager death: configurable, default die                                | `disconnect` event, exit without listeners; proxy `managerLoss`                       |
+| RFC answers    | Proxies: capacity, queue when full, failover managers, no rebalancing   | `capacity` with `Load` reports, pending spawns, `managers` list, `reconnectGrace`     |
+| RFC answers    | `Result<T, E>` instead of `try`/`catch`                                 | `try*` methods, handlers returning a `Result`, `ShardError`                           |
+| RFC answers    | Proxies with several managers                                           | `mode: "failover"` or `mode: "all"`, per-manager `token`, `tls`, and `id`             |
+| RFC            | Proxies routing to shards they host, and to other proxies (P2P)         | Local routing, `peer` connections, the manager's directory of ready shards            |
+| RFC answers    | Optional built-in command layer                                         | `createCommandHandler`, `command`                                                     |
+| RFC answers    | Identify processes and threads for observability                        | `channel.pid`, `threadId`, `host`; worker threads named `shard <id>`                  |
+| #7204          | `totalShards`, `shardList`, `clusters` (CPU count), `"auto"`            | Layout options                                                                        |
+| #7204          | Respawn budget that resets on ready                                     | `supervisor` with `period: 0`                                                         |
+| #7204          | Fetch `/gateway/bot` once in the manager and share it                   | `gatewayInformation`, `shard.fetchGatewayInformation()`                               |
+| #7204          | `fetchRecommendedShards` with `guildsPerShard` and `multipleOf`         | `fetchRecommendedShardCount`, `recommended`                                           |
+| #7204          | Ping with `delaySinceReceived`                                          | `ping.delaySinceReceived`                                                             |
+| #7204 / #8859  | Restart all shards, spawn delay after ready, spawn timeout then requeue | `restartAll`, `spawn.delay`, `spawn.timeout`                                          |
+| #8859          | Manager-side "channel" to each shard                                    | `ShardChannel`, `manager.channels`                                                    |
+| #8859          | Start, close, restart single gateway shards, from the manager or shards | `setShardHandler`, `startShard` & co., `shard.control()`                              |
+| #8859          | Strategies with `init` and `destroy`                                    | `ChannelStrategy.init` / `destroy`                                                    |
+| #7204 comments | Cross-process identify pacing, minimal-downtime restarts and resharding | `identifyThrottler`, `restart(id, { rolling })`, `reshard()`                          |