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

deltachat/
tools.rs
