Refactor TCPSocket::setup Timeout and Error Handling

[srvald]

Refactor TCPSocket::setup

Description

This PR refactors the TCPSocket::setup() method to resolve the blocking behavior during network failures.

The implementation now introduces an asynchronous approach to enforce a connection timeout and capture socket errors.

Step-by-Step Modifications

1. Signature Update (Timeout Parameter)

• Added a new timeout parameter (std::chrono::milliseconds) to the setup() function. This makes it possible to define exactly how long to wait for a connection before giving up. Otherwise, the code blocks indefinitely, keeping the thread hanging even if the number of max tries is set to 1. The default value has been set to 500 ms.

2. Error Tracking (std::error_code)

• Introduced a std::error_code socket_error variable.
• Now, getLastSocketErrorCode() is called immediately after any failure to store the exact system reason (e.g., ECONNREFUSED, EHOSTUNREACH) so it can be reported later.

3. Non-Blocking Connection Logic

• State Change: The socket is temporarily set to non-blocking mode using fcntl() and O_NONBLOCK.
• Async Connect: ::connect() is called. If it returns EINPROGRESS, the code now hands control over to ::select().
• Timeout Enforcement: select() waits for the socket to become writable, strictly bounded by the newly provided timeout parameter.
• Error Verification: If select() indicates readiness, ::getsockopt(..., SO_ERROR, ...) is used to verify if the connection actually succeeded or if it failed in the background.
• State Restoration: The socket is restored to its original blocking state before proceeding.

4. Proper Resource Cleanup on Failure

• If socket_fd_ is created but the connection attempt fails, it is now properly closed.
• Added ::ur_close(socket_fd_) and reset to INVALID_SOCKET inside the failure branches within the for loop to properly release resources. Also added error capturing if ::socket() creation fails directly.

5. Improved Logging & Debugging

• Replaced the generic and hardcoded log message ("Please check that the robot is booted and reachable...") with the exact system string translated by socket_error.message().
• Logs will now report "Reason: Connection refused", "Reason: Operation not permitted", or "Reason: Connection timed out", improving troubleshooting capabilities for end users.

Testing Performed

• Connection Refused: Pointed to an active IP with a closed port. Verified the code bypasses select() and fails immediately.

• Connection Timed Out: Simulated a network blackhole (e.g., using a dead IP). Verified the code waits exactly for the timeout duration before logging a timeout error.

• Host Unreachable: Pointed to an invalid subnet. Verified immediate routing error capture.

---

Note

Medium Risk
Changes core TCP connection establishment logic (non-blocking connect + select()/getsockopt()), which can affect connectivity behavior across platforms and edge cases like fd limits/timeouts.

Overview
TCPSocket::setup() now accepts an additional timeout (default 500ms) and uses a non-blocking connect with select() to enforce connection timeouts instead of potentially blocking indefinitely.

Connection attempts now capture and surface the underlying std::error_code reason in retry logs, add extra failure-path cleanup (close/reset fd), and include a non-Windows guard for FD_SETSIZE overflow before using select().

^{Reviewed by Cursor Bugbot for commit 6b46158. Bugbot is set up for automated code reviews on this repo. Configure here.}

[codecov]

Codecov Report

❌ Patch coverage is 58.49057% with 22 lines in your changes missing coverage. Please review.
✅ Project coverage is 77.20%. Comparing base (de90b90) to head (6b46158).
⚠️ Report is 4 commits behind head on master.

Files with missing lines	Patch %	Lines
src/comm/tcp_socket.cpp	58.49%	14 Missing and 8 partials ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master     #511      +/-   ##
==========================================
+ Coverage   77.14%   77.20%   +0.06%     
==========================================
  Files         116      116              
  Lines        6354     6415      +61     
  Branches     2764     2792      +28     
==========================================
+ Hits         4902     4953      +51     
- Misses       1101     1106       +5     
- Partials      351      356       +5     

Flag	Coverage Δ
check_version_ur10-3.15.8	11.37% <41.50%> (-0.81%)	⬇️
check_version_ur10e-10.11.0	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur10e-5.15.2	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur12e-10.12.1	11.96% <41.50%> (+0.17%)	⬆️
check_version_ur12e-5.25.1	12.22% <52.83%> (-0.35%)	⬇️
check_version_ur15-10.12.1	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur15-5.25.1	11.96% <41.50%> (+0.02%)	⬆️
check_version_ur16e-10.12.1	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur16e-5.25.1	12.22% <52.83%> (+0.29%)	⬆️
check_version_ur18-10.12.1	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur18-5.25.1	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur20-10.12.1	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur20-5.25.1	12.22% <52.83%> (+0.29%)	⬆️
check_version_ur3-3.14.3	11.96% <41.50%> (-0.03%)	⬇️
check_version_ur30-10.12.1	11.96% <41.50%> (+0.17%)	⬆️
check_version_ur30-5.25.1	11.96% <41.50%> (+0.17%)	⬆️
check_version_ur3e-10.11.0	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur3e-5.9.4	12.01% <41.50%> (+0.07%)	⬆️
check_version_ur5-3.15.8	12.01% <41.50%> (+0.02%)	⬆️
check_version_ur5e-10.11.0	11.96% <41.50%> (+0.17%)	⬆️
check_version_ur5e-5.12.8	12.01% <41.50%> (+0.22%)	⬆️
check_version_ur7e-10.11.0	12.01% <41.50%> (+0.27%)	⬆️
check_version_ur7e-5.22.2	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur8long-10.12.1	11.96% <41.50%> (+0.22%)	⬆️
check_version_ur8long-5.25.1	11.96% <41.50%> (+0.02%)	⬆️
python_scripts	75.90% <ø> (ø)
start_ursim	84.24% <ø> (-0.06%)	⬇️
ur20-latest	72.76% <58.49%> (-0.01%)	⬇️
ur5-3.14.3	72.53% <58.49%> (+0.05%)	⬆️
ur5e-10.11.0	66.67% <58.49%> (+0.07%)	⬆️
ur5e-10.12.0	67.99% <58.49%> (+0.14%)	⬆️
ur5e-10.7.0	66.26% <58.49%> (-0.11%)	⬇️
ur5e-5.9.4	73.34% <58.49%> (+0.02%)	⬆️

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.

[cursor]

Cursor Bugbot has reviewed your changes using default mode and found 1 potential issue.

^{Reviewed by Cursor Bugbot for commit 6618266. Configure here.}

[urfeex]

To be honest, I'm not sure whether this actually improves things a lot. Am I correct, that you want to solve UniversalRobots/Universal_Robots_ROS2_Driver#838?

From my understanding, that issue isn't about the blocking connect itself. For example, you can start the primary pipeline example from the client library with a wrong IP / an IP address that doesn't host a primary interface and just close it using CTRL-C.

Thus, I would expect that UniversalRobots/Universal_Robots_ROS2_Driver#838 is more a problem of signal forwarding inside the ROS node.

This PR seems to complicate the socket connection quite a lot and I'd like to challenge the requirement for actually doing this.

[srvald]

Hi @urfeex. Well... this PR doesn't fully resolve [#838] UniversalRobots/Universal_Robots_ROS2_Driver#838) on its own.

Regarding the primary_pipeline example you mentioned, the ::connect() call does block the thread, but since it's a standard C++ application, when CTRL-C is hit, the OS terminates the process immediately, but it is able to do it because is a standard application, isn't it?

With this PR implemented, the output on the teminal when using a wrong IP for that example will be:

~/ws_rol/ur_c/Universal_Robots_Client_Library/b/examples tcp_socket_timeout > ./primary_pipeline_example 1.2.3.4 
[1780382828.827426] ERROR /home/mirserv/ws_rolling/ur_client_library/Universal_Robots_Client_Library/src/comm/tcp_socket.cpp 270: Failed to connect to robot on IP 1.2.3.4:30001. Reason: Connection timed out. Retrying in 10 seconds. 
[1780382839.328329] ERROR /home/mirserv/ws_rolling/ur_client_library/Universal_Robots_Client_Library/src/comm/tcp_socket.cpp 270: Failed to connect to robot on IP 1.2.3.4:30001. Reason: Connection timed out. Retrying in 10 seconds. 
[1780382849.829394] ERROR /home/mirserv/ws_rolling/ur_client_library/Universal_Robots_Client_Library/src/comm/tcp_socket.cpp 270: Failed to connect to robot on IP 1.2.3.4:30001. Reason: Connection timed out. Retrying in 10 seconds. 
[1780382860.330338] ERROR /home/mirserv/ws_rolling/ur_client_library/Universal_Robots_Client_Library/src/comm/tcp_socket.cpp 270: Failed to connect to robot on IP 1.2.3.4:30001. Reason: Connection timed out. Retrying in 10 seconds. 

Without the PR, it will be blocked without showing any output:

~/ws_rol/ur_c/Universal_Robots_Client_Library/b/examples master > ./primary_pipeline_example 1.2.3.4 
^C
~/ws_rol/ur_c/Universal_Robots_Client_Library/b/examples master > 

In a ROS 2 node like urscript_interface, it is different. ROS 2 captures the CTRL+C signal to do a clean shutdown, meaning the OS doesn't just kill the process anymore, as done in the C++ application, because ROS 2 catches it and flips its internal shutdown flag, but it cannot interrupt the socket block. So, the node just hangs there.

Currently, when urscript_interface is used with a wrong IP, it gets trapped in this chain:

1. m_secondary_stream->connect() is called in the constructor.

https://github.com/UniversalRobots/Universal_Robots_ROS2_Driver/blob/417f7323bea6472fa52077aea0428c3b7b273a5a/ur_robot_driver/src/urscript_interface.cpp#L72

2. It enters TCPSocket::setup and hits the while (!connected) loop.

Universal_Robots_Client_Library/src/comm/tcp_socket.cpp

Lines 75 to 76 in 627cf20

	bool TCPSocket::setup(const std::string& host, const int port, const size_t max_num_tries,
	const std::chrono::milliseconds reconnection_time)

Universal_Robots_Client_Library/src/comm/tcp_socket.cpp

Line 107 in 627cf20

while (!connected)

3. It calls the OS ::connect(), which has no timeout.

Universal_Robots_Client_Library/include/ur_client_library/comm/tcp_socket.h

Line 61 in 627cf20

return ::connect(socket_fd, address, static_cast<socklen_t>(address_len)) == 0;

Because of this, the thread is blocked. This makes the max_num_tries parameter completely useless, it gets stuck on the very first try and freezes the node, preventing any CTRL+C response.

This PR introduces a timeout using select(). Now, if the IP is unreachable, the attempt times out quickly (e.g., 500ms). This allows max_num_tries to actually work as intended, iterate, and eventually return that it couldn't connect, freeing the thread.

To fix this at the node level, I actually tested moving m_secondary_stream->connect() into a ROS Timer with max_num_tries set to 1, and it worked perfectly (the main node didn't block and CTRL+C worked instantly). However, if I recall correctly, we previously discussed holding off on that node-level change because the upcoming primary client refactor might handle it better.

Let me know if this makes sense or if you think I should take a different approach.