Mint.HTTP.stream_request_body

You're seeing just the function stream_request_body, go back to Mint.HTTP module for more information.
Link to this function

stream_request_body(conn, ref, body)

View Source

Specs

stream_request_body(
  t(),
  Mint.Types.request_ref(),
  iodata() | :eof | {:eof, trailing_headers :: Mint.Types.headers()}
) :: {:ok, t()} | {:error, t(), Mint.Types.error()}

Streams a chunk of the request body on the connection or signals the end of the body.

If a request is opened (through request/5) with the body as :stream, then the body can be streamed through this function. The function takes a conn, a request_ref returned by request/5 to identify the request to stream the body for, and a chunk of body to stream. The value of chunk can be:

  • iodata - a chunk of iodata is transmitted to the server as part of the body of the request. If the chunk is empty, in HTTP/1 it's a no-op, while in HTTP/2 a DATA frame will be sent.

  • :eof - signals the end of the streaming of the request body for the given request. Usually the server won't send any reply until this is sent.

  • {:eof, trailing_headers} - sends trailing headers and signals the end of the streaming of the request body for the given request. This behaves the same way as :eof but first sends the trailing headers. See the "Trailing headers" section below.

This function always returns an updated connection to be stored over the old connection.

For information about transfer encoding and content length in HTTP/1, see Mint.HTTP1.stream_request_body/3.

Trailing headers

HTTP trailing headers can be sent after the body of a request. The behaviour is slightly different for HTTP/1 and HTTP/2.

In HTTP/1, trailing headers are only supported if the transfer encoding is set to chunked. See Mint.HTTP1.stream_request_body/3 for more information on chunked transfer encoding.

In HTTP/2, trailing headers behave like normal headers. You don't need to care about the transfer encoding.

The trailer header

As specified in section 4.4 of RFC 7230, in HTTP/1 you need to specify which headers you're going to send as trailing headers using the trailer header. The trailer header applies to both HTTP/1 and HTTP/2. See the examples below for more information.

The te header

As specified in section 4.3 of RFC 7230, the te (or TE) header is used to specify which transfer-encodings the client is willing to accept (besides chunked). Mint supports decoding of trailing headers, but if you want to notify the server that you are accepting trailing headers, use the trailers value in the te header. For example:

Mint.HTTP.request(conn, "GET", "/", [{"te", "trailers"}], "some body")

Note that the te header can also be used to communicate which encodings you support to the server.

Examples

Let's see an example of streaming an empty JSON object ({}) by streaming one curly brace at a time.

headers = [{"content-type", "application/json"}, {"content-length", "2"}]
{:ok, conn, request_ref} = Mint.HTTP.request(conn, "POST", "/", headers, :stream)
{:ok, conn} = Mint.HTTP.stream_request_body(conn, request_ref, "{")
{:ok, conn} = Mint.HTTP.stream_request_body(conn, request_ref, "}")
{:ok, conn} = Mint.HTTP.stream_request_body(conn, request_ref, :eof)

Here's an example of sending trailing headers:

headers = [{"content-type", "application/json"}, {"trailer", "my-trailer, x-expires"}]
{:ok, conn, request_ref} = Mint.HTTP.request(conn, "POST", "/", headers, :stream)

{:ok, conn} = Mint.HTTP.stream_request_body(conn, request_ref, "{}")

trailing_headers = [{"my-trailer", "xxx"}, {"x-expires", "10 days"}]
{:ok, conn} = Mint.HTTP.stream_request_body(conn, request_ref, {:eof, trailing_headers})