aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2016-12-23 12:19:27 +0100
committerLoïc Hoguin <[email protected]>2016-12-23 12:19:27 +0100
commit98ae01b599fcaa91f0f66ca1218cdf6c3e28d3c4 (patch)
tree7509534060e7f74ed912f484735d6da609ea4a83 /doc/src
parent56e489f00aa60319febf78ebe121a5155e3bb4aa (diff)
downloadcowboy-98ae01b599fcaa91f0f66ca1218cdf6c3e28d3c4.tar.gz
cowboy-98ae01b599fcaa91f0f66ca1218cdf6c3e28d3c4.tar.bz2
cowboy-98ae01b599fcaa91f0f66ca1218cdf6c3e28d3c4.zip
Update the cowboy_static manual
Diffstat (limited to 'doc/src')
-rw-r--r--doc/src/manual/cowboy_static.asciidoc141
1 files changed, 119 insertions, 22 deletions
diff --git a/doc/src/manual/cowboy_static.asciidoc b/doc/src/manual/cowboy_static.asciidoc
index 658d93b..7a78660 100644
--- a/doc/src/manual/cowboy_static.asciidoc
+++ b/doc/src/manual/cowboy_static.asciidoc
@@ -2,40 +2,137 @@
== Name
-cowboy_static - static file handler
+cowboy_static - Static file handler
== Description
-The `cowboy_static` module implements file serving capabilities
-by using the REST semantics provided by `cowboy_rest`.
+The module `cowboy_static` implements file serving capabilities
+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]
----
-Option = {priv_file, atom(), string() | binary()}
- | {priv_file, atom(), string() | binary(), Extra}
- | {file, string() | binary()}
- | {file, string() | binary(), Extra}
- | {priv_dir, atom(), string() | binary()}
- | {priv_dir, atom(), string() | binary(), Extra}
- | {dir, string() | binary()}
- | {dir, string() | binary(), Extra}
+opts() :: {priv_file, App, Path}
+ | {priv_file, App, Path, Extra}
+ | {file, Path}
+ | {file, Path, Extra}
+ | {priv_dir, App, Path}
+ | {priv_dir, App, Path, Extra}
+ | {dir, Path}
+ | {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, binary() | {binary(), binary(), [{binary(), binary()}]}}
+Mimetypes :: {mimetypes, module(), function()}
+ | {mimetypes, binary() | ParsedMime}
+
+ParsedMime :: {Type :: binary(), SubType :: binary(), Params}
+Params :: [{Key :: binary(), Value :: binary()}]
+----
+
+Static handler configuration.
+
+priv_file::
+
+Send a file.
++
+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()
----
-Configuration for the static handler.
+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.
+----
-The handler can be configured for sending either one file or
-a directory (including its subdirectories).
+== See also
-Extra options allow you to define how the etag should be calculated
-and how the mimetype of files should be detected.
+link:man:cowboy(7)[cowboy(7)],
+link:man:cowboy_router(3)[cowboy_router(3)]