Trait SourcePluginInstance

pub trait SourcePluginInstance {
    type Plugin: SourcePlugin<Instance = Self>;

    // Required method
    fn next_batch(
        &mut self,
        plugin: &mut Self::Plugin,
        batch: &mut EventBatch<'_>,
    ) -> Result<(), Error>;

    // Provided methods
    fn get_progress(&mut self) -> ProgressInfo<'_> { ... }
    fn plugin_event(data: &[u8]) -> Event<PluginEvent<'_>> { ... }
}

An open instance of a source plugin

Required Associated Types

type Plugin: SourcePlugin<Instance = Self>

The SourcePlugin this instance belongs to.

Source plugin and instance types must correspond 1:1 to each other.

Required Methods

fn next_batch( &mut self, plugin: &mut Self::Plugin, batch: &mut EventBatch<'_>, ) -> Result<(), Error>

Fill the next batch of events

This is the most important method for the source plugin implementation. It is responsible for actually generating the events for the main event loop.

For performance, events are returned in batches. Of course, it’s entirely valid to have just a single event in a batch.

Returning one or more events

For each event that is ready, pass it to batch.add() to add it to the current batch to be returned.

fn next_batch(
    &mut self,
    plugin: &mut Self::Plugin,
    batch: &mut EventBatch,
) -> Result<(), anyhow::Error> {
    let mut event = Vec::new();
    // ...
    let event = Self::plugin_event(&event);
    batch.add(event)?;
    Ok(())
}

Returning no events, temporarily

If there are no events to return at the moment but there might be later, you should return FailureReason::Timeout as the error. The plugin framework will retry the call to next_batch later.

fn next_batch(
    &mut self,
    plugin: &mut Self::Plugin,
    batch: &mut EventBatch,
) -> Result<(), anyhow::Error> {
    std::thread::sleep(Duration::from_millis(100));
    Err(anyhow::anyhow!("no events right now").context(FailureReason::Timeout))
}

Returning no events, permanently

If there will be no more events coming from this instance, you should return
FailureReason::Eof as the error. The plugin framework will end the capture and shut down gracefully.

fn next_batch(
    &mut self,
    plugin: &mut Self::Plugin,
    batch: &mut EventBatch,
) -> Result<(), anyhow::Error> {
    Err(anyhow::anyhow!("no more events").context(FailureReason::Eof))
}

Timing considerations

This method is effectively called in a loop by Falco and there’s a delicate balance of how much time to spend here waiting for events. On the one hand, you don’t want to poll in a tight loop, since that leads to excessive CPU usage. On the other hand, you don’t want to sleep forever waiting for an event, since it may block other tasks running in the main event loop thread. As a rule of thumb, waiting up to 10-100 milliseconds for an event works fine.

Provided Methods

fn get_progress(&mut self) -> ProgressInfo<'_>

Get progress information

If your plugin reads from a source that has a well-defined end (like a file), you can use this method to report progress information.

It consists of a percentage (0.0-100.0) and an optional description containing more details about the progress (e.g. bytes read/bytes total).

fn plugin_event(data: &[u8]) -> Event<PluginEvent<'_>>

A helper for generating plugin events

If your plugin defines a PLUGIN_ID and a source name, the only allowed events are of type PluginEvent and effectively the only customizable field is the event data (which is a generic byte buffer).

This method makes it easy to generate such events: just pass it the event data and get the complete event, with all the metadata set to reasonable defaults.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors