maxwell v2.3.0 Maxwell.Conn

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

Functions

Get a private value

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 all request headers as a map

Return the response body.

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

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

Get all response headers as a map.

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

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

Set an adapter option for the request.

Set adapter options for the request.

Set the path of the request.

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

Add query string to conn.query_string.

Set a query string value for the request.

Set the request body.

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

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

Link to this section Types

Link to this type

file_body_t()

file_body_t() :: {:file, Path.t()}
Link to this type

t()

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

Link to this function

get_private(conn, key)

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

Get a private value

Examples

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

get_req_header(conn, key)

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"
Link to this function

get_req_headers(conn)

Get all request headers as a map

Examples

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

get_resp_body(conn)

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"
Link to this function

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"
Link to this function

get_resp_header(conn, key)

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"
Link to this function

get_resp_headers(conn)

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"}
Link to this function

get_status(conn)

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
Link to this function

new()

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"}}
Link to this function

new(url)

new(binary()) :: t()
Link to this function

put_option(conn, key, value)

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]}
Link to this function

put_options(conn, extra_opts)

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]}
Link to this function

put_path(conn, path)

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

Set the path of the request.

Examples

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

put_private(conn, key, value)

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"}}
Link to this function

put_query_string(conn, query)

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"})
Link to this function

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"}}
Link to this function

put_req_body(conn, req_body)

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"}
Link to this function

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"}
Link to this function

put_req_headers(conn, extra_headers)

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"}}