path: root/doc
diff options
authorLoïc Hoguin <[email protected]>2019-10-10 11:33:35 +0200
committerLoïc Hoguin <[email protected]>2019-10-10 11:33:35 +0200
commitd52e84bdd97b93d7d9cea827de57bd4a0edea9a8 (patch)
tree48958da1fc3bd2b2e3666fc9ee2b545099116d47 /doc
parentcc54c207e35f3ab7a2dfc105eef39fe7d3bf1633 (diff)
Add shutdown_reason Websocket command
This allows changing the normal exit reason of Websocket processes, providing a way to signal other processes of why the exit occurred.
Diffstat (limited to 'doc')
2 files changed, 19 insertions, 2 deletions
diff --git a/doc/src/guide/migrating_from_2.6.asciidoc b/doc/src/guide/migrating_from_2.6.asciidoc
index a582ee4..91d1588 100644
--- a/doc/src/guide/migrating_from_2.6.asciidoc
+++ b/doc/src/guide/migrating_from_2.6.asciidoc
@@ -81,6 +81,12 @@ Cowboy 2.7 requires Erlang/OTP 20.0 or greater.
is now considered stable and has been documented.
The old interface is now deprecated.
+* A new Websocket handler command `shutdown_reason`
+ can be used to change the normal exit reason of
+ Websocket processes. By default `normal` is used;
+ with this command the exit reason can be changed
+ to `{shutdown, ShutdownReason}`.
* The experimental stream handlers `cowboy_metrics_h`
and `cowboy_tracer_h` are now considered stable and
have been documented.
diff --git a/doc/src/manual/cowboy_websocket.asciidoc b/doc/src/manual/cowboy_websocket.asciidoc
index 440a0e8..59d412d 100644
--- a/doc/src/manual/cowboy_websocket.asciidoc
+++ b/doc/src/manual/cowboy_websocket.asciidoc
@@ -141,6 +141,7 @@ commands() :: [Command]
Command :: {active, boolean()}
| {deflate, boolean()}
| {set_options, #{idle_timeout => timeout()}}
+ | {shutdown_reason, any()}
| Frame :: cow_ws:frame()
@@ -163,6 +164,15 @@ set_options::
Set Websocket options. Currently only the option `idle_timeout`
may be updated from a Websocket handler.
+Change the shutdown reason. The Websocket process will exit
+with reason `normal` by default. This command can be used to
+exit with reason `{shutdown, ShutdownReason}` under normal
+conditions. This command has no effect when the Websocket
+process exits abnormally, for example following a crash in a
+handler callback.
Send the corresponding Websocket frame.
@@ -266,8 +276,9 @@ normal circumstances if necessary.
== Changelog
-* *2.7*: The commands based interface has been added. The old
- interface is now deprecated.
+* *2.7*: The commands based interface has been documented.
+ The old interface is now deprecated.
+* *2.7*: The command `shutdown_reason` was introduced.
* *2.7*: The option `validate_utf8` has been added.
* *2.6*: Deflate options can now be configured via `deflate_opts`.
* *2.0*: The Req object is no longer passed to Websocket callbacks.