tcp_socket.hpp

// SPDX-License-Identifier: Apache-2.0
 
#pragma once
#include <arpa/inet.h>
#include <fcntl.h>
#include <netdb.h>
#include <poll.h>
#include <sys/socket.h>
#include <unistd.h>
 
#include <algorithm>
#include <cerrno>
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <limits>
#include <optional>
#include <stdexcept>
#include <string>
#include <system_error>
#include <utility>
 
#if defined(__APPLE__)
#include <signal.h>
#endif
 
#ifndef MSG_NOSIGNAL
// macOS has no MSG_NOSIGNAL; SO_NOSIGPIPE (set per-socket below) is the
// portable equivalent there, so this becomes a harmless no-op flag.
#define MSG_NOSIGNAL 0
#endif
 
namespace morph::net::detail {
 
/// @brief How a `pollUntil()` wait ended.
enum class PollOutcome : std::uint8_t {
    kReady,     ///< `poll()` reported the descriptor (readiness, hang-up or error bits alike).
    kTimedOut,  ///< The deadline passed first.
    kFailed,    ///< `poll()` failed with something other than `EINTR`; see `PollResult::error`.
};
 
/// @brief The result of a `pollUntil()` wait.
struct PollResult {
    /// @brief How the wait ended.
    PollOutcome outcome = PollOutcome::kTimedOut;
    /// @brief The `errno` of the failing `poll()` when `outcome` is `kFailed`; `0` otherwise.
    int error = 0;
};
 
/// @brief Waits for @p events on @p fd until @p deadline, with one budget for the whole wait.
///
/// A signal that interrupts `poll()` (`EINTR`) does not end the wait and does
/// not re-arm the full timeout: the loop recomputes what is left of the budget
/// and polls again, so a host delivering signals steadily (a profiler's timer,
/// `SIGCHLD`) cannot stretch the wait past @p deadline. The per-call timeout is
/// clamped to `int` milliseconds, which is what `poll()` takes; an unclamped
/// multi-week budget would truncate to garbage, possibly negative, meaning
/// "wait forever".
///
/// Reports rather than throws, so each caller keeps its own policy for a
/// timeout or a failure (a connect moves on to the next address candidate; a
/// handshake read gives up).
///
/// @param descriptor Descriptor to wait on.
/// @param events     `poll()` event mask, e.g. `POLLIN` or `POLLOUT`.
/// @param deadline   Point after which the wait reports `kTimedOut`. A deadline
///                   already passed reports it without polling.
/// @return The outcome, plus the failing `errno` for `kFailed`.
// A descriptor and an event mask are different things that happen to convert; the
// parameter names carry the distinction.
// NOLINTNEXTLINE(bugprone-easily-swappable-parameters)
inline PollResult pollUntil(int descriptor, short events, std::chrono::steady_clock::time_point deadline) {
    pollfd pfd{};
    pfd.fd = descriptor;
    pfd.events = events;
    for (;;) {
        // Rounded up: poll() takes whole milliseconds, and truncating would wake
        // it up to a millisecond before the deadline and report a timeout early.
        auto const remaining =
            std::chrono::ceil<std::chrono::milliseconds>(deadline - std::chrono::steady_clock::now());
        if (remaining.count() <= 0) {
            return {.outcome = PollOutcome::kTimedOut};
        }
        auto const waitMs = static_cast<int>(
            std::min<std::chrono::milliseconds::rep>(remaining.count(), std::numeric_limits<int>::max()));
        int const ready = ::poll(&pfd, 1, waitMs);
        if (ready > 0) {
            return {.outcome = PollOutcome::kReady};
        }
        if (ready < 0) {
            int const err = errno;
            if (err != EINTR) {
                return {.outcome = PollOutcome::kFailed, .error = err};
            }
        }
        // EINTR, or a poll that returned early with nothing ready (the
        // millisecond rounding above): recompute what is left and go again.
    }
}
 
/// @brief RAII wrapper around a POSIX (BSD sockets) TCP file descriptor.
///
/// Linux/macOS only today — see `docs/spec/core/backend.md`'s `morph::net`
/// section for the Windows/Winsock2 follow-up. Move-only.
class TcpSocket {
public:
    /// @brief Constructs an empty (invalid) socket.
    TcpSocket() = default;
 
    /// @brief Wraps an already-open file descriptor (e.g. from `::accept`).
    ///
    /// Normalises the two fd properties this class's API depends on: SIGPIPE
    /// suppression, and **blocking mode**. A `TcpSocket` is blocking unless its
    /// owner asks otherwise with `setNonBlocking()`, because `recvSome()` and
    /// `sendAll()` are written for blocking descriptors — neither treats
    /// `EAGAIN` as anything but a fatal error.
    ///
    /// The blocking reset is not hypothetical bookkeeping.
    /// macOS/BSD propagate a listening socket's `O_NONBLOCK` onto the sockets
    /// `accept(2)` returns; POSIX permits that and Linux documents that it does
    /// not do it. Without this, every connection `tryAccept()` hands back from
    /// a non-blocking listener on macOS/BSD would be non-blocking too, and a
    /// blocking reader such as `performServerHandshake()` would throw on
    /// `EAGAIN` before the client's Upgrade request had arrived. Clearing it
    /// here rather than in `tryAccept()` covers `accept()`, `connect()` and
    /// `listen()` by the same rule, and leaves one place where the mode is
    /// decided.
    ///
    /// Best effort, like `applyNoSigPipe`: an fd whose flags cannot be read or
    /// written fails its first read anyway, which every caller already handles.
    /// @param rawFd Native socket file descriptor; takes ownership.
    explicit TcpSocket(int rawFd) : _fd{rawFd} {
        applyNoSigPipe(rawFd);
        clearNonBlocking(rawFd);
    }
 
    TcpSocket(const TcpSocket&) = delete;
    TcpSocket& operator=(const TcpSocket&) = delete;
 
    /// @brief Transfers ownership of @p other's file descriptor.
    /// @param other Socket to move from; left invalid.
    TcpSocket(TcpSocket&& other) noexcept : _fd{other._fd} { other._fd = -1; }
 
    /// @brief Transfers ownership of @p other's file descriptor, closing this one first.
    /// @param other Socket to move from; left invalid.
    /// @return `*this`.
    TcpSocket& operator=(TcpSocket&& other) noexcept {
        if (this != &other) {
            closeNow();
            _fd = other._fd;
            other._fd = -1;
        }
        return *this;
    }
 
    /// @brief Closes the socket if open.
    ~TcpSocket() { closeNow(); }
 
    /// @brief Connects to `host:port`, failing after @p timeout.
    /// @param host    Numeric or resolvable hostname.
    /// @param port    TCP port.
    /// @param timeout Maximum time to wait for the connection to establish,
    ///                across *all* resolved addresses -- one deadline for the
    ///                whole call, not one per candidate.
    /// @return A connected `TcpSocket`.
    /// @throws std::runtime_error on resolution failure, connect failure, or timeout.
    static TcpSocket connect(const std::string& host, std::uint16_t port, std::chrono::milliseconds timeout) {
        addrinfo hints{};
        hints.ai_family = AF_UNSPEC;
        hints.ai_socktype = SOCK_STREAM;
        addrinfo* resolved = nullptr;
        // Widened explicitly: std::to_string has no uint16_t overload, and
        // letting the integral promotion pick one trips GCC's -Wsign-promo
        // (it would choose the signed `int` overload over `unsigned`).
        std::string const portStr = std::to_string(static_cast<unsigned>(port));
        int const rc = ::getaddrinfo(host.c_str(), portStr.c_str(), &hints, &resolved);
        if (rc != 0 || resolved == nullptr) {
            // `::gai_strerror`, and NOT `errnoMessage()`: `rc` is an `EAI_*`
            // code, not an `errno`, so `std::system_category().message(rc)`
            // would render a confidently wrong string.
            //
            // It also stays, rather than being replaced the way `std::strerror`
            // was, because it does not have `std::strerror`'s thread-safety
            // defect. This throw site can run on several threads at once (see
            // `errnoMessage` below), so the question is live; what follows is
            // measured rather than assumed.
            //
            // glibc 2.44, `gcc -O0`: `gai_strerror` returns a pointer to a
            // string literal inside libc's own read-only data, distinct per
            // code and stable across calls --
            //
            //   EAI_AGAIN ptr=0x7fa71e9b62f2 "Temporary failure in name resolution"
            //   EAI_FAIL  ptr=0x7fa71e9b632e "Non-recoverable failure in name resolution"
            //   dladdr -> /usr/lib/libc.so.6, anonymous (a literal in a data section)
            //   7fa71e99f000-7fa71ea15000 r--p ... /usr/lib/libc.so.6
            //
            // The `r--p` mapping is the load-bearing part: a shared scratch
            // buffer would have to be writable. Even an unrecognised code
            // returns a constant ("Unknown error"), not a formatted one. The
            // musl/emscripten implementation morph's WASM build uses is a
            // `static const char msgs[]` table by inspection, same property.
            // `TcpSocket` is POSIX-only (this file's own class comment), so
            // Winsock's documented-unsafe `gai_strerrorA` never applies.
            //
            // Re-check if a platform with a different libc joins CI.
            throw std::runtime_error("TcpSocket::connect: getaddrinfo failed for " + host + ": " + ::gai_strerror(rc));
        }
        struct AddrInfoGuard {
            addrinfo* p;
            ~AddrInfoGuard() { ::freeaddrinfo(p); }
        } guard{resolved};
 
        // One deadline for the whole call, not one timeout per candidate.
        // `ai_family = AF_UNSPEC` makes several candidates the norm ("localhost"
        // resolves to both ::1 and 127.0.0.1), and polling `timeout` inside the
        // loop would make the worst case N x timeout -- while two doc comments
        // (here and SocketBackend's destructor note) state it as a single
        // bound. A deadline computed once keeps the stated bound true.
        auto const deadline = std::chrono::steady_clock::now() + timeout;
 
        for (addrinfo* rp = resolved; rp != nullptr; rp = rp->ai_next) {
            int fd = ::socket(rp->ai_family, rp->ai_socktype, rp->ai_protocol);
            if (fd < 0) {
                continue;
            }
            int const flags = ::fcntl(fd, F_GETFL, 0);
            ::fcntl(fd, F_SETFL, flags | O_NONBLOCK);
            int const connectRc = ::connect(fd, rp->ai_addr, rp->ai_addrlen);
            if (connectRc == 0) {
                ::fcntl(fd, F_SETFL, flags);
                return TcpSocket{fd};
            }
            if (errno != EINPROGRESS) {
                ::close(fd);
                continue;
            }
            // A timeout or a poll failure on this candidate moves on to the
            // next; only running out of candidates is an error. A delivered
            // signal is neither (pollUntil retries across EINTR).
            if (pollUntil(fd, POLLOUT, deadline).outcome != PollOutcome::kReady) {
                ::close(fd);
                continue;
            }
            int soErr = 0;
            socklen_t soErrLen = sizeof(soErr);
            // Checked: a failing getsockopt leaves `soErr` at 0, which would
            // otherwise hand back a broken socket as successfully connected.
            if (::getsockopt(fd, SOL_SOCKET, SO_ERROR, &soErr, &soErrLen) != 0 || soErr != 0) {
                ::close(fd);
                continue;
            }
            ::fcntl(fd, F_SETFL, flags);
            return TcpSocket{fd};
        }
        throw std::runtime_error("TcpSocket::connect: could not connect to " + host + ":" + portStr);
    }
 
    /// @brief Creates a listening socket bound to `127.0.0.1:port`.
    /// @param port    TCP port to bind to; `0` lets the OS choose a free port.
    /// @param backlog Pending-connection backlog passed to `::listen`.
    /// @return A listening `TcpSocket`.
    /// @throws std::runtime_error on socket/bind/listen failure.
    static TcpSocket listen(std::uint16_t port, int backlog = 64) {
        int fd = ::socket(AF_INET, SOCK_STREAM, 0);
        if (fd < 0) {
            throw std::runtime_error("TcpSocket::listen: socket() failed: " + errnoMessage(errno));
        }
        int const reuse = 1;
        ::setsockopt(fd, SOL_SOCKET, SO_REUSEADDR, &reuse, sizeof(reuse));
        sockaddr_in addr{};
        addr.sin_family = AF_INET;
        addr.sin_port = htons(port);
        addr.sin_addr.s_addr = htonl(INADDR_LOOPBACK);
        if (::bind(fd, reinterpret_cast<sockaddr*>(&addr), sizeof(addr)) != 0) {
            int const err = errno;
            ::close(fd);
            throw std::runtime_error("TcpSocket::listen: bind() failed: " + errnoMessage(err));
        }
        if (::listen(fd, backlog) != 0) {
            int const err = errno;
            ::close(fd);
            throw std::runtime_error("TcpSocket::listen: listen() failed: " + errnoMessage(err));
        }
        return TcpSocket{fd};
    }
 
    /// @brief Returns the local port this socket is bound to, or `0` if invalid.
    /// @return The bound TCP port (useful after `listen(0, ...)`).
    [[nodiscard]] std::uint16_t boundPort() const {
        if (_fd < 0) {
            return 0;
        }
        sockaddr_in addr{};
        socklen_t len = sizeof(addr);
        ::getsockname(_fd, reinterpret_cast<sockaddr*>(&addr), &len);
        return ntohs(addr.sin_port);
    }
 
    /// @brief Blocks until a client connects, returning the accepted connection.
    ///
    /// **This call has no portable interruption mechanism.** `shutdown(2)` on a
    /// *listening* socket unblocks a parked `accept()` on Linux, but that is a
    /// Linux property rather than a POSIX one — on macOS/BSD the parked thread
    /// stays parked. Anything that has to be able to stop waiting
    /// must therefore not park here at all: use `setNonBlocking()` plus a
    /// readiness wait, and take the connection with `tryAccept()` — or hand
    /// the listener to an event loop, as `SocketServer` does. This blocking
    /// overload remains for callers that wait for exactly one known-imminent
    /// connection (the socket-level tests).
    /// @return The accepted `TcpSocket`.
    /// @throws std::runtime_error if `::accept` fails.
    TcpSocket accept() {
        for (;;) {
            int const clientFd = ::accept(_fd, nullptr, nullptr);
            if (clientFd >= 0) {
                return TcpSocket{clientFd};
            }
            // EINTR is not a failure, just a signal delivered while blocked, and
            // `recvSome`/`sendAll` already retry it. Without the same retry
            // here, any signal the host happens to deliver (a profiler's timer,
            // SIGCHLD, SIGWINCH) tears down the accept loop and the server
            // silently stops taking connections.
            //
            // Every other errno throws, and no other one is retried.
            // ECONNABORTED in particular is not special-cased: `shutdown(
            // listenfd, SHUT_RDWR)` unblocks a parked `accept()` with EINVAL,
            // not ECONNABORTED, and shutting the listener down is not how
            // anything here breaks out of an accept loop -- `SocketServer`
            // polls a self-pipe instead and never parks here at all.
            //
            // No ECONNABORTED retry is added in its place. A reset-race repro
            // over six shapes (blocking and non-blocking + poll, with and
            // without TCP_DEFER_ACCEPT, with and without data, 1- and 8-deep
            // queues) produced zero ECONNABORTED across 8000 `accept()` calls
            // on Linux: the kernel queues the reset connection, `accept`
            // succeeds, and the abort surfaces on the next `recv` as
            // ECONNRESET -- which `recvSome` already absorbs as an orderly
            // close. A retry loop here would therefore be behaviour no test on
            // this project's only CI platform could make fail.
            if (errno == EINTR) {
                continue;
            }
            throw std::runtime_error("TcpSocket::accept: " + errnoMessage(errno));
        }
    }
 
    /// @brief Puts this socket into non-blocking mode (`O_NONBLOCK`).
    ///
    /// Applied by `SocketServer` to its listening socket: `poll()` reporting a
    /// listener readable does not guarantee the following `accept()` will not
    /// block (a peer that resets in between takes the pending connection away),
    /// and a listener that parks again after the wakeup has been consumed would
    /// never be woken a second time.
    /// @return `true` if the flag was applied; `false` on an empty socket or an
    ///         `fcntl` failure.
    // Non-const for the same reason shutdownBoth() is: it mutates the open file
    // description this object owns, and a const overload would advertise a call
    // that changes nothing. ::fcntl is variadic by POSIX's design, as every
    // other fcntl call in this file already is.
    // NOLINTNEXTLINE(readability-make-member-function-const)
    [[nodiscard]] bool setNonBlocking() noexcept {
        if (_fd < 0) {
            return false;
        }
        int const flags = ::fcntl(_fd, F_GETFL, 0);
        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
        return flags >= 0 && ::fcntl(_fd, F_SETFL, flags | O_NONBLOCK) == 0;
    }
 
    /// @brief Non-blocking counterpart of `accept()`, for a listener that
    ///        `setNonBlocking()` has been applied to.
    ///
    /// The connection it yields is **blocking**, whatever mode this listener is
    /// in: the fd-adopting constructor clears `O_NONBLOCK`, which is what stops
    /// macOS/BSD's inheritance of the listener's flag reaching `recvSome()`
    /// Any rewrite of this function has to keep going through that
    /// constructor, or do the reset itself.
    /// @return The accepted `TcpSocket`, or `std::nullopt` when no connection
    ///         was pending — a readiness report that went stale before the
    ///         `accept`, which the caller answers by waiting again.
    /// @throws std::runtime_error if `::accept` fails for any other reason.
    // Non-const to match accept(): taking a connection consumes it from the
    // listener's queue, which is state this object owns.
    // NOLINTNEXTLINE(readability-make-member-function-const)
    std::optional<TcpSocket> tryAccept() {
        for (;;) {
            int const clientFd = ::accept(_fd, nullptr, nullptr);
            if (clientFd >= 0) {
                return TcpSocket{clientFd};
            }
            int const err = errno;
            if (err == EINTR) {  // retried for the same reason accept() retries it
                continue;
            }
            if (wouldBlock(err)) {
                return std::nullopt;
            }
            throw std::runtime_error("TcpSocket::tryAccept: " + errnoMessage(err));
        }
    }
 
    /// @brief Reads up to @p len bytes into @p buf.
    /// @param buf Destination buffer.
    /// @param len Capacity of @p buf.
    /// @return Number of bytes read; `0` means the peer closed the connection
    ///         (or a concurrent `shutdownBoth()` unblocked this call).
    /// @throws std::runtime_error on a socket error other than an internally
    ///         retried `EINTR` or a peer reset (treated as an orderly close).
    std::size_t recvSome(char* buf, std::size_t len) {
        for (;;) {
            ssize_t const n = ::recv(_fd, buf, len, 0);
            if (n < 0) {
                if (errno == EINTR) {
                    continue;
                }
                if (errno == ECONNRESET) {
                    return 0;
                }
                throw std::runtime_error("TcpSocket::recvSome: " + errnoMessage(errno));
            }
            return static_cast<std::size_t>(n);
        }
    }
 
    /// @brief Writes all @p len bytes of @p data, looping over partial writes.
    /// @param data Bytes to send.
    /// @param len  Number of bytes in @p data.
    /// @throws std::runtime_error on a socket error.
    void sendAll(const char* data, std::size_t len) {
        std::size_t sent = 0;
        while (sent < len) {
            ssize_t const n = ::send(_fd, data + sent, len - sent, MSG_NOSIGNAL);
            if (n < 0) {
                if (errno == EINTR) {
                    continue;
                }
                throw std::runtime_error("TcpSocket::sendAll: " + errnoMessage(errno));
            }
            sent += static_cast<std::size_t>(n);
        }
    }
 
    /// @brief Bounds how long a single `::send` inside `sendAll()` may block.
    ///
    /// Without this a `sendAll` against a peer that has stopped reading blocks
    /// forever once the kernel send buffer fills, and it does so while holding
    /// whatever lock its caller took. With `SO_SNDTIMEO` set, the blocked
    /// `send` returns `EAGAIN`/`EWOULDBLOCK` instead, `sendAll` throws as it
    /// already does for any other send error, and the lock is released.
    ///
    /// A timeout is not a "slow link" cutoff: it bounds one `send` syscall that
    /// is making *no* progress, so it should be set generously. Zero disables it
    /// (the kernel default, block forever).
    ///
    /// @param timeout Per-`send` bound; zero to disable.
    /// @return `true` if the option was applied.
    [[nodiscard]] bool setSendTimeout(std::chrono::milliseconds timeout) const noexcept {
        // Assigned without casts on purpose: `milliseconds::rep` and
        // `timeval`'s members are both `long` on the platforms this builds for,
        // so an explicit cast is an identity cast and GCC rejects it under
        // -Werror=useless-cast. clang-tidy also wants names of three characters
        // or more, hence `timeoutVal` rather than the conventional `tv`.
        timeval timeoutVal{};
        timeoutVal.tv_sec = timeout.count() / 1000;
        timeoutVal.tv_usec = (timeout.count() % 1000) * 1000;
        return ::setsockopt(_fd, SOL_SOCKET, SO_SNDTIMEO, &timeoutVal, sizeof(timeoutVal)) == 0;
    }
 
    /// @brief Bounds how long a single `::recv` (inside `recvSome()`) may block.
    ///
    /// Without this, a peer that completes the TCP handshake but never writes
    /// a byte (e.g. a load balancer connecting lazily to its backend) parks
    /// the caller in `recvSome` forever -- for `SocketBackend`'s client
    /// handshake read specifically, that in turn wedges `~SocketBackend`,
    /// since the destructor's escape hatch only reaches a socket already
    /// published to `_socket`.
    ///
    /// A timed-out `recv` makes `recvSome` throw (`EAGAIN`/`EWOULDBLOCK` is
    /// not one of the errors it treats as an orderly close), so callers meant
    /// to block indefinitely during normal operation must disable this again
    /// (`timeout` of zero) once whatever bounded phase needed it is over.
    ///
    /// @param timeout Per-`recv` bound; zero to disable.
    /// @return `true` if the option was applied.
    [[nodiscard]] bool setRecvTimeout(std::chrono::milliseconds timeout) const noexcept {
        timeval timeoutVal{};
        timeoutVal.tv_sec = timeout.count() / 1000;
        timeoutVal.tv_usec = (timeout.count() % 1000) * 1000;
        return ::setsockopt(_fd, SOL_SOCKET, SO_RCVTIMEO, &timeoutVal, sizeof(timeoutVal)) == 0;
    }
 
    /// @brief Shuts down both directions of the socket, unblocking a concurrent
    ///        `recvSome`/`sendAll` on another thread. Safe to call from any thread.
    ///
    /// Documented for *connected* sockets only, which is where `shutdown(2)`
    /// waking a parked peer call is portable. It is not a way to interrupt
    /// `accept()` on a listening socket — see `accept()`.
    void shutdownBoth() noexcept {
        if (_fd >= 0) {
            ::shutdown(_fd, SHUT_RDWR);
        }
    }
 
    /// @brief Returns the native file descriptor (`-1` if empty/moved-from).
    /// @return The native fd.
    [[nodiscard]] int nativeHandle() const noexcept { return _fd; }
 
    /// @brief Gives up ownership of the descriptor without closing it.
    ///
    /// For handing a bound listener to something that adopts it, such as
    /// `core::net::adoptListener`, which closes it from then on.
    /// @return The descriptor (`-1` if empty); this socket is empty afterwards.
    [[nodiscard]] int release() noexcept { return std::exchange(_fd, -1); }
 
    /// @brief Returns whether this socket owns an open file descriptor.
    /// @return `true` if `nativeHandle() >= 0`.
    [[nodiscard]] bool valid() const noexcept { return _fd >= 0; }
 
private:
    /// Describes `err` the way `std::strerror` would, without `std::strerror`'s
    /// shared static buffer.
    ///
    /// Every throw site in this class formats its message on whichever thread
    /// hit the error, and sockets are driven from several threads at once — a
    /// server loop and its clients' threads, in the tests. Two of them can
    /// therefore be inside a throw site at the same moment, and `std::strerror`
    /// is permitted to return a pointer to one buffer shared by all callers --
    /// a data race on the message, not merely an interleaved string.
    ///
    /// `std::error_category::message` is specified with no such carve-out, so
    /// it carries the library's ordinary "shall not introduce a data race"
    /// guarantee, and it returns an owned `std::string`, leaving nothing for
    /// two threads to share. `std::system_category()` is the category whose
    /// values are `errno` values on POSIX, which is what every caller here
    /// passes. Preferred over `strerror_r` because that function's XSI and GNU
    /// variants differ in return type, so a portable call needs a build-time
    /// discriminator and a caller-supplied buffer; this needs neither.
    static std::string errnoMessage(int err) { return std::system_category().message(err); }
 
    /// POSIX allows `EAGAIN` and `EWOULDBLOCK` to differ, and both name the
    /// same "nothing to take right now" answer. Written as two statements
    /// rather than `err == EAGAIN || err == EWOULDBLOCK` so GCC's
    /// `-Wlogical-op` cannot read it as a disjunction of equal expressions on
    /// the platforms (Linux, macOS) where the two macros expand to one value.
    static bool wouldBlock(int err) noexcept {
        if (err == EAGAIN) {
            return true;
        }
        return err == EWOULDBLOCK;
    }
 
    /// Takes `rawFd` out of non-blocking mode, if it was in it. See the
    /// fd-adopting constructor for why every adopted descriptor gets this.
    static void clearNonBlocking(int rawFd) noexcept {
        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg) — ::fcntl is variadic by POSIX's design
        int const flags = ::fcntl(rawFd, F_GETFL, 0);
        if (flags < 0 || (flags & O_NONBLOCK) == 0) {
            return;
        }
        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-vararg)
        static_cast<void>(::fcntl(rawFd, F_SETFL, flags & ~O_NONBLOCK));
    }
 
    static void applyNoSigPipe(int fd) {
#if defined(SO_NOSIGPIPE)
        int const one = 1;
        ::setsockopt(fd, SOL_SOCKET, SO_NOSIGPIPE, &one, sizeof(one));
#else
        (void)fd;
#endif
    }
 
    void closeNow() noexcept {
        if (_fd >= 0) {
            ::close(_fd);
            _fd = -1;
        }
    }
 
    int _fd{-1};
};
 
}  // namespace morph::net::detail