aboutsummaryrefslogtreecommitdiffstats
path: root/src/cowboy_http_static.erl
diff options
context:
space:
mode:
Diffstat (limited to 'src/cowboy_http_static.erl')
-rw-r--r--src/cowboy_http_static.erl104
1 files changed, 99 insertions, 5 deletions
diff --git a/src/cowboy_http_static.erl b/src/cowboy_http_static.erl
index 94ba6cd..3e3cb9e 100644
--- a/src/cowboy_http_static.erl
+++ b/src/cowboy_http_static.erl
@@ -85,6 +85,53 @@
%% [{directory, {priv_dir, cowboy, []}},
%% {mimetypes, {fun mimetypes:path_to_mimes/2, default}}]]}
%% '''
+%%
+%% == ETag Header Function ==
+%%
+%% The default behaviour of the static file handler is to not generate ETag
+%% headers. This is because generating ETag headers based on file metadata
+%% causes different servers in a cluster to generate different ETag values for
+%% the same file unless the metadata is also synced. Generating strong ETags
+%% based on the contents of a file is currently out of scope for this module.
+%%
+%% The default behaviour can be overridden to generate an ETag header based on
+%% a combination of the file path, file size, inode and mtime values. If the
+%% option value is a list of attribute names tagged with `attributes' a hex
+%% encoded CRC32 checksum of the attribute values are used as the ETag header
+%% value.
+%%
+%% If a strong ETag is required a user defined function for generating the
+%% header value can be supplied. The function must accept a proplist of the
+%% file attributes as the first argument and a second argument containing any
+%% additional data that the function requires. The function must return a
+%% `binary()' or `undefined'.
+%%
+%% ==== Examples ====
+%% ```
+%% %% A value of default is equal to not specifying the option.
+%% {[<<"static">>, '...', cowboy_http_static,
+%% [{directory, {priv_dir, cowboy, []}},
+%% {etag, default}]]}
+%%
+%% %% Use all avaliable ETag function arguments to generate a header value.
+%% {[<<"static">>, '...', cowboy_http_static,
+%% [{directory, {priv_dir, cowboy, []}},
+%% {etag, {attributes, [filepath, filesize, inode, mtime]}}]]}
+%%
+%% %% Use a user defined function to generate a strong ETag header value.
+%% {[<<"static">>, '...', cowboy_http_static,
+%% [{directory, {priv_dir, cowboy, []}},
+%% {etag, {fun generate_strong_etag/2, strong_etag_extra}}]]}
+%%
+%% generate_strong_etag(Arguments, strong_etag_extra) ->
+%% {_, Filepath} = lists:keyfind(filepath, 1, Arguments),
+%% {_, _Filesize} = lists:keyfind(filesize, 1, Arguments),
+%% {_, _INode} = lists:keyfind(inode, 1, Arguments),
+%% {_, _Modified} = lists:keyfind(mtime, 1, Arguments),
+%% ChecksumCommand = lists:flatten(io_lib:format("sha1sum ~s", [Filepath])),
+%% [Checksum|_] = string:tokens(os:cmd(ChecksumCommand), " "),
+%% iolist_to_binary(Checksum).
+%% '''
-module(cowboy_http_static).
%% include files
@@ -95,8 +142,9 @@
-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]).
+-export([rest_init/2, allowed_methods/2, malformed_request/2,
+ resource_exists/2, forbidden/2, last_modified/2, generate_etag/2,
+ content_types_provided/2, file_contents/2]).
%% internal
-export([path_to_mimetypes/2]).
@@ -105,12 +153,15 @@
-type dirpath() :: string() | binary() | [binary()].
-type dirspec() :: dirpath() | {priv, atom(), dirpath()}.
-type mimedef() :: {binary(), binary(), [{binary(), binary()}]}.
+-type etagarg() :: {filepath, binary()} | {mtime, cowboy_clock:datetime()}
+ | {inode, non_neg_integer()} | {filesize, non_neg_integer()}.
%% handler state
-record(state, {
filepath :: binary() | error,
fileinfo :: {ok, #file_info{}} | {error, _} | error,
- mimetypes :: {fun((binary(), T) -> [mimedef()]), T} | undefined}).
+ mimetypes :: {fun((binary(), T) -> [mimedef()]), T} | undefined,
+ etag_fun :: {fun(([etagarg()], T) -> undefined | binary()), T}}).
%% @private Upgrade from HTTP handler to REST handler.
@@ -129,14 +180,22 @@ rest_init(Req, Opts) ->
[] -> {fun path_to_mimetypes/2, []};
[_|_] -> {fun path_to_mimetypes/2, Mimetypes}
end,
+ ETagFunction = case proplists:get_value(etag, Opts) of
+ default -> {fun no_etag_function/2, undefined};
+ undefined -> {fun no_etag_function/2, undefined};
+ {attributes, Attrs} -> {fun attr_etag_function/2, Attrs};
+ {_, _}=EtagFunction1 -> EtagFunction1
+ end,
{Filepath, Req1} = cowboy_http_req:path_info(Req),
State = case check_path(Filepath) of
error ->
- #state{filepath=error, fileinfo=error, mimetypes=undefined};
+ #state{filepath=error, fileinfo=error, mimetypes=undefined,
+ etag_fun=ETagFunction};
ok ->
Filepath1 = join_paths(Directory1, Filepath),
Fileinfo = file:read_file_info(Filepath1),
- #state{filepath=Filepath1, fileinfo=Fileinfo, mimetypes=Mimetypes1}
+ #state{filepath=Filepath1, fileinfo=Fileinfo, mimetypes=Mimetypes1,
+ etag_fun=ETagFunction}
end,
{ok, Req1, State}.
@@ -186,6 +245,22 @@ last_modified(Req, #state{fileinfo={ok, #file_info{mtime=Modified}}}=State) ->
{Modified, Req, State}.
+%% @private Generate the ETag header value for this file.
+%% The ETag header value is only generated if the resource is a file that
+%% exists in document root.
+-spec generate_etag(#http_req{}, #state{}) ->
+ {undefined | binary(), #http_req{}, #state{}}.
+generate_etag(Req, #state{fileinfo={_, #file_info{type=regular, inode=INode,
+ mtime=Modified, size=Filesize}}, filepath=Filepath,
+ etag_fun={ETagFun, ETagData}}=State) ->
+ ETagArgs = [
+ {filepath, Filepath}, {filesize, Filesize},
+ {inode, INode}, {mtime, Modified}],
+ {ETagFun(ETagArgs, ETagData), Req, State};
+generate_etag(Req, State) ->
+ {undefined, 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,
@@ -329,6 +404,25 @@ default_mimetype() ->
[{<<"application">>, <<"octet-stream">>, []}].
+%% @private Do not send ETag headers in the default configuration.
+-spec no_etag_function([etagarg()], undefined) -> undefined.
+no_etag_function(_Args, undefined) ->
+ undefined.
+
+%% @private A simple alternative is to send an ETag based on file attributes.
+-type fileattr() :: filepath | filesize | mtime | inode.
+-spec attr_etag_function([etagarg()], [fileattr()]) -> binary().
+attr_etag_function(Args, Attrs) ->
+ attr_etag_function(Args, Attrs, []).
+
+-spec attr_etag_function([etagarg()], [fileattr()], [binary()]) -> binary().
+attr_etag_function(_Args, [], Acc) ->
+ list_to_binary(integer_to_list(erlang:crc32(Acc), 16));
+attr_etag_function(Args, [H|T], Acc) ->
+ {_, Value} = lists:keyfind(H, 1, Args),
+ attr_etag_function(Args, T, [term_to_binary(Value)|Acc]).
+
+
-ifdef(TEST).
-include_lib("eunit/include/eunit.hrl").
-define(_eq(E, I), ?_assertEqual(E, I)).