# Sputnik This library extends the types from the [http](https://crates.io/crates/http) crate: * extends `http::request::Parts` with query parameter deserialization & cookie parsing * extends `http::response::Builder` with methods to set cookies and content-types If you use [Hyper](https://hyper.rs/) and want to deserialize request bodies with [Serde](https://serde.rs/) you can enable the following feature flags: - `hyper_body` provides a trait to extend `hyper::Body` with an `into_form` method for parsing data submitted from HTML forms. - `hyper_body_json` additionaly provides an `into_json` method With the `security` feature Sputnik furthermore provides what's necessary to implement [signed & expiring cookies](#signed--expiring-cookies) with the expiry date encoded into the signed cookie value, providing a more lightweight alternative to JWT if you don't need interoperability. Sputnik does **not** handle routing because even complex routing can be quite easily implemented with nested `match` blocks. If you want a more high-level router, you can check out the [router crates](https://crates.io/keywords/router). Sputnik encourages you to create your own error enum and implement `From` conversions for every error type, which you want to short-circuit with the `?` operator. This can be easily done with [thiserror](https://crates.io/crates/thiserror) because Sputnik restricts its error types to the `'static` lifetime. ## Security Considerations Protect your application against [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) by setting `SameSite` to `Lax` or `Strict` for your cookies and checking that the `Origin` header matches your domain name (especially if you have unauthenticated POST endpoints). ## Hyper Example ```rust use std::convert::Infallible; use hyper::service::{service_fn, make_service_fn}; use hyper::{Method, Server, StatusCode, Body}; use hyper::http::request::Parts; use hyper::http::response::Builder; use serde::Deserialize; use sputnik::{html_escape, mime, request::SputnikParts, response::SputnikBuilder}; use sputnik::hyper_body::{SputnikBody, FormError}; type Response = hyper::Response; #[derive(thiserror::Error, Debug)] enum Error { #[error("page not found")] NotFound(String), #[error("{0}")] FormError(#[from] FormError) } fn render_error(err: Error) -> (StatusCode, String) { match err { Error::NotFound(msg) => (StatusCode::NOT_FOUND, msg), Error::FormError(err) => (StatusCode::BAD_REQUEST, err.to_string()), } } async fn route(req: &mut Parts, body: Body) -> Result { match (&req.method, req.uri.path()) { (&Method::GET, "/form") => Ok(get_form(req)), (&Method::POST, "/form") => post_form(req, body).await, _ => return Err(Error::NotFound("page not found".to_owned())) } } fn get_form(_req: &mut Parts) -> Response { Builder::new() .content_type(mime::TEXT_HTML) .body( "
".into() ).unwrap() } #[derive(Deserialize)] struct FormData {text: String} async fn post_form(_req: &mut Parts, body: Body) -> Result { let msg: FormData = body.into_form().await?; Ok(Builder::new().content_type(mime::TEXT_HTML).body( format!("hello {}", html_escape(msg.text)).into() ).unwrap()) } async fn service(req: hyper::Request) -> Result, Infallible> { let (mut parts, body) = req.into_parts(); match route(&mut parts, body).await { Ok(mut res) => { for (k,v) in parts.response_headers().iter() { res.headers_mut().append(k, v.clone()); } Ok(res) } Err(err) => { let (code, message) = render_error(err); // you can easily wrap or log errors here Ok(hyper::Response::builder().status(code).body(message.into()).unwrap()) } } } #[tokio::main] async fn main() { let service = make_service_fn(move |_| { async move { Ok::<_, hyper::Error>(service_fn(move |req| { service(req) })) } }); let addr = ([127, 0, 0, 1], 8000).into(); let server = Server::bind(&addr).serve(service); println!("Listening on http://{}", addr); server.await; } ``` ## Signed & expiring cookies After a successful authentication you can build a session id cookie for example as follows: ```rust let expiry_date = SystemTime::now() + Duration::from_secs(24 * 60 * 60); let mut cookie = Cookie::new("userid", key.sign( &encode_expiring_claim(&userid, expiry_date) )); headers.set_cookie(Cookie{ name: "userid".into(), value: key.sign( &encode_expiring_claim(&userid, expiry_date) ), secure: Some(true), expires: Some(expiry_date), same_site: SameSite::Lax, }); ``` This session id cookie can then be retrieved and verified as follows: ```rust let userid = req.cookies().find(|(name, _value)| *name == "userid") .ok_or_else(|| "expected userid cookie".to_owned()) .and_then(|(_name, value)| key.verify(value)) .and_then(|value| decode_expiring_claim(value).map_err(|e| format!("failed to decode userid cookie: {}", e))); ``` Tip: If you want to store multiple claims in the cookie, you can (de)serialize a struct with [serde_json](https://docs.serde.rs/serde_json/). This approach can pose a lightweight alternative to JWT, if you don't care about the standardization aspect.