Gun 1.3.0

1 files changed, 127 insertions, 0 deletions

diff --git a/docs/en/gun/1.3/guide/protocols.asciidoc b/docs/en/gun/1.3/guide/protocols.asciidoc
new file mode 100644
index 00000000..2c4fd10e
--- /dev/null
+++ b/docs/en/gun/1.3/guide/protocols.asciidoc
@@ -0,0 +1,127 @@
+[[protocols]]
+== Supported protocols
+
+This chapter describes the protocols supported and the
+operations available to them.
+
+=== HTTP/1.1
+
+HTTP/1.1 is a text request-response protocol. The client
+sends a request, the server sends back a response.
+
+Gun provides convenience functions for performing GET, HEAD,
+OPTIONS, POST, PATCH, PUT, and DELETE requests. All these
+functions are aliases of `gun:request/4,5,6` for the respective
+methods. Gun also provides a `gun:data/4` function for streaming
+the request body.
+
+Gun will send a `gun_inform` message for every intermediate
+informational responses received. They will always be sent
+before the `gun_response` message.
+
+Gun will send a `gun_response` message for every response
+received, followed by zero or more `gun_data` messages for
+the response body, which is optionally terminated by a
+`gun_trailers` message. If something goes wrong, a `gun_error`
+will be sent instead.
+
+Gun provides convenience functions for dealing with messages.
+The `gun:await/2,3,4` function waits for a response to the given
+request, and the `gun:await_body/2,3,4` function for the
+response body. The `gun:flush/1` function can be used to clear all
+messages related to a request or a connection from the mailbox
+of the calling process.
+
+The function `gun:cancel/2` can be used to silence the
+response to a request previously sent if it is no longer
+needed. When using HTTP/1.1 there is no multiplexing so
+Gun will have to receive the response fully before any
+other responses can be received.
+
+Finally, Gun can upgrade an HTTP/1.1 connection to Websocket.
+It provides the `gun:ws_upgrade/2,3,4` function for that
+purpose. A `gun_upgrade` message will be sent on success;
+a `gun_response` message otherwise.
+
+=== HTTP/2
+
+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 additional resources along with
+the normal response to the original request.
+
+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.
+
+Gun will send `gun_push` messages for every push received.
+They will always be sent before the `gun_response` message.
+They can be ignored safely if they are not needed, or they
+can be canceled.
+
+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 currently possible to upgrade an HTTP/2 connection
+to Websocket. Support for this will be added in a future
+release.
+
+=== Websocket
+
+Websocket is a binary protocol built on top of HTTP that
+allows asynchronous concurrent communication between the
+client and the server. A Websocket server can push data to
+the client at any time.
+
+Websocket is only available as a connection upgrade over
+an HTTP/1.1 connection.
+
+Once the Websocket connection is established, the only
+operation available on this connection is sending Websocket
+frames using `gun:ws_send/2`.
+
+Gun will send a `gun_ws` message for every frame received.
+
+=== Summary
+
+The two following tables summarize the supported operations
+and the messages Gun sends depending on the connection's
+current protocol.
+
+.Supported operations per protocol
+[cols="<,3*^",options="header"]
+|===
+| 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 | HTTP/2 | Websocket
+| gun_push              | no       | yes    | no
+| gun_inform            | yes      | yes    | no
+| gun_response          | yes      | yes    | no
+| gun_data              | yes      | yes    | no
+| gun_trailers          | yes      | yes    | no
+| gun_error             | yes      | yes    | yes
+| gun_upgrade           | yes      | no     | no
+| gun_ws                | no       | no     | yes
+|===