feat(tus): add Upload-Metadata header to TUS requests (#1795)

* feat(tus): add Upload-Metadata header to TUS requests

Add the `Upload-Metadata` header to TUS creation (POST) and upload
(PATCH) requests in the `sentry <base64({"attachment_type":"<type>"})>`
format that the relay server expects for preliminary quota checks.

* Update CHANGELOG.md

Author: jpnurmi

CHANGELOG.md

@@ -13,6 +13,7 @@
 - Add a `transfer_timeout` option for SDK-managed HTTP transports. ([#1741](https://github.com/getsentry/sentry-native/pull/1741))
 - Apple: use `os_sync_wait_on_address` for the level-triggered waitable flag in the batcher on modern macOS(14.4+) and iOS(17.4+). ([#1765](https://github.com/getsentry/sentry-native/pull/1765))
 - Native/macOS: add thread names. ([#1766](https://github.com/getsentry/sentry-native/pull/1766))
+- Add Upload-Metadata header to TUS requests. ([#1795](https://github.com/getsentry/sentry-native/pull/1795))
 
 **Fixes**:
 

examples/example.c

@@ -658,22 +658,6 @@ main(int argc, char **argv)
 
     if (has_arg(argc, argv, "large-attachment")) {
         sentry_options_set_enable_large_attachments(options, 1);
-        const char *large_file = ".sentry-large-attachment";
-        FILE *f = fopen(large_file, "wb");
-        if (f) {
-            // 100 MB = TUS upload threshold
-            char zeros[4096];
-            memset(zeros, 0, sizeof(zeros));
-            size_t remaining = 100 * 1024 * 1024;
-            while (remaining > 0) {
-                size_t chunk
-                    = remaining < sizeof(zeros) ? remaining : sizeof(zeros);
-                fwrite(zeros, 1, chunk, f);
-                remaining -= chunk;
-            }
-            fclose(f);
-            sentry_options_add_attachment(options, large_file);
-        }
     }
 
     if (has_arg(argc, argv, "stdout")) {
@@ -968,6 +952,29 @@ main(int argc, char **argv)
             view_hierarchy, SENTRY_ATTACHMENT_TYPE_VIEW_HIERARCHY);
     }
 
+    if (has_arg(argc, argv, "large-attachment")) {
+        const char *large_file = ".sentry-large-attachment";
+        FILE *f = fopen(large_file, "wb");
+        if (f) {
+            // 100 MB = TUS upload threshold
+            char zeros[4096];
+            memset(zeros, 0, sizeof(zeros));
+            size_t remaining = 100 * 1024 * 1024;
+            while (remaining > 0) {
+                size_t chunk
+                    = remaining < sizeof(zeros) ? remaining : sizeof(zeros);
+                fwrite(zeros, 1, chunk, f);
+                remaining -= chunk;
+            }
+            fclose(f);
+            sentry_attachment_t *attachment = sentry_attach_file(large_file);
+            if (attachment) {
+                sentry_attachment_set_type(
+                    attachment, SENTRY_ATTACHMENT_TYPE_MINIDUMP);
+            }
+        }
+    }
+
     if (sentry_options_get_enable_logs(options)) {
         if (has_arg(argc, argv, "capture-log")) {
             sentry_log_debug("I'm a log message!");

src/sentry_envelope.c

@@ -1551,6 +1551,8 @@ sentry__envelope_item_get_attachment_ref(
         sentry_value_get_by_key(ref->_owner, "location"));
     ref->content_type = sentry_value_as_string(
         sentry_value_get_by_key(ref->_owner, "content_type"));
+    ref->attachment_type = sentry_value_as_string(
+        sentry_value_get_by_key(item->headers, "attachment_type"));
     return true;
 }
 
@@ -1599,6 +1601,9 @@ sentry__envelope_item_resolve_attachment_ref(
     if (sentry__guarded_strlen(ref.path)) {
         resolved.path = ref.path;
     }
+    if (sentry__guarded_strlen(ref.attachment_type)) {
+        resolved.attachment_type = ref.attachment_type;
+    }
     resolved.location = location;
     if (sentry__guarded_strlen(ref.content_type)) {
         resolved.content_type = ref.content_type;

src/sentry_envelope.h

@@ -22,6 +22,7 @@ typedef struct {
     const char *path;
     const char *location;
     const char *content_type;
+    const char *attachment_type;
     sentry_value_t _owner;
 } sentry_attachment_ref_t;
 

src/sentry_utils.c

@@ -14,6 +14,7 @@
 #include <locale.h>
 #include <math.h>
 #include <stdarg.h>
+#include <stdint.h>
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
@@ -435,6 +436,37 @@ sentry__dsn_get_minidump_url(const sentry_dsn_t *dsn, const char *user_agent)
     return sentry__stringbuilder_into_string(&sb);
 }
 
+char *
+sentry__base64_encode(const char *data, size_t len)
+{
+    static const char b64[]
+        = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+    size_t output_len = 4 * ((len + 2) / 3);
+    char *out = sentry_malloc(output_len + 1);
+    if (!out) {
+        return NULL;
+    }
+
+    size_t i, j;
+    for (i = 0, j = 0; i < len; i += 3) {
+        uint32_t triple = (uint32_t)(unsigned char)data[i] << 16;
+        if (i + 1 < len) {
+            triple |= (uint32_t)(unsigned char)data[i + 1] << 8;
+        }
+        if (i + 2 < len) {
+            triple |= (uint32_t)(unsigned char)data[i + 2];
+        }
+
+        out[j++] = b64[(triple >> 18) & 0x3F];
+        out[j++] = b64[(triple >> 12) & 0x3F];
+        out[j++] = i + 1 < len ? b64[(triple >> 6) & 0x3F] : '=';
+        out[j++] = i + 2 < len ? b64[triple & 0x3F] : '=';
+    }
+
+    out[j] = '\0';
+    return out;
+}
+
 char *
 sentry__usec_time_to_iso8601(uint64_t time)
 {

src/sentry_utils.h

@@ -158,6 +158,12 @@ char *sentry__dsn_resolve_url(const sentry_dsn_t *dsn, const char *path);
 char *sentry__dsn_get_minidump_url(
     const sentry_dsn_t *dsn, const char *user_agent);
 
+/**
+ * RFC 4648 base64-encodes `len` bytes from `data` and returns a newly
+ * allocated NUL-terminated string (caller frees).
+ */
+char *sentry__base64_encode(const char *data, size_t len);
+
 /**
  * Returns the number of microseconds since the unix epoch.
  */

src/transports/sentry_http_transport.c

@@ -4,6 +4,7 @@
 #include "sentry_client_report.h"
 #include "sentry_database.h"
 #include "sentry_envelope.h"
+#include "sentry_json.h"
 #include "sentry_options.h"
 #include "sentry_ratelimiter.h"
 #include "sentry_retry.h"
@@ -20,7 +21,7 @@
 
 #define ENVELOPE_MIME "application/x-sentry-envelope"
 #define TUS_MIME "application/offset+octet-stream"
-#define TUS_MAX_HTTP_HEADERS 4
+#define TUS_MAX_HTTP_HEADERS 5
 #ifdef SENTRY_TRANSPORT_COMPRESSION
 #    define MAX_HTTP_HEADERS 4
 #else
@@ -195,9 +196,39 @@ sentry__prepared_http_request_free(sentry_prepared_http_request_t *req)
     sentry_free(req);
 }
 
+static char *
+tus_build_upload_metadata(const char *attachment_type)
+{
+    sentry_jsonwriter_t *jw = sentry__jsonwriter_new_sb(NULL);
+    sentry__jsonwriter_write_object_start(jw);
+    sentry__jsonwriter_write_key(jw, "attachment_type");
+    sentry__jsonwriter_write_str(jw, attachment_type);
+    sentry__jsonwriter_write_object_end(jw);
+
+    size_t json_len;
+    char *json = sentry__jsonwriter_into_string(jw, &json_len);
+    if (!json) {
+        return NULL;
+    }
+
+    char *encoded = sentry__base64_encode(json, json_len);
+    sentry_free(json);
+    if (!encoded) {
+        return NULL;
+    }
+
+    sentry_stringbuilder_t sb;
+    sentry__stringbuilder_init(&sb);
+    sentry__stringbuilder_append(&sb, "sentry ");
+    sentry__stringbuilder_append(&sb, encoded);
+    sentry_free(encoded);
+
+    return sentry__stringbuilder_into_string(&sb);
+}
+
 static sentry_prepared_http_request_t *
-prepare_tus_request_common(
-    size_t upload_size, const sentry_dsn_t *dsn, const char *user_agent)
+prepare_tus_request_common(size_t upload_size, const char *attachment_type,
+    const sentry_dsn_t *dsn, const char *user_agent)
 {
     if (!dsn || !dsn->is_valid) {
         return NULL;
@@ -234,12 +265,19 @@ prepare_tus_request_common(
     h->key = "upload-length";
     h->value = sentry__uint64_to_string((uint64_t)upload_size);
 
+    if (!sentry__string_empty(attachment_type)) {
+        h = &req->headers[req->headers_len++];
+        h->key = "upload-metadata";
+        h->value = tus_build_upload_metadata(attachment_type);
+    }
+
     return req;
 }
 
 static sentry_prepared_http_request_t *
 prepare_tus_upload_request(const char *location, const sentry_path_t *path,
-    size_t file_size, const sentry_dsn_t *dsn, const char *user_agent)
+    size_t file_size, const char *attachment_type, const sentry_dsn_t *dsn,
+    const char *user_agent)
 {
     if (!location || !path) {
         return NULL;
@@ -282,6 +320,12 @@ prepare_tus_upload_request(const char *location, const sentry_path_t *path,
     h->key = "upload-offset";
     h->value = sentry__string_clone("0");
 
+    if (!sentry__string_empty(attachment_type)) {
+        h = &req->headers[req->headers_len++];
+        h->key = "upload-metadata";
+        h->value = tus_build_upload_metadata(attachment_type);
+    }
+
     return req;
 }
 
@@ -346,22 +390,22 @@ http_update_ratelimiter(
 // resulting remote location URL (caller frees) in `location_out`.
 static int
 tus_upload_file(http_transport_state_t *state, const sentry_path_t *cache_path,
-    const char *basename, char **location_out)
+    const sentry_attachment_ref_t *ref, char **location_out)
 {
-    if (!basename || *basename == '\0') {
+    if (sentry__string_empty(ref->path)) {
         return RESULT_ERROR;
     }
     *location_out = NULL;
-    sentry_path_t *att_file = sentry__path_join_str(cache_path, basename);
+    sentry_path_t *att_file = sentry__path_join_str(cache_path, ref->path);
     size_t file_size = att_file ? sentry__path_get_size(att_file) : 0;
     if (!att_file || file_size == 0) {
         sentry__path_free(att_file);
         return RESULT_ERROR;
     }
 
     // Step 1: TUS creation (POST, no body)
-    sentry_prepared_http_request_t *req
-        = prepare_tus_request_common(file_size, state->dsn, state->user_agent);
+    sentry_prepared_http_request_t *req = prepare_tus_request_common(
+        file_size, ref->attachment_type, state->dsn, state->user_agent);
     if (!req) {
         sentry__path_free(att_file);
         return RESULT_ERROR;
@@ -393,8 +437,8 @@ tus_upload_file(http_transport_state_t *state, const sentry_path_t *cache_path,
         sentry__path_free(att_file);
         return RESULT_ERROR;
     }
-    req = prepare_tus_upload_request(
-        patch_url, att_file, file_size, state->dsn, state->user_agent);
+    req = prepare_tus_upload_request(patch_url, att_file, file_size,
+        ref->attachment_type, state->dsn, state->user_agent);
     sentry_free(patch_url);
     sentry__path_free(att_file);
     if (!req) {
@@ -553,8 +597,7 @@ resolve_attachment_refs(
         }
 
         char *new_location = NULL;
-        int result
-            = tus_upload_file(state, cache_path, ref.path, &new_location);
+        int result = tus_upload_file(state, cache_path, &ref, &new_location);
         if (new_location) {
             bool resolved = sentry__envelope_item_resolve_attachment_ref(
                 item, new_location);
@@ -933,17 +976,19 @@ sentry__http_transport_get_bgworker(sentry_transport_t *transport)
 #endif
 
 sentry_prepared_http_request_t *
-sentry__prepare_tus_create_request(
-    size_t file_size, const sentry_dsn_t *dsn, const char *user_agent)
+sentry__prepare_tus_create_request(size_t file_size,
+    const char *attachment_type, const sentry_dsn_t *dsn,
+    const char *user_agent)
 {
-    return prepare_tus_request_common(file_size, dsn, user_agent);
+    return prepare_tus_request_common(
+        file_size, attachment_type, dsn, user_agent);
 }
 
 sentry_prepared_http_request_t *
 sentry__prepare_tus_upload_request(const char *location,
-    const sentry_path_t *path, size_t file_size, const sentry_dsn_t *dsn,
-    const char *user_agent)
+    const sentry_path_t *path, size_t file_size, const char *attachment_type,
+    const sentry_dsn_t *dsn, const char *user_agent)
 {
     return prepare_tus_upload_request(
-        location, path, file_size, dsn, user_agent);
+        location, path, file_size, attachment_type, dsn, user_agent);
 }

src/transports/sentry_http_transport.h

@@ -27,10 +27,12 @@ sentry_prepared_http_request_t *sentry__prepare_http_request(
     sentry_envelope_t *envelope, const sentry_dsn_t *dsn,
     const sentry_rate_limiter_t *rl, const char *user_agent);
 sentry_prepared_http_request_t *sentry__prepare_tus_create_request(
-    size_t file_size, const sentry_dsn_t *dsn, const char *user_agent);
+    size_t file_size, const char *attachment_type, const sentry_dsn_t *dsn,
+    const char *user_agent);
 sentry_prepared_http_request_t *sentry__prepare_tus_upload_request(
     const char *location, const sentry_path_t *path, size_t file_size,
-    const sentry_dsn_t *dsn, const char *user_agent);
+    const char *attachment_type, const sentry_dsn_t *dsn,
+    const char *user_agent);
 
 void sentry__prepared_http_request_free(sentry_prepared_http_request_t *req);
 

tests/test_integration_tus.py

@@ -23,6 +23,8 @@
 auth_header = (
     f"Sentry sentry_key=uiaeosnrtdy, sentry_version=7, sentry_client=sentry.native/{SENTRY_VERSION}"
 )
+# sentry <base64({"attachment_type":"event.minidump"})>
+upload_metadata = "sentry eyJhdHRhY2htZW50X3R5cGUiOiJldmVudC5taW5pZHVtcCJ9"
 # fmt: on
 
 
@@ -39,6 +41,7 @@ def test_tus_upload(cmake, httpserver):
     # TUS creation request (POST, no body) -> 201 + Location
     httpserver.expect_oneshot_request(
         "/api/123456/upload/",
+        method="POST",
         headers={"tus-resumable": "1.0.0"},
     ).respond_with_data(
         "OK",
@@ -92,6 +95,7 @@ def test_tus_upload(cmake, httpserver):
     upload_length = create_req.headers.get("upload-length")
     assert upload_length is not None
     assert int(upload_length) == 100 * 1024 * 1024
+    assert create_req.headers.get("upload-metadata") == upload_metadata
 
     # Verify TUS upload request headers
     assert upload_req.headers.get("tus-resumable") == "1.0.0"
@@ -118,6 +122,7 @@ def test_tus_upload(cmake, httpserver):
     assert attachment_ref.payload.json["location"] == location
     assert not os.path.isabs(attachment_ref.payload.json["path"])
     assert attachment_ref.headers.get("attachment_length") == 100 * 1024 * 1024
+    assert attachment_ref.headers.get("attachment_type") == "event.minidump"
 
     # large attachment files should be cleaned up after send
     cache_dir = os.path.join(tmp_path, ".sentry-native", "cache")
@@ -461,6 +466,7 @@ def test_tus_crash_restart(cmake, httpserver, backend):
     # Verify TUS creation request headers
     assert create_req.headers.get("tus-resumable") == "1.0.0"
     assert int(create_req.headers.get("upload-length")) == 100 * 1024 * 1024
+    assert create_req.headers.get("upload-metadata") == upload_metadata
 
     # Verify TUS upload request headers
     assert upload_req.headers.get("tus-resumable") == "1.0.0"
@@ -550,6 +556,7 @@ def test_tus_crash_native(cmake, httpserver):
     assert upload_req is not None
     assert envelope_req is not None
     assert int(create_req.headers.get("upload-length")) == 100 * 1024 * 1024
+    assert create_req.headers.get("upload-metadata") == upload_metadata
 
     body = envelope_req.get_data()
     envelope = Envelope.deserialize(body)