feat(transport): add HTTP retry with exponential backoff (#1520)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Co-authored-by: Cursor Agent <cursoragent@cursor.com>

Author: 3 people

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 **Features**:
 
+- Add HTTP retry with exponential backoff, opt-in via `sentry_options_set_http_retry`. ([#1520](https://github.com/getsentry/sentry-native/pull/1520))
 - Store minidump attachments as separate `.dmp` files in the offline cache for direct debugger access. ([#1607](https://github.com/getsentry/sentry-native/pull/1607))
 
 **Fixes**:

examples/example.c

@@ -676,6 +676,12 @@ 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, "http-retry")) {
+        sentry_options_set_http_retry(options, true);
+    }
+    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.
  */
@@ -2260,6 +2278,18 @@ 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.
+ *
+ * Only applicable for HTTP transports.
+ *
+ * Disabled 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/native/sentry_crash_daemon.c

@@ -3152,6 +3152,7 @@ sentry__crash_daemon_main(pid_t app_pid, uint64_t app_tid, HANDLE event_handle,
     sentry_options_set_debug(options, ipc->shmem->debug_enabled);
     options->attach_screenshot = ipc->shmem->attach_screenshot;
     options->cache_keep = ipc->shmem->cache_keep;
+    options->http_retry = false;
 
     // Set custom logger that writes to file
     if (log_file) {

src/sentry_core.c

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

src/sentry_database.c

@@ -179,14 +179,120 @@ sentry__run_write_external(
 
 bool
 sentry__run_write_cache(
-    const sentry_run_t *run, const sentry_envelope_t *envelope)
+    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;
+    }
+
+    if (retry_count < 0) {
+        return sentry__envelope_write_to_cache(envelope, run->cache_path) == 0;
+    }
+
+    sentry_uuid_t event_id = sentry__envelope_get_event_id(envelope);
+    if (sentry_uuid_is_nil(&event_id)) {
+        event_id = sentry_uuid_new_v4();
+    }
+
+    char uuid[37];
+    sentry_uuid_as_string(&event_id, uuid);
+
+    sentry_path_t *path = sentry__run_make_cache_path(
+        run, sentry__usec_time() / 1000, retry_count, uuid);
+    if (!path) {
+        return false;
+    }
+
+    int rv = sentry_envelope_write_to_path(envelope, path);
+    sentry__path_free(path);
+    if (rv) {
+        SENTRY_WARN("writing envelope to file failed");
+    }
+    return rv == 0;
+}
+
+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];
+    if (count >= 0) {
+        snprintf(filename, sizeof(filename), "%" PRIu64 "-%02d-%.36s.envelope",
+            ts, count, uuid);
+    } else {
+        snprintf(filename, sizeof(filename), "%.36s.envelope", 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;
     }
 
-    return sentry__envelope_write_to_cache(envelope, run->cache_path) == 0;
+    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;
+
+    sentry_path_t *dst_path = sentry__run_make_cache_path(
+        run, sentry__usec_time() / 1000, retry_count, cache_name);
+    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

src/sentry_database.h

@@ -72,10 +72,27 @@ 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`
+ * directory. When retry_count >= 0 the filename uses retry format
+ * `<ts>-<count>-<uuid>.envelope`, otherwise `<uuid>.envelope`.
  */
-bool sentry__run_write_cache(
-    const sentry_run_t *run, const sentry_envelope_t *envelope);
+bool sentry__run_write_cache(const sentry_run_t *run,
+    const sentry_envelope_t *envelope, int retry_count);
+
+/**
+ * Moves a file into the cache directory. When retry_count >= 0 the
+ * destination uses retry format `<ts>-<count>-<uuid>.envelope`,
+ * otherwise the original filename is preserved.
+ */
+bool sentry__run_move_cache(
+    const sentry_run_t *run, const sentry_path_t *src, int retry_count);
+
+/**
+ * Builds a cache path. When count >= 0 the result is
+ * `<db>/cache/<ts>-<count>-<uuid>.envelope`, otherwise
+ * `<db>/cache/<uuid>.envelope`.
+ */
+sentry_path_t *sentry__run_make_cache_path(
+    const sentry_run_t *run, uint64_t ts, int count, const char *uuid);
 
 /**
  * This function is essential to send crash reports from previous runs of the
@@ -92,6 +109,13 @@ bool sentry__run_write_cache(
 void sentry__process_old_runs(
     const sentry_options_t *options, uint64_t last_crash);
 
+/**
+ * Parses a retry cache filename: `<ts>-<count>-<uuid>.envelope`.
+ * Returns false for plain cache filenames (`<uuid>.envelope`).
+ */
+bool sentry__parse_cache_filename(const char *filename, uint64_t *ts_out,
+    int *count_out, const char **uuid_out);
+
 /**
  * Cleans up the cache based on options.cache_max_items,
  * options.cache_max_size and options.cache_max_age.

src/sentry_options.c

@@ -82,6 +82,7 @@ sentry_options_new(void)
     opts->crash_reporting_mode
         = SENTRY_CRASH_REPORTING_MODE_NATIVE_WITH_MINIDUMP; // Default: best of
                                                             // both worlds
+    opts->http_retry = false;
 
     return opts;
 }
@@ -876,6 +877,18 @@ sentry_options_set_handler_strategy(
 
 #endif // SENTRY_PLATFORM_LINUX
 
+void
+sentry_options_set_http_retry(sentry_options_t *opts, int enabled)
+{
+    opts->http_retry = !!enabled;
+}
+
+int
+sentry_options_get_http_retry(const sentry_options_t *opts)
+{
+    return opts->http_retry;
+}
+
 void
 sentry_options_set_propagate_traceparent(
     sentry_options_t *opts, int propagate_traceparent)

src/sentry_options.h

@@ -78,6 +78,7 @@ struct sentry_options_s {
     bool enable_metrics;
     sentry_before_send_metric_function_t before_send_metric_func;
     void *before_send_metric_data;
+    bool http_retry;
 
     /* everything from here on down are options which are stored here but
        not exposed through the options API */