# Sputnik

A microframework based on [Hyper](https://hyper.rs/) that forces you to:

* make error handling explicit (no possible failures hidden behind macros)
* implement your own error type ([because you need to anyway](#error-handling))

Sputnik provides:

* convenience wrappers around hyper's `Request` & `Response`
    * parse, set and delete cookies
      (powered by the [cookie](https://crates.io/crates/cookie) crate)
    * parse query strings and HTML form data (powered by the
      [serde_urlencoded](https://crates.io/crates/serde_urlencoded) crate)
* cookie-based [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) tokens
* `Key`: a convenience wrapper around HMAC (stolen from the cookie crate, so
  that you don't have to use `CookieJar`s if you don't need them)
* `decode_expiring_claim` & `encode_expiring_claim`, which can be combined with
  `Key` to implement [signed & expiring cookies](#signed--expiring-cookies)
  (with the expiry date encoded into the signed cookie value)

Sputnik does **not**:

* handle routing: for most web apps `match`ing on (method, path) suffices
* handle configuration: we recommend [toml](https://crates.io/crates/toml)
* handle persistence: we recommend [diesel](https://diesel.rs/)
* handle templating: we recommend [maud](https://maud.lambda.xyz/)

## Error handling

Rust provides convenient short-circuiting with the `?` operator, which
converts errors with `From::from()`. Since you probably want to short-circuit
errors from other crates (e.g. database errors), a web framework cannot
provide you an error type since Rust disallows you from defining a `From`
conversion between two foreign types.

This does imply that you need to define your own error type, allowing you to
implement a `From` conversion for every error type you want to short-circuit
with `?`. Fortunately the [thiserror](https://crates.io/crates/thiserror)
crate makes defining custom errors and `From` implementations trivial.

## Example

```rust
use std::convert::Infallible;
use hyper::service::{service_fn, make_service_fn};
use hyper::{Method, Server, StatusCode};
use serde::Deserialize;
use sputnik::security::CsrfToken;
use sputnik::{request::{Parts, Body}, response::Response};
use sputnik::request::error::*;

#[derive(thiserror::Error, Debug)]
enum Error {
    #[error("page not found")]
    NotFound(String),
    #[error("{0}")]
    CsrfError(#[from] CsrfProtectedFormError)
}

fn render_error(err: Error) -> (StatusCode, String) {
    match err {
        Error::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
        Error::CsrfError(err) => (StatusCode::BAD_REQUEST, err.to_string()),
    }
}

async fn route(req: &mut Parts, body: Body) -> Result<Response,Error> {
    match (req.method(), req.uri().path()) {
        (&Method::GET, "/form") => get_form(req).await,
        (&Method::POST, "/form") => post_form(req, body).await,
        _ => return Err(Error::NotFound("page not found".to_owned()))
    }
}

async fn get_form(req: &mut Parts) -> Result<Response, Error> {
    let mut response = Response::new();
    let csrf_token = CsrfToken::from_parts(req, &mut response);
    *response.body() = format!("<form method=post>
        <input name=text>{}<button>Submit</button></form>", csrf_token.html_input()).into();
    Ok(response)
}

#[derive(Deserialize)]
struct FormData {text: String}

async fn post_form(req: &mut Parts, body: Body) -> Result<Response, Error> {
    let mut response = Response::new();
    let csrf_token = CsrfToken::from_parts(req, &mut response);
    let msg: FormData = body.into_form_csrf(&csrf_token).await?;
    *response.body() = format!("hello {}", msg.text).into();
    Ok(response)
}

/// adapt between Hyper's types and Sputnik's convenience types
async fn service(req: hyper::Request<hyper::Body>) -> Result<hyper::Response<hyper::Body>, Infallible> {
    let (mut parts, body) = sputnik::request::adapt(req);
    match route(&mut parts, body).await {
        Ok(res) => Ok(res.into()),
        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 = OffsetDateTime::now_utc() + Duration::hours(24);
let mut cookie = Cookie::new("userid",
    key.sign(
        &encode_expiring_claim(&userid, expiry_date)
    ));
cookie.set_secure(Some(true));
cookie.set_expires(expiry_date);
cookie.set_same_site(SameSite::Lax);
resp.set_cookie(cookie);
```

This session id cookie can then be retrieved and verified as follows:

```rust
let userid = req.cookies().get("userid")
    .ok_or_else(|| "expected userid cookie".to_owned())
    .and_then(|cookie| key.verify(cookie.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.