feat(transport): add HTTP retry with exponential backoff

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 **Features**:
 
+- Add HTTP retry with exponential backoff. ([#1520](https://github.com/getsentry/sentry-native/pull/1520))
 - Support `SENTRY_SAMPLE_RATE` and `SENTRY_TRACES_SAMPLE_RATE` environment variables. ([#1540](https://github.com/getsentry/sentry-native/pull/1540))
 
 **Fixes**:

examples/example.c

@@ -633,6 +633,9 @@ main(int argc, char **argv)
         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, "no-http-retry")) {
+        sentry_options_set_http_retry(options, false);
+    }
 
     if (has_arg(argc, argv, "enable-metrics")) {
         sentry_options_set_enable_metrics(options, true);

include/sentry.h

@@ -946,6 +946,24 @@ SENTRY_API void sentry_transport_set_shutdown_func(
     sentry_transport_t *transport,
     int (*shutdown_func)(uint64_t timeout, void *state));
 
+/**
+ * Retries sending all pending envelopes in the transport's retry queue,
+ * e.g. when coming back online. Only applicable for HTTP transports.
+ *
+ * Note: The SDK automatically retries failed envelopes on next application
+ * startup. This function allows manual triggering of pending retries at
+ * runtime. Each envelope is retried up to 6 times. If all attempts are
+ * exhausted during intermittent connectivity, events will be discarded
+ * (or moved to cache if enabled via sentry_options_set_cache_keep).
+ *
+ * Warning: This function has no rate limiting - it will immediately
+ * attempt to send all pending envelopes. Calling this repeatedly during
+ * extended network outages may exhaust retry attempts that might have
+ * succeeded with the SDK's built-in exponential backoff.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_transport_retry(
+    sentry_transport_t *transport);
+
 /**
  * Generic way to free transport.
  */
@@ -2146,6 +2164,15 @@ SENTRY_EXPERIMENTAL_API void sentry_options_set_enable_logs(
 SENTRY_EXPERIMENTAL_API int sentry_options_get_enable_logs(
     const sentry_options_t *opts);
 
+/**
+ * Enables or disables HTTP retry with exponential backoff for network failures.
+ * Enabled by default.
+ */
+SENTRY_EXPERIMENTAL_API void sentry_options_set_http_retry(
+    sentry_options_t *opts, int enabled);
+SENTRY_EXPERIMENTAL_API int sentry_options_get_http_retry(
+    const sentry_options_t *opts);
+
 /**
  * Enables or disables custom attributes parsing for structured logging.
  *

src/CMakeLists.txt

@@ -34,6 +34,8 @@ sentry_target_sources_cwd(sentry
 	sentry_process.h
 	sentry_ratelimiter.c
 	sentry_ratelimiter.h
+	sentry_retry.c
+	sentry_retry.h
 	sentry_ringbuffer.c
 	sentry_ringbuffer.h
 	sentry_sampling_context.h

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

@@ -290,7 +290,7 @@ sentry_init(sentry_options_t *options)
         backend->prune_database_func(backend);
     }
 
-    if (options->cache_keep) {
+    if (options->cache_keep || options->http_retry) {
         sentry__cleanup_cache(options);
     }
 

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,18 +115,20 @@ 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);
 }
 
 static bool
-write_envelope(const sentry_path_t *path, const sentry_envelope_t *envelope)
+write_envelope(const sentry_path_t *path, const sentry_envelope_t *envelope,
+    int retry_count)
 {
     sentry_uuid_t event_id = sentry__envelope_get_event_id(envelope);
 
@@ -111,13 +138,18 @@ write_envelope(const sentry_path_t *path, const sentry_envelope_t *envelope)
         event_id = sentry_uuid_new_v4();
     }
 
-    char *envelope_filename = sentry__uuid_as_filename(&event_id, ".envelope");
-    if (!envelope_filename) {
-        return false;
+    char uuid[37];
+    sentry_uuid_as_string(&event_id, uuid);
+
+    char filename[128];
+    if (retry_count >= 0) {
+        snprintf(filename, sizeof(filename), "%" PRIu64 "-%02d-%.36s.envelope",
+            sentry__usec_time() / 1000, retry_count, uuid);
+    } else {
+        snprintf(filename, sizeof(filename), "%.36s.envelope", uuid);
     }
 
-    sentry_path_t *output_path = sentry__path_join_str(path, envelope_filename);
-    sentry_free(envelope_filename);
+    sentry_path_t *output_path = sentry__path_join_str(path, filename);
     if (!output_path) {
         return false;
     }
@@ -136,7 +168,7 @@ bool
 sentry__run_write_envelope(
     const sentry_run_t *run, const sentry_envelope_t *envelope)
 {
-    return write_envelope(run->run_path, envelope);
+    return write_envelope(run->run_path, envelope, -1);
 }
 
 bool
@@ -148,7 +180,104 @@ sentry__run_write_external(
         return false;
     }
 
-    return write_envelope(run->external_path, envelope);
+    return write_envelope(run->external_path, envelope, -1);
+}
+
+bool
+sentry__run_write_cache(
+    const sentry_run_t *run, const sentry_envelope_t *envelope, int retry_count)
+{
+    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, retry_count);
+}
+
+bool
+sentry__parse_cache_filename(const char *filename, uint64_t *ts_out,
+    int *count_out, const char **uuid_out)
+{
+    // Minimum retry filename: <ts>-<count>-<uuid>.envelope (49+ chars).
+    // Cache filenames are exactly 45 chars (<uuid>.envelope).
+    if (strlen(filename) <= 45) {
+        return false;
+    }
+
+    char *end;
+    uint64_t ts = strtoull(filename, &end, 10);
+    if (*end != '-') {
+        return false;
+    }
+
+    const char *count_str = end + 1;
+    long count = strtol(count_str, &end, 10);
+    if (*end != '-' || count < 0) {
+        return false;
+    }
+
+    const char *uuid = end + 1;
+    size_t tail_len = strlen(uuid);
+    // 36 chars UUID (with dashes) + ".envelope"
+    if (tail_len != 36 + 9 || strcmp(uuid + 36, ".envelope") != 0) {
+        return false;
+    }
+
+    *ts_out = ts;
+    *count_out = (int)count;
+    *uuid_out = uuid;
+    return true;
+}
+
+sentry_path_t *
+sentry__run_make_cache_path(
+    const sentry_run_t *run, uint64_t ts, int count, const char *uuid)
+{
+    char filename[128];
+    snprintf(filename, sizeof(filename), "%" PRIu64 "-%02d-%.36s.envelope", ts,
+        count, uuid);
+    return sentry__path_join_str(run->cache_path, filename);
+}
+
+bool
+sentry__run_move_cache(
+    const sentry_run_t *run, const sentry_path_t *src, int retry_count)
+{
+    if (sentry__path_create_dir_all(run->cache_path) != 0) {
+        SENTRY_ERRORF("mkdir failed: \"%s\"", run->cache_path->path);
+        return false;
+    }
+
+    char filename[128];
+    const char *src_name = sentry__path_filename(src);
+    uint64_t parsed_ts;
+    int parsed_count;
+    const char *parsed_uuid;
+    const char *cache_name = sentry__parse_cache_filename(src_name, &parsed_ts,
+                                 &parsed_count, &parsed_uuid)
+        ? parsed_uuid
+        : src_name;
+    if (retry_count >= 0) {
+        snprintf(filename, sizeof(filename), "%" PRIu64 "-%02d-%.36s.envelope",
+            sentry__usec_time() / 1000, retry_count, cache_name);
+    } else {
+        snprintf(filename, sizeof(filename), "%s", cache_name);
+    }
+
+    sentry_path_t *dst_path = sentry__path_join_str(run->cache_path, filename);
+    if (!dst_path) {
+        return false;
+    }
+
+    int rv = sentry__path_rename(src, dst_path);
+    sentry__path_free(dst_path);
+    if (rv != 0) {
+        SENTRY_WARNF("failed to cache envelope \"%s\"", src_name);
+        return false;
+    }
+
+    return true;
 }
 
 bool
@@ -239,13 +368,9 @@ 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);
-            }
-        }
+        bool can_cache = options->cache_keep
+            && (!options->http_retry
+                || !sentry__transport_can_retry(options->transport));
 
         sentry_pathiter_t *run_iter = sentry__path_iter_directory(run_dir);
         const sentry_path_t *file;
@@ -292,15 +417,8 @@ sentry__process_old_runs(const sentry_options_t *options, uint64_t last_crash)
                 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);
+                if (can_cache
+                    && sentry__run_move_cache(options->run, file, -1)) {
                     continue;
                 }
             }
@@ -309,7 +427,6 @@ sentry__process_old_runs(const sentry_options_t *options, uint64_t last_crash)
         }
         sentry__pathiter_free(run_iter);
 
-        sentry__path_free(cache_dir);
         sentry__path_remove_all(run_dir);
         sentry__filelock_free(lock);
     }