rustf 1.0.0

A simple MVC web framework inspired by Total.js
Documentation
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
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
//! End-to-end checks for the raw WebSocket path: the `SOCKET` route keyword,
//! `ctx.websocket`, handshake rejection, and the per-route `[json]` /
//! `[max = ..]` flags — all over a real socket against a real server.
//!
//! One server for the whole binary: the framework's configuration is a
//! process-global singleton, so a second `RustF::new()` in the same test
//! binary fails. Every check below hits that one server.

use futures::{SinkExt, StreamExt};
use rustf::prelude::*;
use std::net::SocketAddr;
use std::time::Duration;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpStream;
use tokio_tungstenite::tungstenite::client::IntoClientRequest;
use tokio_tungstenite::tungstenite::protocol::frame::coding::CloseCode;
use tokio_tungstenite::tungstenite::Message as ClientMessage;

/// What the tungstenite client stream yields. Spelled out because
/// `rustf::prelude::*` brings its own one-parameter `Result` into scope.
type ClientItem = std::result::Result<ClientMessage, tokio_tungstenite::tungstenite::Error>;

// ---------------------------------------------------------------- handlers

/// Echoes every message back, unchanged.
async fn echo(ctx: &mut Context) -> rustf::Result<()> {
    ctx.websocket(|mut socket| async move {
        while let Some(message) = socket.recv().await {
            socket.send(message?).await?;
        }
        Ok(())
    })
}

/// Sends the route parameters back, so we can prove `{name}` is extracted
/// before the upgrade.
async fn greet(ctx: &mut Context) -> rustf::Result<()> {
    let name = ctx.param_str("name").unwrap_or_default();
    ctx.websocket(move |mut socket| async move {
        socket.send_text(format!("hello {name}")).await?;
        while socket.recv().await.is_some() {}
        Ok(())
    })
}

/// Requires an authenticated session. Nothing here has one, so it must 401
/// and never upgrade.
///
/// Written the way an app author would write it — `ctx.require_auth()?` — which
/// also pins the handler-error status mapping on the socket path.
async fn guarded(ctx: &mut Context) -> rustf::Result<()> {
    ctx.require_auth()?;

    ctx.websocket(|mut socket| async move {
        while socket.recv().await.is_some() {}
        Ok(())
    })
}

/// `[json]`: non-JSON text must be refused by the framework, not the handler.
async fn json_only(ctx: &mut Context) -> rustf::Result<()> {
    ctx.websocket(|mut socket| async move {
        while let Some(message) = socket.recv().await {
            socket.send(message?).await?;
        }
        Ok(())
    })
}

/// `[max = 64]`: anything larger must be refused by the framework.
async fn small(ctx: &mut Context) -> rustf::Result<()> {
    ctx.websocket(|mut socket| async move {
        while let Some(message) = socket.recv().await {
            socket.send(message?).await?;
        }
        Ok(())
    })
}

/// A handler that asks for a socket from a route that is not `SOCKET`.
async fn not_a_socket(ctx: &mut Context) -> rustf::Result<()> {
    ctx.websocket(|mut socket| async move {
        while socket.recv().await.is_some() {}
        Ok(())
    })
}

/// An ordinary page, so the socket routes are not the only thing registered.
async fn page(ctx: &mut Context) -> rustf::Result<()> {
    ctx.plain("chat page")
}

fn install_routes() -> Vec<Route> {
    routes![
        GET    "/chat"          => page,
        GET    "/mistake"       => not_a_socket,
        SOCKET "/echo"          => echo,
        SOCKET "/greet/{name}"  => greet,
        SOCKET "/guarded"       => guarded,
        SOCKET "/json"          => json_only, [json],
        SOCKET "/small"         => small, [max = 64],
    ]
}

// ----------------------------------------------------------------- helpers

/// Minimal HTTP/1.1 GET, returning the response head (status line plus
/// headers).
///
/// Reads up to the header terminator rather than to EOF: an accepted
/// handshake answers `101` and then keeps the connection open forever, so
/// `read_to_end` would never return. `Connection: close` is deliberately not
/// sent either — it is meaningless on an upgrade request.
async fn http_get(addr: SocketAddr, path: &str, extra_headers: &str) -> String {
    let mut stream = TcpStream::connect(addr).await.unwrap();
    let request = format!("GET {path} HTTP/1.1\r\nHost: {addr}\r\n{extra_headers}\r\n");
    stream.write_all(request.as_bytes()).await.unwrap();

    let mut response = Vec::new();
    let mut byte = [0u8; 1];
    let read = async {
        loop {
            match stream.read(&mut byte).await.unwrap() {
                0 => break,
                _ => {
                    response.push(byte[0]);
                    if response.ends_with(b"\r\n\r\n") {
                        break;
                    }
                }
            }
        }
    };

    tokio::time::timeout(Duration::from_secs(5), read)
        .await
        .unwrap_or_else(|_| panic!("timed out reading the response head for {path}"));

    String::from_utf8_lossy(&response).into_owned()
}

/// Status line of a raw HTTP response, e.g. `HTTP/1.1 426 Upgrade Required`.
fn status_line(response: &str) -> &str {
    response.lines().next().unwrap_or("")
}

async fn connect(
    addr: SocketAddr,
    path: &str,
) -> tokio_tungstenite::WebSocketStream<tokio_tungstenite::MaybeTlsStream<TcpStream>> {
    let (socket, _) = tokio_tungstenite::connect_async(format!("ws://{addr}{path}"))
        .await
        .unwrap_or_else(|e| panic!("connecting to {path} failed: {e}"));
    socket
}

/// Read the next message, failing the test rather than hanging forever.
async fn next_message<S>(socket: &mut S) -> Option<ClientMessage>
where
    S: StreamExt<Item = ClientItem> + Unpin,
{
    match tokio::time::timeout(Duration::from_secs(5), socket.next()).await {
        Ok(Some(Ok(message))) => Some(message),
        Ok(Some(Err(error))) => panic!("socket error: {error}"),
        Ok(None) => None,
        Err(_) => panic!("timed out waiting for a message"),
    }
}

/// Drain until a close frame arrives, returning its code.
///
/// Keeps reading afterwards, which is how a normal client loop answers a close:
/// tungstenite queues the reply frame and flushes it on the next read. Without
/// that the server would sit out its five-second wait for a reply that never
/// comes, on every route that closes from the server side.
async fn close_code<S>(socket: &mut S) -> Option<CloseCode>
where
    S: StreamExt<Item = ClientItem> + Unpin,
{
    let mut code = None;

    loop {
        match tokio::time::timeout(Duration::from_secs(5), socket.next()).await {
            Ok(Some(Ok(ClientMessage::Close(frame)))) => {
                code = frame.map(|f| f.code);
                // Keep going: the next read is what puts our reply on the wire.
                continue;
            }
            Ok(Some(Ok(_))) => continue,
            // The stream ends once the close handshake is complete.
            Ok(Some(Err(_))) | Ok(None) => return code,
            Err(_) => panic!("timed out waiting for a close frame"),
        }
    }
}

// -------------------------------------------------------------------- test

#[tokio::test]
async fn websocket_routes_behave_correctly_on_the_wire() {
    let app = RustF::new().controllers(install_routes());
    let running = app.serve_with_handle("127.0.0.1:0").await.unwrap();
    let addr = running.local_addr;

    // --- ordinary routes still work next to socket routes ---
    let response = http_get(addr, "/chat", "").await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 200"),
        "{response}"
    );

    // --- a plain GET on a SOCKET route is 426, and the handler never runs ---
    let response = http_get(addr, "/echo", "").await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 426"),
        "a non-handshake GET on a SOCKET route must be 426: {response}"
    );
    assert!(
        response.to_lowercase().contains("upgrade: websocket"),
        "426 must advertise the protocol to switch to: {response}"
    );
    assert!(
        response
            .to_lowercase()
            .contains("sec-websocket-version: 13"),
        "426 must advertise the supported version: {response}"
    );

    // --- a handshake with the wrong version is refused ---
    let response = http_get(
        addr,
        "/echo",
        "Upgrade: websocket\r\nConnection: Upgrade\r\n\
         Sec-WebSocket-Version: 8\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n",
    )
    .await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 426"),
        "an unsupported version must be refused: {response}"
    );

    // --- a handshake with a malformed key is a 400 ---
    let response = http_get(
        addr,
        "/echo",
        "Upgrade: websocket\r\nConnection: Upgrade\r\n\
         Sec-WebSocket-Version: 13\r\nSec-WebSocket-Key: nope\r\n",
    )
    .await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 400"),
        "a malformed Sec-WebSocket-Key must be refused: {response}"
    );

    // --- a handshake from a foreign origin is a 403, and never upgrades ---
    let response = http_get(
        addr,
        "/echo",
        "Upgrade: websocket\r\nConnection: Upgrade\r\n\
         Sec-WebSocket-Version: 13\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\
         Origin: http://evil.example\r\n",
    )
    .await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 403"),
        "a cross-origin handshake must be refused: {response}"
    );

    // --- the site's own origin is accepted ---
    let response = http_get(
        addr,
        "/echo",
        &format!(
            "Upgrade: websocket\r\nConnection: Upgrade\r\n\
             Sec-WebSocket-Version: 13\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\
             Origin: http://{addr}\r\n"
        ),
    )
    .await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 101"),
        "a same-origin handshake must be accepted: {response}"
    );
    assert!(
        response.contains("s3pPLMBiTxaQ9kYGzzhZRbK+xOo="),
        "the 101 must carry the RFC-derived Sec-WebSocket-Accept: {response}"
    );

    // --- an unauthenticated request to a guarded socket is 401, no upgrade ---
    let response = http_get(
        addr,
        "/guarded",
        "Upgrade: websocket\r\nConnection: Upgrade\r\n\
         Sec-WebSocket-Version: 13\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n",
    )
    .await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 401"),
        "an auth check must reject before the upgrade: {response}"
    );

    // --- a duplicated singleton handshake header is refused ---
    // Two `Origin` headers collapse into one map entry, so whichever survived
    // would decide the origin check. RFC 6455 allows exactly one.
    let response = http_get(
        addr,
        "/echo",
        "Upgrade: websocket\r\nConnection: Upgrade\r\n\
         Sec-WebSocket-Version: 13\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\
         Origin: http://evil.example\r\nOrigin: http://example.com\r\n",
    )
    .await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 400"),
        "a duplicated Origin must be refused, not silently resolved: {response}"
    );

    let response = http_get(
        addr,
        "/echo",
        "Upgrade: websocket\r\nConnection: Upgrade\r\n\
         Sec-WebSocket-Version: 13\r\n\
         Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n\
         Sec-WebSocket-Key: AAAAAAAAAAAAAAAAAAAAAA==\r\n",
    )
    .await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 400"),
        "a duplicated Sec-WebSocket-Key must be refused: {response}"
    );

    // --- ctx.websocket outside a SOCKET route is a server error, not a socket ---
    let response = http_get(
        addr,
        "/mistake",
        "Upgrade: websocket\r\nConnection: Upgrade\r\n\
         Sec-WebSocket-Version: 13\r\nSec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==\r\n",
    )
    .await;
    assert!(
        status_line(&response).starts_with("HTTP/1.1 500"),
        "asking for a socket from a GET route must fail loudly: {response}"
    );

    // --- a real echo round trip, then a clean close handshake ---
    let mut socket = connect(addr, "/echo").await;
    socket
        .send(ClientMessage::Text("hello".into()))
        .await
        .unwrap();
    assert_eq!(
        next_message(&mut socket).await,
        Some(ClientMessage::Text("hello".into()))
    );

    socket
        .send(ClientMessage::Binary(vec![1, 2, 3].into()))
        .await
        .unwrap();
    match next_message(&mut socket).await {
        Some(ClientMessage::Binary(bytes)) => assert_eq!(&bytes[..], &[1, 2, 3]),
        other => panic!("expected the binary frame back, got {other:?}"),
    }

    socket.close(None).await.unwrap();
    // A completed close handshake ends the stream cleanly. Anything else —
    // notably a reset — means the server dropped the socket without replying.
    while next_message(&mut socket).await.is_some() {}

    // --- route parameters are extracted before the upgrade ---
    let mut socket = connect(addr, "/greet/morle").await;
    assert_eq!(
        next_message(&mut socket).await,
        Some(ClientMessage::Text("hello morle".into()))
    );
    socket.close(None).await.unwrap();

    // --- [json]: valid JSON passes through ---
    let mut socket = connect(addr, "/json").await;
    socket
        .send(ClientMessage::Text(r#"{"a":1}"#.into()))
        .await
        .unwrap();
    assert_eq!(
        next_message(&mut socket).await,
        Some(ClientMessage::Text(r#"{"a":1}"#.into()))
    );

    // --- [json]: anything else is closed with 1003 ---
    socket
        .send(ClientMessage::Text("not json".into()))
        .await
        .unwrap();
    assert_eq!(
        close_code(&mut socket).await,
        Some(CloseCode::Unsupported),
        "non-JSON text on a [json] route must close with 1003"
    );

    // --- [max = 64]: a larger message is closed with 1009 ---
    let mut socket = connect(addr, "/small").await;
    socket
        .send(ClientMessage::Text("x".repeat(16).into()))
        .await
        .unwrap();
    assert_eq!(
        next_message(&mut socket).await,
        Some(ClientMessage::Text("x".repeat(16).into())),
        "a message within the cap must still be echoed"
    );

    socket
        .send(ClientMessage::Text("x".repeat(256).into()))
        .await
        .unwrap();
    assert_eq!(
        close_code(&mut socket).await,
        Some(CloseCode::Size),
        "a message over the route's [max] must close with 1009"
    );

    // --- the handshake a real client builds is answered correctly ---
    assert_handshake_response_is_correct(addr).await;

    running.handle.shutdown().await.unwrap();
}

/// The handshake a real client builds, checked against what RustF answers.
///
/// Driven through the same server as the test above — one server per binary —
/// so this asserts on the actual `101`, not just on the request headers.
async fn assert_handshake_response_is_correct(addr: SocketAddr) {
    use base64::Engine as _;
    use sha1::Digest as _;

    let request = format!("ws://{addr}/echo").into_client_request().unwrap();
    assert_eq!(
        request.headers().get("sec-websocket-version").unwrap(),
        "13",
        "a client must ask for version 13"
    );
    let key = request
        .headers()
        .get("sec-websocket-key")
        .expect("a client must send a key")
        .to_str()
        .unwrap()
        .to_string();

    // What RFC 6455 §4.2.2 says the server must derive from that key.
    let mut hasher = sha1::Sha1::new();
    hasher.update(key.as_bytes());
    hasher.update(b"258EAFA5-E914-47DA-95CA-C5AB0DC85B11");
    let expected = base64::engine::general_purpose::STANDARD.encode(hasher.finalize());

    let response = http_get(
        addr,
        "/echo",
        &format!(
            "Upgrade: websocket\r\nConnection: Upgrade\r\n\
             Sec-WebSocket-Version: 13\r\nSec-WebSocket-Key: {key}\r\n"
        ),
    )
    .await;

    assert!(
        status_line(&response).starts_with("HTTP/1.1 101"),
        "a well-formed handshake must be accepted: {response}"
    );
    let lower = response.to_lowercase();
    assert!(lower.contains("upgrade: websocket"), "{response}");
    assert!(lower.contains("connection: upgrade"), "{response}");
    assert!(
        response.contains(&expected),
        "the 101 must carry the accept key derived from this client's key: {response}"
    );
    assert!(
        !lower.contains("sec-websocket-extensions"),
        "nothing negotiated an extension: {response}"
    );
}