From b5d4cb91f80c833795a2d87050c3674bb7aecdc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 3 Oct 2017 13:39:41 +0200 Subject: Update Hugo, docs --- docs/en/gun/1.0/guide/websocket/index.html | 249 +++++++++++++++-------------- 1 file changed, 126 insertions(+), 123 deletions(-) (limited to 'docs/en/gun/1.0/guide/websocket') diff --git a/docs/en/gun/1.0/guide/websocket/index.html b/docs/en/gun/1.0/guide/websocket/index.html index 4f162488..b10064cf 100644 --- a/docs/en/gun/1.0/guide/websocket/index.html +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -7,7 +7,7 @@ - + Nine Nines: Websocket @@ -67,134 +67,137 @@

Websocket

-

This chapter describes how to use the Gun client for -communicating with a Websocket server.

-

@todo recovering from connection failure -reconnecting to Websocket etc.

-
-

HTTP upgrade

-
-

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
-
-
gun:ws_upgrade(ConnPid, "/websocket").
-

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
-
-
gun:ws_upgrade(ConnPid, "/websocket", [
-        {<<"sec-websocket-protocol">>, "mychat"}
-]).
-

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. This function call -will crash if the options are incorrect, unlike when passing -them through gun:open/{2,3}.

-

When the upgrade succeeds, a gun_ws_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:

-
-
-
receive
-        {gun_ws_upgrade, ConnPid, ok, Headers} ->
-                upgrade_success(ConnPid);
-        {gun_response, ConnPid, _, _, Status, Headers} ->
-                exit({ws_upgrade_failed, Status, Headers});
-        {gun_error, ConnPid, StreamRef, Reason} ->
-                exit({ws_upgrade_failed, Reason})
-        %% More clauses here as needed.
-after 1000 ->
-        exit(timeout)
-end.
-

Note that you shouldn’t use the reply_to request option -for connections you plan to upgrade, because only the -owner of the connection will receive messages about it.

-
-
-
-

Sending data

-
-

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 one or more messages to the server.

-

@todo Implement sending of N frames

-
-
Send a text frame
-
-
gun:ws_send(ConnPid, {text, "Hello!"}).
-
-
Send a text frame, a binary frame and then close the connection
-
-
gun:ws_send(ConnPid, [
-        {text, "Hello!"},
-        {binary, BinaryValue},
-        close
-]).
-

Note that if you send a close frame, Gun will close the connection -cleanly and will not attempt to reconnect afterwards, similar to -calling gun:shutdown/1.

-
-
-
-

Receiving data

-
-

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

-
-
-
receive
-        {gun_ws, ConnPid, Frame} ->
-                handle_frame(ConnPid, Frame)
-end.
-

@todo auto ping has not been implemented yet

-

Gun will automatically send ping messages to the server to keep -the connection alive, however if the connection dies and Gun has -to reconnect it will not upgrade to Websocket automatically, you -need to perform the operation when you receive the gun_error -message.

-
-
+

This chapter describes how to use the Gun client for +communicating with a Websocket server.

+

@todo recovering from connection failure +reconnecting to Websocket etc.

+
+

HTTP upgrade

+
+

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
+
+
gun:ws_upgrade(ConnPid, "/websocket").
+

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
+
+
gun:ws_upgrade(ConnPid, "/websocket", [
+        {<<"sec-websocket-protocol">>, "mychat"}
+]).
+

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. This function call +will crash if the options are incorrect, unlike when passing +them through gun:open/{2,3}.

+

When the upgrade succeeds, a gun_ws_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:

+
+
+
receive
+        {gun_ws_upgrade, ConnPid, ok, Headers} ->
+                upgrade_success(ConnPid);
+        {gun_response, ConnPid, _, _, Status, Headers} ->
+                exit({ws_upgrade_failed, Status, Headers});
+        {gun_error, ConnPid, StreamRef, Reason} ->
+                exit({ws_upgrade_failed, Reason})
+        %% More clauses here as needed.
+after 1000 ->
+        exit(timeout)
+end.
+

Note that you shouldn’t use the reply_to request option +for connections you plan to upgrade, because only the +owner of the connection will receive messages about it.

+
+
+
+

Sending data

+
+

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 one or more messages to the server.

+

@todo Implement sending of N frames

+
+
Send a text frame
+
+
gun:ws_send(ConnPid, {text, "Hello!"}).
+
+
Send a text frame, a binary frame and then close the connection
+
+
gun:ws_send(ConnPid, [
+        {text, "Hello!"},
+        {binary, BinaryValue},
+        close
+]).
+

Note that if you send a close frame, Gun will close the connection +cleanly and will not attempt to reconnect afterwards, similar to +calling gun:shutdown/1.

+
+
+
+

Receiving data

+
+

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

+
+
+
receive
+        {gun_ws, ConnPid, Frame} ->
+                handle_frame(ConnPid, Frame)
+end.
+

@todo auto ping has not been implemented yet

+

Gun will automatically send ping messages to the server to keep +the connection alive, however if the connection dies and Gun has +to reconnect it will not upgrade to Websocket automatically, you +need to perform the operation when you receive the gun_error +message.

+
+
+ + +