rust/ffi: add flow lifecycle callback wrappers - v12

doc/userguide/devguide/extending/flow-lifecycle-callbacks.rst

@@ -0,0 +1,131 @@
+Flow Life Cycle Callbacks
+#########################
+
+Flow lifecycle callbacks let plugins and library users observe when
+Suricata initializes a flow, updates a flow with a packet, and finishes
+with a flow.
+
+These callbacks are useful for maintaining plugin state that follows the
+lifetime of a Suricata flow. For example, a plugin can allocate per-flow
+state from the init callback, update it as packets are seen, and perform
+final accounting from the finish callback.
+
+C API
+*****
+
+Flow Init Callback
+==================
+
+The init callback is called when Suricata initializes a flow.
+
+.. literalinclude:: ../../../../src/flow-callbacks.h
+   :language: c
+   :start-at: /** \brief Function type for flow initialization callbacks.
+   :end-at: typedef void (*SCFlowInitCallbackFn)(ThreadVars *tv, Flow *f, const Packet *p, void *user);
+
+Register an init callback with ``SCFlowRegisterInitCallback``.
+
+.. literalinclude:: ../../../../src/flow-callbacks.h
+   :language: c
+   :start-at: /** \brief Register a flow init callback.
+   :end-at: bool SCFlowRegisterInitCallback(SCFlowInitCallbackFn fn, void *user);
+
+Flow Update Callback
+====================
+
+The update callback is called when Suricata updates a flow with a packet.
+
+.. literalinclude:: ../../../../src/flow-callbacks.h
+   :language: c
+   :start-at: /** \brief Function type for flow update callbacks.
+   :end-at: typedef void (*SCFlowUpdateCallbackFn)(ThreadVars *tv, Flow *f, Packet *p, void *user);
+
+Register an update callback with ``SCFlowRegisterUpdateCallback``.
+
+.. literalinclude:: ../../../../src/flow-callbacks.h
+   :language: c
+   :start-at: /** \brief Register a flow update callback.
+   :end-at: bool SCFlowRegisterUpdateCallback(SCFlowUpdateCallbackFn fn, void *user);
+
+Flow Finish Callback
+====================
+
+The finish callback is called when Suricata is done with a flow.
+
+.. literalinclude:: ../../../../src/flow-callbacks.h
+   :language: c
+   :start-at: /** \brief Function type for flow finish callbacks.
+   :end-at: typedef void (*SCFlowFinishCallbackFn)(ThreadVars *tv, Flow *f, void *user);
+
+Register a finish callback with ``SCFlowRegisterFinishCallback``.
+
+.. code-block:: c
+
+   bool SCFlowRegisterFinishCallback(SCFlowFinishCallbackFn fn, void *user);
+
+Example
+=======
+
+.. code-block:: c
+
+   static void ExampleFlowInit(ThreadVars *tv, Flow *f, const Packet *p, void *user)
+   {
+       SCLogNotice("flow initialized: %p", f);
+   }
+
+   static void ExampleFlowUpdate(ThreadVars *tv, Flow *f, Packet *p, void *user)
+   {
+       SCLogNotice("flow updated: %p packet: %p", f, p);
+   }
+
+   static void ExampleFlowFinish(ThreadVars *tv, Flow *f, void *user)
+   {
+       SCLogNotice("flow finished: %p", f);
+   }
+
+   static void ExampleInit(void)
+   {
+       SCFlowRegisterInitCallback(ExampleFlowInit, NULL);
+       SCFlowRegisterUpdateCallback(ExampleFlowUpdate, NULL);
+       SCFlowRegisterFinishCallback(ExampleFlowFinish, NULL);
+   }
+
+Rust API
+********
+
+In Rust, use the ``suricata_ffi::flow`` module:
+
+- ``flow::register_init_callback``
+- ``flow::register_update_callback``
+- ``flow::register_finish_callback``
+
+The Rust wrappers register closures or function items and return
+``Result<(), &'static str>``.
+
+.. code-block:: rust
+
+   use suricata_ffi::flow::{self, Flow, Packet, ThreadVars};
+   use suricata_ffi::SCLogNotice;
+
+   fn flow_init(_tv: *mut ThreadVars, f: *mut Flow, _p: *const Packet) {
+       SCLogNotice!("flow initialized: {:p}", f);
+   }
+
+   fn flow_update(_tv: *mut ThreadVars, f: *mut Flow, p: *mut Packet) {
+       SCLogNotice!("flow updated: {:p} packet: {:p}", f, p);
+   }
+
+   fn flow_finish(_tv: *mut ThreadVars, f: *mut Flow) {
+       SCLogNotice!("flow finished: {:p}", f);
+   }
+
+   fn register_flow_callbacks() -> Result<(), &'static str> {
+       flow::register_init_callback(flow_init)?;
+       flow::register_update_callback(flow_update)?;
+       flow::register_finish_callback(flow_finish)?;
+       Ok(())
+   }
+
+The raw pointers passed into callbacks are only valid for the duration
+of the callback invocation and must not be stored. Rust callbacks must
+not panic.

doc/userguide/devguide/extending/index.rst

@@ -12,3 +12,4 @@ Extending Suricata
    output/index.rst
    output/eve-filetypes.rst
    output/eve-hooks.rst
+   flow-lifecycle-callbacks.rst

rust/ffi/src/flow.rs

@@ -0,0 +1,134 @@
+/* Copyright (C) 2026 Open Information Security Foundation
+ *
+ * You can copy, redistribute or modify this Program under the terms of
+ * the GNU General Public License version 2 as published by the Free
+ * Software Foundation.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * version 2 along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
+ * 02110-1301, USA.
+ */
+
+use std::os::raw::c_void;
+
+pub use suricata_sys::sys::{Flow, Packet, ThreadVars};
+use suricata_sys::sys::{
+    SCFlowRegisterFinishCallback, SCFlowRegisterInitCallback, SCFlowRegisterUpdateCallback,
+};
+
+/// Register a flow initialization callback.
+///
+/// The callback is invoked whenever Suricata initializes a flow. It receives:
+/// - `tv`: the `ThreadVars` for the thread creating the flow
+/// - `f`: the newly initialized `Flow`
+/// - `p`: the packet related to creating the flow
+///
+/// # Safety
+///
+/// The callback receives raw pointers from Suricata. These pointers are only
+/// valid for the duration of the callback invocation and must not be stored.
+///
+/// The callback must not panic.
+pub fn register_init_callback<F>(callback: F) -> Result<(), &'static str>
+where
+    F: Fn(*mut ThreadVars, *mut Flow, *const Packet) + Send + Sync + 'static,
+{
+    let user = Box::into_raw(Box::new(callback)) as *mut c_void;
+    if unsafe { SCFlowRegisterInitCallback(Some(init_callback_wrapper::<F>), user) } {
+        Ok(())
+    } else {
+        unsafe {
+            drop(Box::from_raw(user as *mut F));
+        }
+        Err("Failed to register flow init callback")
+    }
+}
+
+/// Register a flow update callback.
+///
+/// The callback is invoked whenever Suricata updates a flow with a packet. It
+/// receives:
+/// - `tv`: the `ThreadVars` for the thread updating the flow
+/// - `f`: the flow being updated
+/// - `p`: the packet responsible for the flow update
+///
+/// # Safety
+///
+/// The callback receives raw pointers from Suricata. These pointers are only
+/// valid for the duration of the callback invocation and must not be stored.
+///
+/// The callback must not panic.
+pub fn register_update_callback<F>(callback: F) -> Result<(), &'static str>
+where
+    F: Fn(*mut ThreadVars, *mut Flow, *mut Packet) + Send + Sync + 'static,
+{
+    let user = Box::into_raw(Box::new(callback)) as *mut c_void;
+    if unsafe { SCFlowRegisterUpdateCallback(Some(update_callback_wrapper::<F>), user) } {
+        Ok(())
+    } else {
+        unsafe {
+            drop(Box::from_raw(user as *mut F));
+        }
+        Err("Failed to register flow update callback")
+    }
+}
+
+/// Register a flow finish callback.
+///
+/// The callback is invoked when Suricata is finished with a flow. It receives:
+/// - `tv`: the `ThreadVars` for the thread finishing the flow
+/// - `f`: the flow being finished
+///
+/// # Safety
+///
+/// The callback receives raw pointers from Suricata. These pointers are only
+/// valid for the duration of the callback invocation and must not be stored.
+///
+/// The callback must not panic.
+pub fn register_finish_callback<F>(callback: F) -> Result<(), &'static str>
+where
+    F: Fn(*mut ThreadVars, *mut Flow) + Send + Sync + 'static,
+{
+    let user = Box::into_raw(Box::new(callback)) as *mut c_void;
+    if unsafe { SCFlowRegisterFinishCallback(Some(finish_callback_wrapper::<F>), user) } {
+        Ok(())
+    } else {
+        unsafe {
+            drop(Box::from_raw(user as *mut F));
+        }
+        Err("Failed to register flow finish callback")
+    }
+}
+
+unsafe extern "C" fn init_callback_wrapper<F>(
+    tv: *mut ThreadVars, f: *mut Flow, p: *const Packet, user: *mut c_void,
+) where
+    F: Fn(*mut ThreadVars, *mut Flow, *const Packet) + Send + Sync + 'static,
+{
+    let callback = &*(user as *const F);
+    callback(tv, f, p);
+}
+
+unsafe extern "C" fn update_callback_wrapper<F>(
+    tv: *mut ThreadVars, f: *mut Flow, p: *mut Packet, user: *mut c_void,
+) where
+    F: Fn(*mut ThreadVars, *mut Flow, *mut Packet) + Send + Sync + 'static,
+{
+    let callback = &*(user as *const F);
+    callback(tv, f, p);
+}
+
+unsafe extern "C" fn finish_callback_wrapper<F>(
+    tv: *mut ThreadVars, f: *mut Flow, user: *mut c_void,
+) where
+    F: Fn(*mut ThreadVars, *mut Flow) + Send + Sync + 'static,
+{
+    let callback = &*(user as *const F);
+    callback(tv, f);
+}

rust/ffi/src/lib.rs

@@ -20,6 +20,7 @@ pub mod conf;
 pub mod debug;
 pub mod detect;
 pub mod eve;
+pub mod flow;
 pub mod jsonbuilder;
 pub mod plugin;
 

rust/sys/src/sys.rs

@@ -1791,6 +1791,58 @@ extern "C" {
 extern "C" {
     pub fn SCFlowGetAppProtocol(f: *const Flow) -> AppProto;
 }
+#[doc = " \\brief Function type for flow initialization callbacks.\n\n Once registered with SCFlowRegisterInitCallback, this function will\n be called every time a flow is initialized, or in other words,\n every time Suricata picks up a flow.\n\n \\param tv The ThreadVars data structure for the thread creating the\n     flow.\n \\param f The newly initialized flow.\n \\param p The packet related to creating the new flow.\n \\param user The user data provided during callback registration."]
+pub type SCFlowInitCallbackFn = ::std::option::Option<
+    unsafe extern "C" fn(
+        tv: *mut ThreadVars,
+        f: *mut Flow,
+        p: *const Packet,
+        user: *mut ::std::os::raw::c_void,
+    ),
+>;
+extern "C" {
+    #[doc = " \\brief Register a flow init callback.\n\n Register a user provided function to be called every time a flow is\n initialized for use.\n\n \\param fn Pointer to function to be called\n \\param user Additional user data to be passed to callback\n\n \\returns true if callback was registered, otherwise false if the\n     callback could not be registered due to memory allocation error."]
+    pub fn SCFlowRegisterInitCallback(
+        fn_: SCFlowInitCallbackFn, user: *mut ::std::os::raw::c_void,
+    ) -> bool;
+}
+extern "C" {
+    #[doc = " \\internal\n\n Run all registered flow init callbacks."]
+    pub fn SCFlowRunInitCallbacks(tv: *mut ThreadVars, f: *mut Flow, p: *const Packet);
+}
+#[doc = " \\brief Function type for flow update callbacks.\n\n Once registered with SCFlowRegisterUpdateCallback, this function\n will be called every time a flow is updated by a packet (basically\n everytime a packet is seen on a flow).\n\n \\param tv The ThreadVars data structure for the thread updating the\n     flow.\n \\param f The flow being updated.\n \\param p The packet responsible for the flow update.\n \\param user The user data provided during callback registration."]
+pub type SCFlowUpdateCallbackFn = ::std::option::Option<
+    unsafe extern "C" fn(
+        tv: *mut ThreadVars,
+        f: *mut Flow,
+        p: *mut Packet,
+        user: *mut ::std::os::raw::c_void,
+    ),
+>;
+extern "C" {
+    #[doc = " \\brief Register a flow update callback.\n\n Register a user provided function to be called everytime a flow is\n updated.\n\n \\param fn Pointer to function to be called\n \\param user Additional user data to be passed to callback\n\n \\returns true if callback was registered, otherwise false if the\n     callback could not be registered due to memory allocation error."]
+    pub fn SCFlowRegisterUpdateCallback(
+        fn_: SCFlowUpdateCallbackFn, user: *mut ::std::os::raw::c_void,
+    ) -> bool;
+}
+extern "C" {
+    #[doc = " \\internal\n\n Run all registered flow update callbacks."]
+    pub fn SCFlowRunUpdateCallbacks(tv: *mut ThreadVars, f: *mut Flow, p: *mut Packet);
+}
+#[doc = " \\brief Function type for flow finish callbacks.\n\n Once registered with SCFlowRegisterFinshCallback, this function\n will be called when Suricata is done with a flow.\n\n \\param tv The ThreadVars data structure for the thread finishing\n     the flow.\n \\param f The flow being finshed.\n \\param user The user data provided during callback registration."]
+pub type SCFlowFinishCallbackFn = ::std::option::Option<
+    unsafe extern "C" fn(tv: *mut ThreadVars, f: *mut Flow, user: *mut ::std::os::raw::c_void),
+>;
+extern "C" {
+    #[doc = " \\brief Register a flow init callback.\n\n Register a user provided function to be called every time a flow is\n finished.\n\n \\param fn Pointer to function to be called\n \\param user Additional user data to be passed to callback\n\n \\returns true if callback was registered, otherwise false if the\n     callback could not be registered due to memory allocation error."]
+    pub fn SCFlowRegisterFinishCallback(
+        fn_: SCFlowFinishCallbackFn, user: *mut ::std::os::raw::c_void,
+    ) -> bool;
+}
+extern "C" {
+    #[doc = " \\internal\n\n Run all registered flow init callbacks."]
+    pub fn SCFlowRunFinishCallbacks(tv: *mut ThreadVars, f: *mut Flow);
+}
 extern "C" {
     pub fn SCSRepCatGetByShortname(shortname: *const ::std::os::raw::c_char) -> u8;
 }

src/bindgen.h

@@ -62,6 +62,7 @@
 #include "util-spm-bs.h"
 
 #include "flow-bindgen.h"
+#include "flow-callbacks.h"
 
 #include "reputation.h"
 #include "feature.h"

src/flow-callbacks.h

@@ -18,8 +18,10 @@
 #ifndef SURICATA_FLOW_CALLBACKS_H
 #define SURICATA_FLOW_CALLBACKS_H
 
+#ifndef SURICATA_BINDGEN_H
 #include "suricata-common.h"
 #include "flow.h"
+#endif
 
 /** \brief Function type for flow initialization callbacks.
  *