Skip to main content

zrip_encode/
streaming.rs

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