Deprecate stream and add migration docs

Author: Nemo157

Diff for: Cargo.lock

@@ -22,9 +22,6 @@ all = ["all-implementations", "all-algorithms"]
 all-implementations = ["futures-io", "stream", "tokio-02", "tokio-03", "tokio"]
 all-algorithms = ["brotli", "bzip2", "deflate", "gzip", "lzma", "xz", "zlib", "zstd"]
 
-# implementations
-stream = ["bytes-05"]
-
 # algorithms
 deflate = ["flate2"]
 gzip = ["flate2"]
@@ -34,6 +31,7 @@ zlib = ["flate2"]
 zstd = ["libzstd", "zstd-safe"]
 
 # deprecated
+stream = ["bytes-05"]
 futures-bufread = ["futures-io"]
 futures-write = ["futures-io"]
 
@@ -62,12 +60,16 @@ futures-test = "0.3.5"
 ntest = "0.3.3"
 timebomb = "0.1.2"
 bytes-05 = { package = "bytes", version = "0.5.0" }
+bytes-06 = { package = "bytes", version = "0.6.0" }
 bytes = "1.0.0"
 tokio-02 = { package = "tokio", version = "0.2.21", default-features = false, features = ["io-util", "stream", "macros", "io-std"] }
 tokio-03 = { package = "tokio", version = "0.3.0", default-features = false, features = ["io-util", "stream"] }
 tokio = { version = "1.0.0", default-features = false, features = ["io-util"] }
-tokio-util-04 = { package = "tokio-util", version = "0.4.0", default-features = false, features = ["io"] }
-tokio-util-06 = { package = "tokio-util", version = "0.6.0", default-features = false, features = ["io"] }
+tokio-util-03 = { package = "tokio-util", version = "0.3.0", default-features = false, features = ["codec"] }
+tokio-util-04 = { package = "tokio-util", version = "0.4.0", default-features = false, features = ["codec", "io"] }
+tokio-util-05 = { package = "tokio-util", version = "0.5.0", default-features = false, features = ["codec", "io"] }
+tokio-util-06 = { package = "tokio-util", version = "0.6.0", default-features = false, features = ["codec", "io"] }
+futures_codec = { version = "0.4.1", default-features = false }
 
 [[test]]
 name = "brotli"

Diff for: Cargo.toml

@@ -47,11 +47,11 @@
 )]
 #![cfg_attr(
     feature = "stream",
-    doc = "[`stream`] | [`futures::stream::Stream`](futures_core::stream::Stream)`<Item = `[`std::io::Result`]`<`[`bytes_05::Bytes`]`>>`"
+    doc = "[`stream`] | (*deprecated*, see [`async-compression:stream`](crate::stream) docs for migration)"
 )]
 #![cfg_attr(
     not(feature = "stream"),
-    doc = "`stream` (*inactive*) | `futures::stream::Stream<Item = std::io::Result<bytes::Bytes>>`"
+    doc = "`stream` (*inactive*) | (*deprecated*, see `async-compression::stream` docs for migration)"
 )]
 #![cfg_attr(
     feature = "tokio-02",

Diff for: src/lib.rs

@@ -7,6 +7,101 @@
 //! between chunks of data from the underlying stream and the resulting compressed/decompressed
 //! stream, the encoders and decoders will buffer the incoming data and choose their own boundaries
 //! at which to yield a new item.
+//!
+//! # Deprecation Migration
+//!
+//! This feature and module was deprecated because it's choosing one point in a large solution
+//! space of "stream of byte chunks" to represent an IO data stream, and the conversion between
+//! these solutions and standard IO data streams like `futures::io::AsyncBufRead` /
+//! `tokio::io::AsyncBufRead` should be zero-cost.
+//!
+//! ```rust
+//! use bytes_05::Bytes;
+//! use futures::{stream::Stream, TryStreamExt};
+//! use std::io::Result;
+//!
+//!
+//! /// For code that looks like this, choose one of the options below to replace it
+//! fn from(
+//!     input: impl Stream<Item = Result<bytes_05::Bytes>>,
+//! ) -> impl Stream<Item = Result<bytes_05::Bytes>> {
+//!     #[allow(deprecated)]
+//!     async_compression::stream::GzipEncoder::new(input)
+//! }
+//!
+//! /// Direct replacement with `tokio` v0.2 and `bytes` v0.5 using `tokio-util` v0.3
+//! fn tokio_02_bytes_05(
+//!     input: impl Stream<Item = Result<bytes_05::Bytes>>,
+//! ) -> impl Stream<Item = Result<bytes_05::Bytes>> {
+//!     tokio_util_03::codec::FramedRead::new(
+//!         async_compression::tokio_02::bufread::GzipEncoder::new(
+//!             tokio_02::io::stream_reader(input),
+//!         ),
+//!         tokio_util_03::codec::BytesCodec::new(),
+//!     ).map_ok(|bytes| bytes.freeze())
+//! }
+//!
+//! /// Upgrade replacement with `tokio` v0.3 and `bytes` v0.5 using `tokio-util` v0.4
+//! fn tokio_03_bytes_05(
+//!     input: impl Stream<Item = Result<bytes_05::Bytes>>,
+//! ) -> impl Stream<Item = Result<bytes_05::Bytes>> {
+//!     tokio_util_04::codec::FramedRead::new(
+//!         async_compression::tokio_03::bufread::GzipEncoder::new(
+//!             tokio_util_04::io::StreamReader::new(input),
+//!         ),
+//!         tokio_util_04::codec::BytesCodec::new(),
+//!     ).map_ok(|bytes| bytes.freeze())
+//! }
+//!
+//! /// Upgrade replacement with `tokio` v0.3 and `bytes` v0.6 using `tokio-util` v0.5
+//! fn tokio_03_bytes_06(
+//!     input: impl Stream<Item = Result<bytes_06::Bytes>>,
+//! ) -> impl Stream<Item = Result<bytes_06::Bytes>> {
+//!     tokio_util_05::codec::FramedRead::new(
+//!         async_compression::tokio_03::bufread::GzipEncoder::new(
+//!             tokio_util_05::io::StreamReader::new(input),
+//!         ),
+//!         tokio_util_05::codec::BytesCodec::new(),
+//!     ).map_ok(|bytes| bytes.freeze())
+//! }
+//!
+//! /// Upgrade replacement with `tokio` v1.0 and `bytes` v1.0 using `tokio-util` v0.6
+//! fn tokio_bytes(
+//!     input: impl Stream<Item = Result<bytes::Bytes>>,
+//! ) -> impl Stream<Item = Result<bytes::Bytes>> {
+//!     tokio_util_06::codec::FramedRead::new(
+//!         async_compression::tokio::bufread::GzipEncoder::new(
+//!             tokio_util_06::io::StreamReader::new(input),
+//!         ),
+//!         tokio_util_06::codec::BytesCodec::new(),
+//!     ).map_ok(|bytes| bytes.freeze())
+//! }
+//!
+//! /// What if you didn't want anything to do with `bytes`, but just a `Vec<u8>` instead?
+//! fn futures_vec(
+//!     input: impl Stream<Item = Result<Vec<u8>>> + Unpin,
+//! ) -> impl Stream<Item = Result<Vec<u8>>> {
+//!     use futures::io::AsyncReadExt;
+//!
+//!     futures::stream::try_unfold(
+//!         async_compression::futures::bufread::GzipEncoder::new(input.into_async_read()),
+//!         |mut encoder| async move {
+//!             let mut chunk = vec![0; 8 * 1024];
+//!             let len = encoder.read(&mut chunk).await?;
+//!             if len == 0 {
+//!                 Ok(None)
+//!             } else {
+//!                 chunk.truncate(len);
+//!                 Ok(Some((chunk, encoder)))
+//!             }
+//!         })
+//! }
+//! ```
+
+#![deprecated(
+    since = "0.3.8",
+    note = "See `async-compression::stream` docs for migration"
+)]
 
 #[macro_use]
 mod macros;

Diff for: src/stream/mod.rs

@@ -107,6 +107,7 @@ macro_rules! tests {
     ($variant:ident) => {
         mod $variant {
             #[cfg(feature = "stream")]
+            #[allow(deprecated)]
             mod stream {
                 use crate::utils::{algos::$variant::{stream, sync}, InputStream};
                 use proptest::{prelude::{any, ProptestConfig}, proptest};

Diff for: tests/proptest.rs

@@ -56,6 +56,7 @@ macro_rules! algos {
                 pub mod sync { $($tt)* }
 
                 #[cfg(feature = "stream")]
+                #[allow(deprecated)]
                 pub mod stream {
                     pub use async_compression::stream::{$decoder as Decoder, $encoder as Encoder};
                     pub use crate::utils::impls::stream::to_vec;

Diff for: tests/utils/algos.rs

@@ -79,6 +79,7 @@ pub mod futures {
 }
 
 #[cfg(feature = "stream")]
+#[allow(deprecated)]
 pub mod stream {
     use crate::utils::{block_on, pin_mut, Result};
     use bytes_05::Bytes;

Diff for: tests/utils/impls.rs

@@ -448,6 +448,7 @@ macro_rules! test_cases {
     ($variant:ident) => {
         mod $variant {
             #[cfg(feature = "stream")]
+            #[allow(deprecated)]
             mod stream {
                 mod compress {
                     use crate::utils::{

Diff for: tests/utils/test_cases.rs

@@ -29,7 +29,9 @@ fn stream_multiple_members_with_padding() {
 
     let input = InputStream::from(vec![compressed]);
 
+    #[allow(deprecated)]
     let mut decoder = stream::Decoder::new(input.bytes_05_stream());
+    #[allow(deprecated)]
     decoder.multiple_members(true);
     let output = stream::to_vec(decoder);
 
@@ -50,7 +52,9 @@ fn stream_multiple_members_with_invalid_padding() {
 
     let input = InputStream::from(vec![compressed]);
 
+    #[allow(deprecated)]
     let mut decoder = stream::Decoder::new(input.bytes_05_stream());
+    #[allow(deprecated)]
     decoder.multiple_members(true);
 
     assert!(block_on(decoder.next()).unwrap().is_err());