feat(socket): Add SocketReactor (select() loop + thread pool) and expose it

[finger563]

Description

Adds espp::SocketReactor: a single select()-based event-loop thread that
multiplexes many receiver sockets and dispatches each socket's read + user
callback onto a shared espp::ThreadPool, instead of dedicating one thread
(one espp::Task) to every receiving socket. This collapses "N receiver
threads" into "1 loop thread + a small fixed pool" that can be shared across
subsystems (dns_server, rtps, rtsp, ftp, …).

Design

• One-shot arm/disarm. Under level-triggered select(), a readable socket
  is disarmed and a job is submitted to the pool, then re-armed only after
  that job completes — so there is at most one in-flight handler per socket
  (per-socket ordering preserved, no concurrent recv on one fd) while
  different sockets run concurrently. If the pool is saturated the socket is
  left for the next select() to re-report (natural backpressure, no loss).
• Wakeup socket. A loopback UDP socket in the select set makes
  add/remove/re-arm/stop immediately responsive.
• Pool ownership. The thread pool may be owned (built from Config) or an
  external shared_ptr shared across subsystems.
• APIs. add_udp_receiver() (binds + receives, replacing a per-socket
  UdpSocket::start_receiving() thread); add_tcp_listener() (accept →
  dispatch) and add_tcp_stream() (recv → callback, auto-remove on disconnect)
  — so a TCP server runs with no accept thread and no thread-per-client; plus a
  low-level add_fd()/remove(). Registration is guarded against FD_SETSIZE.

Supporting changes

• UdpSocket::bind(ReceiveConfig) is factored out of start_receiving() (bind
  a socket for external-loop use without a thread) and Socket::native_handle()
  is added.
• Correctness fixes surfaced by review of the socket component:
  TcpSocket::connected_ → std::atomic<bool>; Socket::Info uses inet_ntop
  into a local buffer instead of inet_ntoa's shared static buffer (both raced
  under concurrent reactor use); the reactor's stop() waits unbounded for
  in-flight handlers (a shared-pool use-after-free otherwise), the TCP stream
  handler no longer busy-loops on a non-EOF error (e.g. peer RST), and the
  wakeup fd is atomic.

Host library exposure (lib)

• socket_reactor.cpp is built into the C++ static library and the Python
  extension; socket_reactor.hpp is added to the espp.hpp aggregate.
• litgen cannot parse the header, so the Python bindings are hand-written in
  python_bindings/socket_reactor_bindings.cpp (GIL-safe UDP-receiver
  callback), registered via py_init_socket_reactor; the autogenerate script
  documents the exclusion. TCP listener/stream paths stay C++-only for now.

Docs & examples/tests

• ESP example gains reactor + TCP-reactor scenarios plus shared-pool /
  lifecycle / multi-client / UDP-overloads cases (15 pass/fail scenarios) with a
  failure summary.
• New host examples/tests: python/socket_reactor.py,
  python/socket_reactor_test.py, and pc/tests/socket_reactor.cpp.
• Component README, a new doc/en/network/socket_reactor.rst (+ toctree), and
  the Doxyfile are updated.

Motivation and Context

Every receiving socket in espp currently owns a dedicated background thread:
UdpSocket::start_receiving() spins up one espp::Task, and TCP servers
(ftp_server, rtsp_server) run an accept thread plus one or more threads per
connected client. A server with N clients therefore consumes N+ threads, each
with its own stack — expensive on ESP targets. SocketReactor lets many
sockets share a single select() loop and a small, bounded thread pool, so
adding receivers/clients no longer adds threads. Existing per-socket APIs are
unchanged, so this is purely additive; consumers can migrate incrementally.

How has this been tested?

• ESP target (compile-only; I can't flash): idf.py build of
  components/socket/example for esp32 (the example is in the CI build matrix).
  The expanded suite has 15 self-checking scenarios.
• Host C++: standalone lib build (C++ static espp_pc + _espp module),
  then pc/tests/socket_reactor.cpp run → 23/23 checks pass (lifecycle,
  multiple UDP receivers, dynamic remove, add_fd validation, shared pool, and
  the full TCP listener/stream/disconnect flow).
• Host Python: python/socket_reactor_test.py run against the locally-built
  _espp → 17/17 checks pass (lifecycle, UDP receiver + reversed echo via a
  Python callback, sender info, None-response, multiple receivers, dynamic
  remove); python/socket_reactor.py round-trips datagrams through two
  reactor-multiplexed receivers.
• Static analysis: cppcheck clean on the new/changed socket files using the
  CI static_analysis arguments.
• Docs: Doxygen 1.17 parses socket_reactor.hpp with zero warnings in
  the real-build configuration (EXTRACT_ALL=YES, with task.hpp/
  thread_pool.hpp in INPUT); \ref/\snippet references resolve.

Env: macOS host build; ESP-IDF for the esp32 example compile.

Screenshots (if appropriate, e.g. schematic, board, console logs, lab pictures):

N/A

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation Update
• Hardware (schematic, board, system design) change
• Software change

Checklist:

• My change requires a change to the documentation.
• I have added / updated the documentation related to this change via either README or WIKI

Software

• I have added tests to cover my changes.
• I have updated the .github/workflows/build.yml file to add my new test to the automated cloud build
• All new and existing tests passed.
• My code follows the code style of this project.

[github-actions]

✅Static analysis result - no issues found! ✅

[Copilot]

Pull request overview

Adds a new espp::SocketReactor component feature that multiplexes many sockets on one select() loop thread and dispatches read handling onto a shared espp::ThreadPool, reducing thread-per-socket overhead while also exposing the reactor in the host C++ library and Python bindings (UDP path).

Changes:

• Implement SocketReactor (select loop + wakeup socket + thread-pool dispatch) with UDP receiver, TCP listener, TCP stream, and low-level fd registration APIs.
• Refactor/extend the socket component for reactor use (UdpSocket::bind(ReceiveConfig), Socket::native_handle()), plus concurrency-related fixes (inet_ntop usage and TcpSocket::connected_ atomics).
• Add host/ESP examples, C++/Python tests, documentation updates, and integrate the new source/bindings into the host build.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
python/socket_reactor.py	Python example demonstrating reactor-multiplexed UDP echo receivers.
python/socket_reactor_test.py	Self-checking Python test coverage for the Python UDP reactor binding.
python/README.md	Documents the new Python example + test scripts.
pc/tests/socket_reactor.cpp	Host-side C++ test exercising UDP + TCP reactor paths and lifecycle.
lib/python_bindings/socket_reactor_bindings.cpp	Hand-written pybind11 bindings for SocketReactor (UDP path + lifecycle).
lib/python_bindings/module.cpp	Registers the new hand-written socket reactor bindings in the module init.
lib/include/espp.hpp	Exposes socket_reactor.hpp via the aggregate host include header.
lib/espp.cmake	Adds socket_reactor.cpp and the new bindings file to host build targets.
lib/autogenerate_bindings.py	Documents why socket_reactor.hpp is excluded from litgen generation.
doc/en/network/socket_reactor.rst	Adds Sphinx/Doxygen-facing documentation page for SocketReactor.
doc/en/network/index.rst	Adds socket_reactor to the network docs toctree.
doc/Doxyfile	Adds socket_reactor.hpp to Doxygen INPUT list.
components/socket/src/udp_socket.cpp	Factors out UdpSocket::bind(ReceiveConfig) from start_receiving().
components/socket/src/socket.cpp	Switches IPv4 address formatting to thread-safe inet_ntop.
components/socket/src/socket_reactor.cpp	Implements the new SocketReactor runtime.
components/socket/README.md	Updates component README with SocketReactor overview and usage notes.
components/socket/include/udp_socket.hpp	Declares the new UdpSocket::bind(ReceiveConfig) API.
components/socket/include/tcp_socket.hpp	Makes connected_ atomic for reactor/pool concurrency.
components/socket/include/socket.hpp	Adds Socket::native_handle() to expose the underlying fd/handle.
components/socket/include/socket_reactor.hpp	Adds the public SocketReactor API and documentation.
components/socket/idf_component.yml	Adds espp/thread_pool dependency required by reactor.
components/socket/example/main/socket_example.cpp	Adds multiple reactor scenarios and expands example summary output.
components/socket/CMakeLists.txt	Adds thread_pool to component requirements for ESP builds.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 4 comments.

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

components/socket/src/socket_reactor.cpp:476

• Same Windows compatibility issue here: ::close(fd) is not the correct way to close a Winsock socket. Use closesocket() under _MSC_VER, consistent with close_wakeup_socket().

    ::close(fd);

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated 2 comments.

Suppressed comments (3)

components/socket/src/socket_reactor.cpp:160

• On Windows (_MSC_VER), fd_set capacity is limited by count (FD_SETSIZE), not by the numeric socket value. check_fd() currently skips FD_SETSIZE checks on Windows, so registrations beyond FD_SETSIZE-1 may be silently dropped by FD_SET, leaving entries registered but never dispatched.

bool SocketReactor::check_fd(sock_type_t fd) const {
  if (!Socket::is_valid_fd(fd)) {
    logger_.error("register: invalid socket fd");
    return false;
  }

components/socket/src/socket_reactor.cpp:201

• add_udp_receiver() binds the socket before validating whether its fd can be registered with the reactor. If registration later fails (e.g. FD_SETSIZE or Windows fd_set capacity), the socket remains bound even though the reactor returns INVALID_ID, which can surprise callers and cause later bind failures.

SocketReactor::add_udp_receiver(espp::UdpSocket &socket,
                                const espp::UdpSocket::ReceiveConfig &receive_config) {
  if (!socket.bind(receive_config)) {
    logger_.error("add_udp_receiver: could not bind socket to port {}", receive_config.port);
    return INVALID_ID;
  }

doc/Doxyfile:392

• The doc/Doxyfile INPUT list is kept in alphabetical order for deterministic diffs. The new socket_reactor.hpp entry is appended after udp_socket.hpp/tcp_socket.hpp; it should be placed in alphabetical order with the other socket headers.

  $(PROJECT_PATH)/components/socket/include/socket.hpp \
  $(PROJECT_PATH)/components/socket/include/udp_socket.hpp \
  $(PROJECT_PATH)/components/socket/include/tcp_socket.hpp \
  $(PROJECT_PATH)/components/socket/include/socket_reactor.hpp \

[Copilot]

Pull request overview

Copilot reviewed 23 out of 23 changed files in this pull request and generated no new comments.

Suppressed comments (2)

components/socket/src/socket_reactor.cpp:94

• If loop_task_->start() fails, start() returns false but leaves the owned thread pool potentially running (pool_->start() was already called) and keeps loop_task_ allocated. This can leak worker threads and leaves the reactor in a partially-started state after a failed start(). Clean up on failure by resetting loop_task_ and stopping the owned pool before returning.

  if (!loop_task_->start()) {
    logger_.error("Could not start reactor loop task");
    running_ = false;
    close_wakeup_socket();
    return false;

doc/Doxyfile:392

• In doc/Doxyfile the INPUT list is generally kept in alphabetical order (e.g., the surrounding rtsp/socket/spi sections). With socket_reactor.hpp added, the socket headers are now out of order, which makes future maintenance harder. Please reorder the socket header entries alphabetically (socket.hpp, socket_reactor.hpp, tcp_socket.hpp, udp_socket.hpp).

  $(PROJECT_PATH)/components/socket/include/socket.hpp \
  $(PROJECT_PATH)/components/socket/include/udp_socket.hpp \
  $(PROJECT_PATH)/components/socket/include/tcp_socket.hpp \
  $(PROJECT_PATH)/components/socket/include/socket_reactor.hpp \