revault_lockbox_api 0.0.59

reVault lockbox API to create and manage lockboxes
Documentation
//! Scratch allocation reuse limited to one synchronous content-stream operation.
use crate::page_buffer::ZeroizingBytes;
use crate::{Error, Result};
use std::cell::RefCell;
use zstd_complete::decoding::{
    errors::FrameDecoderError, DecoderWorkspaceError, StaticDecoderWorkspace,
};

const WINDOW: usize = super::MAX_DECOMPRESSED_COMPRESSION_FRAME_BYTES as usize;

thread_local! {
    static SCRATCH: RefCell<Option<ZeroizingBytes>> = const { RefCell::new(None) };
}

pub(crate) fn scoped<R>(operation: impl FnOnce() -> R) -> R {
    struct Scope(bool);
    impl Drop for Scope {
        fn drop(&mut self) {
            if self.0 {
                // The last scope wipes the full allocation, including scratch
                // history, on success, error, or unwinding through a visitor.
                let _ = SCRATCH.try_with(|scratch| {
                    scratch.borrow_mut().take();
                });
            }
        }
    }
    let owns = SCRATCH
        .try_with(|scratch| {
            let mut scratch = scratch.borrow_mut();
            if scratch.is_some() {
                false
            } else {
                *scratch = Some(ZeroizingBytes::new(Vec::new()));
                true
            }
        })
        .unwrap_or(false);
    let _scope = Scope(owns);
    operation()
}

pub(super) fn decode(stored: &[u8], expected_len: usize) -> Option<Result<Vec<u8>>> {
    // Metadata and oversized legacy pages keep the ordinary decoder. The
    // bounded allocation is lazy, so raw-only streams allocate no workspace.
    if !(64 * 1024..=WINDOW).contains(&expected_len) {
        return None;
    }
    // This is only an allocation hint: the decoder still validates the whole
    // header and enforces the bound. Non-single-segment frames can advertise a
    // window larger than their output; preserve that without always reserving
    // the maximum. Skippable prefixes retain the ordinary decoder.
    let header = stored.get(..6)?;
    if &header[..4] != super::ZSTD_MAGIC {
        return None;
    }
    let window = if header[4] & 0x20 == 0 {
        let base = 1u64 << (10 + (header[5] >> 3));
        let advertised = base + base / 8 * u64::from(header[5] & 7);
        advertised.max(expected_len as u64)
    } else {
        expected_len as u64
    };
    if window > WINDOW as u64 {
        return None;
    }
    let window = window as usize;
    // A caller can legitimately decode from another TLS destructor after this
    // slot has gone away. Scratch reuse is optional, never a reason to panic.
    SCRATCH
        .try_with(|slot| {
            let mut slot = slot.borrow_mut();
            let scratch = slot.as_mut()?;
            let result = (|| {
                let required = StaticDecoderWorkspace::required_size(window, 0)
                    .map_err(|_| Error::CorruptRecord)?;
                if scratch.len() < required {
                    // Replacing the wrapper wipes the old history before freeing
                    // it; Vec growth could otherwise leave an unwiped old buffer.
                    *scratch = ZeroizingBytes::new(vec![0; required]);
                }
                let mut decoded = ZeroizingBytes::new(vec![0; expected_len]);
                let mut decoder = StaticDecoderWorkspace::new(scratch, window, 0)
                    .map_err(|_| Error::CorruptRecord)?;
                match decoder.decode_into(stored, &mut decoded) {
                    Ok(len) => {
                        if len != expected_len {
                            return Err(Error::CorruptRecord);
                        }
                        decoded.truncate(len);
                        Ok(Some(std::mem::take(&mut *decoded)))
                    }
                    // A valid small-output frame can advertise a larger history
                    // window. Preserve the existing decoder's acceptance limits.
                    Err(DecoderWorkspaceError::Decode(FrameDecoderError::WindowSizeTooBig {
                        ..
                    })) => Ok(None),
                    Err(_) => Err(Error::CorruptRecord),
                }
            })();
            match result {
                Ok(Some(bytes)) => Some(Ok(bytes)),
                Ok(None) => None,
                Err(error) => Some(Err(error)),
            }
        })
        .ok()
        .flatten()
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn decoding_from_a_later_thread_local_destructor_falls_back() {
        use std::sync::{
            atomic::{AtomicBool, Ordering},
            Arc,
        };
        struct LateDecode {
            passed: Arc<AtomicBool>,
            encoded: Vec<u8>,
            expected: Vec<u8>,
        }
        impl Drop for LateDecode {
            fn drop(&mut self) {
                // Catch inside the destructor so a regression fails this test
                // normally instead of aborting the complete test process.
                let decoded = std::panic::catch_unwind(|| {
                    scoped(|| super::super::zstd_decode(&self.encoded, self.expected.len() as u64))
                });
                self.passed.store(
                    decoded
                        .ok()
                        .and_then(Result::ok)
                        .is_some_and(|bytes| bytes == self.expected),
                    Ordering::SeqCst,
                );
            }
        }
        thread_local! {
            static LATE: RefCell<Option<LateDecode>> = const { RefCell::new(None) };
        }
        let passed = Arc::new(AtomicBool::new(false));
        let expected = vec![23; 64 * 1024];
        let late = LateDecode {
            passed: passed.clone(),
            encoded: super::super::zstd_encode(&expected, 1),
            expected,
        };
        std::thread::spawn(move || {
            // TLS destructors run in reverse initialization order. Scratch is
            // already destroyed when the earlier LATE slot calls the decoder.
            LATE.with(|slot| *slot.borrow_mut() = Some(late));
            scoped(|| {});
        })
        .join()
        .unwrap();
        assert!(passed.load(Ordering::SeqCst));
    }

    #[test]
    fn checksum_failure_returns_no_decoded_content_and_releases_scoped_scratch() {
        let payload = vec![37; 65536];
        let mut encoded = vec![0x28, 0xb5, 0x2f, 0xfd, 0, 0x38];
        let block = ((payload.len() as u32) << 3) | 1;
        encoded.extend_from_slice(&block.to_le_bytes()[..3]);
        encoded.extend_from_slice(&payload);
        let mut frame = zstd_complete::decoding::FrameDecoder::new();
        let mut output = vec![0; payload.len()];
        frame.decode_all(&encoded, &mut output).unwrap();
        let checksum = frame.get_calculated_checksum().unwrap();
        encoded[4] |= 4;
        encoded.extend_from_slice(&checksum.to_le_bytes());
        assert_eq!(
            super::super::zstd_decode(&encoded, payload.len() as u64).unwrap(),
            payload
        );
        *encoded.last_mut().unwrap() ^= 1;
        let mut callbacks = 0;
        for reuse in [false, true] {
            let mut read = || {
                let result = super::super::zstd_decode(&encoded, payload.len() as u64);
                if result.is_ok() {
                    callbacks += 1;
                }
                assert!(result.is_err());
            };
            if reuse {
                scoped(read);
            } else {
                read();
            }
            assert!(SCRATCH.with(|slot| slot.borrow().is_none()));
        }
        assert_eq!(callbacks, 0);
    }

    #[test]
    fn declared_length_mismatch_fails_before_transferring_decoded_output() {
        let payload = vec![53; 131072];
        let encoded = super::super::zstd_encode(&payload, 1);
        for expected in [payload.len() - 1, payload.len() + 1] {
            assert!(super::super::zstd_decode(&encoded, expected as u64).is_err());
            scoped(|| {
                assert!(decode(&encoded, expected).unwrap().is_err());
                assert_eq!(decode(&encoded, payload.len()).unwrap().unwrap(), payload);
            });
            assert!(SCRATCH.with(|slot| slot.borrow().is_none()));
        }
    }

    #[test]
    fn scoped_decoder_matches_fresh_decoder_for_sizes_corruption_and_concatenation() {
        for len in [65_536, 131_073, 2 * 1024 * 1024, WINDOW] {
            let payload = (0..len)
                .map(|i| ((i * 13 + i / 251) % 251) as u8)
                .collect::<Vec<_>>();
            let encoded = super::super::zstd_encode(&payload, 1);
            let compare = |bytes: &[u8], expected: usize| {
                let fresh = super::super::zstd_decode(bytes, expected as u64);
                let reused = scoped(|| super::super::zstd_decode(bytes, expected as u64));
                match (fresh, reused) {
                    (Ok(left), Ok(right)) => assert_eq!(left, right),
                    (Err(_), Err(_)) => {}
                    other => panic!(
                        "decoder acceptance differs: {:?}",
                        (other.0.is_ok(), other.1.is_ok())
                    ),
                }
            };
            compare(&encoded, len);
            compare(&encoded, len - 1);
            compare(&encoded, len + 1);
            for offset in [0, encoded.len() / 2, encoded.len() - 1] {
                let mut corrupt = encoded.clone();
                corrupt[offset] ^= 0x80;
                compare(&corrupt, len);
                compare(&encoded[..offset], len);
            }
            if len * 2 <= WINDOW {
                let mut concatenated = encoded.clone();
                concatenated.extend_from_slice(&encoded);
                compare(&concatenated, len * 2);
            }
        }
    }

    #[test]
    fn scoped_scratch_reuses_allocation_and_cleans_up_nested_and_panicking_calls() {
        let payload = vec![42; 128 * 1024];
        let encoded = super::super::zstd_encode(&payload, 1);
        assert!(decode(&encoded, payload.len()).is_none());
        scoped(|| {
            assert_eq!(decode(&encoded, payload.len()).unwrap().unwrap(), payload);
            let allocation = SCRATCH.with(|slot| slot.borrow().as_ref().unwrap().as_ptr());
            scoped(|| {
                assert_eq!(decode(&encoded, payload.len()).unwrap().unwrap(), payload);
                assert!(decode(&encoded[..encoded.len() - 1], payload.len())
                    .unwrap()
                    .is_err());
                assert_eq!(decode(&encoded, payload.len()).unwrap().unwrap(), payload);
            });
            assert_eq!(
                SCRATCH.with(|slot| slot.borrow().as_ref().unwrap().as_ptr()),
                allocation
            );
            let previous_len = SCRATCH.with(|slot| slot.borrow().as_ref().unwrap().len());
            let larger = vec![73; WINDOW];
            let larger_encoded = super::super::zstd_encode(&larger, 1);
            assert_eq!(
                decode(&larger_encoded, larger.len()).unwrap().unwrap(),
                larger
            );
            assert!(SCRATCH.with(|slot| slot.borrow().as_ref().unwrap().len()) > previous_len);
            assert_eq!(decode(&encoded, payload.len()).unwrap().unwrap(), payload);
        });
        assert!(SCRATCH.with(|slot| slot.borrow().is_none()));
        assert!(std::panic::catch_unwind(|| scoped(|| {
            decode(&encoded, payload.len()).unwrap().unwrap();
            panic!("visitor failure");
        }))
        .is_err());
        assert!(SCRATCH.with(|slot| slot.borrow().is_none()));
    }

    #[test]
    fn oversized_history_keeps_the_original_decoder_fallback() {
        // A single raw block with a 16 MiB advertised window and no content
        // size. Output is small enough for our workspace, but history is not.
        let payload = vec![19; 64 * 1024];
        let mut encoded = vec![0x28, 0xb5, 0x2f, 0xfd, 0, 0x70];
        let header = ((payload.len() as u32) << 3) | 1;
        encoded.extend_from_slice(&header.to_le_bytes()[..3]);
        encoded.extend_from_slice(&payload);
        scoped(|| {
            assert!(decode(&encoded, payload.len()).is_none());
            assert_eq!(
                super::super::zstd_decode(&encoded, payload.len() as u64).unwrap(),
                payload
            );
        });
    }
}