summaryrefslogtreecommitdiffstats
path: root/docs/en/cowboy/2.3/guide/static_files/index.html
diff options
context:
space:
mode:
authorLoïc Hoguin <[email protected]>2018-04-04 13:13:37 +0200
committerLoïc Hoguin <[email protected]>2018-04-04 13:13:37 +0200
commitd2a3f2cedd7c00d0933222aed9c06b3149aa4db4 (patch)
tree4f1499bac639c782b250af0fbf0dec2064315813 /docs/en/cowboy/2.3/guide/static_files/index.html
parent1d654719f5fa6be67d2c95145872068665702cb7 (diff)
downloadninenines.eu-d2a3f2cedd7c00d0933222aed9c06b3149aa4db4.tar.gz
ninenines.eu-d2a3f2cedd7c00d0933222aed9c06b3149aa4db4.tar.bz2
ninenines.eu-d2a3f2cedd7c00d0933222aed9c06b3149aa4db4.zip
Cowboy 2.3.0
Diffstat (limited to 'docs/en/cowboy/2.3/guide/static_files/index.html')
-rw-r--r--docs/en/cowboy/2.3/guide/static_files/index.html334
1 files changed, 334 insertions, 0 deletions
diff --git a/docs/en/cowboy/2.3/guide/static_files/index.html b/docs/en/cowboy/2.3/guide/static_files/index.html
new file mode 100644
index 00000000..04110d37
--- /dev/null
+++ b/docs/en/cowboy/2.3/guide/static_files/index.html
@@ -0,0 +1,334 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+ <meta charset="utf-8">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0">
+ <meta name="description" content="">
+ <meta name="author" content="Loïc Hoguin based on a design from (Soft10) Pol Cámara">
+
+ <meta name="generator" content="Hugo 0.37.1" />
+
+ <title>Nine Nines: Static files</title>
+
+ <link href='https://fonts.googleapis.com/css?family=Open+Sans:400,700,400italic' rel='stylesheet' type='text/css'>
+ <link href="/css/99s.css?r=1" rel="stylesheet">
+
+ <link rel="shortcut icon" href="/img/ico/favicon.ico">
+ <link rel="apple-touch-icon-precomposed" sizes="114x114" href="/img/ico/apple-touch-icon-114.png">
+ <link rel="apple-touch-icon-precomposed" sizes="72x72" href="/img/ico/apple-touch-icon-72.png">
+ <link rel="apple-touch-icon-precomposed" href="/img/ico/apple-touch-icon-57.png">
+
+
+</head>
+
+
+<body class="">
+ <header id="page-head">
+ <div id="topbar" class="container">
+ <div class="row">
+ <div class="span2">
+ <h1 id="logo"><a href="/" title="99s">99s</a></h1>
+ </div>
+ <div class="span10">
+
+ <div id="side-header">
+ <nav>
+ <ul>
+ <li><a title="Hear my thoughts" href="/articles">Articles</a></li>
+ <li><a title="Watch my talks" href="/talks">Talks</a></li>
+ <li class="active"><a title="Read the docs" href="/docs">Documentation</a></li>
+ <li><a title="Request my services" href="/services">Consulting & Training</a></li>
+ </ul>
+ </nav>
+ <ul id="social">
+ <li>
+ <a href="https://github.com/ninenines" title="Check my Github repositories"><img src="/img/ico_github.png" data-hover="/img/ico_github_alt.png" alt="Github"></a>
+ </li>
+ <li>
+ <a title="Keep in touch!" href="http://twitter.com/lhoguin"><img src="/img/ico_microblog.png" data-hover="/img/ico_microblog_alt.png"></a>
+ </li>
+ <li>
+ <a title="Contact me" href="mailto:[email protected]"><img src="/img/ico_mail.png" data-hover="/img/ico_mail_alt.png"></a>
+ </li>
+ </ul>
+ </div>
+ </div>
+ </div>
+ </div>
+
+
+</header>
+
+<div id="contents" class="two_col">
+<div class="container">
+<div class="row">
+<div id="docs" class="span9 maincol">
+
+<h1 class="lined-header"><span>Static files</span></h1>
+
+<div class="paragraph"><p>Cowboy comes with a ready to use handler for serving static
+files. It is provided as a convenience for serving files
+during development.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>The static handler can serve either one file or all files
+from a given directory. The etag generation and mime types
+can be configured.</p></div>
+<div class="sect1">
+<h2 id="_serve_one_file">Serve one file</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>You can use the static handler to serve one specific file
+from an application&#8217;s private directory. This is particularly
+useful to serve an <em>index.html</em> file when the client requests
+the <code>/</code> path, for example. The path configured is relative
+to the given application&#8217;s private directory.</p></div>
+<div class="paragraph"><p>The following rule will serve the file <em>static/index.html</em>
+from the application <code>my_app</code>'s priv directory whenever the
+path <code>/</code> is accessed:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>}}</tt></pre></div></div>
+<div class="paragraph"><p>You can also specify the absolute path to a file, or the
+path to the file relative to the current directory:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">file</span>, <span style="color: #FF0000">"/var/www/index.html"</span>}}</tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_serve_all_files_from_a_directory">Serve all files from a directory</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>You can also use the static handler to serve all files that
+can be found in the configured directory. The handler will
+use the <code>path_info</code> information to resolve the file location,
+which means that your route must end with a <code>[...]</code> pattern
+for it to work. All files are served, including the ones that
+may be found in subfolders.</p></div>
+<div class="paragraph"><p>You can specify the directory relative to an application&#8217;s
+private directory.</p></div>
+<div class="paragraph"><p>The following rule will serve any file found in the application
+<code>my_app</code>'s priv directory inside the <code>static/assets</code> folder
+whenever the requested path begins with <code>/assets/</code>:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>}}</tt></pre></div></div>
+<div class="paragraph"><p>You can also specify the absolute path to the directory or
+set it relative to the current directory:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">dir</span>, <span style="color: #FF0000">"/var/www/assets"</span>}}</tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_customize_the_mimetype_detection">Customize the mimetype detection</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>By default, Cowboy will attempt to recognize the mimetype
+of your static files by looking at the extension.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>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:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
+ [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">web</span>}]}}</tt></pre></div></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>To use the function that will detect almost any mimetype,
+the following configuration will do:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
+ [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">all</span>}]}}</tt></pre></div></div>
+<div class="paragraph"><p>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:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
+ [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div>
+<div class="paragraph"><p>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&#8217;t figure out the mimetype,
+then it should return <code>{&lt;&lt;"application"&gt;&gt;, &lt;&lt;"octet-stream"&gt;&gt;, []}</code>.</p></div>
+<div class="paragraph"><p>When the static handler fails to find the extension,
+it will send the file as <code>application/octet-stream</code>.
+A browser receiving such file will attempt to download it
+directly to disk.</p></div>
+<div class="paragraph"><p>Finally, the mimetype can be hard-coded for all files.
+This is especially useful in combination with the <code>file</code>
+and <code>priv_file</code> options as it avoids needless computation:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>,
+ [{<span style="color: #FF6600">mimetypes</span>, {<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"text"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"html"</span><span style="color: #990000">&gt;&gt;</span>, []}}]}}</tt></pre></div></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_generate_an_etag">Generate an etag</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>You can however change the way the etag is calculated:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
+ [{<span style="color: #FF6600">etag</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div>
+<div class="paragraph"><p>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.</p></div>
+<div class="paragraph"><p>You can also completely disable etag handling:</p></div>
+<div class="listingblock">
+<div class="content"><!-- Generator: GNU source-highlight
+by Lorenzo Bettini
+http://www.lorenzobettini.it
+http://www.gnu.org/software/src-highlite -->
+<pre><tt>{<span style="color: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
+ [{<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>}]}}</tt></pre></div></div>
+</div>
+</div>
+
+
+
+
+
+
+
+
+
+
+ <nav style="margin:1em 0">
+
+ <a style="float:left" href="https://ninenines.eu/docs/en/cowboy/2.3/guide/loop_handlers/">
+ Loop handlers
+ </a>
+
+
+
+ <a style="float:right" href="https://ninenines.eu/docs/en/cowboy/2.3/guide/req/">
+ The Req object
+ </a>
+
+ </nav>
+
+
+
+
+</div>
+
+<div class="span3 sidecol">
+
+
+<h3>
+ Cowboy
+ 2.3
+
+ User Guide
+</h3>
+
+<ul>
+
+ <li><a href="/docs/en/cowboy/2.3/guide">User Guide</a></li>
+
+
+ <li><a href="/docs/en/cowboy/2.3/manual">Function Reference</a></li>
+
+
+</ul>
+
+<h4 id="docs-nav">Navigation</h4>
+
+<h4>Version select</h4>
+<ul>
+
+
+
+ <li><a href="/docs/en/cowboy/2.3/guide">2.3</a></li>
+
+ <li><a href="/docs/en/cowboy/2.2/guide">2.2</a></li>
+
+ <li><a href="/docs/en/cowboy/2.1/guide">2.1</a></li>
+
+ <li><a href="/docs/en/cowboy/2.0/guide">2.0</a></li>
+
+ <li><a href="/docs/en/cowboy/1.0/guide">1.0</a></li>
+
+</ul>
+
+</div>
+</div>
+</div>
+</div>
+
+ <footer>
+ <div class="container">
+ <div class="row">
+ <div class="span6">
+ <p id="scroll-top"><a href="#">↑ Scroll to top</a></p>
+ <nav>
+ <ul>
+ <li><a href="mailto:[email protected]" title="Contact us">Contact us</a></li><li><a href="https://github.com/ninenines/ninenines.github.io" title="Github repository">Contribute to this site</a></li>
+ </ul>
+ </nav>
+ </div>
+ <div class="span6 credits">
+ <p><img src="/img/footer_logo.png"></p>
+ <p>Copyright &copy; Loïc Hoguin 2012-2016</p>
+ </div>
+ </div>
+ </div>
+ </footer>
+
+
+ <script src="/js/custom.js"></script>
+ </body>
+</html>
+
+