feat: Add logging module with file rotation support (#252)

Introduces a new logging module for the SPV client with:
- Configurable log file rotation
- Active log file: `run.log` and rotated files: `dash-spv.YYYYMMDD_HHMMSS.log`
- Separate console and file output options
- CLI flags: `--log-level`, `--no-log-file`, `--print-to-console`, `--max-log-files`, `--log-url`

Author: xdustinface

dash-spv-ffi/FFI_API.md

@@ -1176,14 +1176,14 @@ dash_spv_ffi_enable_test_mode() -> ()
 #### `dash_spv_ffi_init_logging`
 
 ```c
-dash_spv_ffi_init_logging(level: *const c_char) -> i32
+dash_spv_ffi_init_logging(level: *const c_char, enable_console: bool, log_dir: *const c_char, max_files: usize,) -> i32
 ```
 
 **Description:**
-Initialize logging for the SPV library.  # Safety - `level` may be null or point to a valid, NUL-terminated C string. - If non-null, the pointer must remain valid for the duration of this call.
+Initialize logging for the SPV library.  # Arguments - `level`: Log level string (null uses RUST_LOG env var or defaults to INFO). Valid values: "error", "warn", "info", "debug", "trace" - `enable_console`: Whether to output logs to console (stderr) - `log_dir`: Directory for log files (null to disable file logging) - `max_files`: Maximum archived log files to retain (ignored if log_dir is null)  # Safety - `level` and `log_dir` may be null or point to valid, NUL-terminated C strings.
 
 **Safety:**
-- `level` may be null or point to a valid, NUL-terminated C string. - If non-null, the pointer must remain valid for the duration of this call.
+- `level` and `log_dir` may be null or point to valid, NUL-terminated C strings.
 
 **Module:** `utils`
 

dash-spv-ffi/README.md

@@ -47,7 +47,7 @@ See `examples/basic_usage.c` for a simple example of using the FFI bindings.
 #include "dash_spv_ffi.h"
 
 // Initialize logging
-dash_spv_ffi_init_logging("info");
+dash_spv_ffi_init_logging("info", true, NULL, 0);
 
 // Create configuration
 FFIClientConfig* config = dash_spv_ffi_config_testnet();

dash-spv-ffi/examples/basic_usage.c

@@ -4,7 +4,7 @@
 
 int main() {
     // Initialize logging
-    if (dash_spv_ffi_init_logging("info") != 0) {
+    if (dash_spv_ffi_init_logging("info", true, NULL, 0) != 0) {
         fprintf(stderr, "Failed to initialize logging\n");
         return 1;
     }

dash-spv-ffi/include/dash_spv_ffi.h

@@ -979,11 +979,22 @@ void dash_spv_ffi_unconfirmed_transaction_destroy_addresses(struct FFIString *ad
 /**
  * Initialize logging for the SPV library.
  *
+ * # Arguments
+ * - `level`: Log level string (null uses RUST_LOG env var or defaults to INFO).
+ *   Valid values: "error", "warn", "info", "debug", "trace"
+ * - `enable_console`: Whether to output logs to console (stderr)
+ * - `log_dir`: Directory for log files (null to disable file logging)
+ * - `max_files`: Maximum archived log files to retain (ignored if log_dir is null)
+ *
  * # Safety
- * - `level` may be null or point to a valid, NUL-terminated C string.
- * - If non-null, the pointer must remain valid for the duration of this call.
+ * - `level` and `log_dir` may be null or point to valid, NUL-terminated C strings.
  */
- int32_t dash_spv_ffi_init_logging(const char *level) ;
+
+int32_t dash_spv_ffi_init_logging(const char *level,
+                                  bool enable_console,
+                                  const char *log_dir,
+                                  uintptr_t max_files)
+;
 
  const char *dash_spv_ffi_version(void) ;
 

dash-spv-ffi/src/bin/ffi_cli.rs

@@ -121,7 +121,7 @@ fn main() {
         // Initialize tracing/logging via FFI so `tracing::info!` emits output
         let level = matches.get_one::<String>("log-level").map(String::as_str).unwrap_or("info");
         let level_c = CString::new(level).unwrap();
-        let _ = dash_spv_ffi_init_logging(level_c.as_ptr());
+        let _ = dash_spv_ffi_init_logging(level_c.as_ptr(), true, std::ptr::null(), 0);
 
         // Build config
         let cfg = dash_spv_ffi_config_new(network);

dash-spv-ffi/src/error.rs

@@ -60,6 +60,7 @@ impl From<SpvError> for FFIErrorCode {
             SpvError::Io(_) => FFIErrorCode::RuntimeError,
             SpvError::Config(_) => FFIErrorCode::ConfigError,
             SpvError::Parse(_) => FFIErrorCode::ValidationError,
+            SpvError::Logging(_) => FFIErrorCode::RuntimeError,
             SpvError::Wallet(_) => FFIErrorCode::WalletError,
             SpvError::QuorumLookupError(_) => FFIErrorCode::ValidationError,
             SpvError::General(_) => FFIErrorCode::Unknown,

dash-spv-ffi/src/utils.rs

@@ -1,28 +1,84 @@
-use crate::{set_last_error, FFIErrorCode};
 use std::ffi::CStr;
 use std::os::raw::c_char;
+use std::path::PathBuf;
+use std::sync::OnceLock;
+
+use crate::{set_last_error, FFIErrorCode};
+use dash_spv::{LogFileConfig, LoggingConfig};
+
+/// Static storage for the logging guard to keep it alive for the FFI lifetime.
+/// The guard must remain alive for log flushing to work correctly.
+static LOGGING_GUARD: OnceLock<dash_spv::LoggingGuard> = OnceLock::new();
 
 /// Initialize logging for the SPV library.
 ///
+/// # Arguments
+/// - `level`: Log level string (null uses RUST_LOG env var or defaults to INFO).
+///   Valid values: "error", "warn", "info", "debug", "trace"
+/// - `enable_console`: Whether to output logs to console (stderr)
+/// - `log_dir`: Directory for log files (null to disable file logging)
+/// - `max_files`: Maximum archived log files to retain (ignored if log_dir is null)
+///
 /// # Safety
-/// - `level` may be null or point to a valid, NUL-terminated C string.
-/// - If non-null, the pointer must remain valid for the duration of this call.
+/// - `level` and `log_dir` may be null or point to valid, NUL-terminated C strings.
 #[no_mangle]
-pub unsafe extern "C" fn dash_spv_ffi_init_logging(level: *const c_char) -> i32 {
-    let level_str = if level.is_null() {
-        "info"
+pub unsafe extern "C" fn dash_spv_ffi_init_logging(
+    level: *const c_char,
+    enable_console: bool,
+    log_dir: *const c_char,
+    max_files: usize,
+) -> i32 {
+    let level_filter = if level.is_null() {
+        None
     } else {
         match CStr::from_ptr(level).to_str() {
-            Ok(s) => s,
+            Ok(s) => match s.parse() {
+                Ok(lf) => Some(lf),
+                Err(_) => {
+                    set_last_error(&format!(
+                        "Invalid log level '{}'. Valid: error, warn, info, debug, trace",
+                        s
+                    ));
+                    return FFIErrorCode::InvalidArgument as i32;
+                }
+            },
             Err(e) => {
                 set_last_error(&format!("Invalid UTF-8 in log level: {}", e));
                 return FFIErrorCode::InvalidArgument as i32;
             }
         }
     };
 
-    match dash_spv::init_logging(level_str) {
-        Ok(()) => FFIErrorCode::Success as i32,
+    let file_config = if log_dir.is_null() {
+        None
+    } else {
+        match CStr::from_ptr(log_dir).to_str() {
+            Ok(s) => Some(LogFileConfig {
+                log_dir: PathBuf::from(s),
+                max_files,
+            }),
+            Err(e) => {
+                set_last_error(&format!("Invalid UTF-8 in log directory: {}", e));
+                return FFIErrorCode::InvalidArgument as i32;
+            }
+        }
+    };
+
+    let config = LoggingConfig {
+        level: level_filter,
+        console: enable_console,
+        file: file_config,
+    };
+
+    match dash_spv::init_logging(config) {
+        Ok(guard) => {
+            // Store guard in static to keep it alive for log flushing.
+            // OnceLock::set returns Err if already set (first init wins).
+            if LOGGING_GUARD.set(guard).is_err() {
+                tracing::warn!("Logging already initialized, ignoring subsequent init");
+            }
+            FFIErrorCode::Success as i32
+        }
         Err(e) => {
             set_last_error(&format!("Failed to initialize logging: {}", e));
             FFIErrorCode::RuntimeError as i32

dash-spv-ffi/tests/test_event_callbacks.rs

@@ -138,7 +138,7 @@ extern "C" fn test_balance_callback(confirmed: u64, unconfirmed: u64, user_data:
 fn test_event_callbacks_setup() {
     // Initialize logging
     unsafe {
-        dash_spv_ffi_init_logging(c"debug".as_ptr());
+        dash_spv_ffi_init_logging(c"debug".as_ptr(), true, std::ptr::null(), 0);
     }
 
     // Create test data
@@ -238,7 +238,7 @@ fn test_event_callbacks_setup() {
 #[serial]
 fn test_enhanced_event_callbacks() {
     unsafe {
-        dash_spv_ffi_init_logging(c"info".as_ptr());
+        dash_spv_ffi_init_logging(c"info".as_ptr(), true, std::ptr::null(), 0);
 
         // Create test data
         let event_data = TestEventData::new();

dash-spv-ffi/tests/test_utils.rs

@@ -11,15 +11,15 @@ mod tests {
     fn test_init_logging() {
         unsafe {
             let level = CString::new("debug").unwrap();
-            let result = dash_spv_ffi_init_logging(level.as_ptr());
+            let result = dash_spv_ffi_init_logging(level.as_ptr(), true, std::ptr::null(), 0);
             // May fail if already initialized, but should handle gracefully
             assert!(
                 result == FFIErrorCode::Success as i32
                     || result == FFIErrorCode::RuntimeError as i32
             );
 
-            // Test with null pointer (should use default)
-            let result = dash_spv_ffi_init_logging(std::ptr::null());
+            // Test with null level pointer (should use RUST_LOG or default to INFO)
+            let result = dash_spv_ffi_init_logging(std::ptr::null(), true, std::ptr::null(), 0);
             assert!(
                 result == FFIErrorCode::Success as i32
                     || result == FFIErrorCode::RuntimeError as i32

dash-spv/Cargo.toml

@@ -19,7 +19,7 @@ key-wallet-manager = { path = "../key-wallet-manager" }
 blsful = { git = "https://github.com/dashpay/agora-blsful", rev = "0c34a7a488a0bd1c9a9a2196e793b303ad35c900" }
 
 # CLI
-clap = { version = "4.0", features = ["derive"] }
+clap = { version = "4.0", features = ["derive", "env"] }
 
 # Async runtime
 tokio = { version = "1.0", features = ["full"] }
@@ -37,7 +37,9 @@ bincode = "1.3"
 
 # Logging
 tracing = "0.1"
-tracing-subscriber = "0.3"
+tracing-subscriber = { version = "0.3.20", features = ["env-filter"] }
+tracing-appender = "0.2"
+chrono = "0.4.20"
 
 # Utilities
 rand = "0.8"