From 849fab7227a2fd1ff5fa4d603ba89037e1c462b4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Lo=C3=AFc=20Hoguin?= Date: Tue, 26 May 2020 09:54:54 +0200 Subject: Cowboy 2.8.0 --- .../2.8/manual/cowboy_req.parse_header/index.html | 426 +++++++++++++++++++++ 1 file changed, 426 insertions(+) create mode 100644 docs/en/cowboy/2.8/manual/cowboy_req.parse_header/index.html (limited to 'docs/en/cowboy/2.8/manual/cowboy_req.parse_header/index.html') diff --git a/docs/en/cowboy/2.8/manual/cowboy_req.parse_header/index.html b/docs/en/cowboy/2.8/manual/cowboy_req.parse_header/index.html new file mode 100644 index 00000000..ee101649 --- /dev/null +++ b/docs/en/cowboy/2.8/manual/cowboy_req.parse_header/index.html @@ -0,0 +1,426 @@ + + + + + + + + + + Nine Nines: cowboy_req:parse_header(3) + + + + + + + + + + + + + + +
+
+
+
+

99s

+
+
+ +
+ +
    +
  • + Github +
    • +
  • + +
    • +
+
+
+
+
+ + +
+ +
+
+
+
+ +

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)

+ + + + + + +
+ +
+ + +

+ Cowboy + 2.8 + Function Reference + +

+ + + +

Navigation

+ +

Version select

+ + +

Like my work? Donate!

+

Donate to Loïc Hoguin because his work on Cowboy, Ranch, Gun and Erlang.mk is fantastic:

+
+ + + + + + + + + +

Recurring payment options are also available via GitHub Sponsors. These funds are used to cover the recurring expenses like food, dedicated servers or domain names.

+ + + +
+
+
+
+ + + + + + + + + -- cgit v1.2.3