Ws: doc clarification between ws.close() and ws.terminate()

[xileftenurb]

I would like to understand the exact difference between ws.close() and ws.terminate().

I don't find the doc very clear, about it because as I tested them, they behave exacly the same. Both trigger "close" event on the other side if open.

so when to use one instead of the other?

thank you.

[lpinca]

Use ws.close() when you want to close the connection gracefully and/or want to use a specific close code/reason. This implements the close handshake.

Use ws.terminate() to shut down the connection immediately.

[brubbel]

This may not tell the complete story.
I found that ws.close() may still execute signal handlers 30 seconds after close() if the network connection is unavailable, while ws.terminate() did not show this behaviour.

During a change of network (e.g. from wired to wireless), when I create a new WebSocket() and registered all signal handlers (onopen/onclose/onerror), I was struggling that the new connection went up, but was consistently receiving 1006/onclose events from the previous socket, which is confusing, but also correct behaviour.

Please also refer to https://github.com/websockets/ws/issues/891

[slidenerd]

My question is highly related and dont want to open an issue, super appreciated if you can clarify something, I noticed in the source code that error triggers a close

• Are error and close always triggered together

• Are there situations where error can be triggered without close and vice-versa?

• I am trying to call a reconnect method when the connection errors out unless I explicitly disconnected it, having some problems with things happening twice

[lpinca]

Are error and close always triggered together

Not always, there might be buffered data and until all data is read the 'close' event is not emitted. You always get a 'close' event after an 'error' event.

Are there situations where error can be triggered without close and vice-versa?

'close' can be emitted without 'error' (clean close).

I am trying to call a reconnect method when the connection errors out unless I explicitly disconnected it, having some problems with things happening twice

Use the 'close' event and an heartbeat system based ping/pong frame where the connection is terminated if no ping is received within an expected amount of time.

[aleqx]

Is the 'close' event emitted if I call .terminate()?

[lpinca]

@aleqx yes.

[aleqx]

I looked at the code and I gather it emits close if the state is CONNECTING but not otherwise. In the code below abortHandshake() does emit close but then you have this._socket.destroy() which doesn't trickle up to the WebSocket instance ... what am I missing?

  terminate() {
    if (this.readyState === WebSocket.CLOSED) return;
    if (this.readyState === WebSocket.CONNECTING) {
      const msg = 'WebSocket was closed before the connection was established';
      return abortHandshake(this, this._req, msg);
    }

    if (this._socket) {
      this.readyState = WebSocket.CLOSING;
      this._socket.destroy();
    }
  }

[lpinca]

@aleqx, see https://github.com/websockets/ws/blob/b45e9121f4a1f067a142c0fb4f2fae65658e90fc/lib/websocket.js#L773-L808

[aleqx]

That's what I missed! Many thanks.

[basickarl]

@lpinca Does terminate inform the other side of what is happening? I am trying to write a test where the client disconnects un-grafully (to test my ping pong handler and kicker) and I'm wondering if terminate can be used for this, from what I see it triggers the close event on the server side (which is not what I want).

[lpinca]

Not explicitly by sending a frame but it does because it closes the TCP connection. It's not trivial to write that test on localhost or a local network.

[basickarl]

@lpinca Ah I see.. One more question: Is there a way to forcibly refuse the sending of a pong from the client in this WS library if the server sends a ping (essentially breaking the WS protocol), this behavior would trigger my ping pong kicker in that case?

[lpinca]

You can but not in an official way.

ws._receiver.removeAllListeners('ping');

It can break at any time.

[lpinca]

Another way would be to override ws.pong() with a noop function.

[basickarl]

@lpinca Thank you ever so much dude! I tried both and they both worked (I'll use the latter one).