Basic-http-server 0.6 - a static HTTP server for learning and development

basic-http-server is a simple static HTTP server designed for learning and for local documentation development. Version 0.6 is a major update, with improved source code organization and commenting, as well as new “developer extensions”.

Install with cargo install basic-http-server.

It is a one-line command to serve static files from a local directory, a useful tool in the developer’s toolbox.

More than that though, it written to be as clean and clear as possible, and heavily commented, to illustrate basic async Rust programming, currently with hyper and tokio. (I’m not an async Rust expert, so patches that improve clarity and make code more idiomatic welcome).

I write lots of documentation in my day job and use it nearly every day. In the course of doing so, I’ve found myself wanting some developer-specific features.

So new in this release is a -x flag that turns on two new “developer extensions”:

  • directory listings - if the requested URL corresponds to a directory, and there’s no index.html to display, return a hyperlinked directory listing. Useful in many situations, like exploring target/doc.

  • markdown rendering - if a .md file is requested, render it as markdown, with GitHub extensions. Useful to see more-or-less what your markdown files are going to render like on GitHub. This uses comrak (:heart: @kivikakk!).

When extensions are off, they have no impact on the server performance or behavior — it remains a regular static file server.

This release also features some minor feature improvements and bug fixes.

With respect to the learning aspects of this code, in the code for this release I’d particularly like to draw attention to the basic-http-server error type. I’ve been rethinking my approach to error boilerplate, particularly after this post by @BurntSushi. This error type uses no special error libraries, but does use #[derive(Display)], and makes a distinction between “semantic” error variants, and “blanket” (or “passthrough”) error variants.

Hope this tool is useful to Rust learners and others.


Version 0.6.3 is out. This minor release includes fixes to URL percent-encoding so that more URLs should be translated to filenames correctly; it also includes, in -x extended mode, better percent-encoding of characters that will confuse the web agent. So file names with spaces, hashes, and question marks should work correctly now.

Thanks to Richard Dodd for contributions to this release.