Repository navigation
How-to: add a new socket event end-to-end #616
Description
Branch: Open your PR against dev. PRs targeting main are closed automatically.
Description:
Write apps/backend/docs/howto-add-socket-event.md. Adding an event touches at least four places, and missing one fails silently: the type must be in KNOWN_EVENT_TYPES (lib/eventEnvelope.ts), the handler must be registered through EventDispatcher.register (socket/dispatcher.ts) — there is no raw socket.on fallback, so an unregistered event is simply dropped — and the event should be mapped to a rate-limit bucket in config/rateLimits.ts.
Acceptance criteria:
- A numbered checklist covering every file that must change, in order, with a minimal worked example of a new event
- Explains what the dispatcher does before a handler runs: envelope schema validation, the timestamp freshness window (
SOCKET_EVENT_MAX_AGE_MS, default 300 s;SOCKET_EVENT_MAX_FUTURE_SKEW_MS, default 30 s), andeventIdreplay rejection - States the invariant checks every payload-carrying handler is expected to run (
findForbiddenSessionStateField, ciphertext-only payloads) and links to the server-side crypto invariants doc (Require device registration inPOST /auth/verify#332) - Shows how to emit errors in the shape documented by the error catalog (feat(auth): reuse device schema for auth verify and /devices route #325) and how to unit-test the handler with the existing dispatcher test harness
- Ends with "update the docs": the WebSocket event catalog (feat: add heartbeat watchdog, device revocation pub/sub, rate limitin… #268) and payload reference (feat: add push_subscriptions table, VAPID config, and web-push depend… #271)
Activity
LightX5 commentedon Oct 19, 2026
@LightX5 has applied to work on this issue as part of the Stellar Wave Program's 10th wave.
ℹ️ Repo Maintainers: To accept this application, review their application or assign @LightX5 to this issue.
drips-wave commentedon Oct 20, 2026
Congratulations, @0xDeon! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on October 22, 2026.
🧑💻 @0xDeon: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.
Warning
When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.
🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.
🌊 Happy Wave 🌊
github-actions commentedon Oct 20, 2026
Closed by #647, merged into
dev.drips-wave commentedon Oct 20, 2026
This issue has been completed by @0xDeon as part of the Stellar Wave Program's 10th Wave 🥳
😎 @0xDeon: You earned 200 Points for completing this issue! Once the Wave's rewards are finalized, you'll be eligible for a percentage of the Wave's reward pool based on the percentage of total points you've earned. Learn more here. You can also Leave a review to share your experience working on this issue.
🧑💻 Repo maintainers: How'd the contributor do? Leave a review to share your experience working with them.