servio 0.6.2

HTTP server for static files, with live reload, for local development
servio-0.6.2 is not a library.

servio

An HTTP server for static files, with live reload, built with Axum. It is designed for local development: files are not cached, and the browser refreshes when they change.

Features

  • Live reload, debounced by 200 ms
  • Gzip and Brotli compression
  • Single-page app (SPA) fallback
  • Optional long-term caching for published assets
  • Safe defaults: localhost only, no caching, hidden files blocked
  • Protection against serving files through symlinks outside the chosen directory
  • Security headers including X-Content-Type-Options, X-Frame-Options, and Referrer-Policy

Install

Rust 1.88 or newer is required.

cargo install servio

To install the latest development version:

cargo install --git https://github.com/alexylon/servio

To install from a local clone:

git clone https://github.com/alexylon/servio
cd servio
cargo install --path .

Quick start

Run servio in the directory you want to serve, then open the address shown in the terminal.

# Serve the current directory at http://127.0.0.1:3030
servio

# Serve another directory on port 8080
servio --dir /path/to/static --port 8080

# Fall back to index.html for SPA routes such as /users/123
servio --spa

# Make the server reachable from other devices on your network
servio --host 0.0.0.0

# Open the browser as well
servio --open

Options

Option Default Description
-d, --dir <DIR> . Directory to serve
-p, --port <PORT> 3030 Port to use
--host <HOST> 127.0.0.1 Address to listen on
--spa off Serve index.html when a page route matches no file
--no-reload off Disable file watching and browser refreshes
--poll off Find changes by looking at the files, once a second
--cache-assets off Cache files under /assets/ for one year
--open off Open the address in the browser
--ignore <PATTERN> none Do not refresh the browser for changes matching this pattern; may be given more than once

If you do not specify a port and 3030 is busy, servio tries the next available port through 3039 and prints the selected address. If you specify a port, servio uses that exact port or exits with an error.

--open opens the address in your usual browser, or in the one BROWSER names. That variable may be a whole command, with %s where the address goes:

BROWSER="firefox --new-window %s" servio --open

It may also name several, tried in turn until one opens the address, parted by : (; on Windows); one that stops at once with an error is passed over for the next. Quote anything with a space in it, a path or a flag's value:

BROWSER="firefox:'/Applications/Firefox.app/Contents/MacOS/firefox' %s" servio --open

A quote counts anywhere in a word, as it does in a shell, so a path with an apostrophe in it has to be quoted whole.

If no browser can be opened, or the one named stops at once with an error, servio says so and keeps serving. With --poll, the browser opens once the first look at the files is done.

Live reload

Saving a file refreshes the browser. servio ignores changes in hidden directories, target, node_modules, and common editor temporary files.

--ignore adds patterns of your own, for a build that writes logs or a cache next to the pages:

servio --ignore "*.log" --ignore cache

A pattern is matched against the path below the served directory, written with /, and against every directory above it, so cache covers everything in cache/. A pattern with no / in it matches a name at any depth, as it does in .gitignore; one with a / starts from the served directory, so build/*.log is exactly one directory deep, and /cache is only the cache at the top. * stops at a /; ** crosses any number of directories, and tmp/** covers tmp itself as well. On macOS and Windows, where the disk does not tell Build.LOG from build.log, neither does a pattern. The files are still served, and --poll still reads them: the pattern only decides what refreshes the browser.

Naming files does not name the folder holding them. With *.log, a build that creates out/ afresh each run refreshes the browser once, for the new folder; out/** covers the folder as well.

Patterns used on every run belong in a file called .servioignore in the served directory, one to a line, with # starting a comment:

# what the build writes next to the pages
*.log
cache

The file is read once, when the server starts. Being hidden, it is never served, and editing it does not refresh the browser. Its patterns and those from --ignore apply together, and the banner says how many it added.

Live reload continues working when a build replaces the served directory, or moves it aside and back. On macOS, changing file permissions may also trigger one refresh because of how the operating system reports file events.

When saving a file changes nothing

Live reload normally waits for the operating system to report a change. Some filesystems never report one: network shares, folders shared with a virtual machine, and directories mounted into a container. There, --poll finds changes by looking at the files itself, once a second:

servio --dir /mnt/share --poll

Every look reads every file in the served directory and compares its contents, because a poll compares write times only to the whole second, and two saves within one second of each other would otherwise look like one. So --poll notices a change up to a second later than the ordinary watcher, and costs far more while it waits. Use it only where the ordinary watcher stays silent, and point it at the build output rather than the whole project tree, or every look will read node_modules as well.

On Windows there is one more reason to poll. A build that changes thousands of files in the same instant can overflow the room the system keeps for reporting them. The system's watcher then stops without a word, and nothing refreshes until servio is started again. Where builds are that large, --poll cannot lose the watch.

Links are not followed. The server refuses to hand out anything outside the served directory, so a link leading out cannot change what the browser sees, and one leading back in points at files each look reads anyway.

Neither --poll nor --ignore can be combined with --no-reload, which turns off watching altogether.

Single-page apps

With --spa, missing page routes fall back to index.html so the client-side router can handle them. Missing scripts, stylesheets, images, and anything under /assets/ still return 404, making broken asset paths easy to spot.

If index.html disappears while the server is running, such as during a build that clears the output directory, servio says so in the terminal. It says it once each time the page goes missing rather than once per route, so a broken build does not leave every address returning 404 without explanation.

Without --spa, every missing path returns 404.

Serving a published site

Disable live reload and enable caching for content-hashed assets:

servio --dir site_public --host 0.0.0.0 --spa --no-reload --cache-assets

--cache-assets gives files under /assets/ a one-year immutable cache policy. Other files are revalidated so visitors still receive updated pages.

When exposing servio to a network, serve only the intended build directory. Hidden paths are blocked apart from .well-known, which certificate renewal needs, and symlinks may point only within the served directory. Each subdirectory also uses a file watch while live reload is on, so serving a large project tree can exhaust the operating system's watch limit.

Development

Run the test suite with:

cargo test

See CHANGELOG.md for version history and RELEASE.md for the release process.

License

MIT — see LICENSE.