[−][src]Crate vial
~ 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 aResponse
. - 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:
- [x] horror: Small & fast macro-based HTML builder, via [horrowshow].
- [x] json_serde:
Request::json
andResponse::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 |
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 |
routes | The |
run | The |
run_with_banner | Same as |
use_state | Gives Vial a state object to manage globally. You can access it
by calling
|
Structs
Request | Contains information about a single request. |
Response | Each request ultimately ends in a |
Router |
|
TypeCache | The TypeCache is heavily inspired by the |
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 |
Type Definitions
Result | Convenience Result that returns |