Security Features Home Extensions Ecosystem

Features & why to use Kvarn

Kvarn tries to package many useful features without being bloated. Optional extensions are available in the extensions crate.

Here is a incomplete list of Kvarn’s features, most of which have guides in their respective pages.

Some require certain Cargo “features” to be compiled in, and some require kvarn_extensions. This will be explicitly noted.

Contents
1 Features & why to use Kvarn
2 Sane defaults
3 HTTP/2
3.1 HTTP/2 Push
4 HTTPS
5 Full documentation coverage
6 Extensions
7 Cache
8 PHP
9 MarkDown
10 Templates
11 Full text search engine
12 CORS
13 Graceful shutdown & handover
14 Reverse proxy
15 Guaranteed memory-safety
16 Other fundamental features & systems
17 Back to the basics

Sane defaults

The example of running a Kvarn server provides sane defaults, which optimize security; speed; and help mitigate DOS attacks.

HTTP/2

Requires the feature http2 (part of default and full)

HTTP/2 is abstracted from all other internal and extension logic; offering complete parity. This means you get all the pros of the latest protocols without any code.

Kvarn passes the h2spec test. If something doesn’t work, it’s the user agent not conforming.

HTTP/2 Push

Part of kvarn_extensions under the feature push (part of default)

HTTP/2 introduced a features where the server can push other resources before the client requests them. This has not been widely used because of the problem with pushing to the client when it’s already got the resource in a cache.

Kvarn aims to solve this by making it simple to integrate, not requiring any configuration and not sending the same resource twice to a client.

HTTPS

Requires the feature https (part of default and full)

HTTPS makes the web more secure. Kvarn’s design is not only influenced by HTTPS, but encourages you to use it.

When creating a virtual host, the recommended constructor redirects all HTTP requests to HTTPS before the request reaches your code.

Kvarn also suggest using HSTS. When you’re ready, you only need to add one line of code to enable it for a host, improving security further.

If you want maximum security, you can of course simply not listen on port 80, reducing the code you write.

Full documentation coverage

Documentation and examples are key to a good library.

You can always read Kvarn’s documentation online. Under Crates to the left, you can explore all other crates part of the ecosystem.

The full coverage is enforced by the compiler. All examples are enforced to run correctly by Rust’s builtin testing.

Extensions

Kvarn in it’s default acts as a file-server. That in itself isn’t useful for building a backend. To build a API, implement authentication, add dynamic language support, or CORS, extensions provides the data and tools you need.

As there are few and small performance benefits of implementing features directly into Kvarn, but great flexibility advantages. Therefore, as many features as possible are built as extensions.

When writing an API, Kvarn handles all HTTP boilerplate. It’ll cache, compress, encrypt, set content-length, and secure the response, with minimal info from the implementation.

There exists several types of extensions, all of which have a separate function for complete control over the response pipeline. A present extension can be called from within a file. If it start with !> you can specify present extensions like this !> my-extension arg1 arg2 &> another-extension argument.... These are evaluated in order, first to last.

Here, server-side caching is critical for heavy workloads. The flexibility of Kvarn is advantageous; if you have frequent changes, content is recalculated on the fly, but if you need performance, it’ll cache the results as a complete response, ready to be sent. Kvarn tries to generalize requests, reducing cache misses. This also acts as a primitive anti-DOS strategy; if no new content is calculated (or read from disk), the requests are very cheap.

Cache

When Kvarn was created, a reverse-proxy caching the responses from a web application seemed slow. It holds up to this day.

The built in cache in Kvarn is in-memory for performance and integration with extensions is seamless.

If you build extensions directly in Kvarn with it’s convenient macros with C-like performance. It’s much faster, and easier to manage, than a reverse-proxy fighting with Node’s transfer-encoding: chunked and not being sure of exactly how to cache the content.

If you need the maintenance advantage of a modular system, look no further than Kvarn’s handover.

PHP

Part of kvarn_extensions under the feature php (part of default)

Kvarn can interpret .php files and send them back, with all of Kvarn’s other features. Server caching can be set with the kvarn-cache-control header.

MarkDown

Part of Chute

Sometimes you need to write a consistent website easily, with minimal effort. That’s where Kvarn Chute comes in. You write MarkDown, Chute translates it to HTML, using Kvarn’s templating system.

Long pages are hard to navigate. Therefore, Chute offers a table of contents generator. Just insert ${toc} in your document, run chute -y <doc>. You now have a high-quality HTML-only TOC.

This page is written using this features, reducing boilerplate even more and speeding up documentation.

You can add tags to the head of the HTML by starting the MD document (after the extensions declaration) with a <head> tag. You’ll of course have to close it when all the metadata is written.

As with normal files, you can run extensions. Chute will automatically add the tmpl (template) extension with the standard.html and md.html templates present. If you add !> hide to hide the MD source, it’ll be removed, so users can view the HTML.

Templates

Part of kvarn_extensions under the feature templates (part of default)

To build a consistent website, you need templates. Copying your header and footer isn’t viable! As a simple, fast, and easy to use template system, this can virtually copy-paste bytes from a template file (located in <webroot>/templates/), but does not, for example, handle conditional inclusion or loops. Only simple inclusion.

The nav-bar on this page is powered by the templates. HTML documents are about 15 lines for a title, heading, and a paragraph, and of course the nav-bar.

See this directory in the source code of this website for an example of the format of templates.

Full text search engine

A search engine with typo tolerance, no index set-up, and fast (1-4ms) responses.

Boasts an API for accessing the search hits. This means you can implement your own frontend, or use mine at icelk.dev. All the code for that is summarized at the example.

See the link for more information.

CORS

As the web has expanded and complexity increased, cross-site requests have become essential.

Many of the best-practises of HTTP/1.1; loading from multiple domains and chunking together content is irrelevant when using HTTP/2, as it resolves these issues.

Kvarn features a CORS handling (using extensions), backed by testing, which blocks unauthorized CORS requests before they get to your API. This ensures all CORS requests, even from faulty user agents, don’t change server state.

Graceful shutdown & handover

Requires the feature graceful-shutdown (part of default and full)

To enable upgrade of the server, you need to shut it down and then start it up, with no downtime. The way Kvarn solves this is through graceful shutdown and handover.

Reverse proxy

Part of kvarn_extensions under the feature reverse-proxy (part of default)

If you want to develop your web application in another language, Kvarn can act as a reverse proxy, with all the benefits of HTTP/2, caching, and easy upgrades.

In contrast to writing extensions in Rust, the speed and throughput is greatly reduced.

Guaranteed memory-safety

Kvarn is written in Rust.

This greatly improves security (resilience against buffer overflows) and reliability, as Rust guarantees pointers to be valid through it’s strict borrowing rules. This, together with phenomenal error handling and strong tooling makes for maintainable and predictable code.

The borrow rules ensure memory safety without runtime overhead, while being as fast as C (assuming the code is optimal, which is easier to accomplish with Rust).

The compiler catches nearly all errors. The quote, “if it compiles, it runs” is indeed true. Compare Rust vs C++ to TS vs JS, only in one case silly bugs cause production to go offline.

Other fundamental features & systems

Back to the basics

Doesn’t mean they’re more simple or easier to implement, as development time has shown. ಠ_ಠ