refactor(facade): migrate all facade APIs from throw to Result<T> (#952)

* refactor(facade): migrate all facade APIs from throw to Result<T>

Replace 30 throw statements across 5 facade files with Result<T>
return values, unifying error handling with the ecosystem convention.

Changes per facade (tcp, quic, udp, websocket, http):
- validate_* return type: void -> VoidResult
- create_client/create_server return type: shared_ptr -> Result<shared_ptr>
- create_connection_pool return type: shared_ptr -> Result<shared_ptr>
- throw std::invalid_argument -> return error_void(-1, msg, source)
- throw std::runtime_error -> return error<T>(code, msg, source)
- Success paths: return ptr -> return ok(ptr)

Also fix broken markdown anchors in docs TOC files.

Closes #951

* test(facade): update facade tests for Result<T> return types

Migrate all facade test assertions from exception-based to Result-based:
- EXPECT_THROW -> result.is_err()
- EXPECT_NO_THROW(var = ...) -> ASSERT_TRUE(result.is_ok()); var = result.value()
- Direct assignment -> result check + value extraction

* fix(test): resolve conflicting 'auto result' redeclaration in test scopes

Rename second 'auto result' to 'send_result' or 'stop_result' in
tests where create_* result and interface method result share scope.

* fix(benchmarks): unwrap Result<T> from facade create methods

facade create_client() and create_server() now return Result<shared_ptr<T>>
instead of shared_ptr<T>. Update all call sites in the benchmark file to
unwrap the Result with .value() before using the pointer.

* fix(tests): update facade tests for Result<T> return types

Facade create methods now return Result<shared_ptr<T>> instead of
throwing exceptions or returning raw pointers. Update tests to:
- Use .is_ok() and .value() to unwrap Result before nullptr checks
- Replace EXPECT_THROW(invalid_argument) with is_err() assertions
  for port validation tests across TCP, UDP, HTTP, WebSocket, and
  QUIC facades

* fix(tests): suppress nodiscard warnings for VoidResult in e2e tests

start_server(), stop_server(), start_client(), stop_client(), and
send_packet() now return [[nodiscard]] VoidResult. Cast all call sites
to (void) to suppress -Werror=unused-result warnings.

* docs(facade): update guide for Result<T> return types

Update all facade code examples and API signatures to reflect the
migration from throw-based to Result<T> return types in create_client(),
create_server(), and create_connection_pool() methods.

Author: kcenon

benchmarks/facade_vs_direct_bench.cpp

@@ -138,11 +138,16 @@ static void BM_FacadeClient_Create(benchmark::State& state)
 	{
 		try
 		{
-			auto client = facade.create_client({
+			auto client_result = facade.create_client({
 				.host = "127.0.0.1",
 				.port = 8080,
 				.client_id = "bench_client"
 			});
+			if (client_result.is_err())
+			{
+				break;
+			}
+			auto client = client_result.value();
 			benchmark::DoNotOptimize(client);
 			// Allow thread cleanup between iterations
 			(void)client->stop();
@@ -188,10 +193,15 @@ static void BM_FacadeServer_Create(benchmark::State& state)
 	{
 		try
 		{
-			auto server = facade.create_server({
+			auto server_result = facade.create_server({
 				.port = 8080,
 				.server_id = "bench_server"
 			});
+			if (server_result.is_err())
+			{
+				break;
+			}
+			auto server = server_result.value();
 			benchmark::DoNotOptimize(server);
 			// Ensure cleanup before next iteration
 			(void)server->stop();
@@ -342,10 +352,16 @@ static void BM_FacadeAPI_SendThroughput(benchmark::State& state)
 	try
 	{
 		// Setup server via facade
-		server = facade.create_server({
+		auto server_result = facade.create_server({
 			.port = port,
 			.server_id = "facade_bench_server"
 		});
+		if (server_result.is_err())
+		{
+			state.SkipWithError("Failed to create facade server");
+			return;
+		}
+		server = server_result.value();
 		auto start_result = server->start(port);
 		if (start_result.is_err())
 		{
@@ -357,11 +373,18 @@ static void BM_FacadeAPI_SendThroughput(benchmark::State& state)
 		std::this_thread::sleep_for(std::chrono::milliseconds(50));
 
 		// Setup client via facade
-		client = facade.create_client({
+		auto client_result = facade.create_client({
 			.host = "127.0.0.1",
 			.port = port,
 			.client_id = "facade_bench_client"
 		});
+		if (client_result.is_err())
+		{
+			(void)server->stop();
+			state.SkipWithError("Failed to create facade client");
+			return;
+		}
+		client = client_result.value();
 		auto connect_result = client->start("127.0.0.1", port);
 		if (connect_result.is_err())
 		{
@@ -638,10 +661,16 @@ static void BM_FacadeAPI_FullLifecycle(benchmark::State& state)
 
 	try
 	{
-		server = facade.create_server({
+		auto server_result = facade.create_server({
 			.port = port,
 			.server_id = "facade_lifecycle_server"
 		});
+		if (server_result.is_err())
+		{
+			state.SkipWithError("Failed to create server");
+			return;
+		}
+		server = server_result.value();
 		auto start_result = server->start(port);
 		if (start_result.is_err())
 		{
@@ -664,11 +693,16 @@ static void BM_FacadeAPI_FullLifecycle(benchmark::State& state)
 		try
 		{
 			// Create via facade
-			auto client = facade.create_client({
+			auto client_result = facade.create_client({
 				.host = "127.0.0.1",
 				.port = port,
 				.client_id = "facade_lifecycle_client"
 			});
+			if (client_result.is_err())
+			{
+				continue;
+			}
+			auto client = client_result.value();
 
 			// Connect
 			auto connect_result = client->start("127.0.0.1", port);

docs/API_REFERENCE_FACADES.md

@@ -18,16 +18,16 @@ Facade API documentation for the Network System library, covering TCP, UDP, WebS
 
 ## Table of Contents
 
-- [Overview](#overview)
-- [C++20 Concepts](#c20-concepts)
-- [Core Classes](#core-classes)
-- [Networking Components](#networking-components)
-- [Utility Classes](#utility-classes)
-- [Error Handling](#error-handling)
-- [Configuration](#configuration)
-- [Examples](#examples)
-- [Thread Safety](#thread-safety)
-- [Platform-Specific Notes](#platform-specific-notes)
+- Overview
+- C++20 Concepts
+- Core Classes
+- Networking Components
+- Utility Classes
+- Error Handling
+- Configuration
+- Examples
+- Thread Safety
+- Platform-Specific Notes
 
 ## Overview
 

docs/API_REFERENCE_PROTOCOLS.md

@@ -18,10 +18,10 @@ Protocol-level API documentation for the Network System library, covering low-le
 
 ## Table of Contents
 
-- [Protocol Handlers](#protocol-handlers)
-- [Thread Integration API](#thread-integration-api)
-- [Version History](#version-history)
-- [License](#license)
+- Protocol Handlers
+- Thread Integration API
+- Version History
+- License
 
 ## Protocol Handlers