From 89af4ad77e168d35a287568104dfd54df23236a3 Mon Sep 17 00:00:00 2001 From: RedStar Date: Fri, 13 Nov 2026 17:21:14 +0100 Subject: [PATCH] feat(plugin-gateway): add dispatch wrappers and destroy hooks addDispatchWrapper runs code around the processing of each dispatch received from Discord, so a tracing span or an AsyncLocalStorage store covers the cache writes and the listeners. addDestroyHook runs at the end of every destroy(), once the shards are disconnected and the dispatches processed, to flush what is left before the process exits. Refs #261 --- .changeset/gateway-dispatch-wrappers.md | 5 + packages/plugin-gateway/README.md | 25 +++ packages/plugin-gateway/src/GatewayClient.ts | 119 ++++++++++- packages/plugin-gateway/tests/hooks.test.ts | 209 +++++++++++++++++++ 4 files changed, 349 insertions(+), 9 deletions(-) create mode 100644 .changeset/gateway-dispatch-wrappers.md create mode 100644 packages/plugin-gateway/tests/hooks.test.ts diff --git a/.changeset/gateway-dispatch-wrappers.md b/.changeset/gateway-dispatch-wrappers.md new file mode 100644 index 00000000..4eea127a --- /dev/null +++ b/.changeset/gateway-dispatch-wrappers.md @@ -0,0 +1,5 @@ +--- +"@wolfstar/plugin-gateway": minor +--- + +`GatewayClient#addDispatchWrapper` runs code around the processing of each dispatch received from Discord, such as a tracing span or an `AsyncLocalStorage` store that the cache writes and listeners run in, and `GatewayClient#addDestroyHook` runs a hook at the end of every `destroy()`, once the shards are disconnected and the dispatches processed, to flush what is left before the process exits. diff --git a/packages/plugin-gateway/README.md b/packages/plugin-gateway/README.md index 9c4b4b48..674192aa 100644 --- a/packages/plugin-gateway/README.md +++ b/packages/plugin-gateway/README.md @@ -246,6 +246,31 @@ transport.receive(async ({ payload, shardId, state }) => { [`@wolfstar/plugin-broker`](https://www.npmjs.com/package/@wolfstar/plugin-broker) wires this up over Redis Streams with `forwardGatewayDispatches` and `replayGatewayDispatches`. +### Wrapping dispatches and shutting down + +`client.addDispatchWrapper(wrapper)` runs code around the processing of each dispatch received from Discord, for what +an event cannot do: a tracing span that the cache writes and listeners become children of, or an `AsyncLocalStorage` +store they can read. The wrapper gets `{ payload, shardId, partition }` and a `run` function, which it must call once +and return or await. `run` rejects when the processing fails, and the client still reports the failure through `error`. +Wrappers nest in the order they were added, the first one outermost. Dispatches replayed with `replayDispatch` are not +wrapped. + +`client.addDestroyHook(hook)` runs a hook at the end of every `client.destroy()`, once the shards are disconnected and +every dispatch is processed, even when disconnecting failed: the place to flush what is left to export before the +process exits. A hook that throws is reported through `error` and does not stop the next ones. + +Both return a function that removes what they added. + +```ts +import { AsyncLocalStorage } from "node:async_hooks"; + +const dispatchContext = new AsyncLocalStorage<{ type: string; shardId: number }>(); +client.addDispatchWrapper(({ payload, shardId }, run) => + dispatchContext.run({ type: payload.t, shardId }, run), +); +client.addDestroyHook(() => metrics.flush()); +``` + ## Listeners Since `GatewayClient` emits on the client itself, gateway events are handled by regular listener diff --git a/packages/plugin-gateway/src/GatewayClient.ts b/packages/plugin-gateway/src/GatewayClient.ts index 22f26ec1..683e3b77 100644 --- a/packages/plugin-gateway/src/GatewayClient.ts +++ b/packages/plugin-gateway/src/GatewayClient.ts @@ -325,6 +325,37 @@ export interface GatewayClientDestroyOptions { resumable?: boolean; } +/** + * The dispatch a {@link DispatchWrapper} wraps. + */ +export interface WrappedDispatch { + /** The payload Discord sent. */ + payload: GatewayDispatchPayload; + /** The gateway shard it came from. */ + shardId: number; + /** The partition it is ordered in (`guild:`, `channel:`...), or `null` for one ordered by shard only. */ + partition: string | null; +} + +/** + * Wraps the processing of each dispatch, for code that has to run around it rather than react to an event: a tracing + * span the cache and listener work becomes the child of, a timer, an `AsyncLocalStorage` store. + * + * @param dispatch The dispatch being processed. + * @param run Processes it: writes it into the cache and emits its events. Call it exactly once and return (or await) + * its promise. It rejects when the processing fails, which the client then reports as for any dispatch. + */ +export type DispatchWrapper = ( + dispatch: WrappedDispatch, + run: () => Promise, +) => Promise; + +/** + * Runs at the end of {@link GatewayClient.destroy}, once the shards are disconnected and every dispatch is processed: + * flushing what is left to export, such as traces, before the process exits. + */ +export type GatewayClientDestroyHook = () => unknown; + /** * A {@link Client} that, on top of serving HTTP interactions, connects to the Discord gateway, writes every dispatch * into its cache, and emits {@link GatewayEventMap} events carrying structures. @@ -508,6 +539,11 @@ export class GatewayClient extends Client { // The `destroy` in progress, which a concurrent call joins instead of changing `#keepSessions` under it. #destroying: Promise | null = null; + // See `addDispatchWrapper`: the first added is the outermost. + #dispatchWrappers: readonly DispatchWrapper[] = []; + + readonly #destroyHooks = new Set(); + public constructor(options: GatewayClientOptions) { super(options); container.gatewayClient = this; @@ -627,18 +663,70 @@ export class GatewayClient extends Client { } private async disconnect(resumable: boolean): Promise { - this.#keepSessions = resumable; try { - // Discord invalidates the session of a connection closed with 1000 or 1001, the default is 1000. - await this.gateway.destroy( - this.#keepSessions ? { code: CloseCodes.Resuming, reason: "Resumable shutdown" } : {}, - ); + this.#keepSessions = resumable; + try { + // Discord invalidates the session of a connection closed with 1000 or 1001, the default is 1000. + await this.gateway.destroy( + this.#keepSessions ? { code: CloseCodes.Resuming, reason: "Resumable shutdown" } : {}, + ); + } finally { + this.#keepSessions = false; + } + + await this.#sessions?.flush(); + await this.idle(); } finally { - this.#keepSessions = false; + // Even when disconnecting failed: the process is likely to exit next, and what is left should still go out. + await this.#runDestroyHooks(); } + } + + /** + * Wraps the processing of every dispatch received from now on, see {@link DispatchWrapper}. + * + * @remarks + * Wrappers nest in the order they were added: the first one added is the outermost. The dispatch timeout and the + * error reporting of the client are outside of every wrapper. + * + * @param wrapper The wrapper. + * @returns A function that removes the wrapper, for the dispatches received after it is called. + */ + public addDispatchWrapper(wrapper: DispatchWrapper): () => void { + this.#dispatchWrappers = [...this.#dispatchWrappers, wrapper]; + return () => { + this.#dispatchWrappers = this.#dispatchWrappers.filter((entry) => entry !== wrapper); + }; + } + + /** + * Runs a hook at the end of every {@link GatewayClient.destroy}, see {@link GatewayClientDestroyHook}. + * + * @remarks + * The hooks run one after the other, in the order they were added, even when disconnecting the shards failed. A hook + * that throws is reported through the `error` event (or logged when nothing listens) and does not stop the others. + * Adding the same function twice adds it once. + * + * @param hook The hook. + * @returns A function that removes the hook. + */ + public addDestroyHook(hook: GatewayClientDestroyHook): () => void { + this.#destroyHooks.add(hook); + return () => { + this.#destroyHooks.delete(hook); + }; + } - await this.#sessions?.flush(); - await this.idle(); + async #runDestroyHooks(): Promise { + // A copy: a hook added while the hooks run waits for the next destroy. + for (const hook of Array.from(this.#destroyHooks)) { + try { + await hook(); + } catch (error) { + if (this.listenerCount("error") > 0) this.emit("error", error); + else this.logger.error("[Gateway] A destroy hook failed:", error); + } + } } /** @@ -1262,7 +1350,7 @@ export class GatewayClient extends Client { timer?.unref?.(); try { - await this.handleDispatch(payload, shardId); + await this.#wrapDispatch({ payload, shardId, partition }); } catch (error) { this.reportError(error, payload.t, shardId); } finally { @@ -1270,6 +1358,19 @@ export class GatewayClient extends Client { } } + #wrapDispatch(dispatch: WrappedDispatch): Promise { + let run = () => this.handleDispatch(dispatch.payload, dispatch.shardId); + // Read once, so a wrapper added or removed meanwhile only changes the next dispatches. + const wrappers = this.#dispatchWrappers; + for (let index = wrappers.length - 1; index >= 0; index--) { + const wrapper = wrappers[index]!; + const inner = run; + run = () => wrapper(dispatch, inner); + } + + return run(); + } + private sessionCallbacks( options: GatewayClientOptions, ): Pick { diff --git a/packages/plugin-gateway/tests/hooks.test.ts b/packages/plugin-gateway/tests/hooks.test.ts new file mode 100644 index 00000000..2c7c03ce --- /dev/null +++ b/packages/plugin-gateway/tests/hooks.test.ts @@ -0,0 +1,209 @@ +import { AsyncLocalStorage } from "node:async_hooks"; +import { WebSocketShardEvents } from "@discordjs/ws"; +import { createInMemoryCache } from "@wolfstar/plugin-cache"; +import { + GatewayDispatchEvents, + GatewayOpcodes, + type APIUser, + type GatewayDispatchPayload, +} from "discord-api-types/v10"; +import { afterEach, describe, expect, test, vi } from "vitest"; +import { GatewayClient, type WrappedDispatch } from "../src/index.js"; + +const user: APIUser = { + id: "266624760782258186", + username: "wolf", + discriminator: "0", + global_name: null, + avatar: null, +}; + +function createClient() { + return new GatewayClient({ + discordPublicKey: "0".repeat(64), + discordToken: "test-token", + clientId: "266624760782258186", + intents: 0, + cache: createInMemoryCache(), + }); +} + +function send(client: GatewayClient, id: string, shardId = 0) { + const payload = { + op: GatewayOpcodes.Dispatch, + s: 1, + t: GatewayDispatchEvents.MessageCreate, + d: { + id, + channel_id: "20", + guild_id: "10", + author: user, + content: id, + mentions: [], + mention_roles: [], + attachments: [], + embeds: [], + timestamp: "2024-01-01T00:00:00.000Z", + edited_timestamp: null, + type: 0, + }, + } as GatewayDispatchPayload; + client.gateway.emit(WebSocketShardEvents.Dispatch, payload, shardId); +} + +function collectErrors(client: GatewayClient) { + const errors: unknown[] = []; + client.on("error", (error) => errors.push(error)); + return errors; +} + +afterEach(() => { + vi.restoreAllMocks(); +}); + +describe("GatewayClient#addDispatchWrapper", () => { + test("GIVEN wrappers THEN they nest, the first added outermost, around the processing of the dispatch", async () => { + const client = createClient(); + const calls: string[] = []; + const seen: WrappedDispatch[] = []; + client.addDispatchWrapper(async (dispatch, run) => { + seen.push(dispatch); + calls.push("outer:start"); + await run(); + calls.push("outer:end"); + }); + client.addDispatchWrapper(async (_dispatch, run) => { + calls.push("inner:start"); + await run(); + calls.push("inner:end"); + }); + client.on("messageCreate", () => calls.push("messageCreate")); + + send(client, "1", 3); + await client.idle(); + + expect(calls).toEqual([ + "outer:start", + "inner:start", + "messageCreate", + "inner:end", + "outer:end", + ]); + expect(seen).toEqual([ + { + payload: expect.objectContaining({ t: GatewayDispatchEvents.MessageCreate }), + shardId: 3, + partition: "guild:10", + }, + ]); + }); + + test("GIVEN a wrapper that enters an AsyncLocalStorage THEN the listeners of the dispatch run in its store", async () => { + const client = createClient(); + const storage = new AsyncLocalStorage(); + client.addDispatchWrapper((dispatch, run) => storage.run(`shard ${dispatch.shardId}`, run)); + const stores: (string | undefined)[] = []; + client.on("messageCreate", () => stores.push(storage.getStore())); + + send(client, "1", 2); + await client.idle(); + + expect(stores).toEqual(["shard 2"]); + }); + + test("GIVEN a failing dispatch THEN run rejects in the wrapper and the client still reports it", async () => { + const client = createClient(); + const failure = new Error("listener failed"); + vi.spyOn(client.cache!.messages!, "upsert").mockRejectedValue(failure); + const errors = collectErrors(client); + const rejections: unknown[] = []; + client.addDispatchWrapper(async (_dispatch, run) => { + try { + await run(); + } catch (error) { + rejections.push(error); + throw error; + } + }); + + send(client, "1"); + await client.idle(); + + expect(rejections).toHaveLength(1); + expect(errors).toHaveLength(1); + }); + + test("GIVEN a removed wrapper THEN the next dispatches skip it", async () => { + const client = createClient(); + const wrapper = vi.fn((_dispatch: WrappedDispatch, run: () => Promise) => run()); + const remove = client.addDispatchWrapper(wrapper); + + send(client, "1"); + await client.idle(); + remove(); + send(client, "2"); + await client.idle(); + + expect(wrapper).toHaveBeenCalledTimes(1); + }); +}); + +describe("GatewayClient#addDestroyHook", () => { + test("GIVEN hooks THEN they run in order once the shards are disconnected and the dispatches processed", async () => { + const client = createClient(); + const calls: string[] = []; + vi.spyOn(client.gateway, "destroy").mockImplementation(async () => { + calls.push("gateway.destroy"); + }); + vi.spyOn(client, "idle").mockImplementation(async () => { + calls.push("idle"); + }); + client.addDestroyHook(() => calls.push("first")); + client.addDestroyHook(async () => { + calls.push("second"); + }); + + await client.destroy(); + + expect(calls).toEqual(["gateway.destroy", "idle", "first", "second"]); + }); + + test("GIVEN a gateway that fails to disconnect THEN the hooks still run and destroy rejects", async () => { + const client = createClient(); + const failure = new Error("close failed"); + vi.spyOn(client.gateway, "destroy").mockRejectedValue(failure); + const hook = vi.fn(); + client.addDestroyHook(hook); + + await expect(client.destroy()).rejects.toBe(failure); + expect(hook).toHaveBeenCalledTimes(1); + }); + + test("GIVEN a failing hook THEN it is reported and the next hooks still run", async () => { + const client = createClient(); + vi.spyOn(client.gateway, "destroy").mockResolvedValue(); + const errors = collectErrors(client); + const failure = new Error("flush failed"); + const next = vi.fn(); + client.addDestroyHook(() => { + throw failure; + }); + client.addDestroyHook(next); + + await client.destroy(); + + expect(errors).toEqual([failure]); + expect(next).toHaveBeenCalledTimes(1); + }); + + test("GIVEN a removed hook THEN destroy does not run it", async () => { + const client = createClient(); + vi.spyOn(client.gateway, "destroy").mockResolvedValue(); + const hook = vi.fn(); + client.addDestroyHook(hook)(); + + await client.destroy(); + + expect(hook).not.toHaveBeenCalled(); + }); +});