umgeher/cowboy
0
Fork 0
mirror of https://github.com/ninenines/cowboy.git synced 2025-07-15 12:40:25 +00:00
Code Issues Wiki Activity

Update the cowboy_static manual

Browse source
This commit is contained in:
Loïc Hoguin 2016-12-23 12:19:27 +01:00
parent 56e489f00a
commit 98ae01b599
No known key found for this signature in database
GPG key ID: 71366FF21851DF03
1 changed files with 119 additions and 22 deletions
Download patch file Download diff file Expand all files Collapse all files

141
doc/src/manual/cowboy_static.asciidoc
View file

@ -2,40 +2,137 @@
== Name == Name
cowboy_static - static file handler cowboy_static - Static file handler
== Description == Description
The `cowboy_static` module implements file serving capabilities The module `cowboy_static` implements file serving capabilities
by using the REST semantics provided by `cowboy_rest`. using the REST semantics provided by `cowboy_rest`.
== Types The static file handler is a pre-written handler coming with
Cowboy. To serve files, use it in your routes.
=== opts() = [Option] == Options
[source,erlang] [source,erlang]
---- ----
Option = {priv_file, atom(), string() | binary()} opts() :: {priv_file, App, Path}
| {priv_file, atom(), string() | binary(), Extra} | {priv_file, App, Path, Extra}
| {file, string() | binary()} | {file, Path}
| {file, string() | binary(), Extra} | {file, Path, Extra}
| {priv_dir, atom(), string() | binary()} | {priv_dir, App, Path}
| {priv_dir, atom(), string() | binary(), Extra} | {priv_dir, App, Path, Extra}
| {dir, string() | binary()} | {dir, Path}
| {dir, string() | binary(), Extra} | {dir, Path, Extra}
Extra = [ETag | Mimetypes] App :: atom()
Path :: binary() | string()
Extra :: [Etag | Mimetypes]
ETag = {etag, module(), function()} | {etag, false} Etag :: {etag, module(), function()}
| {etag, false}
Mimetypes = {mimetypes, module(), function()} Mimetypes :: {mimetypes, module(), function()}
| {mimetypes, binary() | {binary(), binary(), [{binary(), binary()}]}} | {mimetypes, binary() | ParsedMime}
ParsedMime :: {Type :: binary(), SubType :: binary(), Params}
Params :: [{Key :: binary(), Value :: binary()}]
---- ----
Configuration for the static handler. Static handler configuration.
The handler can be configured for sending either one file or priv_file::
a directory (including its subdirectories).
Extra options allow you to define how the etag should be calculated Send a file.
and how the mimetype of files should be detected. +
The path is relative to the given application's private
directory.
file::
Send a file.
+
The path is either absolute or relative to the Erlang node's
current directory.
priv_dir::
Recursively serve files from a directory.
+
The path is relative to the given application's private
directory.
dir::
Recursively serve files from a directory.
+
The path is either absolute or relative to the Erlang node's
current directory.
The extra options allow you to define how the etag should be
calculated and how the MIME type of files should be detected.
By default the static handler will generate an etag based
on the size and modification time of the file. You may disable
the etag entirely with `{etag, false}` or provide a module
and function that will be called when needed:
[source,erlang]
----
generate_etag(Path, Size, Mtime) -> {strong | weak, binary()}
Path :: binary()
Size :: non_neg_integer()
Mtime :: file:date_time()
----
By default the static handler will detect Web-related MIME types
by looking at the file extension. You can provide a specific
MIME type that will always be used, or a module and function that
will be called when needed:
[source,erlang]
----
detect_mimetype(Path) -> ParsedMime
Path :: binary()
ParsedMime :: {Type :: binary(), SubType :: binary(), Params}
Params :: [{Key :: binary(), Value :: binary()}]
----
Cowboy comes with two such functions; the default function
`cow_mimetypes:web/1`, and a second function generated from
the Apache 'mime.types' file, `cow_mimetypes:all/1`.
The MIME type function should return
`{<<"application">>, <<"octet-stream">>, []}`
when it fails to detect a file's MIME type.
== Changelog
* *1.0*: Handler introduced.
== Examples
.Custom etag function
[source,erlang]
----
generate_etag(Path, Size, Mtime) ->
{strong, integer_to_binary(
erlang:phash2({Path, Size, Mtime}, 16#ffffffff))}.
----
.Custom MIME type function
[source,erlang]
----
always_octet_stream(_Path) ->
case filename:extension(Path) of
<<".erl">> -> {<<"text">>, <<"plain">>, []};
_ -> {<<"application">>, <<"octet-stream">>, []}
end.
----
== See also
link:man:cowboy(7)[cowboy(7)],
link:man:cowboy_router(3)[cowboy_router(3)]