About

Kvarn is a rusty, open-source, extendable web application framework with native async everywhere; zero downtime; and safe & fast defaults.

Kvarn is batteries-included (optional defaults) with support for automatic HTTPS certificates, HTTP/3, io_uring everywhere, reverse proxying, auto HTTP/2 push, in-memory caching (proper cache invalidation), server communication provided by a simple CLI, and easy website creation through Markdown and Chute.

You can follow progress on GitHub where the project is hosted. The project is under active development to add features, reduce complexity, improve performance, and fix issues.

Getting started

See Mölla for how to install the reference Kvarn implementation. You'll have a web server running in under 5 minutes and the power to write search-indexed websites with user authentication in no time.

We recommend using Kvarn Chute for writing documents. It allows you to use Markdown on web pages. Providing automatic table of contents, date widgets, and other features, it's a convenient way to write text documents without limiting HTML use.

Using Kvarn as a development library (advanced)

Kvarn is programmed using Rust. You'll need to download it before using the Kvarn web server.

Then, enter a directory and initiate a Cargo (Rust's package manager, like NPM to node.js) project.

$ cargo init

Next, add these dependencies in your Cargo.toml.

kvarn = "0.5"
tokio = { version = "1.20", features = ["rt-multi-thread", "macros"] }
env_logger = "0.9"

Now, you can edit src/main.rs and replace the Hello world! example with this.

use kvarn::prelude::*;

#[tokio::main]
async fn main() {
    // Initiate the logger. Set the environment variable `RUST_LOG` to `info` to get more verbose logging.
    env_logger::init();
    // Create a host without HTTPS with hostname "localhost", serving files from directory "./web/public/", with the default extensions and the default options.
    let host = Host::unsecure("localhost", PathBuf::from("web"), Extensions::default(), host::Options::default());
    // Create a collection of virtual hosts with `host`.
    let hosts = HostCollection::builder().insert(host).build();
    // Serve `hosts` on port 8080 without HTTPS
    let port_descriptor = PortDescriptor::unsecure(8080, hosts);

    // Run the server. You can specify multiple PortDescriptors.
    let shutdown_manager = RunConfig::new().bind(port_descriptor).execute().await;
    // Wait for shutdown. This will never happen with this setup,
    // but you can clone `shutdown_manager` and shut the server down from other threads.
    shutdown_manager.wait().await;
}

Start it with the following command.

$ cargo run

Now you have a web server running at localhost:8080 serving files from web/public/ relative to the directory.

See the extensions page for a more holistic example.

Docs

Performance

Kvarn's performance is within margin of error of Iron's, while being easier to work with, brings more to the table with a robust set of integrated features out of the box, all while being more agile.

Kvarn also features zero-downtime upgrades without any config - just push a new binary to the server and run kvarnctl reload.

Applications

Kvarn can be used for anything ranging from large-scale websites in need of massive throughput and availability, to personal websites with the ability to host unlimited domains from one IP, to IOT devices, like the Raspberry Pi or even ESP32.

All features are optional; if you want the latest HTTP and Web features, you can enable those features at compile-time. If you on the other hand run Kvarn as a web interface for a local device and don't need security or the latest features, but rather prioritize fast compile-time with minimal resources, you can disable those features, not compiling in HTTPS or HTTP/2 support.

The extension system allows for simple creation of APIs that can interact with the host machine asynchronously. You can access databases, change GPIO pins, or anything else a program can do, synchronously or asynchronously. When disabling build-time features, no APIs change. You always get the same developer experience.

License

The text and logo on this website is licensed under the CC-BY-SA-4.0 License. The code examples and JavaScript source code is licensed under the MIT license.

The source code is available at GitHub.

Resources