Replace gun:ws_send/2 with gun:ws_send/3

Switching from /2 to /3 should be easy enough.

Also update the documentation about HTTP/2 Websocket support.

4 files changed, 30 insertions, 26 deletions

diff --git a/doc/src/guide/migrating_from_1.3.asciidoc b/doc/src/guide/migrating_from_1.3.asciidoc
index aa7d26b..0afd19e 100644
--- a/doc/src/guide/migrating_from_1.3.asciidoc
+++ b/doc/src/guide/migrating_from_1.3.asciidoc
@@ -104,7 +104,7 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
   example.
 
 * It is now possible to send many Websocket frames in
-  a single `gun:ws_send/2` call.
+  a single `gun:ws_send/3` call.
 
 * Gun may now send Websocket ping frames automatically
   at intervals determined by the `keepalive` option. It
@@ -186,6 +186,10 @@ Gun 2.0 requires Erlang/OTP 22.0 or greater.
   cleaner separation between requests that are followed by
   a body and those that don't.
 
+* The function `gun:ws_send/2` has been replaced with the
+  function `gun:ws_send/3`. The stream reference for the
+  corresponding Websocket upgrade request must now be given.
+
 === Messages added
 
 * The `gun_tunnel_up` message has been added.
diff --git a/doc/src/guide/protocols.asciidoc b/doc/src/guide/protocols.asciidoc
index d2529e3..cd6de2c 100644
--- a/doc/src/guide/protocols.asciidoc
+++ b/doc/src/guide/protocols.asciidoc
@@ -65,10 +65,6 @@ cancellation mechanism which allows Gun to inform the
 server to stop sending a response for this particular
 request, saving resources.
 
-It is not currently possible to upgrade an HTTP/2 connection
-to Websocket. Support for this will be added in a future
-release.
-
 === Websocket
 
 Websocket is a binary protocol built on top of HTTP that
@@ -76,12 +72,9 @@ allows asynchronous concurrent communication between the
 client and the server. A Websocket server can push data to
 the client at any time.
 
-Websocket is only available as a connection upgrade over
-an HTTP/1.1 connection.
-
-Once the Websocket connection is established, the only
-operation available on this connection is sending Websocket
-frames using `gun:ws_send/2`.
+Once the Websocket connection is established over an HTTP/1.1
+connection, the only operation available on this connection
+is sending Websocket frames using `gun:ws_send/3`.
 
 Gun will send a `gun_ws` message for every frame received.
 
@@ -108,7 +101,7 @@ current protocol.
 | await_body | yes      | yes    | no
 | flush      | yes      | yes    | no
 | cancel     | yes      | yes    | no
-| ws_upgrade | yes      | no     | no
+| ws_upgrade | yes      | yes    | no
 | ws_send    | no       | no     | yes
 |===
 
@@ -122,6 +115,6 @@ current protocol.
 | gun_data              | yes      | yes    | no
 | gun_trailers          | yes      | yes    | no
 | gun_error             | yes      | yes    | yes
-| gun_upgrade           | yes      | no     | no
+| gun_upgrade           | yes      | yes    | no
 | gun_ws                | no       | no     | yes
 |===
diff --git a/doc/src/guide/websocket.asciidoc b/doc/src/guide/websocket.asciidoc
index 287b3f7..ba06e2c 100644
--- a/doc/src/guide/websocket.asciidoc
+++ b/doc/src/guide/websocket.asciidoc
@@ -49,7 +49,7 @@ undocumented and must be set to `gun_ws_h`.
 .Upgrade to Websocket with protocol negotiation
 [source,erlang]
 ----
-gun:ws_upgrade(ConnPid, "/websocket", []
+StreamRef = gun:ws_upgrade(ConnPid, "/websocket", []
     #{protocols => [{<<"xmpp">>, gun_ws_h}]}).
 ----
 
@@ -88,18 +88,18 @@ 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.
+Use `gun:ws_send/3` to send messages to the server.
 
 .Send a text frame
 [source,erlang]
 ----
-gun:ws_send(ConnPid, {text, "Hello!"}).
+gun:ws_send(ConnPid, StreamRef, {text, "Hello!"}).
 ----
 
 .Send a text frame, a binary frame and then close the connection
 [source,erlang]
 ----
-gun:ws_send(ConnPid, [
+gun:ws_send(ConnPid, StreamRef, [
     {text, "Hello!"},
     {binary, BinaryValue},
     close
diff --git a/doc/src/manual/gun.ws_send.asciidoc b/doc/src/manual/gun.ws_send.asciidoc
index b39f3f0..224472e 100644
--- a/doc/src/manual/gun.ws_send.asciidoc
+++ b/doc/src/manual/gun.ws_send.asciidoc
@@ -8,13 +8,14 @@ gun:ws_send - Send Websocket frames
 
 [source,erlang]
 ----
-ws_send(ConnPid, Frames) -> ok
-
-ConnPid :: pid()
-Frames  :: Frame | [Frame]
-Frame   :: close | ping | pong
-         | {text | binary | close | ping | pong, iodata()}
-         | {close, non_neg_integer(), iodata()}
+ws_send(ConnPid, StreamRef, Frames) -> ok
+
+ConnPid   :: pid()
+StreamRef :: gun:stream_ref()
+Frames    :: Frame | [Frame]
+Frame     :: close | ping | pong
+           | {text | binary | close | ping | pong, iodata()}
+           | {close, non_neg_integer(), iodata()}
 ----
 
 Send Websocket frames.
@@ -28,6 +29,10 @@ ConnPid::
 
 The pid of the Gun connection process.
 
+StreamRef::
+
+Identifier of the stream that was upgraded to Websocket.
+
 Frames::
 
 One or more Websocket frame(s).
@@ -38,6 +43,8 @@ The atom `ok` is returned.
 
 == Changelog
 
+* *2.0*: The mandatory `StreamRef` argument was added.
+* *2.0*: It is now possible to send multiple frames at once.
 * *1.0*: Function introduced.
 
 == Examples
@@ -45,13 +52,13 @@ The atom `ok` is returned.
 .Send a single frame
 [source,erlang]
 ----
-gun:ws_send(ConnPid, {text, <<"Hello world!">>}).
+gun:ws_send(ConnPid, StreamRef, {text, <<"Hello world!">>}).
 ----
 
 .Send many frames including a close frame
 [source,erlang]
 ----
-gun:ws_send(ConnPid, [
+gun:ws_send(ConnPid, StreamRef, [
     {text, <<"See you later, world!">>},
     close
 ]).