websocket-handler-decomposition

Split oversized WebSocket handlers into ConnectionManager and MessageDispatcher components.

2|3|Updated Apr 1, 2026
One-click install
npx skills add https://github.com/sytone/botnexus --skill websocket-handler-decomposition
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: websocket-handler-decomposition
Source: https://github.com/sytone/botnexus/tree/main/.squad/skills/websocket-handler-decomposition
Command: npx skills add https://github.com/sytone/botnexus --skill websocket-handler-decomposition

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

A WebSocket handler tends to accumulate several concerns (transport lifecycle, session locking, message routing, replay persistence). You need to improve maintainability while preserving endpoint/method contracts.

Core Features & Use Cases

  • Extract a thin orchestrator as the top-level handler and delegate to specialized components.
  • Create a ConnectionManager to handle reconnect throttling, active-session lock management, duplicate close semantics, and ping/pong keepalive handling.
  • Create a MessageDispatcher to route inbound messages, dispatch agent commands, and persist replay sequences with outbound formatting.
  • Preserve endpoint mappings and public signatures to avoid breaking callers.
  • Update DI registrations and tests to wire the new components explicitly.

Quick Start

Refactor by extracting a ConnectionManager and a MessageDispatcher while preserving endpoint contracts.

Frequently Asked Questions about websocket-handler-decomposition

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I refactor a WebSocket handler that mixes transport lifecycle, session locking, and message routing?

To refactor a WebSocket handler, split it into a thin orchestrator that delegates to a ConnectionManager for keepalive and locking, and a MessageDispatcher for routing and replay, preserving the HandleAsync signature to avoid breaking callers.

What is the best way to separate concerns in WebSocket handlers without breaking endpoint contracts?

Separating concerns in WebSocket handlers involves extracting transport and session logic into a ConnectionManager, and routing with replay persistence into a MessageDispatcher, while explicitly preserving public endpoint mappings and the HandleAsync signature.

How do I extract a ConnectionManager and MessageDispatcher from a monolithic WebSocket handler?

Extract a ConnectionManager and MessageDispatcher by making the top-level handler a thin orchestrator, moving reconnect throttling and keepalive to the manager, and shifting inbound message routing and replay persistence to the dispatcher.

Does refactoring WebSocket handlers into separate components require updating dependency injection registrations?

Refactoring WebSocket handlers requires updating dependency injection registrations and adjusting tests to explicitly wire the new ConnectionManager and MessageDispatcher components into the application pipeline.

When should I split a WebSocket handler into specialized components for maintainability?

You should split a WebSocket handler when it accumulates transport lifecycle, session locking, message routing, and replay persistence, and you need to improve maintainability while preserving endpoint and method contracts.

What limitations exist when preserving the HandleAsync signature during a WebSocket handler refactor?

Preserving the HandleAsync signature during a WebSocket refactor limits breaking changes to public contracts but requires internal delegation to new components, necessitating dependency injection updates and test adjustments to wire the new structure.