From f618634bf648124c9562aaf49ee460be9ef71ae7 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Fri, 10 Apr 2015 17:34:26 +0300
Subject: Add headers to gun_ws_upgrade message

Also improves the code and documentation about this message.
It was incorrectly specified that a gun_ws_upgrade message
could be sent on error; instead a gun_response is sent.
---
 doc/src/guide/websocket.asciidoc | 18 +++++++++++++-----
 1 file changed, 13 insertions(+), 5 deletions(-)

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

diff --git a/doc/src/guide/websocket.asciidoc b/doc/src/guide/websocket.asciidoc
index 83a8384..35580ca 100644
--- a/doc/src/guide/websocket.asciidoc
+++ b/doc/src/guide/websocket.asciidoc
@@ -40,17 +40,25 @@ 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}`.
 
-The success or failure of this operation will be sent as a
-message.
+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.
 
-@todo hmm we want the headers to be sent in the gun_ws_upgrade ok message too
+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:
 
 [source,erlang]
 receive
-	{gun_ws_upgrade, ConnPid, ok} ->
+	{gun_ws_upgrade, ConnPid, ok, Headers} ->
 		upgrade_success(ConnPid);
-	{gun_ws_upgrade, ConnPid, error, IsFin, Status, Headers} ->
+	{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);
-- 
cgit v1.2.3

