katipo
=====
An HTTP library for Erlang built around libcurl-multi and libevent.
### Status
Beta
[![Build Status][travis_ci_image]][travis_ci]
[![Hex pm](http://img.shields.io/hexpm/v/katipo.svg?style=flat)](https://hex.pm/packages/katipo)
### Usage
```erlang
{ok, _} = application:ensure_all_started(katipo).
Pool = api_server,
{ok, _} = katipo_pool:start(api_server, 2, [{pipelining, true}]).
Url = <<"https://example.com">>.
ReqHeaders = [{<<"User-Agent">>, <<"katipo">>}].
Opts = #{headers => ReqHeaders,
body => <<"0d5cb3c25b0c5678d5297efa448e1938">>,
connecttimeout_ms => 5000,
proxy => <<"http://127.0.0.1:9000">>,
sslverifyhost => false,
sslverifypeer => false},
{ok, #{status := 200,
headers := RespHeaders,
cookiejar := CookieJar,
body := RespBody}} = katipo:post(Pool, Url, Opts).
```
Or passing the entire request as a map
```erlang
{ok, _} = application:ensure_all_started(katipo).
Pool = api_server,
{ok, _} = katipo_pool:start(api_server, 2, [{pipelining, true}]).
ReqHeaders = [{<<"User-Agent">>, <<"katipo">>}].
Req = #{url => <<"https://example.com">>.
method => post,
headers => ReqHeaders,
body => <<"0d5cb3c25b0c5678d5297efa448e1938">>,
connecttimeout_ms => 5000,
proxy => <<"http://127.0.0.1:9000">>,
sslverifyhost => false,
sslverifypeer => false},
{ok, #{status := 200,
headers := RespHeaders,
cookiejar := CookieJar,
body := RespBody}} = katipo:req(Pool, Req).
```
### Why
We wanted a compatible and high-performance HTTP client so took
advantage of the 15+ years of development that has gone into libcurl.
To allow large numbers of simultaneous connections libevent is used
along with the libcurl-multi interface.
### Documentation
#### API
```erlang
-type method() :: get | post | put | head | options.
katipo_pool:start(Name :: atom(), size :: pos_integer(), PoolOptions :: proplist()).
katipo_pool:stop(Name :: atom()).
katipo:req(Pool :: atom(), Req :: map()).
katipo:Method(Pool :: atom(), URL :: binary()).
katipo:Method(Pool :: atom(), URL :: binary(), ReqOptions :: map()).
```
#### Request options
| Option | Type | Default |
|:--------------------|:------------------------------- |:----------------- |
| `headers` | `[{binary(), iodata()}]` | `[]` |
| `cookiejar` | opaque (returned in response) | `[]` |
| `body` | `iodata()` | `<<>>` |
| `connecttimeout_ms` | `pos_integer()` | 30000 |
| `followlocation` | `boolean()` | `false` |
| `ssl_verifyhost` | `boolean()` | `true` |
| `ssl_verifypeer` | `boolean()` | `true` |
| `capath` | `binary()` | `undefined` |
| `cacert` | `binary()` | `undefined` |
| `timeout_ms` | `pos_integer()` | 30000 |
| `maxredirs` | `non_neg_integer()` | 9 |
| `proxy` | `binary()` | `undefined` |
#### Responses
```erlang
{ok, #{status => pos_integer(),
headers => headers(),
cookiejar => cookiejar(),
body => body()}}
{error, #{code => atom(), message => binary()}}
```
#### Pool Options
| Option | Type | Default | Note |
|:----------------------|:---------------------|:----------------- |----------------------------------------|
| `pipelining` | `boolean()` | `false` | HTTP pipelining |
| `max_pipeline_length` | `non_neg_integer()` | 100 | |
#### Metrics
* ok
* error
* total_time
* curl_time
* namelookup_time
* connect_time
* appconnect_time
* pretransfer_time
* starttransfer_time
### Dependencies
#### Ubuntu Trusty
```sh
sudo apt-get install git libwxgtk2.8-0 libwxbase2.8-0 libevent-dev libcurl4-openssl-dev libcurl4-openssl-dev
wget http://packages.erlang-solutions.com/site/esl/esl-erlang/FLAVOUR_1_esl/esl-erlang_18.0-1~ubuntu~trusty_amd64.deb
sudo dpkg -i esl-erlang_18.0-1~ubuntu~trusty_amd64.deb
```
#### OSX
```sh
brew install --with-c-ares --with-nghttp2 curl
brew install libevent
```
### Building
```sh
make
make test
```
[travis_ci]: https://travis-ci.org/puzza007/katipo
[travis_ci_image]: https://travis-ci.org/puzza007/katipo.png