refactor(tus): cache external attachments by type, choose upload method at transport time

Replace sentry__is_large_attachment(path, size) with
sentry__attachment_is_external(att) which returns true for MINIDUMP type
or size >= SENTRY_LARGE_ATTACHMENT_SIZE. Minidumps are always cached as
external files; other large attachments continue to be cached by size.

Rename sentry__cache_large_attachments to sentry__cache_external_attachments.

At transport time, resolve_and_send_external_attachments checks each
cached attachment: large files with TUS support go via TUS upload,
smaller files are inlined into the envelope. For raw envelopes (read
from disk on restart), sentry__envelope_append_raw_attachment builds
the item bytes and appends them directly to the raw payload buffer.

External attachment cleanup is deferred until after successful send
so files survive for retry on network failure.

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

Author: jpnurmi

src/backends/sentry_backend_breakpad.cpp

@@ -186,7 +186,7 @@ breakpad_backend_callback(const google_breakpad::MinidumpDescriptor &descriptor,
                 tmp.path = dump_path;
                 tmp.type = MINIDUMP;
                 tmp.next = nullptr;
-                sentry__cache_large_attachments(
+                sentry__cache_external_attachments(
                     options->run->cache_path, &event_id, &tmp, nullptr);
             }
 

src/backends/sentry_backend_crashpad.cpp

@@ -531,7 +531,7 @@ report_to_envelope(const crashpad::CrashReportDatabase::Report &report,
             sentry__envelope_add_attachments(envelope, attachments);
             sentry_uuid_t event_id = sentry__envelope_get_event_id(envelope);
             if (options->run) {
-                sentry__cache_large_attachments(options->run->cache_path,
+                sentry__cache_external_attachments(options->run->cache_path,
                     &event_id, attachments, options->run->run_path);
             }
         } else {

src/sentry_attachment.h

@@ -7,15 +7,6 @@
 
 #define SENTRY_LARGE_ATTACHMENT_SIZE (100 * 1024 * 1024) // 100 MB
 
-static inline bool
-sentry__is_large_attachment(const sentry_path_t *path, size_t file_size)
-{
-    // TODO: for temporarily testing with <1 MB minidumps
-    // return file_size < 1024 * 1024 && sentry__path_ends_with(path, ".dmp");
-    (void)path;
-    return file_size >= SENTRY_LARGE_ATTACHMENT_SIZE;
-}
-
 /**
  * The attachment_type.
  */
@@ -51,6 +42,24 @@ struct sentry_attachment_s {
     sentry_attachment_t *next; // Linked list pointer
 };
 
+/**
+ * Returns the size in bytes of the attachment's data (buffer length or file
+ * size).
+ */
+size_t sentry__attachment_get_size(const sentry_attachment_t *attachment);
+
+/**
+ * Returns true if the attachment should be cached as an external file.
+ * Minidumps are always external; other attachments are external when they
+ * exceed the large attachment size threshold.
+ */
+static inline bool
+sentry__attachment_is_external(const sentry_attachment_t *att)
+{
+    return att->type == MINIDUMP
+        || sentry__attachment_get_size(att) >= SENTRY_LARGE_ATTACHMENT_SIZE;
+}
+
 /**
  *  Creates a new file attachment. Takes ownership of `path`.
  */
@@ -100,12 +109,6 @@ void sentry__attachments_remove(
 void sentry__attachments_extend(
     sentry_attachment_t **attachments_ptr, sentry_attachment_t *attachments);
 
-/**
- * Returns the size in bytes of the attachment's data (buffer length or file
- * size).
- */
-size_t sentry__attachment_get_size(const sentry_attachment_t *attachment);
-
 /**
  * Returns the filename string for the attachment (basename of `filename` if
  * set, otherwise basename of `path`).

src/sentry_core.c

@@ -731,8 +731,8 @@ sentry__prepare_event(const sentry_options_t *options, sentry_value_t event,
             = all_attachments ? all_attachments : scope->attachments;
         sentry__envelope_add_attachments(envelope, atts);
         if (options->run) {
-            sentry__cache_large_attachments(options->run->cache_path, event_id,
-                atts, options->run->run_path);
+            sentry__cache_external_attachments(options->run->cache_path,
+                event_id, atts, options->run->run_path);
         }
     }
 
@@ -822,7 +822,7 @@ prepare_user_feedback(sentry_value_t user_feedback, sentry_hint_t *hint)
         sentry_uuid_t event_id = sentry__envelope_get_event_id(envelope);
         SENTRY_WITH_OPTIONS (options) {
             if (options->run) {
-                sentry__cache_large_attachments(options->run->cache_path,
+                sentry__cache_external_attachments(options->run->cache_path,
                     &event_id, hint->attachments, options->run->run_path);
             }
         }
@@ -1761,7 +1761,7 @@ sentry_capture_minidump_n(const char *path, size_t path_len)
             // the minidump is added as an attachment, with the type
             // `event.minidump`
             size_t dump_size = sentry__path_get_size(dump_path);
-            bool is_large = sentry__is_large_attachment(dump_path, dump_size);
+            bool is_large = dump_size >= SENTRY_LARGE_ATTACHMENT_SIZE;
             sentry_envelope_item_t *item = sentry__envelope_add_from_path(
                 envelope, dump_path, "attachment");
 
@@ -1776,7 +1776,7 @@ sentry_capture_minidump_n(const char *path, size_t path_len)
                 tmp.path = dump_path;
                 tmp.type = MINIDUMP;
                 tmp.next = NULL;
-                sentry__cache_large_attachments(
+                sentry__cache_external_attachments(
                     options->run->cache_path, &event_id, &tmp, NULL);
             } else {
                 sentry_envelope_free(envelope);

src/sentry_database.c

@@ -166,7 +166,7 @@ write_envelope(const sentry_path_t *path, const sentry_envelope_t *envelope,
 }
 
 void
-sentry__cache_large_attachments(const sentry_path_t *cache_path,
+sentry__cache_external_attachments(const sentry_path_t *cache_path,
     const sentry_uuid_t *event_id, const sentry_attachment_t *attachments,
     const sentry_path_t *run_path)
 {
@@ -187,7 +187,7 @@ sentry__cache_large_attachments(const sentry_path_t *cache_path,
 
     for (const sentry_attachment_t *att = attachments; att; att = att->next) {
         size_t file_size = sentry__attachment_get_size(att);
-        if (!sentry__is_large_attachment(att->path, file_size)) {
+        if (!sentry__attachment_is_external(att)) {
             continue;
         }
 

src/sentry_database.h

@@ -140,13 +140,13 @@ bool sentry__has_crash_marker(const sentry_options_t *options);
 bool sentry__clear_crash_marker(const sentry_options_t *options);
 
 /**
- * Cache large attachments (>= SENTRY_LARGE_ATTACHMENT_SIZE) to
+ * Cache external attachments (e.g. minidumps) to
  * `<cache_path>/<event-uuid>/` and write `__sentry-attachments.json` metadata.
  *
  * When `run_path` is non-NULL and a file attachment's parent directory
  * matches it, the file is renamed instead of copied.
  */
-void sentry__cache_large_attachments(const sentry_path_t *cache_path,
+void sentry__cache_external_attachments(const sentry_path_t *cache_path,
     const sentry_uuid_t *event_id, const sentry_attachment_t *attachments,
     const sentry_path_t *run_path);
 

src/sentry_envelope.c

@@ -663,9 +663,7 @@ sentry__envelope_add_attachment(
         return NULL;
     }
 
-    size_t file_size = sentry__attachment_get_size(attachment);
-
-    if (sentry__is_large_attachment(attachment->path, file_size)) {
+    if (sentry__attachment_is_external(attachment)) {
         return NULL;
     }
 
@@ -728,7 +726,7 @@ sentry__envelope_add_from_path(
         return NULL;
     }
     size_t file_size = sentry__path_get_size(path);
-    if (sentry__is_large_attachment(path, file_size)) {
+    if (file_size >= SENTRY_LARGE_ATTACHMENT_SIZE) {
         return NULL;
     }
     size_t buf_len;
@@ -741,6 +739,79 @@ sentry__envelope_add_from_path(
     return envelope_add_from_owned_buffer(envelope, buf, buf_len, type);
 }
 
+bool
+sentry__envelope_append_raw_attachment(sentry_envelope_t *envelope,
+    const sentry_path_t *path, const char *filename,
+    const char *attachment_type, const char *content_type)
+{
+    if (!envelope || !envelope->is_raw || !path) {
+        return false;
+    }
+
+    size_t file_len;
+    char *file_buf = sentry__path_read_to_buffer(path, &file_len);
+    if (!file_buf) {
+        return false;
+    }
+
+    sentry_jsonwriter_t *jw = sentry__jsonwriter_new_sb(NULL);
+    if (!jw) {
+        sentry_free(file_buf);
+        return false;
+    }
+    sentry_value_t headers = sentry_value_new_object();
+    sentry_value_set_by_key(
+        headers, "type", sentry_value_new_string("attachment"));
+    sentry_value_set_by_key(
+        headers, "length", sentry_value_new_int32((int32_t)file_len));
+    if (filename) {
+        sentry_value_set_by_key(
+            headers, "filename", sentry_value_new_string(filename));
+    }
+    if (attachment_type) {
+        sentry_value_set_by_key(headers, "attachment_type",
+            sentry_value_new_string(attachment_type));
+    }
+    if (content_type) {
+        sentry_value_set_by_key(
+            headers, "content_type", sentry_value_new_string(content_type));
+    }
+    sentry__jsonwriter_write_value(jw, headers);
+    sentry_value_decref(headers);
+    size_t header_len = 0;
+    char *header_buf = sentry__jsonwriter_into_string(jw, &header_len);
+    if (!header_buf) {
+        sentry_free(file_buf);
+        return false;
+    }
+
+    size_t old_len = envelope->contents.raw.payload_len;
+    size_t new_len = old_len + 1 + header_len + 1 + file_len;
+    char *new_payload = sentry_malloc(new_len);
+    if (!new_payload) {
+        sentry_free(header_buf);
+        sentry_free(file_buf);
+        return false;
+    }
+
+    char *p = new_payload;
+    memcpy(p, envelope->contents.raw.payload, old_len);
+    p += old_len;
+    *p++ = '\n';
+    memcpy(p, header_buf, header_len);
+    p += header_len;
+    *p++ = '\n';
+    memcpy(p, file_buf, file_len);
+
+    sentry_free(envelope->contents.raw.payload);
+    envelope->contents.raw.payload = new_payload;
+    envelope->contents.raw.payload_len = new_len;
+
+    sentry_free(header_buf);
+    sentry_free(file_buf);
+    return true;
+}
+
 static void
 sentry__envelope_serialize_headers_into_stringbuilder(
     const sentry_envelope_t *envelope, sentry_stringbuilder_t *sb)

src/sentry_envelope.h

@@ -121,6 +121,14 @@ void sentry__envelope_add_attachments(
 sentry_envelope_item_t *sentry__envelope_add_from_path(
     sentry_envelope_t *envelope, const sentry_path_t *path, const char *type);
 
+/**
+ * Append an attachment item to a raw envelope by reading `path` and
+ * building the item header/payload bytes directly into the raw buffer.
+ */
+bool sentry__envelope_append_raw_attachment(sentry_envelope_t *envelope,
+    const sentry_path_t *path, const char *filename,
+    const char *attachment_type, const char *content_type);
+
 /**
  * This will add the given buffer as a new envelope item of type `type`.
  */