https://github.com/swimos/ratchet
Ratchet is a fast, robust, lightweight and fully asynchronous implementation of RFC6455 (The WebSocket protocol).
https://github.com/swimos/ratchet
async deflate rust tokio websockets
Last synced: over 1 year ago
JSON representation
Ratchet is a fast, robust, lightweight and fully asynchronous implementation of RFC6455 (The WebSocket protocol).
- Host: GitHub
- URL: https://github.com/swimos/ratchet
- Owner: swimos
- License: apache-2.0
- Created: 2021-11-23T11:58:02.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2024-11-06T16:16:05.000Z (over 1 year ago)
- Last Synced: 2024-12-19T09:16:14.285Z (over 1 year ago)
- Topics: async, deflate, rust, tokio, websockets
- Language: Rust
- Homepage:
- Size: 634 KB
- Stars: 41
- Watchers: 8
- Forks: 9
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-websockets - Ratchet - Ratchet is a fast, lightweight and fully asynchronous implementation of the WebSocket protocol with support for extensions and Deflate. (Tools per Language / Rust)
README
# Ratchet
Ratchet is a fast, robust, lightweight and fully asynchronous implementation
of [RFC6455](https://datatracker.ietf.org/doc/html/rfc6455) (The WebSocket protocol). Complete with an optional
implementation of [RFC7692](https://datatracker.ietf.org/doc/html/rfc7692) (Compression Extensions For WebSocket).
Ratchet powers [SwimOS on Rust](https://github.com/swimos/swim-rust/); a framework for real-time streaming data
applications.
[![Crates.io][crates-badge]][crates-url]
[crates-badge]: https://img.shields.io/crates/v/ratchet_rs.svg
[crates-url]: https://crates.io/crates/ratchet_rs
[Documentation](https://docs.rs/ratchet_rs/latest/ratchet_rs/)
# Features
- Implement your own extensions using [ratchet_ext](/ratchet_ext).
- Per-message deflate with [ratchet_deflate](/ratchet_deflate) or enable with the `deflate`
feature.
- Split WebSocket with the `split` feature.
# Testing
Ratchet is fully tested and passes every Autobahn test for both client and server modes.
# Examples
## Client
```rust
#[tokio::main]
async fn main() -> Result<(), Error> {
let stream = TcpStream::connect("127.0.0.1:9001").await?;
let upgraded = subscribe(
WebSocketConfig::default(),
stream,
"ws://127.0.0.1/hello".try_into_request()?,
)
.await?;
let UpgradedClient { socket, subprotocol } = upgraded;
let mut buf = BytesMut::new();
loop {
match websocket.read(&mut buf).await? {
Message::Text => {
websocket.write(&mut buf, PayloadType::Text).await?;
buf.clear();
}
Message::Binary => {
websocket.write(&mut buf, PayloadType::Binary).await?;
buf.clear();
}
Message::Ping | Message::Pong => {
// Ping messages are transparently handled by Ratchet
}
Message::Close(_) => break Ok(()),
}
}
}
```
## Server
```rust
#[tokio::main]
async fn main() -> Result<(), Error> {
let listener = TcpListener::bind("127.0.0.1:9001").await?;
let mut incoming = TcpListenerStream::new(listener);
while let Some(socket) = incoming.next().await {
let socket = socket?;
// An upgrader contains information about what the peer has requested.
let mut upgrader = ratchet::accept_with(
socket,
WebSocketConfig::default(),
NoExtProvider,
SubprotocolRegistry::default(),
)
.await?;
// You could opt to reject the connection
// upgrader.reject(WebSocketResponse::new(404)?).await?;
// continue;
// Or you could reject the connection with headers
// upgrader.reject(WebSocketResponse::with_headers(404, headers)?).await;
// continue;
let UpgradedServer {
request,
mut websocket,
subprotocol,
} = upgrader.upgrade().await?;
let mut buf = BytesMut::new();
loop {
match websocket.read(&mut buf).await? {
Message::Text => {
websocket.write(&mut buf, PayloadType::Text).await?;
buf.clear();
}
Message::Binary => {
websocket.write(&mut buf, PayloadType::Binary).await?;
buf.clear();
}
Message::Ping | Message::Pong => {
// Ping messages are transparently handled by Ratchet
}
Message::Close(_) => break,
}
}
}
Ok(())
}
```
## Deflate
```rust
let mut websocket = ratchet::accept_with(
socket,
WebSocketConfig::default(),
DeflateProvider,
SubprotocolRegistry::default(),
)
.await?;
```
## Split
```rust
// A split operation will only fail if the WebSocket is already closed.
let (mut sender, mut receiver) = websocket.split()?;
loop {
match receiver.read(&mut buf).await? {
Message::Text => {
sender.write(&mut buf, PayloadType::Text).await?;
buf.clear();
}
Message::Binary => {
sender.write(&mut buf, PayloadType::Binary).await?;
buf.clear();
}
Message::Ping | Message::Pong => {}
Message::Close(_) => break Ok(()),
}
}
```
# License
Ratchet is licensed under the [Apache License 2.0](LICENSE)