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

Streams the HTTP response

Streams the request body

Link to this section Types

Link to this type headers() View Source
headers() :: [{String.t(), String.t()}]
Link to this type request_ref() View Source
request_ref() :: reference()
Link to this type response() View Source
response() ::
  {:status, request_ref(), status()}
  | {:headers, request_ref(), headers()}
  | {:data, request_ref(), binary()}
  | {:done, request_ref()}
Link to this type tcp_message() View Source
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

Link to this function connect(hostname, port, opts \\ []) View Source
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.

Link to this function request(conn, method, path, headers, body) View Source
request(
  t(),
  method :: atom() | String.t(),
  path :: String.t(),
  headers(),
  body :: iodata() | :stream
) :: {:ok, t(), request_ref()} | {:error, term()}

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.

Link to this function stream(conn, arg2) View Source
stream(t(), tcp_message()) ::
  {:ok, t(), [response()]} | {:error, t(), term()} | :unknown

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.

Link to this function stream_request_body(conn, body) View Source
stream_request_body(t(), body :: iodata() | :eof) ::
  {:ok, t()} | {:error, term()}

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.