feat: runtime-independent background event transport (#145)

Author: cat-ph

.sampo/changesets/runtime-independent-event-transport.md

@@ -0,0 +1,9 @@
+---
+posthog-rs: minor
+---
+
+Runtime-independent background event transport. `capture` and `capture_batch` are now non-blocking enqueues onto a background worker — a plain `std::thread` with a blocking HTTP client, independent of any async runtime — that batches events, retries transient failures with backoff (honoring `Retry-After`), and sends them. They no longer block on the network or return delivery errors.
+
+New public API: `flush()` (awaited on the async client, blocking on the blocking client), `shutdown()` (flush + stop the worker + join; idempotent; drops further captures), and flush-on-`Drop`. New `ClientOptions`: `flush_at`, `max_batch_size`, `flush_interval_ms`, `max_queue_size` (a bounded queue that drops with a single warning when full), and `shutdown_timeout_ms` (bounds the shutdown/`Drop` drain). `before_send` hooks now run on the worker thread, so they apply to every queued event.
+
+Breaking change (0.x): `capture` and `capture_batch` no longer return a `Result` — and are no longer `async` on the async client. They enqueue the event and return immediately (infallibly) instead of awaiting delivery; transient HTTP failures surface as logged warnings rather than `Err`. Call `flush()` or `shutdown()` before process exit to ensure queued events are delivered.

api/public-api.txt

@@ -101,16 +101,21 @@ pub struct posthog_rs::CaptureResponse
 pub posthog_rs::CaptureResponse::results: std::collections::hash::map::HashMap<uuid::Uuid, posthog_rs::EventResult>
 pub struct posthog_rs::Client
 impl posthog_rs::Client
-pub async fn posthog_rs::Client::capture(&self, posthog_rs::Event) -> core::result::Result<(), posthog_rs::Error>
-pub async fn posthog_rs::Client::capture_batch(&self, alloc::vec::Vec<posthog_rs::Event>, bool) -> core::result::Result<(), posthog_rs::Error>
+pub fn posthog_rs::Client::capture(&self, posthog_rs::Event)
+pub fn posthog_rs::Client::capture_batch(&self, alloc::vec::Vec<posthog_rs::Event>, bool)
 pub async fn posthog_rs::Client::capture_exception<E>(&self, &E) -> core::result::Result<(), posthog_rs::Error> where E: core::error::Error + ?core::marker::Sized
 pub async fn posthog_rs::Client::capture_exception_with<E>(&self, &E, posthog_rs::CaptureExceptionOptions) -> core::result::Result<(), posthog_rs::Error> where E: core::error::Error + ?core::marker::Sized
 pub fn posthog_rs::Client::evaluate_feature_flag_locally(&self, &posthog_rs::FeatureFlag, &str, &std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>, &std::collections::hash::map::HashMap<alloc::string::String, alloc::string::String>, &std::collections::hash::map::HashMap<alloc::string::String, std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>>) -> core::result::Result<posthog_rs::FlagValue, posthog_rs::Error>
 pub async fn posthog_rs::Client::evaluate_flags<S: core::convert::Into<alloc::string::String>>(&self, S, posthog_rs::EvaluateFlagsOptions) -> core::result::Result<posthog_rs::FeatureFlagEvaluations, posthog_rs::Error>
+pub async fn posthog_rs::Client::flush(&self)
 pub async fn posthog_rs::Client::get_feature_flag<K: core::convert::Into<alloc::string::String>, D: core::convert::Into<alloc::string::String>>(&self, K, D, core::option::Option<std::collections::hash::map::HashMap<alloc::string::String, alloc::string::String>>, core::option::Option<std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>>, core::option::Option<std::collections::hash::map::HashMap<alloc::string::String, std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>>>) -> core::result::Result<core::option::Option<posthog_rs::FlagValue>, posthog_rs::Error>
 pub async fn posthog_rs::Client::get_feature_flag_payload<K: core::convert::Into<alloc::string::String>, D: core::convert::Into<alloc::string::String>>(&self, K, D) -> core::result::Result<core::option::Option<serde_json::value::Value>, posthog_rs::Error>
 pub async fn posthog_rs::Client::get_feature_flags<S: core::convert::Into<alloc::string::String>>(&self, S, core::option::Option<std::collections::hash::map::HashMap<alloc::string::String, alloc::string::String>>, core::option::Option<std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>>, core::option::Option<std::collections::hash::map::HashMap<alloc::string::String, std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>>>) -> core::result::Result<(std::collections::hash::map::HashMap<alloc::string::String, posthog_rs::FlagValue>, std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>), posthog_rs::Error>
 pub async fn posthog_rs::Client::is_feature_enabled<K: core::convert::Into<alloc::string::String>, D: core::convert::Into<alloc::string::String>>(&self, K, D, core::option::Option<std::collections::hash::map::HashMap<alloc::string::String, alloc::string::String>>, core::option::Option<std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>>, core::option::Option<std::collections::hash::map::HashMap<alloc::string::String, std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>>>) -> core::result::Result<bool, posthog_rs::Error>
+pub fn posthog_rs::Client::pending_events(&self) -> usize
+pub async fn posthog_rs::Client::shutdown(&self)
+impl core::ops::drop::Drop for posthog_rs::Client
+pub fn posthog_rs::Client::drop(&mut self)
 pub struct posthog_rs::ClientOptions
 impl posthog_rs::ClientOptions
 pub fn posthog_rs::ClientOptions::is_disabled(&self) -> bool
@@ -128,15 +133,20 @@ pub fn posthog_rs::ClientOptionsBuilder::enable_local_evaluation(&mut self, bool
 pub fn posthog_rs::ClientOptionsBuilder::error_tracking(&mut self, posthog_rs::ErrorTrackingOptions) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::extra_capture_headers(&mut self, std::collections::hash::map::HashMap<alloc::string::String, alloc::string::String>) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::feature_flags_request_timeout_seconds(&mut self, u64) -> &mut Self
+pub fn posthog_rs::ClientOptionsBuilder::flush_at(&mut self, usize) -> &mut Self
+pub fn posthog_rs::ClientOptionsBuilder::flush_interval_ms(&mut self, u64) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::host<VALUE: core::convert::Into<alloc::string::String>>(&mut self, VALUE) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::is_server(&mut self, bool) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::local_evaluation_only(&mut self, bool) -> &mut Self
+pub fn posthog_rs::ClientOptionsBuilder::max_batch_size(&mut self, usize) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::max_capture_attempts(&mut self, u32) -> &mut Self
+pub fn posthog_rs::ClientOptionsBuilder::max_queue_size(&mut self, usize) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::personal_api_key<VALUE: core::convert::Into<alloc::string::String>>(&mut self, VALUE) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::poll_interval_seconds(&mut self, u64) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::request_timeout_seconds(&mut self, u64) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::retry_initial_backoff_ms(&mut self, u64) -> &mut Self
 pub fn posthog_rs::ClientOptionsBuilder::retry_max_backoff_ms(&mut self, u64) -> &mut Self
+pub fn posthog_rs::ClientOptionsBuilder::shutdown_timeout_ms(&mut self, u64) -> &mut Self
 impl posthog_rs::ClientOptionsBuilder
 pub fn posthog_rs::ClientOptionsBuilder::before_send<F>(&mut self, F) -> &mut Self where F: core::ops::function::FnMut(posthog_rs::Event) -> core::option::Option<posthog_rs::Event> + core::marker::Send + 'static
 pub fn posthog_rs::ClientOptionsBuilder::build(&self) -> core::result::Result<posthog_rs::ClientOptions, posthog_rs::ClientOptionsBuilderError>
@@ -302,13 +312,15 @@ pub posthog_rs::Property::value: serde_json::value::Value
 pub const posthog_rs::DEFAULT_HOST: &str
 pub const posthog_rs::EU_INGESTION_ENDPOINT: &str
 pub const posthog_rs::US_INGESTION_ENDPOINT: &str
-pub async fn posthog_rs::capture(posthog_rs::Event) -> core::result::Result<(), posthog_rs::Error>
+pub fn posthog_rs::capture(posthog_rs::Event)
 pub async fn posthog_rs::capture_exception<E>(&E) -> core::result::Result<(), posthog_rs::Error> where E: core::error::Error + ?core::marker::Sized
 pub async fn posthog_rs::capture_exception_with<E>(&E, posthog_rs::CaptureExceptionOptions) -> core::result::Result<(), posthog_rs::Error> where E: core::error::Error + ?core::marker::Sized
 pub async fn posthog_rs::client<C: core::convert::Into<posthog_rs::ClientOptions>>(C) -> posthog_rs::Client
 pub fn posthog_rs::disable_global()
+pub async fn posthog_rs::flush()
 pub fn posthog_rs::global_is_disabled() -> bool
 pub async fn posthog_rs::init_global<C: core::convert::Into<posthog_rs::ClientOptions>>(C) -> core::result::Result<(), posthog_rs::Error>
 pub fn posthog_rs::match_feature_flag(&posthog_rs::FeatureFlag, &str, &std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>, &std::collections::hash::map::HashMap<alloc::string::String, alloc::string::String>, &std::collections::hash::map::HashMap<alloc::string::String, std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>>, &std::collections::hash::map::HashMap<alloc::string::String, alloc::string::String>) -> core::result::Result<posthog_rs::FlagValue, posthog_rs::InconclusiveMatchError>
 pub fn posthog_rs::match_feature_flag_with_context(&posthog_rs::FeatureFlag, &std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>, &posthog_rs::EvaluationContext<'_>) -> core::result::Result<posthog_rs::FlagValue, posthog_rs::InconclusiveMatchError>
 pub fn posthog_rs::match_property_with_context(&posthog_rs::Property, &std::collections::hash::map::HashMap<alloc::string::String, serde_json::value::Value>, &posthog_rs::EvaluationContext<'_>) -> core::result::Result<bool, posthog_rs::InconclusiveMatchError>
+pub async fn posthog_rs::shutdown()