~ vial: a micro micro-framework ~

Vial is a small web "framework" for making small web sites in Rust.

It includes just a few basics:

Parsing and routing HTTP requests
Parsing POST form data
Serving static files (css, js)

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 still in development and shouldn't be used to build real world apps on untrusted networks. Please proceed with caution and wear a hard hat at all times.

~ getting started ~

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

[dependencies]
vial = "0.1"

Now you can use vial::prelude::*; in your application to pull in the common types, or just use the crate like any other.

~ 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>You said: {}</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:

use vial;

mod wiki;
mod blog;

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::*;

#[macro_use]
extern crate horrorshow;

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();
}

~ bonus features ~

vial doesn't come with JSON or a template engine or any of that fancy stuff by default, but there (will be) a few compile-time --features you can activate for enhanced productivity:

hatter: Enable Hatter: A positively mad, HTML templating language.
horror: Enable horrorshow: A small & fast macro-based HTML builder.
json_serde: Request::json and Response::with_json powers, via Serde.
json_nano: Request::json and Response::with_json, via nanoserde.
cookies: Request::cookie(), Response::with_cookie, and friends.
sessions: Request::session(), Response::with_session, and friends.
uploads: Multipart form data (file uploads)
log: Access logging

Please note: The list above is a work-in-progress.

~ hot reloading ~

Your assets will automatically get reloaded in debug mode, complete with proper ETag support, but you probably want to refresh your Rust code, too.

Right now the easiest way is to use cargo-watch:

$ cargo install cargo-watch
$ cargo watch -x 'run --example hello_world'

~ testing ~

Tests can be run on a recent version of stable Rust with make test. We also run tests on commits with GitHub Actions.

Vial prefers to put everything in tests/ rather than include tests directly in src/*.rs files. To access private APIs in tests, we make them pub and use #[doc(hidden)]. Your cooperation is appreciated.

~ license ~

Vial is licensed under either of the following, at your option:

Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT License (LICENSE-MIT or http://opensource.org/licenses/MIT)

`Response::with_*` functions should either panic or state the error

Currently the with_*() functions for Response all have different error-behavior:

with_json() panics on serialization failure.
with_asset() will instead not panic, continue to execute and return a 404 upon attempting to retrieve the asset. This is the same behavior as if the route isn't even defined. Very confusing.
with_file() is the same as with_asset() except that if there is an error opening the file a 500 code with the actual error embedded is returned instead of a 404.

I think it should either be all panic, all returning a 500 with the included error text, a result be propagated somehow or the error message be printed in the "log". 404s are very confusing when the file you are trying to include doesn't exist as it looks like the route doesn't exist instead of the file not existing.

Minimum confusing example:

use vial::{routes, run};

routes! {
    GET "/file" => |_| Response::from_file("I DO NOT EXIST");
}

fn main() {
    _ = run!();
}

Output after two curls:

~ vial running at http://0.0.0.0:7667
GET 404 /file
GET 404 /route_not_existo

xvxx / vial Goto Github PK

vial's Introduction

~ vial: a micro micro-framework ~

~ getting started ~

~ hello world ~

~ bonus features ~

~ hot reloading ~

~ testing ~

~ license ~

vial's People

Contributors

Stargazers

Watchers

Forkers

vial's Issues

Link: https://github.com/sigaloid/vial

Recommend Projects

Recommend Topics

Recommend Org