feat(nebula_hw_interfaces): better UDP socket

[mojomex]

PR Type

• Improvement

Description

The current Boost.ASIO/transport_drivers implementation is bloated and does not offer all the features we need for accurate timing and packet loss measurement.
Specifically, a good equivalent to recvmsg (see man recvmsg for details) is not supported.

This PR introduces a new, minimal and robust UDP socket implementation with the following features:

• setting socket buffer receive queue size (already supported in transport_drivers through feat(udp_socket): allow user to set internal socket buffer size autowarefoundation/transport_drivers#1)
• joining a multicast group (already supported in transport_drivers through feat: add multicast support MapIV/transport_drivers#7)
• filtering by sender (already supported in transport_drivers through feat: add multicast support MapIV/transport_drivers#7)
• setting MTU size (= user-space receive buffer size, already supported in transport_drivers through Support configuration of UDP receive buffer size MapIV/transport_drivers#6)
• measuring packet timestamps accurately* via SO_TIMESTAMP (see man 7 socket)
• measuring UDP socket receive queue overflow via SO_RXQ_OVFL (see man 7 socket)

*: Depending on the network interface hardware, the timestamp will be measured in hardware on packet arrival, or by the kernel in software as soon as possible after. In any case, the timing is much more accurate than doing it in user space, where scheduling has a huge impact on accuracy.

Usage

I aimed to document the class as well as possible, but still, here is a quick rundown of how to use the socket:

#include <nebula_hw_interfaces/nebula_hw_interfaces_common/connections/udp.hpp>

void my_func {
  using nebula::drivers::connections::UdpSocket;
  using nebula::drivers::connections::SocketError;
  using nebula::drivers::connections::UsageError;

  // Creates the underlying socket and sets timestamping, overflow reporting, etc. as options.
  UdpSocket sock{};

  // Sets the host IP and port. No actual socket operations happen at this point.
  sock.init("192.168.1.10", 1234);

  // Binds (= activates) the socket on the given host IP/port.
  sock.bind();

  // Forwards all received packets, with metadata (timestamp, packet drops, etc.) to `my_function`.
  sock.subscribe(my_funcion);

  // Stops forwarding packets. May have to be called manually if a lambda with reference-type captures
  // has been used as `my_function`, and its lifetime is shorter than that of `sock`.
  sock.unsubscribe();
}

Functions can also be chained like this:

auto sock = UdpSocket().init(...).bind().subscribe(...);

Pre-Review Checklist for the PR Author

PR Author should check the checkboxes below when creating the PR.

• Assign PR to reviewer

Checklist for the PR Reviewer

Reviewers should check the checkboxes below before approval.

• Commits are properly organized and messages are according to the guideline
• (Optional) Unit tests have been written for new behavior
• PR title describes the changes

Post-Review Checklist for the PR Author

PR Author should check the checkboxes below before merging.

• All open points are addressed and tracked via issues or tickets

CI Checks

• Build and test for PR: Required to pass before the merge.

[codecov]

Codecov Report

Attention: Patch coverage is 64.38356% with 78 lines in your changes missing coverage. Please review.

Project coverage is 27.03%. Comparing base (3284357) to head (205c5dc).
Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
...es/nebula_hw_interfaces_common/connections/udp.hpp	60.83%	24 Missing and 23 partials ⚠️
nebula_hw_interfaces/test/common/test_udp.cpp	63.51%	7 Missing and 20 partials ⚠️
...ebula_hw_interfaces/test/common/test_udp/utils.hpp	84.00%	0 Missing and 4 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #231      +/-   ##
==========================================
+ Coverage   26.10%   27.03%   +0.93%     
==========================================
  Files         100      103       +3     
  Lines        9218     9435     +217     
  Branches     2215     2318     +103     
==========================================
+ Hits         2406     2551     +145     
- Misses       6423     6446      +23     
- Partials      389      438      +49     

Flag	Coverage Δ
differential	27.03% <64.38%> (?)
total	?

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests

[mojomex]

Unit tests have been written, but things like querying net.core.rmem_max, or simulating packet loss, is not easily possible in Docker in CI, so test coverage is currently at 75%.