First pass

Author: gyuheon0h

datadog-crashtracker-ffi/src/lib.rs

@@ -16,6 +16,7 @@ mod crash_info;
 mod demangler;
 #[cfg(all(unix, feature = "receiver"))]
 mod receiver;
+mod runtime_callback;
 #[cfg(all(unix, feature = "collector"))]
 pub use collector::*;
 #[cfg(all(windows, feature = "collector_windows"))]
@@ -25,3 +26,4 @@ pub use crash_info::*;
 pub use demangler::*;
 #[cfg(all(unix, feature = "receiver"))]
 pub use receiver::*;
+pub use runtime_callback::*;

datadog-crashtracker-ffi/src/runtime_callback.rs

@@ -0,0 +1,290 @@
+// Copyright 2025-Present Datadog, Inc. https://www.datadoghq.com/
+// SPDX-License-Identifier: Apache-2.0
+
+//! FFI bindings for runtime callback registration
+//!
+//! This module provides C-compatible FFI bindings for registering runtime-specific
+//! crash callbacks that can provide stack traces for dynamic languages.
+use datadog_crashtracker::{
+    get_registered_callback_type_ptr, get_registered_runtime_type_ptr,
+    is_runtime_callback_registered, register_runtime_stack_callback, CallbackError, CallbackType,
+    RuntimeStackCallback, RuntimeType,
+};
+
+// Re-export the enums for C/C++ consumers
+pub use datadog_crashtracker::CallbackType as ddog_CallbackType;
+pub use datadog_crashtracker::RuntimeType as ddog_RuntimeType;
+
+#[cfg(test)]
+use datadog_crashtracker::clear_runtime_callback;
+use std::ffi::c_char;
+
+/// Result type for runtime callback registration
+#[repr(C)]
+#[derive(Debug, PartialEq, Eq)]
+pub enum CallbackResult {
+    Ok,
+    NullCallback,
+    UnknownError,
+}
+
+impl From<CallbackError> for CallbackResult {
+    fn from(error: CallbackError) -> Self {
+        match error {
+            CallbackError::NullCallback => CallbackResult::NullCallback,
+        }
+    }
+}
+
+/// Register a runtime stack collection callback
+///
+/// This function allows language runtimes to register a callback that will be invoked
+/// during crash handling to collect runtime-specific stack traces.
+///
+/// # Arguments
+/// - `callback`: The callback function to invoke during crashes
+/// - `context`: User-provided context pointer passed to the callback
+///
+/// # Returns
+/// - `CallbackResult::Ok` if registration succeeds
+/// - `CallbackResult::NullCallback` if the callback function is null
+///
+/// # Safety
+/// - The callback must be signal-safe
+/// - The context pointer must remain valid for the lifetime of the process
+/// - Only one callback can be registered at a time
+/// - The callback must be registered once on CrashTracker initialization, before any crash occurs
+///
+/// # Example Usage from C
+/// ```c
+/// static void my_runtime_callback(
+///     void (*emit_frame)(const ddog_RuntimeStackFrame*),
+///     void (*emit_stacktrace_string)(const char*),
+///     void* context
+/// ) {
+///     // Collect runtime frames and call emit_frame for each one
+///     ddog_RuntimeStackFrame frame = {
+///         .function_name = "my_function",
+///         .file_name = "script.rb",
+///         .line_number = 42,
+///         .column_number = 10,
+///         .class_name = "MyClass",
+///         .module_name = NULL
+///     };
+///     emit_frame(&frame);
+/// }
+///
+///
+/// ddog_CallbackResult result = ddog_crasht_register_runtime_stack_callback(
+///     my_runtime_callback,
+///     RuntimeType::Ruby,
+///     CallbackType::Frame,
+/// );
+/// ```
+/// Register a runtime stack collection callback using type-safe enums
+///
+/// This function provides compile-time safety by using enums instead of strings
+/// for runtime and callback types.
+///
+/// # Arguments
+/// - `callback`: The callback function to invoke during crashes
+/// - `runtime_type`: Runtime type enum (Python, Ruby, Php, Nodejs, Unknown)
+/// - `callback_type`: Callback type enum (Frame, StacktraceString)
+///
+/// # Returns
+/// - `CallbackResult::Ok` if registration succeeds (replaces any existing callback)
+/// - `CallbackResult::NullCallback` if the callback function is null
+///
+/// # Safety
+/// - The callback must be signal-safe
+/// - Only one callback can be registered at a time (this replaces any existing one)
+#[no_mangle]
+pub unsafe extern "C" fn ddog_crasht_register_runtime_stack_callback(
+    callback: RuntimeStackCallback,
+    runtime_type: RuntimeType,
+    callback_type: CallbackType,
+) -> CallbackResult {
+    match register_runtime_stack_callback(callback, runtime_type, callback_type) {
+        Ok(()) => CallbackResult::Ok,
+        Err(e) => e.into(),
+    }
+}
+
+/// Check if a runtime callback is currently registered
+///
+/// Returns true if a callback is registered, false otherwise
+///
+/// # Safety
+/// This function is safe to call at any time
+#[no_mangle]
+pub extern "C" fn ddog_crasht_is_runtime_callback_registered() -> bool {
+    is_runtime_callback_registered()
+}
+
+/// Get the runtime type from the currently registered callback context
+///
+/// Returns the runtime type C string pointer if a callback with valid context is registered,
+/// null pointer otherwise
+///
+/// # Safety
+/// - The returned pointer is valid only while the callback remains registered
+/// - The caller should not free the returned pointer
+/// - The returned string should be copied if it needs to persist beyond callback lifetime
+#[no_mangle]
+pub unsafe extern "C" fn ddog_crasht_get_registered_runtime_type() -> *const c_char {
+    get_registered_runtime_type_ptr()
+}
+
+/// Get the callback type from the currently registered callback context
+///
+/// Returns the callback type C string pointer if a callback with valid context is registered,
+/// null pointer otherwise
+///
+/// # Safety
+/// - The returned pointer is valid only while the callback remains registered
+/// - The caller should not free the returned pointer
+/// - The returned string should be copied if it needs to persist beyond callback lifetime
+#[no_mangle]
+pub unsafe extern "C" fn ddog_crasht_get_registered_callback_type() -> *const c_char {
+    get_registered_callback_type_ptr()
+}
+
+// Re-export the core RuntimeStackFrame for C interop; consumers need to create RuntimeStackFrame
+pub use datadog_crashtracker::RuntimeStackFrame as ddog_RuntimeStackFrame;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use datadog_crashtracker::RuntimeStackFrame;
+    use std::ffi::CString;
+    use std::ptr;
+    use std::sync::Mutex;
+
+    // Use a mutex to ensure tests run sequentially to avoid race conditions
+    // with the global static variable
+    static TEST_MUTEX: Mutex<()> = Mutex::new(());
+
+    unsafe extern "C" fn test_runtime_callback(
+        emit_frame: unsafe extern "C" fn(*const RuntimeStackFrame),
+        _emit_stacktrace_string: unsafe extern "C" fn(*const c_char),
+    ) {
+        let function_name = CString::new("test_function").unwrap();
+        let file_name = CString::new("test.rb").unwrap();
+        let class_name = CString::new("TestClass").unwrap();
+
+        // Create the internal RuntimeStackFrame directly; no conversion needed
+        // since both RuntimeStackFrame and ddog_RuntimeStackFrame have identical layouts
+        let frame = RuntimeStackFrame {
+            function_name: function_name.as_ptr(),
+            file_name: file_name.as_ptr(),
+            line_number: 42,
+            column_number: 10,
+            class_name: class_name.as_ptr(),
+            module_name: ptr::null(),
+        };
+
+        emit_frame(&frame);
+    }
+
+    #[test]
+    fn test_ffi_callback_registration() {
+        let _guard = TEST_MUTEX.lock().unwrap();
+        unsafe {
+            // Ensure clean state at start
+            clear_runtime_callback();
+
+            // Test that no callback is initially registered
+            assert!(!ddog_crasht_is_runtime_callback_registered());
+            assert_eq!(ddog_crasht_get_registered_runtime_type(), ptr::null());
+
+            // Test successful registration using type-safe enums
+            let result = ddog_crasht_register_runtime_stack_callback(
+                test_runtime_callback,
+                RuntimeType::Ruby,
+                CallbackType::Frame,
+            );
+
+            assert_eq!(result, CallbackResult::Ok);
+
+            // Verify callback is now registered
+            assert!(ddog_crasht_is_runtime_callback_registered());
+
+            // Verify we can retrieve the runtime type
+            let runtime_type_ptr = ddog_crasht_get_registered_runtime_type();
+            assert!(!runtime_type_ptr.is_null());
+            let runtime_type_str = std::ffi::CStr::from_ptr(runtime_type_ptr).to_str().unwrap();
+            assert_eq!(runtime_type_str, "ruby");
+
+            // Test duplicate registration fails
+            let result = ddog_crasht_register_runtime_stack_callback(
+                test_runtime_callback,
+                RuntimeType::Ruby,
+                CallbackType::Frame,
+            );
+            assert_eq!(result, CallbackResult::Ok);
+
+            // Callback should still be registered after successful re-registration
+            assert!(ddog_crasht_is_runtime_callback_registered());
+
+            // Clean up - clear the registered callback for subsequent tests
+            clear_runtime_callback();
+        }
+    }
+
+    #[test]
+    fn test_enum_based_registration() {
+        let _guard = TEST_MUTEX.lock().unwrap();
+        unsafe {
+            clear_runtime_callback();
+
+            // Test that no callback is initially registered
+            assert!(!ddog_crasht_is_runtime_callback_registered());
+
+            // Test registration with enum values - Python + StacktraceString
+            let result = ddog_crasht_register_runtime_stack_callback(
+                test_runtime_callback,
+                RuntimeType::Python,
+                CallbackType::StacktraceString,
+            );
+
+            assert_eq!(result, CallbackResult::Ok);
+            assert!(ddog_crasht_is_runtime_callback_registered());
+
+            // Verify runtime type
+            let runtime_type_ptr = ddog_crasht_get_registered_runtime_type();
+            assert!(!runtime_type_ptr.is_null());
+            let runtime_type_str = std::ffi::CStr::from_ptr(runtime_type_ptr).to_str().unwrap();
+            assert_eq!(runtime_type_str, "python");
+
+            // Verify callback type
+            let callback_type_ptr = ddog_crasht_get_registered_callback_type();
+            assert!(!callback_type_ptr.is_null());
+            let callback_type_str = std::ffi::CStr::from_ptr(callback_type_ptr)
+                .to_str()
+                .unwrap();
+            assert_eq!(callback_type_str, "stacktrace_string");
+
+            // Test re-registration with different values - Ruby + Frame
+            let result = ddog_crasht_register_runtime_stack_callback(
+                test_runtime_callback,
+                RuntimeType::Ruby,
+                CallbackType::Frame,
+            );
+
+            assert_eq!(result, CallbackResult::Ok);
+
+            // Verify new values
+            let runtime_type_ptr = ddog_crasht_get_registered_runtime_type();
+            let runtime_type_str = std::ffi::CStr::from_ptr(runtime_type_ptr).to_str().unwrap();
+            assert_eq!(runtime_type_str, "ruby");
+
+            let callback_type_ptr = ddog_crasht_get_registered_callback_type();
+            let callback_type_str = std::ffi::CStr::from_ptr(callback_type_ptr)
+                .to_str()
+                .unwrap();
+            assert_eq!(callback_type_str, "frame");
+
+            clear_runtime_callback();
+        }
+    }
+}