From 7b5f208604c73b8491fbc30088c0edd84ef434ef Mon Sep 17 00:00:00 2001 From: Caio Date: Wed, 27 Sep 2023 19:04:32 -0300 Subject: [PATCH] 0.6.0 --- Cargo.lock | 2 +- README.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++ wtx/Cargo.toml | 2 +- wtx/README.md | 65 +---------------------------------------------- 4 files changed, 71 insertions(+), 66 deletions(-) create mode 100644 README.md mode change 100644 => 120000 wtx/README.md diff --git a/Cargo.lock b/Cargo.lock index 1f9d10f8..45e4dc94 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2106,7 +2106,7 @@ checksum = "ed94fce61571a4006852b7389a063ab983c02eb1bb37b47f8272ce92d06d9538" [[package]] name = "wtx" -version = "0.5.2" +version = "0.6.0" dependencies = [ "arbitrary", "async-std", diff --git a/README.md b/README.md new file mode 100644 index 00000000..d7639d52 --- /dev/null +++ b/README.md @@ -0,0 +1,68 @@ +# WTX + +[![CI](https://github.com/c410-f3r/wtx/workflows/CI/badge.svg)](https://github.com/c410-f3r/wtx/actions?query=workflow%3ACI) +[![crates.io](https://img.shields.io/crates/v/wtx.svg)](https://crates.io/crates/wtx) +[![Documentation](https://docs.rs/wtx/badge.svg)](https://docs.rs/wtx) +[![License](https://img.shields.io/badge/license-APACHE2-blue.svg)](./LICENSE) +[![Rustc](https://img.shields.io/badge/rustc-1.71-lightgray")](https://blog.rust-lang.org/2020/03/12/Rust-1.71.html) + +A collection of different web transport implementations. + +## WebSocket + +Provides low and high level abstractions to dispatch frames, as such, it is up to you to implement [Stream](https://docs.rs/wtx/latest/wtx/trait.Stream.html) with any desired logic or use any of the built-in strategies through the selection of features. + + +```rust +use wtx::{ + Stream, + rng::Rng, + web_socket::{ + FrameBufferVec, FrameMutVec, FrameVecMut, compression::NegotiatedCompression, OpCode, + WebSocketClientOwned + } +}; + +pub async fn handle_client_frames( + fb: &mut FrameBufferVec, + ws: &mut WebSocketClientOwned + ) -> wtx::Result<()> { + loop { + let frame = match ws.read_frame(fb).await { + Err(err) => { + println!("Error: {err}"); + ws.write_frame(&mut FrameMutVec::new_fin(fb, OpCode::Close, &[])?).await?; + break; + } + Ok(elem) => elem, + }; + match (frame.op_code(), frame.text_payload()) { + (_, Some(elem)) => println!("{elem}"), + (OpCode::Close, _) => break, + _ => {} + } + } + Ok(()) +} +``` + +See the `examples` directory for more suggestions. + +### Autobahn + +All the `fuzzingclient`/`fuzzingserver` tests provided by the Autobahn|Testsuite project are passing and the full reports can found at https://c410-f3r.github.io/wtx. + +### Compression + +The "permessage-deflate" extension, described in [RFC-7692](https://datatracker.ietf.org/doc/html/rfc7692), is the only supported compression format and is backed by the fastest compression library available at the current time, which is "zlib-ng". It also means that a C compiler is required to use such a feature. + +### Performance + +There are mainly 2 things that impact performance, the chosen runtime and the number of pre-allocated bytes. Specially for servers that have to create a new `WebSocket` instance for each handshake, pre-allocating a high number of bytes for short-lived or low-transfer connections can have a negative impact. + +![Benchmark](https://i.imgur.com/Iv2WzJV.jpg) + +If you disagree with any of the above numbers, feel free to checkout `wtx-bench` to point any misunderstandings or misconfigurations. A more insightful analysis is available at https://c410-f3r.github.io/thoughts/the-fastest-websocket-implementation/. + +¹ `monoio` and `tokio-uring` are slower because owned vectors need to be created on each read/write operation.
+² `embassy` is supported but there isn't a `std` example for measurement purposes. \ No newline at end of file diff --git a/wtx/Cargo.toml b/wtx/Cargo.toml index fce6450a..7f558bad 100644 --- a/wtx/Cargo.toml +++ b/wtx/Cargo.toml @@ -97,7 +97,7 @@ license = "Apache-2.0" name = "wtx" readme = "README.md" repository = "https://github.com/c410-f3r/wtx" -version = "0.5.2" +version = "0.6.0" [package.metadata.docs.rs] all-features = true diff --git a/wtx/README.md b/wtx/README.md deleted file mode 100644 index 1630cef4..00000000 --- a/wtx/README.md +++ /dev/null @@ -1,64 +0,0 @@ -# WTX - -[![CI](https://github.com/c410-f3r/wtx/workflows/CI/badge.svg)](https://github.com/c410-f3r/wtx/actions?query=workflow%3ACI) -[![crates.io](https://img.shields.io/crates/v/wtx.svg)](https://crates.io/crates/wtx) -[![Documentation](https://docs.rs/wtx/badge.svg)](https://docs.rs/wtx) -[![License](https://img.shields.io/badge/license-APACHE2-blue.svg)](./LICENSE) -[![Rustc](https://img.shields.io/badge/rustc-1.71-lightgray")](https://blog.rust-lang.org/2020/03/12/Rust-1.71.html) - -A collection of different web transport implementations. - -## WebSocket - -Provides low and high level abstractions to dispatch frames, as such, it is up to you to implement [Stream](https://docs.rs/wtx/latest/wtx/trait.Stream.html) with any desired logic or use any of the built-in strategies through the selection of features. - - -```rust -use wtx::{ - Stream, - rng::Rng, - web_socket::{ - FrameBufferVec, FrameMutVec, FrameVecMut, compression::NegotiatedCompression, OpCode, - WebSocketClientOwned - } -}; - -pub async fn handle_client_frames( - fb: &mut FrameBufferVec, - ws: &mut WebSocketClientOwned - ) -> wtx::Result<()> { - loop { - let frame = match ws.read_frame(fb).await { - Err(err) => { - println!("Error: {err}"); - ws.write_frame(&mut FrameMutVec::new_fin(fb, OpCode::Close, &[])?).await?; - break; - } - Ok(elem) => elem, - }; - match (frame.op_code(), frame.text_payload()) { - (_, Some(elem)) => println!("{elem}"), - (OpCode::Close, _) => break, - _ => {} - } - } - Ok(()) -} -``` - -See the `examples` directory for more suggestions. - -### Compression - -The "permessage-deflate" extension, described in [RFC-7692](https://datatracker.ietf.org/doc/html/rfc7692), is the only supported compression format and is backed by the fastest compression library available at the current time, which is "zlib-ng". It also means that a C compiler is required to use such a feature. - -### Performance - -There are mainly 2 things that impact performance, the chosen runtime and the number of pre-allocated bytes. Specially for servers that have to create a new `WebSocket` instance for each handshake, pre-allocating a high number of bytes for short-lived or low-transfer connections can have a negative impact. - -![Benchmark](https://i.imgur.com/Iv2WzJV.jpg) - -If you disagree with any of the above numbers, feel free to checkout `wtx-bench` to point any misunderstandings or misconfigurations. A more insightful analysis is available at https://c410-f3r.github.io/thoughts/the-fastest-websocket-implementation/. - -¹ `monoio` and `tokio-uring` are slower because owned vectors need to be created on each read/write operation.
-² `embassy` is supported but there isn't a `std` example for measurement purposes. \ No newline at end of file diff --git a/wtx/README.md b/wtx/README.md new file mode 120000 index 00000000..32d46ee8 --- /dev/null +++ b/wtx/README.md @@ -0,0 +1 @@ +../README.md \ No newline at end of file