From 5a0c8f31c4ae1885fd05f627f89c088bcbe2b4d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 28 Mar 2025 15:18:59 +0100
Subject: Recommend disabling automatic reconnect for Websocket

---
 doc/src/guide/websocket.asciidoc | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'doc/src/guide/websocket.asciidoc')

diff --git a/doc/src/guide/websocket.asciidoc b/doc/src/guide/websocket.asciidoc
index ba06e2c..31b014b 100644
--- a/doc/src/guide/websocket.asciidoc
+++ b/doc/src/guide/websocket.asciidoc
@@ -122,3 +122,20 @@ receive
         handle_frame(ConnPid, StreamRef, Frame)
 end.
 ----
+
+=== Automatic reconnect gotchas
+
+It is recommended to disable automatic reconnect when
+Websocket is used because Gun cannot automatically upgrade
+to Websocket on reconnect, and so an undetected disconnect
+may lead to many error messages from Gun.
+
+This can be done by setting the `retry` option to `0`
+when opening a connection:
+
+[source,erlang]
+----
+{ok, ConnPid} = gun:open("localhost", 12345, #{
+    retry ⇒ 0
+}).
+----
-- 
cgit v1.2.3

