# 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:
```json
{
"type" : "ping",
"value" : {
"msg" : "Hey kitty kitty"
}
}
```
Which will then be mapped to a struct such as:
```rust
#[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:
```rust
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.