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
|
# 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.
|
