From 836342abb86b3ff15d1c8319a455d776f7027a87 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= <essen@ninenines.eu>
Date: Wed, 1 Nov 2017 16:27:26 +0000
Subject: 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.
---
 doc/src/manual/cowboy_rest.asciidoc | 13 ++++++++++++-
 1 file changed, 12 insertions(+), 1 deletion(-)

(limited to 'doc/src/manual/cowboy_rest.asciidoc')

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.
-- 
cgit v1.2.3

