Process plugins - Introduce VLAN process plugin

Author: Zainullin Damir

src/plugins/process/vlan/CMakeLists.txt

@@ -3,15 +3,20 @@ project(ipfixprobe-process-vlan VERSION 1.0.0 DESCRIPTION "ipfixprobe-process-vl
 add_library(ipfixprobe-process-vlan MODULE
 	src/vlan.cpp
 	src/vlan.hpp
+	src/vlanContext.hpp
+	src/vlanFields.hpp
 )
 
 set_target_properties(ipfixprobe-process-vlan PROPERTIES
 	CXX_VISIBILITY_PRESET hidden
 	VISIBILITY_INLINES_HIDDEN YES
 )
 
-target_include_directories(ipfixprobe-process-vlan PRIVATE
+target_include_directories(ipfixprobe-process-vlan PRIVATE 
 	${CMAKE_SOURCE_DIR}/include/
+	${CMAKE_SOURCE_DIR}/include/ipfixprobe/processPlugin
+	${CMAKE_SOURCE_DIR}/include/ipfixprobe/pluginFactory
+	${adaptmon_SOURCE_DIR}/lib/include/public/
 )
 
 if(ENABLE_NEMEA)

src/plugins/process/vlan/README.md

@@ -0,0 +1,30 @@
+# VLAN Plugin
+
+The **VLAN Plugin** parses VLAN tags and exports extracted values.
+
+## Features
+
+- Extracts and exports VLAN ID.
+
+## Output Fields
+
+| Field Name | Data Type  | Description                        |
+| ---------- | ---------- | ---------------------------------- |
+| `VLAN_ID`  | `uint16_t` | VLAN ID extracted from the packet. |
+
+## Usage
+
+### YAML Configuration
+
+Add the plugin to your ipfixprobe YAML configuration:
+
+```yaml
+process_plugins:
+  - vlan
+```
+
+### CLI Usage
+
+You can also enable the plugin directly from the command line:
+
+`ipfixprobe -p vlan ...`

src/plugins/process/vlan/src/vlan.cpp

@@ -3,21 +3,33 @@
  * @brief Plugin for parsing basicplus traffic.
  * @author Jakub Antonín Štigler xstigl00@[email protected]
  * @author Pavel Siska <[email protected]>
+ * @author Damir Zainullin <[email protected]>
  * @date 2025
  *
- * Copyright (c) 2025 CESNET
+ * Provides a plugin that parses VLAN traffic,
+ * stores it in per-flow plugin data, and exposes that field via FieldManager.
  *
- * SPDX-License-Identifier: BSD-3-Clause
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
  */
 
 #include "vlan.hpp"
 
+#include "vlanContext.hpp"
+#include "vlanGetters.hpp"
+
 #include <iostream>
 
-#include <ipfixprobe/pluginFactory/pluginManifest.hpp>
-#include <ipfixprobe/pluginFactory/pluginRegistrar.hpp>
+#include <amon/layers/VLAN.hpp>
+#include <fieldGroup.hpp>
+#include <fieldManager.hpp>
+#include <flowRecord.hpp>
+#include <ipfixprobe/options.hpp>
+#include <pluginFactory.hpp>
+#include <pluginManifest.hpp>
+#include <pluginRegistrar.hpp>
+#include <utils.hpp>
 
-namespace ipxp {
+namespace ipxp::process::vlan {
 
 static const PluginManifest vlanPluginManifest = {
 	.name = "vlan",
@@ -31,25 +43,56 @@ static const PluginManifest vlanPluginManifest = {
 		},
 };
 
-VLANPlugin::VLANPlugin(const std::string& params, int pluginID)
-	: ProcessPlugin(pluginID)
+static FieldGroup
+createVLANSchema(FieldManager& fieldManager, FieldHandlers<VLANFields>& handlers) noexcept
+{
+	FieldGroup schema = fieldManager.createFieldGroup("vlan");
+
+	handlers.insert(VLANFields::VLAN_ID, schema.addScalarField("VLAN_ID", getVLANIdField));
+
+	return schema;
+}
+
+VLANPlugin::VLANPlugin([[maybe_unused]] const std::string& params, FieldManager& manager)
 {
-	init(params.c_str());
+	createVLANSchema(manager, m_fieldHandlers);
+}
+
+OnInitResult VLANPlugin::onInit(const FlowContext& flowContext, void* pluginContext)
+{
+	if (!flowContext.packetContext.packet->layout.vlan.has_value()) {
+		return OnInitResult::Irrelevant;
+	}
+
+	auto vlanView = flowContext.packetContext.packet->getLayerView<amon::layers::VLANView>(
+		std::get<amon::PacketLayer>(flowContext.packetContext.packet
+										->layers[*flowContext.packetContext.packet->layout.vlan]));
+	if (!vlanView.has_value()) {
+		return OnInitResult::Irrelevant;
+	}
+
+	std::construct_at(reinterpret_cast<VLANContext*>(pluginContext))->vlanId = vlanView->tag();
+	m_fieldHandlers[VLANFields::VLAN_ID].setAsAvailable(flowContext.flowRecord);
+
+	return OnInitResult::ConstructedFinal;
 }
 
-ProcessPlugin* VLANPlugin::copy()
+void VLANPlugin::onDestroy(void* pluginContext) noexcept
 {
-	return new VLANPlugin(*this);
+	std::destroy_at(reinterpret_cast<VLANContext*>(pluginContext));
 }
 
-int VLANPlugin::post_create(Flow& rec, const Packet& pkt)
+PluginDataMemoryLayout VLANPlugin::getDataMemoryLayout() const noexcept
 {
-	auto ext = new RecordExtVLAN(m_pluginID);
-	ext->vlan_id = pkt.vlan_id;
-	rec.add_extension(ext);
-	return 0;
+	return {
+		.size = sizeof(VLANContext),
+		.alignment = alignof(VLANContext),
+	};
 }
 
-static const PluginRegistrar<VLANPlugin, ProcessPluginFactory> vlanRegistrar(vlanPluginManifest);
+static const PluginRegistrar<
+	VLANPlugin,
+	PluginFactory<ProcessPlugin, const std::string&, FieldManager&>>
+	vlanRegistrar(vlanPluginManifest);
 
-} // namespace ipxp
+} // namespace ipxp::process::vlan

src/plugins/process/vlan/src/vlan.hpp

@@ -3,96 +3,76 @@
  * @brief Plugin for parsing basicplus traffic.
  * @author Jakub Antonín Štigler xstigl00@[email protected]
  * @author Pavel Siska <[email protected]>
+ * @author Damir Zainullin <[email protected]>
  * @date 2025
  *
- * Copyright (c) 2025 CESNET
+ * Provides a plugin that parses VLAN traffic,
+ * stores it in per-flow plugin data, and exposes that field via FieldManager.
  *
- * SPDX-License-Identifier: BSD-3-Clause
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
  */
 
 #pragma once
 
-#include <cstring>
+#include "vlanFields.hpp"
 
-#ifdef WITH_NEMEA
-#include "fields.h"
-#endif
-
-#include <cstdint>
 #include <sstream>
 #include <string>
 
-#include <ipfixprobe/flowifc.hpp>
-#include <ipfixprobe/ipfix-elements.hpp>
-#include <ipfixprobe/packet.hpp>
-#include <ipfixprobe/processPlugin.hpp>
-
-namespace ipxp {
-
-#define VLAN_UNIREC_TEMPLATE "VLAN_ID"
+#include <fieldHandlersEnum.hpp>
+#include <fieldManager.hpp>
+#include <processPlugin.hpp>
 
-UR_FIELDS(uint16 VLAN_ID)
+namespace ipxp::process::vlan {
 
 /**
- * \brief Flow record extension header for storing parsed VLAN data.
- */
-struct RecordExtVLAN : public RecordExt {
-	// vlan id is in the host byte order
-	uint16_t vlan_id;
-
-	RecordExtVLAN(int pluginID)
-		: RecordExt(pluginID)
-		, vlan_id(0)
-	{
-	}
-
-#ifdef WITH_NEMEA
-	virtual void fill_unirec(ur_template_t* tmplt, void* record)
-	{
-		ur_set(tmplt, record, F_VLAN_ID, vlan_id);
-	}
-
-	const char* get_unirec_tmplt() const { return VLAN_UNIREC_TEMPLATE; }
-#endif
-
-	virtual int fill_ipfix(uint8_t* buffer, int size)
-	{
-		const int LEN = sizeof(vlan_id);
-
-		if (size < LEN) {
-			return -1;
-		}
-
-		*reinterpret_cast<uint16_t*>(buffer) = htons(vlan_id);
-		return LEN;
-	}
-
-	const char** get_ipfix_tmplt() const
-	{
-		static const char* ipfix_template[] = {IPFIX_VLAN_TEMPLATE(IPFIX_FIELD_NAMES) NULL};
-		return ipfix_template;
-	}
-
-	std::string get_text() const
-	{
-		std::ostringstream out;
-		out << "vlan_id=\"" << vlan_id << '"';
-		return out.str();
-	}
-};
-
-/**
- * \brief Process plugin for parsing VLAN packets.
+ * @class VLANPlugin
+ * @brief A plugin for parsing VLAN traffic.
+ *
+ * Collects and exports VLAN ID.
  */
 class VLANPlugin : public ProcessPlugin {
 public:
-	VLANPlugin(const std::string& params, int pluginID);
-	OptionsParser* get_parser() const { return new OptionsParser("vlan", "Parse VLAN traffic"); }
-	std::string get_name() const { return "vlan"; }
-	RecordExt* get_ext() const { return new RecordExtVLAN(m_pluginID); }
-	ProcessPlugin* copy();
-
-	int post_create(Flow& rec, const Packet& pkt);
+	/**
+	 * @brief Constructs the VLAN plugin and initializes field handlers.
+	 * @param params String with plugin-specific parameters for configuration(currently unused).
+	 * @param manager Reference to the FieldManager for field handler registration.
+	 */
+	VLANPlugin(const std::string& params, FieldManager& manager);
+
+	/**
+	 * @brief Initializes plugin data for a new flow.
+	 *
+	 * Constructs `VLANExport` in `pluginContext` and sets VLAN value.
+	 *
+	 * 0 VLAN value means no VLAN tag present.
+	 *
+	 * @param flowContext Contextual information about the flow to fill new record.
+	 * @param pluginContext Pointer to pre-allocated memory to create record.
+	 * @return Result of the initialization process.
+	 */
+	OnInitResult onInit(const FlowContext& flowContext, void* pluginContext) override;
+
+	/**
+	 * @brief Destroys plugin data.
+	 *
+	 * Calls the destructor of `VLANContext` in `pluginContext`.
+	 *
+	 * @param pluginContext Pointer to `VLANContext`.
+	 */
+	void onDestroy(void* pluginContext) noexcept override;
+
+	/**
+	 * @brief Provides memory layout information for `VLANContext`.
+	 *
+	 * Returns the size and alignment requirements of `VLANContext`.
+	 *
+	 * @return Memory layout details for `VLANContext`.
+	 */
+	PluginDataMemoryLayout getDataMemoryLayout() const noexcept override;
+
+private:
+	FieldHandlers<VLANFields> m_fieldHandlers;
 };
 
-} // namespace ipxp
+} // namespace ipxp::process::vlan

src/plugins/process/vlan/src/vlanContext.hpp

@@ -0,0 +1,24 @@
+/**
+ * @file
+ * @brief Definition of VLAN data structure.
+ * @author Damir Zainullin <[email protected]>
+ * @date 2025
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
+#pragma once
+
+#include <cstdint>
+
+namespace ipxp::process::vlan {
+
+/**
+ * @struct VLANContext
+ * @brief Struct representing VLAN export data.
+ */
+struct VLANContext {
+	uint16_t vlanId;
+};
+
+} // namespace ipxp::process::vlan

src/plugins/process/vlan/src/vlanFields.hpp

@@ -0,0 +1,27 @@
+/**
+ * @file
+ * @brief Definition of VLAN fields.
+ * @author Damir Zainullin <[email protected]>
+ * @date 2025
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
+#pragma once
+
+#include <cstddef>
+
+namespace ipxp::process::vlan {
+
+/**
+ * @enum VLANFields
+ * @brief Enumerates the fields exported by the VLAN plugin.
+ *
+ * These enum values are used to index field handlers for this plugin.
+ */
+enum class VLANFields : std::size_t {
+	VLAN_ID = 0,
+	FIELDS_SIZE,
+};
+
+} // namespace ipxp::process::vlan

src/plugins/process/vlan/src/vlanGetters.hpp

@@ -0,0 +1,26 @@
+
+/**
+ * @file vlanGetters.hpp
+ * @brief Getters for VLAN plugin fields.
+ * @author Damir Zainullin <[email protected]>
+ * @date 2025
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
+#pragma once
+
+#include "vlanContext.hpp"
+
+namespace ipxp::process::vlan {
+
+inline constexpr const VLANContext& asVLANContext(const void* context) noexcept
+{
+	return *static_cast<const VLANContext*>(context);
+}
+
+// VLANField::VLAN_ID
+inline constexpr auto getVLANIdField
+	= [](const void* context) { return asVLANContext(context).vlanId; };
+
+} // namespace ipxp::process::vlan