aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2017-08-12 16:06:59 +0200
committerLoïc Hoguin <[email protected]>2017-08-12 16:06:59 +0200
commit24a777945ae57940f8480b4940599187bba2edcb (patch)
treeae5947ce7e582c0be5eb97891da94bb254e28103 /doc
parent354c1c4ab611d3df81caac928dec1dcc888821e0 (diff)
downloadgun-24a777945ae57940f8480b4940599187bba2edcb.tar.gz
gun-24a777945ae57940f8480b4940599187bba2edcb.tar.bz2
gun-24a777945ae57940f8480b4940599187bba2edcb.zip
Remove SPDY; document HTTP/2
I just replaced "SPDY" with "HTTP/2" in the documentation. I suspect that's all that's needed, but if there's something off we can fix it later.
Diffstat (limited to 'doc')
-rw-r--r--doc/src/guide/connect.asciidoc8
-rw-r--r--doc/src/guide/http.asciidoc8
-rw-r--r--doc/src/guide/introduction.asciidoc4
-rw-r--r--doc/src/guide/protocols.asciidoc60
-rw-r--r--doc/src/manual/gun.asciidoc40
-rw-r--r--doc/src/manual/gun_app.asciidoc4
6 files changed, 62 insertions, 62 deletions
diff --git a/doc/src/guide/connect.asciidoc b/doc/src/guide/connect.asciidoc
index c2e887c..e0b09d6 100644
--- a/doc/src/guide/connect.asciidoc
+++ b/doc/src/guide/connect.asciidoc
@@ -5,10 +5,10 @@ a connection using the Gun client.
=== Gun connections
-Gun is designed with the SPDY and Websocket protocols in mind.
+Gun is designed with the HTTP/2 and Websocket protocols in mind.
They are built for long-running connections that allow concurrent
exchange of data, either in the form of request/responses for
-SPDY or in the form of messages for Websocket.
+HTTP/2 or in the form of messages for Websocket.
A Gun connection is an Erlang process that manages a socket to
a remote endpoint. This Gun connection is owned by a user
@@ -35,8 +35,8 @@ The `gun:open/{2,3}` function must be used to open a connection.
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.
+ALPN extension for TLS. By default Gun supports HTTP/2
+and HTTP/1.1 when connecting using SSL.
For any other port, Gun will attempt to connect using TCP
and will use the HTTP/1.1 protocol.
diff --git a/doc/src/guide/http.asciidoc b/doc/src/guide/http.asciidoc
index e856fb1..ff4aa0a 100644
--- a/doc/src/guide/http.asciidoc
+++ b/doc/src/guide/http.asciidoc
@@ -1,7 +1,7 @@
== HTTP
This chapter describes how to use the Gun client for
-communicating with an HTTP/1.1 or SPDY server.
+communicating with an HTTP/1.1 or HTTP/2 server.
=== Streams
@@ -130,7 +130,7 @@ the request has no body.
It is recommended to send the content-length header if you
know it in advance, although this is not required. If it
is not set, HTTP/1.1 will use the chunked transfer-encoding,
-and SPDY will continue normally as it is chunked by design.
+and HTTP/2 will continue normally as it is chunked by design.
.POST "/organizations/ninenines" with delayed body
@@ -234,7 +234,7 @@ data messages following. If it contains `fin` there will be
no data messages. If it contains `nofin` then one or more data
messages will follow.
-When using SPDY this value is sent with the frame and simply
+When using HTTP/2 this value is sent with the frame and simply
passed on in the message. When using HTTP/1.1 however Gun must
guess whether data will follow by looking at the response headers.
@@ -309,7 +309,7 @@ end.
=== Handling streams pushed by the server
-The SPDY protocol allows the server to push more than one
+The HTTP/2 protocol allows the server to push more than one
resource for every request. It will start sending those
extra resources before it starts sending the response itself,
so Gun will send you `gun_push` messages before `gun_response`
diff --git a/doc/src/guide/introduction.asciidoc b/doc/src/guide/introduction.asciidoc
index 2914ef6..89f2ae7 100644
--- a/doc/src/guide/introduction.asciidoc
+++ b/doc/src/guide/introduction.asciidoc
@@ -1,10 +1,10 @@
== Introduction
-Gun is an Erlang HTTP client with support for HTTP/1.1, SPDY and Websocket.
+Gun is an Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.
=== Prerequisites
-Knowledge of Erlang, but also of the HTTP/1.1, SPDY and Websocket
+Knowledge of Erlang, but also of the HTTP/1.1, HTTP/2 and Websocket
protocols is required in order to read this guide.
=== Supported platforms
diff --git a/doc/src/guide/protocols.asciidoc b/doc/src/guide/protocols.asciidoc
index 5e3b273..ae7705f 100644
--- a/doc/src/guide/protocols.asciidoc
+++ b/doc/src/guide/protocols.asciidoc
@@ -37,29 +37,29 @@ It provides the `gun:ws_upgrade/{2,3,4}` function for that
purpose. A `gun_ws_upgrade` message will be sent on success;
a `gun_response` message otherwise.
-=== SPDY
+=== HTTP/2
-SPDY is a binary protocol based on HTTP, compatible with
+HTTP/2 is a binary protocol based on HTTP, compatible with
the HTTP semantics, that reduces the complexity of parsing
requests and responses, compresses the HTTP headers and
allows the server to push multiple responses to a single
request.
-The SPDY interface is very similar to HTTP/1.1, so this
+The HTTP/2 interface is very similar to HTTP/1.1, so this
section instead focuses on the differences in the interface
for the two protocols.
-Because a SPDY server can push multiple responses to a
+Because a HTTP/2 server can push multiple responses to a
single request, Gun might send `gun_push` messages for
every push received. They can be ignored safely if they
are not needed.
-The `gun:cancel/2` function will use the SPDY stream
+The `gun:cancel/2` function will use the HTTP/2 stream
cancellation mechanism which allows Gun to inform the
server to stop sending a response for this particular
request, saving resources.
-It is not possible to upgrade a SPDY connection to Websocket
+It is not possible to upgrade an HTTP/2 connection to Websocket
due to protocol limitations.
=== Websocket
@@ -87,33 +87,33 @@ current protocol.
.Supported operations per protocol
[cols="<,3*^",options="header"]
|===
-| Operation | HTTP/1.1 | SPDY | Websocket
-| delete | yes | yes | no
-| get | yes | yes | no
-| head | yes | yes | no
-| options | yes | yes | no
-| patch | yes | yes | no
-| post | yes | yes | no
-| put | yes | yes | no
-| request | yes | yes | no
-| data | yes | yes | no
-| await | yes | yes | no
-| await_body | yes | yes | no
-| flush | yes | yes | no
-| cancel | yes | yes | no
-| ws_upgrade | yes | no | no
-| ws_send | no | no | yes
+| Operation | HTTP/1.1 | HTTP/2 | Websocket
+| delete | yes | yes | no
+| get | yes | yes | no
+| head | yes | yes | no
+| options | yes | yes | no
+| patch | yes | yes | no
+| post | yes | yes | no
+| put | yes | yes | no
+| request | yes | yes | no
+| data | yes | yes | no
+| await | yes | yes | no
+| await_body | yes | yes | no
+| flush | yes | yes | no
+| cancel | yes | yes | no
+| ws_upgrade | yes | no | no
+| ws_send | no | no | yes
|===
.Messages sent per protocol
[cols="<,3*^",options="header"]
|===
-| Message | HTTP/1.1 | SPDY | Websocket
-| gun_push | no | yes | no
-| gun_response | yes | yes | no
-| gun_data | yes | yes | no
-| gun_error (StreamRef) | yes | yes | no
-| gun_error | yes | yes | yes
-| gun_ws_upgrade | yes | no | no
-| gun_ws | no | no | yes
+| Message | HTTP/1.1 | HTTP/2 | Websocket
+| gun_push | no | yes | no
+| gun_response | yes | yes | no
+| gun_data | yes | yes | no
+| gun_error (StreamRef) | yes | yes | no
+| gun_error | yes | yes | yes
+| gun_ws_upgrade | yes | no | no
+| gun_ws | no | no | yes
|===
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 7c794ee..2487150 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -7,8 +7,8 @@ gun - asynchronous HTTP client
== Description
The `gun` module provides an asynchronous interface for
-connecting and communicating with Web servers over SPDY,
-HTTP or Websocket.
+connecting and communicating with Web servers over HTTP,
+HTTP/2 or Websocket.
== Types
@@ -22,21 +22,21 @@ connect_timeout => timeout()::
Connection timeout. Defaults to `infinity`.
http_opts => http_opts()::
Options specific to the HTTP protocol. See below.
-protocols => [http | spdy]::
+http2_opts => http2_opts()::
+ Options specific to the HTTP/2 protocol. See below.
+protocols => [http | http2]::
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
+ used using the ALPN protocol negotiation method. 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 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.
-spdy_opts => 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.
@@ -70,23 +70,23 @@ transform_header_name => fun((LowercaseName :: binary()) -> TransformedName :: b
version => 'HTTP/1.1' | 'HTTP/1.0'::
HTTP version to use. Defaults to 'HTTP/1.1'.
-=== req_opts() = map()
+=== http2_opts() = map()
-Configuration for a particular request.
+Configuration for the HTTP/2 protocol.
The following keys are defined:
-reply_to => pid()::
- The pid of a process that is responsible for the response handling.
+keepalive => pos_integer()::
+ Time between pings in milliseconds. Defaults to 5000.
-=== spdy_opts() = map()
+=== req_opts() = map()
-Configuration for the SPDY protocol.
+Configuration for a particular request.
The following keys are defined:
-keepalive => pos_integer()::
- Time between pings in milliseconds. Defaults to 5000.
+reply_to => pid()::
+ The pid of a process that is responsible for the response handling.
=== ws_opts() = map()
@@ -107,7 +107,7 @@ messages being sent.
=== {gun_up, ConnPid, Protocol}
ConnPid = pid():: The pid of the Gun connection process.
-Protocol = http | spdy:: The protocol selected for this connection.
+Protocol = http | http2:: The protocol selected for this connection.
The connection is up.
@@ -127,7 +127,7 @@ subsequent messages ignored.
=== {gun_down, ConnPid, Protocol, Reason, KilledStreams, UnprocessedStreams}
ConnPid = pid():: The pid of the Gun connection process.
-Protocol = http | spdy | ws:: The protocol in use when the connection was lost.
+Protocol = http | http2 | ws:: The protocol in use when the connection was lost.
Reason = normal | closed | {error, atom()}:: The reason for the loss of the connection.
KilledStreams = [reference()]:: List of streams that have been brutally terminated.
UnprocessedStreams = [reference()]:: List of streams that have not been processed by the server.
@@ -165,7 +165,7 @@ Headers = [{binary(), binary()}]:: Headers @todo
A resource pushed alongside an HTTP response.
-This message can only be sent when the protocol is SPDY.
+This message can only be sent when the protocol is HTTP/2.
@todo I fear we also need the scheme; resource is identified by URI
@todo Perhaps we really should send the URI entirely, because cache
@@ -685,7 +685,7 @@ the stream and stop relaying messages.
@todo of a response Gun may also attempt to reconnect rather than
@todo receive the entire response body.
-SPDY streams can however be cancelled at any time.
+HTTP/2 streams can however be cancelled at any time.
=== ws_upgrade(ConnPid, Path) -> ws_upgrade(ConnPid, Path, [], #{})
diff --git a/doc/src/manual/gun_app.asciidoc b/doc/src/manual/gun_app.asciidoc
index e4447d6..219a323 100644
--- a/doc/src/manual/gun_app.asciidoc
+++ b/doc/src/manual/gun_app.asciidoc
@@ -2,14 +2,14 @@
== Name
-gun - Erlang HTTP client with support for HTTP/1.1, SPDY and Websocket.
+gun - Erlang HTTP client with support for HTTP/1.1, HTTP/2 and Websocket.
== Dependencies
The `gun` application uses the Erlang applications `ranch`
for abstracting TCP and TLS over a common interface, and
the `ssl` application for TLS support, required for HTTPS
-and SPDY support. In addition, Gun requires the `crypto`
+and secure HTTP/2 support. In addition, Gun requires the `crypto`
application (a dependency of `ssl`) for Websocket.
These dependencies must be started for the `gun`