From 6fd2cadb1d3f80ba1776d361f017725fad7d1fea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Sat, 4 Oct 2014 13:26:40 +0300 Subject: Update ROADMAP --- ROADMAP.md | 58 ++++++++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 52 insertions(+), 6 deletions(-) (limited to 'ROADMAP.md') diff --git a/ROADMAP.md b/ROADMAP.md index 9251bad..530f6a0 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -20,6 +20,51 @@ A number of backward incompatible changes are planned. These changes are individually small, but together should result in a large improvement in usability. +### New cowboy_req function + +A convenience function will be added to more easily process +HTML forms that were sent using POST. These forms have two +main ways of being submitted: as a form urlencoded format, +or as multipart. The latter case may also be used to submit +files, therefore we also need a way to handle this. We also +need to take into account that we are reading from the socket +and can't take as much a shortcut as with `match_qs/2`. + +The function will work similarly to other body reading functions, +in that it may require more than one call to obtain everything. +In this case there would be two return values: the `ok` return +with the map filled with key/value pairs, ending the body reading; +and the `file` return that informs the caller that a file has been +provided and the caller must handle it. If the caller calls the +function again without doing anything, the part is just skipped, +like what `part/1` is doing. If a file is the last input from +the form then a subsequent call will return an `ok` return with +an empty map. + +The interface would look as follow: + +``` +match_body(Fields, Req) -> match_body(Fields, Req, []) +match_body(Fields, Req, Opts) + -> {ok, Map, Req} + | {file, FieldName, Filename, CType, CTransferEncoding, Map, Req} + when Req::req() +``` + +It would be up to the caller to decide what to do with the +maps returned. Fields are in order so the map returned may +be empty if the form starts with a file, or may only +contain the values before the file input if this one is +in the middle of the form. It is of course possible to +merge all maps returned into one though that should not +be needed very often. + +It is also possible to switch from this function to only +multipart functions if the function returns a `file` tuple, +as this function is a higher level interface that simply +calls the multipart functions when the request body is +in multipart format. + ### Hooks The interface of the `onresponse` hook will change. There has @@ -50,6 +95,13 @@ 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. +### Loop + +We probably want to send something other than 500 when the +max data read value has been reached. This happens when the +client is misbehaving and is not a server error, but rather +a safeguard. + ### REST The documentation for all REST callbacks will be updated @@ -58,9 +110,3 @@ allows us to build introspection tools on top of a working REST API. Range support will be added. - -Under consideration -------------------- - - * Convenience API for extracting query string and body - information, similar to PHP's $_GET, $_POST and $_FILES -- cgit v1.2.3