Add netcode_server_create_error, distinguishing bind failures

The server-side mirror of netcode_client_create_error: each failure path
in server create records a NETCODE_SERVER_CREATE_ERROR_* code, queryable
via netcode_server_create_error() when create returns NULL.

Bind failures are reported separately from other socket errors, per
address family: a port already in use is the common operational failure
for dedicated servers, and callers want to react to it (try the next
port) differently than to a socket that could not be created at all.

With this, create failures are queryable on both client and server. The
running server intentionally has no state machine beyond
netcode_server_running: its only states are stopped and started, and
everything else is per-client.

Adds test_server_create_error covering every reachable code, including
real port-in-use bind collisions for both address families. Suite is now
42 tests.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: gafferongames

CLAUDE.md

@@ -14,7 +14,7 @@ independent implementations (C#, Go, Rust, TypeScript).
 - `sodium/` — vendored subset of libsodium, amalgamated into a single `sodium.h` +
   `sodium.c` pair (see `sodium/NOTES.md` for how it is generated and validated).
 - Build: CMake. `cmake -B build -DCMAKE_BUILD_TYPE=Release && cmake --build build --parallel`,
-  then `ctest --test-dir build --output-on-failure` runs the suite (41 tests). The
+  then `ctest --test-dir build --output-on-failure` runs the suite (42 tests). The
   `netcode_test` target compiles netcode.c into itself with `NETCODE_ENABLE_TESTS`, so it
   links only sodium. `-DNETCODE_SANITIZE=ON` adds ASan+UBSan (sodium gets ASan only);
   `-DNETCODE_FUZZ=ON` builds the `fuzz/` harnesses (libFuzzer where available, else a
@@ -31,10 +31,8 @@ independent implementations (C#, Go, Rust, TypeScript).
 
 This is a mature, disciplined, security-conscious C library that does exactly one thing
 and does it well. The protocol design is its strongest asset. The main weaknesses are
-maintainability of the single-file implementation (internal duplication) and error
-reporting that goes quiet at creation time and on the server side — the client's
-state machine covers connection errors well, but create returning NULL and the server
-API tell the integrator nothing about why something failed.
+maintainability of the single-file implementation (internal duplication) and per-packet
+allocation churn on the receive path.
 
 ### What's genuinely good
 
@@ -72,7 +70,7 @@ hard-disconnecting client doesn't wedge `recvfrom` (netcode.c:554), `IPV6_V6ONLY
 dual-stack IPv4+IPv6 sockets, loopback clients for integrated host-and-play, allocator
 override hooks, and full send/receive transport overrides. A built-in network simulator
 (latency/jitter/loss/duplication) makes the connection tests deterministic without
-touching real sockets. Few networking libraries ship this complete a test story: 41
+touching real sockets. Few networking libraries ship this complete a test story: 42
 unit + integration tests covering every client error state, reconnect, multi-server
 fallback, dual-stack, loopback — plus a soak test and a profiler. All pass today.
 
@@ -81,6 +79,19 @@ explicit `netcode_client_update(client, time)` — time is injected, not sampled
 makes the state machines testable and frame-loop friendly. The header is a clean ~300
 lines with zero dependencies beyond stdint.
 
+**Error reporting matches the transport's nature.** Asynchronous connection failures
+(denial, timeouts, token problems) surface through the client's negative
+`NETCODE_CLIENT_STATE_*` values polled from the game loop — the only channel that can
+carry errors that happen seconds after the call that caused them. Create failures are
+queryable: `netcode_client_create_error()` / `netcode_server_create_error()` report why
+create returned NULL, with server bind failures (port already in use — the common
+operational failure) distinguished from other socket errors per address family.
+Per-packet socket errors are deliberately ignored: UDP is unreliable, so a send error
+is semantically identical to a dropped packet, and a persistently dead socket surfaces
+the same way persistent loss does — as a connection timeout through the state machine.
+The running server deliberately has no state machine of its own: its only states are
+stopped and started (`netcode_server_running`), and everything else is per-client.
+
 ### What's not so good
 
 **Internal duplication is the biggest code-quality issue.**
@@ -100,24 +111,6 @@ default behavior is allocation churn proportional to packet rate, and the intern
 design (allocate → inspect → free) makes even keep-alives cost a round trip through the
 allocator.
 
-**Error reporting goes quiet outside the client state machine.** Client connection
-errors are reported well: denial, timeouts, and token problems are asynchronous by
-nature, and the negative `NETCODE_CLIENT_STATE_*` values polled from the game loop are
-the right mechanism for them — that is by design, not a gap. Per-packet socket errors
-being ignored (`sendto` results cast to void, `recvfrom` errors logged and dropped) is
-also by design, not a gap: UDP is unreliable, so a send error is semantically identical
-to a dropped packet, and the protocol must tolerate drops anyway. A persistently dead
-socket surfaces the same way persistent packet loss does — as a connection timeout
-through the state machine, which is the correct channel for an unreliable protocol.
-The actual gaps are the places the state machine can't reach. Client create failures
-are now queryable — when `netcode_client_create` returns NULL,
-`netcode_client_create_error()` reports which step failed (address parse, socket
-create per family, simulator-requires-port, allocation) — though the finer
-`NETCODE_SOCKET_ERROR_*` granularity (bind vs sockopt vs create) still stops inside
-the socket layer. The remaining gap is the server: create returning NULL is
-undifferentiated, and there is no state-machine equivalent — failures reduce to
-`netcode_server_running()` returning false with no why.
-
 **Small sharp edges:**
 - Global mutable state (log level, printf/assert hooks, the `netcode_init` reference
   count, static timers) means the library is single-threaded by design. The header now
@@ -141,7 +134,9 @@ which runs with a continuing assert handler so it exercises the guards in debug
 term independently; a zeroed client/server config gets default allocators instead of
 crashing; the network simulator uses a per-instance seeded xorshift64* instead of global
 `rand()`, so simulator runs are deterministic — pinned by
-test_network_simulator_determinism.)
+test_network_simulator_determinism; `netcode_client_create_error()` and
+`netcode_server_create_error()` report why create returned NULL, with server bind
+failures distinguished per address family.)
 
 **Process gaps.** CI now builds and runs the tests on all three platforms in Debug and
 Release, runs an ASan+UBSan leg, and smoke-fuzzes the parsing surface

netcode.c

@@ -3920,6 +3920,13 @@ struct netcode_server_t
     struct netcode_address_t receive_from[NETCODE_SERVER_MAX_RECEIVE_PACKETS];
 };
 
+static int server_create_error;
+
+int netcode_server_create_error()
+{
+    return server_create_error;
+}
+
 int netcode_server_socket_create( struct netcode_socket_t * socket,
                                   struct netcode_address_t * address,
                                   int send_buffer_size,
@@ -3934,8 +3941,24 @@ int netcode_server_socket_create( struct netcode_socket_t * socket,
     {
         if ( !config->override_send_and_receive )
         {
-            if ( netcode_socket_create( socket, address, send_buffer_size, receive_buffer_size ) != NETCODE_SOCKET_ERROR_NONE )
+            int socket_error = netcode_socket_create( socket, address, send_buffer_size, receive_buffer_size );
+
+            if ( socket_error != NETCODE_SOCKET_ERROR_NONE )
             {
+                // report bind failures separately: a port already in use is the common
+                // operational failure for dedicated servers, and callers want to react
+                // to it differently than to a socket that could not be created at all
+
+                if ( socket_error == NETCODE_SOCKET_ERROR_BIND_IPV4_FAILED || socket_error == NETCODE_SOCKET_ERROR_BIND_IPV6_FAILED )
+                {
+                    server_create_error = ( address->type == NETCODE_ADDRESS_IPV6 ) ? NETCODE_SERVER_CREATE_ERROR_BIND_SOCKET_IPV6_FAILED
+                                                                                    : NETCODE_SERVER_CREATE_ERROR_BIND_SOCKET_IPV4_FAILED;
+                }
+                else
+                {
+                    server_create_error = ( address->type == NETCODE_ADDRESS_IPV6 ) ? NETCODE_SERVER_CREATE_ERROR_CREATE_SOCKET_IPV6_FAILED
+                                                                                    : NETCODE_SERVER_CREATE_ERROR_CREATE_SOCKET_IPV4_FAILED;
+                }
                 return 0;
             }
         }
@@ -3949,6 +3972,8 @@ struct netcode_server_t * netcode_server_create_dual( NETCODE_CONST char * serve
     netcode_assert( config );
     netcode_assert( netcode.initialized );
 
+    server_create_error = NETCODE_SERVER_CREATE_ERROR_NONE;
+
     // tolerate a zeroed config: default the allocator functions so a forgotten
     // netcode_default_server_config is an inconvenience, not a crash
 
@@ -3968,12 +3993,14 @@ struct netcode_server_t * netcode_server_create_dual( NETCODE_CONST char * serve
     if ( netcode_parse_address( server_address1_string, &server_address1 ) != NETCODE_OK )
     {
         netcode_printf( NETCODE_LOG_LEVEL_ERROR, "error: failed to parse server public address\n" );
+        server_create_error = NETCODE_SERVER_CREATE_ERROR_PARSE_ADDRESS_FAILED;
         return NULL;
     }
 
     if ( server_address2_string != NULL && netcode_parse_address( server_address2_string, &server_address2 ) != NETCODE_OK )
     {
         netcode_printf( NETCODE_LOG_LEVEL_ERROR, "error: failed to parse server public address2\n" );
+        server_create_error = NETCODE_SERVER_CREATE_ERROR_PARSE_ADDRESS2_FAILED;
         return NULL;
     }
 
@@ -4017,6 +4044,7 @@ struct netcode_server_t * netcode_server_create_dual( NETCODE_CONST char * serve
     {
         netcode_socket_destroy( &socket_ipv4 );
         netcode_socket_destroy( &socket_ipv6 );
+        server_create_error = NETCODE_SERVER_CREATE_ERROR_ALLOCATE_SERVER_FAILED;
         return NULL;
     }
 
@@ -6962,6 +6990,70 @@ void test_client_create_error()
     }
 }
 
+void test_server_create_error()
+{
+    struct netcode_server_config_t server_config;
+    netcode_default_server_config( &server_config );
+
+    // successful create leaves the create error as NONE
+
+    {
+        struct netcode_server_t * server = netcode_server_create( "127.0.0.1:40000", &server_config, 0.0 );
+
+        check( server );
+        check( netcode_server_create_error() == NETCODE_SERVER_CREATE_ERROR_NONE );
+
+        netcode_server_destroy( server );
+    }
+
+    // bad first address
+
+    check( netcode_server_create( "not an address", &server_config, 0.0 ) == NULL );
+    check( netcode_server_create_error() == NETCODE_SERVER_CREATE_ERROR_PARSE_ADDRESS_FAILED );
+
+    // bad second address
+
+    check( netcode_server_create_dual( "127.0.0.1:40000", "not an address", &server_config, 0.0 ) == NULL );
+    check( netcode_server_create_error() == NETCODE_SERVER_CREATE_ERROR_PARSE_ADDRESS2_FAILED );
+
+    // a port already in use is reported as a bind failure, distinct from other socket errors (ipv4)
+
+    {
+        struct netcode_server_t * first_server = netcode_server_create( "127.0.0.1:40000", &server_config, 0.0 );
+
+        check( first_server );
+
+        check( netcode_server_create( "127.0.0.1:40000", &server_config, 0.0 ) == NULL );
+        check( netcode_server_create_error() == NETCODE_SERVER_CREATE_ERROR_BIND_SOCKET_IPV4_FAILED );
+
+        netcode_server_destroy( first_server );
+    }
+
+    // and the same over ipv6 reports the ipv6 bind error
+
+    {
+        struct netcode_server_t * first_server = netcode_server_create( "[::1]:40000", &server_config, 0.0 );
+
+        check( first_server );
+
+        check( netcode_server_create( "[::1]:40000", &server_config, 0.0 ) == NULL );
+        check( netcode_server_create_error() == NETCODE_SERVER_CREATE_ERROR_BIND_SOCKET_IPV6_FAILED );
+
+        netcode_server_destroy( first_server );
+    }
+
+    // server struct allocation failure
+
+    {
+        struct netcode_server_config_t failing_config;
+        netcode_default_server_config( &failing_config );
+        failing_config.allocate_function = test_failing_allocate_function;
+
+        check( netcode_server_create( "127.0.0.1:40000", &failing_config, 0.0 ) == NULL );
+        check( netcode_server_create_error() == NETCODE_SERVER_CREATE_ERROR_ALLOCATE_SERVER_FAILED );
+    }
+}
+
 void test_network_simulator_determinism()
 {
     // the network simulator has its own seeded rng, so two simulators given
@@ -9324,6 +9416,7 @@ void netcode_test()
         RUN_TEST( test_runtime_guards );
         RUN_TEST( test_init_and_defaults );
         RUN_TEST( test_client_create_error );
+        RUN_TEST( test_server_create_error );
         RUN_TEST( test_network_simulator_determinism );
         RUN_TEST( test_client_create );
         RUN_TEST( test_server_create );

netcode.h

@@ -100,6 +100,15 @@
 #define NETCODE_CLIENT_CREATE_ERROR_CREATE_SOCKET_IPV6_FAILED   5
 #define NETCODE_CLIENT_CREATE_ERROR_ALLOCATE_CLIENT_FAILED      6
 
+#define NETCODE_SERVER_CREATE_ERROR_NONE                        0
+#define NETCODE_SERVER_CREATE_ERROR_PARSE_ADDRESS_FAILED        1
+#define NETCODE_SERVER_CREATE_ERROR_PARSE_ADDRESS2_FAILED       2
+#define NETCODE_SERVER_CREATE_ERROR_CREATE_SOCKET_IPV4_FAILED   3
+#define NETCODE_SERVER_CREATE_ERROR_CREATE_SOCKET_IPV6_FAILED   4
+#define NETCODE_SERVER_CREATE_ERROR_BIND_SOCKET_IPV4_FAILED     5
+#define NETCODE_SERVER_CREATE_ERROR_BIND_SOCKET_IPV6_FAILED     6
+#define NETCODE_SERVER_CREATE_ERROR_ALLOCATE_SERVER_FAILED      7
+
 #define NETCODE_MAX_CLIENTS         256
 #define NETCODE_MAX_PACKET_SIZE     1200
 
@@ -252,6 +261,16 @@ struct netcode_server_t * netcode_server_create( NETCODE_CONST char * server_add
 
 struct netcode_server_t * netcode_server_create_dual( NETCODE_CONST char * server_address1, NETCODE_CONST char * server_address2, NETCODE_CONST struct netcode_server_config_t * config, double time );
 
+/*
+    If netcode_server_create or netcode_server_create_dual returns NULL, call this to find out why.
+    Returns the NETCODE_SERVER_CREATE_ERROR_* value from the most recent server create call,
+    or NETCODE_SERVER_CREATE_ERROR_NONE if that call succeeded. Bind failures are reported
+    separately from other socket errors because a port already in use is the common
+    operational failure for dedicated servers.
+*/
+
+int netcode_server_create_error();
+
 void netcode_server_destroy( struct netcode_server_t * server );
 
 void netcode_server_start( struct netcode_server_t * server, int max_clients );