feat: add runtime context properties (#136)

* feat: add runtime context properties

* address pr review feedback

Author: marandaneto

.sampo/changesets/sullen-seer-aurelien.md

@@ -0,0 +1,5 @@
+---
+cargo/posthog-rs: minor
+---
+
+Add OS runtime context properties to captured events.

Cargo.lock

@@ -21,6 +21,7 @@ serde_json = "1.0.64"
 semver = "1.0.24"
 derive_builder = "0.20.2"
 uuid = { version = "1.13.2", features = ["serde", "v7"] }
+os_info = "3.14"
 sha1 = "0.10"
 regex = "1.10"
 tracing = "0.1"

Cargo.toml

@@ -1,5 +1,5 @@
 use std::collections::{HashMap, HashSet};
-use std::sync::Mutex;
+use std::sync::{Mutex, OnceLock};
 
 use crate::client::BeforeSendHook;
 use crate::client::CaptureDefaults;
@@ -14,6 +14,32 @@ pub(super) const MAX_FLAG_CALLED_CACHE_SIZE: usize = 50_000;
 
 pub(super) type FlagEventDedupCache = Mutex<HashMap<String, HashSet<String>>>;
 
+struct RuntimeContext {
+    os: String,
+    os_version: String,
+}
+
+static RUNTIME_CONTEXT: OnceLock<RuntimeContext> = OnceLock::new();
+
+fn runtime_context() -> &'static RuntimeContext {
+    RUNTIME_CONTEXT.get_or_init(|| {
+        let info = os_info::get();
+        RuntimeContext {
+            os: info.os_type().to_string(),
+            os_version: info.version().to_string(),
+        }
+    })
+}
+
+pub(super) fn apply_runtime_context(event: &mut Event) {
+    let context = runtime_context();
+    event.insert_prop_default("$os", serde_json::Value::String(context.os.clone()));
+    event.insert_prop_default(
+        "$os_version",
+        serde_json::Value::String(context.os_version.clone()),
+    );
+}
+
 pub(super) fn flag_event_dedup_cache() -> FlagEventDedupCache {
     Mutex::new(HashMap::new())
 }
@@ -326,6 +352,32 @@ mod tests {
         assert_eq!(event.properties().get("$geoip_disable"), Some(&json!(true)));
     }
 
+    #[test]
+    fn runtime_context_adds_missing_os_properties_only() {
+        let mut event = Event::new("test", "user-1");
+        event.insert_prop("$os", "custom-os").unwrap();
+
+        apply_runtime_context(&mut event);
+
+        assert_eq!(event.properties().get("$os"), Some(&json!("custom-os")));
+        assert!(event.properties().contains_key("$os_version"));
+        assert!(!event.properties().contains_key("$os_arch"));
+    }
+
+    #[test]
+    fn flag_called_event_leaves_runtime_context_to_capture_path() {
+        let event = flag_called_event(
+            flag_params(HashMap::new(), HashMap::new(), None),
+            false,
+            true,
+        )
+        .expect("valid flag-called event");
+
+        assert!(!event.properties().contains_key("$os"));
+        assert!(!event.properties().contains_key("$os_version"));
+        assert!(!event.properties().contains_key("$os_arch"));
+    }
+
     #[test]
     fn before_send_hooks_mutate_and_drop_events() {
         let options = crate::ClientOptionsBuilder::default()

src/client/common.rs

@@ -8,7 +8,7 @@ use reqwest::blocking::RequestBuilder;
 use reqwest::RequestBuilder;
 
 use super::{
-    common::{apply_before_send_hooks, apply_capture_defaults},
+    common::{apply_before_send_hooks, apply_capture_defaults, apply_runtime_context},
     BeforeSendHook, CaptureDefaults, ClientOptions,
 };
 use crate::error::Error;
@@ -24,6 +24,7 @@ use crate::event::{BatchRequest, Event, InnerEvent};
 /// event before calling `capture()` keeps their value.
 pub(crate) fn prepare_event(event: &mut Event, defaults: &CaptureDefaults) {
     apply_capture_defaults(event, defaults);
+    apply_runtime_context(event);
     event.prepare_for_v0();
 }
 

src/client/v0_capture.rs

@@ -14,7 +14,7 @@ use super::retry::{backoff_duration, is_retryable_status};
 // Re-exported so the V1 capture loops in the client modules can reach them as
 // `v1_capture::parse_retry_after` / `v1_capture::Step`.
 pub(crate) use super::retry::{parse_retry_after, Step};
-use super::{CaptureCompression, CaptureDefaults, ClientOptions};
+use super::{common::apply_runtime_context, CaptureCompression, CaptureDefaults, ClientOptions};
 use crate::error::Error;
 use crate::event::Event;
 use crate::event_v1::{CaptureResponse, EventResult, EventStatus, V1ErrorResponse, V1Event};
@@ -27,7 +27,9 @@ pub(crate) fn build_events(events: &[Event], defaults: &CaptureDefaults) -> Vec<
     events
         .iter()
         .map(|event| {
-            let mut v1 = V1Event::from_event(event);
+            let mut event = event.clone();
+            apply_runtime_context(&mut event);
+            let mut v1 = V1Event::from_event(&event);
             if let serde_json::Value::Object(ref mut map) = v1.properties {
                 if defaults.disable_geoip {
                     map.entry("$geoip_disable")