Prepare to release next api (#67)

Not actually releasing it _yet_ but this gets it in a place where I can

- Exposing it at the top-level
- Deprecating the old code
- Re-organising a bit to make cleaning up later easier
- Updating examples

CHANGELOG.md

@@ -11,6 +11,18 @@ all APIs might be changed.
 
 ## Unreleased - xxxx-xx-xx
 
+### Breaking Changes
+
+- The `next` api is now available at the top level rather than the `next`
+  module.
+
+### Deprecations
+
+These will be removed in a future version, probably in v0.9.0
+
+- `AsyncWebsocketClient` and all its supporting traits and structs are now
+  deprecated.
+
 ### New Features
 
 - Added a `streaming_operation` function to `next::ClientBuilder` to make

examples-wasm/examples/subscriptions.rs

@@ -5,7 +5,7 @@
 
 use std::future::IntoFuture;
 
-use graphql_ws_client::{next::Client, ws_stream_wasm::Connection};
+use graphql_ws_client::{ws_stream_wasm::Connection, Client};
 
 mod schema {
     cynic::use_schema!("../schemas/books.graphql");

examples/examples/mulitiple-subscriptions.rs

@@ -1,8 +1,11 @@
 //! An example of running a multiple subscriptions on a single connection
-//! using `graphql-ws-client` and `async-tungstenite`
+//! using `graphql-ws-client`, `async-tungstenite` & the `async_std`
+//! executor.
 //!
 //! Talks to the the tide subscription example in `async-graphql`
 
+use std::future::IntoFuture;
+
 mod schema {
     cynic::use_schema!("../schemas/books.graphql");
 }
@@ -38,7 +41,7 @@ struct BooksChangedSubscription {
 async fn main() {
     use async_tungstenite::tungstenite::{client::IntoClientRequest, http::HeaderValue};
     use futures::StreamExt;
-    use graphql_ws_client::CynicClientBuilder;
+    use graphql_ws_client::Client;
 
     let mut request = "ws://localhost:8000/graphql".into_client_request().unwrap();
     request.headers_mut().insert(
@@ -52,12 +55,8 @@ async fn main() {
 
     println!("Connected");
 
-    let (sink, stream) = connection.split();
-
-    let mut client = CynicClientBuilder::new()
-        .build(stream, sink, async_executors::AsyncStd)
-        .await
-        .unwrap();
+    let (mut client, actor) = Client::build(connection).await.unwrap();
+    async_std::task::spawn(actor.into_future());
 
     // In reality you'd probably want to different subscriptions, but for the sake of this example
     // these are the same subscriptions

examples/examples/single-subscription.rs

@@ -38,7 +38,7 @@ struct BooksChangedSubscription {
 async fn main() {
     use async_tungstenite::tungstenite::{client::IntoClientRequest, http::HeaderValue};
     use futures::StreamExt;
-    use graphql_ws_client::next::Client;
+    use graphql_ws_client::Client;
 
     let mut request = "ws://localhost:8000/graphql".into_client_request().unwrap();
     request.headers_mut().insert(

examples/examples/tokio.rs

@@ -3,7 +3,7 @@
 //!
 //! Talks to the the tide subscription example in `async-graphql`
 
-use examples::TokioSpawner;
+use std::future::IntoFuture;
 
 mod schema {
     cynic::use_schema!("../schemas/books.graphql");
@@ -40,7 +40,7 @@ struct BooksChangedSubscription {
 async fn main() {
     use async_tungstenite::tungstenite::{client::IntoClientRequest, http::HeaderValue};
     use futures::StreamExt;
-    use graphql_ws_client::CynicClientBuilder;
+    use graphql_ws_client::Client;
 
     let mut request = "ws://localhost:8000".into_client_request().unwrap();
     request.headers_mut().insert(
@@ -54,12 +54,8 @@ async fn main() {
 
     println!("Connected");
 
-    let (sink, stream) = connection.split();
-
-    let mut client = CynicClientBuilder::new()
-        .build(stream, sink, TokioSpawner::current())
-        .await
-        .unwrap();
+    let (mut client, actor) = Client::build(connection).await.unwrap();
+    tokio::spawn(actor.into_future());
 
     let mut stream = client.streaming_operation(build_query()).await.unwrap();
     println!("Running subscription apparently?");

examples/src/lib.rs

@@ -1,26 +1 @@
-#[cfg(not(target_arch = "wasm32"))]
-mod tokio_spawner {
-    pub struct TokioSpawner(tokio::runtime::Handle);
 
-    impl TokioSpawner {
-        pub fn new(handle: tokio::runtime::Handle) -> Self {
-            TokioSpawner(handle)
-        }
-
-        pub fn current() -> Self {
-            TokioSpawner::new(tokio::runtime::Handle::current())
-        }
-    }
-
-    impl futures::task::Spawn for TokioSpawner {
-        fn spawn_obj(
-            &self,
-            obj: futures::task::FutureObj<'static, ()>,
-        ) -> Result<(), futures::task::SpawnError> {
-            self.0.spawn(obj);
-            Ok(())
-        }
-    }
-}
-#[cfg(not(target_arch = "wasm32"))]
-pub use tokio_spawner::TokioSpawner;

src/error.rs

@@ -0,0 +1,28 @@
+#[derive(thiserror::Error, Debug)]
+/// Error type
+pub enum Error {
+    /// Unknown error
+    #[error("unknown: {0}")]
+    Unknown(String),
+    /// Custom error
+    #[error("{0}: {1}")]
+    Custom(String, String),
+    /// Unexpected close frame
+    #[error("got close frame. code: {0}, reason: {1}")]
+    Close(u16, String),
+    /// Decoding / parsing error
+    #[error("message decode error, reason: {0}")]
+    Decode(String),
+    /// Serializing error
+    #[error("couldn't serialize message, reason: {0}")]
+    Serializing(String),
+    /// Sending error
+    #[error("message sending error, reason: {0}")]
+    Send(String),
+    /// Futures spawn error
+    #[error("futures spawn error, reason: {0}")]
+    SpawnHandle(String),
+    /// Sender shutdown error
+    #[error("sender shutdown error, reason: {0}")]
+    SenderShutdown(String),
+}

src/client.rs → src/legacy/client.rs

@@ -18,55 +18,32 @@ use futures::{
 use serde::Serialize;
 use serde_json::json;
 
-use super::{
+use crate::{
     graphql::GraphqlOperation,
     logging::trace,
     protocol::{ConnectionInit, Event, Message},
     websockets::WebsocketMessage,
+    Error,
 };
 
 const SUBSCRIPTION_BUFFER_SIZE: usize = 5;
 
 /// A websocket client
+#[deprecated(since = "0.8.0-rc.1", note = "use Client instead")]
 pub struct AsyncWebsocketClient<WsMessage> {
     inner: Arc<ClientInner>,
     sender_sink: mpsc::Sender<WsMessage>,
     next_id: AtomicU64,
 }
 
-#[derive(thiserror::Error, Debug)]
-/// Error type
-pub enum Error {
-    /// Unknown error
-    #[error("unknown: {0}")]
-    Unknown(String),
-    /// Custom error
-    #[error("{0}: {1}")]
-    Custom(String, String),
-    /// Unexpected close frame
-    #[error("got close frame. code: {0}, reason: {1}")]
-    Close(u16, String),
-    /// Decoding / parsing error
-    #[error("message decode error, reason: {0}")]
-    Decode(String),
-    /// Serializing error
-    #[error("couldn't serialize message, reason: {0}")]
-    Serializing(String),
-    /// Sending error
-    #[error("message sending error, reason: {0}")]
-    Send(String),
-    /// Futures spawn error
-    #[error("futures spawn error, reason: {0}")]
-    SpawnHandle(String),
-    /// Sender shutdown error
-    #[error("sender shutdown error, reason: {0}")]
-    SenderShutdown(String),
-}
-
 #[derive(Serialize)]
 pub enum NoPayload {}
 
 /// A websocket client builder
+#[deprecated(
+    since = "0.8.0-rc.1",
+    note = "use ClientBuilder (via Client::build) instead"
+)]
 pub struct AsyncWebsocketClientBuilder<Payload = NoPayload> {
     payload: Option<Payload>,
 }

src/legacy/mod.rs

@@ -0,0 +1,6 @@
+#![allow(deprecated)]
+
+pub mod client;
+#[cfg(feature = "ws_stream_wasm")]
+pub mod wasm;
+pub mod websockets;

src/wasm.rs → src/legacy/wasm.rs

@@ -8,8 +8,6 @@ use pharos::{Observable, ObserveConfig};
 use pin_project_lite::pin_project;
 use ws_stream_wasm::{WsErr, WsEvent, WsMessage, WsMeta, WsStream};
 
-use crate::websockets::WebsocketMessage;
-
 /// Creates a new pair of sink and stream which operate on [`WasmWebsocketMessage`] instead of `WsMessage` and `WsEvent` separately.
 pub async fn wasm_websocket_combined_split(
     mut ws_meta: WsMeta,
@@ -45,7 +43,8 @@ pub enum WasmWebsocketMessage {
     WsEvent(ws_stream_wasm::WsEvent),
 }
 
-impl WebsocketMessage for WasmWebsocketMessage {
+#[allow(deprecated)]
+impl crate::legacy::websockets::WebsocketMessage for WasmWebsocketMessage {
     type Error = ws_stream_wasm::WsErr;
 
     fn new(text: String) -> Self {

src/websockets.rs → src/legacy/websockets.rs

@@ -4,6 +4,10 @@
 ///
 /// graphql-ws-client doesn't implement the websocket protocol itself.
 /// This trait provides part of the integration with websocket client libraries.
+#[deprecated(
+    since = "0.8.0-rc.1",
+    note = "WebsockeMessage is only used for the deprecated AsyncWebsocketClient.  You should update to use Client instead"
+)]
 pub trait WebsocketMessage: std::fmt::Debug {
     /// The `Error` type for this websocket client.
     type Error: std::error::Error + Send + 'static;

src/lib.rs

@@ -22,7 +22,8 @@
 
 #![warn(missing_docs)]
 
-mod client;
+mod error;
+mod legacy;
 mod logging;
 mod protocol;
 
@@ -31,16 +32,10 @@ mod protocol;
 pub mod __doc_utils;
 
 pub mod graphql;
-pub mod websockets;
 
 // TODO: next shouldn't be public really, and shouldn't allow missing_docs
 #[allow(missing_docs)]
-pub mod next;
-
-#[cfg(feature = "ws_stream_wasm")]
-mod wasm;
-#[cfg(feature = "ws_stream_wasm")]
-pub use wasm::{wasm_websocket_combined_split, FusedWasmWebsocketSink, WasmWebsocketMessage};
+mod next;
 
 #[cfg(feature = "ws_stream_wasm")]
 /// Integration with the ws_stream_wasm library
@@ -49,18 +44,53 @@ pub mod ws_stream_wasm;
 #[cfg(feature = "async-tungstenite")]
 mod native;
 
-pub use client::{AsyncWebsocketClient, AsyncWebsocketClientBuilder, Error, SubscriptionStream};
+#[allow(deprecated)]
+pub use legacy::{
+    client::{AsyncWebsocketClient, AsyncWebsocketClientBuilder, SubscriptionStream},
+    websockets,
+};
+
+#[cfg(feature = "ws_stream_wasm")]
+pub use legacy::wasm::{
+    wasm_websocket_combined_split, FusedWasmWebsocketSink, WasmWebsocketMessage,
+};
+
+pub use next::*;
+
+pub use error::Error;
 
 /// A websocket client for the cynic graphql crate
 #[cfg(feature = "cynic")]
+#[allow(deprecated)]
+#[deprecated(
+    since = "0.8.0-rc.1",
+    note = "graphql-ws-client no longer needs client specific types.  Use the general purpose Client instead"
+)]
 pub type CynicClient<WsMessage> = AsyncWebsocketClient<WsMessage>;
+
 /// A websocket client builder for the cynic graphql crate
 #[cfg(feature = "cynic")]
+#[allow(deprecated)]
+#[deprecated(
+    since = "0.8.0-rc.1",
+    note = "graphql-ws-client no longer needs client specific types.  Use the general purpose Client instead"
+)]
 pub type CynicClientBuilder = AsyncWebsocketClientBuilder;
 
 /// A websocket client for the graphql_client graphql crate
 #[cfg(feature = "client-graphql-client")]
+#[allow(deprecated)]
+#[deprecated(
+    since = "0.8.0-rc.1",
+    note = "graphql-ws-client no longer needs client specific types.  Use the general purpose Client instead"
+)]
 pub type GraphQLClientClient<WsMessage> = AsyncWebsocketClient<WsMessage>;
+
 /// A websocket client builder for the graphql_client graphql crate
 #[cfg(feature = "client-graphql-client")]
+#[allow(deprecated)]
+#[deprecated(
+    since = "0.8.0-rc.1",
+    note = "graphql-ws-client no longer needs client specific types.  Use the general purpose Client instead"
+)]
 pub type GraphQLClientClientBuilder = AsyncWebsocketClientBuilder;

src/native.rs

@@ -1,9 +1,10 @@
 use async_tungstenite::tungstenite::{self, protocol::CloseFrame};
 use futures::{AsyncRead, AsyncWrite, SinkExt, StreamExt};
 
-use crate::{websockets::WebsocketMessage, Error};
+use crate::Error;
 
-impl WebsocketMessage for tungstenite::Message {
+#[allow(deprecated)]
+impl crate::legacy::websockets::WebsocketMessage for tungstenite::Message {
     type Error = tungstenite::Error;
 
     fn new(text: String) -> Self {

src/next/builder.rs

@@ -14,7 +14,7 @@ use super::{
 /// Builder for Clients.
 ///
 /// ```rust
-///  use graphql_ws_client::next::{Client};
+///  use graphql_ws_client::Client;
 ///  use std::future::IntoFuture;
 /// #
 /// # async fn example() -> Result<(), graphql_ws_client::Error> {
@@ -33,7 +33,7 @@ impl super::Client {
     /// Creates a ClientBuilder with the given connection.
     ///
     /// ```rust
-    ///  use graphql_ws_client::next::{Client};
+    ///  use graphql_ws_client::Client;
     ///  use std::future::IntoFuture;
     /// # async fn example() -> Result<(), graphql_ws_client::Error> {
     /// # let connection = graphql_ws_client::__doc_utils::Conn;
@@ -78,7 +78,7 @@ impl ClientBuilder {
     /// Initialise a Client and use it to run a single streaming operation
     ///
     /// ```rust
-    ///  use graphql_ws_client::next::{Client};
+    ///  use graphql_ws_client::Client;
     ///  use std::future::IntoFuture;
     /// # async fn example() -> Result<(), graphql_ws_client::Error> {
     /// # let connection = graphql_ws_client::__doc_utils::Conn;