cowboy_req:parse_header(3)

NAME

cowboy_req:parse_header - Parse the given HTTP header

DESCRIPTION
    parse_header(Name, Req)          -> ParsedValue | Default
    parse_header(Name, Req, Default) -> ParsedValue | Default

    Name        :: binary()
    Req         :: cowboy_req:req()
    ParsedValue :: any()
    Default     :: any()

Parse the given HTTP header.

The header name must be given as a lowercase binary string. While header names are case insensitive, Cowboy requires them to be given as lowercase to function properly.

The type of the parsed value varies depending on the header. Similarly, the default value when calling cowboy_req:parse_header/2 differs depending on the header.

ARGUMENTS

Name
    Desired HTTP header name as a lowercase binary string.

Req
    The Req object.

Default
    Default value returned when the header is missing.

RETURN VALUE

The parsed header value varies depending on the header. When the header is missing, the default argument is returned.

HEADERS

The following snippets detail the types returned by the different headers. Unless mentioned otherwise, the default value when the header is missing will be undefined:

accept
    parse_header(<<"accept">>, Req)
        -> [{{Type, SubType, Params}, Quality, AcceptExt}]

    Type      :: binary()               %% case insensitive
    SubType   :: binary()               %% case insensitive
    Params    :: [{Key, Value}]
    Quality   :: 0..1000
    AcceptExt :: [Key | {Key, Value}]
    Key       :: binary()               %% case insensitive
    Value     :: binary()               %% case sensitive

accept-charset, accept-encoding and accept-language
    parse_header(Name, Req) -> [{Value, Quality}]

    Name    :: <<"accept-charset">>
             | <<"accept-encoding">>
             | <<"accept-language">>
    Value   :: binary()                 %% case insensitive
    Quality :: 0..1000

access-control-request-headers
    parse_header(<<"access-control-request-headers">>, Req)
        -> [Header]

    Header :: binary()   %% case insensitive

access-control-request-method
    parse_header(<<"access-control-request-method">>)
        -> Method

    Method :: binary()   %% case sensitive

authorization and proxy-authorization
    parse_header(<<"authorization">>, Req)
        -> {basic, Username :: binary(), Password :: binary()}
         | {bearer, Token :: binary()}
         | {digest, [{Key :: binary(), Value :: binary()}]}

content-encoding and content-language
    parse_header(Name, Req) -> [Value]

    Name  :: <<"content-encoding">>
           | <<"content-language">>
    Value :: binary()                 %% case insensitive

content-length
    parse_header(<<"content-length">>, Req) -> non_neg_integer()

When the content-length header is missing, 0 is returned.

content-type
    parse_header(<<"content-type">>, Req)
        -> {Type, SubType, Params}

    Type      :: binary()               %% case insensitive
    SubType   :: binary()               %% case insensitive
    Params    :: [{Key, Value}]
    Key       :: binary()               %% case insensitive
    Value     :: binary()               %% case sensitive;

Note that the value for the charset parameter is case insensitive and returned as a lowercase binary string.

cookie
    parse_header(<<"cookie">>, Req) -> [{Name, Value}]

    Name  :: binary()                   %% case sensitive
    Value :: binary()                   %% case sensitive

When the cookie header is missing, [] is returned.

While an empty cookie header is not valid, some clients do send it. Cowboy will in this case also return [].

expect
    parse_header(<<"expect">>, Req) -> continue

if-match and if-none-match
    parse_header(Name, Req)
        -> '*' | [{weak | strong, OpaqueTag}]

    Name      :: <<"if-match">>
               | <<"if-none-match">>
    OpaqueTag :: binary()               %% case sensitive

if-modified-since and if-unmodified-since
    parse_header(Name, Req) -> calendar:datetime()

max-forwards
    parse_header(<<"max-forwards">>, Req) -> non_neg_integer()

origin
    parse_header(<<"origin">>, Req)
        -> [{Scheme, Host, Port} | GUID]

    Scheme :: <<"http">> | <<"https">>
    Host   :: binary()                   %% case insensitive
    Port   :: 0..65535
    GUID   :: reference()

Cowboy generates a reference in place of a GUID when the URI uses an unsupported uri-scheme or is not an absolute URI.

    parse_header(<<"range">>, Req) -> {From, To} | Final

    From  :: non_neg_integer()
    To    :: non_neg_integer() | infinity
    Final :: neg_integer()

sec-websocket-extensions
    parse_header(<<"sec-websocket-extensions">>, Req)
        -> [{Extension, Params}]

    Extension :: binary()               %% case sensitive
    Params    :: [Key | {Key, Value}]
    Key       :: binary()               %% case sensitive
    Value     :: binary()               %% case sensitive

sec-websocket-protocol and upgrade
    parse_header(Name, Req) -> [Token]

    Name  :: <<"sec-websocket-protocol">>
           | <<"upgrade">>
    Token :: binary()                   %% case insensitive

trailer
    parse_header(Name, Req) -> [Header]

    Header :: binary()   %% case insensitive

x-forwarded-for
    parse_header(<<"x-forwarded-for">>, Req) -> [Token]

    Token :: binary()                   %% case sensitive

This function will crash when attempting to parse a header Cowboy does not currently understand.

CHANGELOG
    • 2.8: The function now parses access-control-request-headers, access-control-request-method, content-encoding, content-language, max-forwards, origin, proxy-authorization and trailer.
    • 2.0: Only the parsed header value is returned, it is no longer wrapped in a tuple.
    • 1.0: Function introduced.

EXAMPLES

Parse the accept header with a custom default value
    %% Accept everything when header is missing.
    Accept = cowboy_req:parse_header(<<"accept">>, Req,
        [{{ <<"*">>, <<"*">>, []}, 1000, []}]).

Parse the content-length header
    %% Default content-length is 0.
    Length = cowboy_req:header(<<"content-length">>, Req).

SEE ALSO

cowboy_req(3), cowboy_req:header(3), cowboy_req:headers(3)