Skip to main content

Interface: WebSocketRouteOptions

Defined in: service-core/src/decorators/RouteDecorators.ts:548

Per-route WebSocket limits for @WebSocket(). Every field is optional; a field left out (or undefined) keeps the framework default (DEFAULT_WS_OPTIONS in http/types.ts, the same as uWebSockets.js' own), so a route without options behaves exactly as it always has. The values are checked when the route is registered (see RouteUtils.resolveWebSocketOptions()), and an invalid one throws an Error that names the route.

Properties​

idleTimeout?​

optional idleTimeout?: number

Defined in: service-core/src/decorators/RouteDecorators.ts:577

How many seconds the connection may go without receiving any data before the server closes it. 0 disables the timeout; otherwise an integer from 8 to MAX_WEBSOCKET_IDLE_TIMEOUT (960), which is what uWebSockets.js accepts (it refuses 1 to 7, and its resolution is about 4 seconds). Default 120.

A client that stays connected but silent (no message, and no reply to the server's ping) is closed after this long. On the Bun router this is server-wide (the largest value any route set, and 0 wins).

maxBackpressure?​

optional maxBackpressure?: number

Defined in: service-core/src/decorators/RouteDecorators.ts:568

How many bytes the route may have queued to send to a slow client before further sends are dropped, in bytes. Integer from 1 to MAX_WEBSOCKET_BACKPRESSURE (64 MiB). Default 65536 (64 KiB).

When a client reads more slowly than the route sends, the unsent bytes are buffered per connection. Once the buffer is over this limit, uWebSockets.js drops further messages (send() reports them as dropped) instead of queuing them. Raise it for a route that streams large frames (e.g. video); each connection may then hold that much memory. On the Bun router this is server-wide, using the largest value any WebSocket route set.

maxPayloadLength?​

optional maxPayloadLength?: number

Defined in: service-core/src/decorators/RouteDecorators.ts:558

The largest single message the route accepts from a client, in bytes. Integer from 1 to MAX_WEBSOCKET_PAYLOAD_LENGTH (16 MiB). Default 16384 (16 KiB).

A client message larger than this is not delivered to the route. uWebSockets.js drops the connection at once without sending a close frame, so the client sees an abnormal closure (code 1006 in browsers and ws); the Bun router closes the socket with code 1009 instead. The limit is per message, so a payload a client splits into several messages is not bound by it as a whole.