Roadmap for Cowboy 2.0

ROADMAP.md

@@ -15,23 +15,101 @@ are expected to be bug fixes and documentation improvements.
 2.0 (R17 and R18)
 -----------------
 
- *  HTTP/2.0
+The main features that will be added to Cowboy 2.0 are support
+for HTTP/2.0 and Websocket permessage deflate compression.
 
- *  Websocket permessage deflate compression
+A number of backward incompatible changes are planned. These
+changes are individually small, but together should result
+in a large improvement in usability.
 
- *  Better cowboy_req usability
+### cowboy_req
 
-    The number one usability concern with Cowboy today is
-    the need to keep the Req object. Most functions in
-    cowboy_req don't actually modify it and probably never
-    will. This change will make sure that only the required
-    function return a new Req.
+The interface of `cowboy_req` will be largely changed. The
+number one complaint about Cowboy today is that you have
+to keep track of the Req whenever you do anything. The new
+interface will minimize that.
 
-    At the same time, some of the functions that cache their
-    results will stop to do so. This will save memory and
-    allow us to not modify the Req.
+All functions will return a single term, excluding the body
+reading functions `body/{1,2}`, `body_qs/{1,2}`, `part/{1,2}`,
+`part_body/{1,2}`.
 
- *  Start experimenting with maps.
+%% @todo yeah qs and cookies too probably???
+
+Of the functions returning a single term, some of them will
+return a Req object. This includes the functions that already
+return Req: `compact/1`, `delete_resp_header/2`, `set_meta/3`,
+`set_resp_body/2`, `set_resp_body_fun/{2,3}`, `set_resp_cookie/4`,
+`set_resp_header/3`, and adds the `chunked_reply/{2,3}` and
+`reply/{2,3,4}` functions to the list.
+
+Of note is that this will allow chaining all the response
+functions if that's what you fancy.
+
+The `parse_header/{2,3}` function will now only return the
+parsed header value, and crash on error. It will also not
+cache the parsed value anymore, except for headers that Cowboy
+requires, like the connection header.
+
+### init/terminate unification
+
+The first argument of the `init/3` is too rarely used. It
+will be removed.
+
+The return value of the `init/2` function will become
+`{http, Req, State} | {loop, Req, State} | {Module, Req, State}`
+with `Module` being `cowboy_rest`, `cowboy_websocket` or a
+user provided module.
+
+The `rest_init` and `websocket_init` callbacks will be removed
+as they become unnecessary with the new `init/2` interface.
+
+Similarly, the `rest_terminate` and `websocket_terminate`
+callbacks will be removed in favor of a unified `terminate/3`.
+
+The `terminate/3` callback will become optional.
+
+### Hooks
+
+The `onrequest` hook will be removed. It can easily be replaced
+by a middleware.
+
+The interface of the `onresponse` hook will change. There has
+been a number of issues and added complexity with the current
+interface that warrant fixing. The main problem is that the
+hook may be used to change the reply, by calling the reply
+function again, forcing us to be careful not to reprocess
+everything again.
+
+To fix that, we will cut the reply mechanism in two steps,
+one that is basically some preprocessing of the response
+header to follow the protocol requirements, and then the
+actual response. The `onresponse` hook will fit in the
+middle, being called from the first step and calling the
+second step itself.
+
+If a body streaming function is provided, the hook will
+also receive it (unlike today). It will not be able to
+inspect its contents however.
+
+This should greatly simplify the code and allow users to
+do any operation they wish.
+
+### Low-level interface documented
+
+A special chapter of the manual will document a low-level
+interface that may be used in middlewares or hooks (but
+nowhere else). This includes the Req access and update
+functions and the new response function described above.
+
+### REST
+
+The `known_content_type` callback has no purpose, so it
+is going to be removed.
+
+The documentation for all REST callbacks will be updated
+to describe whether they can have side effects. This will
+allows us to build introspection tools on top of a working
+REST API.
 
 Under consideration
 -------------------