[socket] Document ready() contract: callers must drain or track (#15590)

esphome/components/api/api_frame_helper.h

@@ -195,7 +195,10 @@ class APIFrameHelper {
   }
   // Get the frame footer size required by this protocol
   uint8_t frame_footer_size() const { return frame_footer_size_; }
-  // Check if socket has data ready to read
+  // Check if socket has buffered data ready to read.
+  // Contract: callers must read until it would block (EAGAIN/EWOULDBLOCK)
+  // or track that they stopped early and retry without this check.
+  // See Socket::ready() for details.
   bool is_socket_ready() const { return socket_ != nullptr && socket_->ready(); }
   // Release excess memory from internal buffers after initial sync
   void release_buffers() {

esphome/components/socket/bsd_sockets_impl.h

@@ -112,6 +112,8 @@ class BSDSocketImpl {
   int setblocking(bool blocking);
   int loop() { return 0; }
 
+  /// Check if the socket has buffered data ready to read.
+  /// See the ready() contract in socket.h — callers must drain or track remaining data.
   bool ready() const;
 
   int get_fd() const { return this->fd_; }

esphome/components/socket/lwip_raw_tcp_impl.h

@@ -96,6 +96,8 @@ class LWIPRawImpl : public LWIPRawCommon {
     errno = ENOSYS;
     return -1;
   }
+  // Check if the socket has buffered data ready to read.
+  // See the ready() contract in socket.h — callers must drain or track remaining data.
   // Intentionally unlocked — this is a polling check called every loop iteration.
   // A stale read at worst delays processing by one loop tick; the actual I/O in
   // read() holds the lwip lock and re-checks properly. See esphome#10681.

esphome/components/socket/lwip_sockets_impl.h

@@ -78,6 +78,8 @@ class LwIPSocketImpl {
   int setblocking(bool blocking);
   int loop() { return 0; }
 
+  /// Check if the socket has buffered data ready to read.
+  /// See the ready() contract in socket.h — callers must drain or track remaining data.
   bool ready() const;
 
   int get_fd() const { return this->fd_; }

esphome/components/socket/socket.h

@@ -53,6 +53,19 @@ bool socket_ready_fd(int fd, bool loop_monitored);
 
 // Inline ready() — defined here because it depends on socket_ready/socket_ready_fd
 // declared above, while the impl headers are included before those declarations.
+//
+// Contract (applies to ALL socket implementations — each platform implements
+// ready() differently, but this contract holds regardless of the mechanism):
+// ready() checks if the socket has buffered data ready to read. When it returns
+// true, the caller MUST read until it would block (EAGAIN/EWOULDBLOCK), or until
+// read() returns 0 to indicate EOF / connection closed, or track that it stopped
+// early and retry without calling ready(). The next call to ready() will only
+// report new data correctly if all callers fulfill this contract. Failing to
+// drain the socket may cause ready() to return false while data remains readable.
+//
+// In practice each socket is owned by a single component, so this contract is
+// straightforward to fulfill — but the owning component must be aware of it,
+// especially if it limits how many messages it processes per loop iteration.
 #if defined(USE_SOCKET_IMPL_BSD_SOCKETS) || defined(USE_SOCKET_IMPL_LWIP_SOCKETS)
 inline bool Socket::ready() const {
 #ifdef USE_LWIP_FAST_SELECT