diff --git a/docs/transports/websockets.rst b/docs/transports/websockets.rst index 23e4735a..a8f6cac6 100644 --- a/docs/transports/websockets.rst +++ b/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 diff --git a/gql/transport/websockets.py b/gql/transport/websockets.py index 9e111551..c385d3d7 100644 --- a/gql/transport/websockets.py +++ b/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 ` + 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 `_ :param subprotocols: list of subprotocols sent to the backend in the 'subprotocols' http header. By default: both apollo and graphql-ws subprotocols.