Skip to main content

zrip_encode/
streaming.rs

1#![forbid(unsafe_code)]
2
3use std::io::{self, Write};
4
5use crate::frame_state::EncodeState;
6use crate::strategy::{self, LevelParams};
7use zrip_core::dict::Dictionary;
8use zrip_core::error::CompressError;
9
10#[derive(Clone, Copy)]
11enum EncoderState {
12    Ready,
13    Finished,
14    Failed,
15}
16
17/// Streaming zstd compressor implementing [`Write`].
18///
19/// Buffers input until a full block (128 KiB, or the window if smaller) is
20/// ready, then compresses and writes it to the underlying writer. Call [`finish`](Self::finish)
21/// to flush the final block, write the content checksum, and recover the
22/// writer.
23///
24/// After a write, flush, or finalization error, the encoder cannot be reused.
25/// Later writes, flushes, [`finish`](Self::finish), and [`reset`](Self::reset)
26/// return errors. Discard the encoder and its incomplete output.
27///
28/// Internal buffers (hash tables, sequence scratch, block encoder workspace)
29/// are allocated once and reused across blocks. To reuse them across
30/// multiple frames, call [`reset`](Self::reset) instead of `finish`:
31///
32/// ```
33/// use std::io::Write;
34///
35/// let mut encoder = zrip::FrameEncoder::new(Vec::new(), 1).unwrap();
36/// encoder.write_all(b"first frame").unwrap();
37/// let first = encoder.reset(Vec::new()).unwrap();   // reuses buffers
38/// encoder.write_all(b"second frame").unwrap();
39/// let second = encoder.finish().unwrap();
40/// ```
41pub struct FrameEncoder<W: Write> {
42    inner: W,
43    frame: EncodeState,
44    header_written: bool,
45    state: EncoderState,
46    block_out: Vec<u8>,
47}
48
49impl<W: Write> FrameEncoder<W> {
50    /// Creates a new streaming encoder at the given level (-7..=4; -8 runs as -7).
51    pub fn new(writer: W, level: i32) -> Result<Self, CompressError> {
52        let params = strategy::level_params(level).ok_or(CompressError::InvalidLevel(level))?;
53        Self::from_params(writer, params, None)
54    }
55
56    /// Creates a new streaming encoder with [`Options`](strategy::Options)
57    /// for large windows and/or LDM.
58    pub fn with_options(
59        writer: W,
60        level: i32,
61        opts: &strategy::Options,
62    ) -> Result<Self, CompressError> {
63        let mut params = strategy::level_params(level).ok_or(CompressError::InvalidLevel(level))?;
64        strategy::apply_options(&mut params, opts);
65        Self::from_params(writer, params, None)
66    }
67
68    /// Creates a new streaming encoder with a dictionary at the given level (-7..=4; -8 runs as -7).
69    pub fn with_dict(writer: W, level: i32, dict: Dictionary) -> Result<Self, CompressError> {
70        let params = strategy::level_params(level).ok_or(CompressError::InvalidLevel(level))?;
71        Self::from_params(writer, params, Some(dict))
72    }
73
74    #[allow(clippy::unnecessary_wraps)]
75    fn from_params(
76        writer: W,
77        params: LevelParams,
78        dict: Option<Dictionary>,
79    ) -> Result<Self, CompressError> {
80        Ok(Self {
81            inner: writer,
82            frame: EncodeState::new(params, dict),
83            header_written: false,
84            state: EncoderState::Ready,
85            block_out: Vec::new(),
86        })
87    }
88
89    /// Flushes remaining data, writes the content checksum, and returns the inner writer.
90    pub fn finish(mut self) -> Result<W, io::Error> {
91        self.finish_frame()?;
92        Ok(self.inner)
93    }
94
95    /// Finishes the current frame and installs `new_writer` for the next one.
96    ///
97    /// Returns the previous writer containing the completed frame. All
98    /// internal buffers (hash tables, workspace, block scratch) stay
99    /// allocated and are reused for the next frame.
100    pub fn reset(&mut self, new_writer: W) -> Result<W, io::Error> {
101        self.finish_frame()?;
102        let old = core::mem::replace(&mut self.inner, new_writer);
103        self.header_written = false;
104        self.state = EncoderState::Ready;
105        self.frame.reset();
106        Ok(old)
107    }
108
109    fn finish_frame(&mut self) -> io::Result<()> {
110        if matches!(self.state, EncoderState::Failed) {
111            return Err(io::Error::other("encoder cannot be reused after an error"));
112        }
113        if matches!(self.state, EncoderState::Finished) {
114            return Ok(());
115        }
116        self.state = EncoderState::Failed;
117
118        if !self.header_written {
119            self.write_header()?;
120        }
121
122        self.block_out.clear();
123        self.frame
124            .encode_block(true, &mut self.block_out)
125            .map_err(io::Error::other)?;
126        self.frame.write_checksum(&mut self.block_out);
127        self.inner.write_all(&self.block_out)?;
128        self.state = EncoderState::Finished;
129        Ok(())
130    }
131
132    fn write_header(&mut self) -> io::Result<()> {
133        self.block_out.clear();
134        self.frame
135            .write_header(&mut self.block_out)
136            .map_err(io::Error::other)?;
137        self.inner.write_all(&self.block_out)?;
138        self.header_written = true;
139        Ok(())
140    }
141
142    fn flush_block(&mut self) -> io::Result<()> {
143        self.block_out.clear();
144        self.frame
145            .encode_block(false, &mut self.block_out)
146            .map_err(io::Error::other)?;
147        self.inner.write_all(&self.block_out)
148    }
149}
150
151impl<W: Write> Write for FrameEncoder<W> {
152    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
153        if matches!(self.state, EncoderState::Failed) {
154            return Err(io::Error::other("encoder cannot be reused after an error"));
155        }
156        if matches!(self.state, EncoderState::Finished) {
157            return Err(io::Error::other("encoder already finished"));
158        }
159        // Any early return leaves the encoder failed, including partial writes.
160        self.state = EncoderState::Failed;
161
162        if !self.header_written {
163            self.write_header()?;
164        }
165
166        let block_size = self.frame.block_size();
167        let mut consumed = 0;
168        while consumed < buf.len() {
169            consumed += self.frame.take_input(&buf[consumed..]);
170            if self.frame.buffered() >= block_size {
171                self.flush_block()?;
172            }
173        }
174
175        self.state = EncoderState::Ready;
176        Ok(consumed)
177    }
178
179    fn flush(&mut self) -> io::Result<()> {
180        if matches!(self.state, EncoderState::Failed) {
181            return Err(io::Error::other("encoder cannot be reused after an error"));
182        }
183        let state = self.state;
184        self.state = EncoderState::Failed;
185        if self.frame.buffered() > 0 {
186            self.flush_block()?;
187        }
188        self.inner.flush()?;
189        self.state = state;
190        Ok(())
191    }
192}