This RFC proposes adding a specification of how "Incremental" GraphQL results should be delivered to clients, using HTTP chunked transfer encoding.
An Incremental result is a GraphQL result that is split up into multiple payloads, allowing clients quicker access to parts of the results. Currently this is supported by the proposed @defer
and @stream
directives (RFC).
The HTTP response for an incrementally delivered response should contain the transfer-encoding: chunked
response header. Chunked transfer encoding allows the body of the response to be delivered as a series of chunks, allowing clients to read each chunk of the response as it is sent without waiting for the entire response.
The HTTP response for an incrementally delivered response should conform to the specification of multipart content defined by the W3 in rfc1341. The HTTP response must contain the Content-Type
response header with a specified boundary, for example Content-Type: multipart/mixed; boundary="-"
. A simple boundary of -
can be used as there is no possiblity of conflict with JSON data. However, any arbitrary boundary may be used.
An example response body will look like:
---
Content-Type: application/json; charset=utf-8
{"data":{"hello":"Hello Rob"},"hasNext":true}
---
Content-Type: application/json; charset=utf-8
{"data":{"test":"Hello World"},"path":[],"hasNext":false}
-----
- The boundary used is
-
and is passed to the client in the http response'sContent-Type
header. Note that headers can appear in both the HTTP response itself and as part of the response body. TheContent-Type
header must be sent in the HTTP response. - An initial boundary is sent marking the end of the preamble area.
- Each part of the multipart response must contain a
Content-Type
header. Similar to the GraphQL specification this specification does not require a specific serialization format. For consistency and ease of notation, examples of the response are given in JSON throughout the spec. - After all headers, an additional
CRLF
is sent. - The payload is sent, followed by a
CRLF
. - After each payload, a boundary is sent. For the final payload, the terminating boundary of
-----
followed by aCRLF
is sent. For all other payloads a boundary of---
followed by aCRFL
is sent.
express-graphql
: pull requestHot Chocolate
: release
- fetch-multipart-graphql - Browser support using
fetch
orXMLHttpRequest
- meros - A fast utility for reading streamed multipart/mixed responses on the client.