forked from ninenines/cowboy
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add built-in cowboy_http_static handler.
- Loading branch information
Showing
2 changed files
with
421 additions
and
11 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,349 @@ | ||
%% Copyright (c) 2011, Magnus Klaar <magnus.klaar@gmail.com> | ||
%% | ||
%% 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 Static resource handler. | ||
%% | ||
%% This built in HTTP handler provides a simple file serving capability for | ||
%% cowboy applications. It should be considered an experimental feature because | ||
%% of it's dependency on the experimental REST handler. It's recommended to be | ||
%% used for small or temporary environments where it is not preferrable to set | ||
%% up a second server just to serve files. | ||
%% | ||
%% == Base configuration == | ||
%% | ||
%% The handler must be configured with a request path prefix to serve files | ||
%% under and the path to a directory to read files from. The request path prefix | ||
%% is defined in the path pattern of the cowboy dispatch rule for the handler. | ||
%% The request path pattern must end with a ``'...''' token. | ||
%% The directory path can be set to either an absolute or relative path in the | ||
%% form of a list or binary string representation of a file system path. A list | ||
%% of binary path segments, as is used throughout cowboy, is also a valid | ||
%% directory path. | ||
%% | ||
%% The directory path can also be set to a relative path within the `priv/' | ||
%% directory of an application. This is configured by setting the value of the | ||
%% directory option to a tuple of the form `{priv_dir, Application, Relpath}'. | ||
%% | ||
%% ==== Examples ==== | ||
%% ``` | ||
%% %% Serve files from /var/www/ under http://example.com/static/ | ||
%% {[<<"static">>, '...'], cowboy_http_static, | ||
%% [{directory, "/var/www"}]} | ||
%% | ||
%% %% Serve files from the current working directory under http://example.com/static/ | ||
%% {[<<"static">>, '...'], cowboy_http_static, | ||
%% [{directory, <<"./">>}]} | ||
%% | ||
%% %% Serve files from cowboy/priv/www under http://example.com/ | ||
%% {['...'], cowboy_http_static, | ||
%% [{directory, {priv_dir, cowboy, [<<"www">>]}}]} | ||
%% ''' | ||
%% | ||
%% == Content type configuration == | ||
%% | ||
%% By default the content type of all static resources will be set to | ||
%% `application/octet-stream'. This can be overriden by supplying a list | ||
%% of filename extension to mimetypes pairs in the `mimetypes' option. | ||
%% The filename extension should be a binary string including the leading dot. | ||
%% The mimetypes must be of a type that the `cowboy_http_rest' protocol can | ||
%% handle. | ||
%% | ||
%% ==== Example ==== | ||
%% ``` | ||
%% {[<<"static">>, '...'], cowboy_http_static, | ||
%% [{directory, {priv_dir, cowboy, []}}, | ||
%% {mimetypes, [ | ||
%% {<<".css">>, [<<"text/css">>]}, | ||
%% {<<".js">>, [<<"application/javascript">>]}]}]} | ||
%% ''' | ||
-module(cowboy_http_static). | ||
|
||
%% include files | ||
-include("http.hrl"). | ||
-include_lib("kernel/include/file.hrl"). | ||
|
||
%% cowboy_http_protocol callbacks | ||
-export([init/3]). | ||
|
||
%% cowboy_http_rest callbacks | ||
-export([rest_init/2, allowed_methods/2, malformed_request/2, resource_exists/2, | ||
forbidden/2, last_modified/2, content_types_provided/2, file_contents/2]). | ||
|
||
%% internal | ||
-export([path_to_mimetypes/2]). | ||
|
||
%% types | ||
-type dirpath() :: string() | binary() | [binary()]. | ||
-type dirspec() :: dirpath() | {priv, atom(), dirpath()}. | ||
-type mimedef() :: {binary(), binary(), [{binary(), binary()}]}. | ||
|
||
%% handler state | ||
-record(state, { | ||
filepath :: binary() | error, | ||
fileinfo :: {ok, #file_info{}} | {error, _} | error, | ||
mimetypes :: {fun((binary(), T) -> [mimedef()]), T} | undefined}). | ||
|
||
|
||
%% @private Upgrade from HTTP handler to REST handler. | ||
init({_Transport, http}, _Req, _Opts) -> | ||
{upgrade, protocol, cowboy_http_rest}. | ||
|
||
|
||
%% @private Set up initial state of REST handler. | ||
-spec rest_init(#http_req{}, list()) -> {ok, #http_req{}, #state{}}. | ||
rest_init(Req, Opts) -> | ||
Directory = proplists:get_value(directory, Opts), | ||
Directory1 = directory_path(Directory), | ||
Mimetypes = proplists:get_value(mimetypes, Opts, []), | ||
Mimetypes1 = case Mimetypes of | ||
{_, _} -> Mimetypes; | ||
[] -> {fun path_to_mimetypes/2, []}; | ||
[_|_] -> {fun path_to_mimetypes/2, Mimetypes} | ||
end, | ||
{Filepath, Req1} = cowboy_http_req:path_info(Req), | ||
State = case check_path(Filepath) of | ||
error -> | ||
#state{filepath=error, fileinfo=error, mimetypes=undefined}; | ||
ok -> | ||
Filepath1 = join_paths(Directory1, Filepath), | ||
Fileinfo = file:read_file_info(Filepath1), | ||
#state{filepath=Filepath1, fileinfo=Fileinfo, mimetypes=Mimetypes1} | ||
end, | ||
{ok, Req1, State}. | ||
|
||
|
||
%% @private Only allow GET and HEAD requests on files. | ||
-spec allowed_methods(#http_req{}, #state{}) -> | ||
{[atom()], #http_req{}, #state{}}. | ||
allowed_methods(Req, State) -> | ||
{['GET', 'HEAD'], Req, State}. | ||
|
||
%% @private | ||
-spec malformed_request(#http_req{}, #state{}) -> | ||
{boolean(), #http_req{}, #state{}}. | ||
malformed_request(Req, #state{filepath=error}=State) -> | ||
{true, Req, State}; | ||
malformed_request(Req, State) -> | ||
{false, Req, State}. | ||
|
||
|
||
%% @private Check if the resource exists under the document root. | ||
-spec resource_exists(#http_req{}, #state{}) -> | ||
{boolean(), #http_req{}, #state{}}. | ||
resource_exists(Req, #state{fileinfo={error, _}}=State) -> | ||
{false, Req, State}; | ||
resource_exists(Req, #state{fileinfo={ok, Fileinfo}}=State) -> | ||
{Fileinfo#file_info.type =:= regular, Req, State}. | ||
|
||
|
||
%% @private | ||
%% Access to a file resource is forbidden if it exists and the local node does | ||
%% not have permission to read it. Directory listings are always forbidden. | ||
-spec forbidden(#http_req{}, #state{}) -> {boolean(), #http_req{}, #state{}}. | ||
forbidden(Req, #state{fileinfo={_, #file_info{type=directory}}}=State) -> | ||
{true, Req, State}; | ||
forbidden(Req, #state{fileinfo={error, eacces}}=State) -> | ||
{true, Req, State}; | ||
forbidden(Req, #state{fileinfo={error, _}}=State) -> | ||
{false, Req, State}; | ||
forbidden(Req, #state{fileinfo={ok, #file_info{access=Access}}}=State) -> | ||
{not (Access =:= read orelse Access =:= read_write), Req, State}. | ||
|
||
|
||
%% @private Read the time a file system system object was last modified. | ||
-spec last_modified(#http_req{}, #state{}) -> | ||
{cowboy_clock:datetime(), #http_req{}, #state{}}. | ||
last_modified(Req, #state{fileinfo={ok, #file_info{mtime=Modified}}}=State) -> | ||
{Modified, Req, State}. | ||
|
||
|
||
%% @private Return the content type of a file. | ||
-spec content_types_provided(#http_req{}, #state{}) -> tuple(). | ||
content_types_provided(Req, #state{filepath=Filepath, | ||
mimetypes={MimetypesFun, MimetypesData}}=State) -> | ||
Mimetypes = [{T, file_contents} | ||
|| T <- MimetypesFun(Filepath, MimetypesData)], | ||
{Mimetypes, Req, State}. | ||
|
||
|
||
%% @private Return a function that writes a file directly to the socket. | ||
-spec file_contents(#http_req{}, #state{}) -> tuple(). | ||
file_contents(Req, #state{filepath=Filepath, | ||
fileinfo={ok, #file_info{size=Filesize}}}=State) -> | ||
{ok, Transport, Socket} = cowboy_http_req:transport(Req), | ||
Writefile = content_function(Transport, Socket, Filepath), | ||
{{stream, Filesize, Writefile}, Req, State}. | ||
|
||
|
||
%% @private Return a function writing the contents of a file to a socket. | ||
%% The function returns the number of bytes written to the socket to enable | ||
%% the calling function to determine if the expected number of bytes were | ||
%% written to the socket. | ||
-spec content_function(module(), inet:socket(), binary()) -> | ||
fun(() -> {sent, non_neg_integer()}). | ||
content_function(Transport, Socket, Filepath) -> | ||
%% `file:sendfile/2' will only work with the `cowboy_tcp_transport' | ||
%% transport module. SSL or future SPDY transports that require the | ||
%% content to be encrypted or framed as the content is sent. | ||
case erlang:function_exported(file, sendfile, 2) of | ||
false -> | ||
fun() -> sfallback(Transport, Socket, Filepath) end; | ||
_ when Transport =/= cowboy_tcp_transport -> | ||
fun() -> sfallback(Transport, Socket, Filepath) end; | ||
true -> | ||
fun() -> sendfile(Socket, Filepath) end | ||
end. | ||
|
||
|
||
%% @private Sendfile fallback function. | ||
-spec sfallback(module(), inet:socket(), binary()) -> {sent, non_neg_integer()}. | ||
sfallback(Transport, Socket, Filepath) -> | ||
{ok, File} = file:open(Filepath, [read,binary,raw]), | ||
sfallback(Transport, Socket, File, 0). | ||
|
||
-spec sfallback(module(), inet:socket(), file:io_device(), | ||
non_neg_integer()) -> {sent, non_neg_integer()}. | ||
sfallback(Transport, Socket, File, Sent) -> | ||
case file:read(File, 16#1FFF) of | ||
eof -> | ||
ok = file:close(File), | ||
{sent, Sent}; | ||
{ok, Bin} -> | ||
ok = Transport:send(Socket, Bin), | ||
sfallback(Transport, Socket, File, Sent + byte_size(Bin)) | ||
end. | ||
|
||
|
||
%% @private Wrapper for sendfile function. | ||
-spec sendfile(inet:socket(), binary()) -> {sent, non_neg_integer()}. | ||
sendfile(Socket, Filepath) -> | ||
{ok, Sent} = file:sendfile(Filepath, Socket), | ||
{sent, Sent}. | ||
|
||
-spec directory_path(dirspec()) -> dirpath(). | ||
directory_path({priv_dir, App, []}) -> | ||
priv_dir_path(App); | ||
directory_path({priv_dir, App, [H|_]=Path}) when is_integer(H) -> | ||
filename:join(priv_dir_path(App), Path); | ||
directory_path({priv_dir, App, [H|_]=Path}) when is_binary(H) -> | ||
filename:join(filename:split(priv_dir_path(App)) ++ Path); | ||
directory_path({priv_dir, App, Path}) when is_binary(Path) -> | ||
filename:join(priv_dir_path(App), Path); | ||
directory_path(Path) -> | ||
Path. | ||
|
||
|
||
%% @private Validate a request path for unsafe characters. | ||
%% There is no way to escape special characters in a filesystem path. | ||
-spec check_path(Path::[binary()]) -> ok | error. | ||
check_path([]) -> ok; | ||
check_path([<<"">>|_T]) -> error; | ||
check_path([<<".">>|_T]) -> error; | ||
check_path([<<"..">>|_T]) -> error; | ||
check_path([H|T]) -> | ||
case binary:match(H, <<"/">>) of | ||
{_, _} -> error; | ||
nomatch -> check_path(T) | ||
end. | ||
|
||
|
||
%% @private Join the the directory and request paths. | ||
-spec join_paths(dirpath(), [binary()]) -> binary(). | ||
join_paths([H|_]=Dirpath, Filepath) when is_integer(H) -> | ||
filename:join(filename:split(Dirpath) ++ Filepath); | ||
join_paths([H|_]=Dirpath, Filepath) when is_binary(H) -> | ||
filename:join(Dirpath ++ Filepath); | ||
join_paths(Dirpath, Filepath) when is_binary(Dirpath) -> | ||
filename:join([Dirpath] ++ Filepath); | ||
join_paths([], Filepath) -> | ||
filename:join(Filepath). | ||
|
||
|
||
%% @private Return the path to the priv/ directory of an application. | ||
-spec priv_dir_path(atom()) -> string(). | ||
priv_dir_path(App) -> | ||
case code:priv_dir(App) of | ||
{error, bad_name} -> priv_dir_mod(App); | ||
Dir -> Dir | ||
end. | ||
|
||
-spec priv_dir_mod(atom()) -> string(). | ||
priv_dir_mod(Mod) -> | ||
case code:which(Mod) of | ||
File when not is_list(File) -> "../priv"; | ||
File -> filename:join([filename:dirname(File),"../priv"]) | ||
end. | ||
|
||
|
||
%% @private Use application/octet-stream as the default mimetype. | ||
%% If a list of extension - mimetype pairs are provided as the mimetypes | ||
%% an attempt to find the mimetype using the file extension. If no match | ||
%% is found the default mimetype is returned. | ||
-spec path_to_mimetypes(binary(), [{binary(), [mimedef()]}]) -> | ||
[mimedef()]. | ||
path_to_mimetypes(Filepath, Extensions) when is_binary(Filepath) -> | ||
Ext = filename:extension(Filepath), | ||
case Ext of | ||
<<>> -> default_mimetype(); | ||
_Ext -> path_to_mimetypes_(Ext, Extensions) | ||
end. | ||
|
||
-spec path_to_mimetypes_(binary(), [{binary(), [mimedef()]}]) -> [mimedef()]. | ||
path_to_mimetypes_(Ext, Extensions) -> | ||
case lists:keyfind(Ext, 1, Extensions) of | ||
{_, MTs} -> MTs; | ||
_Unknown -> default_mimetype() | ||
end. | ||
|
||
-spec default_mimetype() -> [mimedef()]. | ||
default_mimetype() -> | ||
[{<<"application">>, <<"octet-stream">>, []}]. | ||
|
||
|
||
-ifdef(TEST). | ||
-include_lib("eunit/include/eunit.hrl"). | ||
-define(_eq(E, I), ?_assertEqual(E, I)). | ||
|
||
check_path_test_() -> | ||
C = fun check_path/1, | ||
[?_eq(error, C([<<>>])), | ||
?_eq(ok, C([<<"abc">>])), | ||
?_eq(error, C([<<".">>])), | ||
?_eq(error, C([<<"..">>])), | ||
?_eq(error, C([<<"/">>])) | ||
]. | ||
|
||
join_paths_test_() -> | ||
P = fun join_paths/2, | ||
[?_eq(<<"a">>, P([], [<<"a">>])), | ||
?_eq(<<"a/b/c">>, P(<<"a/b">>, [<<"c">>])), | ||
?_eq(<<"a/b/c">>, P("a/b", [<<"c">>])), | ||
?_eq(<<"a/b/c">>, P([<<"a">>, <<"b">>], [<<"c">>])) | ||
]. | ||
|
||
directory_path_test_() -> | ||
P = fun directory_path/1, | ||
PL = fun(I) -> length(filename:split(P(I))) end, | ||
Base = PL({priv_dir, cowboy, []}), | ||
[?_eq(Base + 1, PL({priv_dir, cowboy, "a"})), | ||
?_eq(Base + 1, PL({priv_dir, cowboy, <<"a">>})), | ||
?_eq(Base + 1, PL({priv_dir, cowboy, [<<"a">>]})), | ||
?_eq(Base + 2, PL({priv_dir, cowboy, "a/b"})), | ||
?_eq(Base + 2, PL({priv_dir, cowboy, <<"a/b">>})), | ||
?_eq(Base + 2, PL({priv_dir, cowboy, [<<"a">>, <<"b">>]})), | ||
?_eq("a/b", P("a/b")) | ||
]. | ||
|
||
|
||
-endif. |
Oops, something went wrong.