From e39252ae5048156ac33999ce9bb07212798b6b80 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 26 Sep 2019 14:05:08 +0200 Subject: Add Gun 2.0-pre documentation But don't propagate via RSS. --- docs/en/gun/2.0/guide/websocket/index.html | 263 +++++++++++++++++++++++++++++ 1 file changed, 263 insertions(+) create mode 100644 docs/en/gun/2.0/guide/websocket/index.html (limited to 'docs/en/gun/2.0/guide/websocket') diff --git a/docs/en/gun/2.0/guide/websocket/index.html b/docs/en/gun/2.0/guide/websocket/index.html new file mode 100644 index 00000000..88694744 --- /dev/null +++ b/docs/en/gun/2.0/guide/websocket/index.html @@ -0,0 +1,263 @@ + + + + + + + + + + Nine Nines: Websocket + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

Websocket

+ +

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

+ +

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

+
Upgrade to Websocket using HTTP authentication
+
+
gun:ws_upgrade(ConnPid, "/websocket", [
+    {<<"authorization">>, "Basic dXNlcm5hbWU6cGFzc3dvcmQ="}
+]).
+
+

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.

+

Gun can negotiate the protocol to be used for the Websocket connection. The protocols option can be given with a list of protocols accepted and the corresponding handler module. Note that the interface for handler modules is currently undocumented and must be set to gun_ws_h.

+
Upgrade to Websocket with protocol negotiation
+
+
gun:ws_upgrade(ConnPid, "/websocket", []
+    #{protocols => [{<<"xmpp">>, gun_ws_h}]}).
+
+

The upgrade will fail if the server cannot satisfy the protocol negotiation.

+

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:

+
+
receive
+    {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)
+end.
+
+

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 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 but may attempt to reconnect afterwards depending on the retry configuration.

+

Receiving data

+

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

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

+ Gun + 2.0 + + User Guide +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via BountySource. These funds are used to cover the recurring expenses like dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + -- cgit v1.2.3