Uncertainities around constraints

[fififionek]

Issues

1. Only the forward mode appears to have ever been used throughout cowboy. The support for reverse and format_error seems to be lacking
2. Matching of repeating parameters seems to not be supported
3. Documentation contradicts implementation on several places

Discussion

1. Bundling of all the functionality of a parameter constraint into a single function using forward, reverse and format_error modes is a cool idea. But it seems it was never decided, how the reverse and format_error modes should be used
   • functions in cowboy_constraints module implementing the modes are not documented. My natural expectation would be the constraint lists used in validate/2 and reverse/2 should be identical so the user would not need to worry which of the two modes is used. But if the constrains do subsequent transformations (eg. first parses a datetime and second transforms the datetime to age) the reverse/2 has to be called with reverted list of constraints
   • to be able to use the format_error mode, you need to catch an exception from match function (cowboy_req:match_qs/2, cowboy_req:match_cookies/2 or cowboy_req:read_and_match_urlencoded_body/2) and extract the constraint and its arguments from an undocumented structure
2. The user guide mentions the match functions support multiple parameters of the same name. But it is never explicitly mentioned how would the constraints work in this situation. Only the last paragraph in the guide mentions key=1&key=2 query would result in #{key := [1, 2]} which would imply int constraint was used on single values. It also seems natural to me to use the constraints on every value separately and only combine them to the list after. Nevertheless the implementation passes a list of binaries of all the values to the constraints. So separate constraints have to be created for keys allowing for multiple values
3. In addition to contradictions mentioned in previous points
   • the user guide promises (or at least hints to it) some complex functionality around constraints. I think some features should be marked experimental or incomplete. The natural place for this would be cowboy_constraints module documentation. Unfortunately this page is obsolete (probably more than 5 years old, when the last big change happened). It documets int/2 and nonempty/2 as exports which are actually internals, while the actual exports validate/2, reverse/2 and format_error/1 are not mentioned

[essen]

1. I'll need to review all this in details but it's possible that it's missing a few things for proper use within Cowboy.
2. That's probably just a documentation edit mistake as the key=1&key=2 line is mentioned twice in that section. It's only there to say that unlike PHP we don't care about [].
3. The exports are really just the list of built-in constraints, always been. Not sure more is needed in the context of Cowboy.

The reverse stuff is mostly there for HATEOAS stuff which I've not finished experimenting with (ran into other missing stuff and implemented them such as uri templates). It's a slow process.