<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/content/features/url-rewrites.md - fork/static-web-server @ allow-symlink</title>
<meta name="description" content="docs/content/features/url-rewrites.md in fork/static-web-server at allow-symlink.">
<meta property="og:title" content="docs/content/features/url-rewrites.md - fork/static-web-server @ allow-symlink">
<meta property="og:description" content="docs/content/features/url-rewrites.md in fork/static-web-server at allow-symlink.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="allow-symlink" data-tip="4414610fe1b0370ff0ac415e9367548840584710">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/static-web-server</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/static-web-server</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Matthias Schoettle</span><span class="commit-message" data-commit="dd43d06551fcf853e0012381c76af5b832d23b57">refactor: format check support Markdown files via mdformat (#597)</span><span class="snapshot-sha sha" data-commit="dd43d06551fcf853e0012381c76af5b832d23b57">dd43d06</span><time datetime="2025-12-07T04:40:21-05:00" title="2025-12-07 04:40:21 -0500">2025-12-07</time></p>
<header class="topbar"><details class="switcher"><summary>allow-symlink</summary><div class="menu"><strong>branches</strong><a class="current" href="/fork/static-web-server/ref/allow-symlink/">allow-symlink</a><a class="all" href="/fork/static-web-server/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/static-web-server/">static-web-server</a> / <a href="/fork/static-web-server/ref/allow-symlink/tree/docs/">docs</a> / <a href="/fork/static-web-server/ref/allow-symlink/tree/docs/content/">content</a> / <a href="/fork/static-web-server/ref/allow-symlink/tree/docs/content/features/">features</a> / <span class="cur">url-rewrites.md</span></nav>
<span class="view-stats"><span>6.3 KiB</span><span>138 lines</span></span><span class="actions"><a class="raw" href="/fork/static-web-server/raw/e7fbf05a0753cd454e4188eb21fbeb8010742958/docs/content/features/url-rewrites.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1>URL Rewrites</h1>
<p><strong>SWS</strong> provides the ability to rewrite request URLs (routes) with Glob pattern-matching support.</p>
<p>URI rewrites are particularly useful with pattern matching (<a href="https://en.wikipedia.org/wiki/Glob_(programming)">globs</a>), as the server can accept any URL that matches the pattern and let the client-side code decide what to display.</p>
<h2>Structure</h2>
<p>URL rewrite rules should be defined mainly as an <a href="https://toml.io/en/v1.0.0#array-of-tables">Array of Tables</a>.</p>
<p>Each table entry should have two key/value pairs:</p>
<ul>
<li><code>source</code>: key containing a string <em>glob pattern</em>.</li>
<li><code>destination</code>: file path with optional replacements (placeholders).</li>
<li><code>redirect</code>: optional number containing the HTTP response code (redirection).</li>
</ul>
<p>!!! info "Note"</p>
<pre><code>The incoming request(s) will reach the `destination` only if the request(s) URI matches the `source` pattern.
</code></pre>
<h3>Source</h3>
<p>It's a <a href="https://en.wikipedia.org/wiki/Glob_(programming)">Glob pattern</a> that should match against the URI that is requesting a resource file.</p>
<p>The glob pattern functionality is powered by the <a href="https://docs.rs/globset/latest/globset/">globset</a> crate which supports Standard Unix-style glob syntax.</p>
<p>!!! tip "Glob pattern syntax"</p>
<pre><code>For more details about the Glob pattern syntax check out https://docs.rs/globset/latest/globset/#syntax
</code></pre>
<p>!!! warning "Matching of path separator in <code>*</code>"</p>
<pre><code>Up to version `2.33.1` the wildcard `*` was matching the path separator.
For example, `/{*}/{*}/` matched `/assets/images/logo/`.

In later versions, the default has changed such that `*` does not match the path separator.
</code></pre>
<h3>Destination</h3>
<p>The value should be a relative or absolute URL. A relative URL could look like <code>/some/directory/file.html</code>. An absolute URL can be <code>https://external.example.com/</code> for example.</p>
<h4>Replacements</h4>
<p>Additionally, a <code>destination</code> supports replacements for every Glob pattern group that matches against the <code>source</code>.</p>
<p>Replacements order start from <code>0</code> to <code>n</code> and are defined with a dollar sign followed by an index (Glob pattern group occurrence).</p>
<p>!!! tip "Group your Glob patterns"</p>
<pre><code>When using replacements, also group your Glob pattern by surrounding them with curly braces so every group should map to its corresponding replacement.&lt;br&gt;
For example: `source = "**/{*}.{png,gif}"`
</code></pre>
<h4>Destination processing</h4>
<p>How destination is processed depends on whether the <code>redirect</code> key (see below) is present. If it is present, SWS will perform an <em>external</em> redirect. It will send a redirect response to the client, and the browser will usually proceed to the destination. In case of a relative URL, it will be another page on the same server. An absolute URL can result in navigation to another server.</p>
<p>Without a <code>redirect</code> key, SWS will perform an <em>internal</em> redirect. It will attempt to retrieve the file denoted by the destination and send it to the client. While it is possible to specify an absolute URL here as well, it will always be processed by the same SWS instance. It will result by the request being mapped to a different <a href="/fork/static-web-server/ref/allow-symlink/blob/docs/content/features/virtual-hosting.md">virtual host</a> however if a matching virtual host is present.</p>
<h4>Different roots within the same virtual host</h4>
<p>Normally, different root directories are only possible with different virtual hosts. Rewrites however allow exposing another root in a subdirectory for example. For that, you add an internal virtual host that isn't normally visible from outside, e.g. <code>internal.local</code>. You then rewrite the requests to the subdirectory to the internal virtual host. For example:</p>
<pre class="language-toml"><a-p>[</a-p><a-pr>general</a-pr><a-p>]</a-p>
<a-pr>root</a-pr> <a-o>=</a-o> <a-s>&quot;/usr/srv/www&quot;</a-s>

<a-p>[</a-p><a-pr>advanced</a-pr><a-p>]</a-p>

<a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>rewrites</a-pr><a-p>]]</a-p>
<a-pr>source</a-pr> <a-o>=</a-o> <a-s>&quot;/test/{**}&quot;</a-s>
<a-pr>destination</a-pr> <a-o>=</a-o> <a-s>&quot;http://internal.local/test/$1&quot;</a-s>

<a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>virtual-hosts</a-pr><a-p>]]</a-p>
<a-pr>host</a-pr> <a-o>=</a-o> <a-s>&quot;internal.local&quot;</a-s>
<a-pr>root</a-pr> <a-o>=</a-o> <a-s>&quot;/usr/srv/alternative-root&quot;</a-s></pre>
<p>A request to <code>/index.html</code> will be mapped to <code>/usr/srv/www/index.html</code>, yet <code>/test/hi.txt</code> will be mapped to the file <code>/usr/srv/alternative-root/test/hi.txt</code>.</p>
<p>This approach has two caveats:</p>
<ol>
<li>When SWS produces redirects (e.g. redirecting <code>http://internal.local/test/subdir</code> to <code>http://internal.local/test/subdir/</code>), it isn't aware of rewrites. Unless the path part of the URL is identical before and after rewrite (like in the example above), this will result in broken redirects.</li>
<li>While the <code>internal.local</code> virtual host isn't normally accessed directly, this doesn't mean that it isn't possible for someone knowing (or guessing) its name. You should consider all files under the virtual host's root as public. Don't put any secrets in it even if these aren't accessible via rewrites.</li>
</ol>
<h3>Redirect</h3>
<p>An optional number that indicates the HTTP response code (redirect).
The values can be:</p>
<ul>
<li><code>301</code> for "Moved Permanently"</li>
<li><code>302</code> for "Found" (Temporary Redirect)</li>
</ul>
<h2>Examples</h2>
<pre class="language-toml"><a-p>[</a-p><a-pr>advanced</a-pr><a-p>]</a-p>

<a-c>### URL Rewrites</a-c>

<a-c># a. Simple route rewrite example</a-c>
<a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>rewrites</a-pr><a-p>]]</a-p>
<a-pr>source</a-pr> <a-o>=</a-o> <a-s>&quot;**/*.{png,ico,gif}&quot;</a-s>
<a-pr>destination</a-pr> <a-o>=</a-o> <a-s>&quot;/assets/generic1.png&quot;</a-s>

<a-c># b. Route rewrite example with redirection</a-c>
<a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>rewrites</a-pr><a-p>]]</a-p>
<a-pr>source</a-pr> <a-o>=</a-o> <a-s>&quot;**/*.{jpg,jpeg}&quot;</a-s>
<a-pr>destination</a-pr> <a-o>=</a-o> <a-s>&quot;/images/generic2.png&quot;</a-s>
<a-c>## NOTE: `redirect` can be omitted too</a-c>
<a-pr>redirect</a-pr> <a-o>=</a-o> <a-n>301</a-n>

<a-c># c. Route rewrite example with destination replacements</a-c>
<a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>rewrites</a-pr><a-p>]]</a-p>
<a-c>## Note that we&#39;re using curly braces to group the `*` wildcard.</a-c>
<a-c>## See https://docs.rs/globset/latest/globset/#syntax</a-c>
<a-pr>source</a-pr> <a-o>=</a-o> <a-s>&quot;**/{*}.{png,gif}&quot;</a-s>
<a-c>## For example, the destination will result in `/assets/abcdef.png`</a-c>
<a-pr>destination</a-pr> <a-o>=</a-o> <a-s>&quot;/assets/$1.$2&quot;</a-s></pre>
<p>If you request something like:</p>
<pre class="language-bash"><a-f>curl</a-f> <a-co>-I</a-co> http://localhost/abcdef.png</pre>
<p>Then the server logs should look something like this:</p>
<pre>2023-07-08T20:31:36.606035Z  INFO static_web_server::handler: incoming request: method=HEAD uri=/abcdef.png
2023-07-08T20:31:36.608439Z DEBUG static_web_server::handler: url rewrites glob patterns: [&quot;$0&quot;, &quot;$1&quot;, &quot;$2&quot;]
2023-07-08T20:31:36.608491Z DEBUG static_web_server::handler: url rewrites regex equivalent: (?-u)^(?:/?|.*/)(?:[^/]*)\.(?:gif|png)$
2023-07-08T20:31:36.608525Z DEBUG static_web_server::handler: url rewrites glob pattern captures: [&quot;abcdef.png&quot;, &quot;abcdef&quot;, &quot;png&quot;]
2023-07-08T20:31:36.608561Z DEBUG static_web_server::handler: url rewrites glob pattern destination: &quot;/assets/$1.$2&quot;
2023-07-08T20:31:36.609655Z DEBUG static_web_server::handler: url rewrites glob patterns destination replaced: &quot;/assets/abcdef.png&quot;
2023-07-08T20:31:36.609735Z TRACE static_web_server::static_files: dir: base=&quot;public&quot;, route=&quot;assets/abcdef.png&quot;
...
</pre>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>URL Rewrites</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">**SWS** provides the ability to rewrite request URLs (routes) with Glob pattern-matching support.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">URI rewrites are particularly useful with pattern matching ([globs](&lt;https://en.wikipedia.org/wiki/Glob_(programming)&gt;)), as the server can accept any URL that matches the pattern and let the client-side code decide what to display.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-p>##</a-p> <a-tt>Structure</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">URL rewrite rules should be defined mainly as an [Array of Tables](https://toml.io/en/v1.0.0#array-of-tables).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">Each table entry should have two key/value pairs:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"><a-p>- </a-p>`source`: key containing a string _glob pattern_.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"><a-p>- </a-p>`destination`: file path with optional replacements (placeholders).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"><a-p>- </a-p>`redirect`: optional number containing the HTTP response code (redirection).</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"><a-p>!!! info &quot;Note&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"><a-tl>    The incoming request(s) will reach the `destination` only if the request(s) URI matches the `source` pattern.</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"><a-p>### </a-p><a-tt>Source</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>It&#39;s a [Glob pattern](&lt;https://en.wikipedia.org/wiki/Glob_(programming)&gt;) that should match against the URI that is requesting a resource file.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>The glob pattern functionality is powered by the [globset](https://docs.rs/globset/latest/globset/) crate which supports Standard Unix-style glob syntax.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"><a-p>!!! tip &quot;Glob pattern syntax&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"><a-tl>    For more details about the Glob pattern syntax check out https://docs.rs/globset/latest/globset/#syntax</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>!!! warning &quot;Matching of path separator in `*`&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-tl>    Up to version `2.33.1` the wildcard `*` was matching the path separator.</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>    </a-p><a-tl>For example, `/{*}/{*}/` matched `/assets/images/logo/`.</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-tl>    In later versions, the default has changed such that `*` does not match the path separator.</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>### </a-p><a-tt>Destination</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>The value should be a relative or absolute URL. A relative URL could look like `/some/directory/file.html`. An absolute URL can be `https://external.example.com/` for example.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>#### </a-p><a-tt>Replacements</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>Additionally, a `destination` supports replacements for every Glob pattern group that matches against the `source`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>Replacements order start from `0` to `n` and are defined with a dollar sign followed by an index (Glob pattern group occurrence).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>!!! tip &quot;Group your Glob patterns&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-tl>    When using replacements, also group your Glob pattern by surrounding them with curly braces so every group should map to its corresponding replacement.&lt;br&gt;</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>    </a-p><a-tl>For example: `source = &quot;**/{*}.{png,gif}&quot;`</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>#### </a-p><a-tt>Destination processing</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>How destination is processed depends on whether the `redirect` key (see below) is present. If it is present, SWS will perform an *external* redirect. It will send a redirect response to the client, and the browser will usually proceed to the destination. In case of a relative URL, it will be another page on the same server. An absolute URL can result in navigation to another server.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>Without a `redirect` key, SWS will perform an *internal* redirect. It will attempt to retrieve the file denoted by the destination and send it to the client. While it is possible to specify an absolute URL here as well, it will always be processed by the same SWS instance. It will result by the request being mapped to a different [virtual host](virtual-hosting.md) however if a matching virtual host is present.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>#### </a-p><a-tt>Different roots within the same virtual host</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>Normally, different root directories are only possible with different virtual hosts. Rewrites however allow exposing another root in a subdirectory for example. For that, you add an internal virtual host that isn&#39;t normally visible from outside, e.g. `internal.local`. You then rewrite the requests to the subdirectory to the internal virtual host. For example:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>```</a-p><a-tl>toml</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>[</a-p><a-pr>general</a-pr><a-p>]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>root </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;/usr/srv/www&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>[</a-p><a-pr>advanced</a-pr><a-p>]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>rewrites</a-pr><a-p>]]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>source </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;/test/{**}&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>destination </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;http://internal.local/test/$1&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>virtual-hosts</a-pr><a-p>]]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"><a-p>host </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;internal.local&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-p>root </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;/usr/srv/alternative-root&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p>A request to `/index.html` will be mapped to `/usr/srv/www/index.html`, yet `/test/hi.txt` will be mapped to the file `/usr/srv/alternative-root/test/hi.txt`.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</a><span class="code-text"><a-p>This approach has two caveats:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L81" href="#L81">81</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"><a-p>1. When SWS produces redirects (e.g. redirecting `http://internal.local/test/subdir` to `http://internal.local/test/subdir/`), it isn&#39;t aware of rewrites. Unless the path part of the URL is identical before and after rewrite (like in the example above), this will result in broken redirects.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"><a-p>2. While the `internal.local` virtual host isn&#39;t normally accessed directly, this doesn&#39;t mean that it isn&#39;t possible for someone knowing (or guessing) its name. You should consider all files under the virtual host&#39;s root as public. Don&#39;t put any secrets in it even if these aren&#39;t accessible via rewrites.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L84" href="#L84">84</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L85" href="#L85">85</a><span class="code-text"><a-p>### </a-p><a-tt>Redirect</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L86" href="#L86">86</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L87" href="#L87">87</a><span class="code-text"><a-p>An optional number that indicates the HTTP response code (redirect).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L88" href="#L88">88</a><span class="code-text"><a-p>The values can be:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L89" href="#L89">89</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L90" href="#L90">90</a><span class="code-text"><a-p>- `301` for &quot;Moved Permanently&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L91" href="#L91">91</a><span class="code-text"><a-p>- `302` for &quot;Found&quot; (Temporary Redirect)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L92" href="#L92">92</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L93" href="#L93">93</a><span class="code-text"><a-p>## </a-p><a-tt>Examples</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L94" href="#L94">94</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L95" href="#L95">95</a><span class="code-text"><a-p>```</a-p><a-tl>toml</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L96" href="#L96">96</a><span class="code-text"><a-p>[</a-p><a-pr>advanced</a-pr><a-p>]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L97" href="#L97">97</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L98" href="#L98">98</a><span class="code-text"><a-p>### URL Rewrites</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L99" href="#L99">99</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L100" href="#L100">100</a><span class="code-text"><a-p># a. Simple route rewrite example</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L101" href="#L101">101</a><span class="code-text"><a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>rewrites</a-pr><a-p>]]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L102" href="#L102">102</a><span class="code-text"><a-p>source </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;**/*.{png,ico,gif}&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L103" href="#L103">103</a><span class="code-text"><a-p>destination </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;/assets/generic1.png&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L104" href="#L104">104</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L105" href="#L105">105</a><span class="code-text"><a-p># b. Route rewrite example with redirection</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L106" href="#L106">106</a><span class="code-text"><a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>rewrites</a-pr><a-p>]]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L107" href="#L107">107</a><span class="code-text"><a-p>source </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;**/*.{jpg,jpeg}&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L108" href="#L108">108</a><span class="code-text"><a-p>destination </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;/images/generic2.png&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L109" href="#L109">109</a><span class="code-text"><a-p>## NOTE: `redirect` can be omitted too</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L110" href="#L110">110</a><span class="code-text"><a-p>redirect </a-p><a-o>=</a-o><a-p> </a-p><a-n>301</a-n></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L111" href="#L111">111</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L112" href="#L112">112</a><span class="code-text"><a-p># c. Route rewrite example with destination replacements</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L113" href="#L113">113</a><span class="code-text"><a-p>[[</a-p><a-pr>advanced</a-pr><a-p>.</a-p><a-pr>rewrites</a-pr><a-p>]]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L114" href="#L114">114</a><span class="code-text"><a-p>## Note that we&#39;re using curly braces to group the `*` wildcard.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L115" href="#L115">115</a><span class="code-text"><a-p>## See https://docs.rs/globset/latest/globset/#syntax</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L116" href="#L116">116</a><span class="code-text"><a-p>source </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;**/{*}.{png,gif}&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L117" href="#L117">117</a><span class="code-text"><a-p>## For example, the destination will result in `/assets/abcdef.png`</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L118" href="#L118">118</a><span class="code-text"><a-p>destination </a-p><a-o>=</a-o><a-p> </a-p><a-s>&quot;/assets/$1.$2&quot;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L119" href="#L119">119</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L120" href="#L120">120</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L121" href="#L121">121</a><span class="code-text"><a-p>If you request something like:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L122" href="#L122">122</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L123" href="#L123">123</a><span class="code-text"><a-p>```</a-p><a-tl>sh</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L124" href="#L124">124</a><span class="code-text"><a-p>curl -I http://localhost/abcdef.png</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L125" href="#L125">125</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L126" href="#L126">126</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L127" href="#L127">127</a><span class="code-text"><a-p>Then the server logs should look something like this:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L128" href="#L128">128</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L129" href="#L129">129</a><span class="code-text"><a-p>```</a-p><a-tl>log</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L130" href="#L130">130</a><span class="code-text"><a-p>2023-07-08T20:31:36.606035Z  INFO static_web_server::handler: incoming request: method=HEAD uri=/abcdef.png</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L131" href="#L131">131</a><span class="code-text"><a-p>2023-07-08T20:31:36.608439Z DEBUG static_web_server::handler: url rewrites glob patterns: [&quot;$0&quot;, &quot;$1&quot;, &quot;$2&quot;]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L132" href="#L132">132</a><span class="code-text"><a-p>2023-07-08T20:31:36.608491Z DEBUG static_web_server::handler: url rewrites regex equivalent: (?-u)^(?:/?|.*/)(?:[^/]*)\.(?:gif|png)$</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L133" href="#L133">133</a><span class="code-text"><a-p>2023-07-08T20:31:36.608525Z DEBUG static_web_server::handler: url rewrites glob pattern captures: [&quot;abcdef.png&quot;, &quot;abcdef&quot;, &quot;png&quot;]</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L134" href="#L134">134</a><span class="code-text"><a-p>2023-07-08T20:31:36.608561Z DEBUG static_web_server::handler: url rewrites glob pattern destination: &quot;/assets/$1.$2&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L135" href="#L135">135</a><span class="code-text"><a-p>2023-07-08T20:31:36.609655Z DEBUG static_web_server::handler: url rewrites glob patterns destination replaced: &quot;/assets/abcdef.png&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L136" href="#L136">136</a><span class="code-text"><a-p>2023-07-08T20:31:36.609735Z TRACE static_web_server::static_files: dir: base=&quot;public&quot;, route=&quot;assets/abcdef.png&quot;</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L137" href="#L137">137</a><span class="code-text"><a-p>...</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L138" href="#L138">138</a><span class="code-text"><a-p>```</a-p></span></span></pre></div></div>
</main>
</body>
</html>
