Mint.HTTP1 (Mint v1.8.0)
View SourceProcess-less HTTP/1.1 client connection.
This module provides a data structure that represents an HTTP/1 or HTTP/1.1 connection to
a given server. The connection is represented as an opaque struct %Mint.HTTP1{}.
The connection is a data structure and is not backed by a process, and all the
connection handling happens in the process that creates the struct.
This module and data structure work exactly like the ones described in the Mint
module, with the exception that Mint.HTTP1 specifically deals with HTTP/1 and HTTP/1.1 while
Mint deals seamlessly with HTTP/1, HTTP/1.1, and HTTP/2. For more information on
how to use the data structure and client architecture, see Mint.
Summary
Functions
Same as Mint.HTTP.connect/4, but forces an HTTP/1 or HTTP/1.1 connection.
Types
@type error_reason() :: term()
An HTTP/1-specific error reason.
The values can be:
:closed- when you try to make a request or stream a body chunk but the connection is closed.:request_body_is_streaming- when you callrequest/5to send a new request but another request is already streaming.{:unexpected_data, data}- when unexpected data is received from the server.:invalid_status_line- when the HTTP/1 status line is invalid.{:invalid_request_target, target}- when the request target is invalid.:invalid_header- when headers can't be parsed correctly.{:invalid_header_name, name}- when a header name is invalid.{:invalid_header_value, name, value}- when a header value is invalid.nameis the name of the header andvalueis the invalid value.:invalid_chunk_size- when the chunk size is invalid.:missing_crlf_after_chunk- when the CRLF after a chunk is missing.:invalid_trailer_header- when trailer headers can't be parsed.:more_than_one_content_length_header- when more than onecontent-lengthheaders are in the response.:transfer_encoding_and_content_length- when both thecontent-lengthas well as thetransfer-encodingheaders are in the response.{:invalid_content_length_header, value}- when the value of thecontent-lengthheader is invalid, that is, is not an non-negative integer.:empty_token_list- when a header that is supposed to contain a list of tokens (such as theconnectionheader) doesn't contain any.{:invalid_token_list, string}- when a header that is supposed to contain a list of tokens (such as theconnectionheader) contains a malformed list of tokens.:trailing_headers_but_not_chunked_encoding- when you try to send trailer headers throughstream_request_body/3but the transfer encoding of the request was notchunked.
@opaque t()
A Mint HTTP/1 connection struct.
The struct's fields are private.
Functions
See Mint.HTTP.close/1.
@spec connect( Mint.Types.scheme(), Mint.Types.address(), :inet.port_number(), keyword() ) :: {:ok, t()} | {:error, Mint.Types.error()}
Same as Mint.HTTP.connect/4, but forces an HTTP/1 or HTTP/1.1 connection.
This function doesn't support proxying.
Additional Options
:case_sensitive_headers- (boolean) if set totruethe case of the supplied headers in requests will be preserved. The default is to lowercase the headers because HTTP/1.1 header names are case-insensitive. Available since v1.6.0.:skip_target_validation- (boolean) if set totruethe target of a request will not be validated. You might want this if you deal with non standard- conforming URIs but need to preserve them. The default is to validate the request target. Available since v1.7.0.:optional_responses- (list of atoms) a list of optional responses to return. Defaults to[]. The allowed values in the list are::status_reason: includes the reason-phrase for the status code if it is returned by the server in the status-line. This is only available for HTTP/1.1 connections. Available since v1.8.0.
@spec controlling_process(t(), pid()) :: {:ok, t()} | {:error, Mint.Types.error()}
@spec get_proxy_headers(t()) :: Mint.Types.headers()
@spec get_socket(t()) :: Mint.Types.socket()
See Mint.HTTP.open?/1.
@spec open_request_count(t()) :: non_neg_integer()
See Mint.HTTP.open_request_count/1.
In HTTP/1, the number of open requests is the number of pipelined requests.
See Mint.HTTP.put_log/2.
@spec recv(t(), non_neg_integer(), timeout()) :: {:ok, t(), [Mint.Types.response()]} | {:error, t(), Mint.Types.error(), [Mint.Types.response()]}
See Mint.HTTP.recv/3.
@spec request( t(), method :: String.t(), path :: String.t(), Mint.Types.headers(), body :: iodata() | nil | :stream ) :: {:ok, t(), Mint.Types.request_ref()} | {:error, t(), Mint.Types.error()}
See Mint.HTTP.request/5.
In HTTP/1 and HTTP/1.1, you can't open a new request if you're streaming the body of another request. If you try, an error will be returned.
@spec set_mode(t(), :active | :passive) :: {:ok, t()} | {:error, Mint.Types.error()}
See Mint.HTTP.set_mode/2.
@spec stream(t(), term()) :: {:ok, t(), [Mint.Types.response()]} | {:error, t(), Mint.Types.error(), [Mint.Types.response()]} | :unknown
See Mint.HTTP.stream/2.
@spec stream_request_body( t(), Mint.Types.request_ref(), iodata() | :eof | {:eof, trailer_headers :: Mint.Types.headers()} ) :: {:ok, t()} | {:error, t(), Mint.Types.error()}
See Mint.HTTP.stream_request_body/3.
In HTTP/1, sending an empty chunk is a no-op.
Transfer encoding and content length
When streaming the request body, Mint cannot send a precalculated content-length
request header because it doesn't know the body that you'll stream. However, Mint
will transparently handle the presence of a content-length header using this logic:
if you specifically set a
content-lengthheader, then transfer encoding and making sure the content length is correct for what you'll stream is up to you.if you specifically set the transfer encoding (
transfer-encodingheader) tochunked, then it's up to you to properly encode chunks.if you don't set the transfer encoding to
chunkedand don't provide acontent-lengthheader, Mint will do implicitchunkedtransfer encoding (setting thetransfer-encodingheader appropriately) and will take care of properly encoding the chunks.