diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/src/manual/gun.asciidoc | 111 | ||||
| -rw-r--r-- | doc/src/manual/gun.await_up.asciidoc | 3 | ||||
| -rw-r--r-- | doc/src/manual/gun.info.asciidoc | 6 | ||||
| -rw-r--r-- | doc/src/manual/gun.open.asciidoc | 5 | ||||
| -rw-r--r-- | doc/src/manual/gun.open_unix.asciidoc | 5 | ||||
| -rw-r--r-- | doc/src/manual/gun_down.asciidoc | 3 | ||||
| -rw-r--r-- | doc/src/manual/gun_error.asciidoc | 1 | ||||
| -rw-r--r-- | doc/src/manual/gun_socks_up.asciidoc | 66 | ||||
| -rw-r--r-- | doc/src/manual/gun_up.asciidoc | 13 |
9 files changed, 186 insertions, 27 deletions
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc index b9fbbc2..7b54666 100644 --- a/doc/src/manual/gun.asciidoc +++ b/doc/src/manual/gun.asciidoc @@ -63,6 +63,7 @@ by sending any of the following messages: Connection: * link:man:gun_up(3)[gun_up(3)] - The connection is up +* link:man:gun_socks_up(3)[gun_socks_up(3)] - The Socks connection is up * link:man:gun_down(3)[gun_down(3)] - The connection is down * link:man:gun_upgrade(3)[gun_upgrade(3)] - Successful protocol upgrade * link:man:gun_error(3)[gun_error(3)] - Stream or connection-wide error @@ -96,7 +97,7 @@ connect_destination() :: #{ username => iodata(), password => iodata(), - protocols => [http | http2], + protocols => protocols(), transport => tcp | tls, tls_opts => [ssl:tls_client_option()], @@ -121,15 +122,17 @@ username, password:: Proxy authorization credentials. They are only sent when both options are provided. -protocol (http):: +protocols - see below:: -Protocol that will be used for tunneled requests. +Ordered list of preferred protocols. Please refer to the +`protocols()` type documentation for details. ++ +Defaults to `[http]` when the transport is `tcp`, +and `[http2, http]` when the transport is `tls`. 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. +Transport that will be used for tunneled requests. tls_opts ([]):: @@ -233,7 +236,7 @@ opts() :: #{ domain_lookup_timeout => timeout(), http_opts => http_opts(), http2_opts => http2_opts(), - protocols => [http | http2], + protocols => protocols(), retry => non_neg_integer(), retry_fun => fun(), retry_timeout => pos_integer(), @@ -269,13 +272,11 @@ Options specific to the HTTP/2 protocol. protocols - see below:: -Ordered list of preferred protocols. When the transport is `tcp`, -this list must contain exactly one protocol. When the transport -is `tls`, this list must contain at least one protocol and will be -used to negotiate a protocol via ALPN. When the server does not -support ALPN then `http` will always be used. Defaults to -`[http]` when the transport is `tcp`, and `[http2, http]` when the -transport is `tls`. +Ordered list of preferred protocols. Please refer to the +`protocols()` type documentation for details. ++ +Defaults to `[http]` when the transport is `tcp`, +and `[http2, http]` when the transport is `tls`. retry (5):: @@ -340,6 +341,25 @@ ws_opts (#{}):: Options specific to the Websocket protocol. +=== protocols() + +[source,erlang] +---- +protocols() :: http | {http, http_opts()} + | http2 | {http2, http2_opts()} + | socks | {socks, socks_opts()} +---- + +Ordered list of preferred protocols. When the transport is `tcp`, +this list must contain exactly one protocol. When the transport +is `tls`, this list must contain at least one protocol and will be +used to negotiate a protocol via ALPN. When the server does not +support ALPN then `http` will be used, except when the list of +preferred protocols is set to only accept `socks`. + +Defaults to `[http]` when the transport is `tcp`, +and `[http2, http]` when the transport is `tls`. + === req_headers() [source,erlang] @@ -373,6 +393,64 @@ reply_to (`self()`):: The pid of the process that will receive the response messages. +=== socks_opts() + +[source,erlang] +---- +socks_opts() :: #{ + host := inet:hostname() | inet:ip_address(), + port := inet:port_number(), + + auth => [{username_password, binary(), binary()} | none], + protocols => protocols(), + transport => tcp | tls, + version => 5, + + tls_opts => [ssl:tls_client_option()], + tls_handshake_timeout => timeout() +} +---- + +Configuration for the Socks protocol. + +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 Socks connection, Gun will +begin using these as the host and port of the origin server +for subsequent requests. + +auth ([none]):: + +Authentication methods Gun advertises to the Socks proxy. + +protocols - see below:: + +Ordered list of preferred protocols. Please refer to the +`protocols()` type documentation for details. ++ +Defaults to `[http]` when the transport is `tcp`, +and `[http2, http]` when the transport is `tls`. + +transport (tcp):: + +Transport that will be used for tunneled requests. + +tls_opts ([]):: + +Options to use for tunneled TLS connections. + +tls_handshake_timeout (infinity):: + +Handshake timeout for tunneled TLS connections. + +version (5):: + +Version of the Socks protocol to use. + === ws_opts() [source,erlang] @@ -417,6 +495,11 @@ undocumented and must be set to `gun_ws_h`. == Changelog +* *2.0*: The types `protocols()` and `socks_opts()` have been + added. Support for the Socks protocol has been added + in every places where protocol selection is available. + In addition it is now possible to specify separate + HTTP options for the CONNECT proxy and the origin server. * *2.0*: The `connect_timeout` option has been split into three options: `domain_lookup_timeout`, `connect_timeout` and when applicable `tls_handshake_timeout`. diff --git a/doc/src/manual/gun.await_up.asciidoc b/doc/src/manual/gun.await_up.asciidoc index dfd4da9..d9934b5 100644 --- a/doc/src/manual/gun.await_up.asciidoc +++ b/doc/src/manual/gun.await_up.asciidoc @@ -23,7 +23,7 @@ await_up(ConnPid, Timeout, MonitorRef) ConnPid :: pid() MonitorRef :: reference() Timeout :: timeout() -Protocol :: http | http2 +Protocol :: http | http2 | socks Reason :: {down, any()} | timeout ---- @@ -71,4 +71,5 @@ may also be returned when a timeout or an error occur. link:man:gun(3)[gun(3)], link:man:gun:open(3)[gun:open(3)], link:man:gun:open_unix(3)[gun:open_unix(3)], +link:man:gun_socks_up(3)[gun_socks_up(3)], link:man:gun_up(3)[gun_up(3)] diff --git a/doc/src/manual/gun.info.asciidoc b/doc/src/manual/gun.info.asciidoc index afb2333..cf861c9 100644 --- a/doc/src/manual/gun.info.asciidoc +++ b/doc/src/manual/gun.info.asciidoc @@ -14,7 +14,7 @@ ConnPid :: pid() Info :: #{ socket => inet:socket() | ssl:sslsocket(), transport => tcp | tls, - protocol => http | http2 | ws, + protocol => http | http2 | socks | ws, sock_ip => inet:ip_address(), sock_port => inet:port_number(), origin_host => inet:hostname() | inet:ip_address(), @@ -22,11 +22,11 @@ Info :: #{ intermediaries => [Intermediary] } Intermediary :: #{ - type => connect, + type => connect | socks5, host => inet:hostname() | inet:ip_address(), port => inet:port_number(), transport => tcp | tls, - protocol => http | http2 + protocol => http | http2 | socks } ---- diff --git a/doc/src/manual/gun.open.asciidoc b/doc/src/manual/gun.open.asciidoc index 79a9d54..63bb3f8 100644 --- a/doc/src/manual/gun.open.asciidoc +++ b/doc/src/manual/gun.open.asciidoc @@ -14,7 +14,9 @@ open(Host, Port, Opts) -> {ok, pid()} | {error, Reason} Host :: inet:hostname() | inet:ip_address() Port :: inet:port_number() Opts :: gun:opts() -Reason :: {options, OptName} | {options, {http | http2, OptName}} | any() +Reason :: {options, OptName} + | {options, {http | http2 | socks | ws, OptName}} + | any() OptName :: atom() ---- @@ -71,4 +73,5 @@ message will be sent for that. link:man:gun(3)[gun(3)], link:man:gun:open_unix(3)[gun:open_unix(3)], link:man:gun:await_up(3)[gun:await_up(3)], +link:man:gun_socks_up(3)[gun_socks_up(3)], link:man:gun_up(3)[gun_up(3)] diff --git a/doc/src/manual/gun.open_unix.asciidoc b/doc/src/manual/gun.open_unix.asciidoc index 4ea8d2b..441bfa8 100644 --- a/doc/src/manual/gun.open_unix.asciidoc +++ b/doc/src/manual/gun.open_unix.asciidoc @@ -12,7 +12,9 @@ open_unix(SocketPath, Opts) -> {ok, pid()} | {error, Reason} SocketPath :: string() Opts :: gun:opts() -Reason :: {options, OptName} | {options, {http | http2, OptName}} | any() +Reason :: {options, OptName} + | {options, {http | http2 | socks | ws, OptName}} + | any() OptName :: atom() ---- @@ -59,4 +61,5 @@ message will be sent for that. link:man:gun(3)[gun(3)], link:man:gun:open(3)[gun:open(3)], link:man:gun:await_up(3)[gun:await_up(3)], +link:man:gun_socks_up(3)[gun_socks_up(3)], link:man:gun_up(3)[gun_up(3)] diff --git a/doc/src/manual/gun_down.asciidoc b/doc/src/manual/gun_down.asciidoc index 67c7796..6c72898 100644 --- a/doc/src/manual/gun_down.asciidoc +++ b/doc/src/manual/gun_down.asciidoc @@ -11,7 +11,7 @@ gun_down - The connection is down {gun_down, ConnPid, Protocol, Reason, KilledStreams, UnprocessedStreams} ConnPid :: pid() -Protocol :: http | http2 | ws +Protocol :: http | http2 | socks | ws Reason :: any() KilledStreams :: [reference()] UnprocessedStreams :: [reference()] @@ -83,4 +83,5 @@ link:man:gun(3)[gun(3)], link:man:gun:open(3)[gun:open(3)], link:man:gun:open_unix(3)[gun:open_unix(3)], link:man:gun_up(3)[gun_up(3)], +link:man:gun_socks_up(3)[gun_socks_up(3)], link:man:gun_error(3)[gun_error(3)] diff --git a/doc/src/manual/gun_error.asciidoc b/doc/src/manual/gun_error.asciidoc index a43d32b..ac278fd 100644 --- a/doc/src/manual/gun_error.asciidoc +++ b/doc/src/manual/gun_error.asciidoc @@ -64,4 +64,5 @@ handle_info({gun_error, ConnPid, _StreamRef, _Reason}, link:man:gun(3)[gun(3)], link:man:gun_up(3)[gun_up(3)], +link:man:gun_socks_up(3)[gun_socks_up(3)], link:man:gun_down(3)[gun_down(3)] diff --git a/doc/src/manual/gun_socks_up.asciidoc b/doc/src/manual/gun_socks_up.asciidoc new file mode 100644 index 0000000..e74f1a9 --- /dev/null +++ b/doc/src/manual/gun_socks_up.asciidoc @@ -0,0 +1,66 @@ += gun_socks_up(3) + +== Name + +gun_socks_up - The Socks connection is up + +== Description + +[source,erlang] +---- +{gun_socks_up, ConnPid, Protocol} + +ConnPid :: pid() +Protocol :: http | http2 | socks +---- + +The Socks connection is up. + +This message informs the owner process that the connection +completed through the configured Socks proxy. + +If Gun is configured to connect to another Socks server, then the +connection is not usable yet. One or more +link:man:gun_socks_up(3)[gun_socks_up(3)] messages will follow. + +Otherwise, Gun will start processing the messages it received while +waiting for the connection to be up. If this is a reconnection, +then this may not be desirable for all requests. Those requests +should be cancelled when the connection goes down, and any +subsequent messages ignored. + +== Elements + +ConnPid:: + +The pid of the Gun connection process. + +Protocol:: + +The protocol selected for this connection. It can be used +to determine the capabilities of the server. + +== Changelog + +* *2.0*: Message introduced. + +== Examples + +.Receive a gun_socks_up message in a gen_server +[source,erlang] +---- +handle_info({gun_socks_up, ConnPid, _Protocol}, + State=#state{conn_pid=ConnPid}) -> + %% Do something. + {noreply, State}. +---- + +== See also + +link:man:gun(3)[gun(3)], +link:man:gun:open(3)[gun:open(3)], +link:man:gun:open_unix(3)[gun:open_unix(3)], +link:man:gun:await_up(3)[gun:await_up(3)], +link:man:gun_up(3)[gun_up(3)], +link:man:gun_down(3)[gun_down(3)], +link:man:gun_error(3)[gun_error(3)] diff --git a/doc/src/manual/gun_up.asciidoc b/doc/src/manual/gun_up.asciidoc index a103594..db09fca 100644 --- a/doc/src/manual/gun_up.asciidoc +++ b/doc/src/manual/gun_up.asciidoc @@ -11,7 +11,7 @@ gun_up - The connection is up {gun_up, ConnPid, Protocol} ConnPid :: pid() -Protocol :: http | http2 +Protocol :: http | http2 | socks ---- The connection is up. @@ -19,16 +19,16 @@ The connection is up. This message informs the owner process that the connection or reconnection completed. -Gun will now start processing the messages it received while +If Gun is configured to connect to a Socks server, then the +connection is not usable yet. One or more +link:man:gun_socks_up(3)[gun_socks_up(3)] messages will follow. + +Otherwise, Gun will start processing the messages it received while waiting for the connection to be up. If this is a reconnection, then this may not be desirable for all requests. Those requests should be cancelled when the connection goes down, and any subsequent messages ignored. -// @todo Gun doesn't process messages immediately if it -// is using the socks protocol, there are gun_socks_connected -// messages coming up before reaching HTTP. - == Elements ConnPid:: @@ -61,5 +61,6 @@ link:man:gun(3)[gun(3)], link:man:gun:open(3)[gun:open(3)], link:man:gun:open_unix(3)[gun:open_unix(3)], link:man:gun:await_up(3)[gun:await_up(3)], +link:man:gun_socks_up(3)[gun_socks_up(3)], link:man:gun_down(3)[gun_down(3)], link:man:gun_error(3)[gun_error(3)] |