Skip to content

Commit b30712b

Browse files
dancixxdancixx
committed
chore: simplify docs
1 parent 77dc9fa commit b30712b

4 files changed

Lines changed: 0 additions & 586 deletions

File tree

‎src/plugins/compression/brotli_stream.rs‎

Lines changed: 0 additions & 133 deletions
Original file line numberDiff line numberDiff line change
@@ -39,38 +39,6 @@ use pin_project_lite::pin_project;
3939
use crate::{body::TakoBody, types::BoxError};
4040

4141
/// Compresses an HTTP body stream using Brotli compression algorithm.
42-
///
43-
/// This function converts any HTTP body into a Brotli-compressed streaming body using
44-
/// the specified compression level. The compression is performed on-the-fly as data
45-
/// flows through the stream, making it memory-efficient for large responses.
46-
///
47-
/// # Arguments
48-
///
49-
/// * `body` - HTTP body to compress, must implement `Body<Data = Bytes, Error = BoxError>`
50-
/// * `lvl` - Brotli compression level (1-11, where 11 provides maximum compression)
51-
///
52-
/// # Compression Levels
53-
///
54-
/// - **1-3**: Fast compression, lower compression ratio
55-
/// - **4-6**: Balanced compression and speed (recommended for most use cases)
56-
/// - **7-9**: High compression, slower processing
57-
/// - **10-11**: Maximum compression, slowest processing (best for static content)
58-
///
59-
/// # Examples
60-
///
61-
/// ```rust
62-
/// use tako::plugins::compression::brotli_stream::stream_brotli;
63-
/// use http_body_util::Full;
64-
/// use bytes::Bytes;
65-
///
66-
/// // Fast compression for dynamic content
67-
/// let body = Full::from(Bytes::from("Dynamic API response data"));
68-
/// let fast_compressed = stream_brotli(body, 4);
69-
///
70-
/// // Maximum compression for static assets
71-
/// let static_body = Full::from(Bytes::from("Large static file content..."));
72-
/// let max_compressed = stream_brotli(static_body, 11);
73-
/// ```
7442
pub fn stream_brotli<B>(body: B, lvl: u32) -> TakoBody
7543
where
7644
B: Body<Data = Bytes, Error = BoxError> + Send + 'static,
@@ -82,76 +50,16 @@ where
8250

8351
pin_project! {
8452
/// Streaming Brotli compressor that wraps an inner data stream.
85-
///
86-
/// `BrotliStream` provides on-the-fly Brotli compression for streaming data sources.
87-
/// It maintains an internal encoder state and buffer to efficiently compress data
88-
/// as it flows through the stream. The implementation handles backpressure and
89-
/// ensures all compressed data is properly flushed when the stream ends.
90-
///
91-
/// # Type Parameters
92-
///
93-
/// * `S` - Inner stream type that yields `Result<Bytes, BoxError>` items
94-
///
95-
/// # Examples
96-
///
97-
/// ```rust
98-
/// use tako::plugins::compression::brotli_stream::BrotliStream;
99-
/// use futures_util::stream;
100-
/// use bytes::Bytes;
101-
///
102-
/// # async fn example() {
103-
/// // Create a stream of data chunks
104-
/// let data_stream = stream::iter(vec![
105-
/// Ok(Bytes::from("First chunk of data")),
106-
/// Ok(Bytes::from("Second chunk of data")),
107-
/// Ok(Bytes::from("Final chunk of data")),
108-
/// ]);
109-
///
110-
/// // Wrap with Brotli compression
111-
/// let compressed_stream = BrotliStream::new(data_stream, 6);
112-
/// # }
113-
/// ```
11453
pub struct BrotliStream<S> {
115-
/// Inner stream providing source data for compression.
11654
#[pin] inner: S,
117-
/// Brotli encoder with internal buffer for compressed output.
11855
encoder: brotli::CompressorWriter<Vec<u8>>,
119-
/// Current position in the encoder's output buffer.
12056
pos: usize,
121-
/// Flag indicating whether the input stream has ended.
12257
done: bool,
12358
}
12459
}
12560

12661
impl<S> BrotliStream<S> {
12762
/// Creates a new Brotli compression stream with the specified compression level.
128-
///
129-
/// The encoder is initialized with a 4KB buffer size and standard Brotli parameters
130-
/// optimized for streaming web content. The compression level controls the
131-
/// trade-off between compression ratio and processing speed.
132-
///
133-
/// # Arguments
134-
///
135-
/// * `stream` - Source stream to compress
136-
/// * `level` - Brotli compression level (1-11, clamped to valid range)
137-
///
138-
/// # Examples
139-
///
140-
/// ```rust
141-
/// use tako::plugins::compression::brotli_stream::BrotliStream;
142-
/// use futures_util::stream;
143-
/// use bytes::Bytes;
144-
///
145-
/// # fn example() {
146-
/// let source = stream::iter(vec![Ok(Bytes::from("test data"))]);
147-
///
148-
/// // Fast compression for real-time data
149-
/// let fast_stream = BrotliStream::new(source.clone(), 1);
150-
///
151-
/// // High compression for static content
152-
/// let high_stream = BrotliStream::new(source, 9);
153-
/// # }
154-
/// ```
15563
fn new(stream: S, level: u32) -> Self {
15664
Self {
15765
inner: stream,
@@ -169,47 +77,6 @@ where
16977
type Item = Result<Bytes, BoxError>;
17078

17179
/// Polls the stream for the next compressed data chunk.
172-
///
173-
/// This method implements the core streaming compression logic:
174-
/// 1. Returns any buffered compressed data first
175-
/// 2. Polls the inner stream for new input data
176-
/// 3. Compresses new input and buffers the output
177-
/// 4. Finalizes compression when input stream ends
178-
/// 5. Handles errors and backpressure appropriately
179-
///
180-
/// The implementation ensures efficient memory usage by immediately returning
181-
/// compressed data as it becomes available, rather than accumulating large
182-
/// buffers.
183-
///
184-
/// # Examples
185-
///
186-
/// ```rust,no_run
187-
/// use tako::plugins::compression::brotli_stream::BrotliStream;
188-
/// use futures_util::{stream, StreamExt};
189-
/// use bytes::Bytes;
190-
///
191-
/// # async fn example() {
192-
/// let data = stream::iter(vec![
193-
/// Ok(Bytes::from("chunk1")),
194-
/// Ok(Bytes::from("chunk2")),
195-
/// ]);
196-
///
197-
/// let mut compressed = BrotliStream::new(data, 6);
198-
///
199-
/// // Poll for compressed chunks
200-
/// while let Some(result) = compressed.next().await {
201-
/// match result {
202-
/// Ok(compressed_chunk) => {
203-
/// println!("Compressed {} bytes", compressed_chunk.len());
204-
/// }
205-
/// Err(e) => {
206-
/// eprintln!("Compression error: {}", e);
207-
/// break;
208-
/// }
209-
/// }
210-
/// }
211-
/// # }
212-
/// ```
21380
fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
21481
let mut this = self.project();
21582

‎src/plugins/compression/deflate_stream.rs‎

Lines changed: 0 additions & 143 deletions
Original file line numberDiff line numberDiff line change
@@ -39,43 +39,6 @@ use pin_project_lite::pin_project;
3939
use crate::{body::TakoBody, types::BoxError};
4040

4141
/// Compresses an HTTP body stream using the DEFLATE compression algorithm.
42-
///
43-
/// This function converts any HTTP body into a DEFLATE-compressed streaming body using
44-
/// the specified compression level. The compression is performed incrementally as data
45-
/// flows through the stream, providing memory-efficient compression for responses of
46-
/// any size.
47-
///
48-
/// # Arguments
49-
///
50-
/// * `body` - HTTP body to compress, must implement `Body<Data = Bytes, Error = BoxError>`
51-
/// * `level` - DEFLATE compression level (0-9, where 9 provides maximum compression)
52-
///
53-
/// # Compression Levels
54-
///
55-
/// - **0**: No compression (store only)
56-
/// - **1-3**: Fast compression, lower compression ratio
57-
/// - **4-6**: Balanced compression and speed (recommended for most use cases)
58-
/// - **7-9**: High compression, slower processing (best for static content)
59-
///
60-
/// # Examples
61-
///
62-
/// ```rust
63-
/// use tako::plugins::compression::deflate_stream::stream_deflate;
64-
/// use http_body_util::Full;
65-
/// use bytes::Bytes;
66-
///
67-
/// // Balanced compression for general web content
68-
/// let body = Full::from(Bytes::from("JSON API response data"));
69-
/// let compressed = stream_deflate(body, 6);
70-
///
71-
/// // Fast compression for real-time data
72-
/// let realtime_body = Full::from(Bytes::from("Live data stream"));
73-
/// let fast_compressed = stream_deflate(realtime_body, 1);
74-
///
75-
/// // Maximum compression for static assets
76-
/// let static_body = Full::from(Bytes::from("Large static file content..."));
77-
/// let max_compressed = stream_deflate(static_body, 9);
78-
/// ```
7942
pub fn stream_deflate<B>(body: B, level: u32) -> TakoBody
8043
where
8144
B: Body<Data = Bytes, Error = BoxError> + Send + 'static,
@@ -87,75 +50,16 @@ where
8750

8851
pin_project! {
8952
/// Streaming DEFLATE compressor that wraps an inner data stream.
90-
///
91-
/// `DeflateStream` provides on-the-fly DEFLATE compression for streaming data sources.
92-
/// It maintains an internal encoder state and buffer to efficiently compress data
93-
/// as it flows through the stream. The implementation handles proper stream
94-
/// finalization and ensures all compressed data is flushed when the input ends.
95-
///
96-
/// # Examples
97-
///
98-
/// ```rust
99-
/// use tako::plugins::compression::deflate_stream::DeflateStream;
100-
/// use futures_util::stream;
101-
/// use bytes::Bytes;
102-
///
103-
/// # fn example() {
104-
/// // Create a stream of data chunks
105-
/// let data_stream = stream::iter(vec![
106-
/// Ok(Bytes::from("First data chunk")),
107-
/// Ok(Bytes::from("Second data chunk")),
108-
/// Ok(Bytes::from("Final data chunk")),
109-
/// ]);
110-
///
111-
/// // Wrap with DEFLATE compression at level 6
112-
/// let compressed_stream = DeflateStream::new(data_stream, 6);
113-
/// # }
114-
/// ```
11553
pub struct DeflateStream<S> {
116-
/// Inner stream providing source data for compression.
11754
#[pin] inner: S,
118-
/// DEFLATE encoder with internal buffer for compressed output.
11955
encoder: DeflateEncoder<Vec<u8>>,
120-
/// Current position in the encoder's output buffer.
12156
pos: usize,
122-
/// Flag indicating whether the input stream has ended.
12357
done: bool,
12458
}
12559
}
12660

12761
impl<S> DeflateStream<S> {
12862
/// Creates a new DEFLATE compression stream with the specified compression level.
129-
///
130-
/// The encoder is initialized with the specified compression level, which controls
131-
/// the trade-off between compression ratio and processing speed. Higher levels
132-
/// provide better compression at the cost of increased CPU usage.
133-
///
134-
/// # Arguments
135-
///
136-
/// * `inner` - Source stream to compress
137-
/// * `level` - DEFLATE compression level (0-9, clamped to valid range)
138-
///
139-
/// # Examples
140-
///
141-
/// ```rust
142-
/// use tako::plugins::compression::deflate_stream::DeflateStream;
143-
/// use futures_util::stream;
144-
/// use bytes::Bytes;
145-
///
146-
/// # fn example() {
147-
/// let source = stream::iter(vec![Ok(Bytes::from("test data"))]);
148-
///
149-
/// // Fast compression for dynamic content
150-
/// let fast_stream = DeflateStream::new(source.clone(), 1);
151-
///
152-
/// // Balanced compression for general use
153-
/// let balanced_stream = DeflateStream::new(source.clone(), 6);
154-
///
155-
/// // Maximum compression for static content
156-
/// let max_stream = DeflateStream::new(source, 9);
157-
/// # }
158-
/// ```
15963
pub fn new(inner: S, level: u32) -> Self {
16064
Self {
16165
inner,
@@ -173,53 +77,6 @@ where
17377
type Item = Result<Bytes, BoxError>;
17478

17579
/// Polls the stream for the next compressed data chunk.
176-
///
177-
/// This method implements the core streaming compression logic with the following steps:
178-
/// 1. Returns any buffered compressed data immediately if available
179-
/// 2. Polls the inner stream for new input data when buffer is empty
180-
/// 3. Compresses new input data and flushes it to the buffer
181-
/// 4. Finalizes compression when the input stream ends
182-
/// 5. Handles errors and backpressure appropriately
183-
///
184-
/// The implementation prioritizes memory efficiency by returning compressed data
185-
/// as soon as it's available rather than accumulating large buffers.
186-
///
187-
/// # Returns
188-
///
189-
/// - `Poll::Ready(Some(Ok(Bytes)))` - A compressed chunk of data
190-
/// - `Poll::Ready(Some(Err(BoxError)))` - An error occurred during compression
191-
/// - `Poll::Ready(None)` - The stream has finished and all data has been compressed
192-
/// - `Poll::Pending` - The stream is not ready and should be polled again later
193-
///
194-
/// # Examples
195-
///
196-
/// ```rust,no_run
197-
/// use tako::plugins::compression::deflate_stream::DeflateStream;
198-
/// use futures_util::{stream, StreamExt};
199-
/// use bytes::Bytes;
200-
///
201-
/// # async fn example() {
202-
/// let data = stream::iter(vec![
203-
/// Ok(Bytes::from("chunk1")),
204-
/// Ok(Bytes::from("chunk2")),
205-
/// ]);
206-
///
207-
/// let mut compressed = DeflateStream::new(data, 6);
208-
///
209-
/// // Process compressed chunks as they become available
210-
/// while let Some(result) = compressed.next().await {
211-
/// match result {
212-
/// Ok(compressed_chunk) => {
213-
/// println!("Compressed {} bytes", compressed_chunk.len());
214-
/// }
215-
/// Err(e) => {
216-
/// eprintln!("Compression error: {}", e);
217-
/// break;
218-
/// }
219-
/// }
220-
/// }
221-
/// # }
222-
/// ```
22380
fn poll_next(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Option<Self::Item>> {
22481
let mut this = self.project();
22582

0 commit comments

Comments
 (0)