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
|
# Sputnik
A microframework based on [Hyper](https://hyper.rs/) providing traits to:
* extend `http::request::Parts` with query parameter deserialization & cookie parsing
* extend `hyper::Body` with form deserialization (and optional [CSRF](https://en.wikipedia.org/wiki/Cross-site_request_forgery) protection)
* extend `http::response::Builder` with methods to set & delete cookies and set the Content-Type
Furthermore Sputnik 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. For most web applications `match`ing on
(method, path) suffices. If you need path variables, you can use one of the
many [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.
## 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::{mime, request::{SputnikParts, SputnikBody}, response::SputnikBuilder};
use sputnik::request::CsrfProtectedFormError;
type Response = hyper::Response<Body>;
#[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 = Builder::new();
let csrf_token = req.csrf_token(&mut response);
Ok(response.content_type(mime::TEXT_HTML).body(
format!("<form method=post>
<input name=text>{}<button>Submit</button></form>", csrf_token.html_input()).into()
).unwrap())
}
#[derive(Deserialize)]
struct FormData {text: String}
async fn post_form(req: &mut Parts, body: Body) -> Result<Response, Error> {
let mut response = Builder::new();
let csrf_token = req.csrf_token(&mut response);
let msg: FormData = body.into_form_csrf(&csrf_token).await?;
Ok(response.body(
format!("hello {}", msg.text).into()
).unwrap())
}
async fn service(req: hyper::Request<hyper::Body>) -> Result<hyper::Response<hyper::Body>, Infallible> {
let (mut parts, body) = req.into_parts();
match route(&mut parts, body).await {
Ok(res) => 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 = 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.
|
