xclient v0.6.0-vendored-xhttp XHTTP1.Conn View Source
Streaming API for HTTP connections.
After a connection is established with connect/3
and a request has been
sent with request/5
, the connection needs to be streamed messages to
stream/2
from :gen_tcp
or :ssl
socket active modes.
If the message is from the socket belonging to the given %Conn{}
then
stream/2
will return parts of the response.
All connection handling happens in the current process.
The stream/2
function is pure because it’s the users responsibility to
receive socket messages and pass them to the function, therefor it’s important
to always store the returned %Conn{}
struct from functions.
Link to this section Summary
Functions
Establishes a connection and returns a %Conn{}
with the connection state
Returns true
if the connection is currently open
Sends an HTTP request
Streams the HTTP response
Streams the request body
Link to this section Types
http_version() :: {non_neg_integer(), non_neg_integer()}
response() :: {:status, request_ref(), status()} | {:headers, request_ref(), headers()} | {:data, request_ref(), binary()} | {:done, request_ref()}
tcp_message() :: {:tcp | :ssl, :gen_tcp.socket(), binary()} | {:tcp_closed | :ssl_closed, :gen_tcp.socket()} | {:tcp_error | :ssl_error, :gen_tcp.socket(), term()}
Link to this section Functions
connect( hostname :: String.t(), port :: :inet.port_number(), opts :: Keyword.t() ) :: {:ok, t()} | {:error, term()}
Establishes a connection and returns a %Conn{}
with the connection state.
The connection will be in active: true
mode.
Returns true
if the connection is currently open.
Should be called between every request to check that server has not closed the connection.
Sends an HTTP request.
Requests can be pipelined so the full response does not have to received before the next request can be sent. It is up to users to verify that the server supports pipelining and that the request is safe to pipeline.
If :stream
is given as body
the request body should be be streamed with
stream_request_body/2
.
Streams the HTTP response.
This functions takes messages received from :gen_tcp
or :ssl
sockets in
active mode and returns the HTTP response in parts:
:status
- This response will always be returned and will be the first response returned for a request.:headers
- Headers will always be returned after the status and before the body, the headers will only be returned when all headers have been received. Trailing headers can optionally be returned after the body and before done.:data
- The body is optional and can be returned in multiple parts.:done
- This is the last response for a request and indicates that the response is done streaming.
If the message does not belong to the connection’s socket :unknown
will
be returned.
If requests are pipelined multiple responses may be returned, use the request
reference request_ref/0
to distinguish them.
Streams the request body.
Requires the body
to be set as :stream
in request/5
. The body will be
sent until :eof
is given.
Users should send the appropriate request headers to indicate the length of the message body.