feat: read and capture envelopes (#1320)

jpnurmi · jpnurmi · commit e5f0e3c8af96 · 2025-07-22T12:21:56.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,6 +13,7 @@
 - Add `Dynamic Sampling Context (DSC)` to events. ([#1254](https://github.com/getsentry/sentry-native/pull/1254))
 - Add `sentry_value_new_feedback` and `sentry_capture_feedback` to allow capturing [User Feedback](https://develop.sentry.dev/sdk/data-model/envelope-items/#user-feedback). ([#1304](https://github.com/getsentry/sentry-native/pull/1304))
   - Deprecate `sentry_value_new_user_feedback` and `sentry_capture_user_feedback` in favor of the new API.
+- Add `sentry_envelope_read_from_file`, `sentry_envelope_get_header`, and `sentry_capture_envelope`. ([#1320](https://github.com/getsentry/sentry-native/pull/1320))
 
 **Fixes**:
 
diff --git a/include/sentry.h b/include/sentry.h
@@ -662,6 +662,16 @@ typedef struct sentry_envelope_s sentry_envelope_t;
  */
 SENTRY_API void sentry_envelope_free(sentry_envelope_t *envelope);
 
+/**
+ * Given an Envelope, returns the header if present.
+ *
+ * This returns a borrowed value to the headers in the Envelope.
+ */
+SENTRY_API sentry_value_t sentry_envelope_get_header(
+    const sentry_envelope_t *envelope, const char *key);
+SENTRY_API sentry_value_t sentry_envelope_get_header_n(
+    const sentry_envelope_t *envelope, const char *key, size_t key_len);
+
 /**
  * Given an Envelope, returns the embedded Event if there is one.
  *
@@ -698,6 +708,34 @@ SENTRY_API int sentry_envelope_write_to_file(
 SENTRY_API int sentry_envelope_write_to_file_n(
     const sentry_envelope_t *envelope, const char *path, size_t path_len);
 
+/**
+ * Reads an envelope from a file.
+ *
+ * `path` is assumed to be in platform-specific filesystem path encoding.
+ *
+ * API Users on windows are encouraged to use `sentry_envelope_read_from_filew`
+ * instead.
+ */
+SENTRY_API sentry_envelope_t *sentry_envelope_read_from_file(const char *path);
+SENTRY_API sentry_envelope_t *sentry_envelope_read_from_file_n(
+    const char *path, size_t path_len);
+
+#ifdef SENTRY_PLATFORM_WINDOWS
+/**
+ * Wide char versions of `sentry_envelope_read_from_file` and
+ * `sentry_envelope_read_from_file_n`.
+ */
+SENTRY_API sentry_envelope_t *sentry_envelope_read_from_filew(
+    const wchar_t *path);
+SENTRY_API sentry_envelope_t *sentry_envelope_read_from_filew_n(
+    const wchar_t *path, size_t path_len);
+#endif
+
+/**
+ * Submits an envelope, first checking for consent.
+ */
+SENTRY_API void sentry_capture_envelope(sentry_envelope_t *envelope);
+
 /**
  * The Sentry Client Options.
  *
diff --git a/src/sentry_core.c b/src/sentry_core.c
@@ -447,6 +447,14 @@ sentry__capture_envelope(
     sentry__transport_send_envelope(transport, envelope);
 }
 
+void
+sentry_capture_envelope(sentry_envelope_t *envelope)
+{
+    SENTRY_WITH_OPTIONS (options) {
+        sentry__capture_envelope(options->transport, envelope);
+    }
+}
+
 static bool
 event_is_considered_error(sentry_value_t event)
 {
diff --git a/src/sentry_envelope.c b/src/sentry_envelope.c
@@ -65,6 +65,24 @@ envelope_item_cleanup(sentry_envelope_item_t *item)
     sentry_free(item->payload);
 }
 
+sentry_value_t
+sentry_envelope_get_header(const sentry_envelope_t *envelope, const char *key)
+{
+    return sentry_envelope_get_header_n(
+        envelope, key, sentry__guarded_strlen(key));
+}
+
+sentry_value_t
+sentry_envelope_get_header_n(
+    const sentry_envelope_t *envelope, const char *key, size_t key_len)
+{
+    if (envelope->is_raw) {
+        return sentry_value_new_null();
+    }
+    return sentry_value_get_by_key_n(
+        envelope->contents.items.headers, key, key_len);
+}
+
 void
 sentry__envelope_item_set_header(
     sentry_envelope_item_t *item, const char *key, sentry_value_t value)
@@ -726,6 +744,150 @@ sentry_envelope_write_to_file(
     return sentry_envelope_write_to_file_n(envelope, path, strlen(path));
 }
 
+// https://develop.sentry.dev/sdk/data-model/envelopes/
+static sentry_envelope_t *
+parse_envelope_from_file(sentry_path_t *path)
+{
+    if (!path) {
+        return NULL;
+    }
+
+    size_t buf_len = 0;
+    char *buf = sentry__path_read_to_buffer(path, &buf_len);
+    sentry__path_free(path);
+    if (!buf) {
+        return NULL;
+    }
+
+    sentry_envelope_t *envelope = sentry__envelope_new();
+    if (!envelope) {
+        goto fail;
+    }
+
+    const char *ptr = buf;
+    const char *end = buf + buf_len;
+
+    // headers
+    const char *headers_end = memchr(ptr, '\n', (size_t)(end - ptr));
+    if (!headers_end) {
+        headers_end = end;
+    }
+    size_t headers_len = (size_t)(headers_end - ptr);
+    sentry_value_decref(envelope->contents.items.headers);
+    envelope->contents.items.headers
+        = sentry__value_from_json(ptr, headers_len);
+    if (sentry_value_is_null(envelope->contents.items.headers)) {
+        envelope->contents.items.headers = sentry_value_new_object();
+    }
+
+    ptr = headers_end + 1; // skip newline
+
+    // items
+    while (ptr < end) {
+        sentry_envelope_item_t *item = envelope_add_item(envelope);
+        if (!item) {
+            goto fail;
+        }
+
+        // item headers
+        const char *item_headers_end = memchr(ptr, '\n', (size_t)(end - ptr));
+        if (!item_headers_end) {
+            item_headers_end = end;
+        }
+        size_t item_headers_len = (size_t)(item_headers_end - ptr);
+        sentry_value_decref(item->headers);
+        item->headers = sentry__value_from_json(ptr, item_headers_len);
+        if (sentry_value_is_null(item->headers)) {
+            goto fail;
+        }
+        ptr = item_headers_end + 1; // skip newline
+
+        // item payload
+        sentry_value_t length
+            = sentry_value_get_by_key(item->headers, "length");
+        if (sentry_value_is_null(length)) {
+            // find newline or end of buffer
+            const char *payload_end = memchr(ptr, '\n', (size_t)(end - ptr));
+            if (!payload_end) {
+                payload_end = end;
+            }
+            item->payload_len = (size_t)(payload_end - ptr);
+        } else {
+            item->payload_len = (size_t)sentry_value_as_int32(length);
+        }
+        if (item->payload_len <= 0 || ptr + item->payload_len > end) {
+            goto fail;
+        }
+        item->payload = sentry_malloc(item->payload_len + 1);
+        if (!item->payload) {
+            goto fail;
+        }
+        memcpy(item->payload, ptr, item->payload_len);
+        item->payload[item->payload_len] = '\0';
+
+        // item event/transaction
+        const char *type = sentry_value_as_string(
+            sentry_value_get_by_key(item->headers, "type"));
+        if (type
+            && (sentry__string_eq(type, "event")
+                || sentry__string_eq(type, "transaction"))) {
+            item->event
+                = sentry__value_from_json(item->payload, item->payload_len);
+        }
+
+        ptr += item->payload_len;
+        while (ptr < end && *ptr == '\n') {
+            ptr++;
+        }
+    }
+
+    sentry_free(buf);
+    return envelope;
+
+fail:
+    sentry_envelope_free(envelope);
+    sentry_free(buf);
+    return NULL;
+}
+
+sentry_envelope_t *
+sentry_envelope_read_from_file(const char *path)
+{
+    if (!path) {
+        return NULL;
+    }
+    return parse_envelope_from_file(sentry__path_from_str(path));
+}
+
+sentry_envelope_t *
+sentry_envelope_read_from_file_n(const char *path, size_t path_len)
+{
+    if (!path || path_len == 0) {
+        return NULL;
+    }
+    return parse_envelope_from_file(sentry__path_from_str_n(path, path_len));
+}
+
+#ifdef SENTRY_PLATFORM_WINDOWS
+sentry_envelope_t *
+sentry_envelope_read_from_filew(const wchar_t *path)
+{
+    if (!path) {
+        return NULL;
+    }
+    return parse_envelope_from_file(sentry__path_from_wstr(path));
+}
+
+sentry_envelope_t *
+sentry_envelope_read_from_filew_n(const wchar_t *path, size_t path_len)
+{
+    if (!path || path_len == 0) {
+        return NULL;
+    }
+    return parse_envelope_from_file(sentry__path_from_wstr_n(path, path_len));
+}
+#endif
+
 #ifdef SENTRY_UNITTEST
 size_t
 sentry__envelope_get_item_count(const sentry_envelope_t *envelope)
diff --git a/tests/unit/test_envelopes.c b/tests/unit/test_envelopes.c
@@ -14,7 +14,7 @@ static char *const SERIALIZED_ENVELOPE_STR
       "\"production\",\"sampled\":\"false\"}}\n"
       "{\"type\":\"event\",\"length\":71}\n"
       "{\"event_id\":\"c993afb6-b4ac-48a6-b61b-2558e601d65d\",\"some-"
-      "context\":null}\n"
+      "context\":1234}\n"
       "{\"type\":\"minidump\",\"length\":4}\n"
       "MDMP\n"
       "{\"type\":\"attachment\",\"length\":12}\n"
@@ -263,7 +263,8 @@ create_test_envelope()
     sentry_value_t event = sentry_value_new_object();
     sentry_value_set_by_key(
         event, "event_id", sentry__value_new_uuid(&event_id));
-    sentry_value_set_by_key(event, "some-context", sentry_value_new_null());
+    sentry_value_set_by_key(
+        event, "some-context", sentry_value_new_int32(1234));
     sentry__envelope_add_event(envelope, event);
 
     char dmp[] = "MDMP";
@@ -319,6 +320,7 @@ SENTRY_TEST(write_envelope_to_file_null)
 {
     sentry_envelope_t *empty_envelope = sentry__envelope_new();
 
+    TEST_CHECK(!sentry_envelope_read_from_file(NULL));
     TEST_CHECK_INT_EQUAL(
         sentry_envelope_write_to_file(NULL, "irrelevant/path"), 1);
     TEST_CHECK_INT_EQUAL(
@@ -336,6 +338,7 @@ SENTRY_TEST(write_envelope_to_invalid_path)
     sentry_envelope_t *envelope = create_test_envelope();
     const char *test_file_str = SENTRY_TEST_PATH_PREFIX
         "./directory_that_does_not_exist/sentry_test_envelope";
+    TEST_CHECK(!sentry_envelope_read_from_file(test_file_str));
     sentry_path_t *test_file_path = sentry__path_from_str(test_file_str);
     int rv = sentry_envelope_write_to_file(envelope, test_file_str);
     TEST_CHECK_INT_EQUAL(rv, 1);
@@ -372,3 +375,76 @@ SENTRY_TEST(write_raw_envelope_to_file)
     sentry_envelope_free(raw_envelope);
     sentry_close();
 }
+
+SENTRY_TEST(parse_envelope)
+{
+    sentry_envelope_t *test_envelope = create_test_envelope();
+    const char *test_file_str = SENTRY_TEST_PATH_PREFIX "sentry_test_envelope";
+    sentry_path_t *test_file_path = sentry__path_from_str(test_file_str);
+    TEST_CHECK_INT_EQUAL(
+        sentry_envelope_write_to_file(test_envelope, test_file_str), 0);
+
+    sentry_envelope_t *file_envelope
+        = sentry_envelope_read_from_file(test_file_str);
+
+    TEST_CHECK_STRING_EQUAL(sentry_value_as_string(sentry_envelope_get_header(
+                                file_envelope, "dsn")),
+        "https://foo@sentry.invalid/42");
+    TEST_CHECK_STRING_EQUAL(sentry_value_as_string(sentry_envelope_get_header(
+                                file_envelope, "event_id")),
+        "c993afb6-b4ac-48a6-b61b-2558e601d65d");
+
+    sentry_uuid_t event_id = sentry__envelope_get_event_id(file_envelope);
+    char event_id_str[37];
+    sentry_uuid_as_string(&event_id, event_id_str);
+    TEST_CHECK_STRING_EQUAL(
+        event_id_str, "c993afb6-b4ac-48a6-b61b-2558e601d65d");
+
+    TEST_CHECK_INT_EQUAL(sentry__envelope_get_item_count(file_envelope), 3);
+
+    sentry_value_t event = sentry_envelope_get_event(file_envelope);
+    TEST_CHECK(!sentry_value_is_null(event));
+    TEST_CHECK_INT_EQUAL(
+        sentry_value_as_int32(sentry_value_get_by_key(event, "some-context")),
+        1234);
+
+    const sentry_envelope_item_t *ev
+        = sentry__envelope_get_item(file_envelope, 0);
+    TEST_CHECK(!!ev);
+    TEST_CHECK_STRING_EQUAL(
+        sentry_value_as_string(sentry__envelope_item_get_header(ev, "type")),
+        "event");
+    size_t ev_len = 0;
+    TEST_CHECK_STRING_EQUAL(sentry__envelope_item_get_payload(ev, &ev_len),
+        "{\"event_id\":\"c993afb6-b4ac-48a6-b61b-2558e601d65d\","
+        "\"some-context\":1234}");
+
+    const sentry_envelope_item_t *dmp
+        = sentry__envelope_get_item(file_envelope, 1);
+    TEST_CHECK(!!dmp);
+    TEST_CHECK_STRING_EQUAL(
+        sentry_value_as_string(sentry__envelope_item_get_header(dmp, "type")),
+        "minidump");
+    size_t dmp_len = 0;
+    TEST_CHECK_STRING_EQUAL(
+        sentry__envelope_item_get_payload(dmp, &dmp_len), "MDMP");
+    TEST_CHECK_INT_EQUAL(dmp_len, 4);
+
+    const sentry_envelope_item_t *attachment
+        = sentry__envelope_get_item(file_envelope, 2);
+    TEST_CHECK(!!attachment);
+    TEST_CHECK_STRING_EQUAL(
+        sentry_value_as_string(
+            sentry__envelope_item_get_header(attachment, "type")),
+        "attachment");
+    size_t attachment_len = 0;
+    TEST_CHECK_STRING_EQUAL(
+        sentry__envelope_item_get_payload(attachment, &attachment_len),
+        "Hello World!");
+    TEST_CHECK_INT_EQUAL(attachment_len, 12);
+
+    sentry__path_free(test_file_path);
+    sentry_envelope_free(test_envelope);
+    sentry_envelope_free(file_envelope);
+    sentry_close();
+}
diff --git a/tests/unit/tests.inc b/tests/unit/tests.inc
@@ -86,6 +86,7 @@ XX(os_release_non_existent_files)
 XX(os_releases_snapshot)
 XX(overflow_spans)
 XX(page_allocator)
+XX(parse_envelope)
 XX(path_basics)
 XX(path_current_exe)
 XX(path_directory)

Original file line number	Diff line number	Diff line change
`@@ -447,6 +447,14 @@ sentry__capture_envelope(`
`447`	`447`	`sentry__transport_send_envelope(transport, envelope);`
`448`	`448`	`}`
`449`	`449`
	`450`	`+void`
	`451`	`+sentry_capture_envelope(sentry_envelope_t *envelope)`
	`452`	`+{`
	`453`	`+ SENTRY_WITH_OPTIONS (options) {`
	`454`	`+ sentry__capture_envelope(options->transport, envelope);`
	`455`	`+ }`
	`456`	`+}`
	`457`	`+`
`450`	`458`	`static bool`
`451`	`459`	`event_is_considered_error(sentry_value_t event)`
`452`	`460`	`{`