Read data from socket into buffer. The only await point for message reception.

On AsyncTimeoutError the caller (typically invalidateOnTimeout) is responsible for the state transition (the recvMessage wrapper does it itself). On any other CatchableError the connection is marked csClosed before re-raising: the read may have consumed an indeterminate number of bytes from the socket and the stream is no longer parseable.

Whether the underlying transport is present and the OS has not yet observed a peer-side close.

Cheap, non-blocking (no round trip): checks that the connection object holds a transport handle, and on POSIX also issues a single recv(MSG_PEEK | MSG_DONTWAIT) via socketHasFin to catch FIN/RST already sitting in the kernel buffer (half-open detection). On non-POSIX platforms the check falls back to handle presence only.

Pair with state == csReady to decide whether a connection is usable before issuing a query. Use ping for a full server round trip when the OS-level probe is insufficient (e.g. TLS-layer state, application liveness rather than transport liveness).

Synchronously parse the next message from the receive buffer. Returns none if the buffer doesn't contain a complete message. Notification/Notice messages are dispatched internally. ParameterStatus messages are recorded into conn.serverParams and consumed, so callers never see them. DataRow messages are consumed: when onRow is nil, they are counted (if rowCount != nil) and left decoded in rowData for the caller; when onRow is set, it is invoked once per row and rowData.buf / rowData.cellIndex are reset before the next row, giving streaming callers (e.g. queryEach) constant memory. When onRow raises, the error is captured into onRowError[] (required to be non-nil when onRow is set) and subsequent rows are drained without re-invoking the callback. When rowData == nil and onRow == nil and skipDataRow is true, DataRow messages are also skipped without decoding their columns — used by discard-only consumers (exec paths, simple-protocol exec) to avoid a per-row seq[Option[seq[byte]]] + per-cell seq allocation.

On PgProtocolError the protocol stream is desynchronised — the connection is transitioned to csClosed before re-raising so that it is never reused (in particular, by the connection pool).

Receive a single backend message from the connection. Thin wrapper around nextMessage + fillRecvBuf for backward compatibility.

On AsyncTimeoutError the connection is set csClosed before re-raising (the partial read leaves the byte stream unparseable); no CancelRequest is dispatched — callers needing that must invalidate explicitly.

Non-blocking OS-level half-open probe (POSIX only).

Returns true when the kernel has already observed a peer-side FIN/RST on this connection's underlying socket. Returns false when the socket is alive and idle, when there is pending data (which the next operation will handle), when the probe hits transient kernel resource exhaustion (ENOMEM/ENOBUFS, which says nothing about peer state), or when there is no transport handle to probe (e.g. mock connections, or after close).

A single recv(MSG_PEEK | MSG_DONTWAIT) syscall — no round trip. For TLS connections this still detects TCP-level FIN/RST, but not TLS-layer errors that haven't been read yet; use ping for that.

On non-POSIX platforms this always returns false (no probe available).

Non-blocking OS-level check: does the kernel currently hold readable bytes on this connection's socket? (POSIX only.)

Used by SSL negotiation to detect pre-TLS plaintext injection (CVE-2021-23214 / CVE-2021-23222 family): after a server answers the SSLRequest with 'S' it must stay silent until the client sends the TLS ClientHello, so any byte already readable was injected by a man-in-the-middle to be smuggled ahead of the encrypted stream.

A single recv(MSG_PEEK | MSG_DONTWAIT) syscall — no round trip. Only a positive read of buffered bytes yields true. Returns false when the socket is idle (EAGAIN), when the peer has closed (FIN: nothing was injected), on EINTR/other transient errors, and where the probe is unavailable (non-POSIX, or no transport handle).

Note: this sees only bytes still in the kernel buffer. Data the higher-level transport has already drained into its own buffer (the chronos StreamTransport may do this) is invisible here and must be detected by the caller reading more than the single response byte.

Fail open: any non-data outcome (idle, FIN, transient or other error) yields false so a probe error never rejects a legitimate connection.

var idx = 0
let rows = @["1\tAlice\n".toBytes(), "2\tBob\n".toBytes()]
let cb = makeCopyInCallback:
  if idx < rows.len:
    let chunk = rows[idx]
    inc idx
    chunk
  else:
    newSeq[byte]()

var chunks: seq[seq[byte]]
let cb = makeCopyOutCallback:
  chunks.add(data)

Bare overload for callers that do not accumulate into a RowData. Body mirrors the data overload above with nextMessage() in place of the accumulating call.

DataRow is skipped in the parser here — no current caller inspects rows inside body: exec paths (extended-query, simple-protocol) discard them, and the remaining callers (prepare, close, cursor close, COPY setup, ping) never receive DataRow in a well-formed reply. If a future caller needs the row bytes, drop skipDataRow = true here.

Generic protocol pump loop. pumpMsg and queryError are accessible in body and readyBody. DataRow messages are decoded in-place into resultData and counted through rowCountPtr by nextMessage, so they never surface in body.

The loop is spelled out in both overloads rather than one forwarding to the other: {.dirty.} injection only reaches body/readyBody across a single template boundary, so forwarding would leave their references to pumpMsg/queryError undeclared. A single template with defaulted resultData/rowCountPtr fails the same way — typed params ahead of the untyped bodies suppress the injection (Nim 2.2.x).