diff options
| author | Loïc Hoguin <essen@ninenines.eu> | 2017-11-01 16:27:26 +0000 |
|---|---|---|
| committer | Loïc Hoguin <essen@ninenines.eu> | 2017-11-01 16:27:26 +0000 |
| commit | 836342abb86b3ff15d1c8319a455d776f7027a87 (patch) | |
| tree | 9d5fb1277006fac53920e8df80c144c7b45171d3 /doc | |
| parent | 5e88a9b394a2ae966ba95efadbf1cc24d060b457 (diff) | |
| download | cowboy-836342abb86b3ff15d1c8319a455d776f7027a87.tar.gz cowboy-836342abb86b3ff15d1c8319a455d776f7027a87.tar.bz2 cowboy-836342abb86b3ff15d1c8319a455d776f7027a87.zip | |
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')
| -rw-r--r-- | doc/src/guide/rest_handlers.asciidoc | 8 | ||||
| -rw-r--r-- | doc/src/manual/cowboy_rest.asciidoc | 13 |
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. |