Crate vial

Expand description

§~ vial: a micro micro-framework ~

Vial is a small web “framework” for making small web sites.

It only includes a few basics:

routes!: Macro for mapping URLs to handlers.
Request: Information about the current request, such as form data or URL path segments.
Response: Response to deliver to the client.
Responder: Trait to convert your types or a few built-ins like String into a Response.
asset: Serving of static files and support for bundling into the release binary.

Everything else… well, that’s up to you.

The goal is an as-few-as-possible-dependencies web library you can use to test out an idea quickly or get a personal project rolling. Single file, server side apps? You bet! Fast compilation? Yes please! À la carte dependencies? Now you’re talkin’!

It’s sort of like a picnic where the playlist is all 90s music and you have to bring your own beverages. And food.

To learn more, keep reading or visit one of these links:

Status: Vial is currently in early development. It is being developed alongside [deadwiki], but that is strictly for personal use. Proceed with caution.

To get started, just add vial to your Cargo.toml:

[dependencies]
vial = "0.1"

There are a handful of --features that you can enable, most of which add additional dependencies that need to be included:

[dependencies]
vial = { version = "*", features = ["horror", "cookies"] }

This list is a work in progress:

horror: Small & fast macro-based HTML builder, via [horrowshow].
json_serde: Request::json and Response::with_json powers, via Serde.
cookies: Cookie monster!
sessions: Session support
multipart: Multipart form data (file uploads)
log: Access logging

§~ hello world ~

As is tradition:

vial::routes! {
    GET "/" => |_| "Hello, world!";
}

fn main() {
    vial::run!().unwrap();
}

For a bit more sanity, you can route to functions directly:

use vial::prelude::*;

routes! {
    GET "/echo" => echo;
    POST "/echo" => post;
}

fn echo(_: Request) -> &'static str {
    "<form method='POST'>
        <input type='text' name='echo'/>
        <input type='submit'/>
    </form>"
}

fn post(req: Request) -> String {
    format!(
        "<h1>{}</h1>",
        req.form("echo").unwrap_or("You didn't say anything!")
    )
}

fn main() {
    vial::run!().unwrap();
}

To really break the mold, you can split your site into different modules:

mod wiki {
    vial::routes! {
        GET "/wiki" => |_| Response::from_file("wiki.html");
        // etc...
    }
}

mod blog {
    vial::routes! {
        GET "/blog" => |_| Response::from_file("wiki.html");
        // etc...
    }
}

mod index {
    use vial::prelude::*;
    routes! {
        GET "/" => |_| Response::from_file("index.html");
    }
}

fn main() {
    // The order matters here - if `wiki` and `blog` both define "/",
    // the `mod index` version will match first and get run.
    vial::run!(index, wiki, blog);
}

But hey, who wants to putz around with HTML when you can be writing Rust? Enable the horror feature and you’re on your way:

use vial::prelude::*;

routes! {
    GET "/" => |_| html! {
        p {
            : "You're looking for this: ";
            a(href="/echo") { : "echo" }
        }
    };
    GET "/echo" => echo;
    POST "/echo" => post;
}

fn echo(_: Request) -> impl Responder {
    html! {
        form(method="POST") {
            p {
            : "Type something: ";
                input(type="text", name="echo");
                input(type="submit");
            }
        }
    }
}

fn post(req: Request) -> impl Responder {
    owned_html! {
        h1: req.form("echo")
            .unwrap_or("You didn't say anything!");
    }
}

fn main() {
    vial::run!().unwrap();
}

§~ performance ~

We want to keep Vial snappy, but this is not a production web server that’s competing in any shootouts. Our bigger priority is keeping the base dependency count and compilation time low.

§~ when to use ~

Probably never, or only ever to quickly test an idea. Certainly not for personal wikis or small hobby projects, unless you insisted.

Modules§

asset: Vial can serve static files out of an asset directory and optionally bundle them into your application in --release mode.
prelude: The prelude pulls in all the main types, traits, and macros:

Macros§

asset_dir: Vial can serve static files out of an asset directory, complete with ETag support so your browser isn’t constantly re-downloading.
bundle_assets: If you want to bundle your assets into your final binary in release mode, then you need to call vial::bundle_assets!() with the path to your asset directory in a build.rs file.
routes: The vial::routes! macro, they say, is half of the battle, with the other 50% being a toss up between “knowledge” and the vial::run! macro you use to start your app.
run: The vial::run! macro is the preferred way of starting your Vial application after you’ve defined one or more routes using vial::routes!. run! performs a bit of necessary setup, then starts listening for client requests at http://0.0.0.0:7667 by default.
run_with_banner: Same as vial::run!(), but allows setting a banner that will be printed to the console when your Vial web app starts.
use_state: Gives Vial a state object to manage globally. You can access it by calling request.state::<YourStruct>() in an action.

Structs§

Request: Contains information about a single request.
Response: Each request ultimately ends in a Response that is served to the client and then discarded, like fallen flower petals. Together with Request and Responder it forms the holy trinity of R’s in Vial.
Router: Router keeps track of all the routes defined by vial::routes! and can produce an action for a given HTTP Method and URL path combination using action_for.
TypeCache: The TypeCache is heavily inspired by the state crate and the way the Rocket framework handles global and local state. You could say we’ve immutably borrowed some ideas. Rim-shot!

Enums§

Error: Possible Vial errors.
Method: Method is just an enum representing the HTTP methods Vial supports. Which is not all of them.

Constants§

BUILD_DATE: Date and time this program was compiled.
VERSION: Crate version

Statics§

ASSET_DIR: Directory where assets are stored, if any.
BUNDLED_ASSETS: Assets bundled into the binary in release mode.

Traits§

Responder: The Responder trait converts your custom types or a few basic Rust types into a Response that gets hand delivered to the HTTP client in a timley fashion, barring any weather delays.

Type Aliases§

Result: Convenience Result that returns vial::Error.

Crate vial

Crate vial Copy item path

§~ vial: a micro micro-framework ~

§~ hello world ~

§~ performance ~

§~ when to use ~

Modules§

Macros§

Structs§

Enums§

Constants§

Statics§

Traits§

Type Aliases§

Crate vial