From e714b99fecb1923cfc4182d2c439fb0bd3943ac6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 17 Sep 2018 15:47:31 +0200 Subject: Document gun:connect/2,3,4 --- doc/src/manual/gun.asciidoc | 61 +++++++++++++++++++ doc/src/manual/gun.connect.asciidoc | 115 ++++++++++++++++++++++++++++++++++++ 2 files changed, 176 insertions(+) create mode 100644 doc/src/manual/gun.connect.asciidoc diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc index 7e1f343..29ca3ea 100644 --- a/doc/src/manual/gun.asciidoc +++ b/doc/src/manual/gun.asciidoc @@ -32,6 +32,10 @@ Requests: * link:man:gun:request(3)[gun:request(3)] - Perform the given request * link:man:gun:data(3)[gun:data(3)] - Stream the body of a request +Proxies: + +* link:man:gun:connect(3)[gun:connect(3)] - Establish a tunnel to the origin server + Messages: * link:man:gun:await(3)[gun:await(3)] - Wait for a response @@ -79,6 +83,59 @@ process. == Types +=== connect_destination() + +[source,erlang] +---- +connect_destination() :: #{ + host := inet:hostname() | inet:ip_address(), + port := inet:port_number(), + + username => iodata(), + password => iodata(), + protocol => http | http2, + transport => tcp | tls, + + tls_opts => [ssl:connect_option()], + tls_handshake_timeout => timeout() +} +---- + +Destination of a CONNECT request. + +The default value, if any, is given next to the option name: + +host, port:: + +Destination hostname and port number. Mandatory. ++ +Upon successful completion of the CONNECT request, Gun will +begin using these as the host and port of the origin server +for subsequent requests. + +username, password:: + +Proxy authorization credentials. They are only sent when +both options are provided. + +protocol (http):: + +Protocol that will be used for tunneled requests. + +transport (tcp):: + +Transport that will be used for tunneled requests. Note that +due to Erlang/OTP limitations it is not possible to tunnel +a TLS connection inside a TLS tunnel. + +tls_opts ([]):: + +Options to use for tunneled TLS connections. + +tls_handshake_timeout (infinity):: + +Handshake timeout for tunneled TLS connections. + === http_opts() [source,erlang] @@ -246,6 +303,10 @@ server that ultimately decides. Defaults to false. // @todo Document default_protocol, protocols and user_opts. +== Changelog + +* *1.2*: Introduce the type `connect_destination()`. + == See also link:man:gun(7)[gun(7)] diff --git a/doc/src/manual/gun.connect.asciidoc b/doc/src/manual/gun.connect.asciidoc new file mode 100644 index 0000000..a1acaa5 --- /dev/null +++ b/doc/src/manual/gun.connect.asciidoc @@ -0,0 +1,115 @@ += gun:connect(3) + +== Name + +gun:connect - Establish a tunnel to the origin server + +== Description + +[source,erlang] +---- +connect(ConnPid, Destination) + -> connect(ConnPid, Destination, [], #{}). + +connect(ConnPid, Destination, Headers) + -> connect(ConnPid, Destination, Headers, #{}). + +connect(ConnPid, Destination, Headers, ReqOpts) + -> StreamRef + +ConnPid :: pid() +Destination :: gun:connect_destination() +Headers :: [{binary(), iodata()}] +ReqOpts :: gun:req_opts() +StreamRef :: reference() +---- + +Establish a tunnel to the origin server. + +This feature is currently only available for HTTP/1.1 connections. +Upon successful completion of the CONNECT request a tunnel is +established and subsequent requests will go through the tunnel. + +Gun will not automatically re-issue the CONNECT request upon +reconnection to the proxy server. The `gun_up` message can +be used to know when the tunnel needs to be established again. + +== Arguments + +ConnPid:: + +The pid of the Gun connection process. + +Destination:: + +Destination of the CONNECT request. + +Headers:: + +Additional request headers. + +ReqOpts:: + +Request options. + +== Return value + +A reference that identifies the newly created stream is +returned. It is this reference that must be passed in +subsequent calls and will be received in messages related +to this new stream. + +== Changelog + +* *1.2*: Function introduced. + +== Examples + +.Establish a tunnel +[source,erlang] +---- +{ok, ConnPid} = gun:open("proxy.example.org", 1080), +{ok, http} = gun:await_up(ConnPid), +StreamRef = gun:connect(ConnPid, #{ + host => "origin-server.example.org", + port => 80 +}), +{response, fin, 200, _} = gun:await(ConnPid, StreamRef), +%% Subsequent requests will be sent to origin-server.example.org. +---- + +.Establish a tunnel for a secure HTTP/2 connection +[source,erlang] +---- +{ok, ConnPid} = gun:open("proxy.example.org", 1080), +{ok, http} = gun:await_up(ConnPid), +StreamRef = gun:connect(ConnPid, #{ + host => "origin-server.example.org", + port => 80, + protocol => http2, + transport => tls +}), +{response, fin, 200, _} = gun:await(ConnPid, StreamRef), +%% Subsequent requests will be sent to origin-server.example.org. +---- + +.Establish a tunnel using proxy authorization +[source,erlang] +---- +{ok, ConnPid} = gun:open("proxy.example.org", 1080), +{ok, http} = gun:await_up(ConnPid), +StreamRef = gun:connect(ConnPid, #{ + host => "origin-server.example.org", + port => 80, + username => "essen", + password => "myrealpasswordis" +}), +{response, fin, 200, _} = gun:await(ConnPid, StreamRef), +%% Subsequent requests will be sent to origin-server.example.org. +---- + +== See also + +link:man:gun(3)[gun(3)], +link:man:gun:await_up(3)[gun:await_up(3)], +link:man:gun_up(3)[gun_up(3)] -- cgit v1.2.3