feat(nebula_hw_interfaces): better UDP socket

mojomex commented 1 week ago

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 autowarefoundation/transport_drivers#1)
joining a multicast group (already supported in transport_drivers through MapIV/transport_drivers#7)
filtering by sender (already supported in transport_drivers through MapIV/transport_drivers#7)
setting MTU size (= user-space receive buffer size, already supported in transport_drivers through 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[bot] commented 1 week ago

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 :warning:
nebula_hw_interfaces/test/common/test_udp.cpp	63.51%	7 Missing and 20 partials :warning:
...ebula_hw_interfaces/test/common/test_udp/utils.hpp	84.00%	0 Missing and 4 partials :warning:

Additional details and impacted files

```diff @@ 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](https://app.codecov.io/gh/tier4/nebula/pull/231/flags?src=pr&el=flags&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=tier4) | Coverage Δ | | |---|---|---| | [differential](https://app.codecov.io/gh/tier4/nebula/pull/231/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=tier4) | `27.03% <64.38%> (?)` | | | [total](https://app.codecov.io/gh/tier4/nebula/pull/231/flags?src=pr&el=flag&utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=tier4) | `?` | | Flags with carried forward coverage won't be shown. [Click here](https://docs.codecov.io/docs/carryforward-flags?utm_medium=referral&utm_source=github&utm_content=comment&utm_campaign=pr+comments&utm_term=tier4#carryforward-flags-in-the-pull-request-comment) to find out more.

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.

🚨 Try these New Features:

Flaky Tests Detection - Detect and resolve failed and flaky tests

mojomex commented 1 week ago

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%.

tier4 / nebula