meows

Crates.iomeows
lib.rsmeows
version0.2.0
sourcesrc
created_at2020-06-14 16:13:34.870459
updated_at2020-06-21 20:09:46.654184
descriptionA simple pattern for async service messaging over WebSockets
homepagehttps://github.com/rtyler/meows
repositoryhttps://github.com/rtyler/meows
max_upload_size
id253897
size88,433
R. Tyler Croy (rtyler)

documentation

README

Message Exchange Over Web Sockets 🐈

This crate implements the simple pattern needed for implementing service-to-service message exchange over WebSocket connections. Users of meows can handle typed JSON message with the option for a default handler for any un-typed messages.

Meows is built on top of link:https://github.com/stjepang/smol[smol] for async websocket handling behavior. This makes Meows compatible with other smol-based applications, including those using link:https://github.com/async-rs/async-std[async-std] 1.6.0 or later.

All messages intended to be handled must be wrapped in a meows appropriate envelope described below:

{
    "type" : "ping",
    "value" : {
        "msg" : "Hey kitty kitty"
    }
}

Which will then be mapped to a struct such as:

#[derive(Debug, Deserialize, Serialize)]
struct Ping {
    msg: String,
}

In essence, anything that serde can deserialize, can be passed through meows.

Example

There are examples in the examples/ directory, here's a simple message handler:

use log::*;
use meows::*;
use smol;

async fn handle_ping(mut req: Request<()>) -> Option<Message> {
    if let Some(ping) = req.from_value::<Ping>() {
        info!("Ping received with message: {}", ping.msg);
    }
    Some(Message::text("pong"))
}

fn main() -> Result<(), std::io::Error> {
    info!("Starting simple ping/pong websocket server with meows");
    let mut server = meows::Server::new();
    server.on("ping", handle_ping);

    smol::run(async move {
        server.serve("127.0.0.1:8105".to_string()).await
    })
}

Contributing

Meows is a typical Rust project, e.g. cargo build and cargo test will do most everything you would need to do.

There aren't nearly enough tests, helping with that would certainly be appreciated :)

Licensing

This crate is licensed as GPL-3.0+, which roughly means that if you're packaging up Meows and distributing a binary to an end-user, you must also make the source of the Meows code available to that end-user. It is intentionally not AGPL licensed, which means if you incorporate Meows into server-side code that is never distributed to end-users, then you do not need to make the code available to the service's users.

Commit count: 34

cargo fmt