From 2b588340af501825f3ab03f2e76dba0353c98fae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Mon, 4 Jun 2018 12:59:26 +0200 Subject: Update documentation for Gun 1.0 --- docs/en/gun/1.0/guide/protocols/index.html | 51 ++++++++++++++++++------------ 1 file changed, 30 insertions(+), 21 deletions(-) (limited to 'docs/en/gun/1.0/guide/protocols') diff --git a/docs/en/gun/1.0/guide/protocols/index.html b/docs/en/gun/1.0/guide/protocols/index.html index b94891f0..00d70ad6 100644 --- a/docs/en/gun/1.0/guide/protocols/index.html +++ b/docs/en/gun/1.0/guide/protocols/index.html @@ -7,8 +7,6 @@ - - Nine Nines: Supported protocols @@ -73,27 +71,31 @@ operations available to them.

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 each respective +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. If something goes wrong, a gun_error +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’s body. The gun:flush/1 function can be used to clear all +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 process.

+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 response can be received.

+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_ws_upgrade message will be sent on success; +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.

@@ -103,21 +105,22 @@ a gun_response message otherwise.

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.

+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.

-

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.

+

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 possible to upgrade an HTTP/2 connection to Websocket -due to protocol limitations.

+

It is not currently possible to upgrade an HTTP/2 connection +to Websocket. Support for this will be added in a future +release.

@@ -277,6 +280,12 @@ cellspacing="0" cellpadding="4">

no

+

gun_inform

+

yes

+

yes

+

no

+ +

gun_response

yes

yes

@@ -289,7 +298,7 @@ cellspacing="0" cellpadding="4">

no

-

gun_error (StreamRef)

+

gun_trailers

yes

yes

no

@@ -301,7 +310,7 @@ cellspacing="0" cellpadding="4">

yes

-

gun_ws_upgrade

+

gun_upgrade

yes

no

no

-- cgit v1.2.3