improve network targets (#404)

Makes improvements focused on network targets, including:

WSAStartup and WSACleanup are now only called the first time needed and
upon stumpless_free_all, respectively, instead of once for each network
target opened/closed.

TCP network targets using the sys/socket.h implementation will detect a
FIN message before a send and fail immediately. Before this change, the
closure of the stream was not caught noticed and message sends would return
with a success code despite not having being received by the remote end.
TCP network targets using the Winsock implementation still exhibit the
later (broken) behavior.

ChangeLog.md

@@ -9,7 +9,7 @@ fixes, check out the
 [roadmap](https://github.com/goatshriek/stumpless/blob/master/docs/roadmap.md).
 
 
-## [2.2.0] - 2023-12-10
+## [2.2.0] - 2024-02-05
 ### Added 
  - @since format check enforcement in CI pipeline.
  - `single-file` target for rollup `.c` and `.h` files.
@@ -18,6 +18,9 @@ fixes, check out the
  - Deadlock potential in `stumpless_set_entry_hostname` and
    `stumpless_set_entry_procid` when validation fails.
  - Builds in ANSI C environments.
+ - `sys/socket.h`-based TCP network targets will immediately fail with an error
+   if the remote end sends a FIN message, instead of waiting for `send` to fail,
+   possibly sending messages that are not actually received by the remote end.
 
 
 ## [2.1.0] - 2022-11-13

docs/roadmap.md

@@ -10,12 +10,6 @@ or want to make a suggestion, please submit an issue on the project's
    as to a local file as well as a network server. Target chains will allow this
    stream to be defined as a logging target, and a logging call only made to
    this instead of manually logging to each target.
- * [ADD] **Improved network target error detection**
-   Network targets do not currently detect errors that they would be able to in
-   some cases, such as with `select` or `poll`. This may lead to a connection
-   being left open for longer than necessary if the error is already detected.
-   This change will improve error detection in network targets to reduce the
-   time needed to pass these errors on to callers.
 
 
 ## 3.0.0 (next major release)

include/private/config/have_sys_socket.h

@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 
 /*
- * Copyright 2019-2020 Joel E. Anderson
+ * Copyright 2019-2024 Joel E. Anderson
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -52,10 +52,65 @@ sys_socket_reopen_udp4_target( struct network_target *target );
 struct network_target *
 sys_socket_reopen_udp6_target( struct network_target *target );
 
+/**
+ * Send a message to a TCP-based network target.
+ *
+ * **Thread Safety: MT-Safe**
+ * This function is thread safe.
+ *
+ * **Async Signal Safety: AS-Unsafe lock**
+ * This function is not safe to call from signal handlers as some targets make
+ * use of non-reentrant locks to coordinate access.
+ *
+ * **Async Cancel Safety: AC-Unsafe lock**
+ * This function is not safe to call from threads that may be asynchronously
+ * cancelled, due to the use of locks that may be left locked.
+ *
+ * @since release v2.2.0
+ *
+ * @param target The network target to send the message to.
+ *
+ * @param msg The message to send to the target.
+ *
+ * @param msg_size The size of the message, in bytes.
+ *
+ * @return A positive value if no error was encountered, -1 otherwise. If an
+ * error is encountered, an error code is set appropriately.
+ */
+int
+sys_socket_sendto_tcp_target( struct network_target *target,
+                              const char *msg,
+                              size_t msg_size );
+
+/**
+ * Send a message to a UDP-based network target.
+ *
+ * **Thread Safety: MT-Safe**
+ * This function is thread safe.
+ *
+ * **Async Signal Safety: AS-Unsafe lock**
+ * This function is not safe to call from signal handlers as some targets make
+ * use of non-reentrant locks to coordinate access.
+ *
+ * **Async Cancel Safety: AC-Unsafe lock**
+ * This function is not safe to call from threads that may be asynchronously
+ * cancelled, due to the use of locks that may be left locked.
+ *
+ * @since release v2.2.0
+ *
+ * @param target The network target to send the message to.
+ *
+ * @param msg The message to send to the target.
+ *
+ * @param msg_size The size of the message, in bytes.
+ *
+ * @return A positive value if no error was encountered, -1 otherwise. If an
+ * error is encountered, an error code is set appropriately.
+ */
 int
-sys_socket_sendto_target( struct network_target *target,
-                          const char *msg,
-                          size_t msg_length );
+sys_socket_sendto_udp_target( const struct network_target *target,
+                              const char *msg,
+                              size_t msg_size );
 
 int
 sys_socket_network_target_is_open( const struct network_target *target );

include/private/config/have_winsock2.h

@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 
 /*
- * Copyright 2018-2020 Joel E. Anderson
+ * Copyright 2018-2024 Joel E. Anderson
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -26,6 +26,27 @@
 void
 winsock2_close_network_target( const struct network_target *target );
 
+/**
+ * Runs WSACleanup if WSA has already been started.
+ *
+ * **Thread Safety: MT-Safe**
+ * This function is thread safe.
+ *
+ * **Async Signal Safety: AS-Unsafe lock**
+ * This function is not safe to call from signal handlers as some targets make
+ * use of non-reentrant locks to coordinate access.
+ *
+ * **Async Cancel Safety: AC-Unsafe lock**
+ * This function is not safe to call from threads that may be asynchronously
+ * cancelled, due to the use of lock schemes that may be left locked.
+ *
+ * @since release v2.2.0
+ *
+ * @return The return code from WSACleanup.
+ */
+int
+winsock2_free_all( void );
+
 struct network_target *
 winsock2_init_network_target( struct network_target *target );
 
@@ -53,13 +74,65 @@ winsock2_reopen_udp4_target( struct network_target *target );
 struct network_target *
 winsock2_reopen_udp6_target( struct network_target *target );
 
+/**
+ * Send a message to a TCP-based network target.
+ *
+ * **Thread Safety: MT-Safe**
+ * This function is thread safe.
+ *
+ * **Async Signal Safety: AS-Unsafe lock**
+ * This function is not safe to call from signal handlers as some targets make
+ * use of non-reentrant locks to coordinate access.
+ *
+ * **Async Cancel Safety: AC-Unsafe lock**
+ * This function is not safe to call from threads that may be asynchronously
+ * cancelled, due to the use of locks that may be left locked.
+ *
+ * @since release v2.2.0
+ *
+ * @param target The network target to send the message to.
+ *
+ * @param msg The message to send to the target.
+ *
+ * @param msg_size The size of the message, in bytes.
+ *
+ * @return A positive value if no error was encountered, -1 otherwise. If an
+ * error is encountered, an error code is set appropriately.
+ */
 int
-winsock2_sendto_target( struct network_target *target,
-                        const char *msg,
-                        size_t msg_length );
+winsock2_sendto_tcp_target( const struct network_target *target,
+                            const char *msg,
+                            size_t msg_size );
 
-struct network_target *
-winsock2_set_network_port( struct network_target *target, const char *port );
+/**
+ * Send a message to a UDP-based network target.
+ *
+ * **Thread Safety: MT-Safe**
+ * This function is thread safe.
+ *
+ * **Async Signal Safety: AS-Unsafe lock**
+ * This function is not safe to call from signal handlers as some targets make
+ * use of non-reentrant locks to coordinate access.
+ *
+ * **Async Cancel Safety: AC-Unsafe lock**
+ * This function is not safe to call from threads that may be asynchronously
+ * cancelled, due to the use of locks that may be left locked.
+ *
+ * @since release v2.2.0
+ *
+ * @param target The network target to send the message to.
+ *
+ * @param msg The message to send to the target.
+ *
+ * @param msg_size The size of the message, in bytes.
+ *
+ * @return A positive value if no error was encountered, -1 otherwise. If an
+ * error is encountered, an error code is set appropriately.
+ */
+int
+winsock2_sendto_udp_target( const struct network_target *target,
+                            const char *msg,
+                            size_t msg_size );
 
 int
 winsock2_network_target_is_open( const struct network_target *target );

include/private/config/locale/bg-bg.h

@@ -171,6 +171,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] and inet_pton failed to resolve the name"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 // todo translate
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "chosen network protocol is unsupported"

include/private/config/locale/bn-in.h

@@ -164,6 +164,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] and inet_pton failed to resolve the name"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "নির্বাচিত নেটওয়ার্ক প্রোটোকল অসমর্থিত"
 

include/private/config/locale/cz-cz.h

@@ -164,6 +164,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] and inet_pton failed to resolve the name"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "vybraný síťový protokol není podporován"
 

include/private/config/locale/da-dk.h

@@ -155,6 +155,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] og inet_pton fejlede i at løse navnet"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "valgte nætværks protokol er ikke støttet"
 

include/private/config/locale/de-de.h

@@ -179,6 +179,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] and inet_pton failed to resolve the name"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 // todo translate
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "chosen network protocol is unsupported"

include/private/config/locale/el-gr.h

@@ -167,6 +167,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] and inet_pton failed to resolve the name"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 # define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "το πρωτόκολλο του δικτύου που επιλέχθηκε δεν υποστηρίζεται"
 

include/private/config/locale/en-us.h

@@ -1,7 +1,7 @@
 /* SPDX-License-Identifier: Apache-2.0 */
 
 /*
- * Copyright 2020-2023 Joel E. Anderson
+ * Copyright 2020-2024 Joel E. Anderson
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -158,6 +158,9 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] and inet_pton failed to resolve the name"
 
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "chosen network protocol is unsupported"
 

include/private/config/locale/es-es.h

@@ -157,6 +157,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] y inet_pton fallaron en resolver el nombre"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "protocolo de red elegido no soportado"
 

include/private/config/locale/fr-fr.h

@@ -155,6 +155,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] et inet_pton échec de résolvez le nom"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "le protocol réseaux choisi n'est pas supporté"
 

include/private/config/locale/he-il.h

@@ -156,6 +156,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "לא הצליחו לפתור שם זה gethostbyname[2] וגם inet_pton"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "פרוטוקול הרשת שנבחר אינו נתמך"
 

include/private/config/locale/hi-in.h

@@ -159,6 +159,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] and inet_pton failed to resolve the name"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "चुना गया नेटवर्क प्रोटोकॉल असमर्थित है"
 

include/private/config/locale/hu-hu.h

@@ -161,6 +161,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] és inet_pton nem tudta feloldani a nevet"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "a kiválasztott hálózati protokoll nem támogatott"
 

include/private/config/locale/it-it.h

@@ -157,6 +157,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] e inet_pton fallita realizzare il nome"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "il protocollo di rete non è supportato"
 

include/private/config/locale/pl-pl.h

@@ -167,6 +167,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] and inet_pton failed to resolve the name"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "wybrany protokół sieciowy nie jest obsługiwany"
 

include/private/config/locale/pt-br.h

@@ -158,6 +158,10 @@
 #  define L10N_NAME_RESOLUTION_FAILED_ERROR_MESSAGE \
 "gethostbyname[2] and inet_pton failed to resolve the name"
 
+// todo translate
+#  define L10N_NETWORK_CLOSED_ERROR_MESSAGE \
+"the network connection is closed"
+
 #  define L10N_NETWORK_PROTOCOL_UNSUPPORTED_ERROR_MESSAGE \
 "o protocolo de rede escolhido não é suportado"