Heartbeat does not work when timeout < interval

[zehawki]

I recently switched over to the inbuilt heartbeat, but was not able to get it working properly, while my own heartbeat implementation on top has been working fine for long. After various debugging, I narrowed it down to the following:

If timeout < interval, the timeout occurs before the 1st heartbeat is sent, and the WS is closed.

But this is not as per the documentation.

The desc says:

1. ...the library will send a 'ping' message to the server every interval milliseconds
2. If no response is received within timeout milliseconds, indicating a potential connection issue, the library will close the connection.

Making it very clear that timeout starts AFTER a ping is sent, which is how it should be, and makes perfect sense.

Whereas, whats going on is that the timeout has already started counting down from the time the last message was received. With setting like:

timeout = 60000 (ie 1min)
interval = 600000 (ie 10 mins)

and the WS idle for just 1 min, the TO expires and closes the WS with a message like hook.js:608 Heartbeat timed out, closing connection, last message received 106046ms ago, last ping sent 106257ms ago.

Rather it should be based on interval. I know when the server will close the WS, so I can set interval accordingly, in this case 10 mins. Every 10min I expect to send a heartbeat, and IF no response comes back within timeout, then it makes sense to close the connection.

[jambsik]

@zehawki I suspect the library starts the heartbeat interval and the heartbeat timeout at the same time for each cycle. This is just my belief based on observed behavior and the discussion in that issue, not a confirmed fact. If that’s what’s happening, then the timeout can elapse before (or right as) the ping/pong round-trip occurs when the two values are too close. That explains why a timeout must be set larger than the interval to avoid false reconnects.

Given API Gateway WebSocket’s hard 10-minute idle limit, the practical approach is:

• Send an application-level ping on your specific route (e.g.,'ping') well before 10 minutes.
• Ensure heartbeat timeout > interval (ideally by 60–120 seconds) to account for network jitter, GC pauses, background tab timer throttling, and backend latency (e.g., Lambda cold starts).
• If you see occasional false timeouts, either increase the timeout buffer or reduce the interval slightly.

I hope this comment is useful to you.

[zehawki]

@jambsik what you said makes sense, this is certainly useful. Thank you for taking the time and trouble to drop a long note.

[michaelboyles]

The heartbeat.timeout property is actually basically unrelated to heartbeating (confusingly!)

What heartbeat.timeout actually does is just kill the connection after there have been no messages for that period. It doesn't care if it's a heartbeat/response or a regular message.

You would be forgiven for thinking it means "how long to wait for the heartbeat response", but that is not what it does.

I have forked this library as react-use-websocket-lite and I have renamed this to messageTimeout (no longer inside heartbeat options), as part of one of many improvements