aboutsummaryrefslogtreecommitdiffstats
path: root/doc/src/manual/cowboy_static.asciidoc
blob: 0e131dd1e0328b99bae552b2bea35543a9e2462c (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
= cowboy_static(3)

== Name

cowboy_static - Static file handler

== Description

The module `cowboy_static` implements file serving capabilities
using the REST semantics provided by `cowboy_rest`.

The static file handler is a pre-written handler coming with
Cowboy. To serve files, use it in your routes.

== Options

[source,erlang]
----
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}

App        :: atom()
Path       :: binary() | string()
Extra      :: [Charset | Etag | Mimetypes]

Charset    :: {charset, module(), function()}
            | {charset, binary()}

Etag       :: {etag, module(), function()}
            | {etag, false}

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 not send a charset with
the response. You can provide a specific charset that will
be used for all files using the text media type, or provide
a module and function that will be called when needed:

[source,erlang]
----
detect_charset(Path :: binary()) -> Charset :: binary()
----

A charset must always be returned even if it doesn't make
sense considering the media type of the file. A good default
is `<<"utf-8">>`.

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()}]
----

// @todo Case sensitivity of parsed mime content?

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

* *2.6*: The `charset` extra option was added.
* *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)]