DOC Add documentation on websockets level ping frames (#345)

Author: leszekhanusz

docs/transports/websockets.rst

@@ -82,6 +82,8 @@ There are two ways to send authentication tokens with websockets depending on th
         init_payload={'Authorization': 'token'}
     )
 
+.. _websockets_transport_keepalives:
+
 Keep-Alives
 -----------
 
@@ -125,6 +127,28 @@ Here is an example with a ping sent every 60 seconds, expecting a pong within 10
         pong_timeout=10,
     )
 
+Underlying websockets protocol
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In addition to the keep-alives described above for the apollo and graphql-ws protocols,
+there are also `ping frames`_ sent by the underlying websocket connection itself for both of them.
+
+These pings are enabled by default (every 20 seconds) and could be modified or disabled
+by passing extra arguments to the :code:`connect` call of the websockets client using the
+:code:`connect_args` argument of the transport.
+
+.. code-block:: python
+
+    # Disabling websocket protocol level pings
+    transport = WebsocketsTransport(
+        url='wss://SERVER_URL:SERVER_PORT/graphql',
+        connect_args={"ping_interval": None},
+    )
+
+See the `websockets keepalive documentation`_ for details.
+
 .. _version 5.6.1: https://github.com/enisdenjo/graphql-ws/releases/tag/v5.6.1
 .. _Apollo websockets transport protocol:  https://github.com/apollographql/subscriptions-transport-ws/blob/master/PROTOCOL.md
 .. _GraphQL-ws websockets transport protocol: https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md
+.. _ping frames: https://www.rfc-editor.org/rfc/rfc6455.html#section-5.5.2
+.. _websockets keepalive documentation: https://websockets.readthedocs.io/en/stable/topics/timeouts.html#keepalive-in-websockets

gql/transport/websockets.py

@@ -64,14 +64,19 @@ def __init__(
             a sign of liveness from the server.
         :param ping_interval: Delay in seconds between pings sent by the client to
             the backend for the graphql-ws protocol. None (by default) means that
-            we don't send pings.
+            we don't send pings. Note: there are also pings sent by the underlying
+            websockets protocol. See the
+            :ref:`keepalive documentation <websockets_transport_keepalives>`
+            for more information about this.
         :param pong_timeout: Delay in seconds to receive a pong from the backend
             after we sent a ping (only for the graphql-ws protocol).
             By default equal to half of the ping_interval.
         :param answer_pings: Whether the client answers the pings from the backend
             (for the graphql-ws protocol).
             By default: True
-        :param connect_args: Other parameters forwarded to websockets.connect
+        :param connect_args: Other parameters forwarded to
+            `websockets.connect <https://websockets.readthedocs.io/en/stable/reference/\
+            client.html#opening-a-connection>`_
         :param subprotocols: list of subprotocols sent to the
             backend in the 'subprotocols' http header.
             By default: both apollo and graphql-ws subprotocols.