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 66.22222% with 76 lines in your changes missing coverage. Please review.

Project coverage is 27.07%. Comparing base (3284357) to head (3124948).
Report is 10 commits behind head on main.

Files with missing lines	Patch %	Lines
...es/nebula_hw_interfaces_common/connections/udp.hpp	63.49%	23 Missing and 23 partials ⚠️
nebula_hw_interfaces/test/common/test_udp.cpp	64.86%	7 Missing and 19 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.07%   +0.97%     
==========================================
  Files         100      104       +4     
  Lines        9218     9455     +237     
  Branches     2215     2319     +104     
==========================================
+ Hits         2406     2560     +154     
- Misses       6423     6458      +35     
- Partials      389      437      +48     

Flag	Coverage Δ
differential	27.07% <66.22%> (?)
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.

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

[drwnz]

I left some comments! Many are questions and there are no must-do changes but please have a look and I will approve once confirmed.

[drwnz]

Very very nit: sock_fd is checked for explicitly -1, where setsockopt for < 0. Both seem to only return -1 when a problem has occurred.

[mojomex]

Addressed in 193bf6e.

[drwnz]

If the socket is kept alive, should we consider shutting it down to prevent reading from it?
shutdown(sock_fd_, SHUT_RD);
and associated error handling.

[drwnz]

Would it be better to leave any subscribed multicast groups on destruction? (or in unsubscribe)

[knzo25]

nit: are we moving to header blocks?

[mojomex]

Do you mean

#ifndef ...
#define ...

versus

#pragma once

?

I strongly prefer pragma once for style, is there any discussion on this I have missed?

[knzo25]

nit: are we moving to header blocks?

[mojomex]

(see my other comment on udp.hpp)

[knzo25]

uniform initialization and const/constexpr for the 1500?

[mojomex]

It can be changed during runtime via set_mtu, but I agree with uniform initialization.

[mojomex]

Addressed in 9ea3a90.