falco_plugin/plugin/async_event/
mod.rs

1use crate::base::Plugin;
2use crate::event::AsyncEvent;
3use crate::plugin::async_event::async_handler::AsyncHandler;
4use crate::plugin::async_event::wrappers::AsyncPluginExported;
5use falco_event::events::Event;
6
7pub mod async_handler;
8pub mod background_task;
9#[doc(hidden)]
10pub mod wrappers;
11
12/// Support for asynchronous event plugins
13pub trait AsyncEventPlugin: Plugin + AsyncPluginExported {
14    /// # Event names coming from this plugin
15    ///
16    /// This constant contains a list describing the name list of all asynchronous events
17    /// that this plugin is capable of pushing into a live event stream. The framework rejects
18    /// async events produced by a plugin if their name is not on the name list returned by this
19    /// function.
20    const ASYNC_EVENTS: &'static [&'static str];
21    /// # Event sources to attach asynchronous events to
22    ///
23    /// This constant contains a list describing the event sources for which this plugin
24    /// is capable of injecting async events in the event stream of a capture.
25    ///
26    /// This is optional--if NULL or an empty array, then async events produced by this plugin will
27    /// be injected in the event stream of any data source.
28    ///
29    /// **Note**: one notable event source is called `syscall`
30    const EVENT_SOURCES: &'static [&'static str];
31
32    /// # Start asynchronous event generation
33    ///
34    /// When this method is called, your plugin should start whatever background mechanism
35    /// is necessary (e.g. spawn a separate thread) and use the [`AsyncHandler::emit`] method
36    /// to inject events to the main event loop.
37    ///
38    /// **Note**: you must provide a mechanism to shut down the thread upon a call to [`AsyncEventPlugin::stop_async`].
39    /// This may involve e.g. a [`std::sync::Condvar`] that's checked via [`std::sync::Condvar::wait_timeout`]
40    /// by the thread.
41    ///
42    /// **Note**: one notable event source is called `syscall`
43    fn start_async(&mut self, handler: AsyncHandler) -> Result<(), anyhow::Error>;
44
45    /// # Stop asynchronous event generation
46    ///
47    /// When this method is called, your plugin must stop the background mechanism started by
48    /// [`AsyncEventPlugin::start_async`] and wait for it to finish (no calls to [`AsyncHandler::emit`]
49    /// are permitted after this method returns).
50    ///
51    /// **Note**: [`AsyncEventPlugin::start_async`] can be called again, with a different [`AsyncHandler`].
52    fn stop_async(&mut self) -> Result<(), anyhow::Error>;
53
54    /// # Dump the plugin state as a series of async events
55    ///
56    /// When this method is called, your plugin may save its state via a series of async events
57    /// that will be replayed when a capture file is loaded.
58    ///
59    /// The default implementation does nothing.
60    fn dump_state(&mut self, _handler: AsyncHandler) -> Result<(), anyhow::Error> {
61        Ok(())
62    }
63
64    /// # A helper method to create an asynchronous event
65    fn async_event<'a>(
66        name: &'a std::ffi::CStr,
67        data: &'a [u8],
68    ) -> Event<AsyncEvent<'a, &'a [u8]>> {
69        let event = AsyncEvent {
70            plugin_id: 0, // gets populated by the framework, shall be None
71            name,
72            data,
73        };
74
75        let metadata = falco_event::events::EventMetadata::default();
76
77        Event {
78            metadata,
79            params: event,
80        }
81    }
82}
falco_plugin/plugin/async_event/mod.rs

falco_plugin/plugin/async_event/
mod.rs
