1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248
//! # ~ vial: a micro micro-framework ~ //! //! **Vial** is a small web "framework" for making small web sites. //! //! It only includes a few basics: //! //! - **[routes!](macro.routes.html)**: Macro for mapping URLs to //! handlers. //! - **[Request](struct.Request.html)**: Information about the //! current request, such as form data or URL path segments. //! - **[Response](struct.Response.html)**: Response to deliver to the //! client. //! - **[Responder](trait.Responder.html)**: Trait to convert your //! types or a few built-ins like `String` into a `Response`. //! - **[asset](asset/index.html)**: 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: //! //! - [Manual](https://vial.rs/) //! - [Source Code](https://github.com/xvxx/vial) //! - [Bug Tracker](https://github.com/xvxx/vial/issues) //! - [Crate](https://crates.io/crates/vial) //! //! ---- //! //! **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`: //! //! ```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: //! //! ```toml //! [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` and `Response::with_json` powers, //! via Serde. //! - [x] **cookies**: Cookie monster! //! - [ ] **sessions**: Session support //! - [ ] **multipart**: Multipart form data (file uploads) //! - [ ] **log**: Access logging //! //! ## ~ hello world ~ //! //! As is tradition: //! //! ```no_run //! vial::routes! { //! GET "/" => |_| "Hello, world!"; //! } //! //! fn main() { //! vial::run!().unwrap(); //! } //! ``` //! //! For a bit more sanity, you can route to functions directly: //! //! ```no_run //! 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: //! //! ```no_run //! 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: //! //! ```ignore //! 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. //! #![warn(missing_docs)] #![allow(clippy::needless_doctest_main)] #![allow(clippy::large_enum_variant)] #[macro_use] mod macros; pub mod asset; mod cache; mod error; mod method; pub mod prelude; mod request; mod responder; mod response; mod router; mod server; // used in tests #[doc(hidden)] pub mod bundler; #[doc(hidden)] pub mod http_parser; #[doc(hidden)] pub mod util; #[doc(hidden)] pub mod storage; #[cfg(feature = "horror")] #[doc(hidden)] pub mod horrorshow; pub use { bundler::bundle_assets, cache::TypeCache, error::Error, method::Method, request::Request, responder::Responder, response::Response, router::Router, server::run, }; /// Convenience Result that returns `vial::Error`. pub type Result<T> = std::result::Result<T, Error>; /// Directory where assets are stored, if any. pub static mut ASSET_DIR: Option<String> = None; /// Assets bundled into the binary in release mode. pub static mut BUNDLED_ASSETS: Option<std::collections::HashMap<String, &'static [u8]>> = None; /// Date and time this program was compiled. pub const BUILD_DATE: &str = env!("BUILD_DATE"); /// Crate version pub const VERSION: &str = env!("CARGO_PKG_VERSION");