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(); + }); +});