rustwave 0.1.0

A lightweight async event-driven WebSocket framework for Rust
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

use std::fmt::Display;

use serde::{Deserialize, Serialize, de::DeserializeOwned};
use serde_json::Value;

#[derive(Debug, Serialize, Deserialize)]
pub(crate) struct Response<T: Serialize> {
    pub event: String,
    pub data: T,
}

#[derive(Debug, Serialize, Deserialize)]
pub(crate) struct Request {
    pub event: String,
    pub data: Value,
}

/// The data carried by an event, either received from a peer/server or
/// about to be sent.
#[derive(Clone, Debug)]
pub struct Payload {
    data: Value,
}

impl Payload {
    pub(crate) fn new(data: Value) -> Self {
        Self { data }
    }

    /// Deserializes the payload into a concrete type `T`.
    ///
    /// # Errors
    ///
    /// Returns an error if the payload's data doesn't match the shape
    /// expected by `T`.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use rustwave::{Server, Result};
    /// use serde::Deserialize;
    ///
    /// #[derive(Deserialize)]
    /// struct ChatMessage {
    ///     text: String,
    /// }
    ///
    /// #[tokio::main]       
    /// async fn main() -> Result<()> {
    ///     let server = Server::bind("127.0.0.1:8080");
    ///     server.on("message", |data, ctx| async move {
    ///         // parse returns a Result
    ///         if let Ok(message) = data.parse::<ChatMessage>() {
    ///             println!("Client {} say: {}", ctx.get_socket_id(), message.text);
    ///         }
    ///         
    ///     });
    ///     server.run().await?;
    ///     Ok(())
    /// }
    /// ```
    pub fn parse<T: DeserializeOwned>(&self) -> Result<T, serde_json::Error> {
        serde_json::from_value(self.data.clone())
    }

    /// Returns the payload's underlying data as a raw JSON string.
    ///
    /// Useful when you don't need to deserialize into a concrete type, e.g.
    /// for logging or re-broadcasting the data as-is.
    ///
    /// # Example
    ///
    /// ```no_run
    /// use rustwave::{Server, Result};
    ///
    /// #[tokio::main]
    /// async fn main() -> Result<()> {
    ///     let server = Server::bind("127.0.0.1:8080");
    ///
    ///     server.on("message", |data, ctx| async move {
    ///         println!("Client {} say: {}", ctx.get_socket_id(), data.raw());
    ///     });
    ///
    ///     server.run().await?;
    ///
    ///     Ok(())
    /// }
    /// ```
    pub fn raw(&self) -> String {
        self.data.to_string()
    }
}

impl Display for Payload {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.data)
    }
}