Field guide · WebSocket
Node.js WebSocket server: what matters in production?
Short answer
A WebSocket server becomes production-ready when an upgrade is validated before opening a connection, state belongs to a specific connection context, pressure has a measurable policy, and shutdown stops new upgrades then waits for active work only within a deadline. swm-core 5.1.2 combines HTTP and WebSocket lifecycle in one server instance.
- HTTP → WS
- explicit upgrade
- pub/sub
- topics and delivery
- 22 / 24
- Node.js
Scope
This page fixes the @swarmmachina/swm-core 5.1.2 API and boundaries for Node.js 22/24. It does not promise delivery of every message under every load, or replace client, proxy, and broker policy.
WebSocket connection contract
| Area | Explicit contract | Pre-launch check |
|---|---|---|
| Upgrade | Authentication, origin, and required headers are validated before calling upgrade. | A rejected upgrade creates no socket and invokes no open handler. |
| Context | Connection data belongs to one socket and never mixes with adjacent connections. | A concurrent test proves tenant, principal, and connectionKey isolation. |
| Messages | Size, format, and invalid-payload behavior are decided before the business handler. | Test oversized, malformed, and unexpected binary or text messages. |
| Backpressure | Queue and slow-client behavior are measurable; the code does not call every send delivered. | A load test includes a slow receiver and records the close or drop policy. |
| Pub/sub | Topic, binary format, and delivery boundary are known to the calling code. | Test join/leave, broadcast, and no delivery after a socket closes. |
| Shutdown | The application stops new upgrades and terminates connections by a fixed policy. | An integration test distinguishes normal drain from an immediate close. |
Practical decisions
- 01
You need HTTP routes and a WebSocket gateway in one process
Use one server lifecycleUpgrade, errors, and termination do not become disconnected subsystems.
- 02
Clients can read slower than the sender writes
Make pressure part of the protocolUse a bound, observable policy, and client recovery instead of hoping for an infinite queue.
- 03
You need guarantees after disconnect
Add an external durable transportA WebSocket socket is not itself a message log or guaranteed delivery mechanism.
WebSocket transport boundaries
- A connection does not replace authentication, authorization, or origin validation at upgrade time.
- Pub/sub is useful for live delivery, while replay and durability require separate storage or a broker.
- Load testing must include slow receivers and reconnects, not only a fast echo connection.
Primary sources
The contract is checked against the fixed README and package metadata, not claims in a marketing comparison.