logwise 0.3.0

//SPDX-License-Identifier: MIT OR Apache-2.0
//! Context management for logwise.
//!
//! This module provides a lightweight, hierarchical, thread‑local context system used
//! by logwise to add structure to logs without requiring explicit parameters on every call.
//! A Context represents a logical task and any nested work. Contexts form a parent→child
//! chain that is used to:
//!
//! - Prefix logs with task identity and nesting level
//! - Track performance intervals per task (emitted as `perfwarn` on task drop)
//! - Opt‑in per‑thread tracing via `begin_trace`/`currently_tracing`
//! - Propagate context across executors via `ApplyContext<F>`
//!
//! The root context for a thread is created automatically as a "Default task". You can
//! create new tasks with `Context::new_task` and nest additional contexts with
//! `Context::from_parent` while keeping the same task.
//!
//! Basic usage
//!
//! ```rust
//! use logwise::context::Context;
//! logwise::declare_logging_domain!();
//! fn main() {
//!     // Start a new top‑level task and make it current for this thread
//!     let task = Context::new_task(None, "import_job".to_string());
//!     task.clone().set_current();
//! 
//!     // Produce some logs
//!     logwise::info_sync!("Starting import");
//! 
//!     // Create a nested context that preserves the same task
//!     let child = Context::from_parent(Context::current());
//!     child.clone().set_current();
//!     logwise::debuginternal_sync!("Parsing file");
//! 
//!     // Pop the child when finished
//!     logwise::context::Context::pop(child.context_id());
//! }
//! ```
//!
//! Tracing
//!
//! ```rust
//! # use logwise::context::Context;
//! // Opt‑in to verbose per‑thread tracing
//! Context::begin_trace();
//! if Context::currently_tracing() {
//!     logwise::trace_sync!("heavy detail");
//! }
//! ```
//!
//! Async executors and hostile runtimes
//!
//! Many executors poll futures on worker threads lacking your thread‑local context. Wrap a
//! future with `ApplyContext` to temporarily install a context during each poll:
//!
//! ```no_run
//! # use logwise::context::{Context, ApplyContext};
//! # async fn do_work() {}
//! let ctx = Context::new_task(None, "download".to_string());
//! let fut = ApplyContext::new(ctx, do_work());
//! // spawn `fut` on your executor; logs inside will use the applied context
//! # let _ = fut; // silence unused warning in doctest
//! ```
//!
//! Display and debugging
//!
//! `Context` implements `Display` to show nesting and task information. You can also obtain
//! a `&Task` via `AsRef<Task>` for advanced integrations like custom formatting.
//!
//! Privacy note: Refer to `logwise::privacy` when logging sensitive values; the context system
//! itself does not alter data redaction.
use crate::Level;
use std::cell::Cell;
use std::collections::HashMap;
use std::fmt::Display;
use std::future::Future;
use std::hash::{Hash, Hasher};
use std::pin::Pin;
use std::sync::atomic::{AtomicBool, AtomicU64, Ordering};
use std::sync::{Arc, Mutex};
use std::task::Poll;

static TASK_ID: AtomicU64 = AtomicU64::new(0);

static CONTEXT_ID: AtomicU64 = AtomicU64::new(0);

/// Unique identifier for a logical task.
///
/// A task groups related logs together across a hierarchy of contexts. The ID is stable
/// for the lifetime of the task and is included in log prefixes.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct TaskID(u64);
impl Display for TaskID {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "{}", self.0)
    }
}

/// Identifier for a specific context instance in the parent→child chain.
///
/// Use with [`Context::pop`] to unwind to a prior context.
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct ContextID(u64);

impl Task {
    #[inline]
    fn add_task_interval(&self, key: &'static str, duration: crate::sys::Duration) {
        let mut borrow = self.mutable.lock().unwrap();
        borrow
            .interval_statistics
            .get_mut(key)
            .map(|v| *v += duration)
            .unwrap_or_else(|| {
                borrow.interval_statistics.insert(key, duration);
            });
    }
}

impl Drop for Task {
    fn drop(&mut self) {
        if !self.mutable.lock().unwrap().interval_statistics.is_empty() {
            let mut record = crate::log_record::LogRecord::new(Level::PerfWarn);
            //log task ID
            record.log_owned(format!("{} ", self.task_id.0));
            record.log("PERFWARN: statistics[");
            for (key, duration) in &self.mutable.lock().unwrap().interval_statistics {
                record.log(key);
                record.log_owned(format!(": {:?},", duration));
            }
            record.log("]");
            let global_loggers = crate::global_logger::global_loggers();
            for logger in global_loggers {
                logger.finish_log_record(record.clone());
            }
        }

        if self.label != "Default task" {
            let mut record = crate::log_record::LogRecord::new(Level::Info);
            record.log_owned(format!("{} ", self.task_id.0));
            record.log("Finished task `");
            record.log(&self.label);
            record.log("`");
            let global_loggers = crate::global_logger::global_loggers();
            for logger in global_loggers {
                logger.finish_log_record(record.clone());
            }
        }
    }
}
#[derive(Clone, Debug)]
struct TaskMutable {
    interval_statistics: HashMap<&'static str, crate::sys::Duration>,
}
/// Represents the current logical task for a context chain.
///
/// Tasks are created by [`Context::new_task`] and are automatically logged when dropped:
/// - Accumulated performance intervals are emitted as a `perfwarn` record.
/// - A finishing `info` record is emitted for non‑default tasks.
#[derive(Debug)]
pub struct Task {
    task_id: TaskID,
    mutable: Mutex<TaskMutable>,
    label: String,
}

impl Task {
    fn new(label: String) -> Task {
        Task {
            task_id: TaskID(TASK_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed)),
            mutable: Mutex::new(TaskMutable {
                interval_statistics: HashMap::new(),
            }),
            label,
        }
    }
}

/**
Internal context data.
*/
#[derive(Debug)]
struct ContextInner {
    parent: Option<Context>,
    context_id: u64,
    //if some, we define a new task ID for this context.
    define_task: Option<Task>,
    ///whether this context is currently tracing
    is_tracing: AtomicBool,
}

/// A thread‑local, hierarchical context used to prefix and correlate logs.
///
/// New contexts can either create a new task (`new_task`) or inherit the task from a parent
/// (`from_parent`). The current thread's active context is retrieved with [`Context::current`]
/// and changed with [`Context::set_current`].
///
/// See the module‑level documentation for usage examples.
#[derive(Debug, Clone)]
pub struct Context {
    inner: Arc<ContextInner>,
}

impl PartialEq for Context {
    fn eq(&self, other: &Self) -> bool {
        Arc::ptr_eq(&self.inner, &other.inner)
    }
}

impl Eq for Context {}

impl Hash for Context {
    fn hash<H: Hasher>(&self, state: &mut H) {
        Arc::as_ptr(&self.inner).hash(state);
    }
}

impl Display for Context {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let nesting = self.nesting_level();
        write!(
            f,
            "{}{} ({})",
            "  ".repeat(nesting),
            self.task_id(),
            self.task().label
        )
    }
}

impl AsRef<Task> for Context {
    fn as_ref(&self) -> &Task {
        self.task()
    }
}

thread_local! {
    static CONTEXT: Cell<Context> = Cell::new(Context::new_task_internal(None,"Default task".to_string(),0));
}

impl Context {
    /// Returns the current thread‑local context.
    ///
    /// Examples
    ///
    /// ```
    /// # use logwise::context::Context;
    /// Context::reset("example".to_string());
    /// let c = Context::current();
    /// let _task_id = c.task_id();
    /// ```
    #[inline]
    pub fn current() -> Context {
        CONTEXT.with(|c|
            //safety: we don't let anyone get a mutable reference to this
            unsafe{&*c.as_ptr()}.clone())
    }

    /// Returns the task associated with this context chain.
    ///
    /// The returned reference remains valid for the lifetime of the task. All contexts created
    /// with [`from_parent`](Context::from_parent) share the same task as their parent.
    pub fn task(&self) -> &Task {
        if let Some(task) = &self.inner.define_task {
            task
        } else {
            self.inner
                .parent
                .as_ref()
                .expect("No parent context")
                .task()
        }
    }

    /// Creates a new context that defines a new task.
    ///
    /// - `parent`: Optional parent context to establish nesting (for indentation).
    /// - `label`: A human‑readable task label included in finishing logs and `Display`.
    ///
    /// Returns a context that owns a new [`Task`] and task ID. Make it current with
    /// [`Context::set_current`].
    ///
    /// ```
    /// # use logwise::context::Context;
    /// let c = Context::new_task(None, "thumbnail_job".to_string());
    /// c.clone().set_current();
    /// logwise::info_sync!("Generating thumbnails");
    /// ```
    #[inline]
    pub fn new_task(parent: Option<Context>, label: String) -> Context {
        let context_id = CONTEXT_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
        Self::new_task_internal(parent, label, context_id)
    }
    #[inline]
    fn new_task_internal(parent: Option<Context>, label: String, context_id: u64) -> Context {
        Context {
            inner: Arc::new(ContextInner {
                parent,
                context_id,
                define_task: Some(Task::new(label)),
                is_tracing: AtomicBool::new(false),
            }),
        }
    }

    /// Replaces the current thread‑local context with a new top‑level task.
    ///
    /// Convenience for `Context::new_task(None, label).set_current()`.
    #[inline]
    pub fn reset(label: String) {
        let new_context = Context::new_task(None, label);
        new_context.set_current();
    }

    /// Creates a new context that inherits the parent's task.
    ///
    /// Useful to represent nested work while maintaining the same task identity.
    ///
    /// ```
    /// # use logwise::context::Context;
    /// logwise::declare_logging_domain!();
    /// fn main() {
    ///     Context::reset("build".to_string());
    ///     let parent = Context::current();
    ///     let child = Context::from_parent(parent);
    ///     child.clone().set_current();
    ///     logwise::debuginternal_sync!("compile crate");
    /// }
    /// ```
    pub fn from_parent(context: Context) -> Context {
        let is_tracing = context.inner.is_tracing.load(Ordering::Relaxed);
        Context {
            inner: Arc::new(ContextInner {
                parent: Some(context),
                context_id: CONTEXT_ID.fetch_add(1, std::sync::atomic::Ordering::Relaxed),
                define_task: None,
                is_tracing: AtomicBool::new(is_tracing),
            }),
        }
    }

    #[inline]
    /// Returns the [`TaskID`] for this context's task.
    pub fn task_id(&self) -> TaskID {
        self.task().task_id
    }

    /// Returns true if this context is currently tracing.
    #[inline]
    pub fn is_tracing(&self) -> bool {
        self.inner.is_tracing.load(Ordering::Relaxed)
    }

    /// Returns true if the thread‑local current context has tracing enabled.
    #[inline]
    pub fn currently_tracing() -> bool {
        CONTEXT.with(|c| {
            //safety: we don't let anyone get a mutable reference to this
            unsafe { &*c.as_ptr() }
                .inner
                .is_tracing
                .load(Ordering::Relaxed)
        })
    }

    /// Enables tracing for the current thread‑local context and emits a "Begin trace" record.
    ///
    /// Tracing affects `trace_*` macros; they only produce output when tracing is enabled.
    pub fn begin_trace() {
        Context::current()
            .inner
            .is_tracing
            .store(true, Ordering::Relaxed);
        logwise::trace_sync!("Begin trace");
    }

    /// Makes this context the current thread‑local context.
    pub fn set_current(self) {
        CONTEXT.replace(self);
    }

    /// Returns the number of parent contexts above this one.
    pub fn nesting_level(&self) -> usize {
        let mut level = 0;
        let mut current = self;
        while let Some(parent) = &current.inner.parent {
            level += 1;
            current = parent;
        }
        level
    }

    /// Returns the identifier for this specific context node.
    #[inline]
    pub fn context_id(&self) -> ContextID {
        ContextID(self.inner.context_id)
    }

    /// Restores the current context to the parent of the context with the given ID.
    ///
    /// If the ID is not found in the current context chain, a `warn` record is emitted and
    /// the current context is left unchanged.
    ///
    /// ```
    /// # use logwise::context::Context;
    /// Context::reset("example".to_string());
    /// let child = Context::from_parent(Context::current());
    /// let id = child.context_id();
    /// child.set_current();
    /// Context::pop(id);
    /// ```
    pub fn pop(id: ContextID) {
        let mut current = Context::current();
        loop {
            if current.context_id() == id {
                let parent = current.inner.parent.clone().expect("No parent context");
                CONTEXT.replace(parent);
                return;
            }
            match current.inner.parent.as_ref() {
                None => {
                    logwise::warn_sync!(
                        "Tried to pop context with ID {id}, but it was not found in the current context chain.",
                        id = id.0
                    );
                    return;
                }
                Some(ctx) => current = ctx.clone(),
            }
        }
    }

    /// Internal: writes standard context prefix into a record.
    ///
    /// Not intended for external use.
    #[doc(hidden)]
    #[inline]
    pub fn _log_prelude(&self, record: &mut crate::log_record::LogRecord) {
        let prefix = if self.is_tracing() { "T" } else { " " };
        record.log(prefix);
        for _ in 0..self.nesting_level() {
            record.log(" ");
        }
        record.log_owned(format!("{} ", self.task_id()));
    }

    /// Internal: accumulate a perf interval on the current task.
    ///
    /// Not intended for external use.
    #[doc(hidden)]
    #[inline]
    pub fn _add_task_interval(&self, key: &'static str, duration: crate::sys::Duration) {
        self.task().add_task_interval(key, duration);
    }
}

/// A future wrapper that temporarily applies a context during each poll.
///
/// Use this when running on an executor that may poll your future on a worker thread without
/// your thread‑local context. The wrapper sets the provided context before polling and restores
/// the prior context afterwards.
///
/// ```no_run
/// # use logwise::context::{Context, ApplyContext};
/// # async fn work() {}
/// let ctx = Context::new_task(None, "download".to_string());
/// let fut = ApplyContext::new(ctx, work());
/// // spawn/await `fut` on your async runtime
/// # let _ = fut;
/// ```
pub struct ApplyContext<F>(Context, F);

impl<F> ApplyContext<F> {
    /// Creates a new wrapper with the context to apply and the future to poll.
    pub fn new(context: Context, f: F) -> Self {
        Self(context, f)
    }
}

impl<F> Future for ApplyContext<F>
where
    F: Future,
{
    type Output = F::Output;

    fn poll(self: Pin<&mut Self>, cx: &mut std::task::Context<'_>) -> Poll<Self::Output> {
        let (context, fut) = unsafe {
            let d = self.get_unchecked_mut();
            (d.0.clone(), Pin::new_unchecked(&mut d.1))
        };
        let prior_context = Context::current();
        context.set_current();
        let r = fut.poll(cx);
        prior_context.set_current();
        r
    }
}

#[cfg(test)]
mod tests {
    use super::{Context, Task, TaskID};
    #[cfg(target_arch = "wasm32")]
    use wasm_bindgen_test::*;
    #[cfg(target_arch = "wasm32")]
    wasm_bindgen_test::wasm_bindgen_test_configure!(run_in_browser);

    #[cfg_attr(not(target_arch = "wasm32"), test)]
    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
    fn test_new_context() {
        Context::reset("test_new_context".to_string());
        let port_context = Context::current();
        let next_context = Context::from_parent(port_context);
        let next_context_id = next_context.context_id();
        next_context.set_current();

        Context::pop(next_context_id);
    }

    #[cfg_attr(not(target_arch = "wasm32"), test)]
    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
    fn test_context_equality() {
        Context::reset("test_context_equality".to_string());
        let context1 = Context::current();
        let context2 = context1.clone();
        let context3 = Context::new_task(None, "different_task".to_string());

        // Same Arc pointer should be equal
        assert_eq!(context1, context2);

        // Different Arc pointers should not be equal
        assert_ne!(context1, context3);
        assert_ne!(context2, context3);
    }

    #[cfg_attr(not(target_arch = "wasm32"), test)]
    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
    fn test_context_hash() {
        use std::collections::HashMap;
        use std::collections::hash_map::DefaultHasher;
        use std::hash::{Hash, Hasher};

        Context::reset("test_context_hash".to_string());
        let context1 = Context::current();
        let context2 = context1.clone();
        let context3 = Context::new_task(None, "different_task".to_string());

        // Same Arc pointer should have same hash
        let mut hasher1 = DefaultHasher::new();
        let mut hasher2 = DefaultHasher::new();
        context1.hash(&mut hasher1);
        context2.hash(&mut hasher2);
        assert_eq!(hasher1.finish(), hasher2.finish());

        // Different Arc pointers should have different hashes (highly likely)
        let mut hasher3 = DefaultHasher::new();
        context3.hash(&mut hasher3);
        assert_ne!(hasher1.finish(), hasher3.finish());

        // Test that Context can be used as HashMap key
        let mut map = HashMap::new();
        map.insert(context1.clone(), "value1");
        map.insert(context3.clone(), "value3");

        assert_eq!(map.get(&context1), Some(&"value1"));
        assert_eq!(map.get(&context2), Some(&"value1")); // same as context1
        assert_eq!(map.get(&context3), Some(&"value3"));
        assert_eq!(map.len(), 2); // only 2 unique contexts
    }

    #[cfg_attr(not(target_arch = "wasm32"), test)]
    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
    fn test_context_display() {
        Context::reset("root_task".to_string());
        let root_context = Context::current();

        // Root context should have no indentation (nesting level 0)
        let root_display = format!("{}", root_context);
        assert!(root_display.starts_with(&format!("{} (root_task)", root_context.task_id())));
        assert!(!root_display.starts_with("  ")); // no indentation

        // Create a child context
        let child_context = Context::from_parent(root_context.clone());
        child_context.clone().set_current();
        let child_display = format!("{}", child_context);

        // Child should have 1 level of indentation
        assert!(child_display.starts_with("  ")); // 2 spaces for nesting level 1
        assert!(child_display.contains(&format!("{} (root_task)", root_context.task_id())));

        // Create a new task context as child
        let task_context = Context::new_task(Some(child_context.clone()), "child_task".to_string());
        task_context.clone().set_current();
        let task_display = format!("{}", task_context);

        // Task context should have 2 levels of indentation
        assert!(task_display.starts_with("    ")); // 4 spaces for nesting level 2
        assert!(task_display.contains(&format!("{} (child_task)", task_context.task_id())));

        // Create grandchild
        let grandchild_context = Context::from_parent(task_context.clone());
        grandchild_context.clone().set_current();
        let grandchild_display = format!("{}", grandchild_context);

        // Grandchild should have 3 levels of indentation
        assert!(grandchild_display.starts_with("      ")); // 6 spaces for nesting level 3
        assert!(grandchild_display.contains(&format!("{} (child_task)", task_context.task_id())));
    }

    #[cfg_attr(not(target_arch = "wasm32"), test)]
    #[cfg_attr(target_arch = "wasm32", wasm_bindgen_test)]
    fn test_context_as_ref_task() {
        Context::reset("test_as_ref".to_string());
        let context = Context::current();

        // Test that AsRef<Task> works
        let task_ref: &Task = context.as_ref();
        assert_eq!(task_ref.task_id, context.task_id());
        assert_eq!(task_ref.label, "test_as_ref");

        // Test that we can use Context where &Task is expected
        fn takes_task_ref(task: &Task) -> TaskID {
            task.task_id
        }

        // Test explicit AsRef usage
        let id1 = takes_task_ref(context.as_ref());
        assert_eq!(id1, context.task_id());

        // Test with generic function that accepts AsRef<Task>
        fn takes_as_ref_task<T: AsRef<Task>>(item: T) -> TaskID {
            item.as_ref().task_id
        }

        let id2 = takes_as_ref_task(&context);
        let id3 = takes_as_ref_task(context.clone());
        assert_eq!(id1, id2);
        assert_eq!(id2, id3);

        // Test with different context types
        let child_context = Context::from_parent(context.clone());
        let child_task_ref: &Task = child_context.as_ref();

        // Child should have same task as parent (since from_parent preserves task)
        assert_eq!(child_task_ref.task_id, context.task_id());
        assert_eq!(child_task_ref.label, "test_as_ref");

        let new_task_context = Context::new_task(Some(context.clone()), "new_task".to_string());
        let new_task_ref: &Task = new_task_context.as_ref();

        // New task should have different ID and label
        assert_ne!(new_task_ref.task_id, context.task_id());
        assert_eq!(new_task_ref.label, "new_task");
    }
}