falco_event/
lib.rs

1#![doc = include_str!("../README.md")]
2#![warn(missing_docs)]
3#![deny(rustdoc::broken_intra_doc_links)]
4
5/// # Derive event-related traits for an enum
6///
7/// Use this macro to define an enum like `falco_event::events::types::AnyEvent`, that is usable
8/// wherever another event type is. For example,
9///
10/// ```
11/// use std::ffi::CStr;
12/// use anyhow::{anyhow, Context};
13/// use falco_event::events::PayloadFromBytesError;
14///
15/// #[derive(Default, Debug, falco_event::EventPayload)]
16/// #[event_payload(source = Some("syscall"), code = 322, length_type = u32)]
17/// pub struct MyPluginEvent<'a> {
18///     pub plugin_id: u32,
19///     pub data: &'a [u8],
20/// }
21///
22/// #[derive(Default, Debug, falco_event::EventPayload)]
23/// #[event_payload(source = Some("syscall"), code = 322, length_type = u32)]
24/// pub struct MyAsyncEvent<'a> {
25///     pub plugin_id: u32,
26///     pub name: &'a [u8],
27///     pub data: &'a [u8],
28/// }
29///
30/// #[derive(falco_event_derive::AnyEvent)]
31/// pub enum AnyPluginEvent<'a> {
32///     AsyncEvent(MyAsyncEvent<'a>),
33///     PluginEvent(MyPluginEvent<'a>),
34/// }
35/// ```
36///
37/// If the `falco_event` crate is available under a different path, provide its name
38/// in the `falco_event_crate` attribute:
39///
40/// ```
41/// # use falco_event as falco_event_alt;
42/// # #[derive(Default, Debug, falco_event::EventPayload)]
43/// # #[event_payload(source = Some("syscall"), code = 322, length_type = u32)]
44/// # pub struct MyPluginEvent<'a> {
45/// #     pub plugin_id: u32,
46/// #     pub data: &'a [u8],
47/// # }
48/// #
49/// # #[derive(Default, Debug, falco_event::EventPayload)]
50/// # #[event_payload(source = Some("syscall"), code = 322, length_type = u32)]
51/// # pub struct MyAsyncEvent<'a> {
52/// #     pub plugin_id: u32,
53/// #     pub name: &'a [u8],
54/// #     pub data: &'a [u8],
55/// # }
56/// #[derive(falco_event_alt::AnyEvent)]
57/// #[falco_event_crate(falco_event_alt)]
58/// pub enum AnyPluginEvent<'a> {
59///     AsyncEvent(MyAsyncEvent<'a>),
60///     PluginEvent(MyPluginEvent<'a>),
61/// }
62/// ```
63///
64/// ## Requirements
65///
66/// To use this macro on an enum, all its variants need to have exactly one unnamed field,
67/// which implements the following traits:
68/// * [`std::fmt::Debug`], for a string representation
69/// * [`events::EventPayload`], which indicates the type id (and source) of the variant
70/// * [`events::FromRawEvent`], which handles deserialization of the variant
71/// * [`events::PayloadToBytes`], which handles serialization of the variant
72///
73/// One way to fullfil these requirements is to use the [`EventPayload`]
74/// macro on the variant field's type.
75///
76/// ## Derived traits
77///
78/// This macro implements the following traits on the enum type:
79/// * [`std::fmt::Debug`], by delegating to each variant (without additional wrapping)
80/// * [`events::AnyEventPayload`], which describes a whole set of type ids and sources supported
81///   by the enum (one for each variant)
82/// * [`events::FromRawEvent`], for deserialization
83/// * [`events::PayloadToBytes`], for serialization
84pub use falco_event_derive::AnyEvent;
85
86/// # Derive event-related traits for a struct
87///
88/// Use this macro to define new event types. For example, the PPME_PLUGINEVENT_E
89/// event could be defined as:
90///
91/// ```
92/// #[derive(Default, falco_event::EventPayload)]
93/// #[event_payload(source = Some("syscall"), code = 322, length_type = u32)]
94/// pub struct MyPluginEvent<'a> {
95///     pub plugin_id: u32,
96///     pub data: &'a [u8],
97/// }
98/// ```
99///
100/// If the `falco_event` crate is available under a different path, provide its name
101/// in the `falco_event_crate` attribute:
102///
103/// ```
104/// # use falco_event as falco_event_alt;
105/// #[derive(Default, falco_event_alt::EventPayload)]
106/// #[event_payload(source = Some("syscall"), code = 322, length_type = u32)]
107/// #[falco_event_crate(falco_event_alt)]
108/// pub struct MyPluginEvent<'a> {
109///     pub plugin_id: u32,
110///     pub data: &'a [u8],
111/// }
112/// ```
113///
114/// To make your struct usable as an event payload, use the `#[event_payload]` attribute
115/// with the following (required) parameters:
116/// * `source` (`Option<&str>`) -- the name of the event source, for use in plugin metadata
117/// * `code` (u16) -- the raw numeric event type id
118/// * `length_type` (u16 or u32) -- the type of parameter length; most events use `u16` but a few
119///   notable ones (like PPME_ASYNCEVENT_E and PPME_PLUGINEVENT_E) support larger parameter values
120///   and so their length type is `u32`
121///
122/// This macro can be used only on structs, not enums. Each field of the struct must implement
123/// [`fields::FromBytes`] and [`fields::FromBytes`]. Due to the requirements of FieldMeta-based
124/// deserialization, the whole struct must also implement [`Default`] and may have at most one
125/// lifetime generic parameter.
126///
127///
128/// See above for an example use.
129///
130/// This variant derives the following traits:
131/// * [`events::FromRawEvent`] to provide deserialization
132/// * [`events::PayloadToBytes`] to provide serialization
133pub use falco_event_derive::EventPayload;
134
135/// Types and traits for Falco events
136pub mod events;
137
138/// Types and traits for Falco event fields
139pub mod fields;
140
141/// Data types used in Falco events
142pub mod types;
falco_event/lib.rs

falco_event/
lib.rs
