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

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.

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.

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 #891

Work around ws library bug

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

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.

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

@aleqx

@aleqx yes.

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();
    }
  }

@aleqx

@aleqx, see

ws/lib/websocket.js

Lines 773 to 808 in b45e912

    
           function socketOnClose() { 
        
             const websocket = this[kWebSocket]; 
        
             this.removeListener('close', socketOnClose); 
        
             this.removeListener('end', socketOnEnd); 
        
             websocket.readyState = WebSocket.CLOSING; 
        
             // 
        
             // The close frame might not have been received or the `'end'` event emitted, 
        
             // for example, if the socket was destroyed due to an error. Ensure that the 
        
             // `receiver` stream is closed after writing any remaining buffered data to 
        
             // it. If the readable side of the socket is in flowing mode then there is no 
        
             // buffered data as everything has been already written and `readable.read()` 
        
             // will return `null`. If instead, the socket is paused, any possible buffered 
        
             // data will be read as a single chunk and emitted synchronously in a single 
        
             // `'data'` event. 
        
             // 
        
             websocket._socket.read(); 
        
             websocket._receiver.end(); 
        
             this.removeListener('data', socketOnData); 
        
             this[kWebSocket] = undefined; 
        
             clearTimeout(websocket._closeTimer); 
        
             if ( 
        
               websocket._receiver._writableState.finished || 
        
               websocket._receiver._writableState.errorEmitted 
        
             ) { 
        
               websocket.emitClose(); 
        
             } else { 
        
               websocket._receiver.on('error', receiverOnFinish); 
        
               websocket._receiver.on('finish', receiverOnFinish); 
        
             } 
        
           }

That's what I missed! Many thanks.

@lpinca

@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).

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.

@lpinca

@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?

You can but not in an official way.

ws._receiver.removeAllListeners('ping');

It can break at any time.

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

@lpinca

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

Is there a way to terminate from the client side?

@lpinca

@lpinca

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

This sounds like it's just "faster" than .close(). Could you maybe edit your post to advise more caution?

What it really does is not a clean shutdown, but rather it simply drops the connection. One should only do this in case of an error. There is no closing handshake, neither on the websocket nor the tcp level, the other end of the connection will be oblivious of the dropped connection. (They will only run into a tcp timeout after (if!) attempting to send something).

More details: https://stackoverflow.com/a/74081838/1048572?when-is-it-preferable-to-use-ws-terminate-vs-ws-close

Navigation Menu

Repository navigation

doc clarification between ws.close() and ws.terminate() #1142

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

	function socketOnClose() {
	const websocket = this[kWebSocket];

	this.removeListener('close', socketOnClose);
	this.removeListener('end', socketOnEnd);

	websocket.readyState = WebSocket.CLOSING;

	//
	// The close frame might not have been received or the `'end'` event emitted,
	// for example, if the socket was destroyed due to an error. Ensure that the
	// `receiver` stream is closed after writing any remaining buffered data to
	// it. If the readable side of the socket is in flowing mode then there is no
	// buffered data as everything has been already written and `readable.read()`
	// will return `null`. If instead, the socket is paused, any possible buffered
	// data will be read as a single chunk and emitted synchronously in a single
	// `'data'` event.
	//
	websocket._socket.read();
	websocket._receiver.end();

	this.removeListener('data', socketOnData);
	this[kWebSocket] = undefined;

	clearTimeout(websocket._closeTimer);

	if (
	websocket._receiver._writableState.finished \|\|
	websocket._receiver._writableState.errorEmitted
	) {
	websocket.emitClose();
	} else {
	websocket._receiver.on('error', receiverOnFinish);
	websocket._receiver.on('finish', receiverOnFinish);
	}
	}

doc clarification between ws.close() and ws.terminate() #1142

Description

Activity

lpinca commented on Jun 14, 2017

brubbel commented on Oct 27, 2017

slidenerd commented on Oct 19, 2018

lpinca commented on Oct 19, 2018

aleqx commented on Feb 14, 2019

lpinca commented on Feb 14, 2019

aleqx commented on Feb 14, 2019

lpinca commented on Feb 14, 2019

aleqx commented on Feb 14, 2019

basickarl commented on Jun 24, 2020

lpinca commented on Jun 24, 2020

basickarl commented on Jun 24, 2020

lpinca commented on Jun 24, 2020

lpinca commented on Jun 24, 2020

basickarl commented on Jun 24, 2020

Esqarrouth commented on Feb 16, 2021

bergus commented on Oct 15, 2022

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions