2015-1-22【erlang】Cowboy学习记录-关于Static files章节

Static files

Cowboy comes with a special handler built as a REST handler and designed specifically for serving static files. It is provided as a convenience and provides a quick solution for serving files during development.

For systems in production, consider using one of the many Content Distribution Network (CDN) available on the market, as they are the best solution for serving files. They are covered in the next chapter. If you decide against using a CDN solution, then please look at the chapter after that, as it explains how to efficiently serve static files on your own.

The static handler can serve either one file or all files from a given directory. It can also send etag headers for client-side caching.

To use the static file handler, simply add routes for it with the appropriate options.

翻译：

Cowboy有一个特殊的handler，是REST类型的handler，是特别设计用来serve static files的。在开发中，这是一种方便且快捷的方法来serve files。

在生产系统中，可以考虑使用市场上的诸多的CDN一款，因为CDN是用于serve files的最佳解决方案。在下一章节中将对此有所介绍。如果不想利用CDN，则可以看CDN的下下章，用自己的方式解决高效率serve files的问题。

static handler可以 serve一个或全部文件。也可以发送一个etag头给客户端的缓存用。

为了使用staic file handler，只要加上有合适选项的route即可。

Serve one file

You can use the static handler to serve one specific file from an application's private directory. This is particularly useful to serve an index.html file when the client requests the / path, for example. The path configured is relative to the given application's private directory.

The following rule will serve the file static/index.html from the application my_app's priv directory whenever the path / is accessed.

{"/", cowboy_static, {priv_file, my_app, "static/index.html"}}<code class="erlang plain"></code>

You can also specify the absolute path to a file, or the path to the file relative to the current directory.

{"/", cowboy_static, {file, "/var/www/index.html"}}

翻译：

在应用的private目录下，可以用static handler来serve 一个特定的file.比如，当客户端请求 / 目录时，可以用来serve index.html文件，这是非常有效的。

当任何时候客户端访问 / 时，下面的规则将在应用my_app的priv目录下，serve 文件 static/index.html（即客户端访问 / 时， 提供 my_app的priv目录下的static/index.html文件给客户端吗？）

也可以在规则中指定绝对路径或者相对路径

{"/", cowboy_static, {file, "/var/www/index.html"}}

Serve all files from a directory

You can also use the static handler to serve all files that can be found in the configured directory. The handler will use the path_info information to resolve the file location, which means that your route must end with a [...] pattern for it to work. All files are served, including the ones that may be found in subfolders.

You can specify the directory relative to an application's private directory.

The following rule will serve any file found in the application my_app's priv directory inside the static/assets folder whenever the requested path begins with /assets/.

{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets"}}

You can also specify the absolute path to the directory or set it relative to the current directory.

{"/assets/[...]", cowboy_static, {dir, "/var/www/assets"}}

翻译：

亦可以用static handler来serve在配置目录下的所有文件。handler可以利用path_info信息来解析文件位置，这意味着route中必须以[...]结尾。

可以指定相对于程序priv的目录的路径。

当请求路径以/assets/开头，则下面的规则会serve在应用my_app的priv的static/assets文件夹下的所有文件。

{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets"}}

也可以指定绝对路径或相对路径

{"/assets/[...]", cowboy_static, {dir, "/var/www/assets"}}

Customize the mimetype detection

By default, Cowboy will attempt to recognize the mimetype of your static files by looking at the extension.

翻译：

默认，Cowboy会根据文件的后缀来判断静态文件的minetype是什么。

You can override the function that figures out the mimetype of the static files. It can be useful when Cowboy is missing a mimetype you need to handle, or when you want to reduce the list to make lookups faster. You can also give a hard-coded mimetype that will be used unconditionally.

翻译：

可以重写关于解析mimetype的函数。当Cowboy漏掉某项mimetype的解析时会有用，或则当你想为了查询更快而减小列表时。也可以提供一个硬编码的mimetype类型。

Cowboy comes with two functions built-in. The default function only handles common file types used when building Web applications. The other function is an extensive list of hundreds of mimetypes that should cover almost any need you may have. You can of course create your own function.

翻译：

Cowboy有两个针对mimetype有两个内建函数。当构建Web程序时，默认的函数只处理常见的文件类型。另外一个处理一个扩展有上千个mimetypes的列表，当然可以构建自己的函数。

To use the default function, you should not have to configure anything, as it is the default. If you insist, though, the following will do the job.

{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
    [{mimetypes, cow_mimetypes, web}]}}

翻译：

使用默认函数，不需要做任何配置。如果非得设置，则可以参考下面

{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
    [{mimetypes, cow_mimetypes, <span style="color:#FF0000;"><strong>web</strong></span>}]}}

As you can see, there is an optional field that may contain a list of less used options, like mimetypes or etag. All option types have this optional field.

翻译：

正如你看到的，最后一项有一个可选的域，可以包含一个不怎么用到的选项列表，比如mimetypes或则etag,全部的可选类型都有这么一个可选的域。

To use the function that will detect almost any mimetype, the following configuration will do.（要探测几乎全部的mimetype,将上面的web改成all即可）

{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
    [{mimetypes, cow_mimetypes, <span style="color:#FF0000;"><strong>all</strong></span>}]}}

You probably noticed the pattern by now. The configuration expects a module and a function name, so you can use any of your own functions instead.
翻译：或许你已经意识到了模式现在。这个configuration期望一个module和一个funaction名字，所以可以使用自己的任意函数。

{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
    [{mimetypes, Module, Function}]}}

The function that performs the mimetype detection receives a single argument that is the path to the file on disk. It is recommended to return the mimetype in tuple form, although a binary string is also allowed (but will require extra processing). If the function can't figure out the mimetype, then it should return {<<"application">>, <<"octet-stream">>, []}.

翻译：

用于mimetype探测的函数会收到一个单一的参数，即磁盘上的文件路径。最好以元组的形式返回mimetype，经过一个二进制字符串形式也是允许，但是需要特别的处理。如果函数不能探测出mimetype类型，则应该返回{<<"application">>, <<"octet-stream">>, []}.

When the static handler fails to find the extension in the list, it will send the file as application/octet-stream. A browser receiving such file will attempt to download it directly to disk.

翻译：

当static handler在列表中无法找到后缀时，会发送一个appliaction/octet-stream文件。浏览器收到这样的文件时，则会尝试直接将其下载到磁盘上。

Finally, the mimetype can be hard-coded for all files. This is especially useful in combination with the file and priv_file options as it avoids needless computation.

翻译：

最后，mimetype也是可以替所有文件硬编码。

{"/", cowboy_static, {priv_file, my_app, "static/index.html",
    [{mimetypes, {<<"text">>, <<"html">>, []}}]}}

Generate an etag

By default, the static handler will generate an etag header value based on the size and modified time. This solution can not be applied to all systems though. It would perform rather poorly over a cluster of nodes, for example, as the file metadata will vary from server to server, giving a different etag on each server.

翻译：

默认情况，static handler会基于文件大小和修改时间来产生etag,尽管刚解决方法不能应用于全部的系统。

再集群系统上将会变现不好，比如，文件的metadata再服务器之间都是不同的，会再不同的server上产生不同的etag

You can however change the way the etag is calculated.

{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
    [{etag, Module, Function}]}}

This function will receive three arguments: the path to the file on disk, the size of the file and the last modification time. In a distributed setup, you would typically use the file path to retrieve an etag value that is identical across all your servers.

翻译；

函数会接受三个参数，文件在磁盘上的路径，文件大小和最后的修改时间。在分布式中，典型的时用文件路径去获取一个再服务器集群中唯一的etag值。

You can also completely disable etag handling.

翻译：

也可以完全关闭掉etag的处理。

{"/assets/[...]", cowboy_static, {priv_dir, my_app, "static/assets",
    [{etag, false}]}}