From 8366ba94bb9e450221a246acdd482c0162affcd9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 8 Apr 2015 23:34:08 +0300 Subject: Use maps for and improve options The type option has been removed. The transport and protocols options can be used in its place. The transport_opts option can be used to specify transport options. The http_opts and spdy_opts options can be used to specify protocol specific options. The keepalive option is now a protocol specific option. Defaults depending on the port number have changed. Now only port 443 uses ssl by default, other ports use tcp. --- doc/src/guide/connect.asciidoc | 24 ++++++++++----- doc/src/manual/gun.asciidoc | 66 +++++++++++++++++++++++++++++++----------- 2 files changed, 65 insertions(+), 25 deletions(-) (limited to 'doc') diff --git a/doc/src/guide/connect.asciidoc b/doc/src/guide/connect.asciidoc index e1ad56e..e2bcaa7 100644 --- a/doc/src/guide/connect.asciidoc +++ b/doc/src/guide/connect.asciidoc @@ -33,16 +33,24 @@ The `gun:open/{2,3}` function must be used to open a connection. [source,erlang] {ok, ConnPid} = gun:open("example.org", 443). -@todo open/3 -@todo make opts a map +If the port given is 443, Gun will attempt to connect using +SSL. The protocol will be selected automatically using the +NPN extension for TLS. By default Gun supports SPDY/3.1, +SPDY/3 and HTTP/1.1 when connecting using SSL. -If the port given is 80, Gun will attempt to connect using -TCP and use the HTTP/1.1 protocol. For any other port, TLS -will be used. The NPN extension for TLS allows Gun to select -SPDY automatically if the server supports it. Otherwise, -HTTP/1.1 will be used. +For any other port, Gun will attempt to connect using TCP +and will use the HTTP/1.1 protocol. -@todo more about defaults +The transport and protocol used can be overriden using +options. The manual documents all available options. + +Options can be provided as a third argument, and take the +form of a map. + +.Opening an SSL connection to example.org on port 8443 + +[source,erlang] +{ok, ConnPid} = gun:open("example.org", 8443, #{transport=>ssl}). === Monitoring the connection process diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc index 14641ee..9d592a8 100644 --- a/doc/src/manual/gun.asciidoc +++ b/doc/src/manual/gun.asciidoc @@ -12,30 +12,62 @@ HTTP or Websocket. == Types -=== opts() = [opt()] +=== opts() = map() Configuration for the connection. -@todo Should be a map. - -With opt(): - -keepalive => pos_integer():: - Time between pings in milliseconds. - Defaults to 5000. +The following keys are defined: + +http_opts => gun:http_opts():: + Options specific to the HTTP protocol. See below. +protocols => [http | spdy]:: + Ordered list of preferred protocols. When the transport is tcp, + this list must contain exactly one protocol. When the transport + is ssl, this list must contain at least one protocol and will be + used using the NPN protocol negotiation method. When the server + does not support NPN then http will always be used. Defaults to + [http] when the transport is tcp, and [spdy, http] when the + transport is ssl. retry => non_neg_integer():: Number of times Gun will try to reconnect on failure before giving up. Defaults to 5. retry_timeout => pos_integer():: - Time between retries in milliseconds. - Defaults to 5000. -type => ssl | tcp | tcp_spdy:: - Whether to use SSL, plain TCP (for HTTP/Websocket) or SPDY over TCP. - The default varies depending on the port used. Port 443 defaults - to ssl. Port 6121 defaults to tcp_spdy (@todo). All other ports - default to tcp. (@todo) - -@todo We want to separate protocol and transport options. + Time between retries in milliseconds. Defaults to 5000. +spdy_opts => gun:spdy_opts():: + Options specific to the SPDY protocol. See below. +trace => boolean():: + Whether to enable `dbg` tracing of the connection process. Should + only be used during debugging. Defaults to false. +transport => tcp | ssl:: + Whether to use SSL or plain TCP. The default varies depending on the + port used. Port 443 defaults to ssl. All other ports default to tcp. +transport_opts => proplists:proplist():: + Transport options. They are TCP options or SSL options depending on + the selected transport. + +=== http_opts() = map() + +Configuration for the HTTP protocol. + +The following keys are defined: + +keepalive => pos_integer():: + Time between pings in milliseconds. Since the HTTP protocol has + no standardized way to ping the server, Gun will simply send an + empty line when the connection is idle. Gun only makes a best + effort here as servers usually have configurable limits to drop + idle connections. Defaults to 5000. +version => 'HTTP/1.1' | 'HTTP/1.0':: + HTTP version to use. Defaults to 'HTTP/1.1'. + +=== spdy_opts() = map() + +Configuration for the SPDY protocol. + +The following keys are defined: + +keepalive => pos_integer():: + Time between pings in milliseconds. Defaults to 5000. @todo We need to document Websocket options. -- cgit v1.2.3