Maxwell.Conn (maxwell v2.4.0) View Source

The Maxwell connection.

This module defines a Maxwell.Conn struct and the main functions for working with Maxwell connections.

Request fields

These fields contain request information:

url - the requested url as a binary, example: "www.example.com:8080/path/?foo=bar".
method - the request method as a atom, example: GET.
req_headers - the request headers as a map, example: %{"content-type" => "text/plain"}.
req_body - the request body, by default is an empty string. It is set to nil after the request is set.

Response fields

These fields contain response information:

status - the response status
resp_headers - the response headers as a map.
resp_body - the response body (todo desc).

Connection fields

state - the connection state

The connection state is used to track the connection lifecycle. It starts as :unsent but is changed to :sending, Its final result is :sent or :error.

Protocols

Maxwell.Conn implements Inspect protocols out of the box. The inspect protocol provides a nice representation of the connection.

Link to this section Summary

Types

file_body_t()

t()

Functions

get_private(conn, key)

Get a private value

get_req_header(conn, key)

Get a request header by key. The key lookup is case-insensitive. Returns the value as a string, or nil if it doesn't exist.

get_req_headers(conn)

Get all request headers as a map

get_resp_body(conn)

Return the response body.

get_resp_body(conn, func)

Return a value from the response body by key or with a parsing function.

get_resp_header(conn, key)

Get a response header by key. The value is returned as a string, or nil if the header is not set.

get_resp_headers(conn)

Get all response headers as a map.

get_status(conn)

Get response status. Raises Maxwell.Conn.NotSentError when the request is unsent.

new()

Create a new connection. The url provided will be parsed by URI.parse/1, and the relevant connection fields will be set accordingly.

new(url)

put_option(conn, key, value)

Set an adapter option for the request.

put_options(conn, extra_opts)

Set adapter options for the request.

put_path(conn, path)

Set the path of the request.

put_private(conn, key, value)

Set a private value. If it already exists, it is updated.

put_query_string(conn, query)

Add query string to conn.query_string.

put_query_string(conn, key, value)

Set a query string value for the request.

put_req_body(conn, req_body)

Set the request body.

put_req_header(conn, key, value)

Set a request header. If it already exists, it is updated.

put_req_headers(conn, extra_headers)

Merge a map of headers into the existing headers of the connection.

Link to this section Types

file_body_t()

Specs

file_body_t() :: {:file, Path.t()}

t()

Specs

t() :: %Maxwell.Conn{
  method: atom(),
  opts: Keyword.t(),
  path: String.t(),
  private: map(),
  query_string: map(),
  req_body:
    iodata() | map() | Maxwell.Multipart.t() | file_body_t() | Enumerable.t(),
  req_headers: %{required(binary()) => binary()},
  resp_body: iodata() | map(),
  resp_headers: %{required(binary()) => binary()},
  state: :unsent | :sending | :sent | :error,
  status: non_neg_integer() | nil,
  url: String.t()
}

Link to this section Functions

get_private(conn, key)

Specs

get_private(t(), atom()) :: term()

Get a private value

Examples

iex> %Maxwell.Conn{private: %{user_id: "zhongwencool"}}
|> get_private(:user_id)
"zhongwencool"

get_req_header(conn, key)

Specs

get_req_header(t(), String.t()) :: String.t() | nil

Get a request header by key. The key lookup is case-insensitive. Returns the value as a string, or nil if it doesn't exist.

Examples

iex> %Maxwell.Conn{req_headers: %{"cookie" => "xyz"} |> get_req_header("cookie")
"xyz"

get_req_headers(conn)

Get all request headers as a map

Examples

iex> %Maxwell.Conn{req_headers: %{"cookie" => "xyz"} |> get_req_header
%{"cookie" => "xyz"}

get_resp_body(conn)

Specs

get_resp_body(t()) :: binary() | map() | no_return()

Return the response body.

Examples

iex> get_resp_body(%Maxwell.Conn{state: :sent, resp_body: "best http client"})
"best http client"

get_resp_body(conn, func)

Return a value from the response body by key or with a parsing function.

Examples

iex> get_resp_body(%Maxwell.Conn{state: :sent, resp_body: %{"name" => "xyz"}}, "name")
"xyz"

iex> func = fn(x) ->
...>   [key, value] = String.split(x, ":")
...>   value
...> end
...> get_resp_body(%Maxwell.Conn{state: :sent, resp_body: "name:xyz"}, func)
"xyz"

get_resp_header(conn, key)

Specs

get_resp_header(t(), String.t()) :: String.t() | nil | no_return()

Get a response header by key. The value is returned as a string, or nil if the header is not set.

Examples

iex> %Maxwell.Conn{resp_headers: %{"cookie" => "xyz"}} |> get_resp_header("cookie")
"xyz"

get_resp_headers(conn)

Specs

get_resp_headers(t()) :: %{required(String.t()) => String.t()} | no_return()

Get all response headers as a map.

Examples

iex> %Maxwell.Conn{resp_headers: %{"cookie" => "xyz"} |> get_resp_header
%{"cookie" => "xyz"}

get_status(conn)

Specs

get_status(t()) :: pos_integer() | no_return()

Get response status. Raises Maxwell.Conn.NotSentError when the request is unsent.

Examples

iex> get_status(%Maxwell.Conn{status: 200})
200

new()

Specs

new() :: t()

Create a new connection. The url provided will be parsed by URI.parse/1, and the relevant connection fields will be set accordingly.

Examples

iex> new()
%Maxwell.Conn{}

iex> new("http://example.com/foo")
%Maxwell.Conn{url: "http://example.com", path: "/foo"}

iex> new("http://example.com/foo?bar=qux")
%Maxwell.Conn{url: "http://example.com", path: "/foo", query_string: %{"bar" => "qux"}}

new(url)

Specs

new(binary()) :: t()

put_option(conn, key, value)

Specs

put_option(t(), atom(), term()) :: t() | no_return()

Set an adapter option for the request.

Examples

iex> put_option(new(), :connect_timeout, 5000)
%Maxwell.Conn{opts: [connect_timeout: 5000]}

put_options(conn, extra_opts)

Specs

put_options(t(), Keyword.t()) :: t() | no_return()

Set adapter options for the request.

Examples

iex> put_options(new(), connect_timeout: 4000)
%Maxwell.Conn{opts: [connect_timeout: 4000]}

put_path(conn, path)

Specs

put_path(t(), String.t()) :: t() | no_return()

Set the path of the request.

Examples

 iex> put_path(new(), "delete")
 %Maxwell.Conn{path: "delete"}

put_private(conn, key, value)

Specs

put_private(t(), atom(), term()) :: t()

Set a private value. If it already exists, it is updated.

Examples

iex> %Maxwell.Conn{private: %{}}
|> put_private(:user_id, "zhongwencool")
%Maxwell.Conn{private: %{user_id: "zhongwencool"}}

put_query_string(conn, query)

Specs

put_query_string(t(), map()) :: t() | no_return()

Add query string to conn.query_string.

conn - %Conn{}
query_map - as map, for example %{foo => bar}

Examples

# %Conn{query_string: %{name: "zhong wen"}}
put_query_string(%Conn{}, %{name: "zhong wen"})

put_query_string(conn, key, value)

Set a query string value for the request.

Examples

  iex> put_query_string(new(), :name, "zhong wen")
  %Maxwell.Conn{query_string: %{:name => "zhong wen"}}

put_req_body(conn, req_body)

Specs

put_req_body(t(), Enumerable.t() | binary()) :: t() | no_return()

Set the request body.

Examples

iex> put_req_body(new(), "new body")
%Maxwell.Conn{req_body: "new_body"}

put_req_header(conn, key, value)

Set a request header. If it already exists, it is updated.

Examples

iex> %Maxwell.Conn{req_headers: %{"content-type" => "text/javascript"}}
|> put_req_header("Content-Type", "application/json")
|> put_req_header("User-Agent", "zhongwencool")
%Maxwell.Conn{req_headers: %{"content-type" => "application/json", "user-agent" => "zhongwenool"}

put_req_headers(conn, extra_headers)

Specs

put_req_headers(t(), map()) :: t() | no_return()

Merge a map of headers into the existing headers of the connection.

Examples

iex> %Maxwell.Conn{headers: %{"content-type" => "text/javascript"}
|> put_req_headers(%{"Accept" => "application/json"})
%Maxwell.Conn{req_headers: %{"accept" => "application/json", "content-type" => "text/javascript"}}