/deps/mochiweb/src/mochiweb_headers.erl

  1%% @author Bob Ippolito <bob@mochimedia.com>
  2%% @copyright 2007 Mochi Media, Inc.
  3
  4%% @doc Case preserving (but case insensitive) HTTP Header dictionary.
  5
  6-module(mochiweb_headers).
  7-author('bob@mochimedia.com').
  8-export([empty/0, from_list/1, insert/3, enter/3, get_value/2, lookup/2]).
  9-export([delete_any/2, get_primary_value/2]).
 10-export([default/3, enter_from_list/2, default_from_list/2]).
 11-export([to_list/1, make/1]).
 12-export([from_binary/1]).
 13
 14%% @type headers().
 15%% @type key() = atom() | binary() | string().
 16%% @type value() = atom() | binary() | string() | integer().
 17
 18%% @spec empty() -> headers()
 19%% @doc Create an empty headers structure.
 20empty() ->
 21    gb_trees:empty().
 22
 23%% @spec make(headers() | [{key(), value()}]) -> headers()
 24%% @doc Construct a headers() from the given list.
 25make(L) when is_list(L) ->
 26    from_list(L);
 27%% assume a non-list is already mochiweb_headers.
 28make(T) ->
 29    T.
 30
 31%% @spec from_binary(iolist()) -> headers()
 32%% @doc Transforms a raw HTTP header into a mochiweb headers structure.
 33%%
 34%%      The given raw HTTP header can be one of the following:
 35%%
 36%%      1) A string or a binary representing a full HTTP header ending with
 37%%         double CRLF.
 38%%         Examples:
 39%%         ```
 40%%         "Content-Length: 47\r\nContent-Type: text/plain\r\n\r\n"
 41%%         <<"Content-Length: 47\r\nContent-Type: text/plain\r\n\r\n">>'''
 42%%
 43%%      2) A list of binaries or strings where each element represents a raw
 44%%         HTTP header line ending with a single CRLF.
 45%%         Examples:
 46%%         ```
 47%%         [<<"Content-Length: 47\r\n">>, <<"Content-Type: text/plain\r\n">>]
 48%%         ["Content-Length: 47\r\n", "Content-Type: text/plain\r\n"]
 49%%         ["Content-Length: 47\r\n", <<"Content-Type: text/plain\r\n">>]'''
 50%%
 51from_binary(RawHttpHeader) when is_binary(RawHttpHeader) ->
 52    from_binary(RawHttpHeader, []);
 53from_binary(RawHttpHeaderList) ->
 54    from_binary(list_to_binary([RawHttpHeaderList, "\r\n"])).
 55
 56from_binary(RawHttpHeader, Acc) ->
 57    case erlang:decode_packet(httph, RawHttpHeader, []) of
 58        {ok, {http_header, _, H, _, V}, Rest} ->
 59            from_binary(Rest, [{H, V} | Acc]);
 60        _ ->
 61            make(Acc)
 62    end.
 63
 64%% @spec from_list([{key(), value()}]) -> headers()
 65%% @doc Construct a headers() from the given list.
 66from_list(List) ->
 67    lists:foldl(fun ({K, V}, T) -> insert(K, V, T) end, empty(), List).
 68
 69%% @spec enter_from_list([{key(), value()}], headers()) -> headers()
 70%% @doc Insert pairs into the headers, replace any values for existing keys.
 71enter_from_list(List, T) ->
 72    lists:foldl(fun ({K, V}, T1) -> enter(K, V, T1) end, T, List).
 73
 74%% @spec default_from_list([{key(), value()}], headers()) -> headers()
 75%% @doc Insert pairs into the headers for keys that do not already exist.
 76default_from_list(List, T) ->
 77    lists:foldl(fun ({K, V}, T1) -> default(K, V, T1) end, T, List).
 78
 79%% @spec to_list(headers()) -> [{key(), string()}]
 80%% @doc Return the contents of the headers. The keys will be the exact key
 81%%      that was first inserted (e.g. may be an atom or binary, case is
 82%%      preserved).
 83to_list(T) ->
 84    F = fun ({K, {array, L}}, Acc) ->
 85                L1 = lists:reverse(L),
 86                lists:foldl(fun (V, Acc1) -> [{K, V} | Acc1] end, Acc, L1);
 87            (Pair, Acc) ->
 88                [Pair | Acc]
 89        end,
 90    lists:reverse(lists:foldl(F, [], gb_trees:values(T))).
 91
 92%% @spec get_value(key(), headers()) -> string() | undefined
 93%% @doc Return the value of the given header using a case insensitive search.
 94%%      undefined will be returned for keys that are not present.
 95get_value(K, T) ->
 96    case lookup(K, T) of
 97        {value, {_, V}} ->
 98            expand(V);
 99        none ->
100            undefined
101    end.
102
103%% @spec get_primary_value(key(), headers()) -> string() | undefined
104%% @doc Return the value of the given header up to the first semicolon using
105%%      a case insensitive search. undefined will be returned for keys
106%%      that are not present.
107get_primary_value(K, T) ->
108    case get_value(K, T) of
109        undefined ->
110            undefined;
111        V ->
112            lists:takewhile(fun (C) -> C =/= $; end, V)
113    end.
114
115%% @spec lookup(key(), headers()) -> {value, {key(), string()}} | none
116%% @doc Return the case preserved key and value for the given header using
117%%      a case insensitive search. none will be returned for keys that are
118%%      not present.
119lookup(K, T) ->
120    case gb_trees:lookup(normalize(K), T) of
121        {value, {K0, V}} ->
122            {value, {K0, expand(V)}};
123        none ->
124            none
125    end.
126
127%% @spec default(key(), value(), headers()) -> headers()
128%% @doc Insert the pair into the headers if it does not already exist.
129default(K, V, T) ->
130    K1 = normalize(K),
131    V1 = any_to_list(V),
132    try gb_trees:insert(K1, {K, V1}, T)
133    catch
134        error:{key_exists, _} ->
135            T
136    end.
137
138%% @spec enter(key(), value(), headers()) -> headers()
139%% @doc Insert the pair into the headers, replacing any pre-existing key.
140enter(K, V, T) ->
141    K1 = normalize(K),
142    V1 = any_to_list(V),
143    gb_trees:enter(K1, {K, V1}, T).
144
145%% @spec insert(key(), value(), headers()) -> headers()
146%% @doc Insert the pair into the headers, merging with any pre-existing key.
147%%      A merge is done with Value = V0 ++ ", " ++ V1.
148insert(K, V, T) ->
149    K1 = normalize(K),
150    V1 = any_to_list(V),
151    try gb_trees:insert(K1, {K, V1}, T)
152    catch
153        error:{key_exists, _} ->
154            {K0, V0} = gb_trees:get(K1, T),
155            V2 = merge(K1, V1, V0),
156            gb_trees:update(K1, {K0, V2}, T)
157    end.
158
159%% @spec delete_any(key(), headers()) -> headers()
160%% @doc Delete the header corresponding to key if it is present.
161delete_any(K, T) ->
162    K1 = normalize(K),
163    gb_trees:delete_any(K1, T).
164
165%% Internal API
166
167expand({array, L}) ->
168    mochiweb_util:join(lists:reverse(L), ", ");
169expand(V) ->
170    V.
171
172merge("set-cookie", V1, {array, L}) ->
173    {array, [V1 | L]};
174merge("set-cookie", V1, V0) ->
175    {array, [V1, V0]};
176merge(_, V1, V0) ->
177    V0 ++ ", " ++ V1.
178
179normalize(K) when is_list(K) ->
180    string:to_lower(K);
181normalize(K) when is_atom(K) ->
182    normalize(atom_to_list(K));
183normalize(K) when is_binary(K) ->
184    normalize(binary_to_list(K)).
185
186any_to_list(V) when is_list(V) ->
187    V;
188any_to_list(V) when is_atom(V) ->
189    atom_to_list(V);
190any_to_list(V) when is_binary(V) ->
191    binary_to_list(V);
192any_to_list(V) when is_integer(V) ->
193    integer_to_list(V).
194
195%%
196%% Tests.
197%%
198-ifdef(TEST).
199-include_lib("eunit/include/eunit.hrl").
200
201make_test() ->
202    Identity = make([{hdr, foo}]),
203    ?assertEqual(
204       Identity,
205       make(Identity)).
206
207enter_from_list_test() ->
208    H = make([{hdr, foo}]),
209    ?assertEqual(
210       [{baz, "wibble"}, {hdr, "foo"}],
211       to_list(enter_from_list([{baz, wibble}], H))),
212    ?assertEqual(
213       [{hdr, "bar"}],
214       to_list(enter_from_list([{hdr, bar}], H))),
215    ok.
216
217default_from_list_test() ->
218    H = make([{hdr, foo}]),
219    ?assertEqual(
220       [{baz, "wibble"}, {hdr, "foo"}],
221       to_list(default_from_list([{baz, wibble}], H))),
222    ?assertEqual(
223       [{hdr, "foo"}],
224       to_list(default_from_list([{hdr, bar}], H))),
225    ok.
226
227get_primary_value_test() ->
228    H = make([{hdr, foo}, {baz, <<"wibble;taco">>}]),
229    ?assertEqual(
230       "foo",
231       get_primary_value(hdr, H)),
232    ?assertEqual(
233       undefined,
234       get_primary_value(bar, H)),
235    ?assertEqual(
236       "wibble",
237       get_primary_value(<<"baz">>, H)),
238    ok.
239
240set_cookie_test() ->
241    H = make([{"set-cookie", foo}, {"set-cookie", bar}, {"set-cookie", baz}]),
242    ?assertEqual(
243       [{"set-cookie", "foo"}, {"set-cookie", "bar"}, {"set-cookie", "baz"}],
244       to_list(H)),
245    ok.
246
247headers_test() ->
248    H = ?MODULE:make([{hdr, foo}, {"Hdr", "bar"}, {'Hdr', 2}]),
249    [{hdr, "foo, bar, 2"}] = ?MODULE:to_list(H),
250    H1 = ?MODULE:insert(taco, grande, H),
251    [{hdr, "foo, bar, 2"}, {taco, "grande"}] = ?MODULE:to_list(H1),
252    H2 = ?MODULE:make([{"Set-Cookie", "foo"}]),
253    [{"Set-Cookie", "foo"}] = ?MODULE:to_list(H2),
254    H3 = ?MODULE:insert("Set-Cookie", "bar", H2),
255    [{"Set-Cookie", "foo"}, {"Set-Cookie", "bar"}] = ?MODULE:to_list(H3),
256    "foo, bar" = ?MODULE:get_value("set-cookie", H3),
257    {value, {"Set-Cookie", "foo, bar"}} = ?MODULE:lookup("set-cookie", H3),
258    undefined = ?MODULE:get_value("shibby", H3),
259    none = ?MODULE:lookup("shibby", H3),
260    H4 = ?MODULE:insert("content-type",
261                        "application/x-www-form-urlencoded; charset=utf8",
262                        H3),
263    "application/x-www-form-urlencoded" = ?MODULE:get_primary_value(
264                                             "content-type", H4),
265    H4 = ?MODULE:delete_any("nonexistent-header", H4),
266    H3 = ?MODULE:delete_any("content-type", H4),
267    HB = <<"Content-Length: 47\r\nContent-Type: text/plain\r\n\r\n">>,
268    H_HB = ?MODULE:from_binary(HB),
269    H_HB = ?MODULE:from_binary(binary_to_list(HB)),
270    "47" = ?MODULE:get_value("Content-Length", H_HB),
271    "text/plain" = ?MODULE:get_value("Content-Type", H_HB),
272    L_H_HB = ?MODULE:to_list(H_HB),
273    2 = length(L_H_HB),
274    true = lists:member({'Content-Length', "47"}, L_H_HB),
275    true = lists:member({'Content-Type', "text/plain"}, L_H_HB),
276    HL = [ <<"Content-Length: 47\r\n">>, <<"Content-Type: text/plain\r\n">> ],
277    HL2 = [ "Content-Length: 47\r\n", <<"Content-Type: text/plain\r\n">> ],
278    HL3 = [ <<"Content-Length: 47\r\n">>, "Content-Type: text/plain\r\n" ],
279    H_HL = ?MODULE:from_binary(HL),
280    H_HL = ?MODULE:from_binary(HL2),
281    H_HL = ?MODULE:from_binary(HL3),
282    "47" = ?MODULE:get_value("Content-Length", H_HL),
283    "text/plain" = ?MODULE:get_value("Content-Type", H_HL),
284    L_H_HL = ?MODULE:to_list(H_HL),
285    2 = length(L_H_HL),
286    true = lists:member({'Content-Length', "47"}, L_H_HL),
287    true = lists:member({'Content-Type', "text/plain"}, L_H_HL),
288    [] = ?MODULE:to_list(?MODULE:from_binary(<<>>)),
289    [] = ?MODULE:to_list(?MODULE:from_binary(<<"">>)),
290    [] = ?MODULE:to_list(?MODULE:from_binary(<<"\r\n">>)),
291    [] = ?MODULE:to_list(?MODULE:from_binary(<<"\r\n\r\n">>)),
292    [] = ?MODULE:to_list(?MODULE:from_binary("")),
293    [] = ?MODULE:to_list(?MODULE:from_binary([<<>>])),
294    [] = ?MODULE:to_list(?MODULE:from_binary([<<"">>])),
295    [] = ?MODULE:to_list(?MODULE:from_binary([<<"\r\n">>])),
296    [] = ?MODULE:to_list(?MODULE:from_binary([<<"\r\n\r\n">>])),
297    ok.
298
299-endif.