Skip to content

feat(plugin-sharder): add shard exit hooks and manager destroy hooks - #287

Merged
RedStar071 merged 4 commits into
mainfrom
feat/plugin-sharder-exit-hooks
Nov 13, 2026
Merged

RedStar071 merged 4 commits into
mainfrom
feat/plugin-sharder-exit-hooks

Conversation

@RedStar071

@RedStar071 RedStar071 commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

🔗 Linked issue

Refs #261

🧭 Context

Second half of #261, in three PRs:

  1. feat(plugin-gateway): add dispatch wrappers and destroy hooks #285 (merged): plugin-gateway dispatch wrappers and destroy hooks
  2. this PR: plugin-sharder exit and destroy hooks
  3. plugin-opentelemetry dispatch spans and the flushTraces() wiring, which resolves request: a plugin that traces the bot with OpenTelemetry #261

A shard stops with process.exit, which skips beforeExit. The OpenTelemetry preload exports its last spans on beforeExit or SIGTERM, so a shard that exits or restarts loses the batch it has not exported yet. Nothing in ShardClient gives code a chance to flush first.

📚 Description

ShardClient#addExitHook(hook) runs a hook before the shard stops: on exit() and restart(), after the close handler when the manager closes the shard, and when the manager is gone and nothing listens to disconnect. The hooks run before the shard signals that it is stopping, so they count towards the manager's close timeout.

ShardManager#addDestroyHook(hook) runs a hook at the end of destroy(), once the shards are closed, even when closing one failed.

In both, a hook that throws is reported through error and the next hooks still run. Each call returns a function that removes the hook. Nothing changes for a shard or a manager that adds none.

Key changes

  • ShardClient: addExitHook and the ShardExitHook type.
  • ShardManager: addDestroyHook and the ShardManagerDestroyHook type.
  • tests/hooks.test.ts: hook order against shardExit, a close from the manager, the manager going away, failing and removed hooks, and destroy hooks when closing fails.
  • README paragraph under "Lifecycle and supervision" and a minor changeset.

Type of Change

  • New feature (non-breaking change which adds functionality)
  • Bug fix (non-breaking change which fixes an issue)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation change
  • Workflow / CI change

Pre-flight Checklist

  • I have read the Contributing Guidelines (if applicable)
  • My code follows the code style of this project
  • I have added tests that prove my fix is effective or that my feature works
  • New and existing unit tests pass locally with my changes
  • I have updated the documentation accordingly
  • I added a changeset with pnpm changeset (or pnpm changeset add --empty if no release is needed). See .changeset/README.md.

🤖 AI disclosure: Claude Code was used on this PR. Code written with claude-opus-5-5; PR description written with claude-opus-5-5. AI policy.


Read this PR faster    Follow each request

RetriggerView in GreptileConfidence Score: 5/5

The reviewed changes appear safe to merge.

Reviews (2) · Last reviewed commit: "fix(plugin-sharder): run exit hooks once..." · Reviewed by Greptile

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
A shard stops with process.exit, which skips beforeExit, so whatever a
library flushes there is lost. ShardClient#addExitHook runs a hook
first, on exit(), restart(), a close from the manager, and when the
manager is gone. ShardManager#addDestroyHook runs one at the end of
destroy(), once the shards are closed.

Refs #261
@coldtea-pr-lens

coldtea-pr-lens Bot commented Nov 13, 2026 •

Copy link
Copy Markdown
  • Redraw · drawn at bcc74e1, the branch has moved on

Architecture

Walkthrough of Add shutdown hooks to ShardClient and ShardManager, in three steps

Read this PR faster


Data flow

Data flow diagram for wolfstar-project/plugins at bcc74e1

Follow each request


Review

✨ Nothing new to flag · reviewed bcc74e1


Tip

After a push, tick Redraw to draw the latest commit

🪧 More tips
  • Run npx skills add coldteadotai/pr-lens, then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
  • Run npx @coldtea/pr-lens-cli analyze --base origin/main on a branch, then npx @coldtea/pr-lens-cli render .pr-lens/graph.json. Same lenses, your own model key, before the pull request exists
  • Click the link under each diagram to open it on a canvas you can zoom, pan and step through
  • The diagrams are links. Click one to open it on the canvas, then press W or click play to walk through the change
  • Open a diagram on the canvas, then press W or click play to walk through the change one step at a time
  • The CLI's render reads .github/pr-lens.yml and applies your renames, exclusions and lane pins at draw time
  • Set github.comment.collapsed: true in .github/pr-lens.yml to fold the comment behind one View architecture… row. Drawing still runs as before
  • Set github.draw: on-demand in .github/pr-lens.yml and PR Lens stops drawing pull requests on its own. Comment @pr-lens draw on a pull request when you want that one drawn
  • Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and your model provider's key as its api-key to run PR Lens from your own CI. Any /chat/completions endpoint works
  • Switch GitHub to dark mode and the diagrams follow. The moving dots are this pull request's data in motion
  • Set github.description: false in .github/pr-lens.yml to stop PR Lens adding buttons to your PR descriptions

Thanks for using PR Lens! It's free for OSS. If it helped, a star helps other teams find it.  Star PR Lens on GitHub

@wolfstarbot wolfstarbot added the packages:plugin-sharder Changes in plugin-sharder label Nov 13, 2026

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

ℹ️ No critical issues — one docs rough edge inline.

Reviewed changes

Reviewed the full diff (5 files) of the exit and destroy hooks for plugin-sharder.

  • ShardClient#addExitHook: hooks run in #stop (exit(), restart(), and the manager Op.Close path after the close handler) and on the orphaned onDisconnect path, before the shard signals its status. Errors go through #report, and the hook set is copied so hooks added mid-run wait for the next stop.
  • ShardManager#addDestroyHook: destroy() now wraps closing in try/finally so the hooks run even when closing a shard rejects, and the original rejection still propagates.
  • Tests, README and changeset: tests/hooks.test.ts covers ordering, the manager-close path, failing and removed hooks, the manager-gone path and destroy when closing fails. The minor changeset matches the new public API. ShardExitHook and ShardManagerDestroyHook are exported through export * in src/index.ts.

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using claude-sonnet-5-5 | 𝕏

…y close

Share the exit hooks in progress across the paths that stop a shard, so
the manager going away during exit() waits for the first flush instead
of starting another and exiting before it is done. Let every shard
close settle before the destroy hooks run, and keep the JSDoc of
ShardManagerOptions attached to it.
@pkg-pr-new

pkg-pr-new Bot commented Nov 13, 2026

Copy link
Copy Markdown

Open in StackBlitz

@wolfstar/plugin-api

pnpm add https://pkg.pr.new/@wolfstar/plugin-api@287

@wolfstar/plugin-broker

pnpm add https://pkg.pr.new/@wolfstar/plugin-broker@287

@wolfstar/plugin-cache

pnpm add https://pkg.pr.new/@wolfstar/plugin-cache@287

@wolfstar/plugin-gateway

pnpm add https://pkg.pr.new/@wolfstar/plugin-gateway@287

@wolfstar/plugin-i18next

pnpm add https://pkg.pr.new/@wolfstar/plugin-i18next@287

@wolfstar/plugin-logger

pnpm add https://pkg.pr.new/@wolfstar/plugin-logger@287

@wolfstar/plugin-opentelemetry

pnpm add https://pkg.pr.new/@wolfstar/plugin-opentelemetry@287

@wolfstar/plugin-scheduled-tasks

pnpm add https://pkg.pr.new/@wolfstar/plugin-scheduled-tasks@287

@wolfstar/plugin-sharder

pnpm add https://pkg.pr.new/@wolfstar/plugin-sharder@287

@wolfstar/plugin-subcommands-advanced

pnpm add https://pkg.pr.new/@wolfstar/plugin-subcommands-advanced@287

commit: 7ebafc2

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

✅ No new issues found.

Reviewed changes

Reviewed the delta since the prior Pullfrog review (bcc74e1 → 7ebafc2).

  • Shared exit-hook run: ShardClient#runExitHooks memoizes the in-progress run in #exiting, so exit() and the manager-disconnect path share one run. The hooks run once and neither path calls transport.exit before they finish.
  • Destroy waits for every close: ShardManager#destroy uses Promise.allSettled, rethrows the first rejection, and runs the destroy hooks in finally. No shard is still stopping when the hooks run.
  • Docs placement fix: ShardManagerDestroyHook now sits above the ShardManagerOptions doc block, which fixes the earlier inline finding.
  • Tests: Added an overlapping-stops test and a one-shard-fails-to-close ordering test in tests/hooks.test.ts.

Pullfrog  | View workflow run | Using claude-sonnet-5-5 | 𝕏

@RedStar071
RedStar071 merged commit 4de0802 into main Nov 13, 2026
20 checks passed
@RedStar071
RedStar071 deleted the feat/plugin-sharder-exit-hooks branch November 13, 2026 17:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

packages:plugin-sharder Changes in plugin-sharder

Projects

None yet

Development

Successfully merging this pull request may close these issues.

request: a plugin that traces the bot with OpenTelemetry

2 participants