0.1.0-0-pre.4

crates/common/game-logging-lib/Cargo.toml

@@ -0,0 +1,19 @@
+# file: crates/common/game-logging-lib/Cargo.toml
+# version: 1
+
+[package]
+name = "game-logging-lib"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+repository.workspace = true
+authors.workspace = true
+publish.workspace = true
+
+[dependencies]
+tracing.workspace = true
+tracing-appender.workspace = true
+tracing-subscriber.workspace = true
+
+[lints]
+workspace = true

crates/common/game-logging-lib/src/lib.rs

@@ -0,0 +1,20 @@
+// file: crates/common/game-logging-lib/src/lib.rs
+// version: 1
+
+#![warn(missing_docs)]
+#![deny(unreachable_pub)]
+#![forbid(unsafe_code)]
+
+//! Shared tracing initialization and test diagnostics for games.sasedev applications and crates.
+
+mod runtime;
+mod test_support;
+
+/// Re-export of the console tracing initialization error.
+pub use self::runtime::LoggingInitError;
+/// Re-export of the guard keeping the non-blocking tracing writer alive.
+pub use self::runtime::LoggingWorkerGuard;
+/// Re-export of the standard console tracing initializer.
+pub use self::runtime::init_console_tracing;
+/// Re-export of the scoped tracing helper intended for tests.
+pub use self::test_support::with_test_tracing;

crates/common/game-logging-lib/src/runtime.rs

@@ -0,0 +1,31 @@
+// file: crates/common/game-logging-lib/src/runtime.rs
+// version: 1
+
+/// Error returned when the process-global tracing subscriber is already configured.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub struct LoggingInitError;
+
+impl std::fmt::Display for LoggingInitError {
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        return formatter.write_str("the process-global tracing subscriber is already configured");
+    }
+}
+
+impl std::error::Error for LoggingInitError {}
+
+/// Guard keeping the non-blocking tracing writer alive for the application lifetime.
+pub struct LoggingWorkerGuard {
+    _worker_guard: tracing_appender::non_blocking::WorkerGuard,
+}
+
+/// Initializes a process-global non-blocking tracing subscriber writing formatted events to standard error.
+///
+/// The returned guard must remain alive for as long as events may still be emitted.
+pub fn init_console_tracing() -> std::result::Result<LoggingWorkerGuard, LoggingInitError> {
+    let (writer, worker_guard) = tracing_appender::non_blocking(std::io::stderr());
+    let subscriber = tracing_subscriber::fmt().with_target(true).with_writer(writer).finish();
+    if tracing::subscriber::set_global_default(subscriber).is_err() {
+        return std::result::Result::Err(LoggingInitError);
+    }
+    return std::result::Result::Ok(LoggingWorkerGuard { _worker_guard: worker_guard });
+}

crates/common/game-logging-lib/src/test_support.rs

@@ -0,0 +1,13 @@
+// file: crates/common/game-logging-lib/src/test_support.rs
+// version: 1
+
+/// Executes one test body with a thread-local tracing subscriber configured for the Rust test writer.
+pub fn with_test_tracing<T>(test_name: &str, operation: impl FnOnce() -> T) -> T {
+    let subscriber = tracing_subscriber::fmt().with_target(true).with_test_writer().without_time().finish();
+    return tracing::subscriber::with_default(subscriber, || {
+        tracing::debug!(test_name = test_name, "test started");
+        let result = operation();
+        tracing::debug!(test_name = test_name, "test completed");
+        return result;
+    });
+}

crates/common/game-logging-lib/tests/test_support.rs

@@ -0,0 +1,11 @@
+// file: crates/common/game-logging-lib/tests/test_support.rs
+// version: 1
+
+#[test]
+fn scoped_test_tracing_returns_test_result() {
+    let result = game_logging_lib::with_test_tracing("scoped_test_tracing_returns_test_result", || {
+        tracing::info!(value = 41_u32, "integration test event");
+        return 42_u32;
+    });
+    assert_eq!(result, 42_u32);
+}