About

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

Kvarn is batteries-included (optional defaults) with support for automatic HTTPS certificates reverse proxying, auto HTTP/2 push, in-memory caching (proper cache invalidation), server communication through kvarnctl, 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. It utilizes Kvarn templates for integration with headers and footers.

Using Kvarn as a library

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, comes with more, integrated features out of the box, and is 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 throughput and availability, to personal websites with the ability to host unlimited domains from one IP, to IOT devices, like the Raspberry Pi.

All features are configurable; if you want the latest HTTP and Web features, you can enable those features at compile-time. Of 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 require compile-time and only have spare resources, you can disable those features, not compiling in HTTPS or HTTP/2 support.

The extension system allows for easy creation of APIs and can interact with the host machine asynchronously. It can access databases, change the GPIO pins, or anything else a program can do. When disabling 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