WebsocketsTransport¶

The websockets transport supports both:

the Apollo websockets transport protocol.

the GraphQL-ws websockets transport protocol

It will propose both subprotocols to the backend and detect the supported protocol from the response http headers returned by the backend.

Note

For some backends (graphql-ws before version 5.6.1 without backwards compatibility), it may be necessary to specify only one subprotocol to the backend. It can be done by using subprotocols=[WebsocketsTransport.GRAPHQLWS_SUBPROTOCOL] or subprotocols=[WebsocketsTransport.APOLLO_SUBPROTOCOL] in the transport arguments.

This transport allows to do multiple queries, mutations and subscriptions on the same websocket connection.

Reference: gql.transport.websockets.WebsocketsTransport

import asyncio
import logging

from gql import Client, gql
from gql.transport.websockets import WebsocketsTransport

logging.basicConfig(level=logging.INFO)


async def main():

    transport = WebsocketsTransport(url="wss://countries.trevorblades.com/graphql")

    # Using `async with` on the client will start a connection on the transport
    # and provide a `session` variable to execute queries on this connection
    async with Client(
        transport=transport,
        fetch_schema_from_transport=True,
    ) as session:

        # Execute single query
        query = gql(
            """
            query getContinents {
              continents {
                code
                name
              }
            }
        """
        )
        result = await session.execute(query)
        print(result)

        # Request subscription
        subscription = gql(
            """
            subscription {
                somethingChanged {
                    id
                }
            }
        """
        )
        async for result in session.subscribe(subscription):
            print(result)


asyncio.run(main())

Websockets SSL¶

If you need to connect to an ssl encrypted endpoint:

use wss instead of ws in the url of the transport

transport = WebsocketsTransport(
    url='wss://SERVER_URL:SERVER_PORT/graphql',
    headers={'Authorization': 'token'}
)

If you have a self-signed ssl certificate, you need to provide an ssl_context with the server public certificate:

import pathlib
import ssl

ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
localhost_pem = pathlib.Path(__file__).with_name("YOUR_SERVER_PUBLIC_CERTIFICATE.pem")
ssl_context.load_verify_locations(localhost_pem)

transport = WebsocketsTransport(
    url='wss://SERVER_URL:SERVER_PORT/graphql',
    ssl=ssl_context
)

If you have also need to have a client ssl certificate, add:

ssl_context.load_cert_chain(certfile='YOUR_CLIENT_CERTIFICATE.pem', keyfile='YOUR_CLIENT_CERTIFICATE_KEY.key')

Websockets authentication¶

There are two ways to send authentication tokens with websockets depending on the server configuration.

Using HTTP Headers

transport = WebsocketsTransport(
    url='wss://SERVER_URL:SERVER_PORT/graphql',
    headers={'Authorization': 'token'}
)

With a payload in the connection_init websocket message

transport = WebsocketsTransport(
    url='wss://SERVER_URL:SERVER_PORT/graphql',
    init_payload={'Authorization': 'token'}
)

Keep-Alives¶

Apollo protocol¶

With the Apollo protocol, the backend can optionally send unidirectional keep-alive (“ka”) messages (only from the server to the client).

It is possible to configure the transport to close if we don’t receive a “ka” message within a specified time using the keep_alive_timeout parameter.

Here is an example with 60 seconds:

transport = WebsocketsTransport(
    url='wss://SERVER_URL:SERVER_PORT/graphql',
    keep_alive_timeout=60,
)

One disadvantage of the Apollo protocol is that because the keep-alives are only sent from the server to the client, it can be difficult to detect the loss of a connection quickly from the server side.

GraphQL-ws protocol¶

With the GraphQL-ws protocol, it is possible to send bidirectional ping/pong messages. Pings can be sent either from the client or the server and the other party should answer with a pong.

As with the Apollo protocol, it is possible to configure the transport to close if we don’t receive any message from the backend within the specified time using the keep_alive_timeout parameter.

But there is also the possibility for the client to send pings at a regular interval and verify that the backend sends a pong within a specified delay. This can be done using the ping_interval and pong_timeout parameters.

Here is an example with a ping sent every 60 seconds, expecting a pong within 10 seconds:

transport = WebsocketsTransport(
    url='wss://SERVER_URL:SERVER_PORT/graphql',
    ping_interval=60,
    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 connect call of the websockets client using the connect_args argument of the transport.

# 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.