Incremental Delivery over HTTP

November 18, 2020 ยท View on GitHub

This RFC proposes adding a specification of how "Incremental" GraphQL results should be delivered to clients, using HTTP chunked transfer encoding.

Incremental Results

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

transfer-encoding: chunked

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.

content-type: multipart/mixed

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's Content-Type header. Note that headers can appear in both the HTTP response itself and as part of the response body. The Content-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 a CRLF is sent. For all other payloads a boundary of --- followed by a CRFL is sent.

Server Implementations

Client Implementations

  • fetch-multipart-graphql - Browser support using fetch or XMLHttpRequest
  • meros - A fast utility for reading streamed multipart/mixed responses on the client.