deltachat/
tools.rs

1//! Some tools and enhancements to the used libraries, there should be
2//! no references to Context and other "larger" entities here.
3
4#![allow(missing_docs)]
5
6use std::borrow::Cow;
7use std::io::{Cursor, Write};
8use std::mem;
9use std::ops::{AddAssign, Deref};
10use std::path::{Path, PathBuf};
11use std::str::from_utf8;
12// If a time value doesn't need to be sent to another host, saved to the db or otherwise used across
13// program restarts, a monotonically nondecreasing clock (`Instant`) should be used. But as
14// `Instant` may use `libc::clock_gettime(CLOCK_MONOTONIC)`, e.g. on Android, and does not advance
15// while being in deep sleep mode, we use `SystemTime` instead, but add an alias for it to document
16// why `Instant` isn't used in those places. Also this can help to switch to another clock impl if
17// we find any. Another reason is that `Instant` may reintroduce panics in the future versions:
18// https://doc.rust-lang.org/1.87.0/std/time/struct.Instant.html#method.elapsed.
19use std::time::Duration;
20pub use std::time::SystemTime as Time;
21#[cfg(not(test))]
22pub use std::time::SystemTime;
23
24use anyhow::{Context as _, Result, bail, ensure};
25use base64::Engine as _;
26use chrono::{Local, NaiveDateTime, NaiveTime, TimeZone};
27use deltachat_contact_tools::EmailAddress;
28#[cfg(test)]
29pub use deltachat_time::SystemTimeTools as SystemTime;
30use futures::TryStreamExt;
31use mailparse::MailHeaderMap;
32use mailparse::dateparse;
33use mailparse::headers::Headers;
34use num_traits::PrimInt;
35use rand::{Rng, thread_rng};
36use tokio::{fs, io};
37use url::Url;
38use uuid::Uuid;
39
40use crate::chat::{add_device_msg, add_device_msg_with_importance};
41use crate::config::Config;
42use crate::constants::{self, DC_ELLIPSIS, DC_OUTDATED_WARNING_DAYS};
43use crate::context::Context;
44use crate::events::EventType;
45use crate::log::warn;
46use crate::message::{Message, Viewtype};
47use crate::stock_str;
48
49/// Shortens a string to a specified length and adds "[...]" to the
50/// end of the shortened string.
51pub(crate) fn truncate(buf: &str, approx_chars: usize) -> Cow<'_, str> {
52    let count = buf.chars().count();
53    if count <= approx_chars + DC_ELLIPSIS.len() {
54        return Cow::Borrowed(buf);
55    }
56    let end_pos = buf
57        .char_indices()
58        .nth(approx_chars)
59        .map(|(n, _)| n)
60        .unwrap_or_default();
61
62    if let Some(index) = buf.get(..end_pos).and_then(|s| s.rfind([' ', '\n'])) {
63        Cow::Owned(format!(
64            "{}{}",
65            &buf.get(..=index).unwrap_or_default(),
66            DC_ELLIPSIS
67        ))
68    } else {
69        Cow::Owned(format!(
70            "{}{}",
71            &buf.get(..end_pos).unwrap_or_default(),
72            DC_ELLIPSIS
73        ))
74    }
75}
76
77/// Shortens a string to a specified line count and adds "[...]" to the
78/// end of the shortened string.
79///
80/// returns tuple with the String and a boolean whether is was truncated
81pub(crate) fn truncate_by_lines(
82    buf: String,
83    max_lines: usize,
84    max_line_len: usize,
85) -> (String, bool) {
86    let mut lines = 0;
87    let mut line_chars = 0;
88    let mut break_point: Option<usize> = None;
89
90    for (index, char) in buf.char_indices() {
91        if char == '\n' {
92            line_chars = 0;
93            lines += 1;
94        } else {
95            line_chars += 1;
96            if line_chars > max_line_len {
97                line_chars = 1;
98                lines += 1;
99            }
100        }
101        if lines == max_lines {
102            break_point = Some(index);
103            break;
104        }
105    }
106
107    if let Some(end_pos) = break_point {
108        // Text has too many lines and needs to be truncated.
109        let text = {
110            if let Some(buffer) = buf.get(..end_pos) {
111                if let Some(index) = buffer.rfind([' ', '\n']) {
112                    buf.get(..=index)
113                } else {
114                    buf.get(..end_pos)
115                }
116            } else {
117                None
118            }
119        };
120
121        if let Some(truncated_text) = text {
122            (format!("{truncated_text}{DC_ELLIPSIS}"), true)
123        } else {
124            // In case of indexing/slicing error, we return an error
125            // message as a preview and add HTML version. This should
126            // never happen.
127            let error_text = "[Truncation of the message failed, this is a bug in the Delta Chat core. Please report it.\nYou can still open the full text to view the original message.]";
128            (error_text.to_string(), true)
129        }
130    } else {
131        // text is unchanged
132        (buf, false)
133    }
134}
135
136/// Shortens a message text if necessary according to the configuration. Adds "[...]" to the end of
137/// the shortened text.
138///
139/// Returns the resulting text and a bool telling whether a truncation was done.
140pub(crate) async fn truncate_msg_text(context: &Context, text: String) -> Result<(String, bool)> {
141    if context.get_config_bool(Config::Bot).await? {
142        return Ok((text, false));
143    }
144    // Truncate text if it has too many lines
145    Ok(truncate_by_lines(
146        text,
147        constants::DC_DESIRED_TEXT_LINES,
148        constants::DC_DESIRED_TEXT_LINE_LEN,
149    ))
150}
151
152/* ******************************************************************************
153 * date/time tools
154 ******************************************************************************/
155
156/// Converts Unix time in seconds to a local timestamp string.
157pub fn timestamp_to_str(wanted: i64) -> String {
158    if let Some(ts) = Local.timestamp_opt(wanted, 0).single() {
159        ts.format("%Y.%m.%d %H:%M:%S").to_string()
160    } else {
161        // Out of range number of seconds.
162        "??.??.?? ??:??:??".to_string()
163    }
164}
165
166/// Converts duration to string representation suitable for logs.
167pub fn duration_to_str(duration: Duration) -> String {
168    let secs = duration.as_secs();
169    let h = secs / 3600;
170    let m = (secs % 3600) / 60;
171    let s = (secs % 3600) % 60;
172    format!("{h}h {m}m {s}s")
173}
174
175pub(crate) fn gm2local_offset() -> i64 {
176    /* returns the offset that must be _added_ to an UTC/GMT-time to create the localtime.
177    the function may return negative values. */
178    let lt = Local::now();
179    i64::from(lt.offset().local_minus_utc())
180}
181
182/// Returns the current smeared timestamp,
183///
184/// The returned timestamp MAY NOT be unique and MUST NOT go to "Date" header.
185pub(crate) fn smeared_time(context: &Context) -> i64 {
186    let now = time();
187    let ts = context.smeared_timestamp.current();
188    std::cmp::max(ts, now)
189}
190
191/// Returns a timestamp that is guaranteed to be unique.
192pub(crate) fn create_smeared_timestamp(context: &Context) -> i64 {
193    let now = time();
194    context.smeared_timestamp.create(now)
195}
196
197// creates `count` timestamps that are guaranteed to be unique.
198// the first created timestamps is returned directly,
199// get the other timestamps just by adding 1..count-1
200pub(crate) fn create_smeared_timestamps(context: &Context, count: usize) -> i64 {
201    let now = time();
202    context.smeared_timestamp.create_n(now, count as i64)
203}
204
205/// Returns the last release timestamp as a unix timestamp compatible for comparison with time() and
206/// database times.
207pub fn get_release_timestamp() -> i64 {
208    NaiveDateTime::new(
209        *crate::release::DATE,
210        NaiveTime::from_hms_opt(0, 0, 0).unwrap(),
211    )
212    .and_utc()
213    .timestamp_millis()
214        / 1_000
215}
216
217// if the system time is not plausible, once a day, add a device message.
218// for testing we're using time() as that is also used for message timestamps.
219// moreover, add a warning if the app is outdated.
220pub(crate) async fn maybe_add_time_based_warnings(context: &Context) {
221    if !maybe_warn_on_bad_time(context, time(), get_release_timestamp()).await {
222        maybe_warn_on_outdated(context, time(), get_release_timestamp()).await;
223    }
224}
225
226async fn maybe_warn_on_bad_time(context: &Context, now: i64, known_past_timestamp: i64) -> bool {
227    if now < known_past_timestamp {
228        let mut msg = Message::new(Viewtype::Text);
229        msg.text = stock_str::bad_time_msg_body(
230            context,
231            &Local.timestamp_opt(now, 0).single().map_or_else(
232                || "YY-MM-DD hh:mm:ss".to_string(),
233                |ts| ts.format("%Y-%m-%d %H:%M:%S").to_string(),
234            ),
235        )
236        .await;
237        if let Some(timestamp) = chrono::DateTime::<chrono::Utc>::from_timestamp(now, 0) {
238            add_device_msg_with_importance(
239                context,
240                Some(
241                    format!(
242                        "bad-time-warning-{}",
243                        timestamp.format("%Y-%m-%d") // repeat every day
244                    )
245                    .as_str(),
246                ),
247                Some(&mut msg),
248                true,
249            )
250            .await
251            .ok();
252        } else {
253            warn!(context, "Can't convert current timestamp");
254        }
255        return true;
256    }
257    false
258}
259
260async fn maybe_warn_on_outdated(context: &Context, now: i64, approx_compile_time: i64) {
261    if now > approx_compile_time + DC_OUTDATED_WARNING_DAYS * 24 * 60 * 60 {
262        let mut msg = Message::new_text(stock_str::update_reminder_msg_body(context).await);
263        if let Some(timestamp) = chrono::DateTime::<chrono::Utc>::from_timestamp(now, 0) {
264            add_device_msg(
265                context,
266                Some(
267                    format!(
268                        "outdated-warning-{}",
269                        timestamp.format("%Y-%m") // repeat every month
270                    )
271                    .as_str(),
272                ),
273                Some(&mut msg),
274            )
275            .await
276            .ok();
277        }
278    }
279}
280
281/// Generate an unique ID.
282///
283/// The generated ID should be short but unique:
284/// - short, because it used in Chat-Group-ID headers and in QR codes
285/// - unique as two IDs generated on two devices should not be the same
286///
287/// IDs generated by this function have 144 bits of entropy
288/// and are returned as 24 Base64 characters, each containing 6 bits of entropy.
289/// 144 is chosen because it is sufficiently secure
290/// (larger than AES-128 keys used for message encryption)
291/// and divides both by 8 (byte size) and 6 (number of bits in a single Base64 character).
292pub(crate) fn create_id() -> String {
293    // ThreadRng implements CryptoRng trait and is supposed to be cryptographically secure.
294    let mut rng = thread_rng();
295
296    // Generate 144 random bits.
297    let mut arr = [0u8; 18];
298    rng.fill(&mut arr[..]);
299
300    base64::engine::general_purpose::URL_SAFE.encode(arr)
301}
302
303/// Returns true if given string is a valid ID.
304///
305/// All IDs generated with `create_id()` should be considered valid.
306pub(crate) fn validate_id(s: &str) -> bool {
307    let alphabet = base64::alphabet::URL_SAFE.as_str();
308    s.chars().all(|c| alphabet.contains(c)) && s.len() > 10 && s.len() <= 32
309}
310
311/// Function generates a Message-ID that can be used for a new outgoing message.
312/// - this function is called for all outgoing messages.
313/// - the message ID should be globally unique
314/// - do not add a counter or any private data as this leaks information unnecessarily
315pub(crate) fn create_outgoing_rfc724_mid() -> String {
316    // We use UUID similarly to iCloud web mail client
317    // because it seems their spam filter does not like Message-IDs
318    // without hyphens.
319    //
320    // However, we use `localhost` instead of the real domain to avoid
321    // leaking the domain when resent by otherwise anonymizing
322    // From-rewriting mailing lists and forwarders.
323    let uuid = Uuid::new_v4();
324    format!("{uuid}@localhost")
325}
326
327// the returned suffix is lower-case
328pub fn get_filesuffix_lc(path_filename: &str) -> Option<String> {
329    Path::new(path_filename)
330        .extension()
331        .map(|p| p.to_string_lossy().to_lowercase())
332}
333
334/// Returns the `(width, height)` of the given image buffer.
335pub fn get_filemeta(buf: &[u8]) -> Result<(u32, u32)> {
336    let image = image::ImageReader::new(Cursor::new(buf)).with_guessed_format()?;
337    let dimensions = image.into_dimensions()?;
338    Ok(dimensions)
339}
340
341/// Expand paths relative to $BLOBDIR into absolute paths.
342///
343/// If `path` starts with "$BLOBDIR", replaces it with the blobdir path.
344/// Otherwise, returns path as is.
345pub(crate) fn get_abs_path(context: &Context, path: &Path) -> PathBuf {
346    if let Ok(p) = path.strip_prefix("$BLOBDIR") {
347        context.get_blobdir().join(p)
348    } else {
349        path.into()
350    }
351}
352
353pub(crate) async fn get_filebytes(context: &Context, path: &Path) -> Result<u64> {
354    let path_abs = get_abs_path(context, path);
355    let meta = fs::metadata(&path_abs).await?;
356    Ok(meta.len())
357}
358
359pub(crate) async fn delete_file(context: &Context, path: &Path) -> Result<()> {
360    let path_abs = get_abs_path(context, path);
361    if !path_abs.exists() {
362        bail!("path {} does not exist", path_abs.display());
363    }
364    if !path_abs.is_file() {
365        warn!(context, "refusing to delete non-file {}.", path.display());
366        bail!("not a file: \"{}\"", path.display());
367    }
368
369    let dpath = format!("{}", path.to_string_lossy());
370    fs::remove_file(path_abs)
371        .await
372        .with_context(|| format!("cannot delete {dpath:?}"))?;
373    context.emit_event(EventType::DeletedBlobFile(dpath));
374    Ok(())
375}
376
377/// Create a safe name based on a messy input string.
378///
379/// The safe name will be a valid filename on Unix and Windows and
380/// not contain any path separators.  The input can contain path
381/// segments separated by either Unix or Windows path separators,
382/// the rightmost non-empty segment will be used as name,
383/// sanitised for special characters.
384pub(crate) fn sanitize_filename(mut name: &str) -> String {
385    for part in name.rsplit('/') {
386        if !part.is_empty() {
387            name = part;
388            break;
389        }
390    }
391    for part in name.rsplit('\\') {
392        if !part.is_empty() {
393            name = part;
394            break;
395        }
396    }
397
398    let opts = sanitize_filename::Options {
399        truncate: true,
400        windows: true,
401        replacement: "",
402    };
403    let name = sanitize_filename::sanitize_with_options(name, opts);
404
405    if name.starts_with('.') || name.is_empty() {
406        format!("file{name}")
407    } else {
408        name
409    }
410}
411
412/// A guard which will remove the path when dropped.
413///
414/// It implements [`Deref`] so it can be used as a `&Path`.
415#[derive(Debug)]
416pub(crate) struct TempPathGuard {
417    path: PathBuf,
418}
419
420impl TempPathGuard {
421    pub(crate) fn new(path: PathBuf) -> Self {
422        Self { path }
423    }
424}
425
426impl Drop for TempPathGuard {
427    fn drop(&mut self) {
428        let path = self.path.clone();
429        std::fs::remove_file(path).ok();
430    }
431}
432
433impl Deref for TempPathGuard {
434    type Target = Path;
435
436    fn deref(&self) -> &Self::Target {
437        &self.path
438    }
439}
440
441impl AsRef<Path> for TempPathGuard {
442    fn as_ref(&self) -> &Path {
443        self
444    }
445}
446
447pub(crate) async fn create_folder(context: &Context, path: &Path) -> Result<(), io::Error> {
448    let path_abs = get_abs_path(context, path);
449    if !path_abs.exists() {
450        match fs::create_dir_all(path_abs).await {
451            Ok(_) => Ok(()),
452            Err(err) => {
453                warn!(
454                    context,
455                    "Cannot create directory \"{}\": {}",
456                    path.display(),
457                    err
458                );
459                Err(err)
460            }
461        }
462    } else {
463        Ok(())
464    }
465}
466
467/// Write a the given content to provided file path.
468pub(crate) async fn write_file(
469    context: &Context,
470    path: &Path,
471    buf: &[u8],
472) -> Result<(), io::Error> {
473    let path_abs = get_abs_path(context, path);
474    fs::write(&path_abs, buf).await.map_err(|err| {
475        warn!(
476            context,
477            "Cannot write {} bytes to \"{}\": {}",
478            buf.len(),
479            path.display(),
480            err
481        );
482        err
483    })
484}
485
486/// Reads the file and returns its context as a byte vector.
487pub async fn read_file(context: &Context, path: &Path) -> Result<Vec<u8>> {
488    let path_abs = get_abs_path(context, path);
489
490    match fs::read(&path_abs).await {
491        Ok(bytes) => Ok(bytes),
492        Err(err) => {
493            warn!(
494                context,
495                "Cannot read \"{}\" or file is empty: {}",
496                path.display(),
497                err
498            );
499            Err(err.into())
500        }
501    }
502}
503
504pub async fn open_file(context: &Context, path: &Path) -> Result<fs::File> {
505    let path_abs = get_abs_path(context, path);
506
507    match fs::File::open(&path_abs).await {
508        Ok(bytes) => Ok(bytes),
509        Err(err) => {
510            warn!(
511                context,
512                "Cannot read \"{}\" or file is empty: {}",
513                path.display(),
514                err
515            );
516            Err(err.into())
517        }
518    }
519}
520
521pub fn open_file_std(context: &Context, path: impl AsRef<Path>) -> Result<std::fs::File> {
522    let path_abs = get_abs_path(context, path.as_ref());
523
524    match std::fs::File::open(path_abs) {
525        Ok(bytes) => Ok(bytes),
526        Err(err) => {
527            warn!(
528                context,
529                "Cannot read \"{}\" or file is empty: {}",
530                path.as_ref().display(),
531                err
532            );
533            Err(err.into())
534        }
535    }
536}
537
538/// Reads directory and returns a vector of directory entries.
539pub async fn read_dir(path: &Path) -> Result<Vec<fs::DirEntry>> {
540    let res = tokio_stream::wrappers::ReadDirStream::new(fs::read_dir(path).await?)
541        .try_collect()
542        .await?;
543    Ok(res)
544}
545
546pub(crate) fn time() -> i64 {
547    SystemTime::now()
548        .duration_since(SystemTime::UNIX_EPOCH)
549        .unwrap_or_default()
550        .as_secs() as i64
551}
552
553pub(crate) fn time_elapsed(time: &Time) -> Duration {
554    time.elapsed().unwrap_or_default()
555}
556
557/// Struct containing all mailto information
558#[derive(Debug, Default, Eq, PartialEq)]
559pub struct MailTo {
560    pub to: Vec<EmailAddress>,
561    pub subject: Option<String>,
562    pub body: Option<String>,
563}
564
565/// Parse mailto urls
566pub fn parse_mailto(mailto_url: &str) -> Option<MailTo> {
567    if let Ok(url) = Url::parse(mailto_url) {
568        if url.scheme() == "mailto" {
569            let mut mailto: MailTo = Default::default();
570            // Extract the email address
571            url.path().split(',').for_each(|email| {
572                if let Ok(email) = EmailAddress::new(email) {
573                    mailto.to.push(email);
574                }
575            });
576
577            // Extract query parameters
578            for (key, value) in url.query_pairs() {
579                if key == "subject" {
580                    mailto.subject = Some(value.to_string());
581                } else if key == "body" {
582                    mailto.body = Some(value.to_string());
583                }
584            }
585            Some(mailto)
586        } else {
587            None
588        }
589    } else {
590        None
591    }
592}
593
594pub(crate) trait IsNoneOrEmpty<T> {
595    /// Returns true if an Option does not contain a string
596    /// or contains an empty string.
597    fn is_none_or_empty(&self) -> bool;
598}
599impl<T> IsNoneOrEmpty<T> for Option<T>
600where
601    T: AsRef<str>,
602{
603    fn is_none_or_empty(&self) -> bool {
604        !matches!(self, Some(s) if !s.as_ref().is_empty())
605    }
606}
607
608pub(crate) trait ToOption<T> {
609    fn to_option(self) -> Option<T>;
610}
611impl<'a> ToOption<&'a str> for &'a String {
612    fn to_option(self) -> Option<&'a str> {
613        if self.is_empty() { None } else { Some(self) }
614    }
615}
616impl ToOption<String> for u16 {
617    fn to_option(self) -> Option<String> {
618        if self == 0 {
619            None
620        } else {
621            Some(self.to_string())
622        }
623    }
624}
625impl ToOption<String> for Option<i32> {
626    fn to_option(self) -> Option<String> {
627        match self {
628            None | Some(0) => None,
629            Some(v) => Some(v.to_string()),
630        }
631    }
632}
633
634pub fn remove_subject_prefix(last_subject: &str) -> String {
635    let subject_start = if last_subject.starts_with("Chat:") {
636        0
637    } else {
638        // "Antw:" is the longest abbreviation in
639        // <https://en.wikipedia.org/wiki/List_of_email_subject_abbreviations#Abbreviations_in_other_languages>,
640        // so look at the first _5_ characters:
641        match last_subject.chars().take(5).position(|c| c == ':') {
642            Some(prefix_end) => prefix_end + 1,
643            None => 0,
644        }
645    };
646    last_subject
647        .chars()
648        .skip(subject_start)
649        .collect::<String>()
650        .trim()
651        .to_string()
652}
653
654// Types and methods to create hop-info for message-info
655
656fn extract_address_from_receive_header<'a>(header: &'a str, start: &str) -> Option<&'a str> {
657    let header_len = header.len();
658    header.find(start).and_then(|mut begin| {
659        begin += start.len();
660        let end = header
661            .get(begin..)?
662            .find(|c: char| c.is_whitespace())
663            .unwrap_or(header_len);
664        header.get(begin..begin + end)
665    })
666}
667
668pub(crate) fn parse_receive_header(header: &str) -> String {
669    let header = header.replace(&['\r', '\n'][..], "");
670    let mut hop_info = String::from("Hop: ");
671
672    if let Some(from) = extract_address_from_receive_header(&header, "from ") {
673        hop_info += &format!("From: {}; ", from.trim());
674    }
675
676    if let Some(by) = extract_address_from_receive_header(&header, "by ") {
677        hop_info += &format!("By: {}; ", by.trim());
678    }
679
680    if let Ok(date) = dateparse(&header) {
681        // In tests, use the UTC timezone so that the test is reproducible
682        #[cfg(test)]
683        let date_obj = chrono::Utc.timestamp_opt(date, 0).single();
684        #[cfg(not(test))]
685        let date_obj = Local.timestamp_opt(date, 0).single();
686
687        hop_info += &format!(
688            "Date: {}",
689            date_obj.map_or_else(|| "?".to_string(), |x| x.to_rfc2822())
690        );
691    };
692
693    hop_info
694}
695
696/// parses "receive"-headers
697pub(crate) fn parse_receive_headers(headers: &Headers) -> String {
698    headers
699        .get_all_headers("Received")
700        .iter()
701        .rev()
702        .filter_map(|header_map_item| from_utf8(header_map_item.get_value_raw()).ok())
703        .map(parse_receive_header)
704        .collect::<Vec<_>>()
705        .join("\n")
706}
707
708/// If `collection` contains exactly one element, return this element.
709/// Otherwise, return None.
710pub(crate) fn single_value<T>(collection: impl IntoIterator<Item = T>) -> Option<T> {
711    let mut iter = collection.into_iter();
712    if let Some(value) = iter.next() {
713        if iter.next().is_none() {
714            return Some(value);
715        }
716    }
717    None
718}
719
720/// Compressor/decompressor buffer size.
721const BROTLI_BUFSZ: usize = 4096;
722
723/// Compresses `buf` to `Vec` using `brotli`.
724/// Note that it handles an empty `buf` as a special value that remains empty after compression,
725/// otherwise brotli would add its metadata to it which is not nice because this function is used
726/// for compression of strings stored in the db and empty strings are common there. This approach is
727/// not strictly correct because nowhere in the brotli documentation is said that an empty buffer
728/// can't be a result of compression of some input, but i think this will never break.
729pub(crate) fn buf_compress(buf: &[u8]) -> Result<Vec<u8>> {
730    if buf.is_empty() {
731        return Ok(Vec::new());
732    }
733    // level 4 is 2x faster than level 6 (and 54x faster than 10, for comparison).
734    // with the adaptiveness, we aim to not slow down processing
735    // single large files too much, esp. on low-budget devices.
736    // in tests (see #4129), this makes a difference, without compressing much worse.
737    let q: u32 = if buf.len() > 1_000_000 { 4 } else { 6 };
738    let lgwin: u32 = 22; // log2(LZ77 window size), it's the default for brotli CLI tool.
739    let mut compressor = brotli::CompressorWriter::new(Vec::new(), BROTLI_BUFSZ, q, lgwin);
740    compressor.write_all(buf)?;
741    Ok(compressor.into_inner())
742}
743
744/// Decompresses `buf` to `Vec` using `brotli`.
745/// See `buf_compress()` for why we don't pass an empty buffer to brotli decompressor.
746pub(crate) fn buf_decompress(buf: &[u8]) -> Result<Vec<u8>> {
747    if buf.is_empty() {
748        return Ok(Vec::new());
749    }
750    let mut decompressor = brotli::DecompressorWriter::new(Vec::new(), BROTLI_BUFSZ);
751    decompressor.write_all(buf)?;
752    decompressor.flush()?;
753    Ok(mem::take(decompressor.get_mut()))
754}
755
756/// Increments `*t` and checks that it equals to `expected` after that.
757pub(crate) fn inc_and_check<T: PrimInt + AddAssign + std::fmt::Debug>(
758    t: &mut T,
759    expected: T,
760) -> Result<()> {
761    *t += T::one();
762    ensure!(*t == expected, "Incremented value != {expected:?}");
763    Ok(())
764}
765
766/// Returns early with an error if a condition is not satisfied.
767/// In non-optimized builds, panics instead if so.
768#[macro_export]
769macro_rules! ensure_and_debug_assert {
770    ($cond:expr, $($arg:tt)*) => {
771        let cond_val = $cond;
772        debug_assert!(cond_val, $($arg)*);
773        anyhow::ensure!(cond_val, $($arg)*);
774    };
775}
776
777/// Returns early with an error on two expressions inequality.
778/// In non-optimized builds, panics instead if so.
779#[macro_export]
780macro_rules! ensure_and_debug_assert_eq {
781    ($left:expr, $right:expr, $($arg:tt)*) => {
782        match (&$left, &$right) {
783            (left_val, right_val) => {
784                debug_assert_eq!(left_val, right_val, $($arg)*);
785                anyhow::ensure!(left_val == right_val, $($arg)*);
786            }
787        }
788    };
789}
790
791/// Returns early with an error on two expressions equality.
792/// In non-optimized builds, panics instead if so.
793#[macro_export]
794macro_rules! ensure_and_debug_assert_ne {
795    ($left:expr, $right:expr, $($arg:tt)*) => {
796        match (&$left, &$right) {
797            (left_val, right_val) => {
798                debug_assert_ne!(left_val, right_val, $($arg)*);
799                anyhow::ensure!(left_val != right_val, $($arg)*);
800            }
801        }
802    };
803}
804
805/// Logs a warning if a condition is not satisfied.
806/// In non-optimized builds, panics also if so.
807#[macro_export]
808macro_rules! logged_debug_assert {
809    ($ctx:expr, $cond:expr, $($arg:tt)*) => {
810        let cond_val = $cond;
811        if !cond_val {
812            warn!($ctx, $($arg)*);
813        }
814        debug_assert!(cond_val, $($arg)*);
815    };
816}
817
818#[cfg(test)]
819mod tools_tests;