pulsehive_core/
export.rs

1//! Event export trait for streaming HiveEvents to external observability systems.
2//!
3//! [`EventExporter`] enables PulseHive to forward events to tools like PulseVision
4//! for real-time visualization. Implementations handle the wire protocol (WebSocket,
5//! HTTP, file, etc.); the SDK calls `export()` on each event emission.
6//!
7//! # Example
8//! ```rust,ignore
9//! use pulsehive_core::export::EventExporter;
10//! use pulsehive_core::event::HiveEvent;
11//!
12//! struct FileExporter { path: PathBuf }
13//!
14//! #[async_trait]
15//! impl EventExporter for FileExporter {
16//!     async fn export(&self, event: &HiveEvent) {
17//!         let json = serde_json::to_string(event).unwrap();
18//!         tokio::fs::write(&self.path, json).await.ok();
19//!     }
20//!     async fn flush(&self) {}
21//! }
22//! ```
23
24use async_trait::async_trait;
25
26use crate::event::HiveEvent;
27
28/// Trait for exporting HiveEvents to external observability systems.
29///
30/// When registered with `HiveMindBuilder::event_exporter()`, the exporter
31/// receives every event emitted by the agent runtime. Export is fire-and-forget —
32/// errors are logged but don't block agent execution.
33///
34/// Must be `Send + Sync` for use across Tokio tasks.
35#[async_trait]
36pub trait EventExporter: Send + Sync {
37    /// Export a single event. Called for every HiveEvent emission.
38    ///
39    /// Implementations should be non-blocking. For network transports,
40    /// consider buffering and batch-sending.
41    async fn export(&self, event: &HiveEvent);
42
43    /// Flush any buffered events. Called on HiveMind shutdown.
44    async fn flush(&self);
45}
46
47#[cfg(test)]
48mod tests {
49    use super::*;
50    use std::sync::Arc;
51
52    #[test]
53    fn test_event_exporter_is_object_safe() {
54        fn _assert_object_safe(_: &dyn EventExporter) {}
55        fn _assert_arcable(_: Arc<dyn EventExporter>) {}
56    }
57}
pulsehive_core/export.rs

pulsehive_core/
export.rs
