Custom HTTP transport client interface

[jpnurmi]

Problem

The public custom transport API only allows implementing a generic envelope callback function through sentry_transport_new. Once an application replaces the built-in HTTP transport this way, it also bypasses the HTTP transport’s shared behavior, including:

• HTTP retry and exponential backoff configured with sentry_options_set_http_retry
• Offline caching configured with sentry_options_set_cache_keep
• Rate-limit handling
• Client report attachment and restoration
• The standard background worker, flushing, and shutdown behavior

This makes it difficult for downstream SDKs to use platform- or framework-native HTTP clients (.NET, Dart, Qt, ...) without reimplementing a substantial part of sentry-native’s HTTP transport logic.

Proposed solution

Expose a supported public API for creating a custom HTTP transports, in addition to the existing generic function transport API.

The new API should allow users to implement the HTTP "client" interface currently used internally by sentry_http_transport. The custom client would be responsible only for executing HTTP requests and returning HTTP responses (status code & headers).

The shared HTTP transport would remain responsible for:

• Preparing and serializing requests
• Queueing work and preserving envelope order
• HTTP retry and exponential backoff
• Offline caching and cache cleanup
• Rate-limit handling
• Client reports
• Flush and shutdown behavior

Conceptually, this would be a public, stable equivalent of the existing internal sentry__http_transport_new client interface and its lifecycle callbacks.

Notes

The API design should account for potential future multi-threading.

The HTTP transport currently runs on a single transport thread. With recently introduced support for large attachments, it may eventually be useful to be able to process requests using multiple transport threads, to avoid blocking the transport pipeline with a long-lasting large attachment upload.

In a multi-threaded transport model, each transport thread would need its own HTTP client instance. The public interface should therefore avoid assuming that one client instance is permanently shared by the entire transport. For example, it could expose a client factory with per-thread startup, shutdown, and cleanup callbacks.

Thread-safety, request ordering, and client ownership should be documented so that adding multiple transport threads later does not require a breaking API change.

[linear-code]

NATIVE-212

[HuzaifaAbdulRehman]

Hi, I'd be interested in taking this on.

I went through sentry_http_transport.h and the two existing clients (sentry_http_transport_curl.c, sentry_http_transport_winhttp.c) before proposing anything. The internal interface already has basically the right shape for this, a send function plus optional free_client/start_client/shutdown_client callbacks, so making that public looks like the right direction.

One thing I noticed that I think should change along the way rather than just get exposed as-is: right now, parsing the Sentry-specific response headers (retry-after, x-sentry-rate-limits, location) into sentry_http_response_t happens separately inside both the curl and WinHTTP clients, the same logic implemented twice. If the public client interface keeps that shape, every downstream implementation (Qt, .NET, Dart, etc.) would end up reimplementing that same parsing a third time. I think the public boundary should hand the client raw response headers instead, and move that parsing into the shared transport layer once, so new clients only have to execute a request and hand back headers, not know which headers Sentry cares about.

On the multi-threading note, since you mentioned not wanting to assume one client instance lives for the whole transport, would a factory-style API work for what you had in mind, create/destroy per thread plus the send callback, or is there a different ownership model you're already leaning toward?

Happy to put together a short design write-up covering the struct/callback shapes and this header-parsing change before touching any code, if that's useful.

[jpnurmi]

Hi @HuzaifaAbdulRehman,

Sure, you're very welcome to grab the task! 👍

One thing I noticed that I think should change along the way rather than just get exposed as-is: right now, parsing the Sentry-specific response headers (retry-after, x-sentry-rate-limits, location) into sentry_http_response_t happens separately inside both the curl and WinHTTP clients, the same logic implemented twice. If the public client interface keeps that shape, every downstream implementation (Qt, .NET, Dart, etc.) would end up reimplementing that same parsing a third time. I think the public boundary should hand the client raw response headers instead, and move that parsing into the shared transport layer once, so new clients only have to execute a request and hand back headers, not know which headers Sentry cares about.

Good insights about the headers. Something like a generic setter per header would probably work well for passing incoming headers with any HTTP client implementation:

void sentry_http_response_set_header(sentry_http_response_t *response, const char *key, const char *value);

Sentry can then internally process the ones it is actually interested in.

On the multi-threading note, since you mentioned not wanting to assume one client instance lives for the whole transport, would a factory-style API work for what you had in mind, create/destroy per thread plus the send callback, or is there a different ownership model you're already leaning toward?

Yes, a factory-style API would work. Even though there are no immediate plans to add multi-client support right now, it's been previously discussed as a potential future improvement, so I'd prefer to have an API that doesn't exclude the possibility. I think we're good if we simply pass a client factory function instead of a client instance like the current implementation does.