========================================================
= std_net.h: Zero-Dependency Cross-Platform Networking =
========================================================

[Overview]
~~~~~~~~~~
Single-header C/C++ networking library for TCP sockets. Designed for simplicity,
portability, and zero dependencies. Automatically handles platform-specific
initialization (WSAStartup, SO_NOSIGPIPE, etc.) and provides unified API.

[Features]
~~~~~~~~~~
* IPv4/IPv6 support (Happy Eyeballs v2 implementation)
* Blocking/non-blocking modes
* Timeout support for all operations
* Unified error codes across platforms
* Auto-initialization and cleanup
* Optional C++ RAII wrapper
* Thread-safe error handling
* Header-only (just #include "std_net.h")

[Supported Platforms]
~~~~~~~~~~~~~~~~~~~~~
- Windows (Vista+)
- Linux
- macOS
- iOS
- Android
- FreeBSD
- Raspberry Pi
- ESP32 (with custom config)

[API Summary]
~~~~~~~~~~~~~

=== Core Types ===
stdnet_socket_t  - Opaque socket handle
STDNET_INVALID_SOCKET - Invalid socket constant

=== Initialization ===
int  stdnet_init(void)        - Auto-called on first API use (returns STDNET_OK)
void stdnet_cleanup(void)     - Manual cleanup (for Valgrind/LSan)

=== Connection Management ===
int stdnet_connect(stdnet_socket_t*, const char* host, int port)
int stdnet_connect_timeout(stdnet_socket_t*, const char* host, int port, int timeout_ms)
int stdnet_listen(stdnet_socket_t*, const char* host, int port, int backlog)
int stdnet_accept(stdnet_socket_t* server, stdnet_socket_t* client)
void stdnet_close(stdnet_socket_t*)

=== Data Transfer ===
int stdnet_send(stdnet_socket_t*, const void* data, int size)
int stdnet_recv(stdnet_socket_t*, void* buffer, int size)

=== Socket Options ===
int stdnet_set_blocking(stdnet_socket_t*, int blocking)  - 0=non-blocking, 1=blocking

=== Event Handling ===
int stdnet_wait(stdnet_socket_t*, int events, int timeout_ms)

=== Error Handling ===
int stdnet_last_error(void)  - Get last thread-local error

[Event Flags for stdnet_wait()]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
STDNET_WAIT_READ   (1 << 0)  - Data available for reading
STDNET_WAIT_WRITE  (1 << 1)  - Ready for writing
STDNET_WAIT_ERROR  (1 << 2)  - Error condition

[Error Codes]
~~~~~~~~~~~~~
STDNET_OK              =  0   - Success
STDNET_ERR_GENERIC     = -1   - Unspecified error
STDNET_ERR_PARAM       = -2   - Invalid parameter
STDNET_ERR_ADDR        = -3   - Address resolution error
STDNET_ERR_CONNECT     = -4   - Connection failed
STDNET_ERR_BIND        = -5   - Bind failed
STDNET_ERR_LISTEN      = -6   - Listen failed
STDNET_ERR_ACCEPT      = -7   - Accept failed
STDNET_ERR_SEND        = -8   - Send error
STDNET_ERR_RECV        = -9   - Receive error
STDNET_ERR_WOULD_BLOCK = -10  - Operation would block
STDNET_ERR_TIMEOUT     = -11  - Operation timed out
STDNET_ERR_CLOSED      = -12  - Connection closed
STDNET_ERR_IOS_SIGPIPE = -13  - iOS/macOS SIGPIPE error

[C++ RAII Wrapper]
~~~~~~~~~~~~~~~~~~
namespace stdnet {
    class socket {
    public:
        socket() noexcept;
        socket(socket&&) noexcept;
        ~socket();
        
        int connect(const char* host, int port, int timeout_ms = -1);
        int listen(const char* host, int port, int backlog=128);
        int accept(socket& out);
        int send(const void* data, int size);
        int recv(void* buf, int size);
        int set_blocking(bool b);
        int wait(int events, int timeout_ms);
        void close();
        bool valid() const;
    };
}

[Usage]
~~~~~~~
1. Add in one C/C++ file:
   #define STD_NET_IMPLEMENTATION
   #include "std_net.h"

2. In other files:
   #include "std_net.h"

[Example: TCP Echo Client (C)]
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#define STD_NET_IMPLEMENTATION
#include "std_net.h"
#include <stdio.h>

int main() {
    stdnet_socket_t s = STDNET_INVALID_SOCKET;
    if (stdnet_connect_timeout(&s, "example.com", 80, 3000) < 0) {
        fprintf(stderr, "Connect failed: %d\n", stdnet_last_error());
        return 1;
    }
    
    const char* req = "GET / HTTP/1.1\r\nHost: example.com\r\n\r\n";
    stdnet_send(&s, req, (int)strlen(req));
    
    char buf[4096];
    while (1) {
        int r = stdnet_wait(&s, STDNET_WAIT_READ, 2000);
        if (r == STDNET_ERR_TIMEOUT) break;
        if (r < 0) break;
        
        int n = stdnet_recv(&s, buf, sizeof(buf));
        if (n <= 0) break;
        fwrite(buf, 1, n, stdout);
    }
    
    stdnet_close(&s);
    stdnet_cleanup();
    return 0;
}

[Example: C++ RAII Version]
~~~~~~~~~~~~~~~~~~~~~~~~~~~
#include "std_net.h"

int main() {
    stdnet::socket s;
    if (s.connect("example.com", 80, 3000) != STDNET_OK) {
        // Handle error
        return 1;
    }
    
    s.send("PING", 4);
    
    char buf[128];
    if (s.wait(stdnet::wait_read, 1000) > 0) {
        int n = s.recv(buf, sizeof(buf));
        // Process data
    }
    
    return 0;
}

[Advanced Features]
~~~~~~~~~~~~~~~~~~~
1. Happy Eyeballs v2 implementation:
   - Parallel connection attempts to IPv4/IPv6 addresses
   - Optimized connection establishment
   - Automatic fallback to best available protocol

2. Platform Optimizations:
   - epoll on Linux
   - kqueue on BSD/macOS
   - SO_NOSIGPIPE on Apple systems
   - SO_EXCLUSIVEADDRUSE on Windows

3. Android-specific:
   - Automatic SO_RCVTIMEO/SO_SNDTIMEO setting
   - Network permission handling in app manifest

[License (MIT)]
~~~~~~~~~~~~~~~
Copyright (c) 2025

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

[Contributing]
~~~~~~~~~~~~~~
1. Report issues on GitHub
2. Follow platform-specific guidelines
3. Maintain zero-dependency policy
4. Keep API backward compatible

[Version History]
~~~~~~~~~~~~~~~~~
v1.0 (2025-08-14) - Initial release