Make Cowboy CORS friendly

[manifest]

Maybe we could make Cowboy a bit more CORS friendly?
By now, to enable CORS we should work with raw headers, copy-pasting code like this from one header to another:

options(Req, State) ->
  Req1 = cowboy_req:set_resp_header(<<"access-control-max-age">>, <<"1728000">>, Req0),
  Req2 = cowboy_req:set_resp_header(<<"access-control-allow-methods">>, <<"HEAD, GET, POST">>, Req1),
  Req3 = cowboy_req:set_resp_header(<<"access-control-allow-headers">>, <<"content-type, authorization">>, Req2),
  Req4 = cowboy_req:set_resp_header(<<"access-control-allow-origin">>, <<$*>>, Req3),
  {ok, Req, State}.

In this way we do not actually care about allowed header's value types. For instance, "access-control-allow-methods" and "access-control-allow-headers" should only accept a list of binaries, while only a numeric value makes sense for the "access-control-max-age" header, "*" origin cannot be used for a resource that supports credentials. Ignoring this information leads to misspelling errors, breaking CORS responses and isn't flexible for working with.

My proposal is to add two new functions (set_cors_headers/2 and set_cors_preflight_headers/2) to the cowboy_req module extending functionality of set_resp_header/3.

-type cors_header()
  :: {origin, binary() | list(binary())}.

-type cors_preflight_header()
  :: {age, max | non_neg_integer()}
   | {methods, list(binary())}
   | {headers, list(binary())}
   | cors_header().

-spec set_cors_headers(list(cors_header()), Req) -> Req when Req :: cowboy_req:req().
-spec set_cors_preflight_headers(list(cors_preflight_header()), Req) -> Req when Req :: cowboy_req:req().

In my projects, I'm using this simple syntax sugar in REST handlers:

allowed_methods(Req, State) ->
  Req2 = cowboy_req:set_cors_headers([{origin, <<$*>>}], Req),
  {[<<"HEAD">>, <<"GET">>, <<"POST">>, <<"OPTIONS">>], Req2, State}.

options(Req, State) ->
  Headers =
    [ {age, max},
      {origin, <<$*>>},
      {methods, [<<"HEAD">>, <<"GET">>, <<"POST">>]},
      {headers, [<<"content-type">>, <<"authorization">>]} ],
  {ok, cowboy_req:set_cors_preflight_headers(Headers, Req), State}.

It's also possible to use those functions in a middleware:

execute(Req, Env) ->
  case cowboy_req:method(Req) of
    <<"OPTIONS">> ->
      Headers =
        [ {age, max},
          {origin, <<$*>>},
          {methods, [<<"HEAD">>, <<"GET">>, <<"POST">>]},
          {headers, [<<"content-type">>, <<"authorization">>]} ],
      {ok, cowboy_req:set_cors_preflight_headers(Headers, Req), Env};
    _ ->
      {ok, cowboy_req:set_cors_headers([{origin, <<$*>>}], Req), Env}
  end.

I believe those functions could make Cowboy yet more friendly and useful tool and would love to make a pull request, if it's ok with Cowboy's philosophy.

[manifest]

I've just made a pull request for this feature. I've also changed type descriptions a bit:

-type cors_allowed_origins() :: [binary()] | binary().
-type cors_allowed_methods() :: [binary()].
-type cors_allowed_headers() :: [binary()].
-type cors_max_age() :: non_neg_integer() | max.
-type cors_header() :: {origins, cors_allowed_origins()}
  | {exposed_headers, cors_allowed_headers()}
  | {credentials, boolean()}.
-type cors_preflight_header() :: {origins, cors_allowed_origins()}
  | {methods, cors_allowed_methods()}
  | {headers, cors_allowed_headers()}
  | {credentials, boolean()}
  | {max_age, max | non_neg_integer()}.

[manifest]

From the server-side perspective, we need to parse just "Origin", "Access-Control-Request-Method" and "Access-Control-Expose-Headers" headers. Other CORS headers are produced by the server. So, it looks like we should create functions:

access_control_allow_credentials/1
access_control_allow_headers/1
access_control_allow_methods/1
access_control_allow_origin/1
access_control_expose_headers/1
access_control_max_age/1

in the module cow_http_hd along with (or instead of) these ones:

% @todo -export([parse_access_control_allow_credentials/1]). CORS
% @todo -export([parse_access_control_allow_headers/1]). CORS
% @todo -export([parse_access_control_allow_methods/1]). CORS
% @todo -export([parse_access_control_allow_origin/1]). CORS
% @todo -export([parse_access_control_expose_headers/1]). CORS
% @todo -export([parse_access_control_max_age/1]). CORS

In this way, we would have all the parsing/producing headers code within the cow_http_hd module. Is it a good idea?

[essen]

Cowlib is both for clients and servers. I understand your concerns are only for the server, but if you'd like to also contribute client parsing code, be my guest. :-) Though AFAIK this wouldn't usually be useful to plain HTTP clients so no worries there.

Otherwise, the names sound correct, if they take Erlang representation and return an iodata() for the header value.

[essen]

My notes on CORS so far:

• access-control-allow-origin: either "*" or match the configured list against the "origin" header and send back the "origin" header if it matches, disabling CORS otherwise. REST should have a callback for providing the list of allowed origins; default to [] is fine (disallow CORS entirely)
• access-control-allow-credentials: for REST should be "true" only if is_authorized/2 is defined
• access-control-expose-headers: REST should have a callback, it's fairly resource specific; default to []
• access-control-max-age: REST should have a callback; default to 30 minutes is fine
• access-control-allow-methods: same as allowed_methods/2, but might make sense to have a callback (wait for a use case)
• access-control-allow-headers: REST should have a callback; default to same as access-control-request-header

I will add more notes as I go through your PRs this week-end.