[@azure/web-pubsub-client] Use ping/pong as an accurate keepalive (#36751)

### Packages impacted by this PR
@azure/web-pubsub-client

### Issues associated with this PR


### Describe the problem that is addressed by this PR
Web PubSub follows the WebSocket (WS) ping-pong spec and periodically
sends a ping frame to the client, the client should respond with a pong
frame. This mechanism enables Web PubSub to detect client liveness
quickly. But sometimes when there is network interruptions, Web PubSub
detects the client offline quickly, however, client lacks a way to
detect if itself is offline, client might consider itself as still
online for quite some time and fails to reconnect quickly. In some
clients, for example, in the browser, WebSocket ping/pong frames are
quite low-level, and the client does not have access to there ping/pong
frames or events. Here we provide a ping-pong mechanism in the
application layer, providing the clients a way to detect the client
liveness.

### What are the possible designs available to address the problem? If
there are more than one possible design, why was the one in this PR
chosen?


### Are there test cases added in this PR? _(If not, why?)_


### Provide a list of related PRs _(if any)_


### Command used to generate this PR:**_(Applicable only to SDK release
request PRs)_

### Checklists
- [ ] Added impacted package name to the issue description
- [ ] Does this PR needs any fixes in the SDK Generator?** _(If so,
create an Issue in the
[Autorest/typescript](https://github.com/Azure/autorest.typescript)
repository and link it here)_
- [ ] Added a changelog (if necessary)

Author: zackliu

sdk/web-pubsub/web-pubsub-client/review/web-pubsub-client-node.api.md

@@ -41,6 +41,10 @@ export type DownstreamMessageType =
 */
 "ack"
 /**
+* Type for PongMessage
+*/
+| "pong"
+/**
 * Type for ConnectedMessage
 */
 | "connected"
@@ -133,6 +137,16 @@ export interface OnServerDataMessageArgs {
 export interface OnStoppedArgs {
 }
 
+// @public
+export interface PingMessage extends WebPubSubMessageBase {
+    readonly kind: "ping";
+}
+
+// @public
+export interface PongMessage extends WebPubSubMessageBase {
+    readonly kind: "pong";
+}
+
 // @public
 export type RetryMode = "Exponential" | "Fixed";
 
@@ -224,7 +238,11 @@ export type UpstreamMessageType =
 /**
 * Type for SequenceAckMessage
 */
-| "sequenceAck";
+| "sequenceAck"
+/**
+* Type for PingMessage
+*/
+| "ping";
 
 // @public
 export class WebPubSubClient {
@@ -259,6 +277,8 @@ export interface WebPubSubClientCredential {
 export interface WebPubSubClientOptions {
     autoReconnect?: boolean;
     autoRejoinGroups?: boolean;
+    keepAliveIntervalInMs?: number;
+    keepAliveTimeoutInMs?: number;
     messageRetryOptions?: WebPubSubRetryOptions;
     protocol?: WebPubSubClientProtocol;
     reconnectRetryOptions?: WebPubSubRetryOptions;
@@ -298,7 +318,7 @@ export const WebPubSubJsonProtocol: () => WebPubSubClientProtocol;
 export const WebPubSubJsonReliableProtocol: () => WebPubSubClientProtocol;
 
 // @public
-export type WebPubSubMessage = GroupDataMessage | ServerDataMessage | JoinGroupMessage | LeaveGroupMessage | ConnectedMessage | DisconnectedMessage | SendToGroupMessage | SendEventMessage | SequenceAckMessage | AckMessage;
+export type WebPubSubMessage = GroupDataMessage | ServerDataMessage | JoinGroupMessage | LeaveGroupMessage | ConnectedMessage | DisconnectedMessage | SendToGroupMessage | SendEventMessage | SequenceAckMessage | PingMessage | AckMessage | PongMessage;
 
 // @public
 export interface WebPubSubMessageBase {

sdk/web-pubsub/web-pubsub-client/samples-dev/helloworld.ts

@@ -8,6 +8,7 @@
 import type {
   WebPubSubClientCredential,
   GetClientAccessUrlOptions,
+  WebPubSubClientOptions,
 } from "@azure/web-pubsub-client";
 import { WebPubSubClient } from "@azure/web-pubsub-client";
 import { WebPubSubServiceClient } from "@azure/web-pubsub";
@@ -17,6 +18,10 @@ import "dotenv/config";
 async function main(): Promise<void> {
   const hubName = "sample_chat";
   const groupName = "testGroup";
+  const options: WebPubSubClientOptions = {
+    keepAliveTimeoutInMs: 500,
+    keepAliveIntervalInMs: 100,
+  };
   const serviceClient = new WebPubSubServiceClient(
     process.env.WPS_ENDPOINT!,
     new DefaultAzureCredential(),
@@ -30,9 +35,12 @@ async function main(): Promise<void> {
       })
     ).url;
   };
-  const client = new WebPubSubClient({
-    getClientAccessUrl: fetchClientAccessUrl,
-  } as WebPubSubClientCredential);
+  const client = new WebPubSubClient(
+    {
+      getClientAccessUrl: fetchClientAccessUrl,
+    } as WebPubSubClientCredential,
+    options,
+  );
 
   client.on("connected", (e) => {
     console.log(`Connection ${e.connectionId} is connected.`);
@@ -77,7 +85,12 @@ async function main(): Promise<void> {
     "binary",
   );
   await delay(1000);
+  await client.sendToGroup(groupName, "hello world after ping/pong", "text", {
+    fireAndForget: true,
+  });
+  await delay(200);
   client.stop();
+  console.log("Client stopped");
 }
 
 main().catch((e) => {

sdk/web-pubsub/web-pubsub-client/src/models/index.ts

@@ -29,6 +29,21 @@ export interface WebPubSubClientOptions {
    * The retry options for reconnection. Only available when autoReconnect is true.
    */
   reconnectRetryOptions?: WebPubSubRetryOptions;
+  /**
+   * The idle timeout in milliseconds used to detect half-open connections when no data or pong has
+   * been received. Default is 120000ms (120 seconds). Set to 0 to disable this timeout check. Must
+   * be greater than or equal to 0. We recommend keeping this value comfortably larger than
+   * `keepAliveIntervalInMs` (for example 3x) so that probes have time to run before the timeout
+   * closes the socket.
+   */
+  keepAliveTimeoutInMs?: number;
+  /**
+   * The interval in milliseconds at which to send keep-alive ping messages to the runtime. Default
+   * is 20000ms (20 seconds). Set to 0 to disable client-initiated keep-alive pings. Must be greater
+   * than or equal to 0. We recommend choosing a value that is lower than `keepAliveTimeoutInMs`
+   * (again, about 3x lower) so the timeout only triggers when multiple pings fail.
+   */
+  keepAliveIntervalInMs?: number;
 }
 
 /**

sdk/web-pubsub/web-pubsub-client/src/models/messages.ts

@@ -16,7 +16,9 @@ export type WebPubSubMessage =
   | SendToGroupMessage
   | SendEventMessage
   | SequenceAckMessage
-  | AckMessage;
+  | PingMessage
+  | AckMessage
+  | PongMessage;
 
 /**
  * The common of web pubsub message
@@ -33,6 +35,10 @@ export type DownstreamMessageType =
    * Type for AckMessage
    */
   | "ack"
+  /**
+   * Type for PongMessage
+   */
+  | "pong"
   /**
    * Type for ConnectedMessage
    */
@@ -73,7 +79,11 @@ export type UpstreamMessageType =
   /**
    * Type for SequenceAckMessage
    */
-  | "sequenceAck";
+  | "sequenceAck"
+  /**
+   * Type for PingMessage
+   */
+  | "ping";
 
 /**
  * The ack message
@@ -97,6 +107,16 @@ export interface AckMessage extends WebPubSubMessageBase {
   error?: AckMessageError;
 }
 
+/**
+ * The pong message
+ */
+export interface PongMessage extends WebPubSubMessageBase {
+  /**
+   * Message type
+   */
+  readonly kind: "pong";
+}
+
 /**
  * Error detail in AckMessage
  */
@@ -305,6 +325,16 @@ export interface SequenceAckMessage extends WebPubSubMessageBase {
   sequenceId: number;
 }
 
+/**
+ * Ping message
+ */
+export interface PingMessage extends WebPubSubMessageBase {
+  /**
+   * Message type
+   */
+  readonly kind: "ping";
+}
+
 /**
  * The data type
  */

sdk/web-pubsub/web-pubsub-client/src/protocols/jsonProtocolBase.ts

@@ -3,6 +3,7 @@
 
 import type {
   AckMessage,
+  PongMessage,
   ConnectedMessage,
   DisconnectedMessage,
   GroupDataMessage,
@@ -59,6 +60,8 @@ export function parseMessages(input: string): WebPubSubMessage | null {
     }
   } else if (typedMessage.type === "ack") {
     returnMessage = { ...parsedMessage, kind: "ack" } as AckMessage;
+  } else if (typedMessage.type === "pong") {
+    returnMessage = { ...parsedMessage, kind: "pong" } as PongMessage;
   } else {
     // Forward compatible
     return null;
@@ -102,6 +105,10 @@ export function writeMessage(message: WebPubSubMessage): string {
       data = { type: "sequenceAck", sequenceId: message.sequenceId } as SequenceAckData;
       break;
     }
+    case "ping": {
+      data = { type: "ping" } as PingData;
+      break;
+    }
     default: {
       throw new Error(`Unsupported type: ${message.kind}`);
     }
@@ -144,6 +151,10 @@ interface SequenceAckData {
   sequenceId: number;
 }
 
+interface PingData {
+  readonly type: "ping";
+}
+
 function getPayload(data: JSONTypes | ArrayBuffer, dataType: WebPubSubDataType): any {
   switch (dataType) {
     case "text": {