path: root/doc
diff options
authorLoïc Hoguin <[email protected]>2017-11-01 16:27:26 +0000
committerLoïc Hoguin <[email protected]>2017-11-01 16:27:26 +0000
commit836342abb86b3ff15d1c8319a455d776f7027a87 (patch)
tree9d5fb1277006fac53920e8df80c144c7b45171d3 /doc
parent5e88a9b394a2ae966ba95efadbf1cc24d060b457 (diff)
Add {switch_handler, Module} return value to cowboy_rest
Also {switch_handler, Module, Opts}. Allows switching to a different handler type. This is particularly useful for processing most of the request with cowboy_rest and then streaming the response body using cowboy_loop.
Diffstat (limited to 'doc')
2 files changed, 18 insertions, 3 deletions
diff --git a/doc/src/guide/rest_handlers.asciidoc b/doc/src/guide/rest_handlers.asciidoc
index c69f02b..dab5bea 100644
--- a/doc/src/guide/rest_handlers.asciidoc
+++ b/doc/src/guide/rest_handlers.asciidoc
@@ -43,8 +43,12 @@ you need.
All callbacks take two arguments, the Req object and the State,
and return a three-element tuple of the form `{Value, Req, State}`.
-All callbacks can also return `{stop, Req, State}` to stop execution
-of the request.
+Nearly all callbacks can also return `{stop, Req, State}` to
+stop execution of the request, and
+`{{switch_handler, Module}, Req, State}` or
+`{{switch_handler, Module, Opts}, Req, State}` to switch to
+a different handler type. The exceptions are `expires`
+`generate_etag`, `last_modified` and `variances`.
The following table summarizes the callbacks and their default values.
If the callback isn't defined, then the default value will be used.
diff --git a/doc/src/manual/cowboy_rest.asciidoc b/doc/src/manual/cowboy_rest.asciidoc
index 2fabdce..db048e1 100644
--- a/doc/src/manual/cowboy_rest.asciidoc
+++ b/doc/src/manual/cowboy_rest.asciidoc
@@ -25,11 +25,15 @@ init(Req, State)
Callback(Req, State)
-> {Result, Req, State}
| {stop, Req, State}
+ | {{switch_handler, Module}, Req, State}
+ | {{switch_handler, Module, Opts}, Req, State}
terminate(Reason, Req, State) -> ok %% optional
Req :: cowboy_req:req()
State :: any()
+Module :: module()
+Opts :: any()
Reason :: normal
| {crash, error | exit | throw, any()}
@@ -51,7 +55,14 @@ implemented. They otherwise all follow the same interface.
The `stop` tuple can be returned to stop REST processing.
If no response was sent before then, Cowboy will send a
-'204 No Content'.
+'204 No Content'. The `stop` tuple can be returned from
+any callback, excluding `expires`, `generate_etag`,
+`last_modified` and `variances`.
+A `switch_handler` tuple can be returned from these same
+callbacks to stop REST processing and switch to a different
+handler type. This is very useful to, for example, to stream
+the response body.
The optional `terminate/3` callback will ultimately be called
with the reason for the termination of the handler.