Mint.HTTP.stream_request_body
stream_request_body
, go back to Mint.HTTP module for more information.
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})