add ping(websocket, payload) util (#4325)

Author: KhafraDev

docs/docs/api/WebSocket.md

@@ -78,6 +78,33 @@ setInterval(() => write(), 5000)
 
 ```
 
+## ping(websocket, payload)
+Arguments:
+
+* **websocket** `WebSocket` - The WebSocket instance to send the ping frame on
+* **payload** `Buffer|undefined` (optional) - Optional payload data to include with the ping frame. Must not exceed 125 bytes.
+
+Sends a ping frame to the WebSocket server. The server must respond with a pong frame containing the same payload data. This can be used for keepalive purposes or to verify that the connection is still active.
+
+### Example:
+
+```js
+import { WebSocket, ping } from 'undici'
+
+const ws = new WebSocket('wss://echo.websocket.events')
+
+ws.addEventListener('open', () => {
+  // Send ping with no payload
+  ping(ws)
+
+  // Send ping with payload
+  const payload = Buffer.from('hello')
+  ping(ws, payload)
+})
+```
+
+**Note**: A ping frame cannot have a payload larger than 125 bytes. The ping will only be sent if the WebSocket connection is in the OPEN state.
+
 ## Read More
 
 - [MDN - WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket)

index.js

@@ -157,10 +157,12 @@ module.exports.parseMIMEType = parseMIMEType
 module.exports.serializeAMimeType = serializeAMimeType
 
 const { CloseEvent, ErrorEvent, MessageEvent } = require('./lib/web/websocket/events')
-module.exports.WebSocket = require('./lib/web/websocket/websocket').WebSocket
+const { WebSocket, ping } = require('./lib/web/websocket/websocket')
+module.exports.WebSocket = WebSocket
 module.exports.CloseEvent = CloseEvent
 module.exports.ErrorEvent = ErrorEvent
 module.exports.MessageEvent = MessageEvent
+module.exports.ping = ping
 
 module.exports.WebSocketStream = require('./lib/web/websocket/stream/websocketstream').WebSocketStream
 module.exports.WebSocketError = require('./lib/web/websocket/stream/websocketerror').WebSocketError

lib/web/websocket/websocket.js

@@ -8,6 +8,7 @@ const {
   isConnecting,
   isEstablished,
   isClosing,
+  isClosed,
   isValidSubprotocol,
   fireEvent,
   utf8Decode,
@@ -21,6 +22,7 @@ const { getGlobalDispatcher } = require('../../global')
 const { types } = require('node:util')
 const { ErrorEvent, CloseEvent, createFastMessageEvent } = require('./events')
 const { SendQueue } = require('./sender')
+const { WebsocketFrameSend } = require('./frame')
 const { channels } = require('../../core/diagnostics')
 
 /**
@@ -586,8 +588,32 @@ class WebSocket extends EventTarget {
       })
     }
   }
+
+  /**
+   * @param {WebSocket} ws
+   * @param {Buffer|undefined} buffer
+   */
+  static ping (ws, buffer) {
+    if (!Buffer.isBuffer(buffer)) {
+      throw new TypeError('Expected buffer payload')
+    } else if (buffer.length > 125) {
+      throw new TypeError('A PING frame cannot have a body larger than 125 bytes.')
+    }
+
+    // An endpoint MAY send a Ping frame any time after the connection is
+    // established and before the connection is closed.
+    const readyState = ws.#handler.readyState
+
+    if (isEstablished(readyState) && !isClosing(readyState) && !isClosed(readyState)) {
+      const frame = new WebsocketFrameSend(buffer)
+      ws.#handler.socket.write(frame.createFrame(opcodes.PING))
+    }
+  }
 }
 
+const { ping } = WebSocket
+Reflect.deleteProperty(WebSocket, 'ping')
+
 // https://websockets.spec.whatwg.org/#dom-websocket-connecting
 WebSocket.CONNECTING = WebSocket.prototype.CONNECTING = states.CONNECTING
 // https://websockets.spec.whatwg.org/#dom-websocket-open
@@ -682,5 +708,6 @@ webidl.converters.WebSocketSendData = function (V) {
 }
 
 module.exports = {
-  WebSocket
+  WebSocket,
+  ping
 }

test/websocket/ping-util.js

@@ -0,0 +1,56 @@
+'use strict'
+
+const { test } = require('node:test')
+const { WebSocketServer } = require('ws')
+const { WebSocket, ping } = require('../..')
+const { tspl } = require('@matteo.collina/tspl')
+
+test('ping', async (t) => {
+  const { deepStrictEqual, completed } = tspl(t, { plan: 1 })
+
+  const pingBody = Buffer.from('ping body')
+  const wss = new WebSocketServer({ port: 0 })
+
+  wss.on('connection', (ws) => {
+    ws.on('ping', (b) => {
+      deepStrictEqual(b, pingBody)
+    })
+  })
+
+  const ws = new WebSocket(`ws://localhost:${wss.address().port}`)
+
+  ws.addEventListener('open', () => {
+    ping(ws, pingBody)
+  })
+
+  t.after(() => {
+    ws.close()
+    wss.close()
+  })
+
+  await completed
+})
+
+test('attempting to send invalid ping body', async (t) => {
+  const { completed, throws, fail } = tspl(t, { plan: 2 })
+
+  const wss = new WebSocketServer({ port: 0 })
+
+  wss.on('connection', (ws) => {
+    ws.on('ping', () => {
+      fail('Received unexpected ping')
+    })
+  })
+
+  const ws = new WebSocket(`ws://localhost:${wss.address().port}`)
+
+  throws(() => ping(ws, Buffer.from('a'.repeat(126))))
+  throws(() => ping(ws, 'a'.repeat(125)))
+
+  t.after(() => {
+    ws.close()
+    wss.close()
+  })
+
+  await completed
+})

types/websocket.d.ts

@@ -182,3 +182,5 @@ export declare const WebSocketError: {
   prototype: WebSocketError
   new (type: string, init?: WebSocketCloseInfo): WebSocketError
 }
+
+export declare const ping: (ws: WebSocket, body?: Buffer) => void