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-hooks-from-plugins.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@wolfstar/plugin-gateway": patch
---

`addDispatchWrapper` and `addDestroyHook` work when a plugin calls them from `postInitialization`, which runs before the fields of `GatewayClient` are initialized; they threw a `TypeError` about a private member there.
5 changes: 5 additions & 0 deletions .changeset/opentelemetry-dispatch-spans.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
---
"@wolfstar/plugin-opentelemetry": minor
---

On a `GatewayClient` of `@wolfstar/plugin-gateway` 0.17 or later, the plugin opens one span per gateway dispatch, the root of a trace of its own, around its cache writes and listeners (`dispatches`, on by default, with `dispatches.ignore` for noisy types), and calls `flushTraces()` at the end of `GatewayClient#destroy` (`flushOnDestroy`, on by default). The README shows how to wire `flushTraces()` into the exit hooks of `@wolfstar/plugin-sharder`.
4 changes: 2 additions & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ Project conventions discovered for `plugins` (`wolfstar-project/plugins`).
- `@wolfstar/plugin-gateway` — Gateway (WebSocket) support: a `GatewayClient` emitting Structures, backed by a pluggable cache.
- `@wolfstar/plugin-i18next` — i18next-powered internationalization for HTTP interactions.
- `@wolfstar/plugin-logger` — pluggable logger (console, Sentry, and optional consola/evlog/winston adapter subpaths) replacing the framework's built-in console logger.
- `@wolfstar/plugin-opentelemetry` — traces the bot with OpenTelemetry: a `./preload` (loaded with `--import`) that starts the SDK on the main thread only when an OTLP endpoint is set, and a plugin opening one span per interaction; `./register` is a no-op.
- `@wolfstar/plugin-opentelemetry` — traces the bot with OpenTelemetry: a `./preload` (loaded with `--import`) that starts the SDK on the main thread only when an OTLP endpoint is set, and a plugin opening one span per interaction and, on a `GatewayClient`, one root span per dispatch (through `addDispatchWrapper`) plus `flushTraces()` on `destroy` (through `addDestroyHook`); `./register` is a no-op.
- `@wolfstar/plugin-scheduled-tasks` — one-off and repeated tasks as pieces, backed by BullMQ; the first package built on `definePlugin` (framework 6.1) and `defineModule` (`@wolfstar/kit`), with a no-op `./register`.
- `@wolfstar/plugin-sharder` — multi-process sharding for `plugin-gateway` (processes, cluster workers, or worker threads).
- `@wolfstar/plugin-subcommands-advanced` — modularizes slash subcommands into separate command classes.
Expand Down Expand Up @@ -86,7 +86,7 @@ pnpm exec knip # unused code/dependency check (CI's
- `tests/http-framework-peer-range.test.ts` (part of `pnpm test`, so the CI `unit` job) fails when any non-private package's `peerDependencies["@wolfstar/http-framework"]` excludes the framework version the workspace installs (its devDependency, kept on the latest release by Renovate), when a package declaring that peer doesn't also devDepend on it, or when the packages' peer ranges accept different majors (a package whose range starts at a later major, like `plugin-scheduled-tasks`' `^6.1.0`, only has to match from that major up). When Renovate bumps the framework to a new major, widen **every** plugin's peer range (`^x || ^<new>.0.0`) in the same PR **and** add a patch changeset per package — a peer-range change on `main` isn't published without one (that is how `plugin-api`/`plugin-logger`/`plugin-subcommands-advanced` shipped `^3`-only peers to npm after the v5 bump, #121).
- Non-trivial structural work (cross-package parity ports, manager/API redesigns, new plugin scaffolding) gets a design doc under `docs/superpowers/` before implementation: a plan at `docs/superpowers/plans/<date>-<slug>.md` and, for anything with real design decisions, a matching spec at `docs/superpowers/specs/<date>-<slug>-design.md` (e.g. `docs/superpowers/specs/2026-10-05-message-types-parity-design.md`). PR descriptions for such changes link the spec/plan instead of re-explaining the design. Check this directory for prior art before redesigning an area that already has one.
- Activation has two paths. `plugin-scheduled-tasks` and `plugin-opentelemetry` are module-only (their `./register` is a no-op); `plugin-opentelemetry` also ships a third entrypoint, `./preload` (loaded with `--import`), which starts the OpenTelemetry SDK before the bot's own imports run — `./register` cannot do this, since it only runs after the bot has already started importing. The older plugins ship `./module` (default export: `defineModule` from `@wolfstar/kit`, optional peer) and, for those with runtime hooks, `./plugin` (default export: a `definePlugin` factory); `./register` stays the legacy class + `Client.plugins.register*Hook` path for framework v3/v5/v6. Both call the same functions in `src/hooks.ts`, so change behaviour there. The `stars` CLI never imports `<pkg>/register` itself; it only preloads the sources registered through `ctx.addPlugin`, so a user's own `import "<pkg>/register"` (or passing the `./plugin` factory to `plugins` while also importing `/register`) still double-installs the hooks. `tests/module-entries.test.ts` checks that every `src/module.ts` (except `plugin-scheduled-tasks`, excluded on purpose) is exported, built and has kit and schema as optional peers.
- `plugin-opentelemetry` has process-level tests (`tests/preload.test.ts`: worker thread, `SIGTERM`, WebSocket handshake) that spawn Node with the preload. The CI unit job runs vitest with no build, so the test builds `src/preload.ts` itself with `tsdown` into `packages/plugin-opentelemetry/node_modules/.cache/preload-test/`. The `SIGTERM` cases are skipped on Windows (a Windows process cannot handle the signal); run them in WSL or Linux. Interaction spans are made the active span with `context.attach` (`@opentelemetry/api` 1.10), because the framework's `*Run` events do not wrap the command. `protobufjs` is denied in `allowBuilds` (its postinstall is not needed).
- `plugin-opentelemetry` has process-level tests (`tests/preload.test.ts`: worker thread, `SIGTERM`, WebSocket handshake) that spawn Node with the preload. The CI unit job runs vitest with no build, so the test builds `src/preload.ts` itself with `tsdown` into `packages/plugin-opentelemetry/node_modules/.cache/preload-test/`. The `SIGTERM` cases are skipped on Windows (a Windows process cannot handle the signal); run them in WSL or Linux. Interaction spans are made the active span with `context.attach` (`@opentelemetry/api` 1.10), because the framework's `*Run` events do not wrap the command. Hooks a plugin adds to a `GatewayClient` from `postInitialization` run inside the base `Client` constructor, before the subclass fields exist, so `GatewayClient` keeps its dispatch wrappers and destroy hooks in module-level `WeakMap`s, not private fields. `protobufjs` is denied in `allowBuilds` (its postinstall is not needed).
- Module config keys: every `defineModule` sets `meta.configKey`, so a project writes the options under that top-level key of `stars.config` instead of the `[specifier, options]` tuple (the tuple is merged over the key and wins). Needs `@wolfstar/kit` `^0.2.0 || ^0.3.0` as the peer range (dev range `^0.2.0`) of every package with a `src/module.ts`, and each `module.ts` augments `StarsConfig` from `@wolfstar/schema` (an optional peer and devDependency) to type the key. Keys: `plugin-api` `api`, `plugin-broker` `broker`, `plugin-cache` `cache`, `plugin-gateway` `gateway`, `plugin-i18next` `i18n`, `plugin-logger` `logger`, `plugin-opentelemetry` `opentelemetry`, `plugin-scheduled-tasks` `scheduledTasks`, `plugin-sharder` `sharder`, `plugin-subcommands-advanced` `subcommandsAdvanced`; `cache`, `gateway`, `sharder` and `subcommandsAdvanced` take no options yet and only reserve the name. A key must be unique and not a built-in key (`BUILT_IN_CONFIG_KEYS` of `@wolfstar/schema`); renaming one is a breaking change. `tests/module-config-keys.test.ts` runs every module through kit's `setupModules`. What sits under a key is written into the build, so it must be JSON.

## Notes for agents
Expand Down
28 changes: 17 additions & 11 deletions packages/plugin-gateway/src/GatewayClient.ts
Original file line number Diff line number Diff line change
Expand Up @@ -356,6 +356,11 @@ export type DispatchWrapper = (
*/
export type GatewayClientDestroyHook = () => unknown;

// Outside of the instance: plugins add them from `postInitialization`, which the base `Client` constructor runs before
// the fields of `GatewayClient` exist. See `addDispatchWrapper`: the first added is the outermost.
const dispatchWrappers = new WeakMap<GatewayClient, readonly DispatchWrapper[]>();
const destroyHooks = new WeakMap<GatewayClient, Set<GatewayClientDestroyHook>>();

/**
* 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 @@ -539,11 +544,6 @@ 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 @@ -693,9 +693,13 @@ export class GatewayClient extends Client {
* @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];
dispatchWrappers.set(this, [...(dispatchWrappers.get(this) ?? []), wrapper]);
return () => {
this.#dispatchWrappers = this.#dispatchWrappers.filter((entry) => entry !== wrapper);
const wrappers = dispatchWrappers.get(this) ?? [];
dispatchWrappers.set(
this,
wrappers.filter((entry) => entry !== wrapper),
);
};
}

Expand All @@ -711,15 +715,17 @@ export class GatewayClient extends Client {
* @returns A function that removes the hook.
*/
public addDestroyHook(hook: GatewayClientDestroyHook): () => void {
this.#destroyHooks.add(hook);
let hooks = destroyHooks.get(this);
if (!hooks) destroyHooks.set(this, (hooks = new Set()));
hooks.add(hook);
return () => {
this.#destroyHooks.delete(hook);
hooks.delete(hook);
};
}

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)) {
for (const hook of Array.from(destroyHooks.get(this) ?? [])) {
try {
await hook();
} catch (error) {
Expand Down Expand Up @@ -1361,7 +1367,7 @@ export class GatewayClient extends Client {
#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;
const wrappers = dispatchWrappers.get(this) ?? [];
for (let index = wrappers.length - 1; index >= 0; index--) {
const wrapper = wrappers[index]!;
const inner = run;
Expand Down
30 changes: 29 additions & 1 deletion packages/plugin-gateway/tests/hooks.test.ts
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import { AsyncLocalStorage } from "node:async_hooks";
import { WebSocketShardEvents } from "@discordjs/ws";
import { definePlugin } from "@wolfstar/http-framework";
import { createInMemoryCache } from "@wolfstar/plugin-cache";
import {
GatewayDispatchEvents,
Expand All @@ -18,13 +19,14 @@ const user: APIUser = {
avatar: null,
};

function createClient() {
function createClient(plugins: ReturnType<ReturnType<typeof definePlugin>>[] = []) {
return new GatewayClient({
discordPublicKey: "0".repeat(64),
discordToken: "test-token",
clientId: "266624760782258186",
intents: 0,
cache: createInMemoryCache(),
plugins,
});
}

Expand Down Expand Up @@ -207,3 +209,29 @@ describe("GatewayClient#addDestroyHook", () => {
expect(hook).not.toHaveBeenCalled();
});
});

describe("hooks added by a plugin", () => {
// `postInitialization` runs from the constructor of the base `Client`, before the fields of `GatewayClient` exist.
test("GIVEN a plugin that adds a wrapper and a destroy hook in postInitialization THEN both run", async () => {
const calls: string[] = [];
const plugin = definePlugin(() => ({
name: "test-hooks",
postInitialization(client) {
const gateway = client as GatewayClient;
gateway.addDispatchWrapper(async (_dispatch, run) => {
calls.push("wrapper");
await run();
});
gateway.addDestroyHook(() => calls.push("destroy hook"));
},
}));
const client = createClient([plugin()]);
vi.spyOn(client.gateway, "destroy").mockResolvedValue();

send(client, "1");
await client.idle();
await client.destroy();

expect(calls).toEqual(["wrapper", "destroy hook"]);
});
});
37 changes: 37 additions & 0 deletions packages/plugin-opentelemetry/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,15 @@ Without an SDK running, `@opentelemetry/api` hands out no-op spans and the plugi

`interactions: false` turns them all off, `true` takes the defaults.

| Option | Default | What it does |
| ------------------- | ------- | ------------------------------------------------------------------------------- |
| `dispatches` | `true` | A span per gateway dispatch, on a `GatewayClient` (`@wolfstar/plugin-gateway`). |
| `dispatches.ignore` | `[]` | Dispatch types that get no span, such as `PRESENCE_UPDATE` or `TYPING_START`. |
| `flushOnDestroy` | `true` | Calls `flushTraces()` at the end of `GatewayClient#destroy`. |

`dispatches` and `flushOnDestroy` need `@wolfstar/plugin-gateway` 0.17 or later, and are ignored on a client that does
not connect to the gateway.

#### The spans

A span is named `<kind> <name>` (`command ping`, `component confirm`) and carries:
Expand All @@ -127,6 +136,21 @@ A span is named `<kind> <name>` (`command ping`, `component confirm`) and carrie

A failing run records the exception and sets the span status to `ERROR`.

A gateway dispatch gets a span named `dispatch <type>` (`dispatch MESSAGE_CREATE`) around its cache writes and its
listeners, so what they start has it as a parent. It carries:

| Attribute | Value |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `discord.dispatch.type` | The type of the dispatch. |
| `discord.shard.id` | The gateway shard it came from. |
| `discord.dispatch.partition` | The partition it is ordered in, when it has one. |
| `discord.guild.id` | The guild, when the dispatch belongs to one (its `id` for `GUILD_CREATE`, `GUILD_UPDATE` and `GUILD_DELETE`). |
| `dispatch.outcome` | `success` or `error`. |

Each dispatch span is the root of a trace of its own: `@discordjs/ws` receives every dispatch in the context of the
request that opened the WebSocket, and a span started there would put all of the gateway's work in one trace that never
ends. Dispatches replayed with `replayDispatch` (as by `@wolfstar/plugin-broker`) get no span.

The framework's events do not wrap the run of a command, so the span is made the active one with
`context.attach` from the
`*Run` event, and the previous context is restored on `*Finish`. That needs a context manager that implements `attach`,
Expand All @@ -138,6 +162,19 @@ spans are still created, but what a command starts is not attached to them.
Exports the spans waiting in the batch. Call it from a shutdown path before the process exits; it never rejects, and does
nothing when no SDK is running.

The plugin already calls it at the end of `GatewayClient#destroy`. The preload calls it on `SIGTERM` and `beforeExit`,
but `process.exit` skips `beforeExit`, which is how the shards of `@wolfstar/plugin-sharder` stop. Wire it into the
sharder (0.5 or later) yourself, since the plugin cannot see those objects:

```ts
import { flushTraces } from "@wolfstar/plugin-opentelemetry";

shard.addExitHook(flushTraces); // in a shard: before exit(), restart(), or a close from the manager
manager.addDestroyHook(flushTraces); // in the manager: at the end of manager.destroy()
```

For any other path that ends the process:

```ts
import { flushTraces } from "@wolfstar/plugin-opentelemetry";

Expand Down
1 change: 1 addition & 0 deletions packages/plugin-opentelemetry/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@
"@types/node": "22.15.21",
"@wolfstar/http-framework": "^6.5.1",
"@wolfstar/kit": "^0.3.1",
"@wolfstar/plugin-gateway": "workspace:^",
"@wolfstar/schema": "^0.12.0"
},
"peerDependencies": {
Expand Down
38 changes: 38 additions & 0 deletions packages/plugin-opentelemetry/src/lib/attributes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -58,3 +58,41 @@ export interface OpenTelemetryInteractionsOptions {
*/
handlers?: boolean;
}

/**
* The attributes of the span of a gateway dispatch.
*/
export const DispatchAttributes = {
/**
* The type of the dispatch (`MESSAGE_CREATE`, `GUILD_MEMBER_UPDATE`, ...).
*/
Type: "discord.dispatch.type",
/**
* The gateway shard the dispatch came from.
*/
ShardId: "discord.shard.id",
/**
* The partition the dispatch is ordered in (`guild:<id>`, `channel:<id>`...), when it has one.
*/
Partition: "discord.dispatch.partition",
/**
* The guild of the dispatch, when it belongs to one.
*/
GuildId: "discord.guild.id",
/**
* `success` or `error`, set when the processing ends.
*/
Outcome: "dispatch.outcome",
} as const;

/**
* Which gateway dispatches get a span.
*/
export interface OpenTelemetryDispatchesOptions {
/**
* The dispatch types that get no span, such as `PRESENCE_UPDATE` or `TYPING_START` on a busy bot.
*
* @default []
*/
ignore?: readonly string[];
}
Loading
Loading