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.

2 files changed, 15 insertions, 17 deletions

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);
diff --git a/doc/src/manual/gun.asciidoc b/doc/src/manual/gun.asciidoc
index 7c12fc3..baaadcf 100644
--- a/doc/src/manual/gun.asciidoc
+++ b/doc/src/manual/gun.asciidoc
@@ -194,22 +194,12 @@ Reason = any():: Error reason.
 
 General error.
 
-=== {gun_ws_upgrade, ConnPid, ok}
+=== {gun_ws_upgrade, ConnPid, ok, Headers}
 
 ConnPid = pid():: The pid of the Gun connection process.
-
-Successful upgrade to the Websocket protocol.
-
-@todo Yeah we need the headers.
-
-=== {gun_ws_upgrade, ConnPid, error, IsFin, Status, Headers}
-
-ConnPid = pid():: The pid of the Gun connection process.
-IsFin = fin | nofin:: Whether this message terminates the response.
-Status = binary():: Status line for the response.
 Headers = [{binary(), binary()}]:: Headers sent with the response.
 
-Failed upgrade to the Websocket protocol.
+Successful upgrade to the Websocket protocol.
 
 === {gun_ws, ConnPid, Frame}