%% Copyright (c) 2011, Loïc Hoguin %% Copyright (c) 2011, Anthony Ramine %% %% Permission to use, copy, modify, and/or distribute this software for any %% purpose with or without fee is hereby granted, provided that the above %% copyright notice and this permission notice appear in all copies. %% %% THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES %% WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF %% MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR %% ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES %% WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN %% ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF %% OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. %% @doc Dispatch requests according to a hostname and path. -module(cowboy_dispatcher). -export([split_host/1, split_path/1, match/3]). %% API. -type bindings() :: list({atom(), binary()}). -type path_tokens() :: list(binary()). -type match_rule() :: '_' | '*' | list(binary() | '_' | '...' | atom()). -type dispatch_path() :: list({match_rule(), module(), any()}). -type dispatch_rule() :: {Host::match_rule(), Path::dispatch_path()}. -type dispatch_rules() :: list(dispatch_rule()). -export_type([bindings/0, path_tokens/0, dispatch_rules/0]). -include_lib("eunit/include/eunit.hrl"). %% API. %% @doc Split a hostname into a list of tokens. -spec split_host(binary()) -> {path_tokens(), binary(), undefined | inet:ip_port()}. split_host(<<>>) -> {[], <<>>, undefined}; split_host(Host) -> case binary:split(Host, <<":">>) of [Host] -> {binary:split(Host, <<".">>, [global, trim]), Host, undefined}; [Host2, Port] -> {binary:split(Host2, <<".">>, [global, trim]), Host2, list_to_integer(binary_to_list(Port))} end. %% @doc Split a path into a list of tokens. -spec split_path(binary()) -> {path_tokens(), binary(), binary()}. split_path(Path) -> case binary:split(Path, <<"?">>) of [Path] -> {do_split_path(Path, <<"/">>), Path, <<>>}; [<<>>, Qs] -> {[], <<>>, Qs}; [Path2, Qs] -> {do_split_path(Path2, <<"/">>), Path2, Qs} end. -spec do_split_path(binary(), <<_:8>>) -> path_tokens(). do_split_path(RawPath, Separator) -> EncodedPath = case binary:split(RawPath, Separator, [global, trim]) of [<<>>|Path] -> Path; Path -> Path end, [quoted:from_url(Token) || Token <- EncodedPath]. %% @doc Match hostname tokens and path tokens against dispatch rules. %% %% It is typically used for matching tokens for the hostname and path of %% the request against a global dispatch rule for your listener. %% %% Dispatch rules are a list of {Hostname, PathRules} tuples, with %% PathRules being a list of {Path, HandlerMod, HandlerOpts}. %% %% Hostname and Path are match rules and can be either the %% atom '_', which matches everything for a single token, the atom %% '*', which matches everything for the rest of the tokens, or a %% list of tokens. Each token can be either a binary, the atom '_', %% the atom '...' or a named atom. A binary token must match exactly, %% '_' matches everything for a single token, '...' matches %% everything for the rest of the tokens and a named atom will bind the %% corresponding token value and return it. %% %% The list of hostname tokens is reversed before matching. For example, if %% we were to match "www.dev-extend.eu", we would first match "eu", then %% "dev-extend", then "www". This means that in the context of hostnames, %% the '...' atom matches properly the lower levels of the domain %% as would be expected. %% %% When a result is found, this function will return the handler module and %% options found in the dispatch list, a key-value list of bindings and %% the tokens that were matched by the '...' atom for both the %% hostname and path. -spec match(Host::path_tokens(), Path::path_tokens(), dispatch_rules()) -> {ok, module(), any(), bindings(), HostInfo::undefined | path_tokens(), PathInfo::undefined | path_tokens()} | {error, notfound, host} | {error, notfound, path}. match(_Host, _Path, []) -> {error, notfound, host}; match(_Host, Path, [{'_', PathMatchs}|_Tail]) -> match_path(Path, PathMatchs, [], undefined); match(Host, Path, [{HostMatch, PathMatchs}|Tail]) -> case try_match(host, Host, HostMatch) of false -> match(Host, Path, Tail); {true, HostBinds, undefined} -> match_path(Path, PathMatchs, HostBinds, undefined); {true, HostBinds, HostInfo} -> match_path(Path, PathMatchs, HostBinds, lists:reverse(HostInfo)) end. -spec match_path(path_tokens(), dispatch_path(), bindings(), HostInfo::undefined | path_tokens()) -> {ok, module(), any(), bindings(), HostInfo::undefined | path_tokens(), PathInfo::undefined | path_tokens()} | {error, notfound, path}. match_path(_Path, [], _HostBinds, _HostInfo) -> {error, notfound, path}; match_path(_Path, [{'_', Handler, Opts}|_Tail], HostBinds, HostInfo) -> {ok, Handler, Opts, HostBinds, HostInfo, undefined}; match_path('*', [{'*', Handler, Opts}|_Tail], HostBinds, HostInfo) -> {ok, Handler, Opts, HostBinds, HostInfo, undefined}; match_path(Path, [{PathMatch, Handler, Opts}|Tail], HostBinds, HostInfo) -> case try_match(path, Path, PathMatch) of false -> match_path(Path, Tail, HostBinds, HostInfo); {true, PathBinds, PathInfo} -> {ok, Handler, Opts, HostBinds ++ PathBinds, HostInfo, PathInfo} end. %% Internal. -spec try_match(host | path, path_tokens(), match_rule()) -> {true, bindings(), undefined | path_tokens()} | false. try_match(host, List, Match) -> list_match(lists:reverse(List), lists:reverse(Match), []); try_match(path, List, Match) -> list_match(List, Match, []). -spec list_match(path_tokens(), match_rule(), bindings()) -> {true, bindings(), undefined | path_tokens()} | false. %% Atom '...' matches any trailing path, stop right now. list_match(List, ['...'], Binds) -> {true, Binds, List}; %% Atom '_' matches anything, continue. list_match([_E|Tail], ['_'|TailMatch], Binds) -> list_match(Tail, TailMatch, Binds); %% Both values match, continue. list_match([E|Tail], [E|TailMatch], Binds) -> list_match(Tail, TailMatch, Binds); %% Bind E to the variable name V and continue. list_match([E|Tail], [V|TailMatch], Binds) when is_atom(V) -> list_match(Tail, TailMatch, [{V, E}|Binds]); %% Match complete. list_match([], [], Binds) -> {true, Binds, undefined}; %% Values don't match, stop. list_match(_List, _Match, _Binds) -> false. %% Tests. -ifdef(TEST). split_host_test_() -> %% {Host, Result} Tests = [ {<<"">>, {[], <<"">>, undefined}}, {<<".........">>, {[], <<".........">>, undefined}}, {<<"*">>, {[<<"*">>], <<"*">>, undefined}}, {<<"cowboy.dev-extend.eu">>, {[<<"cowboy">>, <<"dev-extend">>, <<"eu">>], <<"cowboy.dev-extend.eu">>, undefined}}, {<<"dev-extend..eu">>, {[<<"dev-extend">>, <<>>, <<"eu">>], <<"dev-extend..eu">>, undefined}}, {<<"dev-extend.eu">>, {[<<"dev-extend">>, <<"eu">>], <<"dev-extend.eu">>, undefined}}, {<<"dev-extend.eu:8080">>, {[<<"dev-extend">>, <<"eu">>], <<"dev-extend.eu">>, 8080}}, {<<"a.b.c.d.e.f.g.h.i.j.k.l.m.n.o.p.q.r.s.t.u.v.w.x.y.z">>, {[<<"a">>, <<"b">>, <<"c">>, <<"d">>, <<"e">>, <<"f">>, <<"g">>, <<"h">>, <<"i">>, <<"j">>, <<"k">>, <<"l">>, <<"m">>, <<"n">>, <<"o">>, <<"p">>, <<"q">>, <<"r">>, <<"s">>, <<"t">>, <<"u">>, <<"v">>, <<"w">>, <<"x">>, <<"y">>, <<"z">>], <<"a.b.c.d.e.f.g.h.i.j.k.l.m.n.o.p.q.r.s.t.u.v.w.x.y.z">>, undefined}} ], [{H, fun() -> R = split_host(H) end} || {H, R} <- Tests]. split_host_fail_test_() -> Tests = [ <<"dev-extend.eu:owns">>, <<"dev-extend.eu: owns">>, <<"dev-extend.eu:42fun">>, <<"dev-extend.eu: 42fun">>, <<"dev-extend.eu:42 fun">>, <<"dev-extend.eu:fun 42">>, <<"dev-extend.eu: 42">>, <<":owns">>, <<":42 fun">> ], [{H, fun() -> case catch split_host(H) of {'EXIT', _Reason} -> ok end end} || H <- Tests]. split_path_test_() -> %% {Path, Result, QueryString} Tests = [ {<<"?">>, [], <<"">>, <<"">>}, {<<"???">>, [], <<"">>, <<"??">>}, {<<"/">>, [], <<"/">>, <<"">>}, {<<"/users">>, [<<"users">>], <<"/users">>, <<"">>}, {<<"/users?">>, [<<"users">>], <<"/users">>, <<"">>}, {<<"/users?a">>, [<<"users">>], <<"/users">>, <<"a">>}, {<<"/users/42/friends?a=b&c=d&e=notsure?whatever">>, [<<"users">>, <<"42">>, <<"friends">>], <<"/users/42/friends">>, <<"a=b&c=d&e=notsure?whatever">>}, {<<"/users/a+b/c%21d?e+f=g+h">>, [<<"users">>, <<"a b">>, <<"c!d">>], <<"/users/a+b/c%21d">>, <<"e+f=g+h">>} ], [{P, fun() -> {R, RawP, Qs} = split_path(P) end} || {P, R, RawP, Qs} <- Tests]. match_test_() -> Dispatch = [ {[<<"www">>, '_', <<"dev-extend">>, <<"eu">>], [ {[<<"users">>, '_', <<"mails">>], match_any_subdomain_users, []} ]}, {[<<"dev-extend">>, <<"eu">>], [ {[<<"users">>, id, <<"friends">>], match_extend_users_friends, []}, {'_', match_extend, []} ]}, {[<<"dev-extend">>, var], [ {[<<"threads">>, var], match_duplicate_vars, [we, {expect, two}, var, here]} ]}, {[<<"erlang">>, ext], [ {'_', match_erlang_ext, []} ]}, {'_', [ {[<<"users">>, id, <<"friends">>], match_users_friends, []}, {'_', match_any, []} ]} ], %% {Host, Path, Result} Tests = [ {[<<"any">>], [], {ok, match_any, [], []}}, {[<<"www">>, <<"any">>, <<"dev-extend">>, <<"eu">>], [<<"users">>, <<"42">>, <<"mails">>], {ok, match_any_subdomain_users, [], []}}, {[<<"www">>, <<"dev-extend">>, <<"eu">>], [<<"users">>, <<"42">>, <<"mails">>], {ok, match_any, [], []}}, {[<<"www">>, <<"dev-extend">>, <<"eu">>], [], {ok, match_any, [], []}}, {[<<"www">>, <<"any">>, <<"dev-extend">>, <<"eu">>], [<<"not_users">>, <<"42">>, <<"mails">>], {error, notfound, path}}, {[<<"dev-extend">>, <<"eu">>], [], {ok, match_extend, [], []}}, {[<<"dev-extend">>, <<"eu">>], [<<"users">>, <<"42">>, <<"friends">>], {ok, match_extend_users_friends, [], [{id, <<"42">>}]}}, {[<<"erlang">>, <<"fr">>], '_', {ok, match_erlang_ext, [], [{ext, <<"fr">>}]}}, {[<<"any">>], [<<"users">>, <<"444">>, <<"friends">>], {ok, match_users_friends, [], [{id, <<"444">>}]}}, {[<<"dev-extend">>, <<"fr">>], [<<"threads">>, <<"987">>], {ok, match_duplicate_vars, [we, {expect, two}, var, here], [{var, <<"fr">>}, {var, <<"987">>}]}} ], [{lists:flatten(io_lib:format("~p, ~p", [H, P])), fun() -> {ok, Handler, Opts, Binds, undefined, undefined} = match(H, P, Dispatch) end} || {H, P, {ok, Handler, Opts, Binds}} <- Tests]. match_info_test_() -> Dispatch = [ {[<<"www">>, <<"dev-extend">>, <<"eu">>], [ {[<<"pathinfo">>, <<"is">>, <<"next">>, '...'], match_path, []} ]}, {['...', <<"dev-extend">>, <<"eu">>], [ {'_', match_any, []} ]} ], Tests = [ {[<<"dev-extend">>, <<"eu">>], [], {ok, match_any, [], [], [], undefined}}, {[<<"bugs">>, <<"dev-extend">>, <<"eu">>], [], {ok, match_any, [], [], [<<"bugs">>], undefined}}, {[<<"cowboy">>, <<"bugs">>, <<"dev-extend">>, <<"eu">>], [], {ok, match_any, [], [], [<<"cowboy">>, <<"bugs">>], undefined}}, {[<<"www">>, <<"dev-extend">>, <<"eu">>], [<<"pathinfo">>, <<"is">>, <<"next">>], {ok, match_path, [], [], undefined, []}}, {[<<"www">>, <<"dev-extend">>, <<"eu">>], [<<"pathinfo">>, <<"is">>, <<"next">>, <<"path_info">>], {ok, match_path, [], [], undefined, [<<"path_info">>]}}, {[<<"www">>, <<"dev-extend">>, <<"eu">>], [<<"pathinfo">>, <<"is">>, <<"next">>, <<"foo">>, <<"bar">>], {ok, match_path, [], [], undefined, [<<"foo">>, <<"bar">>]}} ], [{lists:flatten(io_lib:format("~p, ~p", [H, P])), fun() -> R = match(H, P, Dispatch) end} || {H, P, R} <- Tests]. -endif.