++

Author: Zadamsa

new-process-api/process/basicPlus/src/basicPlus.cpp

@@ -3,11 +3,13 @@
  * @brief Plugin for parsing basicplus traffic.
  * @author Jiri Havranek <[email protected]>
  * @author Pavel Siska <[email protected]>
+ * @author Damir Zainullin <[email protected]>
  * @date 2025
  *
- * Copyright (c) 2025 CESNET
+ * Provides a plugin that extracts basic IP and TCP fields from packets,
+ * stores them in per-flow plugin data, and exposes fields via FieldManager.
  *
- * SPDX-License-Identifier: BSD-3-Clause
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
  */
 
 #include "basicPlus.hpp"

new-process-api/process/basicPlus/src/basicPlus.hpp

@@ -3,11 +3,13 @@
  * @brief Plugin for parsing basicplus traffic.
  * @author Jiri Havranek <[email protected]>
  * @author Pavel Siska <[email protected]>
+ * @author Damir Zainullin <[email protected]>
  * @date 2025
  *
- * Copyright (c) 2025 CESNET
+ * Provides a plugin that extracts basic IP and TCP fields from packets,
+ * stores them in per-flow plugin data, and exposes fields via FieldManager.
  *
- * SPDX-License-Identifier: BSD-3-Clause
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
  */
 
 #pragma once
@@ -27,8 +29,6 @@ namespace ipxp {
 /**
  * @class BasicPlusPlugin
  * @brief A plugin for collecting basic statistics about the flow: IP TTL, flags, TCP window, options, MSS and SYN length.
- *
- * @note Duplicate and empty packets can be optionally skipped.
  */
 class BasicPlusPlugin : public ProcessPlugin {
 public:

new-process-api/process/basicPlus/src/basicPlusData.hpp

@@ -1,3 +1,12 @@
+/**
+ * @file
+ * @brief Export data of basicplus plugin.
+ * @author Damir Zainullin <[email protected]>
+ * @date 2025
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
 #pragma once
 
 #include <directionalField.hpp>

new-process-api/process/basicPlus/src/basicPlusFields.hpp

@@ -1,3 +1,12 @@
+/**
+ * @file
+ * @brief Export fields of basicplus plugin.
+ * @author Damir Zainullin <[email protected]>
+ * @date 2025
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
 #pragma once
 
 #include <cstddef>

new-process-api/process/bstats/src/burst.hpp

@@ -1,3 +1,12 @@
+/**
+ * @file
+ * @brief Burst structure for packet statistics.
+ * @author Damir Zainullin <[email protected]>
+ * @date 2025
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
 #pragma once
 
 #include <sys/time.h>
@@ -7,17 +16,26 @@
 namespace ipxp
 {
 
+/**
+ * @struct Burst
+ * @brief Structure representing one packet burst. Contains packets, bytes which belong to that burst with begin and end timestamps.
+ */
 struct Burst {
-    
     constexpr static uint64_t MAX_INTERPACKET_TIMEDIFF = 1'000'000;
 
     std::reference_wrapper<uint32_t> packets;
 	std::reference_wrapper<uint32_t> bytes;
 	std::reference_wrapper<uint64_t> start;
 	std::reference_wrapper<uint64_t> end;
 
-    constexpr inline
-    bool belongs(const uint64_t& time) const noexcept 
+    /**
+	 * @brief Checks if the given timestamp belongs to the burst.
+	 *
+	 * @param time The timestamp to check.
+     * @return true if the timestamp belongs to the burst, false otherwise.
+	 */
+    constexpr
+    bool belongs(const uint64_t time) const noexcept 
     {
         return time - end < MAX_INTERPACKET_TIMEDIFF;
     }

new-process-api/process/bstats/src/burstStats.cpp

@@ -1,13 +1,15 @@
 /**
  * @file
- * @brief Plugin for parsing basicplus traffic.
- * @author Jiri Havranek <havranek@cesnet.cz>
+ * @brief Plugin for parsing bstats traffic.
+ * @author Karel Hynek <[email protected].cz>
  * @author Pavel Siska <[email protected]>
+ * @author Damir Zainullin <[email protected]>
  * @date 2025
  *
- * Copyright (c) 2025 CESNET
- *
- * SPDX-License-Identifier: BSD-3-Clause
+ * Provides a plugin that extracts packet burst statistics of flows,
+ * stores them in per-flow plugin data, and exposes fields via FieldManager.
+ * 
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
  */
 
 #include "burstStats.hpp"
@@ -167,11 +169,6 @@ PluginDataMemoryLayout BurstStatsPlugin::getDataMemoryLayout() const noexcept
 	};
 }
 
-std::string BurstStatsPlugin::getName() const noexcept 
-{ 
-	return burstStatsPluginManifest.name; 
-}
-
 static const PluginRegistrar<BurstStatsPlugin, PluginFactory<ProcessPlugin, const std::string&, FieldManager&>>
 	burstStatsRegistrar(burstStatsPluginManifest);
 

new-process-api/process/bstats/src/burstStats.hpp

@@ -1,13 +1,15 @@
 /**
  * @file
- * @brief Plugin for parsing basicplus traffic.
- * @author Jiri Havranek <havranek@cesnet.cz>
+ * @brief Plugin for parsing bstats traffic.
+ * @author Karel Hynek <[email protected].cz>
  * @author Pavel Siska <[email protected]>
+ * @author Damir Zainullin <[email protected]>
  * @date 2025
  *
- * Copyright (c) 2025 CESNET
- *
- * SPDX-License-Identifier: BSD-3-Clause
+ * Provides a plugin that extracts packet burst statistics of flows,
+ * stores them in per-flow plugin data, and exposes fields via FieldManager.
+ * 
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
  */
 
 #pragma once
@@ -23,31 +25,76 @@
 
 namespace ipxp {
 
+/**
+ * @class BurstStatsPlugin
+ * @brief A plugin for collecting packet burst statistics.
+ */
 class BurstStatsPlugin : public ProcessPlugin {
 public:
+
+	/**
+	 * @brief Constructs the BurstStats plugin.
+	 *
+	 * @param parameters Plugin parameters as a string (currently unused).
+	 * @param fieldManager Reference to the FieldManager for field registration.
+	 */
 	BurstStatsPlugin(const std::string& params, FieldManager& manager);
 
+	/**
+	 * @brief Initializes plugin data for a new flow.
+	 *
+	 * Constructs `BurstStatsData` in `pluginContext` and initializes it with
+	 * burst containing initial packet.
+	 *
+	 * @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.
+	 */
 	PluginInitResult onInit(const FlowContext& flowContext, void* pluginContext) override;
 
+	/**
+	 * @brief Updates plugin data with values from new packet.
+	 *
+	 * Inserts new packet into `BurstStatsData`.
+	 *
+	 * @param flowContext Contextual information about the flow to be updated.
+	 * @param pluginContext Pointer to `BurstStatsData`.
+	 * @return Result of the update, may not require new packets if burst storage is full.
+	 */
 	PluginUpdateResult onUpdate(const FlowContext& flowContext, void* pluginContext) override;
 
+	/**
+	 * @brief Prepare the export data.
+	 *
+	 * Removes record if it is too short.
+	 * Sets all fields as available otherwise.
+	 *
+	 * @param flowRecord The flow record containing aggregated flow data.
+	 * @param pluginContext Pointer to `BurstStatsData`.
+	 * @return RemovePlugin if packet count is less than `MINIMAL_PACKETS_COUNT`, 
+	 * else no action is required.
+	 */
 	PluginExportResult onExport(const FlowRecord& flowRecord, void* pluginContext) override;
 
+	/**
+	 * @brief Cleans up and destroys `BurstStatsData`.
+	 * @param pluginContext Pointer to `BurstStatsData`.
+	 */
 	void onDestroy(void* pluginContext) override;
 
-	std::string getName() const noexcept override;
-
+	/**
+	 * @brief Provides the memory layout of `BurstStatsData`.
+	 * @return Memory layout description for the plugin data.
+	 */
 	PluginDataMemoryLayout getDataMemoryLayout() const noexcept override;
 
-
 private:
-	constexpr static std::size_t MINIMAL_PACKETS_COUNT = 3;
+	constexpr static std::size_t MINIMAL_PACKETS_COUNT = 3; ///< Minimal number of packets to consider the flow valid.
 
 	void updateBursts(Burst& burst, FlowRecord& flowRecord, const Packet& packet) noexcept;
 	void makeAllFieldsUnavailable(FlowRecord& flowRecord) noexcept; 
 
 	FieldHandlers<BurstStatsFields> m_fieldHandlers;
-	
 };
 
 } // namespace ipxp

new-process-api/process/bstats/src/burstStatsData.hpp

@@ -1,3 +1,12 @@
+/**
+ * @file
+ * @brief Export data of bstats plugin.
+ * @author Damir Zainullin <[email protected]>
+ * @date 2025
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
 #pragma once
 
 #include <array>
@@ -10,8 +19,13 @@
 namespace ipxp
 {
 
-struct BurstStatsData {
-private:
+/**
+ * @class BurstStatsData
+ * @brief Class representing flow burst statistics.
+ *
+ * Contains packets, bytes and begin and end timestamps for each burst.
+ */
+class BurstStatsData {
 	static constexpr std::size_t MAX_BURST_COUNT = 15;
 
 	DirectionalField<boost::container::static_vector<uint32_t, MAX_BURST_COUNT>> packets;
@@ -21,28 +35,57 @@ struct BurstStatsData {
 
 public:
 
+	/**
+	 * @brief Returns a span over the packets for the given direction.
+	 *
+	 * @param direction The direction for which to retrieve the packet span.
+	 * @return A span over the packets.
+	 */
 	std::span<const uint32_t> getPackets(const Direction direction) const noexcept
 	{
 		return {packets[direction].data(), static_cast<std::size_t>(packets[direction].size())};
 	}
 
+	/**
+	 * @brief Returns a span over the bytes for the given direction.
+	 *
+	 * @param direction The direction for which to retrieve the byte span.
+	 * @return A span over the bytes.
+	 */
 	std::span<const uint32_t> getBytes(const Direction direction) const noexcept
 	{
 		return std::span<const uint32_t>(bytes[direction].data(), static_cast<std::size_t>(bytes[direction].size()));
 	}
 
+	/**
+	 * @brief Returns a span over the start timestamps for the given direction.
+	 *
+	 * @param direction The direction for which to retrieve the start timestamps span.
+	 * @return A span over the start timestamps.
+	 */
 	std::span<const uint64_t> getStartTimestamps(const Direction direction) const noexcept
 	{
 		return std::span<const uint64_t>(start[direction].data(), static_cast<std::size_t>(start[direction].size()));
 	}
 
+	/**
+	 * @brief Returns a span over the end timestamps for the given direction.
+	 *
+	 * @param direction The direction for which to retrieve the end timestamps span.
+	 * @return A span over the end timestamps.
+	 */
 	std::span<const uint64_t> getEndTimestamps(const Direction direction) const noexcept
 	{
 		return std::span<const uint64_t>(&*end[direction].begin(), static_cast<std::size_t>(end[direction].size()));
 	}
 
-	inline
-	std::optional<Burst> back(const Direction direction) noexcept
+	/**
+	 * @brief Returns a view to the last observed burst.
+	 *
+	 * @param direction The direction for which to retrieve the last observed burst.
+	 * @return A view to the last observed burst, or std::nullopt if no burst were added.
+	 */
+	inline std::optional<Burst> back(const Direction direction) noexcept
 	{
 		if (packets[direction].empty()) {
 			return std::nullopt;
@@ -55,10 +98,15 @@ struct BurstStatsData {
 		});
 	}
 
-	inline
-	std::optional<Burst> push(const Direction direction) noexcept
+	/**
+	 * @brief Adds new burst and returns it.
+	 *
+	 * @param direction The direction for which to add a burst.
+	 * @return A view to the newly added burst, or std::nullopt if the storage is full.
+	 */
+	inline std::optional<Burst> push(const Direction direction) noexcept
 	{
-		if (packets[direction].size() == packets[direction].max_size()) {
+		if (packets[direction].size() == packets[direction].capacity()) {
 			return std::nullopt;
 		}
 
@@ -69,8 +117,6 @@ struct BurstStatsData {
 
 		return back(direction);
 	}
-
-
 };  
 
 } // namespace ipxp

new-process-api/process/bstats/src/burstStatsFields.hpp

@@ -1,10 +1,25 @@
+/**
+ * @file
+ * @brief Export fields of bstats plugin.
+ * @author Damir Zainullin <[email protected]>
+ * @date 2025
+ *
+ * @copyright Copyright (c) 2025 CESNET, z.s.p.o.
+ */
+
 #pragma once
 
 #include <cstddef>
 
 namespace ipxp
 {
 
+/**
+ * @enum BurstStatsFields
+ * @brief Enumerates the fields exported by the BurstStats plugin.
+ *
+ * These enum values are used to index field handlers for this plugin.
+ */
 enum class BurstStatsFields : std::size_t {
 	SBI_BRST_PACKETS = 0,
 	SBI_BRST_BYTES,