feat(graphql): reply with pong when the server sends a ping

The graphql-transport-ws protocol defines ping/pong as bidirectional and
requires the receiving party to answer a ping as soon as possible. The
client only ever sent pings, so a server-initiated ping fell through to
'unrecognized' and was silently dropped.

Inert on the legacy endpoint, which never initiates a ping (its heartbeat
is 'ka'); this prepares the client for /graphql/subscription-v2, whose
handler is configured with a 10s keep-alive that pings idle connections.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: Stanislav Deviatykh

packages/javascript-api/src/lib/services/graphql/__tests__/graphql-subscriptions.spec.ts

@@ -245,6 +245,19 @@ describe('GraphQL subscriptions', () => {
     subscription.unsubscribe();
   });
 
+  it('replies with a pong when the server sends a ping', async () => {
+    const subscription = fixture.triggerSubscription();
+
+    await fixture.handleConnectionInit();
+    await fixture.consumeSubscribeMessage();
+
+    fixture.sendMessageToClient({ type: 'ping' });
+
+    expect(await fixture.getNextMessage()).toEqual({ type: 'pong' });
+
+    subscription.unsubscribe();
+  });
+
   it('when the server sends an error, it will reconnect and subscribe again', async () => {
     const subscription = fixture.triggerSubscription();
     useFakeSetInterval();

packages/javascript-api/src/lib/services/graphql/__tests__/subscription-protocol.spec.ts

@@ -32,6 +32,10 @@ describe('LegacySubscriptionProtocol', () => {
     it('serializes ping without id and payload', () => {
       expect(JSON.parse(protocol.serializePing())).toEqual({ type: 'ping' });
     });
+
+    it('serializes pong without id and payload', () => {
+      expect(JSON.parse(protocol.serializePong())).toEqual({ type: 'pong' });
+    });
   });
 
   describe('incoming frames', () => {
@@ -47,6 +51,12 @@ describe('LegacySubscriptionProtocol', () => {
       ).toEqual({ type: 'connection-ack' });
     });
 
+    it('parses a server-sent ping', () => {
+      expect(protocol.parseIncomingMessage('{"type":"ping"}')).toEqual({
+        type: 'ping',
+      });
+    });
+
     it('parses pong', () => {
       expect(protocol.parseIncomingMessage('{"type":"pong"}')).toEqual({
         type: 'pong',

packages/javascript-api/src/lib/services/graphql/graphql.service.ts

@@ -542,6 +542,12 @@ export class GraphqlService {
           break;
         }
 
+        case 'ping':
+          // The protocol requires the receiving party to answer a ping as soon
+          // as possible. Only the newer endpoint pings us; the legacy one never does.
+          this.sendRawMessage(this.protocol.serializePong());
+          break;
+
         case 'pong':
           clearTimeout(this.pongTimeout);
           this.connectionAttemptsCount = 0;

packages/javascript-api/src/lib/services/graphql/subscription-protocol.ts

@@ -17,6 +17,7 @@ export interface QminderGraphQLError {
 export type IncomingSubscriptionMessage =
   | { readonly type: 'connection-ack' }
   | { readonly type: 'keep-alive' }
+  | { readonly type: 'ping' }
   | { readonly type: 'pong' }
   | {
       readonly type: 'data';
@@ -45,6 +46,11 @@ export interface SubscriptionProtocol {
   serializeSubscribe(id: string, query: string): string;
   serializeUnsubscribe(id: string): string;
   serializePing(): string;
+  /**
+   * A `pong` answering a `ping` from the server. The `graphql-transport-ws`
+   * protocol requires the receiving party to answer a ping as soon as possible.
+   */
+  serializePong(): string;
   parseIncomingMessage(data: string): IncomingSubscriptionMessage;
 }
 
@@ -106,6 +112,10 @@ export class LegacySubscriptionProtocol implements SubscriptionProtocol {
     return JSON.stringify({ type: LegacyMessageType.GQL_PING });
   }
 
+  serializePong(): string {
+    return JSON.stringify({ type: LegacyMessageType.GQL_PONG });
+  }
+
   parseIncomingMessage(data: string): IncomingSubscriptionMessage {
     const message: LegacyMessage = JSON.parse(data);
 
@@ -116,6 +126,9 @@ export class LegacySubscriptionProtocol implements SubscriptionProtocol {
       case LegacyMessageType.GQL_CONNECTION_ACK:
         return { type: 'connection-ack' };
 
+      case LegacyMessageType.GQL_PING:
+        return { type: 'ping' };
+
       case LegacyMessageType.GQL_PONG:
         return { type: 'pong' };