1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
= cowboy_req:parse_header(3)
== Name
cowboy_req:parse_header - Parse the given HTTP header
== Description
[source,erlang]
----
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
[source,erlang]
----
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
[source,erlang]
----
parse_header(Name, Req) -> [{Value, Quality}]
Name :: <<"accept-charset">>
| <<"accept-encoding">>
| <<"accept-language">>
Value :: binary() %% case insensitive
Quality :: 0..1000
----
.authorization
[source,erlang]
----
parse_header(<<"authorization">>, Req)
-> {basic, Username :: binary(), Password :: binary()}
| {bearer, Token :: binary()}
| {digest, [{Key :: binary(), Value :: binary()}]}
----
// @todo Currently also parses connection. Do we want this? Should it be documented? Use case?
.content-length
[source,erlang]
----
parse_header(<<"content-length">>, Req) -> non_neg_integer()
----
When the content-length header is missing, `0` is returned.
.content-type
[source,erlang]
----
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
[source,erlang]
----
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
[source,erlang]
----
parse_header(<<"expect">>, Req) -> continue
----
.if-match and if-none-match
[source,erlang]
----
parse_header(Name, Req)
-> '*' | [{weak | strong, OpaqueTag}]
Name :: <<"if-match">>
| <<"if-none-match">>
OpaqueTag :: binary() %% case sensitive
----
.if-modified-since and if-unmodified-since
[source,erlang]
----
parse_header(Name, Req) -> calendar:datetime()
----
.range
[source,erlang]
----
parse_header(<<"range">>, Req) -> {From, To} | Final
From :: non_neg_integer()
To :: non_neg_integer() | infinity
Final :: neg_integer()
----
// @todo Remove transfer-encoding from the headers parsed by this function.
.sec-websocket-extensions
[source,erlang]
----
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
[source,erlang]
----
parse_header(Name, Req) -> [Token]
Name :: <<"sec-websocket-protocol">>
| <<"upgrade">>
Token :: binary() %% case insensitive
----
.x-forwarded-for
[source,erlang]
----
parse_header(<<"x-forwarded-for">>, Req) -> [Token]
Token :: binary() %% case sensitive
----
.Unknown headers
[source,erlang]
----
parse_header(_, Req) -> {undefined, RawValue}
----
== Changelog
* *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
[source,erlang]
----
%% Accept everything when header is missing.
Accept = cowboy_req:parse_header(<<"accept">>, Req,
[{{<<"*">>, <<"*">>, []}, 1000, []}]).
----
.Parse the content-length header
[source,erlang]
----
%% Default content-length is 0.
Length = cowboy_req:header(<<"content-length">>, Req).
----
== See also
link:man:cowboy_req(3)[cowboy_req(3)],
link:man:cowboy_req:header(3)[cowboy_req:header(3)],
link:man:cowboy_req:headers(3)[cowboy_req:headers(3)]
|
