summaryrefslogtreecommitdiffstats
path: root/docs/en/gun/1.3/guide/protocols.asciidoc
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2018-10-01 16:35:30 +0200
committerLoïc Hoguin <[email protected]>2018-10-01 16:35:30 +0200
commit24b2e92a06cf6275b972f66373d7bfea7bfc3518 (patch)
tree87ce1f6a58f9d95a69c85f81cd1b45ab6e321ddf /docs/en/gun/1.3/guide/protocols.asciidoc
parent3d7d9e20fe46ed2839bc582d599abeac3ce19a8b (diff)
downloadninenines.eu-24b2e92a06cf6275b972f66373d7bfea7bfc3518.tar.gz
ninenines.eu-24b2e92a06cf6275b972f66373d7bfea7bfc3518.tar.bz2
ninenines.eu-24b2e92a06cf6275b972f66373d7bfea7bfc3518.zip
Gun 1.3.0
Diffstat (limited to 'docs/en/gun/1.3/guide/protocols.asciidoc')
-rw-r--r--docs/en/gun/1.3/guide/protocols.asciidoc127
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
+|===