Update DOC

lpgauth · Mar 20, 2017 · 1d82ae3 · 1d82ae3
1 parent d3c1a8f
commit 1d82ae3
Show file tree

Hide file tree

Showing 10 changed files with 202 additions and 87 deletions.
diff --git a/README.md b/README.md
@@ -5,12 +5,136 @@ High Performance Erlang HTTP 1.1 Client
 [![Build Status](https://travis-ci.org/lpgauth/buoy.svg?branch=dev)](https://travis-ci.org/lpgauth/buoy.svg?branch=dev)
 [![Coverage Status](https://coveralls.io/repos/github/lpgauth/buoy/badge.svg?branch=dev)](https://coveralls.io/github/lpgauth/buoy?branch=dev)
 
+## Disclaimer:
+This HTTP client has been designed for HTTP 1.1 with keep-alive. For performance reasons, it only implements a subset of RFC2616.
+
 ### Unsupported Features:
 
-- Designed for HTTP 1.1 with Keep-alive
+- Doesn't accept an arbitrary number of new lines in headers
+- Doesn't accept random capitalization of content-length header
+- Doesn't protect against malicious servers
 - Doesn't support chunked encoding
-- Doesn't protect against malicious HTTP servers
 
-### TODOs:
+## API
+<a href="http://github.com/lpgauth/buoy/blob/master/doc/buoy#index" class="module">Function Index</a>
+
+## Examples
+
+```erlang
+1> buoy_app:start().
+{ok,[granderl,shackle,buoy]}
+
+2> Url = buoy_utils:parse_url(<<"http://example.com">>).
+{buoy_url,<<"example.com">>,<<"example.com">>,<<"/">>,80,
+          http}
+
+3> ok = buoy_pool:start(Url, [{pool_size, 1}]).
+ok
+
+4> {ok, Resp} = buoy:get(Url).
+{ok,{buoy_resp,done,
+               <<"<!doctype html>\n<html>\n<head>\n    <title>Example Domain</title>\n\n    <meta charset=\"utf-8\" />\n  "...>>,
+               1270,
+               [<<"Cache-Control: max-age=604800">>,
+                <<"Content-Type: text/html">>,
+                <<"Date: Mon, 20 Mar 2017 14:48:25 GMT">>,
+                <<"Etag: \"359670651+gzip+ident\"">>,
+                <<"Expires: Mon, 27 Mar 2017 14:48:25 GMT">>,
+                <<"Last-Modified: Fri, 09 Aug 2013 23:54:35 GMT">>,
+                <<"Server: ECS (cpm/F9D5)">>,<<"Vary: Accept-Encoding">>,
+                <<"X-Cache: HIT">>,<<"Content-Length: 1270">>],
+               <<"OK">>,200}}
+
+5> {ok, Headers} = buoy_protocol:headers(Resp).
+{ok,[{<<"Cache-Control">>,<<"max-age=604800">>},
+     {<<"Content-Type">>,<<"text/html">>},
+     {<<"Date">>,<<"Mon, 20 Mar 2017 14:48:25 GMT">>},
+     {<<"Etag">>,<<"\"359670651+gzip+ident\"">>},
+     {<<"Expires">>,<<"Mon, 27 Mar 2017 14:48:25 GMT">>},
+     {<<"Last-Modified">>,<<"Fri, 09 Aug 2013 23:54:35 GMT">>},
+     {<<"Server">>,<<"ECS (cpm/F9D5)">>},
+     {<<"Vary">>,<<"Accept-Encoding">>},
+     {<<"X-Cache">>,<<"HIT">>},
+     {<<"Content-Length">>,<<"1270">>}]}
+```
+
+### Pool Options
+
+<table width="100%">
+  <theader>
+    <th>Name</th>
+    <th>Type</th>
+    <th>Default</th>
+    <th>Description</th>
+  </theader>
+  <tr>
+    <td>backlog_size</td>
+    <td>pos_integer()</td>
+    <td>1024</td>
+    <td>maximum number of concurrent requests per connection</td>
+  </tr>
+  <tr>
+    <td>pool_size</td>
+    <td>pos_integer()</td>
+    <td>16</td>
+    <td>number of connections</td>
+  </tr>
+  <tr>
+    <td>pool_strategy</td>
+    <td>random | round_robin</td>
+    <td>random</td>
+    <td>connection selection strategy</td>
+  </tr>
+  <tr>
+    <td>reconnect</td>
+    <td>boolean()</td>
+    <td>true</td>
+    <td>reconnect closed connections</td>
+  </tr>
+  <tr>
+    <td>reconnect_time_max</td>
+    <td>pos_integer() | infinity</td>
+    <td>120000</td>
+    <td>reconnect maximum time</td>
+  </tr>
+  <tr>
+    <td>reconnect_time_min</td>
+    <td>pos_integer()</td>
+    <td>500</td>
+    <td>reconnect minimum time</td>
+  </tr>
+</table>
+
+## Tests
+
+```makefile
+make dialyzer
+make elvis
+make eunit
+make xref
+```
+
+## License
+```license
+The MIT License (MIT)
+
+Copyright (c) 2016-2017 Louis-Philippe Gauthier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
 
-- Proper handling of decoding errors
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
diff --git a/doc/buoy.md b/doc/buoy.md
@@ -36,7 +36,7 @@ body() = undefined | iodata()
 
 
 <pre><code>
-buoy_resp() = #buoy_resp{state = body | done, status_code = undefined | 100..505, reason = undefined | binary(), headers = undefined | [binary()], content_length = undefined | non_neg_integer(), body = undefined | binary()}
+buoy_resp() = #buoy_resp{state = body | done, body = undefined | binary(), content_length = undefined | non_neg_integer(), headers = undefined | [binary()], reason = undefined | binary(), status_code = undefined | 100..505}
 </code></pre>
 
 
@@ -46,7 +46,7 @@ buoy_resp() = #buoy_resp{state = body | done, status_code = undefined | 100..505
 
 
 <pre><code>
-buoy_url() = #buoy_url{scheme = <a href="#type-scheme">scheme()</a>, host = <a href="#type-host">host()</a>, hostname = <a href="#type-hostname">hostname()</a>, port = <a href="inet.md#type-port_number">inet:port_number()</a>, path = <a href="#type-path">path()</a>}
+buoy_url() = #buoy_url{host = <a href="#type-host">host()</a>, hostname = <a href="#type-hostname">hostname()</a>, path = <a href="#type-path">path()</a>, port = <a href="inet.md#type-port_number">inet:port_number()</a>, protocol = <a href="#type-protocol_http">protocol_http()</a>}
 </code></pre>
 
 
@@ -56,7 +56,7 @@ buoy_url() = #buoy_url{scheme = <a href="#type-scheme">scheme()</a>, host = <a h
 
 
 <pre><code>
-client_option() = {ip, <a href="inet.md#type-ip_address">inet:ip_address()</a> | <a href="inet.md#type-hostname">inet:hostname()</a>} | {port, <a href="inet.md#type-port_number">inet:port_number()</a>} | {protocol, <a href="#type-protocol">protocol()</a>} | {reconnect, boolean()} | {reconnect_time_max, <a href="#type-time">time()</a>} | {reconnect_time_min, <a href="#type-time">time()</a>} | {socket_options, [<a href="gen_tcp.md#type-connect_option">gen_tcp:connect_option()</a> | <a href="gen_udp.md#type-option">gen_udp:option()</a>]}
+client_option() = {ip, <a href="inet.md#type-ip_address">inet:ip_address()</a> | <a href="inet.md#type-hostname">inet:hostname()</a>} | {port, <a href="inet.md#type-port_number">inet:port_number()</a>} | {protocol, <a href="#type-protocol">protocol()</a>} | {reconnect, boolean()} | {reconnect_time_max, <a href="#type-time">time()</a> | infinity} | {reconnect_time_min, <a href="#type-time">time()</a>} | {socket_options, [<a href="gen_tcp.md#type-connect_option">gen_tcp:connect_option()</a> | <a href="gen_udp.md#type-option">gen_udp:option()</a>]}
 </code></pre>
 
 
@@ -176,27 +176,27 @@ pool_strategy() = random | round_robin
 
 
 <pre><code>
-protocol() = shackle_tcp | shackle_udp
+protocol() = shackle_ssl | shackle_tcp | shackle_udp
 </code></pre>
 
 
 
 
-### <a name="type-request_id">request_id()</a> ###
+### <a name="type-protocol_http">protocol_http()</a> ###
 
 
 <pre><code>
-request_id() = {<a href="#type-server_name">server_name()</a>, reference()}
+protocol_http() = http | https
 </code></pre>
 
 
 
 
-### <a name="type-scheme">scheme()</a> ###
+### <a name="type-request_id">request_id()</a> ###
 
 
 <pre><code>
-scheme() = http | https
+request_id() = {<a href="#type-server_name">server_name()</a>, reference()}
 </code></pre>
 
 
@@ -224,7 +224,7 @@ time() = pos_integer()
 ## Function Index ##
 
 
-<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#async_get-1">async_get/1</a></td><td></td></tr><tr><td valign="top"><a href="#async_get-2">async_get/2</a></td><td></td></tr><tr><td valign="top"><a href="#async_get-3">async_get/3</a></td><td></td></tr><tr><td valign="top"><a href="#async_post-1">async_post/1</a></td><td></td></tr><tr><td valign="top"><a href="#async_post-2">async_post/2</a></td><td></td></tr><tr><td valign="top"><a href="#async_post-3">async_post/3</a></td><td></td></tr><tr><td valign="top"><a href="#async_post-4">async_post/4</a></td><td></td></tr><tr><td valign="top"><a href="#async_request-5">async_request/5</a></td><td></td></tr><tr><td valign="top"><a href="#get-1">get/1</a></td><td></td></tr><tr><td valign="top"><a href="#get-2">get/2</a></td><td></td></tr><tr><td valign="top"><a href="#get-3">get/3</a></td><td></td></tr><tr><td valign="top"><a href="#post-1">post/1</a></td><td></td></tr><tr><td valign="top"><a href="#post-2">post/2</a></td><td></td></tr><tr><td valign="top"><a href="#post-3">post/3</a></td><td></td></tr><tr><td valign="top"><a href="#post-4">post/4</a></td><td></td></tr><tr><td valign="top"><a href="#receive_response-1">receive_response/1</a></td><td></td></tr><tr><td valign="top"><a href="#receive_response-2">receive_response/2</a></td><td></td></tr><tr><td valign="top"><a href="#request-5">request/5</a></td><td></td></tr></table>
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#async_get-1">async_get/1</a></td><td></td></tr><tr><td valign="top"><a href="#async_get-2">async_get/2</a></td><td></td></tr><tr><td valign="top"><a href="#async_get-3">async_get/3</a></td><td></td></tr><tr><td valign="top"><a href="#async_post-1">async_post/1</a></td><td></td></tr><tr><td valign="top"><a href="#async_post-2">async_post/2</a></td><td></td></tr><tr><td valign="top"><a href="#async_post-3">async_post/3</a></td><td></td></tr><tr><td valign="top"><a href="#async_post-4">async_post/4</a></td><td></td></tr><tr><td valign="top"><a href="#async_request-6">async_request/6</a></td><td></td></tr><tr><td valign="top"><a href="#get-1">get/1</a></td><td></td></tr><tr><td valign="top"><a href="#get-2">get/2</a></td><td></td></tr><tr><td valign="top"><a href="#get-3">get/3</a></td><td></td></tr><tr><td valign="top"><a href="#post-1">post/1</a></td><td></td></tr><tr><td valign="top"><a href="#post-2">post/2</a></td><td></td></tr><tr><td valign="top"><a href="#post-3">post/3</a></td><td></td></tr><tr><td valign="top"><a href="#post-4">post/4</a></td><td></td></tr><tr><td valign="top"><a href="#receive_response-1">receive_response/1</a></td><td></td></tr><tr><td valign="top"><a href="#request-5">request/5</a></td><td></td></tr></table>
 
 
 <a name="functions"></a>
@@ -236,7 +236,7 @@ time() = pos_integer()
 ### async_get/1 ###
 
 <pre><code>
-async_get(Url::<a href="#type-buoy_url">buoy_url()</a>) -&gt; {ok, <a href="/Users/lpgauth/Git/buoy/_build/default/lib/shackle/doc/shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
+async_get(Url::<a href="#type-buoy_url">buoy_url()</a>) -&gt; {ok, <a href="shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
 </code></pre>
 <br />
 
@@ -245,7 +245,7 @@ async_get(Url::<a href="#type-buoy_url">buoy_url()</a>) -&gt; {ok, <a href="/Use
 ### async_get/2 ###
 
 <pre><code>
-async_get(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>) -&gt; {ok, <a href="/Users/lpgauth/Git/buoy/_build/default/lib/shackle/doc/shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
+async_get(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>) -&gt; {ok, <a href="shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
 </code></pre>
 <br />
 
@@ -254,7 +254,7 @@ async_get(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-
 ### async_get/3 ###
 
 <pre><code>
-async_get(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>, Pid::pid()) -&gt; {ok, <a href="/Users/lpgauth/Git/buoy/_build/default/lib/shackle/doc/shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
+async_get(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>, Pid::pid()) -&gt; {ok, <a href="shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
 </code></pre>
 <br />
 
@@ -263,7 +263,7 @@ async_get(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-
 ### async_post/1 ###
 
 <pre><code>
-async_post(Url::<a href="#type-buoy_url">buoy_url()</a>) -&gt; {ok, <a href="/Users/lpgauth/Git/buoy/_build/default/lib/shackle/doc/shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
+async_post(Url::<a href="#type-buoy_url">buoy_url()</a>) -&gt; {ok, <a href="shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
 </code></pre>
 <br />
 
@@ -272,7 +272,7 @@ async_post(Url::<a href="#type-buoy_url">buoy_url()</a>) -&gt; {ok, <a href="/Us
 ### async_post/2 ###
 
 <pre><code>
-async_post(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>) -&gt; {ok, <a href="/Users/lpgauth/Git/buoy/_build/default/lib/shackle/doc/shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
+async_post(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>) -&gt; {ok, <a href="shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
 </code></pre>
 <br />
 
@@ -281,7 +281,7 @@ async_post(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type
 ### async_post/3 ###
 
 <pre><code>
-async_post(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>, Body::<a href="#type-body">body()</a>) -&gt; {ok, <a href="/Users/lpgauth/Git/buoy/_build/default/lib/shackle/doc/shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
+async_post(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>, Body::<a href="#type-body">body()</a>) -&gt; {ok, <a href="shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
 </code></pre>
 <br />
 
@@ -290,16 +290,16 @@ async_post(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type
 ### async_post/4 ###
 
 <pre><code>
-async_post(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>, Body::<a href="#type-body">body()</a>, Pid::pid()) -&gt; {ok, <a href="/Users/lpgauth/Git/buoy/_build/default/lib/shackle/doc/shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
+async_post(Url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>, Body::<a href="#type-body">body()</a>, Pid::pid()) -&gt; {ok, <a href="shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
 </code></pre>
 <br />
 
-<a name="async_request-5"></a>
+<a name="async_request-6"></a>
 
-### async_request/5 ###
+### async_request/6 ###
 
 <pre><code>
-async_request(Method::<a href="#type-method">method()</a>, Buoy_url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>, Body::<a href="#type-body">body()</a>, Pid::pid()) -&gt; {ok, <a href="/Users/lpgauth/Git/buoy/_build/default/lib/shackle/doc/shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
+async_request(Method::<a href="#type-method">method()</a>, Buoy_url::<a href="#type-buoy_url">buoy_url()</a>, Headers::<a href="#type-headers">headers()</a>, Body::<a href="#type-body">body()</a>, Pid::pid(), Timeout::timeout()) -&gt; {ok, <a href="shackle.md#type-request_id">shackle:request_id()</a>} | <a href="#type-error">error()</a>
 </code></pre>
 <br />
 
@@ -375,15 +375,6 @@ receive_response(RequestId::<a href="#type-request_id">request_id()</a>) -&gt; {
 </code></pre>
 <br />
 
-<a name="receive_response-2"></a>
-
-### receive_response/2 ###
-
-<pre><code>
-receive_response(RequestId::<a href="#type-request_id">request_id()</a>, Timeout::pos_integer()) -&gt; {ok, term()} | <a href="#type-error">error()</a>
-</code></pre>
-<br />
-
 <a name="request-5"></a>
 
 ### request/5 ###

diff --git a/doc/buoy_app.md b/doc/buoy_app.md
@@ -28,7 +28,7 @@ backlog_size() = pos_integer() | infinity
 
 
 <pre><code>
-buoy_resp() = #buoy_resp{state = body | done, status_code = undefined | 100..505, reason = undefined | binary(), headers = undefined | [binary()], content_length = undefined | non_neg_integer(), body = undefined | binary()}
+buoy_resp() = #buoy_resp{state = body | done, body = undefined | binary(), content_length = undefined | non_neg_integer(), headers = undefined | [binary()], reason = undefined | binary(), status_code = undefined | 100..505}
 </code></pre>
 
 
@@ -38,7 +38,7 @@ buoy_resp() = #buoy_resp{state = body | done, status_code = undefined | 100..505
 
 
 <pre><code>
-buoy_url() = #buoy_url{scheme = <a href="#type-scheme">scheme()</a>, host = <a href="#type-host">host()</a>, hostname = <a href="#type-hostname">hostname()</a>, port = <a href="inet.md#type-port_number">inet:port_number()</a>, path = <a href="#type-path">path()</a>}
+buoy_url() = #buoy_url{host = <a href="#type-host">host()</a>, hostname = <a href="#type-hostname">hostname()</a>, path = <a href="#type-path">path()</a>, port = <a href="inet.md#type-port_number">inet:port_number()</a>, protocol = <a href="#type-protocol_http">protocol_http()</a>}
 </code></pre>
 
 
@@ -48,7 +48,7 @@ buoy_url() = #buoy_url{scheme = <a href="#type-scheme">scheme()</a>, host = <a h
 
 
 <pre><code>
-client_option() = {ip, <a href="inet.md#type-ip_address">inet:ip_address()</a> | <a href="inet.md#type-hostname">inet:hostname()</a>} | {port, <a href="inet.md#type-port_number">inet:port_number()</a>} | {protocol, <a href="#type-protocol">protocol()</a>} | {reconnect, boolean()} | {reconnect_time_max, <a href="#type-time">time()</a>} | {reconnect_time_min, <a href="#type-time">time()</a>} | {socket_options, [<a href="gen_tcp.md#type-connect_option">gen_tcp:connect_option()</a> | <a href="gen_udp.md#type-option">gen_udp:option()</a>]}
+client_option() = {ip, <a href="inet.md#type-ip_address">inet:ip_address()</a> | <a href="inet.md#type-hostname">inet:hostname()</a>} | {port, <a href="inet.md#type-port_number">inet:port_number()</a>} | {protocol, <a href="#type-protocol">protocol()</a>} | {reconnect, boolean()} | {reconnect_time_max, <a href="#type-time">time()</a> | infinity} | {reconnect_time_min, <a href="#type-time">time()</a>} | {socket_options, [<a href="gen_tcp.md#type-connect_option">gen_tcp:connect_option()</a> | <a href="gen_udp.md#type-option">gen_udp:option()</a>]}
 </code></pre>
 
 
@@ -138,17 +138,17 @@ pool_strategy() = random | round_robin
 
 
 <pre><code>
-protocol() = shackle_tcp | shackle_udp
+protocol() = shackle_ssl | shackle_tcp | shackle_udp
 </code></pre>
 
 
 
 
-### <a name="type-scheme">scheme()</a> ###
+### <a name="type-protocol_http">protocol_http()</a> ###
 
 
 <pre><code>
-scheme() = http | https
+protocol_http() = http | https
 </code></pre>