add doc for the handling of trailing / #820 and file.file #822

h2o · Mar 14, 2016 · bc99a50 · bc99a50
1 parent c57f955
commit bc99a50
Show file tree

Hide file tree

Showing 5 changed files with 101 additions and 5 deletions.
diff --git a/doc/configure/base_directives.html b/doc/configure/base_directives.html
@@ -82,7 +82,7 @@ <h3><a href="configure/base_directives.html#hosts"><code>"hosts"</code></a></h3>
 Otherwise, the entry will match the requests targetting the specified port.
 </p>
 <p>
-Wildcard character <code>*</code> can be used as the first component of the hostname.
+Since version 1.7, a wildcard character <code>*</code> can be used as the first component of the hostname.
 If used, they are matched using the rule defined in <a href="https://tools.ietf.org/html/rfc2818#section-3.1" target="_blank">RFC 2818 Section 3.1</a>.
 For example, <code>*.example.com</code> will match HTTP requests for both <code>foo.example.com</code> and <code>bar.example.com</code>.
 Note that an exact match is preferred over host definitions using wildcard characters.
@@ -147,6 +147,15 @@ <h3><a href="configure/base_directives.html#paths"><code>"paths"</code></a></h3>
 </code></pre>
 </div>
 
+<p>
+In releases prior to version 2.0, all the path entries are considered as directories.
+When H2O receives a request that exactly matches to an entry in paths that does not end with a slash, the server always returns a 301 redirect that appends a slash.
+</p>
+<p>
+Since 2.0, it depends on the handler of the path whether if a 301 redirect that appends a slash is returned.
+Server administartors can take advantage of this change to define per-path configurations (see the examples in <a href="configure/file_directives.html#file.file"><code>file.file</code></a> and the <a href="configure/fastcgi_directives.html#proxy.reverse.url">FastCGI handler</a>).
+<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> is an exception that continues to perform the redirection; in case of the example above, access to <code>/assets</code> is redirected to <code>/assets/<code>.
+</p>
 
 </dd>
 <dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>

diff --git a/doc/configure/file_directives.html b/doc/configure/file_directives.html
@@ -59,7 +59,11 @@ <h2>
 
 
 <p>
-This document describes the configuration directives of the file handler.
+This document describes the configuration directives of the file handler - a handler that for serving static files.
+</p>
+<p>
+Two directives: <a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> and <a href="configure/file_directives.html#file.file"><code>file.file</code></a> are used to define the mapping.
+Other directives modify the behavior of the mappings defined by the two.
 </p>
 
 <div id="file.custom-handler" class="directive-head">
@@ -119,6 +123,11 @@ <h3><a href="configure/file_directives.html#file.dir"><code>"file.dir"</code></a
 </dd>
 <dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
 <dd>path</dd>
+<dt>See also:</dt>
+<dd><a href="configure/file_directives.html#file.dirlisting"><code>file.dirlisting</code></a>,
+<a href="configure/file_directives.html#file.file"><code>file.file</code></a>,
+<a href="configure/file_directives.html#file.dirlisting"><code>file.index</code></a>
+</dd>
 </dl>
 
 <div id="file.dirlisting" class="directive-head">
@@ -138,6 +147,9 @@ <h3><a href="configure/file_directives.html#file.dirlisting"><code>"file.dirlist
 <dd>global, host, path</dd>
 <dt>Default:</dt>
 <dd><code><pre>file.dirlisting: OFF</pre></code>
+<dt>See also:</dt>
+<dd><a href="configure/file_directives.html#file.dir"><code>file.dir</code></a>
+</dd>
 </dl>
 <div id="file.etag" class="directive-head">
 <h3><a href="configure/file_directives.html#file.etag"><code>"file.etag"</code></a></h3>
@@ -159,6 +171,35 @@ <h3><a href="configure/file_directives.html#file.etag"><code>"file.etag"</code><
 </dl>
 
 
+<div id="file.file" class="directive-head">
+<div class="directive-since">since v2.0</div>
+<h3><a href="configure/file_directives.html#file.file"><code>"file.file"</code></a></h3>
+</div>
+
+<dl class="directive-desc">
+<dt>Description:</dt>
+<dd>
+<p>
+The directive maps a path to a specific file.
+</p>
+
+<div class="example">
+<div class="caption">Example. Mapping a path to a specific file</div>
+<pre><code>paths:
+  /robots.txt:
+    file.file: /path/to/robots.txt
+</code></pre>
+</div>
+
+
+</dd>
+<dt><a href="configure/syntax_and_structure.html#config_levels">Level</a>:</dt>
+<dd>path</dd>
+<dt>See also:</dt>
+<dd><a href="configure/file_directives.html#file.dir"><code>file.dir</code></a>
+</dd>
+</dl>
+
 <div id="file.index" class="directive-head">
 <h3><a href="configure/file_directives.html#file.index"><code>"file.index"</code></a></h3>
 </div>
@@ -179,6 +220,9 @@ <h3><a href="configure/file_directives.html#file.index"><code>"file.index"</code
 <dd>global, host, path</dd>
 <dt>Default:</dt>
 <dd><code><pre>file.index: [ &#39;index.html&#39;, &#39;index.htm&#39;, &#39;index.txt&#39; ]</pre></code>
+<dt>See also:</dt>
+<dd><a href="configure/file_directives.html#file.dir"><code>file.dir</code></a>
+</dd>
 </dl>
 
 <div id="file.mime.addtypes" class="directive-head">

diff --git a/doc/search/searchindex.js b/doc/search/searchindex.js
diff --git a/srcdoc/configure/base_directives.mt b/srcdoc/configure/base_directives.mt
@@ -21,7 +21,7 @@ When <code>port</code> is omitted, the entry will match the requests targetting
 Otherwise, the entry will match the requests targetting the specified port.
 </p>
 <p>
-Wildcard character <code>*</code> can be used as the first component of the hostname.
+Since version 1.7, a wildcard character <code>*</code> can be used as the first component of the hostname.
 If used, they are matched using the rule defined in <a href="https://tools.ietf.org/html/rfc2818#section-3.1" target="_blank">RFC 2818 Section 3.1</a>.
 For example, <code>*.example.com</code> will match HTTP requests for both <code>foo.example.com</code> and <code>bar.example.com</code>.
 Note that an exact match is preferred over host definitions using wildcard characters.
@@ -74,6 +74,15 @@ hosts:
         file.dir: /path/to/assets
 EOT
 ?>
+<p>
+In releases prior to version 2.0, all the path entries are considered as directories.
+When H2O receives a request that exactly matches to an entry in paths that does not end with a slash, the server always returns a 301 redirect that appends a slash.
+</p>
+<p>
+Since 2.0, it depends on the handler of the path whether if a 301 redirect that appends a slash is returned.
+Server administartors can take advantage of this change to define per-path configurations (see the examples in <a href="configure/file_directives.html#file.file"><code>file.file</code></a> and the <a href="configure/fastcgi_directives.html#proxy.reverse.url">FastCGI handler</a>).
+<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> is an exception that continues to perform the redirection; in case of the example above, access to <code>/assets</code> is redirected to <code>/assets/<code>.
+</p>
 ? })
 
 <?

diff --git a/srcdoc/configure/file_directives.mt b/srcdoc/configure/file_directives.mt
@@ -2,7 +2,11 @@
 ? $_mt->wrapper_file("wrapper.mt", "Configure", "File Directives")->(sub {
 
 <p>
-This document describes the configuration directives of the file handler.
+This document describes the configuration directives of the file handler - a handler that for serving static files.
+</p>
+<p>
+Two directives: <a href="configure/file_directives.html#file.dir"><code>file.dir</code></a> and <a href="configure/file_directives.html#file.file"><code>file.file</code></a> are used to define the mapping.
+Other directives modify the behavior of the mappings defined by the two.
 </p>
 
 <?
@@ -32,6 +36,11 @@ $ctx->{directive}->(
     name    => "file.dir",
     levels  => [ qw(path) ],
     desc    => q{The directive specifies the directory under which should be served for the corresponding path.},
+    see_also => render_mt(<<EOT),
+<a href="configure/file_directives.html#file.dirlisting"><code>file.dirlisting</code></a>,
+<a href="configure/file_directives.html#file.file"><code>file.file</code></a>,
+<a href="configure/file_directives.html#file.dirlisting"><code>file.index</code></a>
+EOT
 )->(sub {
 ?>
 <?= $ctx->{example}->('Serving files under different paths', <<'EOT')
@@ -51,6 +60,9 @@ $ctx->{directive}->(
     default => 'file.dirlisting: OFF',
     desc    => <<'EOT',
 A boolean flag (<code>OFF</code>, or <code>ON</code>) specifying whether or not to send the directory listing in case none of the index files exist.
+EOT
+    see_also => render_mt(<<EOT),
+<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a>
 EOT
 )->(sub {});
 
@@ -64,12 +76,34 @@ EOT
 )->(sub {});
 ?>
 
+<?
+$ctx->{directive}->(
+    name     => "file.file",
+    levels   => [ qw(path) ],
+    desc     => q{The directive maps a path to a specific file.},
+    see_also => render_mt(<<EOT),
+<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a>
+EOT
+    since    => '2.0',
+)->(sub {
+?>
+<?= $ctx->{example}->('Mapping a path to a specific file', <<'EOT')
+paths:
+  /robots.txt:
+    file.file: /path/to/robots.txt
+EOT
+?>
+? })
+
 <?
 $ctx->{directive}->(
     name    => "file.index",
     levels  => [ qw(global host path) ],
     default => "file.index: [ 'index.html', 'index.htm', 'index.txt' ]",
     desc    => q{Specifies the names of the files that should be served when the client sends a request against the directory.},
+    see_also => render_mt(<<EOT),
+<a href="configure/file_directives.html#file.dir"><code>file.dir</code></a>
+EOT
 )->(sub {
 ?>
 <p>