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

deltachat/
tools.rs
