From d9a970be90d0105af215531d74809878f9c21338 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Tue, 24 Sep 2019 19:18:35 +0200
Subject: Add auto-ping to Websocket and a silence_pings option

The auto-ping will at regular interval send a ping frame.

The silence_pings option defaults to true. It can be set
to false when the user needs to receive ping/pong frames.
---
 doc/src/guide/websocket.asciidoc |  8 --------
 doc/src/manual/gun.asciidoc      | 15 ++++++++++++++-
 doc/src/manual/gun_ws.asciidoc   |  5 ++++-
 3 files changed, 18 insertions(+), 10 deletions(-)

(limited to 'doc')

diff --git a/doc/src/guide/websocket.asciidoc b/doc/src/guide/websocket.asciidoc
index 662b9ea..287b3f7 100644
--- a/doc/src/guide/websocket.asciidoc
+++ b/doc/src/guide/websocket.asciidoc
@@ -122,11 +122,3 @@ receive
         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.
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 7b54666..478d40b 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -459,7 +459,9 @@ ws_opts() :: #{
     closing_timeout => timeout(),
     compress        => boolean(),
     flow            => pos_integer(),
-    protocols       => [{binary(), module()}]
+    keepalive       => timeout(),
+    protocols       => [{binary(), module()}],
+    silence_pings   => boolean()
 }
 ----
 
@@ -484,6 +486,10 @@ flow - see below::
 The initial flow control value for the Websocket connection.
 By default flow control is disabled.
 
+keepalive (5000)::
+
+Time between pings in milliseconds.
+
 protocols ([])::
 
 A non-empty list enables Websocket protocol negotiation. The
@@ -491,6 +497,12 @@ list of protocols will be sent in the sec-websocket-protocol
 request header. The handler module interface is currently
 undocumented and must be set to `gun_ws_h`.
 
+silence_pings (true)::
+
+Whether the ping and pong frames should be sent to the user.
+In all cases Gun will automatically send a pong frame back
+when receiving a ping.
+
 // @todo Document default_protocol and user_opts.
 
 == Changelog
@@ -517,6 +529,7 @@ undocumented and must be set to `gun_ws_h`.
 * *2.0*: Function `gun:headers/4,5` introduced.
 * *2.0*: The `keepalive` option is now set to `infinity` by
          default for the HTTP/1.1 protocol, disabling it.
+* *2.0*: Websocket options `keepalive` and `silence_pings` introduced.
 * *1.3*: Add the CONNECT destination's `protocols` option and
          deprecate the previously introduced `protocol` option.
 * *1.2*: Introduce the type `connect_destination()`.
diff --git a/doc/src/manual/gun_ws.asciidoc b/doc/src/manual/gun_ws.asciidoc
index 127f2a2..374b0b3 100644
--- a/doc/src/manual/gun_ws.asciidoc
+++ b/doc/src/manual/gun_ws.asciidoc
@@ -12,9 +12,10 @@ gun_ws - Websocket frame
 
 ConnPid   :: pid()
 StreamRef :: reference()
-Frame     :: close
+Frame     :: close | ping | pong
            | {text | binary | close, binary()}
            | {close, non_neg_integer(), binary()}
+           | {ping | pong, binary()}
 ----
 
 Websocket frame.
@@ -41,6 +42,8 @@ The Websocket frame in question.
 
 == Changelog
 
+* *2.0*: Depending on the option `silence_pings`, ping and
+         pong frames may be sent as well.
 * *1.0*: Message introduced.
 
 == Examples
-- 
cgit v1.2.3