From 8459bebceb9533948193774371cbd9fd571b78ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Wed, 16 Oct 2019 09:48:31 +0200 Subject: Cowboy 2.7.0 --- docs/en/gun/1.0/guide/connect/index.html | 12 ++++----- docs/en/gun/1.0/guide/http/index.html | 42 +++++++++++++++--------------- docs/en/gun/1.0/guide/start/index.html | 10 +++---- docs/en/gun/1.0/guide/websocket/index.html | 10 +++---- 4 files changed, 35 insertions(+), 39 deletions(-) (limited to 'docs/en/gun/1.0/guide') diff --git a/docs/en/gun/1.0/guide/connect/index.html b/docs/en/gun/1.0/guide/connect/index.html index 24d62fff..d253d48b 100644 --- a/docs/en/gun/1.0/guide/connect/index.html +++ b/docs/en/gun/1.0/guide/connect/index.html @@ -71,7 +71,7 @@

Opening a new connection

The gun:open/2,3 function must be used to open a connection.

Opening a connection to example.org on port 443
-
@@ -82,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

The transport and protocol used can be overriden via options. The manual documents all available options.

Options can be provided as a third argument, and take the form of a map.

Opening a TLS connection to example.org on port 8443
-
@@ -92,7 +92,7 @@ http://www.gnu.org/software/src-highlite -->

When Gun successfully connects to the server, it sends a gun_up message with the protocol that has been selected for the connection.

Gun provides the functions gun:await_up/1,2,3 that wait for the gun_up message. They can optionally take a monitor reference and/or timeout value. If no monitor is provided, one will be created for the duration of the function call.

Synchronous opening of a connection
-
@@ -107,7 +107,7 @@ http://www.gnu.org/software/src-highlite -->

Gun leaves you the choice as to which one will be used. However, if you use the gun:await/2,3 or gun:await_body/2,3 functions, a monitor may be used for you to avoid getting stuck waiting for a message that will never come.

If you choose to monitor yourself you can do it on a permanent basis rather than on every message you will receive, saving resources. Indeed, the gun:await/3,4 and gun:await_body/3,4 functions both accept a monitor argument if you have one already.

Monitoring the connection process
-
@@ -116,7 +116,7 @@ http://www.gnu.org/software/src-highlite -->

This monitor reference can be kept and used until the connection process exits.

Handling `DOWN` messages
-
@@ -131,7 +131,7 @@ http://www.gnu.org/software/src-highlite -->

Closing the connection abruptly

The connection can be stopped abruptly at any time by calling the gun:close/1 function.

Immediate closing of the connection
-
diff --git a/docs/en/gun/1.0/guide/http/index.html b/docs/en/gun/1.0/guide/http/index.html index 0fd7edea..fb4105df 100644 --- a/docs/en/gun/1.0/guide/http/index.html +++ b/docs/en/gun/1.0/guide/http/index.html @@ -69,7 +69,7 @@

Streams can be canceled at any time. This will stop any further messages from being sent to the owner process. Depending on its capabilities, the server will also be instructed to cancel the request.

Canceling a stream may result in Gun dropping the connection temporarily, to avoid uploading or downloading data that will not be used.

Cancelling a stream
-
@@ -83,14 +83,14 @@ http://www.gnu.org/software/src-highlite -->

GET and HEAD

Use gun:get/2,3,4 to request a resource.

GET "/organizations/ninenines"
-
StreamRef = gun:get(ConnPid, "/organizations/ninenines").
GET "/organizations/ninenines" with custom headers
-
@@ -102,14 +102,14 @@ http://www.gnu.org/software/src-highlite -->

Note that the list of headers has the field name as a binary. The field value is iodata, which is either a binary or an iolist.

Use gun:head/2,3,4 if you don't need the response body.

HEAD "/organizations/ninenines"
-
StreamRef = gun:head(ConnPid, "/organizations/ninenines").
HEAD "/organizations/ninenines" with custom headers
-
@@ -128,7 +128,7 @@ http://www.gnu.org/software/src-highlite -->

The gun:post/4,5, gun:put/4,5 and gun:patch/4,5 functions take a body as their fourth argument. These functions do not require any body-specific header to be set, although it is always recommended to set the content-type header. Gun will set the other headers automatically.

In this and the following examples in this section, gun:post can be replaced by gun:put or gun:patch for performing a PUT or PATCH request, respectively.

POST "/organizations/ninenines"
-
@@ -140,7 +140,7 @@ http://www.gnu.org/software/src-highlite -->

The gun:post/3, gun:put/3 and gun:patch/3 functions do not take a body in their arguments. If a body is to be provided later on, using the gun:data/4 function, then the request headers must indicate this. This can be done by setting the content-length or content-type request headers. If these headers are not set then Gun will assume 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 HTTP/2 will continue normally as it is chunked by design.

POST "/organizations/ninenines" with delayed body
-
@@ -153,7 +153,7 @@ http://www.gnu.org/software/src-highlite -->

The atom fin indicates this is the last chunk of data to be sent. You can call the gun:data/4 function as many times as needed until you have sent the entire body. The last call must use fin and all the previous calls must use nofin. The last chunk may be empty.

Streaming the request body
-
@@ -174,14 +174,14 @@ http://www.gnu.org/software/src-highlite -->

DELETE

Use gun:delete/2,3,4 to delete a resource.

DELETE "/organizations/ninenines"
-
StreamRef = gun:delete(ConnPid, "/organizations/ninenines").
DELETE "/organizations/ninenines" with custom headers
-
@@ -192,14 +192,14 @@ http://www.gnu.org/software/src-highlite -->

OPTIONS

Use gun:options/2,3 to request information about a resource.

OPTIONS "/organizations/ninenines"
-
StreamRef = gun:options(ConnPid, "/organizations/ninenines").
OPTIONS "/organizations/ninenines" with custom headers
-
@@ -209,7 +209,7 @@ http://www.gnu.org/software/src-highlite -->

You can also use this function to request information about the server itself.

OPTIONS "*"
-
@@ -218,7 +218,7 @@ http://www.gnu.org/software/src-highlite -->

Requests with an arbitrary method

The gun:request/4,5,6 function can be used to send requests with a configurable method name. It is mostly useful when you need a method that Gun does not understand natively.

Example of a TRACE request
-
@@ -232,7 +232,7 @@ http://www.gnu.org/software/src-highlite -->

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.

You can receive messages directly, or you can use the await functions to let Gun receive them for you.

Receiving a response using receive
-
@@ -270,7 +270,7 @@ http://www.gnu.org/software/src-highlite -->

When calling gun:await/2,3 and not passing a monitor reference, one is automatically created for you for the duration of the call.

The gun:await_body/2,3,4 works similarly, but returns the body received. Both functions can be combined to receive the response and its body sequentially.

Receiving a response using await
-
@@ -288,7 +288,7 @@ http://www.gnu.org/software/src-highlite -->

You can safely choose to ignore gun_push messages, or you can handle them. If you do, you can either receive the messages directly or use await functions.

The gun_push message contains both the new stream reference and the stream reference of the original request.

Receiving a pushed response using receive
-
@@ -300,7 +300,7 @@ http://www.gnu.org/software/src-highlite -->

If you use the gun:await/2,3,4 function, however, Gun will use the original reference to identify the message but will return a tuple that doesn't contain it.

Receiving a pushed response using await
-
@@ -311,14 +311,14 @@ http://www.gnu.org/software/src-highlite -->

Flushing unwanted messages

Gun provides the function gun:flush/1 to quickly get rid of unwanted messages sitting in the process mailbox. You can use it to get rid of all messages related to a connection, or just the messages related to a stream.

Flush all messages from a Gun connection
-
gun:flush(ConnPid).
Flush all messages from a specific stream
-
@@ -327,7 +327,7 @@ http://www.gnu.org/software/src-highlite -->

Redirecting responses to a different process

Gun allows you to specify which process will handle responses to a request via the reply_to request option.

GET "/organizations/ninenines" to a different process
-
diff --git a/docs/en/gun/1.0/guide/start/index.html b/docs/en/gun/1.0/guide/start/index.html index 54908b09..9e07ac96 100644 --- a/docs/en/gun/1.0/guide/start/index.html +++ b/docs/en/gun/1.0/guide/start/index.html @@ -67,16 +67,12 @@

Specify Gun as a dependency to your application in your favorite build tool.

With Erlang.mk this is done by adding gun to the DEPS variable in your Makefile.

Adding Gun as an Erlang.mk dependency
-
-
DEPS = gun
+
source-highlight: could not find a language definition for make

Starting

Gun is an OTP application. It needs to be started before you can use it.

Starting Gun in an Erlang shell
-
@@ -86,7 +82,7 @@ http://www.gnu.org/software/src-highlite -->

Stopping

You can stop Gun using the application:stop/1 function, however only Gun will be stopped. This is the reverse of application:start/1. The application_ensure_all_started/1 function has no equivalent for stopping all applications.

Stopping Gun
-
diff --git a/docs/en/gun/1.0/guide/websocket/index.html b/docs/en/gun/1.0/guide/websocket/index.html index c2e93866..00cb6e43 100644 --- a/docs/en/gun/1.0/guide/websocket/index.html +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -68,7 +68,7 @@

Websocket is a protocol built on top of HTTP. To use Websocket, you must first request for the connection to be upgraded. Only HTTP/1.1 connections can be upgraded to Websocket, so you might need to restrict the protocol to HTTP/1.1 if you are planning to use Websocket over TLS.

You must use the gun:ws_upgrade/2,3,4 function to upgrade to Websocket. This function can be called anytime after connection, so you can send HTTP requests before upgrading to Websocket.

Upgrade to Websocket
-
@@ -76,7 +76,7 @@ http://www.gnu.org/software/src-highlite -->

Gun will set all the necessary headers for performing the Websocket upgrade, but you can specify additional headers if needed. For example you can request a custom sub-protocol.

Upgrade to Websocket and request a protocol
-
@@ -87,7 +87,7 @@ http://www.gnu.org/software/src-highlite -->

You can pass the Websocket options as part of the gun:open/2,3 call when opening the connection, or using the gun:ws_upgrade/4. The fourth argument is those same options.

When the upgrade succeeds, a gun_upgrade message is sent. If the server does not understand Websocket or refused the upgrade, a gun_response message is sent. If Gun couldn't perform the upgrade due to an error (for example attempting to upgrade to Websocket on an HTTP/1.0 connection) then a gun_error message is sent.

When the server does not understand Websocket, it may send a meaningful response which should be processed. In the following example we however ignore it:

-
@@ -107,7 +107,7 @@ http://www.gnu.org/software/src-highlite -->

Once the Websocket upgrade has completed successfully, you no longer have access to functions for performing requests. You can only send and receive Websocket messages.

Use gun:ws_send/2 to send messages to the server.

Send a text frame
-
@@ -127,7 +127,7 @@ http://www.gnu.org/software/src-highlite -->

Note that if you send a close frame, Gun will close the connection cleanly but will attempt to reconnect afterwards.

Receiving data

Gun sends an Erlang message to the owner process for every Websocket message it receives.

-
-- cgit v1.2.3