feat: offline caching (inproc & breakpad)

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+**Features**:
+
+- Add new offline caching options to persist envelopes locally, currently supported with the `inproc` and `breakpad` backends: `sentry_options_set_cache_keep`, `sentry_options_set_cache_max_items`, `sentry_options_set_cache_max_size`, and `sentry_options_set_cache_max_age`. ([#1490](https://github.com/getsentry/sentry-native/pull/1490))
+
 ## 0.12.6
 
 **Features**:

examples/example.c

@@ -573,6 +573,12 @@ main(int argc, char **argv)
     if (has_arg(argc, argv, "log-attributes")) {
         sentry_options_set_logs_with_attributes(options, true);
     }
+    if (has_arg(argc, argv, "cache-keep")) {
+        sentry_options_set_cache_keep(options, true);
+        sentry_options_set_cache_max_size(options, 4 * 1024 * 1024); // 4 MB
+        sentry_options_set_cache_max_age(options, 5 * 24 * 60 * 60); // 5 days
+        sentry_options_set_cache_max_items(options, 5);
+    }
 
     if (has_arg(argc, argv, "enable-metrics")) {
         sentry_options_set_enable_metrics(options, true);

include/sentry.h

@@ -165,6 +165,7 @@ extern "C" {
 #include <inttypes.h>
 #include <stdarg.h>
 #include <stddef.h>
+#include <time.h>
 
 /* context type dependencies */
 #ifdef _WIN32
@@ -1415,6 +1416,53 @@ SENTRY_API void sentry_options_set_symbolize_stacktraces(
 SENTRY_API int sentry_options_get_symbolize_stacktraces(
     const sentry_options_t *opts);
 
+/**
+ * Enables or disables storing envelopes in a persistent cache.
+ *
+ * When enabled, envelopes are written to a `cache/` subdirectory within the
+ * database directory and retained regardless of send success or failure.
+ * The cache is cleared on startup based on the cache_max_items, cache_max_size,
+ * and cache_max_age options.
+ *
+ * Disabled by default.
+ */
+SENTRY_API void sentry_options_set_cache_keep(
+    sentry_options_t *opts, int enabled);
+
+/**
+ * Sets the maximum number of items in the cache directory.
+ * On startup, cached entries are removed from oldest to newest until the
+ * directory contains at most the specified number of items.
+ *
+ * Defaults to 30.
+ */
+SENTRY_API void sentry_options_set_cache_max_items(
+    sentry_options_t *opts, size_t items);
+
+/**
+ * Sets the maximum size (in bytes) for the cache directory.
+ * On startup, cached entries are removed from oldest to newest until the
+ * directory size is within the max size limit.
+ *
+ * Defaults to 0 (no max size).
+ */
+SENTRY_API void sentry_options_set_cache_max_size(
+    sentry_options_t *opts, size_t bytes);
+
+/**
+ * Sets the maximum age (in seconds) for cache entries in the cache directory.
+ * On startup, cached entries exceeding the max age limit are removed.
+ *
+ * Defaults to 0 (no max age).
+ */
+SENTRY_API void sentry_options_set_cache_max_age(
+    sentry_options_t *opts, time_t seconds);
+
+/**
+ * Gets the caching mode for crash reports.
+ */
+SENTRY_API int sentry_options_get_cache_keep(const sentry_options_t *opts);
+
 /**
  * Adds a new attachment to be sent along.
  *

src/backends/sentry_backend_crashpad.cpp

@@ -744,19 +744,70 @@ crashpad_backend_last_crash(sentry_backend_t *backend)
     return crash_time;
 }
 
+class CachePruneCondition final : public crashpad::PruneCondition {
+public:
+    CachePruneCondition(size_t max_items, size_t max_size, time_t max_age)
+        : max_items_(max_items)
+        , item_count_(0)
+        , max_size_(max_size)
+        , measured_size_(0)
+        , max_age_(max_age)
+        , oldest_report_time_(time(nullptr) - max_age)
+    {
+    }
+
+    bool
+    ShouldPruneReport(
+        const crashpad::CrashReportDatabase::Report &report) override
+    {
+        ++item_count_;
+        measured_size_ += static_cast<size_t>(report.total_size);
+
+        bool by_items = max_items_ > 0 && item_count_ > max_items_;
+        bool by_size = max_size_ > 0 && measured_size_ > max_size_;
+        bool by_age
+            = max_age_ > 0 && report.creation_time < oldest_report_time_;
+        return by_items || by_size || by_age;
+    }
+
+private:
+    const size_t max_items_;
+    size_t item_count_;
+    const size_t max_size_;
+    size_t measured_size_;
+    const time_t max_age_;
+    const time_t oldest_report_time_;
+};
+
 static void
 crashpad_backend_prune_database(sentry_backend_t *backend)
 {
     auto *data = static_cast<crashpad_state_t *>(backend->data);
 
-    // We want to eagerly clean up reports older than 2 days, and limit the
-    // complete database to a maximum of 8M. That might still be a lot for
-    // an embedded use-case, but minidumps on desktop can sometimes be quite
-    // large.
-    data->db->CleanDatabase(60 * 60 * 24 * 2);
-    crashpad::BinaryPruneCondition condition(crashpad::BinaryPruneCondition::OR,
-        new crashpad::DatabaseSizePruneCondition(1024 * 8),
-        new crashpad::AgePruneCondition(2));
+    // For backwards compatibility, default to the parameters that were used
+    // before the offline caching API was introduced. We wanted to eagerly
+    // clean up reports older than 2 days, and limit the complete database
+    // to a maximum of 8M. That might still have been a lot for an embedded
+    // use-case, but minidumps on desktop can sometimes be quite large.
+    time_t max_age = 2 * 24 * 60 * 60; // 2 days
+    size_t max_size = 8 * 1024 * 1024; // 8 MB
+    size_t max_items = 0;
+
+    // When offline caching is enabled, the user has full control over these
+    // parameters via the cache_max_* options.
+    SENTRY_WITH_OPTIONS (options) {
+        if (options->cache_keep) {
+            max_age = options->cache_max_age;
+            max_size = options->cache_max_size;
+            max_items = options->cache_max_items;
+        }
+    }
+
+    if (max_age > 0) {
+        data->db->CleanDatabase(max_age);
+    }
+
+    CachePruneCondition condition(max_items, max_size, max_age);
     crashpad::PruneCrashReportDatabase(data->db, &condition);
 }
 

src/sentry_core.c

@@ -290,6 +290,10 @@ sentry_init(sentry_options_t *options)
         backend->prune_database_func(backend);
     }
 
+    if (options->cache_keep) {
+        sentry__cleanup_cache(options);
+    }
+
     if (options->auto_session_tracking) {
         sentry_start_session();
     }

src/sentry_database.c

@@ -6,6 +6,7 @@
 #include "sentry_session.h"
 #include "sentry_uuid.h"
 #include <errno.h>
+#include <stdlib.h>
 #include <string.h>
 
 sentry_run_t *
@@ -237,6 +238,15 @@ sentry__process_old_runs(const sentry_options_t *options, uint64_t last_crash)
         if (strcmp(options->run->run_path->path, run_dir->path) == 0) {
             continue;
         }
+
+        sentry_path_t *cache_dir = NULL;
+        if (options->cache_keep) {
+            cache_dir = sentry__path_join_str(options->database_path, "cache");
+            if (cache_dir) {
+                sentry__path_create_dir_all(cache_dir);
+            }
+        }
+
         sentry_pathiter_t *run_iter = sentry__path_iter_directory(run_dir);
         const sentry_path_t *file;
         while (run_iter && (file = sentry__pathiter_next(run_iter)) != NULL) {
@@ -281,12 +291,25 @@ sentry__process_old_runs(const sentry_options_t *options, uint64_t last_crash)
             } else if (sentry__path_ends_with(file, ".envelope")) {
                 sentry_envelope_t *envelope = sentry__envelope_from_path(file);
                 sentry__capture_envelope(options->transport, envelope);
+
+                if (cache_dir) {
+                    sentry_path_t *cached_file = sentry__path_join_str(
+                        cache_dir, sentry__path_filename(file));
+                    if (!cached_file
+                        || sentry__path_rename(file, cached_file) != 0) {
+                        SENTRY_WARNF("failed to cache envelope \"%s\"",
+                            sentry__path_filename(file));
+                    }
+                    sentry__path_free(cached_file);
+                    continue;
+                }
             }
 
             sentry__path_remove(file);
         }
         sentry__pathiter_free(run_iter);
 
+        sentry__path_free(cache_dir);
         sentry__path_remove_all(run_dir);
         sentry__filelock_free(lock);
     }
@@ -295,6 +318,130 @@ sentry__process_old_runs(const sentry_options_t *options, uint64_t last_crash)
     sentry__capture_envelope(options->transport, session_envelope);
 }
 
+// Cache Pruning below is based on prune_crash_reports.cc from Crashpad
+
+/**
+ * A cache entry with its metadata for sorting and pruning decisions.
+ */
+typedef struct {
+    sentry_path_t *path;
+    time_t mtime;
+    size_t size;
+} cache_entry_t;
+
+/**
+ * Comparison function to sort cache entries by mtime, newest first.
+ */
+static int
+compare_cache_entries_newest_first(const void *a, const void *b)
+{
+    const cache_entry_t *entry_a = (const cache_entry_t *)a;
+    const cache_entry_t *entry_b = (const cache_entry_t *)b;
+    // Newest first: if b is newer, return positive (b comes before a)
+    if (entry_b->mtime > entry_a->mtime) {
+        return 1;
+    }
+    if (entry_b->mtime < entry_a->mtime) {
+        return -1;
+    }
+    return 0;
+}
+
+void
+sentry__cleanup_cache(const sentry_options_t *options)
+{
+    if (!options->database_path) {
+        return;
+    }
+
+    sentry_path_t *cache_dir
+        = sentry__path_join_str(options->database_path, "cache");
+    if (!cache_dir || !sentry__path_is_dir(cache_dir)) {
+        sentry__path_free(cache_dir);
+        return;
+    }
+
+    // First pass: collect all cache entries with their metadata
+    size_t entries_capacity = 16;
+    size_t entries_count = 0;
+    cache_entry_t *entries
+        = sentry_malloc(sizeof(cache_entry_t) * entries_capacity);
+    if (!entries) {
+        sentry__path_free(cache_dir);
+        return;
+    }
+
+    sentry_pathiter_t *iter = sentry__path_iter_directory(cache_dir);
+    const sentry_path_t *entry;
+    while (iter && (entry = sentry__pathiter_next(iter)) != NULL) {
+        if (sentry__path_is_dir(entry)) {
+            continue;
+        }
+
+        // Grow array if needed
+        if (entries_count >= entries_capacity) {
+            entries_capacity *= 2;
+            cache_entry_t *new_entries
+                = sentry_malloc(sizeof(cache_entry_t) * entries_capacity);
+            if (!new_entries) {
+                break;
+            }
+            memcpy(new_entries, entries, sizeof(cache_entry_t) * entries_count);
+            sentry_free(entries);
+            entries = new_entries;
+        }
+
+        entries[entries_count].path = sentry__path_clone(entry);
+        if (!entries[entries_count].path) {
+            break;
+        }
+        entries[entries_count].mtime = sentry__path_get_mtime(entry);
+        entries[entries_count].size = sentry__path_get_size(entry);
+        entries_count++;
+    }
+    sentry__pathiter_free(iter);
+
+    // Sort by mtime, newest first (like crashpad)
+    // This ensures we keep the newest entries when pruning by size
+    qsort(entries, entries_count, sizeof(cache_entry_t),
+        compare_cache_entries_newest_first);
+
+    // Calculate the age threshold
+    time_t now = time(NULL);
+    time_t oldest_allowed = now - options->cache_max_age;
+
+    // Prune entries: iterate newest-to-oldest, accumulating size
+    // Remove if: too old OR accumulated size exceeds limit
+    size_t accumulated_size = 0;
+    for (size_t i = 0; i < entries_count; i++) {
+        bool should_prune = false;
+
+        // Age-based pruning
+        if (options->cache_max_age > 0 && entries[i].mtime < oldest_allowed) {
+            should_prune = true;
+        } else {
+            // Size-based pruning (accumulate size as we go, like crashpad)
+            accumulated_size += entries[i].size;
+            if (options->cache_max_size > 0
+                && accumulated_size > options->cache_max_size) {
+                should_prune = true;
+            }
+            // Item count pruning
+            if (options->cache_max_items > 0 && i >= options->cache_max_items) {
+                should_prune = true;
+            }
+        }
+
+        if (should_prune) {
+            sentry__path_remove_all(entries[i].path);
+        }
+        sentry__path_free(entries[i].path);
+    }
+
+    sentry_free(entries);
+    sentry__path_free(cache_dir);
+}
+
 static const char *g_last_crash_filename = "last_crash";
 
 bool

src/sentry_database.h

@@ -78,6 +78,12 @@ bool sentry__run_clear_session(const sentry_run_t *run);
 void sentry__process_old_runs(
     const sentry_options_t *options, uint64_t last_crash);
 
+/**
+ * Cleans up the cache based on options.max_cache_size and
+ * options.max_cache_age.
+ */
+void sentry__cleanup_cache(const sentry_options_t *options);
+
 /**
  * This will write the current ISO8601 formatted timestamp into the
  * `<database>/last_crash` file.