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/websocket/index.html | 62 ++++++++---------------------- 1 file changed, 17 insertions(+), 45 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 b34a290d..a77f1319 100644 --- a/docs/en/gun/1.0/guide/websocket/index.html +++ b/docs/en/gun/1.0/guide/websocket/index.html @@ -7,8 +7,6 @@ - - Nine Nines: Websocket @@ -66,8 +64,6 @@

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

@@ -76,7 +72,7 @@ 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 +

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.

@@ -96,14 +92,12 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
gun:ws_upgrade(ConnPid, "/websocket", [
-        {<<"sec-websocket-protocol">>, "mychat"}
+    {<<"sec-websocket-protocol">>, "mychat"}
 ]).
-

You can pass the Websocket options as part of the gun:open/{2,3} +

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. +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 @@ -118,19 +112,16 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 

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.
+    {gun_upgrade, ConnPid, StreamRef, [<<"websocket">>], Headers} ->
+        upgrade_success(ConnPid, StreamRef);
+    {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)
+    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.

@@ -139,8 +130,7 @@ owner of the connection will receive messages about it.

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

+

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

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.

+cleanly and will not attempt to reconnect afterwards.

@@ -175,15 +153,9 @@ by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> 
receive
-        {gun_ws, ConnPid, Frame} ->
-                handle_frame(ConnPid, Frame)
+    {gun_ws, ConnPid, StreamRef, Frame} ->
+        handle_frame(ConnPid, StreamRef, 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.

-- cgit v1.2.3