feat: add git tracing features (#175)

Author: seokju-na

index.d.ts

@@ -8028,6 +8028,46 @@ export type StatusShow =  'Index'|
 'Workdir'|
 'IndexAndWorkdir';
 
+/**
+ * Clear the global subscriber
+ *
+ * @category Tracing
+ * @signature
+ * ```ts
+ * function traceClear(): void;
+ * ```
+ */
+export declare function traceClear(): void
+
+/**
+ * Available tracing levels.  When tracing is set to a particular level,
+ * callers will be provided tracing at the given level and all lower levels.
+ */
+export type TraceLevel =  'None'|
+'Fatal'|
+'Error'|
+'Warn'|
+'Info'|
+'Debug'|
+'Trace';
+
+/**
+ * Set the global subscriber called when libgit2 produces a tracing message.
+ *
+ * @category Tracing
+ * @signature
+ * ```ts
+ * function traceSet(
+ *   level: TraceLevel,
+ *   callback: (level: TraceLevel, message: string) => void,
+ * ): void;
+ * ```
+ *
+ * @param {TraceLevel} level - Level to set tracing to
+ * @param {(level: TraceLevel, message: string) => void} callback - Callback to call with trace data
+ */
+export declare function traceSet(level: TraceLevel, callback: (level: TraceLevel, message: string) => void): void
+
 /**
  * - `PreOrder` : Runs the traversal in pre-order.
  * - `PostOrder` : Runs the traversal in post-order.

index.js

@@ -0,0 +1,59 @@
+/// Source codes are from [rolldown](https://github.com/rolldown/rolldown)
+/// See: https://github.com/rolldown/rolldown/blob/fc5ec4dbb8cf7a9bc32f2cba6e0e82eba3ac888d/crates/rolldown_binding/src/types/js_callback.rs#L98
+use napi::bindgen_prelude::{FromNapiValue, JsValuesTupleIntoVec};
+use napi::threadsafe_function::{ThreadsafeFunction, UnknownReturnValue};
+use napi::{Either, Error, Status};
+use std::sync::{Arc, Condvar, Mutex};
+
+pub type JsCallback<Args = (), Ret = ()> =
+  Arc<ThreadsafeFunction<Args, Either<Ret, UnknownReturnValue>, Args, Status, false, true>>;
+
+pub trait JsCallbackExt<Args, Ret> {
+  fn invoke(&self, args: Args) -> Result<Ret, Error>;
+}
+
+impl<Args, Ret> JsCallbackExt<Args, Ret> for JsCallback<Args, Ret>
+where
+  Args: 'static + Send + JsValuesTupleIntoVec,
+  Ret: 'static + Send + FromNapiValue,
+  Either<Ret, UnknownReturnValue>: FromNapiValue,
+{
+  fn invoke(&self, args: Args) -> Result<Ret, Error> {
+    let init_value = Ok(Either::B(UnknownReturnValue));
+    let pair = Arc::new((Mutex::new(init_value), Condvar::new()));
+    let pair_clone = Arc::clone(&pair);
+
+    self.call_with_return_value(
+      args,
+      napi::threadsafe_function::ThreadsafeFunctionCallMode::NonBlocking,
+      move |ret, _env| {
+        let (lock, cvar) = &*pair;
+        *lock.lock().unwrap() = ret;
+        cvar.notify_one();
+        Ok(())
+      },
+    );
+
+    let (lock, cvar) = &*pair_clone;
+    let notified = lock.lock().unwrap();
+    let mut res = cvar
+      .wait(notified)
+      .map_err(|err| Error::new(Status::GenericFailure, format!("PoisonError: {err:?}",)))?;
+    let res = res
+      .as_mut()
+      .map_err(|err| Error::new(Status::GenericFailure, format!("{err:?}",)))?;
+
+    match std::mem::replace(res, Either::B(UnknownReturnValue)) {
+      Either::A(ret) => Ok(ret),
+      Either::B(_unknown) => unknown_return_err::<Ret>(),
+    }
+  }
+}
+
+fn unknown_return_err<Ret>() -> Result<Ret, Error> {
+  let js_type = "unknown";
+  Err(Error::new(
+    Status::InvalidArg,
+    format!("UNKNOWN_RETURN_VALUE. Cannot convert {js_type}"),
+  ))
+}

src/js.rs

@@ -14,6 +14,7 @@ pub mod diff;
 mod error;
 pub mod ignore;
 pub mod index;
+pub(crate) mod js;
 pub mod mailmap;
 pub mod merge;
 pub mod note;
@@ -30,6 +31,7 @@ pub mod signature;
 pub mod stash;
 pub mod status;
 pub mod tag;
+pub mod tracing;
 pub mod tree;
 pub(crate) mod util;
 

src/lib.rs

@@ -0,0 +1,97 @@
+use crate::js::{JsCallback, JsCallbackExt};
+use napi::bindgen_prelude::FnArgs;
+use napi_derive::napi;
+use std::sync::{Mutex, OnceLock};
+
+/// Available tracing levels.  When tracing is set to a particular level,
+/// callers will be provided tracing at the given level and all lower levels.
+#[napi(string_enum)]
+pub enum TraceLevel {
+  None,
+  Fatal,
+  Error,
+  Warn,
+  Info,
+  Debug,
+  Trace,
+}
+
+impl From<TraceLevel> for git2::TraceLevel {
+  fn from(value: TraceLevel) -> Self {
+    match value {
+      TraceLevel::None => git2::TraceLevel::None,
+      TraceLevel::Fatal => git2::TraceLevel::Fatal,
+      TraceLevel::Error => git2::TraceLevel::Error,
+      TraceLevel::Warn => git2::TraceLevel::Warn,
+      TraceLevel::Info => git2::TraceLevel::Info,
+      TraceLevel::Debug => git2::TraceLevel::Debug,
+      TraceLevel::Trace => git2::TraceLevel::Trace,
+    }
+  }
+}
+
+impl From<git2::TraceLevel> for TraceLevel {
+  fn from(value: git2::TraceLevel) -> Self {
+    match value {
+      git2::TraceLevel::None => TraceLevel::None,
+      git2::TraceLevel::Fatal => TraceLevel::Fatal,
+      git2::TraceLevel::Error => TraceLevel::Error,
+      git2::TraceLevel::Warn => TraceLevel::Warn,
+      git2::TraceLevel::Info => TraceLevel::Info,
+      git2::TraceLevel::Debug => TraceLevel::Debug,
+      git2::TraceLevel::Trace => TraceLevel::Trace,
+    }
+  }
+}
+
+pub type TracingCallback = JsCallback<FnArgs<(TraceLevel, String)>>;
+
+#[allow(clippy::type_complexity)]
+static TRACING_CALLBACK: OnceLock<Mutex<Option<TracingCallback>>> = OnceLock::new();
+
+fn tracing_callback(level: git2::TraceLevel, msg: &[u8]) {
+  let Some(lock) = TRACING_CALLBACK.get() else { return };
+  let Ok(guard) = lock.lock() else { return };
+  let Some(callback) = guard.as_ref() else { return };
+  if let Ok(message) = std::str::from_utf8(msg) {
+    let _ = callback.invoke((level.into(), message.to_string()).into());
+  }
+}
+
+#[napi]
+/// Set the global subscriber called when libgit2 produces a tracing message.
+///
+/// @category Tracing
+/// @signature
+/// ```ts
+/// function traceSet(
+///   level: TraceLevel,
+///   callback: (level: TraceLevel, message: string) => void,
+/// ): void;
+/// ```
+///
+/// @param {TraceLevel} level - Level to set tracing to
+/// @param {(level: TraceLevel, message: string) => void} callback - Callback to call with trace data
+pub fn trace_set(
+  level: TraceLevel,
+  #[napi(ts_arg_type = "(level: TraceLevel, message: string) => void")] callback: TracingCallback,
+) -> crate::Result<()> {
+  let global = TRACING_CALLBACK.get_or_init(|| Mutex::new(None));
+  *global.lock().unwrap() = Some(callback);
+  git2::trace_set(level.into(), tracing_callback)?;
+  Ok(())
+}
+
+#[napi]
+/// Clear the global subscriber
+///
+/// @category Tracing
+/// @signature
+/// ```ts
+/// function traceClear(): void;
+/// ```
+pub fn trace_clear() {
+  if let Some(global) = TRACING_CALLBACK.get() {
+    *global.lock().unwrap() = None;
+  }
+}