feat: Add attachment support to user feedback

[tustanivsky]

This PR adds the ability to attach files and binary data to feedback submissions allowing users to include screenshots, logs or other contextual information alongside their text messages.

The initial request to add attachment support for user feedback originated from the Unreal SDK:

• Screenshot as attachment along event / Feedback for Windows & Linux sentry-unreal#927

Here, a hint pattern is used (borrowed from the Android SDK) which relies on an opaque pointer to provide a standardized way to attach optional context or metadata to feedback without modifying its core value.

Example usage:

// Create the feedback (what to send)
sentry_value_t feedback = sentry_value_new_feedback(...);

// Create a hint
sentry_hint_t *hint = sentry_hint_new();
sentry_hint_attach_file(hint, "screenshot.png");

// Capture feedback with hint (both are freed automatically)
sentry_capture_feedback_with_hint(feedback, hint);

Current implementation focuses on the feedback use case but it can be expanded to support additional APIs later on if needed.

[github-actions]

	Messages
📖	Do not forget to update Sentry-docs with your feature once the pull request gets approved.

Generated by 🚫 dangerJS against 148416a

[jpnurmi]

Looks good at first glance, even though it feels like it's a lot of new API for a very specific use case. Since the goal is to add attachments to envelopes, I wonder if it would make sense to open up some of the existing but internal envelope APIs to make the same achievable in a more generic way. What do you think?

[jpnurmi]

Since the goal is to add attachments to envelopes, I wonder if it would make sense to open up some of the existing but internal envelope APIs to make the same achievable in a more generic way.

To elaborate a bit, I'd propose wrapping/exposing the missing parts from sentry_envelope.h so that the code becomes:

sentry_value_t feedback = sentry_value_new_feedback(...);

sentry_envelope_t *envelope = sentry_envelope_new();
sentry_envelope_add_feedback(envelope, feedback);
sentry_envelope_attach_file(envelope, "screenshot.png");

sentry_capture_envelope(envelope);

[tustanivsky]

Exposing internal envelope APIs sounds like a reasonable alternative to me.

However, if there are any concerns about doing so, the newly introduced hint type (perhaps with a more generic name like sentry_hint_t instead of sentry_feedback_hint_t) could serve as a public interface for attaching extra data to captured events as well.

Also, the before_send callback already accepts a hint parameter (currently defaulted to NULL) which might be repurposed for this as well - for example, in Android SDK the beforeSend handler provides a hint parameter that can be used to attach files to specific events. This contrasts with the current approach in Unreal SDK where attachments (like game screenshot) are added to the global scope during the on_crash hook processing so that crashpad can pick them up during uploading the event.

UPD: sentry_feedback_hint_t was renamed to sentry_hint_t to support a wider range of use cases (e.g. for events capturing).

[tustanivsky]

If envelope was created successfully it takes ownership of the user_feedback value so we don't have to decref manually.

[tustanivsky]

@JoshuaMoelans @jpnurmi The PR was updated to make the hint structure more generic rather than feedback-specific (sentry_feedback_hint_t -> sentry_hint_t). This technically allows it to be reused for other functionalities in the future and potentially in the beforeSend callback (e.g. to add attachments to a single captured event). Do you think we can move forward with these new APIs?

[jpnurmi]

I think it looks good in principle. 👍 There are still some "setry_feedback_hint" references to rename, and perhaps sentry_feedback.* should be renamed to sentry_hint.* too?

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{Bugbot Autofix is OFF. To automatically fix reported issues with Cloud Agents, enable Autofix in the Cursor dashboard.}

[tustanivsky]

There are still some "setry_feedback_hint" references to rename, and perhaps sentry_feedback.* should be renamed to sentry_hint.* too?

Yes, cleaning up the remaining references to sentry_feedback_hint makes sense.

[jpnurmi]

Was this decref intentionally removed? In the happy path above, the envelope takes ownership of user_feedback, but if it failed to prepare an envelope, would user_feedback be leaked?

[tustanivsky]

If prepare_user_feedback fails to create an envelope the user_feedback should be freed automatically:

sentry-native/src/sentry_core.c

Lines 799 to 803 in 5f54734

	fail:
	SENTRY_WARN("dropping user feedback");
	sentry_envelope_free(envelope);
	sentry_value_decref(user_feedback);
	return NULL;

[jpnurmi]

ah, so there's a bug in the existing implementation. good catch, and thanks for fixing it! 👍

[JoshuaMoelans]

Looks good! Small nit on clarifying a docstring, but no issues otherwise.