feat: expose transport utilities

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Expose transport utilities ([#949](https://github.com/getsentry/sentry-rust/pull/949))
+
 ## 0.46.0
 
 ### Breaking changes

sentry/src/transports/mod.rs

@@ -8,10 +8,18 @@ use std::sync::Arc;
 
 #[cfg(feature = "httpdate")]
 mod ratelimit;
+#[cfg(feature = "httpdate")]
+pub use self::ratelimit::{RateLimiter, RateLimitingCategory};
+
 #[cfg(any(feature = "curl", feature = "ureq"))]
 mod thread;
+#[cfg(any(feature = "curl", feature = "ureq"))]
+pub use self::thread::TransportThread as StdTransportThread;
+
 #[cfg(feature = "reqwest")]
 mod tokio_thread;
+#[cfg(feature = "reqwest")]
+pub use self::tokio_thread::TransportThread as TokioTransportThread;
 
 #[cfg(feature = "reqwest")]
 mod reqwest;

sentry/src/transports/thread.rs

@@ -18,13 +18,15 @@ enum Task {
     Shutdown,
 }
 
+/// A background-thread dedicated to sending [`Envelope`]s whilst respecting the rate limits imposed in the responses.
 pub struct TransportThread {
     sender: SyncSender<Task>,
     shutdown: Arc<AtomicBool>,
     handle: Option<JoinHandle<()>>,
 }
 
 impl TransportThread {
+    /// Spawn a new background thread.
     pub fn new<SendFn>(mut send: SendFn) -> Self
     where
         SendFn: FnMut(Envelope, &mut RateLimiter) + Send + 'static,
@@ -78,6 +80,9 @@ impl TransportThread {
         }
     }
 
+    /// Send an [`Envelope`].
+    ///
+    /// In case the background thread cannot keep up, the [`Envelope`] is dropped.
     pub fn send(&self, envelope: Envelope) {
         // Using send here would mean that when the channel fills up for whatever
         // reason, trying to send an envelope would block everything. We'd rather
@@ -87,6 +92,9 @@ impl TransportThread {
         }
     }
 
+    /// Flush all pending [`Envelope`]s.
+    ///
+    /// Returns true if successful within given timeout.
     pub fn flush(&self, timeout: Duration) -> bool {
         let (sender, receiver) = sync_channel(1);
         let _ = self.sender.send(Task::Flush(sender));

sentry/src/transports/tokio_thread.rs

@@ -18,13 +18,15 @@ enum Task {
     Shutdown,
 }
 
+/// A background-thread powered by [`tokio`] dedicated to sending [`Envelope`]s whilst respecting the rate limits imposed in the responses.
 pub struct TransportThread {
     sender: SyncSender<Task>,
     shutdown: Arc<AtomicBool>,
     handle: Option<JoinHandle<()>>,
 }
 
 impl TransportThread {
+    /// Spawn a new background thread.
     pub fn new<SendFn, SendFuture>(mut send: SendFn) -> Self
     where
         SendFn: FnMut(Envelope, RateLimiter) -> SendFuture + Send + 'static,
@@ -89,6 +91,9 @@ impl TransportThread {
         }
     }
 
+    /// Send an [`Envelope`].
+    ///
+    /// In case the background thread cannot keep up, the [`Envelope`] is dropped.
     pub fn send(&self, envelope: Envelope) {
         // Using send here would mean that when the channel fills up for whatever
         // reason, trying to send an envelope would block everything. We'd rather
@@ -98,6 +103,9 @@ impl TransportThread {
         }
     }
 
+    /// Flush all pending [`Envelope`]s.
+    ///
+    /// Returns true if successful within given timeout.
     pub fn flush(&self, timeout: Duration) -> bool {
         let (sender, receiver) = sync_channel(1);
         let _ = self.sender.send(Task::Flush(sender));