{"id":28516553,"url":"https://github.com/mangad/jsocketpp","last_synced_at":"2026-05-01T03:34:06.681Z","repository":{"id":293744248,"uuid":"652380002","full_name":"MangaD/jsocketpp","owner":"MangaD","description":"A modern, C++20 socket library inspired by Java's networking API. Cross-platform support for TCP, UDP, multicast, and UNIX domain sockets, with blocking, non-blocking, and async operations.","archived":false,"fork":false,"pushed_at":"2025-10-22T12:29:33.000Z","size":3576,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-01T03:33:50.718Z","etag":null,"topics":["cpp","cpp20","java","sockets","tcp","udp","unix-sockets"],"latest_commit_sha":null,"homepage":"https://mangad.github.io/jsocketpp/","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MangaD.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["MangaD"]}},"created_at":"2023-06-12T00:25:18.000Z","updated_at":"2025-10-22T12:26:39.000Z","dependencies_parsed_at":"2025-05-31T08:04:54.562Z","dependency_job_id":"8bbef0ac-63f1-4fb3-b4a8-ff6065524afe","html_url":"https://github.com/MangaD/jsocketpp","commit_stats":null,"previous_names":["mangad/libsocket","mangad/jsocketpp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MangaD/jsocketpp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MangaD%2Fjsocketpp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MangaD%2Fjsocketpp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MangaD%2Fjsocketpp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MangaD%2Fjsocketpp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MangaD","download_url":"https://codeload.github.com/MangaD/jsocketpp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MangaD%2Fjsocketpp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32484352,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpp","cpp20","java","sockets","tcp","udp","unix-sockets"],"created_at":"2025-06-09T04:11:50.139Z","updated_at":"2026-05-01T03:34:06.654Z","avatar_url":"https://github.com/MangaD.png","language":"C++","funding_links":["https://github.com/sponsors/MangaD"],"categories":[],"sub_categories":[],"readme":"# jsocketpp: Java-Style Cross-Platform Socket Library for Modern C++20\n\n\u003c!--! [TOC] --\u003e\n\u003c!--\n- TOC should be placed after the header\n- https://www.doxygen.nl/manual/markdown.html#md_toc\n- https://www.doxygen.nl/manual/htmlcmds.html#htmltagcmds\n--\u003e\n\n[![Build Status](https://img.shields.io/github/actions/workflow/status/MangaD/jsocketpp/ci.yml)](https://github.com/MangaD/jsocketpp/actions)\n[![GH Doxygen](https://github.com/MangaD/jsocketpp/actions/workflows/doxygen-gh-pages.yml/badge.svg)](https://github.com/MangaD/jsocketpp/actions/workflows/doxygen-gh-pages.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)\n[![Conan](https://img.shields.io/badge/conan-available-brightgreen)](https://conan.io/center/jsocketpp)\n[![vcpkg](https://img.shields.io/badge/vcpkg-available-blue)](https://vcpkg.io/en/packages.html#jsocketpp)\n\n\u003e **A modern, cross-platform socket library for C++20 — modeled after Java's networking API, but written with clean,\nidiomatic, exception-safe C++.**\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"docs/doxygen/logo.png\" width=\"180\" alt=\"jsocketpp logo\"\u003e\n\u003c/div\u003e\n\n---\n\n## 📘 Overview\n\n**jsocketpp** brings the simplicity of Java's `Socket`, `ServerSocket`, and `DatagramSocket` APIs to modern C++20 — with\nfull support for TCP, UDP, multicast, and UNIX domain sockets, on both Windows and Unix-like systems.\n\nIt abstracts away:\n\n- platform-specific quirks (Winsock vs BSD)\n- low-level socket boilerplate\n- `select()` and `fcntl()` logic\n- raw buffer juggling\n\n... and replaces them with a safe, portable, **object-oriented** API that’s easy to use and hard to misuse.\n\n### 🧰 Typical Use Cases\n\n- Minimalist web servers or microservices (HTTP/TCP)\n- CLI tools for socket testing or diagnostics\n- Inter-process communication (IPC) with UNIX domain sockets\n- UDP-based discovery and messaging protocols\n- Multicast streaming or group communication\n- Socket wrappers for game servers or simulation engines\n\n---\n\n## 💡 Why jsocketpp?\n\nC++ networking is traditionally low-level and error-prone. `jsocketpp` is designed to:\n\n- Save you from boilerplate (`socket`, `bind`, `listen`, `accept`, `recv`...)\n- Eliminate raw pointer management and platform-specific checks\n- Encourage RAII, strong exception safety, and readable code\n- Support modern build tools (CMake, Conan, vcpkg)\n- Let you write servers and clients in **under 10 lines**\n\n---\n\n## ✨ Features at a Glance\n\n- 📦 **TCP, UDP, Multicast, and UNIX socket support**\n- 📶 **IPv4, IPv6, and dual-stack** support (automatic when possible)\n- 🔁 Blocking, non-blocking, and **timeout-enabled I/O**\n- 📬 Buffered and typed `read\u003cT\u003e()` methods\n- 🔄 `acceptAsync()` and `tryAccept()` for non-blocking server loops\n- ✅ `Socket::isConnected()` to check peer connection state\n- 🎯 Java-inspired classes:\n    - `Socket`, `ServerSocket`, `DatagramSocket`, `MulticastSocket`, `UnixSocket`\n- 🔒 **Exception-safe** by design (no manual cleanup needed)\n- 🧪 Unit tested with GoogleTest\n- ⚙️ Packaged for **Conan**, **vcpkg**, and **CMake** consumers\n- 🪟🧬 **Cross-platform**: Windows, Linux, macOS\n\n---\n\n## 🔧 Platform \u0026 Toolchain Support\n\n| Feature          | Support                          |\n|------------------|----------------------------------|\n| C++ Standard     | C++20                            |\n| OS Support       | Linux, Windows (Win10+), macOS   |\n| Compilers        | GCC ≥ 10, Clang ≥ 11, MSVC 2019+ |\n| Package Managers | Conan, vcpkg                     |\n| Build System     | CMake ≥ 3.19 (presets.json)      |\n| Documentation    | Doxygen + markdown               |\n\n---\n\n## 🔁 jsocketpp vs Boost.Asio\n\n| Feature           | jsocketpp                           | Boost.Asio                            |\n|-------------------|-------------------------------------|---------------------------------------|\n| API style         | Java-style OOP                      | Callback-driven / coroutine / reactor |\n| Dependencies      | None (header + source only)         | Requires Boost (or standalone Asio)   |\n| Asynchronous I/O  | Non-blocking, timeout, async accept | Full async/reactor model              |\n| Learning curve    | Low                                 | Moderate to steep                     |\n| Coroutine support | Planned                             | ✅ Full support (C++20 coroutines)     |\n| Readability       | ✅ Very high (simple methods)        | Can be verbose                        |\n| Performance       | Near-native for blocking I/O        | Optimal with async + threads          |\n\n**Use `jsocketpp`** when you want:\n\n- Clean and portable blocking I/O\n- Simple, readable code\n- Great for CLI tools, daemons, test utilities, game servers, educational use\n\n---\n\n## 🚀 Performance \u0026 Footprint\n\n- No runtime overhead — it's just modern C++ around system calls\n- All socket I/O maps directly to `recv`, `send`, `recvfrom`, etc.\n- Internal buffering is efficient (default: 4 KB)\n- No heap allocations during read/write (unless resizing)\n\nFor high-throughput async workloads, Boost.Asio or io_uring may outperform it. For most real-world usage, **jsocketpp is\nmore than fast enough**.\n\n---\n\n## ⚠️ Limitations\n\n- **Not thread-safe**: Each socket instance must be used from a single thread\n- No coroutine API (`co_await`) — async support is currently based on `select()` with callbacks/futures\n\n- No SSL/TLS (consider wrapping with OpenSSL or mbedTLS externally)\n- No epoll/kqueue/io_uring integration (yet)\n- Does not auto-retry on `EINTR` or transient errors (manual retry loop if needed)\n- Limited to host-native socket support (`AF_UNIX` on Win10+ only)\n\n---\n\n## 📦 Installation\n\njsocketpp can be installed via [vcpkg](https://vcpkg.io), [Conan](https://conan.io/center), or manually as a CMake\nsubproject.\n\n### ✅ vcpkg\n\n```sh\nvcpkg install jsocketpp\n```\n\nThen link via `find_package(jsocketpp CONFIG REQUIRED)` in CMake.\n\n---\n\n### ✅ Conan\n\n```sh\nconan install jsocketpp/[latest]@\n```\n\nYou may also add `jsocketpp` to your `conanfile.txt` or `conanfile.py`.\n\n---\n\n### 🔧 Manual Integration\n\n```sh\ngit clone https://github.com/MangaD/jsocketpp.git\ncd jsocketpp\nmkdir build \u0026\u0026 cd build\ncmake ..\nmake\nsudo make install\n```\n\nOr add the `src/` folder to your CMake project:\n\n```cmake\nadd_subdirectory(jsocketpp)\ntarget_link_libraries(myapp PRIVATE jsocketpp)\n```\n\n---\n\n## 🚀 Quick Start Examples\n\n### 🧵 TCP Echo Server\n\n```cpp\n#include \u003cjsocketpp/ServerSocket.hpp\u003e\n#include \u003cjsocketpp/Socket.hpp\u003e\n\nint main() {\n    jsocketpp::ServerSocket server(8080); // binds and listens\n\n    while (true) {\n        auto client = server.accept(); // blocks (or times out)\n        std::string msg = client.read\u003cstd::string\u003e();\n        client.write(\"Echo: \" + msg);\n    }\n}\n```\n\n---\n\n### 📡 UDP Echo Server\n\n```cpp\n#include \u003cjsocketpp/DatagramSocket.hpp\u003e\n#include \u003cjsocketpp/DatagramPacket.hpp\u003e\n\nint main() {\n    jsocketpp::DatagramSocket socket(9000);\n    jsocketpp::DatagramPacket packet(1024);\n\n    while (true) {\n        socket.read(packet);        // fills sender info\n        socket.write(packet);       // echoes back to sender\n    }\n}\n```\n\n---\n\n### 🌐 Multicast Receiver\n\n```cpp\n#include \u003cjsocketpp/MulticastSocket.hpp\u003e\n#include \u003ciostream\u003e\n\nint main() {\n    jsocketpp::MulticastSocket sock(5000);\n    sock.joinGroup(\"239.255.0.1\");\n\n    jsocketpp::DatagramPacket pkt(2048);\n    sock.read(pkt);\n    std::cout \u003c\u003c \"Got multicast: \" \u003c\u003c std::string(pkt.buffer.begin(), pkt.buffer.end()) \u003c\u003c std::endl;\n}\n```\n\n---\n\n### 🧷 UNIX Domain Socket (IPC)\n\n```cpp\n#include \u003cjsocketpp/UnixSocket.hpp\u003e\n\nint main() {\n    jsocketpp::UnixSocket server(\"/tmp/echo.sock\");\n    server.bind();\n    server.listen();\n\n    auto client = server.accept();\n    std::string msg = client.read\u003cstd::string\u003e();\n    client.write(\"Echo from UNIX socket: \" + msg);\n}\n```\n\n\u003e On Windows, AF\\_UNIX requires Windows 10 build 1803 or later.\n\n---\n\n## 🔄 Java ↔ jsocketpp Class Mapping\n\n| Java Class               | jsocketpp Equivalent                |\n|--------------------------|-------------------------------------|\n| `Socket`                 | `jsocketpp::Socket`                 |\n| `ServerSocket`           | `jsocketpp::ServerSocket`           |\n| `DatagramSocket`         | `jsocketpp::DatagramSocket`         |\n| `DatagramPacket`         | `jsocketpp::DatagramPacket`         |\n| `MulticastSocket`        | `jsocketpp::MulticastSocket`        |\n| `SocketException`        | `jsocketpp::SocketException`        |\n| `SocketTimeoutException` | `jsocketpp::SocketTimeoutException` |\n\n---\n\n## 📚 Documentation\n\nFull API documentation is available as Doxygen-generated HTML:\n\n👉 [📖 jsocketpp API Reference (GitHub Pages)](https://github.com/MangaD/jsocketpp/wiki)\n\nYou can also generate it locally:\n\n```sh\ncmake -S . -B build -DBUILD_DOCS=ON\ncmake --build build --target docs\n```\n\nThe generated HTML will appear in `docs/doxygen/html/index.html`.\n\n---\n\n## 🧪 Building and Testing\n\nThe project uses **CMake presets** for consistent and cross-platform builds:\n\n```sh\ncmake --preset=gcc-debug-x64     # or clang-debug-x64 / msvc-x64-static\ncmake --build --preset=gcc-debug-x64\nctest --preset=gcc-debug-x64\n```\n\nPresets are defined in [CMakePresets.json](./CMakePresets.json) and include configurations for:\n\n* GCC, Clang, MSVC, MinGW\n* x64 and ARM64\n* Debug/Release/RelWithDebInfo\n* Shared and static builds\n* CI workflows for GitHub Actions\n\nTests are written with **GoogleTest**. To run them:\n\n```sh\nctest --preset=gcc-debug-x64\n```\n\n---\n\n## 🛠 Developer Tooling\n\n### Pre-commit hooks\n\nThe repository supports pre-commit checks:\n\n* `clang-format` (via `.clang-format`)\n* `cmake-format` (via `.cmake-format.yaml`)\n* Header guards, whitespace, and YAML checks\n\nSet up with:\n\n```sh\npip install -r requirements.txt\npre-commit install\n```\n\n---\n\n## 🤝 Contributing\n\nWe welcome PRs, issues, and ideas! Please read the following before contributing:\n\n* 📋 [CONTRIBUTING.md](./CONTRIBUTING.md)\n* 📜 [CODE\\_OF\\_CONDUCT.md](./CODE_OF_CONDUCT.md)\n* 🛡️ [SECURITY.md](./SECURITY.md)\n\nTo work on the library:\n\n```sh\ngit clone https://github.com/MangaD/jsocketpp.git\ncd jsocketpp\ncmake --preset=clang-debug-x64\ncmake --build --preset=clang-debug-x64\n```\n\nRemember to format your code with:\n\n```sh\ncmake --build . --target clang-format\n```\n\nAnd write tests in `tests/`!\n\n---\n\n## ⚖️ License\n\nThis project is licensed under the MIT License.\nSee [LICENSE](./LICENSE) for details.\n\n---\n\n## 🙏 Acknowledgements\n\n* [Berkeley Sockets API](https://en.wikipedia.org/wiki/Berkeley_sockets) — used in C/C++ for network programming\n* The Java Networking API — for its excellent abstractions\n* GoogleTest — for testing\n* CLion, VS Code, Ninja, and CMake — for development tooling\n* Everyone who contributes, uses, or discusses jsocketpp ❤️\n\n---\n\n## ❓ FAQ\n\n### Is jsocketpp async?\n\nYes — jsocketpp provides non-blocking and timeout-based I/O, including:\n\n- `Socket::connect(timeout)`\n- `ServerSocket::accept(timeout)` and `tryAccept(timeout)`\n- `ServerSocket::acceptAsync()` (via `std::future`)\n- `ServerSocket::acceptAsync(callback)` (via background thread)\n\nThese are based on `select()` internally and return in bounded time.\n\n**Coroutine support** is a potential future feature via `co_await` + platform-specific polling (e.g., `epoll`, `kqueue`,\n`IOCP`).\n\n---\n\n### How does error handling work?\n\nAll functions throw either:\n\n- `SocketException` — for platform-level errors (`connect()`, `recv()` failure, etc.)\n- `SocketTimeoutException` — if an operation times out (e.g., in `accept()` or `read()` with timeout set)\n\nAll errors include the native error code and message.\n\n---\n\n### Can I use jsocketpp in production?\n\nYes — `jsocketpp` is robust, portable, and suitable for production use in many real-world scenarios:\n\n- Lightweight HTTP and WebSocket servers\n- Game servers using TCP/UDP/multicast\n- Local IPC using UNIX domain sockets\n- Network tools, daemons, test harnesses\n\nIt supports non-blocking and timeout-driven I/O, including async `accept()` and `connect()` via `select()` and futures.\n\nHowever, keep in mind:\n\n- No TLS yet (use OpenSSL or mbedTLS externally)\n- No coroutine (`co_await`) support yet\n- Not thread-safe by default — use one socket per thread\n- No high-performance event loop (e.g., epoll/io_uring)\n\n---\n\n### Does it work on Windows?\n\nYes. It fully supports Winsock, and even supports AF_UNIX on Windows 10+ (1803 or later).\n\nOn Windows:\n\n- `WSAStartup` is handled internally\n- Platform-specific errors are translated to readable messages\n\n---\n\n### What is the default buffer size?\n\nMost read/write operations use a default internal buffer size of **4096 bytes**. You can override this in constructors\nfor `Socket`, `DatagramSocket`, etc.\n\n---\n\n## 🛣️ Roadmap\n\n- [x] TCP (client + server)\n- [x] UDP + Datagram abstraction\n- [x] Multicast (IPv4 + IPv6)\n- [x] UNIX domain sockets (Linux, macOS, Win10+)\n- [x] Timeout + non-blocking support\n- [x] Exception handling and message formatting\n- [x] CMake + Conan + vcpkg packaging\n- [x] CI with full CMake preset matrix\n- [x] Doxygen-rich documentation\n- [ ] TLS/SSL (via OpenSSL wrapper or interface)\n- [ ] Coroutine-based async API (`co_await` I/O)\n- [ ] epoll/kqueue/io_uring abstraction layer\n- [ ] Thread-safe wrappers\n- [ ] IPv6 advanced options (flow label, hop limit)\n- [ ] Proxy socket types (SOCKS5, HTTP CONNECT)\n\n---\n\n## 🧭 See Also\n\n- [Boost.Asio](https://think-async.com/) — heavyweight async networking\n- [libuv](https://libuv.org/) — C event loop abstraction\n- [asio (standalone)](https://github.com/chriskohlhoff/asio)\n- [cpp-httplib](https://github.com/yhirose/cpp-httplib) — a nice C++ HTTP server/client lib\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmangad%2Fjsocketpp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmangad%2Fjsocketpp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmangad%2Fjsocketpp/lists"}