ref(cache): cache envelopes only on failed HTTP send

Previously, cache_keep unconditionally copied envelopes to the cache
directory on restart (during process_old_runs), regardless of whether
sending succeeded or failed. Now envelopes are cached only when the
HTTP send actually fails, fixing the behavior to match the intended
"offline caching" use case.

- Add cache_path and refcount to sentry_run_t
- Extract http_send_envelope() helper to get status_code
- Cache on failed send in http_send_task when cache_keep is enabled
- Add cleanup_func on transport for async cache pruning on bgworker
- Remove unconditional caching from process_old_runs
- Update integration tests to use HTTP transport with unreachable DSN

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: jpnurmi

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+**Fixes**:
+
+- Fix `cache_keep` to only cache envelopes when HTTP send fails, instead of unconditionally on restart. ([#1585](https://github.com/getsentry/sentry-native/pull/1585))
+
 ## 0.13.3
 
 **Features**:

examples/example.c

@@ -940,6 +940,10 @@ main(int argc, char **argv)
         sentry_reinstall_backend();
     }
 
+    if (has_arg(argc, argv, "flush")) {
+        sentry_flush(10000);
+    }
+
     if (has_arg(argc, argv, "sleep")) {
         sleep_s(10);
     }

include/sentry.h

@@ -1476,12 +1476,13 @@ SENTRY_API int sentry_options_get_symbolize_stacktraces(
     const sentry_options_t *opts);
 
 /**
- * Enables or disables storing envelopes in a persistent cache.
+ * Enables or disables storing envelopes that fail to send 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.
+ * When enabled, envelopes that fail to send are written to a `cache/`
+ * subdirectory within the database directory. The cache is cleared on startup
+ * based on the cache_max_items, cache_max_size, and cache_max_age options.
+ *
+ * Only applicable for HTTP transports.
  *
  * Disabled by default.
  */

src/backends/sentry_backend_crashpad.cpp

@@ -565,11 +565,9 @@ process_completed_reports(
 
     SENTRY_DEBUGF("caching %zu completed reports", reports.size());
 
-    sentry_path_t *cache_dir
-        = sentry__path_join_str(options->database_path, "cache");
-    if (!cache_dir || sentry__path_create_dir_all(cache_dir) != 0) {
+    sentry_path_t *cache_dir = options->run->cache_path;
+    if (sentry__path_create_dir_all(cache_dir) != 0) {
         SENTRY_WARN("failed to create cache dir");
-        sentry__path_free(cache_dir);
         return;
     }
 
@@ -593,8 +591,6 @@ process_completed_reports(
         sentry__path_free(out_path);
         sentry_envelope_free(envelope);
     }
-
-    sentry__path_free(cache_dir);
 }
 
 static int

src/sentry_core.c

@@ -293,7 +293,9 @@ sentry_init(sentry_options_t *options)
     }
 
     if (options->cache_keep) {
-        sentry__cleanup_cache(options);
+        if (!sentry__transport_submit_cleanup(options->transport, options)) {
+            sentry__cleanup_cache(options);
+        }
     }
 
     if (options->auto_session_tracking) {

src/sentry_database.c

@@ -4,6 +4,9 @@
 #include "sentry_json.h"
 #include "sentry_options.h"
 #include "sentry_session.h"
+#include "sentry_sync.h"
+#include "sentry_transport.h"
+#include "sentry_utils.h"
 #include "sentry_uuid.h"
 #include <errno.h>
 #include <stdlib.h>
@@ -50,19 +53,32 @@ sentry__run_new(const sentry_path_t *database_path)
         return NULL;
     }
 
+    // `<db>/cache`
+    sentry_path_t *cache_path = sentry__path_join_str(database_path, "cache");
+    if (!cache_path) {
+        sentry__path_free(run_path);
+        sentry__path_free(lock_path);
+        sentry__path_free(session_path);
+        sentry__path_free(external_path);
+        return NULL;
+    }
+
     sentry_run_t *run = SENTRY_MAKE(sentry_run_t);
     if (!run) {
         sentry__path_free(run_path);
         sentry__path_free(session_path);
         sentry__path_free(lock_path);
         sentry__path_free(external_path);
+        sentry__path_free(cache_path);
         return NULL;
     }
 
+    run->refcount = 1;
     run->uuid = uuid;
     run->run_path = run_path;
     run->session_path = session_path;
     run->external_path = external_path;
+    run->cache_path = cache_path;
     run->lock = sentry__filelock_new(lock_path);
     if (!run->lock) {
         goto error;
@@ -80,6 +96,15 @@ sentry__run_new(const sentry_path_t *database_path)
     return NULL;
 }
 
+sentry_run_t *
+sentry__run_incref(sentry_run_t *run)
+{
+    if (run) {
+        sentry__atomic_fetch_and_add(&run->refcount, 1);
+    }
+    return run;
+}
+
 void
 sentry__run_clean(sentry_run_t *run)
 {
@@ -90,12 +115,13 @@ sentry__run_clean(sentry_run_t *run)
 void
 sentry__run_free(sentry_run_t *run)
 {
-    if (!run) {
+    if (!run || sentry__atomic_fetch_and_add(&run->refcount, -1) != 1) {
         return;
     }
     sentry__path_free(run->run_path);
     sentry__path_free(run->session_path);
     sentry__path_free(run->external_path);
+    sentry__path_free(run->cache_path);
     sentry__filelock_free(run->lock);
     sentry_free(run);
 }
@@ -151,6 +177,18 @@ sentry__run_write_external(
     return write_envelope(run->external_path, envelope);
 }
 
+bool
+sentry__run_write_cache(
+    const sentry_run_t *run, const sentry_envelope_t *envelope)
+{
+    if (sentry__path_create_dir_all(run->cache_path) != 0) {
+        SENTRY_ERRORF("mkdir failed: \"%s\"", run->cache_path->path);
+        return false;
+    }
+
+    return write_envelope(run->cache_path, envelope);
+}
+
 bool
 sentry__run_write_session(
     const sentry_run_t *run, const sentry_session_t *session)
@@ -239,14 +277,6 @@ sentry__process_old_runs(const sentry_options_t *options, uint64_t last_crash)
             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) {
@@ -291,25 +321,12 @@ 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);
     }

src/sentry_database.h

@@ -11,7 +11,9 @@ typedef struct sentry_run_s {
     sentry_path_t *run_path;
     sentry_path_t *session_path;
     sentry_path_t *external_path;
+    sentry_path_t *cache_path;
     sentry_filelock_t *lock;
+    long refcount;
 } sentry_run_t;
 
 /**
@@ -22,6 +24,11 @@ typedef struct sentry_run_s {
  */
 sentry_run_t *sentry__run_new(const sentry_path_t *database_path);
 
+/**
+ * Increment the refcount and return the run pointer.
+ */
+sentry_run_t *sentry__run_incref(sentry_run_t *run);
+
 /**
  * This will clean up all the files belonging to this run.
  */
@@ -63,6 +70,13 @@ bool sentry__run_write_session(
  */
 bool sentry__run_clear_session(const sentry_run_t *run);
 
+/**
+ * This will serialize and write the given envelope to disk into the cache
+ * directory: `<database>/cache/<event-uuid>.envelope`
+ */
+bool sentry__run_write_cache(
+    const sentry_run_t *run, const sentry_envelope_t *envelope);
+
 /**
  * This function is essential to send crash reports from previous runs of the
  * program.

src/sentry_transport.c

@@ -10,6 +10,7 @@ struct sentry_transport_s {
     int (*flush_func)(uint64_t timeout, void *state);
     void (*free_func)(void *state);
     size_t (*dump_func)(sentry_run_t *run, void *state);
+    void (*cleanup_func)(const sentry_options_t *options, void *state);
     void *state;
     bool running;
 };
@@ -92,7 +93,7 @@ sentry__transport_startup(
 int
 sentry__transport_flush(sentry_transport_t *transport, uint64_t timeout)
 {
-    if (transport->flush_func && transport->running) {
+    if (transport && transport->flush_func && transport->running) {
         SENTRY_DEBUG("flushing transport");
         return transport->flush_func(timeout, transport->state);
     }
@@ -147,3 +148,21 @@ sentry__transport_get_state(sentry_transport_t *transport)
 {
     return transport ? transport->state : NULL;
 }
+
+void
+sentry__transport_set_cleanup_func(sentry_transport_t *transport,
+    void (*cleanup_func)(const sentry_options_t *options, void *state))
+{
+    transport->cleanup_func = cleanup_func;
+}
+
+bool
+sentry__transport_submit_cleanup(
+    sentry_transport_t *transport, const sentry_options_t *options)
+{
+    if (transport && transport->cleanup_func && transport->running) {
+        transport->cleanup_func(options, transport->state);
+        return true;
+    }
+    return false;
+}

src/sentry_transport.h

@@ -57,4 +57,22 @@ size_t sentry__transport_dump_queue(
 
 void *sentry__transport_get_state(sentry_transport_t *transport);
 
+/**
+ * Sets the cleanup function of the transport.
+ *
+ * This function submits cache cleanup as a task on the transport's background
+ * worker, so it runs after any pending send tasks from process_old_runs.
+ */
+void sentry__transport_set_cleanup_func(sentry_transport_t *transport,
+    void (*cleanup_func)(const sentry_options_t *options, void *state));
+
+/**
+ * Submits cache cleanup to the transport's background worker.
+ *
+ * Returns true if cleanup was submitted, false if the transport does not
+ * support async cleanup (caller should run cleanup synchronously).
+ */
+bool sentry__transport_submit_cleanup(
+    sentry_transport_t *transport, const sentry_options_t *options);
+
 #endif