1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
use byteorder::{LE, WriteBytesExt};
use std::hash::Hasher;
use std::io::{self, Read, Write, Seek, SeekFrom, ErrorKind};
use std::mem;
use twox_hash::XxHash32;
use thiserror::Error;
use culpa::{throws};

use super::{MAGIC, INCOMPRESSIBLE, WINDOW_SIZE};
use super::header::{Flags, BlockDescriptor};
use crate::raw::{U32Table, compress2, EncoderTable};


/// Errors when compressing an LZ4 frame.
#[derive(Error, Debug)]
pub enum CompressionError {
    #[error("error reading from the input you gave me")]
    ReadError(io::Error),
    #[error("error writing to the output you gave me")]
    WriteError(#[from] io::Error),
    #[error("the block size you asked for is not supported")]
    InvalidBlockSize,
}
type Error = CompressionError; // do it this way for better docs
impl From<Error> for io::Error {
    fn from(e: Error) -> io::Error {
        io::Error::new(ErrorKind::Other, e)
    }
}

/// A builder-style struct that configures compression settings.
/// This is how you compress LZ4 frames.
/// (An LZ4 file usually consists of a single frame.)
///
/// Create it using `Default::default()`.
pub struct CompressionSettings<'a> {
    independent_blocks: bool,
    block_checksums: bool,
    content_checksum: bool,
    block_size: usize,
    dictionary: Option<&'a [u8]>,
    dictionary_id: Option<u32>,
}
impl<'a> Default for CompressionSettings<'a> {
    fn default() -> Self {
        Self {
            independent_blocks: true,
            block_checksums: false,
            content_checksum: true,
            block_size: 4 * 1024 * 1024,
            dictionary: None,
            dictionary_id: None,
        }
    }
}
impl<'a> CompressionSettings<'a> {
    /// In independent mode, blocks are not allowed to reference data from previous blocks.
    /// Hence, using dependent blocks yields slightly better compression.
    /// The downside of dependent blocks is that seeking becomes impossible - the entire frame always has
    /// to be decompressed from the beginning.
    ///
    /// Blocks are independent by default.
    pub fn independent_blocks(&mut self, v: bool) -> &mut Self {
        self.independent_blocks = v;
        self
    }

    /// Block checksums can help detect data corruption in storage and transit.
    /// They do not offer error correction though.
    ///
    /// In most cases, block checksums are not very helpful because you generally want a lower
    /// layer to deal with data corruption more comprehensively.
    ///
    /// Block checksums are disabled by default.
    pub fn block_checksums(&mut self, v: bool) -> &mut Self {
        self.block_checksums = v;
        self
    }

    /// The content checksum (also called frame checksum) is calculated over the contents of the entire frame.
    /// This makes them cheaper than block checksums as their size overhead is constant
    /// as well as marginally more useful, because they can help protect against incorrect decompression.
    ///
    /// Note that the content checksum can only be verified *after* the entire frame has been read
    /// (and returned!), which is the downside of content checksums.
    ///
    /// Frame checksums are enabled by default.
    pub fn content_checksum(&mut self, v: bool) -> &mut Self {
        self.content_checksum = v;
        self
    }

    /// Only valid values are 4MiB, 1MiB, 256KiB, 64KiB
    /// (TODO: better interface for this)
    ///
    /// The default block size is 4 MiB.
    pub fn block_size(&mut self, v: usize) -> &mut Self {
        self.block_size = v;
        self
    }

    /// A dictionary is essentially a constant slice of bytes shared by the compressing and decompressing party.
    /// Using a dictionary can improve compression ratios, because the compressor can reference data from the dictionary.
    ///
    /// The dictionary id is an application-specific identifier which can be used during decompression to determine
    /// which dictionary to use.
    ///
    /// Note that while the size of a dictionary can be arbitrary, dictionaries larger than 64 KiB are not useful as
    /// the LZ4 algorithm does not support backreferences by more than 64 KiB, i.e. any dictionary content before
    /// the trailing 64 KiB is silently ignored.
    ///
    /// By default, no dictionary is used and no id is specified.
    pub fn dictionary(&mut self, id: u32, dict: &'a [u8]) -> &mut Self {
        self.dictionary_id = Some(id);
        self.dictionary = Some(dict);
        self
    }

    /// The dictionary id header field is quite obviously intended to tell anyone trying to decompress your frame which dictionary to use.
    /// So it is only natural to assume that the *absence* of a dictionary id indicates that no dictionary was used.
    ///
    /// Unfortunately this assumption turns out to be incorrect. The LZ4 CLI simply never writes a dictionary id.
    /// The major downside is that you can no longer distinguish corrupted data from a missing dictionary
    /// (unless you write block checksums, which the LZ4 CLI also never does).
    ///
    /// Hence, this library is opinionated in the sense that we always want you to specify either neither or both of these things
    /// (the LZ4 CLI basically just ignores the dictionary id completely and only cares about whether you specify a dictionary parameter or not).
    ///
    /// If you think you know better (you probably don't) you may use this method to break this rule.
    pub fn dictionary_id_nonsense_override(&mut self, id: Option<u32>) -> &mut Self {
        self.dictionary_id = id;
        self
    }

    // TODO: these interfaces need to go away in favor of something that can handle individual blocks rather than always compressing full frames at once

    #[throws]
    pub fn compress<R: Read, W: Write>(&self, reader: R, writer: W) {
        self.compress_internal(reader, writer, None)?;
    }

    #[throws]
    pub fn compress_with_size_unchecked<R: Read, W: Write>(&self, reader: R, writer: W, content_size: u64) {
        self.compress_internal(reader, writer, Some(content_size))?;
    }

    #[throws]
    pub fn compress_with_size<R: Read + Seek, W: Write>(&self, mut reader: R, writer: W) {
        // maybe one day we can just use reader.stream_len() here: https://github.com/rust-lang/rust/issues/59359
        // then again, we implement this to ignore the all bytes before the cursor which stream_len() does not
        let start = reader.stream_position()?;
        let end = reader.seek(SeekFrom::End(0))?;
        reader.seek(SeekFrom::Start(start))?;

        let length = end - start;
        self.compress_internal(reader, writer, Some(length))?;
    }

    #[throws]
    fn compress_internal<R: Read, W: Write>(&self, mut reader: R, mut writer: W, content_size: Option<u64>) {
        let mut content_hasher = None;

        let mut flags = Flags::empty();
        if self.independent_blocks {
            flags |= Flags::IndependentBlocks;
        }
        if self.block_checksums {
            flags |= Flags::BlockChecksums;
        }
        if self.content_checksum {
            flags |= Flags::ContentChecksum;
            content_hasher = Some(XxHash32::with_seed(0));
        }
        if self.dictionary_id.is_some() {
            flags |= Flags::DictionaryId;
        }
        if content_size.is_some() {
            flags |= Flags::ContentSize;
        }

        let version = 1 << 6;
        let flag_byte = version | flags.bits();
        let bd_byte = BlockDescriptor::new(self.block_size).ok_or(Error::InvalidBlockSize)?.0;

        let mut header = Vec::new();
        header.write_u32::<LE>(MAGIC)?;
        header.write_u8(flag_byte)?;
        header.write_u8(bd_byte)?;
        
        if let Some(content_size) = content_size {
            header.write_u64::<LE>(content_size)?;
        }
        if let Some(id) = self.dictionary_id {
            header.write_u32::<LE>(id)?;
        }

        let mut hasher = XxHash32::with_seed(0);
        hasher.write(&header[4..]); // skip magic for header checksum
        header.write_u8((hasher.finish() >> 8) as u8)?;
        writer.write_all(&header)?;

        let mut template_table = U32Table::default();
        let mut block_initializer: &[u8] = &[];
        if let Some(dict) = self.dictionary {
            for window in dict.windows(mem::size_of::<usize>()).step_by(3) {
                // this is a perfectly safe way to find out where our window is pointing
                // we could do this manually by iterating with an index to avoid the scary-looking
                // pointer math but this is way more convenient IMO
                let offset = window.as_ptr() as usize - dict.as_ptr() as usize;
                template_table.replace(dict, offset);
            }

            block_initializer = dict;
        }

        // TODO: when doing dependent blocks or dictionaries, in_buffer's capacity is insufficient
        let mut in_buffer = Vec::with_capacity(self.block_size);
        in_buffer.extend_from_slice(block_initializer);
        let mut out_buffer = vec![0u8; self.block_size];
        let mut table = template_table.clone();
        loop {
            let window_offset = in_buffer.len();

            // We basically want read_exact semantics, except at the end.
            // Sadly read_exact specifies the buffer contents to be undefined
            // on error, so we have to use this construction instead.
            reader.by_ref().take(self.block_size as u64).read_to_end(&mut in_buffer).map_err(Error::ReadError)?;
            let read_bytes = in_buffer.len() - window_offset;
            if read_bytes == 0 {
                break;
            }
            
            if let Some(x) = content_hasher.as_mut() {
                x.write(&in_buffer[window_offset..]);
            }

            // TODO: implement u16 table for small inputs

            // 1. limit output by input size so we never have negative compression ratio
            // 2. use a wrapper that forbids partial writes, so don't write 32-bit integers
            //    as four individual bytes with four individual range checks
            let mut cursor = NoPartialWrites(&mut out_buffer[..read_bytes]);
            let write = match compress2(&in_buffer, window_offset, &mut table, &mut cursor) {
                Ok(()) => {
                    let not_written_len = cursor.0.len();
                    let written_len = read_bytes - not_written_len;
                    writer.write_u32::<LE>(written_len as u32)?;
                    &out_buffer[..written_len]
                }
                Err(e) => {
                    assert!(e.kind() == ErrorKind::ConnectionAborted);
                    // incompressible
                    writer.write_u32::<LE>((read_bytes as u32) | INCOMPRESSIBLE)?;
                    &in_buffer[window_offset..]
                }
            };

            writer.write_all(write)?;
            if flags.contains(Flags::BlockChecksums) {
                let mut block_hasher = XxHash32::with_seed(0);
                block_hasher.write(write);
                writer.write_u32::<LE>(block_hasher.finish() as u32)?;
            }

            if flags.contains(Flags::IndependentBlocks) {
                // clear table
                in_buffer.clear();
                in_buffer.extend_from_slice(block_initializer);

                table = template_table.clone();
            } else if in_buffer.len() > WINDOW_SIZE {
                let how_much_to_forget = in_buffer.len() - WINDOW_SIZE;
                table.offset(how_much_to_forget);
                in_buffer.drain(..how_much_to_forget);
            }
        }
        writer.write_u32::<LE>(0)?;

        if let Some(x) = content_hasher {
            writer.write_u32::<LE>(x.finish() as u32)?;
        }
    }
}

/// Helper struct to allow more efficient code generation when using the Write trait on byte buffers.
///
/// The underlying problem is that the Write impl on [u8] (and everything similar, e.g. Cursor<[u8]>)
/// is specified to write as many bytes as possible before returning an error.
/// This is a problem because it forces e.g. a 32-bit write to compile to four 8-bit writes with a range
/// check every time, rather than a single 32-bit write with a range check.
///
/// This wrapper aims to resolve the problem by simply not writing anything in case we fail the bounds check,
/// as we throw away the entire buffer in that case anyway.
struct NoPartialWrites<'a>(&'a mut [u8]);
impl<'a> Write for NoPartialWrites<'a> {
    #[inline]
    fn write(&mut self, data: &[u8]) -> io::Result<usize> {
        if self.0.len() < data.len() {
            // quite frankly it doesn't matter what we specify here
            return Err(ErrorKind::ConnectionAborted.into());
        }

        let amt = data.len();
        let (a, b) = mem::take(&mut self.0).split_at_mut(data.len());
        a.copy_from_slice(data);
        self.0 = b;
        Ok(amt)
    }

    #[inline]
    fn flush(&mut self) -> io::Result<()> {
        Ok(())
    }
}