mojito v0.7.0 Mojito View Source

Mojito is an easy-to-use, high-performance HTTP client built using the low-level Mint library.

Mojito is built for comfort and for speed. Behind a simple and predictable interface, there is a sophisticated connection pool manager that delivers maximum throughput with no intervention from the user.

Just want to make one request and bail? No problem. Mojito can make one-off requests as well, using the same process-less architecture as Mint.

Quickstart

{:ok, response} = Mojito.request(method: :get, url: "https://github.com")

Why Mojito?

Mojito addresses the following design goals:

  • Little or no configuration needed. Use Mojito to make requests to as many different destinations as you like, without thinking about starting or selecting connection pools. Other clients like Hackney (and HTTPoison), Ibrowse (and HTTPotion), and Erlang's built-in httpc offer this feature, except that...

  • Connection pools should be used only for a single destination. Using a pool for making requests against multiple destinations is less than ideal, as many of the connections need to be reset before use. Mojito assigns requests to the correct pools transparently to the user. Other clients, such as Buoy, Hackney/ HTTPoison, Ibrowse/HTTPotion, etc. force the user to handle this themselves, which is often inconvenient if the full set of HTTP destinations is not known at compile time.

  • Redundant pools to reduce concurrency-related bottlenecks. Mojito can serve requests to the same destination from more than one connection pool, and those pools can be selected by round-robin at runtime in order to minimize resource contention in the Erlang VM. This feature is unique to Mojito.

Installation

Add mojito to your deps in mix.exs:

{:mojito, "~> 0.7.0"}

Upgrading from 0.4 and earlier

Upgrading to 0.7 cannot be performed safely inside a hot upgrade. Deploy a regular release instead.

Upgrading from 0.4 to 0.5 requires no end-user code changes.

Mojito 0.5 refactors some internal functions in a way that changes their arity and order of arguments.

Using request methods other than those in the Mojito module is deprecated since 0.3.

A handful of new config parameters appeared in 0.3 as well.

Configuration

The following config.exs config parameters are supported:

  • :timeout (:infinity or milliseconds, default 5000) -- Default request timeout.
  • :transport_opts (t:Keyword.t, default []) -- Options to pass to the :gen_tcp or :ssl modules. Commonly used to make HTTPS requests with self-signed TLS server certificates; see below for details.
  • :pool_opts (t:pool_opts, default []) -- Configuration options for connection pools.

The following :pool_opts options are supported:

  • :size (integer) sets the number of steady-state connections per pool. Default is 5.
  • :max_overflow (integer) sets the number of additional connections per pool, opened under conditions of heavy load. Default is 10.
  • :pools (integer) sets the maximum number of pools to open for a single destination host and port (not the maximum number of total pools to open). Default is 5.
  • :strategy is either :lifo or :fifo, and selects which connection should be checked out of a single pool. Default is :lifo.
  • :destinations (keyword list of t:pool_opts) allows these parameters to be set for individual :"host:port" destinations.

For example:

use Mix.Config

config :mojito,
  timeout: 2500,
  pool_opts: [
    size: 10,
    destinations: [
      "example.com:443": [
        size: 20,
        max_overflow: 20,
        pools: 10
      ]
    ]
  ]

Certain configs can be overridden with each request. See request/1.

Usage

Make requests with Mojito.request/1 or Mojito.request/5:

>>>> Mojito.request(:get, "https://jsonplaceholder.typicode.com/posts/1")
## or...
>>>> Mojito.request(%{method: :get, url: "https://jsonplaceholder.typicode.com/posts/1"})
## or...
>>>> Mojito.request(method: :get, url: "https://jsonplaceholder.typicode.com/posts/1")
{:ok,
 %Mojito.Response{
   body: "{\n  \"userId\": 1,\n  \"id\": 1,\n  \"title\": \"sunt aut facere repellat provident occaecati excepturi optio reprehenderit\",\n  \"body\": \"quia et suscipit\\nsuscipit recusandae consequuntur expedita et cum\\nreprehenderit molestiae ut ut quas totam\\nnostrum rerum est autem sunt rem eveniet architecto\"\n}",
   headers: [
     {"content-type", "application/json; charset=utf-8"},
     {"content-length", "292"},
     {"connection", "keep-alive"},
     ...
   ],
   status_code: 200
 }}

In addition to Mojito.request/5, Mojito also provides convenience functions like Mojito.head/3, Mojito.get/3, Mojito.post/4, Mojito.put/4, Mojito.patch/4, Mojito.delete/3, and Mojito.options/3 for each corresponding HTTP methods.

By default, Mojito will use a connection pool for requests, automatically handling the creation and reuse of pools. If this is not desired, specify the pool: false option with a request to perform a one-off request. See the documentation for request/1 for more details.

Self-signed SSL/TLS certificates

To accept self-signed certificates in HTTPS connections, you can give the transport_opts: [verify: :verify_none] option to Mojito.request or Mojito.Pool.request:

Examples

>>>> Mojito.request(method: :get, url: "https://localhost:8443/")
{:error, {:tls_alert, 'bad certificate'}}

>>>> Mojito.request(method: :get, url: "https://localhost:8443/", opts: [transport_opts: [verify: :verify_none]])
{:ok, %Mojito.Response{...}}

Changelog

See the CHANGELOG.md.

Contributing

Thanks for considering contributing to this project, and to the free software ecosystem at large!

Interested in contributing a bug report? Terrific! Please open a GitHub issue and include as much detail as you can. If you have a solution, even better -- please open a pull request with a clear description and tests.

Have a feature idea? Excellent! Please open a GitHub issue for discussion.

Want to implement an issue that's been discussed? Fantastic! Please open a GitHub pull request and write a clear description of the patch. We'll merge your PR a lot sooner if it is well-documented and fully tested.

Contributors and contributions are listed in the changelog. Heartfelt thanks to everyone who's helped make Mojito better.

Authorship and License

Copyright 2018-2019, Appcues, Inc.

This software is released under the MIT License.

Link to this section Summary

Functions

Performs an HTTP DELETE request and returns the response

Performs an HTTP GET request and returns the response

Performs an HTTP HEAD request and returns the response

Performs an HTTP OPTIONS request and returns the response

Performs an HTTP PATCH request and returns the response

Performs an HTTP POST request and returns the response

Performs an HTTP PUT request and returns the response

Performs an HTTP request and returns the response

Performs an HTTP request and returns the response

Link to this section Types

Link to this type

error() View Source
error() :: %Mojito.Error{message: String.t() | nil, reason: any()}

Link to this type

headers() View Source
headers() :: [header()]

Link to this type

method() View Source
method() ::
  :head | :get | :post | :put | :patch | :delete | :options | String.t()

Link to this type

pool_opt() View Source
pool_opt() ::
  {:size, pos_integer()}
  | {:max_overflow, non_neg_integer()}
  | {:pools, pos_integer()}
  | {:strategy, :lifo | :fifo}

Link to this type

pool_opts() View Source
pool_opts() :: [pool_opt() | {:destinations, [{atom(), pool_opts()}]}]

Link to this type

request() View Source
request() :: %Mojito.Request{
  body: String.t() | nil,
  headers: headers() | nil,
  method: method(),
  opts: Keyword.t() | nil,
  url: String.t()
}

Link to this type

request_field() View Source
request_field() ::
  {:method, method()}
  | {:url, String.t()}
  | {:headers, headers()}
  | {:body, String.t()}
  | {:opts, Keyword.t()}

Link to this type

request_kwlist() View Source
request_kwlist() :: [request_field()]

Link to this type

response() View Source
response() :: %Mojito.Response{
  body: String.t(),
  complete: boolean(),
  headers: headers(),
  size: term(),
  status_code: pos_integer()
}

Link to this section Functions

Link to this function

delete(url, headers \\ [], opts \\ []) View Source
delete(String.t(), headers(), Keyword.t()) ::
  {:ok, response()} | {:error, error()} | no_return()

Performs an HTTP DELETE request and returns the response.

See request/1 for documentation and examples.

Link to this function

get(url, headers \\ [], opts \\ []) View Source
get(String.t(), headers(), Keyword.t()) ::
  {:ok, response()} | {:error, error()} | no_return()

Performs an HTTP GET request and returns the response.

Examples

Assemble a URL with a query string params and fetch it with GET request:

>>>> "https://www.google.com/search"
...> |> URI.parse()
...> |> Map.put(:query, URI.encode_query(%{"q" => "mojito elixir"}))
...> |> URI.to_string()
...> |> Mojito.get()
{:ok,
 %Mojito.Response{
   body: "<!doctype html><html lang=\"en\"><head><meta charset=\"UTF-8\"> ...",
   complete: true,
   headers: [
     {"content-type", "text/html; charset=ISO-8859-1"},
     ...
   ],
   status_code: 200
 }}

See request/1 for detailed documentation.

Link to this function

head(url, headers \\ [], opts \\ []) View Source
head(String.t(), headers(), Keyword.t()) ::
  {:ok, response()} | {:error, error()} | no_return()

Performs an HTTP HEAD request and returns the response.

See request/1 for documentation.

Link to this function

options(url, headers \\ [], opts \\ []) View Source
options(String.t(), headers(), Keyword.t()) ::
  {:ok, response()} | {:error, error()} | no_return()

Performs an HTTP OPTIONS request and returns the response.

See request/1 for documentation.

Link to this function

patch(url, headers \\ [], payload \\ "", opts \\ []) View Source
patch(String.t(), headers(), String.t(), Keyword.t()) ::
  {:ok, response()} | {:error, error()} | no_return()

Performs an HTTP PATCH request and returns the response.

See request/1 and post/4 for documentation and examples.

Link to this function

post(url, headers \\ [], payload \\ "", opts \\ []) View Source
post(String.t(), headers(), String.t(), Keyword.t()) ::
  {:ok, response()} | {:error, error()} | no_return()

Performs an HTTP POST request and returns the response.

Examples

Submitting a form with POST request:

>>>> Mojito.post(
...>   "http://localhost:4000/messages",
...>   [{"content-type", "application/x-www-form-urlencoded"}],
...>   URI.encode_query(%{"message[subject]" => "Contact request", "message[content]" => "data"}))
{:ok,
 %Mojito.Response{
   body: "Thank you!",
   complete: true,
   headers: [
     {"server", "Cowboy"},
     {"connection", "keep-alive"},
     ...
   ],
   status_code: 200
 }}

Submitting a JSON payload as POST request body:

>>>> Mojito.post(
...>   "http://localhost:4000/api/messages",
...>   [{"content-type", "application/json"}],
...>   Jason.encode!(%{"message" => %{"subject" => "Contact request", "content" => "data"}}))
{:ok,
 %Mojito.Response{
   body: "{\"message\": \"Thank you!\"}",
   complete: true,
   headers: [
     {"server", "Cowboy"},
     {"connection", "keep-alive"},
     ...
   ],
   status_code: 200
 }}

See request/1 for detailed documentation.

Link to this function

put(url, headers \\ [], payload \\ "", opts \\ []) View Source
put(String.t(), headers(), String.t(), Keyword.t()) ::
  {:ok, response()} | {:error, error()} | no_return()

Performs an HTTP PUT request and returns the response.

See request/1 and post/4 for documentation and examples.

Link to this function

request(request) View Source
request(request() | request_kwlist()) :: {:ok, response()} | {:error, error()}

Performs an HTTP request and returns the response.

If the pool: true option is given, or :pool is not specified, the request will be made using Mojito's automatic connection pooling system. For more details, see Mojito.Pool.request/1. This is the default mode of operation, and is recommended for best performance.

If pool: false is given as an option, the request will be made on a brand new connection. This does not spawn an additional process. Messages of the form {:tcp, _, _} or {:ssl, _, _} will be sent to and handled by the caller. If the caller process expects to receive other :tcp or :ssl messages at the same time, conflicts can occur; in this case, it is recommended to wrap request/1 in Task.async/1, or use one of the pooled request modes.

Options:

  • :pool - See above.
  • :timeout - Response timeout in milliseconds, or :infinity. Defaults to Application.get_env(:mojito, :timeout, 5000).
  • :raw - Set this to true to prevent the decompression of gzip or compress-encoded responses.
  • :transport_opts - Options to be passed to either :gen_tcp or :ssl. Most commonly used to perform insecure HTTPS requests via transport_opts: [verify: :verify_none].
Link to this function

request(method, url, headers \\ [], body \\ "", opts \\ []) View Source
request(method(), String.t(), headers(), String.t(), Keyword.t()) ::
  {:ok, response()} | {:error, error()} | no_return()

Performs an HTTP request and returns the response.

See request/1 for details.