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#[cfg(feature = "derive_deftly")]
87pub use derive_deftly;
88/// # Derive event-related traits for a struct
89///
90/// Use this macro to define new event types. For example, the PPME_PLUGINEVENT_E
91/// event could be defined as:
92///
93/// ```
94/// #[derive(Default, falco_event::EventPayload)]
95/// #[event_payload(source = Some("syscall"), code = 322, length_type = u32)]
96/// pub struct MyPluginEvent<'a> {
97///     pub plugin_id: u32,
98///     pub data: &'a [u8],
99/// }
100/// ```
101///
102/// If the `falco_event` crate is available under a different path, provide its name
103/// in the `falco_event_crate` attribute:
104///
105/// ```
106/// # use falco_event as falco_event_alt;
107/// #[derive(Default, falco_event_alt::EventPayload)]
108/// #[event_payload(source = Some("syscall"), code = 322, length_type = u32)]
109/// #[falco_event_crate(falco_event_alt)]
110/// pub struct MyPluginEvent<'a> {
111///     pub plugin_id: u32,
112///     pub data: &'a [u8],
113/// }
114/// ```
115///
116/// To make your struct usable as an event payload, use the `#[event_payload]` attribute
117/// with the following (required) parameters:
118/// * `source` (`Option<&str>`) -- the name of the event source, for use in plugin metadata
119/// * `code` (u16) -- the raw numeric event type id
120/// * `length_type` (u16 or u32) -- the type of parameter length; most events use `u16` but a few
121///   notable ones (like PPME_ASYNCEVENT_E and PPME_PLUGINEVENT_E) support larger parameter values
122///   and so their length type is `u32`
123///
124/// This macro can be used only on structs, not enums. Each field of the struct must implement
125/// [`fields::FromBytes`] and [`fields::FromBytes`]. Due to the requirements of FieldMeta-based
126/// deserialization, the whole struct must also implement [`Default`] and may have at most one
127/// lifetime generic parameter.
128///
129///
130/// See above for an example use.
131///
132/// This variant derives the following traits:
133/// * [`events::FromRawEvent`] to provide deserialization
134/// * [`events::PayloadToBytes`] to provide serialization
135pub use falco_event_derive::EventPayload;
136
137#[allow(missing_docs)]
138pub mod events;
139
140/// All the types available in event fields
141pub mod fields;
142mod types;
143
144/// Formatting wrappers
145///
146/// This module provides wrappers for various types that format the inner type according
147/// to Falco style.
148pub mod format {
149    pub use crate::types::format::OptionFormatter;
150    pub use crate::types::ByteBufFormatter;
151    pub use crate::types::CStrFormatter;
152}
153
154#[allow(dead_code)]
155#[allow(non_snake_case)]
156#[allow(non_camel_case_types)]
157#[allow(non_upper_case_globals)]
158#[allow(missing_docs)]
159#[allow(unsafe_op_in_unsafe_fn)]
160#[doc(hidden)]
161pub mod ffi;
falco_event/lib.rs

falco_event/
lib.rs
