Merge pull request ohkami-rs#39 from ohkami-rs/reduce-runtime-crate-dependence

[BREAKING] reduce-runtime-crate-dependence

Author: kanarus

Cargo.toml

@@ -13,48 +13,30 @@ keywords      = ["websocket", "io", "web", "async"]
 categories    = ["web-programming::websocket", "network-programming", "asynchronous"]
 
 [package.metadata.docs.rs]
-features = ["rt_tokio"]
+features = ["io_tokio"]
 
 [dependencies]
-tokio   = { optional = true, version = "1"   }
-smol    = { optional = true, version = "2"   }
-glommio = { optional = true, version = "0.9" }
-nio     = { optional = true, version = "0.0" }
-
-futures-util = { version = "0.3", default-features = false }
+# IO interfaces / utilities
+tokio        = { optional = true, version = "1" }
+futures-util = { optional = true, version = "0.3", default-features = false }
 
+# crypto / encoding
 sha1   = { version = "0.10", default-features = false }
 base64 = { version = "0.22" }
 
 [features]
-### runtimes ###
-rt_tokio = [
-    "__runtime__", "__io_tokio__",
-    "dep:tokio","tokio/net","tokio/sync","tokio/time",
-]
-rt_smol = [
-    "__runtime__", "__io_futures__",
-    "dep:smol"
-]
-rt_glommio = [
-    "__runtime__", "__io_futures__",
-    "dep:glommio"
+io_tokio   = ["__io__",
+    "dep:tokio","tokio/io-util",
+    "dep:futures-util","futures-util/alloc","futures-util/unstable","futures-util/bilock" # for `BiLock` for `split` impl
 ]
-rt_nio = [
-    "__runtime__", "__io_tokio__",
-    "dep:nio",
-    "dep:tokio","tokio/sync"
+io_futures = ["__io__",
+    "dep:futures-util", "futures-util/io"
 ]
 
-### optimizations ###
-tcpstream-only = []
-
 ### internal ###
-__runtime__    = []
-__io_tokio__   = ["dep:tokio","tokio/io-util", "futures-util/alloc","futures-util/unstable","futures-util/bilock"]
-__io_futures__ = ["futures-util/io"]
+__io__ = [
+    "dep:tokio","tokio/sync" # for `RwLock` for `Connection`'s close handling
+]
 
-#####################################
-DEBUG = ["tokio?/rt"] ###############
-## default = ["rt_tokio", "DEBUG"] ##
-#####################################
+[dev-dependencies]
+tokio = { version = "1", features = ["full"] }

README.md

@@ -15,7 +15,10 @@
 
 * Minimal and Efficient : minimal codebase to provide efficient, memory-safe WebSocket handling.
 
-* Multi-Environment : `tokio`, `smol`, `glommio`, `nio` are supported as async runtime ( by feature flags `rt_{name}` ).
+* Multi-Environment : works with any async runtimes with `tokio::io` or `futures_io` interface
+  (for example: `tokio` or `nio` use `tokio::io` interface,
+  and `smol` or `glommio` use `futures_io` interface).\
+  Feature flags **`io_tokio`** or **`io_futures`** enables integration for respective IO interface.
 
 ## Note
 
@@ -25,15 +28,15 @@ MEWS is NOT WebSocket server, just protocol implementation. So :
 
 * Doesn't builtins `wss://` support.
 
-## Feature Flags
+## Usage
 
-- `tcpstream-only` : limit `split` functionality to only the runtime's `TcpStream`, in exchange for possible performance optimization.
+**`io_tokio`** or **`io_futures`** must be activated to integrate with async IO interfaces.
 
-## Example
+Here specifying `io_tokio` to use with `tokio`:
 
 ```toml
 [dependencies]
-mews  = { version = "0.4.0", features = ["rt_tokio"] }
+mews  = { version = "0.4.0", features = ["io_tokio"] }
 tokio = { version = "1", features = ["full"] }
 # ...
 ```

Taskfile.yaml

@@ -3,21 +3,20 @@ version: 3
 tasks:
   CI:
     deps:
-      - for:  [tokio, smol, glommio, nio]
-        task: test:rt
-        vars: { rt: '{{.ITEM}}' }
-      - task: test:no_rt
+      - for:  [tokio, futures]
+        task: test:with_io
+        vars: { io: '{{.ITEM}}' }
+      - task: test:without_io
       - task: test:doc
 
-  test:rt:
+  test:with_io:
     cmds:
-      - cargo test --lib --features rt_{{.rt}}
-      - cargo test --lib --features rt_{{.rt}},tcpstream-only
+      - cargo test --lib --features io_{{.io}}
 
-  test:no_rt:
+  test:without_io:
     cmds:
       - cargo test
 
   test:doc:
     cmds:
-      - cargo test --doc --features rt_tokio,DEBUG
+      - cargo test --doc --features io_tokio

src/connection.rs

@@ -1,5 +1,8 @@
+#![cfg(feature="__io__")]
+
+use crate::io::{AsyncRead, AsyncWrite};
+use crate::sync::RwLock;
 use crate::{Config, Message};
-use crate::runtime::{AsyncRead, AsyncWrite, RwLock};
 use std::{sync::Arc, io::Error};
 
 pub trait UnderlyingConnection: AsyncRead + AsyncWrite + Unpin + 'static {}
@@ -19,24 +22,11 @@ pub struct Connection<C: UnderlyingConnection> {
 /*============================================================*/
     #[inline(always)]
     async fn read_closed(__closed__: &RwLock<bool>) -> bool {
-        #[cfg(feature="rt_glommio")]
-        match __closed__.read().await {
-            Ok(read) => *read,
-            Err(_/* closed */) => true
-        }
-        #[cfg(not(feature="rt_glommio"))]
         *__closed__.read().await
     }
     #[inline(always)]
     async fn set_closed(__closed__: &RwLock<bool>) {
-        #[cfg(feature="rt_glommio")] {
-            if let Ok(mut write) = __closed__.write().await {
-                *write = true
-            }
-        }
-        #[cfg(not(feature="rt_glommio"))] {
-            *__closed__.write().await = true
-        }
+        *__closed__.write().await = true
     }
 
     const ALREADY_CLOSED_MESSAGE: &str = "\n\
@@ -333,17 +323,8 @@ pub mod split {
         }
     }
 
-    #[cfg(feature="__io_futures__")]
+    #[cfg(feature="io_futures")]
     const _: (/* futures-io users */) = {
-        #[cfg(feature="tcpstream-only")]
-        impl<'split> Splitable<'split> for crate::runtime::net::TcpStream {
-            type ReadHalf  = futures_util::io::ReadHalf<&'split mut Self>;
-            type WriteHalf = futures_util::io::WriteHalf<&'split mut Self>;
-            fn split(&'split mut self) -> (Self::ReadHalf, Self::WriteHalf) {
-                AsyncRead::split(self)
-            }
-        }
-        #[cfg(not(feature="tcpstream-only"))]
         impl<'split, T: AsyncRead + AsyncWrite + Unpin + 'split> Splitable<'split> for T {
             type ReadHalf  = futures_util::io::ReadHalf<&'split mut T>;
             type WriteHalf = futures_util::io::WriteHalf<&'split mut T>;
@@ -353,20 +334,7 @@ pub mod split {
         }
     };
 
-    #[cfg(feature="__io_tokio__")]
-    #[cfg(feature="tcpstream-only")]
-    const _: (/* tokio::io users */) = {
-        /* efficient-able specialized impl for `TcpStream` */
-        impl<'split> Splitable<'split> for crate::runtime::net::TcpStream {
-            type ReadHalf  = crate::runtime::net::tcp::ReadHalf<'split>;
-            type WriteHalf = crate::runtime::net::tcp::WriteHalf<'split>;
-            fn split(&'split mut self) -> (Self::ReadHalf, Self::WriteHalf) {
-                crate::runtime::net::TcpStream::split(self)
-            }
-        }
-    };
-    #[cfg(feature="__io_tokio__")]
-    #[cfg(not(feature="tcpstream-only"))]
+    #[cfg(feature="io_tokio")]
     const _: (/* tokio::io users */) = {
         impl<'split, T: AsyncRead + AsyncWrite + Unpin + 'split> Splitable<'split> for T {
             type ReadHalf  = TokioIoReadHalf<'split, T>;
@@ -494,15 +462,3 @@ pub mod split {
         }
     }
 }
-
-#[cfg(test)]
-mod tests {
-    use super::*;
-    
-    #[cfg(feature="__runtime__")]
-    #[test]
-    fn test_impl_splitable() {
-        fn assert_impl_splitable<T: split::Splitable<'static>>() {}
-        assert_impl_splitable::<crate::runtime::net::TcpStream>();
-    }
-}

src/frame.rs

@@ -1,8 +1,9 @@
+#![cfg(feature="__io__")]
+
 use std::io::{Error, ErrorKind};
-use crate::runtime::{AsyncRead, AsyncWrite};
+use crate::io::{AsyncRead, AsyncWrite};
 use crate::Config;
 
-
 #[derive(Debug, PartialEq)]
 pub(crate) enum OpCode {
     /* data op codes */
@@ -45,7 +46,7 @@ pub(crate) struct Frame {
     pub(crate) payload:  Vec<u8>,
 }
 
-#[cfg(feature="__runtime__")]
+#[cfg(feature="__io__")]
 impl Frame {
     pub(crate) async fn read_from(
         stream: &mut (impl AsyncRead + Unpin),

src/lib.rs

@@ -25,72 +25,31 @@
 //! 
 //! * Doesn't builtins `wss://` support.
 
-#[cfg(any(
-    all(feature="rt_tokio",   any(feature="rt_smol",    feature="rt_glommio")),
-    all(feature="rt_smol",    any(feature="rt_glommio", feature="rt_tokio"  )),
-    all(feature="rt_glommio", any(feature="rt_tokio",   feature="rt_smol"   )),
-))]
-compile_error! {"More than one runtime feature flags can't be activated"}
-
-#[cfg(feature="rt_tokio")]
-mod runtime {
-    pub use {
-        tokio::io::AsyncReadExt as AsyncRead,
-        tokio::io::AsyncWriteExt as AsyncWrite,
-        tokio::sync::RwLock,
-        tokio::time::sleep
-    };
-    #[cfg(any(test, feature="tcpstream-only"))]
-    pub use tokio::net;
-}
-#[cfg(feature="rt_smol")]
-mod runtime {
-    pub use {
-        futures_util::AsyncReadExt as AsyncRead,
-        futures_util::AsyncWriteExt as AsyncWrite,
-        smol::lock::RwLock,
-    };
-    pub async fn sleep(duration: std::time::Duration) {
-        smol::Timer::after(duration).await;
-    }
-    #[cfg(any(test, feature="tcpstream-only"))]
-    pub use smol::net;
+#[cfg(feature="__io__")]
+mod io {
+    #[cfg(feature="io_tokio")]
+    pub(crate) use tokio::io::{AsyncReadExt as AsyncRead, AsyncWriteExt as AsyncWrite};
+    #[cfg(feature="io_futures")]
+    pub(crate) use futures_util::io::{AsyncReadExt as AsyncRead, AsyncWriteExt as AsyncWrite};
 }
-#[cfg(feature="rt_glommio")]
-mod runtime {
-    pub use {
-        futures_util::AsyncReadExt as AsyncRead,
-        futures_util::AsyncWriteExt as AsyncWrite,
-        glommio::sync::RwLock,
-        glommio::timer::sleep
-    };
-    #[cfg(any(test, feature="tcpstream-only"))]
-    pub use glommio::net;
-}
-#[cfg(feature="rt_nio")]
-mod runtime {
-    pub use {
-        tokio::io::AsyncReadExt as AsyncRead,
-        tokio::io::AsyncWriteExt as AsyncWrite,
-        tokio::sync::RwLock,
-        nio::time::sleep
-    };
-    #[cfg(any(test, feature="tcpstream-only"))]
-    pub use nio::net;
+
+#[cfg(feature="__io__")]
+mod sync {
+    pub(crate) use tokio::sync::RwLock;
 }
 
+#[cfg(feature="__io__")]
 pub mod message;
-#[cfg(feature="__runtime__")]
+#[cfg(feature="__io__")]
 pub mod frame;
-#[cfg(feature="__runtime__")]
+#[cfg(feature="__io__")]
 pub mod websocket;
-#[cfg(feature="__runtime__")]
+#[cfg(feature="__io__")]
 pub mod connection;
 
-pub use message::{Message, CloseFrame, CloseCode};
-#[cfg(feature="__runtime__")]
+#[cfg(feature="__io__")]
 pub use {
+    message::{Message, CloseFrame, CloseCode},
     websocket::*,
-    connection::Connection,
-    connection::split::{self, Splitable, ReadHalf, WriteHalf},
+    connection::{Connection, split::{self, Splitable, ReadHalf, WriteHalf}},
 };

src/message.rs

@@ -1,10 +1,8 @@
-#[cfg(feature="__runtime__")]
-use {
-    std::io::{Error, ErrorKind},
-    crate::runtime::{AsyncRead, AsyncWrite},
-    crate::frame::{Frame, OpCode},
-    crate::Config,
-};
+#![cfg(feature="__io__")]
+use crate::frame::{Frame, OpCode};
+use crate::io::{AsyncRead, AsyncWrite};
+use crate::Config;
+use std::io::{Error, ErrorKind};
 
 #[derive(Debug)]
 pub enum Message {
@@ -85,7 +83,7 @@ impl CloseCode {
     }
 }
 
-#[cfg(feature="__runtime__")]
+#[cfg(feature="__io__")]
 impl CloseCode {
     pub(super) fn from_bytes(bytes: [u8; 2]) -> Self {
         Self::from(u16::from_be_bytes(bytes))
@@ -97,7 +95,7 @@ impl CloseCode {
     }
 }
 
-#[cfg(feature="__runtime__")]
+#[cfg(feature="__io__")]
 impl Message {
     const PING_PONG_PAYLOAD_LIMIT: usize = 125;