Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/gateway-dispatch-wrappers.md
Original file line number Diff line number Diff line change
@@ -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.
25 changes: 25 additions & 0 deletions packages/plugin-gateway/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
119 changes: 110 additions & 9 deletions packages/plugin-gateway/src/GatewayClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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:<id>`, `channel:<id>`...), 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<void>,
) => Promise<void>;

/**
* 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.
Expand Down Expand Up @@ -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<void> | null = null;

// See `addDispatchWrapper`: the first added is the outermost.
#dispatchWrappers: readonly DispatchWrapper[] = [];

readonly #destroyHooks = new Set<GatewayClientDestroyHook>();

public constructor(options: GatewayClientOptions) {
super(options);
container.gatewayClient = this;
Expand Down Expand Up @@ -627,18 +663,70 @@ export class GatewayClient extends Client {
}

private async disconnect(resumable: boolean): Promise<void> {
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();
Comment on lines 679 to +681

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Shutdown hooks run too early

If gateway.destroy() rejects while a dispatch is still running, disconnect() skips idle() and immediately runs the destroy hooks. A hook that flushes traces can finish before that dispatch ends, leaving its final spans unexported when the process exits. Wait for queued dispatches before running the hooks on the failure path too, while preserving the original disconnect error.

Prompt To Fix With AI
This is a comment left during a code review.
Path: packages/plugin-gateway/src/GatewayClient.ts
Line: 679-681

Comment:
**Shutdown hooks run too early**

If `gateway.destroy()` rejects while a dispatch is still running, `disconnect()` skips `idle()` and immediately runs the destroy hooks. A hook that flushes traces can finish before that dispatch ends, leaving its final spans unexported when the process exits. Wait for queued dispatches before running the hooks on the failure path too, while preserving the original disconnect error.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Fix in Claude Code Fix in Cursor

}
}

/**
* 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<void> {
// 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);
}
}
}

/**
Expand Down Expand Up @@ -1262,14 +1350,27 @@ 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 {
if (timer) clearTimeout(timer);
}
}

#wrapDispatch(dispatch: WrappedDispatch): Promise<void> {
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<OptionalWebSocketManagerOptions, "retrieveSessionInfo" | "updateSessionInfo"> {
Expand Down
Loading
Loading