Permalink
Browse files

ease the use in the console and improve doc

- add `hackney:start/0` & `hackney:stop/0` function to use hackney in
  the console
- Make the example easier.
  • Loading branch information...
1 parent 3fe3559 commit 27905da659b9fed36c7f00e4d67b15729444ab76 @benoitc committed Jul 16, 2012
Showing with 15,349 additions and 148 deletions.
  1. +1 −1 NOTICE
  2. +81 −43 README.md
  3. +81 −43 doc/README.md
  4. +4 −3 doc/edoc-info
  5. +16 −2 doc/hackney.md
  6. +8 −1 doc/hackney_app.md
  7. +102 −0 doc/hackney_deps.md
  8. +33 −0 doc/hackney_pool_sup.md
  9. +83 −44 doc/overview.edoc
  10. +14,804 −0 erl_crash.dump
  11. +2 −7 src/hackney.app.src
  12. +12 −1 src/hackney.erl
  13. +7 −3 src/hackney_app.erl
  14. +80 −0 src/hackney_deps.erl
  15. +35 −0 src/hackney_pool_sup.erl
View
2 NOTICE
@@ -6,5 +6,5 @@ hackney
hackney is released under the Apache 2 license. See the LICENSE file for
the complete license.
-Some part of the code from the cowboy project:
+Some part of the code from the cowboy project under ISC license:
Copyright (c) 2011-2012, Loïc Hoguin <essen@ninenines.eu>
View
124 README.md
@@ -17,7 +17,7 @@ Main features:
process and a state is kept in a `#client{}` record.
- Keepalive handling
- basic authentication
-- stream binary bodies
+- stream the response
- Can send files using the sendfile API
- Chunked encoding support
- Used parse transform for shorcut methods calls:
@@ -32,48 +32,84 @@ informations on what still need to be done.
## Examples
-Quick usage example without pool:<pre>application:start(crypto),
-application:start(public_key),
-application:start(ssl),
-
-%% make a simple connection
-{ok, _, _, Client} = hackney:request(<<"https://friendpaste.com">>),
-{ok, Body, Client1} = hackney:body(Client),
-
-io:format("body: ~p~n~n", [Body]),
-
-%% connection is kept alive, launch a new request
-{ok, _, _, Client2} = hackney:send_request(Client1, {get,
- <<"/_all_languages">>,
- [],
- <<>>}),
-{ok, Body1, Client3} = hackney:body(Client2),
-io:format("body: ~p~n~n", [Body1]),
-
-%% do the same but with a post. Create a paste
-ReqBody = << "{
- \"id\": \"some_paste_id\",
- \"rev\": \"some_revision_id\",
- \"changeset\": \"changeset in unidiff format\"
-}" >>,
-
-ReqHeaders = [{<<"Content-Type">>, <<"application/json">>}],
-{ok, _, _, Client4} = hackney:send_request(Client3, {post, <<"/">>,
- ReqHeaders,
- ReqBody}),
-{ok, Body2, Client5} = hackney:body(Client4),
-io:format("body: ~p~n~n", [Body2]),
-
-%% same as above but using a dile
-ReqBody1 = {file, "./examples/test.json"},
-{ok, _, _, Client6} = hackney:send_request(Client5, {post, <<"/">>,
- ReqHeaders,
- ReqBody1}),
-{ok, Body3, Client7} = hackney:body(Client6),
-io:format("body: ~p~n~n", [Body3]),
-
-%% finally close the client (close the socket)
-hackney:close(Client7).</pre>
+Make a simple request without pool:<pre>1> hackney:start().
+ok
+2> {ok, StatusCode, Headers, Client} = hackney:request(<<"https://friendpaste.com">>).
+{ok,200,
+ [{<<"Server">>,<<"nginx/0.7.62">>},
+ {<<"Date">>,<<"Mon, 16 Jul 2012 08:12:39 GMT">>},
+ {<<"Content-Type">>,<<"text/html; charset=utf-8">>},
+ {<<"Transfer-Encoding">>,<<"chunked">>},
+ {<<"Connection">>,<<"keep-alive">>}],
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,on_body,waiting,4096,
+ <<"eee\r\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n "...>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,
+ <<"text/html; charset=utf-8">>}}
+3> {ok, Body, Client1} = hackney:body(Client).
+{ok,<<"<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <meta charset=\"utf-8\"/>\n <title>Friendpaste - Welcome</title>"...>>,
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,
+ <<"text/html; charset=utf-8">>}}
+4> hackney:close(Client1).
+{client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],nil,infinity,closed,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,
+ <<"text/html; charset=utf-8">>}</pre>
+
+Quick usage example with keepalive:<pre>1> hackney:start().
+ok
+2> {ok, _, _, Client} = hackney:request(<<"https://friendpaste.com/_all_languages">>),
+2> {ok, Body, Client1} = hackney:body(Client).
+{ok,<<"[[\"Cucumber\", \"Gherkin\"], [\"abap\", \"ABAP\"], [\"ada\", \"Ada\"], [\"ahk\", \"autohotkey\"], [\"antlr\", \"ANTLR\"], [\"ant"...>>,
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,<<"application/json">>}}
+3>
+3> ReqBody = << "{
+3> \"id\": \"some_paste_id\",
+3> \"rev\": \"some_revision_id\",
+3> \"changeset\": \"changeset in unidiff format\"
+3> }" >>,
+3> ReqHeaders = [{<<"Content-Type">>, <<"application/json">>}],
+3> {ok, _, _, Client2} = hackney:send_request(Client1, {post, <<"/">>, ReqHeaders, ReqBody}).
+{ok,200,
+ [{<<"Server">>,<<"nginx/0.7.62">>},
+ {<<"Date">>,<<"Mon, 16 Jul 2012 08:18:52 GMT">>},
+ {<<"Content-Type">>,<<"application/json">>},
+ {<<"Transfer-Encoding">>,<<"chunked">>},
+ {<<"Connection">>,<<"keep-alive">>}],
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,on_body,waiting,4096,
+ <<"7c\r\n{\"url\": \"https://friendpaste.com/2kF2g0nQpVE"...>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,<<"application/json">>}}
+4> {ok, Body2, Client3} = hackney:body(Client2).
+{ok,<<"{\"url\": \"https://friendpaste.com/2kF2g0nQpVE0GzrKaEubiY\", \"rev\": \"333732656130\", \"ok\": true, \"id\": \"2kF2g0nQ"...>>,
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,<<"application/json">>}}
+5> hackney:close(Client3).
+{client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],nil,infinity,closed,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,<<"application/json">>}</pre>
Contribute
----------
@@ -86,8 +122,10 @@ For issues, comments or feedback please [create an issue!] [1][1]: http://github
<table width="100%" border="0" summary="list of modules">
<tr><td><a href="http://github.com/benoitc/hackney/blob/master/doc/hackney.md" class="module">hackney</a></td></tr>
<tr><td><a href="http://github.com/benoitc/hackney/blob/master/doc/hackney_app.md" class="module">hackney_app</a></td></tr>
+<tr><td><a href="http://github.com/benoitc/hackney/blob/master/doc/hackney_deps.md" class="module">hackney_deps</a></td></tr>
<tr><td><a href="http://github.com/benoitc/hackney/blob/master/doc/hackney_form.md" class="module">hackney_form</a></td></tr>
<tr><td><a href="http://github.com/benoitc/hackney/blob/master/doc/hackney_headers.md" class="module">hackney_headers</a></td></tr>
+<tr><td><a href="http://github.com/benoitc/hackney/blob/master/doc/hackney_pool_sup.md" class="module">hackney_pool_sup</a></td></tr>
<tr><td><a href="http://github.com/benoitc/hackney/blob/master/doc/hackney_request.md" class="module">hackney_request</a></td></tr>
<tr><td><a href="http://github.com/benoitc/hackney/blob/master/doc/hackney_response.md" class="module">hackney_response</a></td></tr>
<tr><td><a href="http://github.com/benoitc/hackney/blob/master/doc/hackney_ssl_transport.md" class="module">hackney_ssl_transport</a></td></tr>
View
@@ -17,7 +17,7 @@ Main features:
process and a state is kept in a `#client{}` record.
- Keepalive handling
- basic authentication
-- stream binary bodies
+- stream the response
- Can send files using the sendfile API
- Chunked encoding support
- Used parse transform for shorcut methods calls:
@@ -32,48 +32,84 @@ informations on what still need to be done.
## Examples
-Quick usage example without pool:<pre>application:start(crypto),
-application:start(public_key),
-application:start(ssl),
-
-%% make a simple connection
-{ok, _, _, Client} = hackney:request(<<"https://friendpaste.com">>),
-{ok, Body, Client1} = hackney:body(Client),
-
-io:format("body: ~p~n~n", [Body]),
-
-%% connection is kept alive, launch a new request
-{ok, _, _, Client2} = hackney:send_request(Client1, {get,
- <<"/_all_languages">>,
- [],
- <<>>}),
-{ok, Body1, Client3} = hackney:body(Client2),
-io:format("body: ~p~n~n", [Body1]),
-
-%% do the same but with a post. Create a paste
-ReqBody = << "{
- \"id\": \"some_paste_id\",
- \"rev\": \"some_revision_id\",
- \"changeset\": \"changeset in unidiff format\"
-}" >>,
-
-ReqHeaders = [{<<"Content-Type">>, <<"application/json">>}],
-{ok, _, _, Client4} = hackney:send_request(Client3, {post, <<"/">>,
- ReqHeaders,
- ReqBody}),
-{ok, Body2, Client5} = hackney:body(Client4),
-io:format("body: ~p~n~n", [Body2]),
-
-%% same as above but using a dile
-ReqBody1 = {file, "./examples/test.json"},
-{ok, _, _, Client6} = hackney:send_request(Client5, {post, <<"/">>,
- ReqHeaders,
- ReqBody1}),
-{ok, Body3, Client7} = hackney:body(Client6),
-io:format("body: ~p~n~n", [Body3]),
-
-%% finally close the client (close the socket)
-hackney:close(Client7).</pre>
+Make a simple request without pool:<pre>1> hackney:start().
+ok
+2> {ok, StatusCode, Headers, Client} = hackney:request(<<"https://friendpaste.com">>).
+{ok,200,
+ [{<<"Server">>,<<"nginx/0.7.62">>},
+ {<<"Date">>,<<"Mon, 16 Jul 2012 08:12:39 GMT">>},
+ {<<"Content-Type">>,<<"text/html; charset=utf-8">>},
+ {<<"Transfer-Encoding">>,<<"chunked">>},
+ {<<"Connection">>,<<"keep-alive">>}],
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,on_body,waiting,4096,
+ <<"eee\r\n<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n "...>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,
+ <<"text/html; charset=utf-8">>}}
+3> {ok, Body, Client1} = hackney:body(Client).
+{ok,<<"<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n <meta charset=\"utf-8\"/>\n <title>Friendpaste - Welcome</title>"...>>,
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,
+ <<"text/html; charset=utf-8">>}}
+4> hackney:close(Client1).
+{client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],nil,infinity,closed,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,
+ <<"text/html; charset=utf-8">>}</pre>
+
+Quick usage example with keepalive:<pre>1> hackney:start().
+ok
+2> {ok, _, _, Client} = hackney:request(<<"https://friendpaste.com/_all_languages">>),
+2> {ok, Body, Client1} = hackney:body(Client).
+{ok,<<"[[\"Cucumber\", \"Gherkin\"], [\"abap\", \"ABAP\"], [\"ada\", \"Ada\"], [\"ahk\", \"autohotkey\"], [\"antlr\", \"ANTLR\"], [\"ant"...>>,
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,<<"application/json">>}}
+3>
+3> ReqBody = << "{
+3> \"id\": \"some_paste_id\",
+3> \"rev\": \"some_revision_id\",
+3> \"changeset\": \"changeset in unidiff format\"
+3> }" >>,
+3> ReqHeaders = [{<<"Content-Type">>, <<"application/json">>}],
+3> {ok, _, _, Client2} = hackney:send_request(Client1, {post, <<"/">>, ReqHeaders, ReqBody}).
+{ok,200,
+ [{<<"Server">>,<<"nginx/0.7.62">>},
+ {<<"Date">>,<<"Mon, 16 Jul 2012 08:18:52 GMT">>},
+ {<<"Content-Type">>,<<"application/json">>},
+ {<<"Transfer-Encoding">>,<<"chunked">>},
+ {<<"Connection">>,<<"keep-alive">>}],
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,on_body,waiting,4096,
+ <<"7c\r\n{\"url\": \"https://friendpaste.com/2kF2g0nQpVE"...>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,<<"application/json">>}}
+4> {ok, Body2, Client3} = hackney:body(Client2).
+{ok,<<"{\"url\": \"https://friendpaste.com/2kF2g0nQpVE0GzrKaEubiY\", \"rev\": \"333732656130\", \"ok\": true, \"id\": \"2kF2g0nQ"...>>,
+ {client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],
+ {sslsocket,new_ssl,<0.52.0>},
+ infinity,connected,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,<<"application/json">>}}
+5> hackney:close(Client3).
+{client,hackney_ssl_transport,"friendpaste.com",443,netloc,
+ [],nil,infinity,closed,done,done,4096,<<>>,
+ {1,1},
+ nil,<<"chunked">>,<<"keep-alive">>,<<"application/json">>}</pre>
Contribute
----------
@@ -86,8 +122,10 @@ For issues, comments or feedback please [create an issue!] [1][1]: http://github
<table width="100%" border="0" summary="list of modules">
<tr><td><a href="hackney.md" class="module">hackney</a></td></tr>
<tr><td><a href="hackney_app.md" class="module">hackney_app</a></td></tr>
+<tr><td><a href="hackney_deps.md" class="module">hackney_deps</a></td></tr>
<tr><td><a href="hackney_form.md" class="module">hackney_form</a></td></tr>
<tr><td><a href="hackney_headers.md" class="module">hackney_headers</a></td></tr>
+<tr><td><a href="hackney_pool_sup.md" class="module">hackney_pool_sup</a></td></tr>
<tr><td><a href="hackney_request.md" class="module">hackney_request</a></td></tr>
<tr><td><a href="hackney_response.md" class="module">hackney_response</a></td></tr>
<tr><td><a href="hackney_ssl_transport.md" class="module">hackney_ssl_transport</a></td></tr>
View
@@ -1,5 +1,6 @@
{application,hackney}.
{packages,[]}.
-{modules,[hackney,hackney_app,hackney_form,hackney_headers,hackney_request,
- hackney_response,hackney_ssl_transport,hackney_sup,
- hackney_tcp_transport,hackney_transform,hackney_url,hackney_util]}.
+{modules,[hackney,hackney_app,hackney_deps,hackney_form,hackney_headers,
+ hackney_pool_sup,hackney_request,hackney_response,
+ hackney_ssl_transport,hackney_sup,hackney_tcp_transport,
+ hackney_transform,hackney_url,hackney_util]}.
View
@@ -11,7 +11,7 @@
<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#body-1">body/1</a></td><td>Return the full body sent with the response.</td></tr><tr><td valign="top"><a href="#body-2">body/2</a></td><td>Return the full body sent with the response as long as the body
-length doesn't go over MaxLength.</td></tr><tr><td valign="top"><a href="#close-1">close/1</a></td><td></td></tr><tr><td valign="top"><a href="#connect-1">connect/1</a></td><td></td></tr><tr><td valign="top"><a href="#connect-3">connect/3</a></td><td></td></tr><tr><td valign="top"><a href="#connect-4">connect/4</a></td><td></td></tr><tr><td valign="top"><a href="#request-1">request/1</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#request-2">request/2</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#request-3">request/3</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#request-4">request/4</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#request-5">request/5</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#send_request-2">send_request/2</a></td><td></td></tr><tr><td valign="top"><a href="#set_sockopts-2">set_sockopts/2</a></td><td></td></tr><tr><td valign="top"><a href="#skip_body-1">skip_body/1</a></td><td>skip the full body.</td></tr><tr><td valign="top"><a href="#stream_body-1">stream_body/1</a></td><td>Stream the response body.</td></tr></table>
+length doesn't go over MaxLength.</td></tr><tr><td valign="top"><a href="#close-1">close/1</a></td><td></td></tr><tr><td valign="top"><a href="#connect-1">connect/1</a></td><td></td></tr><tr><td valign="top"><a href="#connect-3">connect/3</a></td><td></td></tr><tr><td valign="top"><a href="#connect-4">connect/4</a></td><td></td></tr><tr><td valign="top"><a href="#request-1">request/1</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#request-2">request/2</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#request-3">request/3</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#request-4">request/4</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#request-5">request/5</a></td><td>make a request.</td></tr><tr><td valign="top"><a href="#send_request-2">send_request/2</a></td><td></td></tr><tr><td valign="top"><a href="#set_sockopts-2">set_sockopts/2</a></td><td></td></tr><tr><td valign="top"><a href="#skip_body-1">skip_body/1</a></td><td>skip the full body.</td></tr><tr><td valign="top"><a href="#start-0">start/0</a></td><td>Start the couchbeam process.</td></tr><tr><td valign="top"><a href="#stop-0">stop/0</a></td><td>Stop the couchbeam process.</td></tr><tr><td valign="top"><a href="#stream_body-1">stream_body/1</a></td><td>Stream the response body.</td></tr></table>
<a name="functions"></a>
@@ -156,7 +156,21 @@ Args:
<br></br>
-skip the full body. (read all the body if needed).<a name="stream_body-1"></a>
+skip the full body. (read all the body if needed).<a name="start-0"></a>
+
+###start/0##
+
+
+`start() -> any()`
+
+Start the couchbeam process. Useful when testing using the shell.<a name="stop-0"></a>
+
+###stop/0##
+
+
+`stop() -> any()`
+
+Stop the couchbeam process. Useful when testing using the shell.<a name="stream_body-1"></a>
###stream_body/1##
View
@@ -10,13 +10,20 @@ __Behaviours:__ [`application`](application.md).<a name="index"></a>
##Function Index##
-<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#start-2">start/2</a></td><td></td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td></td></tr></table>
+<table width="100%" border="1" cellspacing="0" cellpadding="2" summary="function index"><tr><td valign="top"><a href="#ensure_deps_started-0">ensure_deps_started/0</a></td><td></td></tr><tr><td valign="top"><a href="#start-2">start/2</a></td><td></td></tr><tr><td valign="top"><a href="#stop-1">stop/1</a></td><td></td></tr></table>
<a name="functions"></a>
##Function Details##
+<a name="ensure_deps_started-0"></a>
+
+###ensure_deps_started/0##
+
+
+`ensure_deps_started() -> any()`
+
<a name="start-2"></a>
###start/2##
Oops, something went wrong.

0 comments on commit 27905da

Please sign in to comment.