Client to server ping message

[michelepra]

Browser is very lazy to detect websocket disconnect, it's responsive only when client try to send some frame to server.
To do this with current graphl-ws protocol i need query exposed in * .graphl service that is only need for websocket transport and only for keep alive. This is a small hack use of graphql due to protocol absence of this feature.
subscriptions-transport-ws has similar concept but managed from server to client

This issue is for discussion of new message type that client or server can periodically sent (with payload to make more complete) similar to connection_init. The response that client or server send can be customized with payload, similar to connection_ack

[andyrichardson]

@michelepra I'm 100% with you on the need for this 🚀

This kind of heartbeat/ping-pong looks to be a recommended approach.

Edit: Bad link - see application layer example here

[michelepra]

This kind of heartbeat/ping-pong looks to be a recommended approach.

This kind is only available on server side and is already mentioned in #10
What I have proposed is not related to websocket (that ping/pong is) but in application layer transport protocol (that graphl-ws is)

[andyrichardson]

My bad - yeah we are talking about the same thing, I linked to the wrong resource 👍

Application layer ping/pong added to the graphql-ws protocol so we can determine whether messages are being sent/received (without consideration for TCP timeouts)

[pranaypratyush]

This thing is SUPER important for me as well.

[enisdenjo]

For keeping the client alive, you should rely on the Pings and Pongs: The Heartbeat of WebSockets. Pong frames are automatically sent in response to ping messages as required by the spec. This feature is a mandatory built-in, all browsers that don't support Ping and Pong are simply not RFC6455 compliant.

Also, it is a part of this lib already:

graphql-ws/src/use/ws.ts

Lines 64 to 87 in 94ea423

	// keep alive through ping-pong messages
	let pongWait: NodeJS.Timeout | null = null;
	const pingInterval =
	keepAlive > 0 && isFinite(keepAlive)
	? setInterval(() => {
	// ping pong on open sockets only
	if (socket.readyState === socket.OPEN) {
	// terminate the connection after pong wait has passed because the client is idle
	pongWait = setTimeout(() => {
	socket.terminate();
	}, keepAlive);
	// listen for client's pong and stop socket termination
	socket.once('pong', () => {
	if (pongWait) {
	clearTimeout(pongWait);
	pongWait = null;
	}
	});
	socket.ping();
	}
	}, keepAlive)
	: null;

Please beware, these ping-pong frames are built-in! Most browsers probably wont show them in the network developer tools. If you do indeed want to see them: use Firefox (it does expose these WS Protocol frames).

Application layer ping/pong added to the graphql-ws protocol so we can determine whether messages are being sent/received (without consideration for TCP timeouts)

@andyrichardson why would you need a message to determine this? If a WS connection is open, you're guaranteed to have the messages flow through. Also, you'd have to send that "are-your-there?" message in the first place - so you're checking if messages are sent/received by sending a message.

Browser is very lazy to detect websocket disconnect, it's responsive only when client try to send some frame to server.

@michelepra if WS connections close prematurely at any point in time, graphql-ws will reconnect silently and automatically. On the other hand, the servers pings should keep the browser around.

Nevertheless, these types of checks go well beyond the Protocol (and thus graphql-ws because it is a minimal reference implementation).

P.S. We had a concrete message before, but it was cut off in favour of the specified ping-pongs. Check the PR out: #11.

[andyrichardson]

@enisdenjo thanks for the response 🙏

If a WS connection is open, you're guaranteed to have the messages flow through

I can't speak for everyone else but this is what I'm struggling to guarantee.

If you spin up this sandbox and disconnect from the network (wifi off, unplug ethernet, etc) you'll see that onClose doesn't get called... at least not for 10 minutes 😅

The lack of pong from the client will allow the server to know that the client is unresponsive, but the same can't be said the other way round. The client will consider the socket to be alive until the TCP timeout is reached (even though the connection may have been closed minutes earlier by the server).

My guess here is that we need some kind of mechanism for the client to know that the server is responsive (which doesn't look to be an option on the ws layer - at least not in JS land)

Edit: There's a good explanation here about the need for application layer pinging for client side aliveness checks

[michelepra]

P.S. We had a concrete message before, but it was cut off in favour of the specified ping-pongs. Check the PR out: #11.

Server side ping/pong can be managed and is that is implemented in #11

Client side ws !== js websocket and here we cannot send ping frame.
Browser cannot detectet network failure until we try to put some frame on opened connection.
Using concrete message is the only thing that solve network failure detection in client side.
This can be reached with specific graphql query, that is out of graphl-ws protocol and is a bit evil use of graphql, or can be managed by protocol using specific message type like for example

interface ConnectionPingMessage {
  type: 'connection_ping';
  payload?: Record<string, unknown>;
}

interface ConnectionPongMessage {
  type: 'connection_pong';
  payload?: Record<string, unknown>;
}

[enisdenjo]

Edit: There's a good explanation here about the need for application layer pinging for client side aliveness checks

@andyrichardson the comment you referenced simply describes the lack of a JS API for ping-pongs. This is intentional because the browser should be handling the connections, not the applications.

The main reason for delayed connection checks is resource conservation (idling browsers have their JS paused). Adding to your example, if you tried issuing a GQL operation (send a WS message) the browser will re-evaluate the connection and notice that the socket is no more. It will then report the closure and graphql-ws will handle the rest (reconnect silently) - the user will notice nothing.

Even if we add the "ping-pong" concrete message, it will suffer from the exact same problem. The browser will go in idling state (which you cant and shouldnt control), you'll try pinging a server, the browser will notice the connection is gone and graphql-ws will kick in again in the exact same way.

Given the current set of laid out arguments, a ping-pong message is something I am not considering adding. Sorry to be blunt guys, but - you're overcomplicating it!

If you would like to discuss this in further detail, or you would like to raise more arguments: please consider leaving a comment over at the PR for standardising this GraphQL over WebSocket Protocol and have the rest of the brilliant developers engage.

[michelepra]

Even if we add the "ping-pong" concrete message, it will suffer from the exact same problem. The browser will go in idling state (which you cant and shouldnt control), you'll try pinging a server, the browser will notice the connection is gone and graphql-ws will kick in again in the exact same way.

This is the purpose of this issue. If the browser will not notice the connection is gone we never kick in againg until we explicitly call some operation.

User experience in this scenario is very poor because we cannot tell the connection is gone and data that we expect to receive from subscription is never receiving.
Ther's more use case when subscription is call once and then put aside until it receives data.

Is more elegant and minor data consumption that this is done by protocol instead of user specific operation.

PS.
I see in PR one screenshot of spotify websocket like an example, and notice that ping/pong is also exposed in application layer.
WTF why they do this!?!? If connection lost they can tell as soon as possibile to user that connection is broken.
This shows how this necessity is more common than one would like to believe

[enisdenjo]

@michelepra, @andyrichardson, I think I am getting the hang of it now. Let me try summarising:

The client might take too long to notice that the connection is gone (for whatever reason), this is bad UX because the user will have to wait for the "browsers time" to reconnect (which might take 10mins+ as @andyrichardson points out).

In this case, a client ping-pong does indeed make sense. Sorry for taking me too long to realise this, glad you guys stuck around! 😅

I want to do a bit more research before I approach this enhancement. But, I will most certainly consider this!

[enisdenjo]

@michelepra, I see you'd like to have a payload accompany the ping/pong messages. Could you please elaborate a bit more on how and why would this payload be helpful?

[michelepra]

The client might take too long to notice that the connection is gone (for whatever reason), this is bad UX because the user will have to wait for the "browsers time" to reconnect (which might take 10mins+ as @andyrichardson points out).

Even worse, user cannot know that must wait reconnecting, because in it's point of view all is ok until websocket is closed, and this is done only when try to send some frame. This is the reason of having ping/pong in graphql-ws protocol

@michelepra, I see you'd like to have a payload accompany the ping/pong messages. Could you please elaborate a bit more on how and why would this payload be helpful?

I think in more than one use case of payload.... the simplest is for logging, the hardest is for event driven ping/pong.
Payload must be optional because it's purpose is in application layer logic, not in protocol

[andyrichardson]

Sorry to be blunt guys, but - you're overcomplicating it!

While savage, I totally agree

The client might take too long to notice that the connection is gone (for whatever reason), this is bad UX because the user will have to wait for the "browsers time" to reconnect (which might take 10mins+ as @andyrichardson points out).

Yup this is exactly the problem I'm stuck with.

My current workaround is to use the online state and assume that if online is true and the socket is open, we will be receiving messages in real time.

If we go offline or the socket is closed, then we communicate to the user that they won't be receiving updates.

Does this cover all use cases? That's what I'm not so confident about 🤔

[enisdenjo]

Yeah, I always favour good UX and DX; but, I had a hard time understanding the needs for this issue.

Nevertheless, it is pretty clear now and after I did my research I'll come back with a PR (or more questions).

[enisdenjo]

Doing further research I feel like I will indeed stay behind my initial decision - NOT supporting client->server pings. The reason is quite simple, please bear with me.

Network loss does not necessarily mean that the socket needs to be closed, as mentioned in a chromium issue report comment, simply because:

... temporal disconnected sockets might recover and continue to send and receive subsequent packets without any packet loss. Timeout depends on OS.

For example, disable WLAN and re-enable it with the same IP address before it become timeout. Your dammed sockets will be back to send and receive. At that time, both of client and server could not detect closed connection. They can continue communication without any additional opening handshake or session recovery.

In essence, the connection might recover on its own and continue as nothing had happened. Since the lack of (or delayed) connection close events, you guys are mentioning, can occur really only on network disconnects - adding a client->server ping for that case exclusively is not something I want to cover because of the aforementioned arguments.

Furthermore, doing a ws.send while the network is down WILL NOT report the error right away. It will still wait for the OS to settle and decide that the underlaying TCP connection is really down before reporting it through the browser. So, our solution (pinging server from the client) to catch network disruptions as soon as possible WONT work either, you're still stuck with having the OS decide that the socket is closed...

What will happen actually is that the send packets will get queued, and once the network is up again, they'll be sent through. However, if the network never recovers, the OS/browser will report a close event in a timely fashon.

A demonstration of a temporal network down without the socket actually getting closed is below. Please note how doing a ws.send while offline will NOT report a close event and the queued messages will go through once the network recovers.

[michelepra]

Network loss does not necessarily mean that the socket needs to be closed, as mentioned in a chromium issue report comment

This is not the purpose of this issue. Closing socket must not be fired by graphql-ws client out of application logic due to missing pong response, but by browser/OS that detect tcp connection is down. The behaviour of force close websocket and run reconnecting must be in application logic if for application this is requested and managed.

... temporal disconnected sockets might recover and continue to send and receive subsequent packets without any packet loss. Timeout depends on OS.

Exactly. Reported issue of chrome (that is very old) tell behave differently depending on the OS and that's why the state has been forced WontFix because is not a bug of websocket spec implementation.
For example on Windows it throws close event after 60-70 seconds (now with chrome 88 on windows 10 is more short), on linux (??), chromeOS never fired... etc etc

In essence, the connection might recover on its own and continue as nothing had happened. Since the lack of (or delayed) connection close events, you guys are mentioning, can occur really only on network disconnects - adding a client->server ping for that case exclusively is not something I want to cover because of the aforementioned arguments.

This is not quoted here but ping/pong in application layer logic is not only exclusively for detect network disconnects but also for keep connection active as toyoshim say in comment in chrome issue.

If you want to keep the connection in active, you can implement application-level ping-pong or heartbeats checker with your favorite intervals.

For example a few years ago i developed web application where communication with server is based on websocket. Client do some requests that on server was managed similar as graphql subscription. Server was write in java and based on jetty websocket that implement and manage ping/pong websocket spec. Whithout interval messages in application layer like ping from client the socket on server was closed (and session associated closed) and client must continuosly reopen new websocket and rerun previous requests.

So, our solution (pinging server from the client) to catch network disruptions as soon as possible WONT work either, you're still stuck with having the OS decide that the socket is closed...

If application based on graphql-ws wait only close event to catch network disruptions it's partly true due to different OS behaviour. With this in mind client application can settle down some logic based on ping/pong (that now is not possible due to the lack of this in the graphql-ws protocol, this only can be simulated with graphql query made specifically for this purpose)

What will happen actually is that the send packets will get queued, and once the network is up again, they'll be sent through. However, if the network never recovers, the OS/browser will report a close event in a timely fashon.

As quoted above this is based on OS where browser run

[andyrichardson]

Thanks for looking into this @enisdenjo

So, our solution (pinging server from the client) to catch network disruptions as soon as possible WONT work either, you're still stuck with having the OS decide that the socket is closed...

I think sending ping/pong messages would still be a valid approach.

The example flow I would have expected would be:

Alive

• Client sends ping message (we don't care whether the server gets it or not)
• setTimeout is introduced which closes the socket after X seconds
• pong message is received and timeout is cleared
• repeat

Dead

• Client sends ping message (we don't care whether the server gets it or not)
• setTimeout is introduced which closes the socket after X seconds
• pong message is not received within X seconds, close socket and state is now updated

[michelepra]

Show `example`

Alive

• Client sends ping message (we don't care whether the server gets it or not)
• setTimeout is introduced which closes the socket after X seconds
• pong message is received and timeout is cleared
• repeat

Dead

• Client sends ping message (we don't care whether the server gets it or not)
• setTimeout is introduced which closes the socket after X seconds
• pong message is not received within X seconds, close socket and state is now updated

@andyrichardson the example can be ok but be careful of chained timers

[enisdenjo]

Guys, you're missing one key point, the connection might recover. Terminating it early will stop all subscriptions and discard all messages that the server might have sent (or the client) in the meantime because it does not know that the client went away yet. By allowing the OS/browser to control the connection, you will receive all queued up messages if the connection recovers; and if not, you'll get a close event and the client will reconnect silently.

Another crucial thing you're overlooking is that you want to close the connection early while the user is offline. No retries or ping-pongs will put the user back online... You might even experience downsides, like for example closing the connection unnecessarily (OS/browser would've recovered), having the client retries get exceeded and then fail for good.

Why do you want to retry while the user is offline? What do you gain by reporting an error early (and even unnecessarly)?

On the other hand, if the OS/browser manages to recover the connection when the user comes back online - messages from both sides will be flushed; and if it does not manage to recover, it will report a close event AFTER the user came back online - allowing the client to retry exactly when it should.

This is not quoted here but ping/pong in application layer logic is not only exclusively for detect network disconnects but also for keep connection active as toyoshim say in comment in chrome issue.

@michelepra the connection will be kept alive because of the server pings as long as the client is online.

[michelepra]

Guys, you're missing one key point, the connection might recover. Terminating it early will stop all subscriptions and discard all messages that the server might have sent (or the client) in the meantime because it does not know that the client went away yet. By allowing the OS/browser to control the connection, you will receive all queued up messages if the connection recovers; and if not, you'll get a close event and the client will reconnect silently.

Server side is not browser, here connection lost can be detected with websocket ping/pong frame, when connection is closed all subscriptions complete and new messages are discarded
Client side will receive all queued up messages (if server side not detect connection lost) when connection recovers, but we will never had close event when necessary or detecting server is down until we send ping message to server

Another crucial thing you're overlooking is that you want to close the connection early while the user is offline. No retries or ping-pongs will put the user back online... You might even experience downsides, like for example closing the connection unnecessarily (OS/browser would've recovered)

Close the connection is only one of possibilities. This must be in client side application logic, not in graphql-ws.
For example you consider unnecessarily to closing the connection because browser would've automatically recovered. This point of view can be true for one application but not for other, use case can be very different. Therefore it would be better not to consider the examples when defining a transport protocol such as graphql-ws. What people do with client side ping/pong must be out of protocol definition

having the client retries get exceeded and then fail for good.

This means severe network problems (like network devices broken or ISP down) and this must be managed in application, How to do this if we never had close event or we never receiving pong message? Easy, now we cannot because we haven't ping/pong client message

Why do you want to retry while the user is offline? What do you gain by reporting an error early (and even unnecessarly)?

If client application is real time data based, we must consider to notify user as soon as possible that is not online.

On the other hand, if the OS/browser manages to recover the connection when the user comes back online - messages from both sides will be flushed; and if it does not manage to recover, it will report a close event AFTER the user came back online - allowing the client to retry exactly when it should.

And if client never, or very long time, came back online? Now we must considering we cannot show user that is not online due to the lack of client side ping/pong

@michelepra the connection will be kept alive because of the server pings as long as the client is online.

I reported this as example, some year ago (and chrome issue is 10 year) this happend on server side where ping/pong of websocket spec was correctly implemented. I will not exclude this was bug of jetty websocket servlet, but this is not the subject of this issue

[asmeikal]

I'm leaving my two cents here based on my experience: the need for early detection of connection loss, and thus for some kind of ping from the client, is useful when a connection loss triggers a fallback. In the project I'm working on subscriptions update continuously the resources that the user is working on, and if we detect a socket disconnection we start polling these resources, as other services may still be working. Detecting earlier that the connection is closed even when it could be re-established (without message loss) is something that can improve the user experience: instead of seeing the client not updating, the fallback can kick in and update the resources.

But I believe that this should not be a protocol concern, and it can be implemented relatively easily with queries at regular intervals using the same client as the subscriptions, or a subscription that sends messages regularly from the server paired with a timeout on the client.

[michelepra]

But I believe that this should not be a protocol concern, and it can be implemented relatively easily with queries at regular intervals using the same client as the subscriptions, or a subscription that sends messages regularly from the server paired with a timeout on the client.

@asmeikal Is exactly that i said above with "this only can be simulated with graphql query made specifically for this purpose" (and that's what I did because I have no alternative, and the reason why I opened this issue)

I do not agree with "this should not be a protocol concern" because expose and use query (that is message protocol) only to monitoring websocket is an abuse due to the lack on graphql-ws (that is transport protocol) of concrete message type to gain this result.

[enisdenjo]

Client side will receive all queued up messages (if server side not detect connection lost) when connection recovers, but we will never had close event when necessary or detecting server is down until we send ping message to server

@michelepra Actually, until the pong message receive times out. Server downs will be detected immediately, only network disruptions of the client will stall. And for a good reason, they might recover and the messages flush.

Close the connection is only one of possibilities. This must be in client side application logic, not in graphql-ws.

@michelepra You are right, this is application, subjective, logic - something graphql-ws shouldnt be responsible for.

For example you consider unnecessarily to closing the connection because browser would've automatically recovered. This point of view can be true for one application but not for other, use case can be very different. Therefore it would be better not to consider the examples when defining a transport protocol such as graphql-ws. What people do with client side ping/pong must be out of protocol definition

@michelepra Can you give me one other example? Just for the example sake.

This means severe network problems (like network devices broken or ISP down) and this must be managed in application, How to do this if we never had close event or we never receiving pong message? Easy, now we cannot because we haven't ping/pong client message

@michelepra Simple, outside of graphql-ws. Just listen for the online and offline events. You absolutely should not rely on a transport implementation (or protocol) for detecting online/offline statuses.

If client application is real time data based, we must consider to notify user as soon as possible that is not online.

@michelepra Again, outside of graphql-ws. There are other primitives that detect online status, like online and offline events for browsers, and other utilities for NodeJS.

And if client never, or very long time, came back online? Now we must considering we cannot show user that is not online due to the lack of client side ping/pong

@michelepra still a use case for online and offline events.

I am not in favour of adding an additional protocol requirement just to detect the online status... If you want absolutely want to kick the client off as soon as the browser goes offline, you can simply do:

import { createClient } from 'graphql-ws';

let activeSocket;
const client = createClient({
  url: 'wss://i.close/on/offline/event',
  on: {
    connected: (socket) => {
      activeSocket = socket;
    },
    closed: () => {
      activeSocket = undefined;
    },
  },
});

window.addEventListener('offline', () => {
  activeSocket?.close(1001, 'Going Away');
});

This 👆 would be more reliable than any ping-pong message a protocol (or an implementation) could offer. You can even go one step further and setTimeout on the activeSocket.close to apply a delay. Note that closing the connection will also toggle the clients silent retries, so you're not loosing any subscriptions or state.

However, I would absolutely not recommend this, you should leave the heavy lifting to the OS/browser.

But I believe that this should not be a protocol concern, and it can be implemented relatively easily with queries at regular intervals using the same client as the subscriptions, or a subscription that sends messages regularly from the server paired with a timeout on the client.

@asmeikal You dont even need queries, the example above achieves exactly what this issue is describing.

[enisdenjo]

I think e43154f is just enough. The only thing that the client configures is the keep-alive timeout (when to issue a ping), all other logic is up to the implementor.

For example, a close-on-timeout + latency metrics implementation would look like this:

import { createClient } from 'graphql-ws';

let activeSocket,
  timedOut,
  pingSentAt = 0,
  latency = 0;
createClient({
  url: 'ws://i.time.out:4000/and-measure/latency',
  keepAlive: 10_000, // ping server every 10 seconds
  on: {
    connected: (socket) => (activeSocket = socket),
    ping: (received) => {
      if (!received /* sent */) {
        pingSentAt = Date.now();
        timedOut = setTimeout(() => {
          if (activeSocket.readyState === WebSocket.OPEN)
            activeSocket.close(4408, 'Request Timeout');
        }, 5_000); // wait 5 seconds for the pong and then close the connection
      }
    },
    pong: (received) => {
      if (received) {
        latency = Date.now() - pingSentAt;
        clearTimeout(timedOut); // pong is received, clear connection close timeout
      }
    },
  },
});

@michelepra, @andyrichardson, @pranaypratyush, @asmeikal, @idevelop, @backbone87 would love to hear your thoughts on this. 😄

[enisdenjo]

🎉 This issue has been resolved in version 5.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[enisdenjo]

Summary behind the decision of adding the ping/pongs in the Protocol: graphql/graphql-over-http#140 (comment).

[michelepra]

🤟 a small step has been taken, i have some points to clarify:

1. client ping must be send according to application logic, with your implementation this is out of client control. keepAlive parameter is only one point of this logic
2. why you don't consider optional payload like ping/pong websocket protocol?
3. message event must be emitted after check message type is not ping/pong because this type have specific event handler

[enisdenjo]

Hey hey, straight to the point:

1. The idea behind the keep-alive is sending it on an interval. I felt like having something like client.ping is an overkill (for now at least). Do you have an example usage in mind?
2. Keeping it simply, I dont think passing a payload through the ping and pong message is really necessary. The main use case is connection stability, latency measurement and, in general, network probing. Still, suggested example usage?
3. As stated in the documentation: the message event is called for all valid messages received by the client. Mainly useful for debugging and logging received messages.

[michelepra]

1. The idea behind the keep-alive is sending it on an interval. I felt like having something like client.ping is an overkill (for now at least). Do you have an example usage in mind?

i can fancy some example

• monitor idle connection, where client ping must be sent after N milliseconds of receiving last message from websocket, because i can correctly assume that if i receive messages the socket is active.
• Can also be browser limitations on some condition
• ping keepAlive interval can be variable by some logic (example after do http request to other place)
• sending ping can be enable/disable by some conditions

2. Keeping it simply, I dont think passing a payload through the ping and pong message is really necessary. The main use case is connection stability, latency measurement and, in general, network probing. Still, suggested example usage?

Most easy example is for logging purpose, server can logging receiving ping X from client Y
Other example can be in client by sending ping with payload containing progression number, If all is ok (client <- network -> server) i expect to receive pong with this number after ping was sent, If network is unstable message is sent as soon network going on (as you correctly report). With payload i can do more sophisticated thing than reporting "receiving N consecutive pong"

3. As stated in the documentation: the message event is called for all valid messages received by the client. Mainly useful for debugging and logging received messages.

Ok, thanks for explanation

[enisdenjo]

i can fancy some example

• monitor idle connection, where client ping must be sent after N milliseconds of receiving last message from websocket, because i can correctly assume that if i receive messages the socket is active.
• Can also be browser limitations on some condition
• ping keepAlive interval can be variable by some logic (example after do http request to other place)
• sending ping can be enable/disable by some conditions

Awesome! Makes perfect sense. I'll introduce a client.ping soon. Please read: #117 (comment).

Most easy example is for logging purpose, server can logging receiving ping X from client Y
Other example can be in client by sending ping with payload containing progression number, If all is ok (client <- network -> server) i expect to receive pong with this number after ping was sent, If network is unstable message is sent as soon network going on (as you correctly report). With payload i can do more sophisticated thing than reporting "receiving N consecutive pong"

Agreed. A payload does indeed make sense.

[enisdenjo]

@michelepra I realised that a manual (and super extensible) client.ping is already possible by using the socket directly (same for client.ping). I'd like to avoid baking it in if not absolutely necessary.

The benefit of this approach is that you can customise your pinger to fit your exact needs (async ping/pong, throw error on closed connection, integrated responses, logging, and much more...).

This is how a super simple manual pinger client would look like:

import {
  createClient,
  Client,
  ClientOptions,
  stringifyMessage,
  PingMessage,
  PongMessage,
  MessageType,
} from 'graphql-ws';

interface PingerClient extends Client {
  ping(payload?: PingMessage['payload']): void;
  pong(payload?: PongMessage['payload']): void;
}

function createPingerClient(options: ClientOptions): PingerClient {
  let activeSocket;

  const client = createClient({
    disablePong: true,
    ...options,
    on: {
      connected: (socket) => {
        options.on?.connected?.(socket);
        activeSocket = socket;
      },
    },
  });

  return {
    ...client,
    ping: (payload) => {
      if (activeSocket.readyState === WebSocket.OPEN)
        activeSocket.send(
          stringifyMessage({
            type: MessageType.Ping,
            payload,
          }),
        );
    },
    pong: (payload) => {
      if (activeSocket.readyState === WebSocket.OPEN)
        activeSocket.send(
          stringifyMessage({
            type: MessageType.Pong,
            payload,
          }),
        );
    },
  };
}

However, what the client needs is a disablePong option so that you can respond manually when necessary and optionally attach a payload.

[michelepra]

looks nice, i think this can cover almost all use cases

[enisdenjo]

🎉 This issue has been resolved in version 5.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[enisdenjo]

Both optional ping/pong payloads and the disablePong client option, together with a recipe of a custom pinger, is available starting from v5.1.0.

[michelepra]

@enisdenjo server don't send payload, see fix

[enisdenjo]

Hmm, I didnt realise you wanted the server to pong with the same payload as the ping. My original thinking was that you would implement the server response.

But, I think that the default behaviour for having the payload do a round trip makes sense. Let me see what I can do.

[enisdenjo]

🎉 This issue has been resolved in version 5.1.1 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[enisdenjo]

v5.1.1 returns ping's payload through the response pong.

[asmeikal]

Hi @enisdenjo, I got around to trying this! Kudos for making the change retrocompatible, we're upgrading all subscription servers before any client and it's working perfectly! I found out we needed this with an electron app, since it didn't reliably detect when the socket dies.

[andyrichardson]

Massive thanks for getting this supported!

I'm a little late to the game but I had a quick thought about the necessity of bi-directional ping/pong.

client->server ping/pong solves the problem where, without this mechanism, a socket timeout has taken place on the server and the client has no way of knowing. The ideal scenario is that both the client and the server acknowledge a socket timeout at the same time.

If this is the case, I think this could be done without the need for bi-directional ping/pong.

Client acknowledgment of a server-side timeout could work as follows:

• Client sends connection_init
• Server sends connection_ack, payload includes socket_timeout (the socket timeout value + delay between pong receipt and subsequent ping)
• Server sends ping to client
• Client sends pong to server

Following a pong to the server, the client would expect a subsequent ping from the server within socket_timeout milliseconds. If this is not the case, it's safe to assume that the server attempted to send a pong but it never arrived.

This approach could have a few advantages:

• Socket aliveness is mutually assured (both client + server use same timeout)
• Socket timeout identification by both parties would be much closer together (identical acknowledgment - connection_ack transport overhead)

[enisdenjo]

@andyrichardson already possible with minimal effort. 😄

On the client, you can use the EventConnectedListener to read out the accompanying payload (or the EventPingListener if you wish to transmit the socket_timout on the first ping or every ping).

Then, combine the payload with the "Client usage with manual pings and pongs" recipe and implement your own pinger following whatever logic you find necessary.

On the server, you can use the "Server usage with ws and subprotocol pings and pongs" recipe for customising the server-side pinger logic.

Please note that the defaults of graphql-ws will not change and it will never use the subprotocol ping/pongs on its own. The subprotocol ping/pongs are considered helpers for cases where using WS protocol level pings and pongs is not possible. Having said that, it is up to the implementor to invest effort in achieving the wished keep-alive logic.

[andyrichardson]

I knew this must have been considered! Thanks for explaining 🔥