From 4a58077d5162325fa5723690e58e7364adbcb18c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Thu, 12 Nov 2020 14:00:41 +0100 Subject: 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. --- doc/src/guide/migrating_from_1.3.asciidoc | 6 +++++- doc/src/guide/protocols.asciidoc | 17 +++++------------ doc/src/guide/websocket.asciidoc | 8 ++++---- doc/src/manual/gun.ws_send.asciidoc | 25 ++++++++++++++++--------- 4 files changed, 30 insertions(+), 26 deletions(-) (limited to 'doc') 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 ]). -- cgit v1.2.3