Add some github workflow

biaks · biaks · commit 4e466bf7aa3c · 2026-02-17T00:20:59.000+03:00
diff --git a/.github/workflows/cmake.yml b/.github/workflows/cmake.yml
@@ -0,0 +1,30 @@
+name: CMake
+
+on:
+  push:
+    branches: [ master ]
+  pull_request:
+    branches: [ master ]
+
+env:
+  # Customize the CMake build type here (Release, Debug, RelWithDebInfo, etc.)
+  BUILD_TYPE: Release
+
+jobs:
+  build:
+    # The CMake configure and build commands are platform agnostic and should work equally well on Windows or Mac.
+    # You can convert this to a matrix build if you need cross-platform coverage.
+    # See: https://docs.github.com/en/free-pro-team@latest/actions/learn-github-actions/managing-complex-workflows#using-a-build-matrix
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+
+    - name: Configure CMake
+      # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
+      # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
+      run: cmake -B ${{github.workspace}}/build -DIP_SOCKETS_CPP_LITE_BUILD_EXAMPLES=ON -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}}
+
+    - name: Build
+      # Build your program with the given configuration
+      run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
diff --git a/readme.md b/readme.md
@@ -1,15 +1,39 @@
 # ip-sockets-cpp-lite 🔌
 
+[![Build examples](https://github.com/biaks/ip-sockets-cpp-lite/actions/workflows/cmake.yml/badge.svg)](https://github.com/biaks/ip-sockets-cpp-lite/actions/workflows/cmake.yml)
+
 **Simplicity. Lightweight. Cross-platform.**
 
-ip-sockets-cpp-lite is a fast, header-only, dependency-free, cross-platform C++ library that makes programming UDP/TCP sockets and working with IPv4/IPv6 addresses as easy as possible.
+It's a fast, header-only, dependency-free, cross-platform C++ library that makes programming UDP/TCP sockets and working with IPv4/IPv6 addresses as easy as possible.
 Forget about endless `getaddrinfo` calls, confusion with `sockaddr_in`/`sockaddr_in6`, and platform-specific workarounds.
 
 ```cpp
-// Send a UDP packet? One line!
-udp_socket_t<v4, client> sock;
-sock.open("192.168.1.100:8080");
-sock.send("Hello!", 6);
+  // Send a UDP packet to a hostname? No problem!
+  udp_socket_t<v4, socket_type_e::client> sock (log_e::debug);
+  ip4_t   ip   = sock.resolve("localhost", nullptr, log_e::debug);
+  addr4_t addr = {ip, 8080};
+  sock.open(addr);
+  sock.send("Hello!", 6);
+
+  // Send a TCP message to an IPv6 address? Easy!
+  tcp_socket_t<v6, socket_type_e::client> sock6 (log_e::debug);
+  sock6.open("[::1]:8081");
+  sock6.send("Hello!", 6);
+
+  //work with ip address from existing raw data with zero-copy? Okay
+  uint8_t raw_data[10] = {0x45,0x00,0x00, 0x7f,0x00,0x00,0x01, 0xa8,0x00,0x00};
+  ip4_t& reint_ip = *reinterpret_cast<ip4_t*>(&raw_data[3]);
+  std::cout << "ip from raw data: " << reint_ip << std::endl;
+```
+
+console output:
+```
+udp<ip4,client>: [static].resolve() [undefined -> localhost] DNS resolution success, resolved to '127.0.0.1'
+udp<ip4,client>: [3].open() [127.0.0.1:50902 <> 127.0.0.1:8080] success
+udp<ip4,client>: [3].send() [127.0.0.1:50902 -> 127.0.0.1:8080] sended 6 bytes
+tcp<ip6,client>: [4].open() [[::1]:39129 <> [::1]:8081] success
+tcp<ip6,client>: [4].send() [[::1]:39129 -> [::1]:8081] sended 6 bytes
+ip from raw data: 127.0.0.1
 ```
 
 ## Why ip-sockets-cpp-lite? ✨
@@ -22,22 +46,131 @@ sock.send("Hello!", 6);
 - **🔒 Predictable** - full control over everything
 - **📋 Human-readable errors** - clear error codes instead of cryptic errno values
 
+---
+
+This header only library gives you predictable, cross platform blocking I/O udp and tcp sockets with configurable timeouts — the simplest model that works for most real-world applications. Keep it simple, keep it portable! 🎯
+
+---
+
+## Features 🔧
+
+### IP Address Handling (`ip_address.h`)
+- Unified IPv4 and IPv6 support
+- String to binary and back conversion
+- Network prefixes and masks
+- IPv4-over-IPv6 mapping
+- Address + port as a single unit
+- Zero-copy overlay on existing memory buffers
+- Rich constructors from strings, numbers, bytes
+- Flexible parsing of various formats (hex, decimal, dotted)
+
+### UDP Sockets (`udp_socket.h`)
+- Unified API and behavior across different OS
+- Client and server modes with IPv4 or IPv6 addresses
+- Blocking I/O with configurable timeouts
+- Сonfigurable comprehensive logging
+- Clear states and error codes across different OS
+
+### TCP Sockets (`tcp_socket.h`)
+- Convenient accept with client socket creation
+- Automatic connection management
+- Consistent API with UDP sockets
+
+## Requirements 📋
+- C++11 or newer
+- C++ standard library
+- Nothing else!
+
 ## Quick Start 🏁
 
-### 1. Installation
+### 1. Project Integration 🛠️
 
-Simply copy three files into your project:
+Option 1 — Simply copy header files what you need into your project:
 - `ip_address.h` — IP address handling
 - `udp_socket.h` — UDP sockets
 - `tcp_socket.h` — TCP sockets
 
-Then include one of what you need:
+Option 2 — link library to your project via CMake
+```cmake
+add_subdirectory(ip-sockets-cpp-lite)
+target_link_libraries(your_app ip-sockets-cpp-lite)
+```
+
+Then include what you need:
 ```cpp
 #include "ip_address.h"  // work only with ipv4/ipv6 addresses
 #include "udp_socket.h"  // work with UDP ipv4/ipv6 client/server sockets
 #include "tcp_socket.h"  // work with TCP ipv4/ipv6 client/server sockets
 ```
 
+### 2. Smart IP Address Handling 🌐
+
+Working with IP addresses has never been easier:
+
+#### Create from anything
+```cpp
+// IPv4 addresses - all the common formats
+ip4_t ip0 = "192.168.1.1";       // from string
+ip4_t ip1 = 0xc0a80101;          // from uint32
+ip4_t ip2 = {192, 168, 1, 1};    // from bytes
+ip4_t ip3 = "0xc0a80101";        // from hex string
+ip4_t ip4 = "3232235777";        // from decimal string
+ip4_t ip5 = "127.1";             // 127.0.0.1 (missing bytes are zero)
+// IPv6 addresses - all the common formats
+ip6_t ip6 = "fe80::";            // link-local address
+ip6_t ip7 = "::1";               // loopback
+ip6_t ip8 = "64:ff9b::10.0.0.7"; // IPv4-translated (NAT64)
+ip6_t ip9 = "11.0.0.1";          // auto IPv4-mapped to ::ffff:11.0.0.1
+// Parsing of all variants of input strings always occurs in one pass
+```
+
+#### Zero-copy overlay on existing memory
+```cpp
+uint8_t raw_data[10] = {0x45,0x00,0x00, 0x7f,0x00,0x00,0x01, 0xa8,0x00,0x00};
+// Treat memory region as ip4_t without copying!
+ip4_t& reint_ip = *reinterpret_cast<ip4_t*>(&raw_data[3]);
+std::cout << reint_ip << std::endl; // prints "127.0.0.1"
+```
+
+#### Network operations made simple
+```cpp
+ip4_t ip = "192.168.1.100";
+ip4_t mask(24);                         // 255.255.255.0 from prefix
+ip4_t network = ip & mask;              // 192.168.1.0
+
+ip6_t ipv6 = "2001:db8::1";
+ip6_t ipv6_from_v4 = ip4_t("10.0.0.1"); // ::ffff:10.0.0.1 (IPv4-mapped)
+```
+
+#### Address + port as one type
+```cpp
+addr4_t server  = "192.168.1.100:8080";  // IP and port together
+addr6_t server6 = "[2001:db8::1]:8080";
+std::cout << server;                     // prints "192.168.1.100:8080"
+```
+
+#### Two Ways to Use IP and Address Types 🔧
+```cpp
+// Direct types (when IP version is known)
+ip4_t ip4     = "192.168.1.1";      // IPv4
+ip6_t ip6     = "2001:db8::1";      // IPv6
+addr4_t addr4 = "192.168.1.1:8080"; // IPv4 + port
+addr6_t addr6 = "[::1]:8080";       // IPv6 + port
+
+// Generic types (template-friendly)
+ip_t<v4> ip4     = "192.168.1.1";      // same as ip4_t
+ip_t<v6> ip6     = "2001:db8::1";      // same as ip6_t
+addr_t<v4> addr4 = "192.168.1.1:8080"; // same as addr4_t
+addr_t<v6> addr6 = "[::1]:8080";       // same as addr6_t
+
+// Perfect for templates!
+template <ip_type_e Type>
+void print_endpoint(const addr_t<Type>& endpoint) {
+    std::cout << "Connecting to: " << endpoint << '\n';
+}
+```
+**Choose what fits your code:** use concrete types for simplicity, or generic types for maximum flexibility in templates!
+
 ### 2. Send a UDP message
 
 ```cpp
@@ -78,7 +211,7 @@ int main() {
     // Create a UDP server on port 8080
     udp_socket_t<v4, socket_type_e::server> server;
     
-    if (server.open("0.0.0.0:8080") != no_error) {
+    if (server.open("0.0.0.0:8080") == no_error) {
 
         std::cout << "Server listening on port 8080\n";
     
@@ -110,7 +243,7 @@ int main() {
     // Create a TCP server
     tcp_socket_t<v4, socket_type_e::server> server;
     
-    if (server.open("0.0.0.0:8080") != no_error) {
+    if (server.open("0.0.0.0:8080") == no_error) {
 
         std::cout << "TCP server listening on port 8080\n";
     
@@ -136,70 +269,74 @@ int main() {
 }
 ```
 
+### 5. More examples 📚
+
+Check out the `examples/` directory for complete working examples:
+- `ip_address.cpp` - all IP address manipulation features
+- `udp_socket.cpp` - UDP client-server interaction
+- `tcp_socket.cpp` - TCP client-server interaction
+- `resolve_host.cpp` - resolving host to ipv4/ipv6 address example
+
 ## Why is this convenient? 🤔
 
-### Instead of this (raw sockets):
+Instead of this (system sockets):
 ```cpp
+// ...
+// ifdef and include hell there for cross platform work
+// ...
 struct sockaddr_in addr;
 addr.sin_family = AF_INET;
 addr.sin_port = htons(8080);
 inet_pton(AF_INET, "192.168.1.100", &addr.sin_addr);
 // ... and 20 more lines to send a single packet
 ```
 
-### Write this:
+Just write this (this library):
 ```cpp
+// single include and simple create socket object there
 sock.open("192.168.1.100:8080");  // done!
 sock.send("Hello", 5);
 ```
 
-## Features 🔧
-
-### IP Address Handling (`ip_address.h`)
-- Unified IPv4 and IPv6 support
-- String to binary and back conversion
-- Network prefixes and masks
-- IPv4-over-IPv6 mapping
-- Address + port as a single unit
-
-### UDP Sockets (`udp_socket.h`)
-- Client and server modes
-- Configurable timeouts
-- Polling-based asynchronous I/O
-- Clear states and error codes
+## Synchronous I/O with Timeouts — Why? ⏱️
 
-### TCP Sockets (`tcp_socket.h`)
-- Blocking I/O with timeouts
-- Convenient accept with client socket creation
-- Automatic connection management
-- Consistent API with UDP
+You might wonder: "Why this library provide synchronous sockets with timeouts instead of async I/O?"
 
-## Requirements 📋
-
-- C++11 or newer
-- C++ standard library
-- Nothing else!
+Great question! Here's why this design choice makes sense:
 
-## Project Integration 🛠️
+### ✅ Cross-platform simplicity
+Async I/O APIs differ dramatically between platforms (epoll on Linux, kqueue on BSD, IOCP on Windows).
+By choosing synchronous operations with timeouts, this library get a **single codebase** that works everywhere without #ifdef hell.
 
-### Option 1 — Just copy the files
-```bash
-cp ip_address.h udp_socket.h tcp_socket.h /path/to/your/project/
+### ✅ Easy to understand and use
+No callbacks, no event loops, no complex state machines. Your code reads linearly:
+```cpp
+sock.open(server);
+sock.send(request);
+sock.recv(response);  // blocks until data arrives or timeout
 ```
+Every developer understands this flow instantly.
 
-### Option 2 — CMake
-```cmake
-add_subdirectory(ip-sockets-cpp-lite)
-target_link_libraries(your_app ip-sockets-cpp-lite)
+### ✅ Threads are cheap, complexity is expensive
+Spawning a thread to wait for socket I/O is perfectly fine:
+```cpp
+std::thread([&]() {
+    while (true) {
+        int bytes = server.recvfrom(buffer, sizeof(buffer), client);
+        if (bytes > 0) handle_client(client, buffer, bytes);
+    }
+}).detach();  // One thread per socket — no problem!
 ```
+Modern systems handle thousands of threads easily. **Don't optimize prematurely** — clean code is better than complex async machinery.
 
-## Examples 📚
+### ✅ Perfect for 95% of use cases
+- REST API clients
+- IoT devices
+- Game servers
+- Protocol implementations
+- Embedded systems
 
-Check out the `examples/` directory for complete working examples:
-- `ip_address.cpp` - all IP address manipulation features
-- `udp_socket.cpp` - UDP client-server interaction
-- `tcp_socket.cpp` - TCP client-server interaction
-- `resolve_host.cpp` - resolving host to ipv4/ipv6 address example
+For the 5% that truly need massive concurrency (10k+ connections), you can still use this library in thread pools or combine it with higher-level async frameworks.
 
 ## License 📄
 
