canarytrap 0.2.0

Rust-native canary tokens and honeytokens for early detection of suspicious access to secrets and configuration.
Documentation
//! Callback-based sink.
//!
//! Provides [`CallbackSink`], a [`Sink`] that invokes a user-provided
//! closure on each canary event.

use super::Sink;
use crate::CanaryEvent;
use core::fmt;

/// A [`Sink`] that calls a user-provided callback.
///
/// # Example
///
/// ```
/// use std::sync::atomic::{AtomicUsize, Ordering};
/// use std::sync::Arc;
///
/// use canarytrap::{CallbackSink, CanaryEvent, CanaryKind, CanaryToken, TriggerSource};
///
/// let count = Arc::new(AtomicUsize::new(0));
/// let counter = count.clone();
///
/// let sink = CallbackSink::new(move |event: &CanaryEvent| {
///     counter.fetch_add(1, Ordering::SeqCst);
///     assert_eq!(event.source, TriggerSource::Reveal);
/// });
///
/// let token = CanaryToken::new("prod.db.password", CanaryKind::Password, "fake")
///     .with_sink(sink);
///
/// token.reveal();
///
/// assert_eq!(count.load(Ordering::SeqCst), 1);
/// ```
pub struct CallbackSink {
    callback: Box<dyn Fn(&CanaryEvent) + Send + Sync + 'static>,
}

impl CallbackSink {
    /// Creates a new callback sink from a closure or function pointer.
    ///
    /// # Example
    ///
    /// ```
    /// use canarytrap::{CallbackSink, CanaryEvent};
    ///
    /// let sink = CallbackSink::new(|_event: &CanaryEvent| {});
    /// ```
    #[must_use]
    pub fn new(callback: impl Fn(&CanaryEvent) + Send + Sync + 'static) -> Self {
        Self {
            callback: Box::new(callback),
        }
    }
}

impl Sink for CallbackSink {
    fn emit(&self, event: &CanaryEvent) {
        (self.callback)(event);
    }
}

impl fmt::Debug for CallbackSink {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("CallbackSink").finish_non_exhaustive()
    }
}

impl<F> From<F> for CallbackSink
where
    F: Fn(&CanaryEvent) + Send + Sync + 'static,
{
    fn from(callback: F) -> Self {
        Self::new(callback)
    }
}

#[cfg(test)]
mod tests {
    use super::CallbackSink;
    use super::Sink;
    use crate::{CanaryEvent, CanaryKind, TriggerSource};
    use std::sync::atomic::{AtomicUsize, Ordering};
    use std::sync::{Arc, Mutex};
    use std::time::SystemTime;

    fn sample_event() -> CanaryEvent {
        CanaryEvent::new(
            "id-1",
            "prod.db.password",
            CanaryKind::Password,
            TriggerSource::Reveal,
        )
        .with_triggered_at(SystemTime::UNIX_EPOCH)
    }

    #[test]
    fn callback_sink_calls_callback() {
        let count = Arc::new(AtomicUsize::new(0));
        let counter = count.clone();

        let sink = CallbackSink::new(move |_event| {
            counter.fetch_add(1, Ordering::SeqCst);
        });

        sink.emit(&sample_event());

        assert_eq!(count.load(Ordering::SeqCst), 1);
    }

    #[test]
    fn callback_sink_receives_event_metadata() {
        let events = Arc::new(Mutex::new(Vec::new()));
        let events_clone = events.clone();

        let sink = CallbackSink::new(move |event: &CanaryEvent| {
            events_clone
                .lock()
                .expect("events mutex poisoned")
                .push(event.clone());
        });

        sink.emit(&sample_event());

        let events = events.lock().expect("events mutex poisoned");
        assert_eq!(events.len(), 1);

        let event = &events[0];
        assert_eq!(event.token_id, "id-1");
        assert_eq!(event.token_name, "prod.db.password");
        assert_eq!(event.kind, CanaryKind::Password);
        assert_eq!(event.source, TriggerSource::Reveal);
    }

    #[test]
    fn callback_sink_debug_does_not_contain_value() {
        let sink = CallbackSink::new(|_event| {});
        let debug = format!("{sink:?}");
        assert!(debug.contains("CallbackSink"));
    }

    #[test]
    fn callback_sink_can_be_created_from_closure() {
        let count = Arc::new(AtomicUsize::new(0));
        let counter = count.clone();

        let sink = CallbackSink::from(move |_event: &CanaryEvent| {
            counter.fetch_add(1, Ordering::SeqCst);
        });

        sink.emit(&sample_event());

        assert_eq!(count.load(Ordering::SeqCst), 1);
    }

    #[test]
    fn callback_sink_is_send_and_sync() {
        fn assert_send_sync<T: Send + Sync>() {}
        assert_send_sync::<CallbackSink>();
    }

    #[test]
    fn sink_trait_object_can_be_used() {
        let count = Arc::new(AtomicUsize::new(0));
        let counter = count.clone();

        let sink: Box<dyn Sink> = Box::new(CallbackSink::new(move |_event| {
            counter.fetch_add(1, Ordering::SeqCst);
        }));

        sink.emit(&sample_event());

        assert_eq!(count.load(Ordering::SeqCst), 1);
    }
}