Inside Bitcoin

1// Copyright (c) 2020-present The Bitcoin Core developers
2// Distributed under the MIT software license, see the accompanying
3// file COPYING or http://www.opensource.org/licenses/mit-license.php.
4
5#ifndef BITCOIN_UTIL_SOCK_H
6#define BITCOIN_UTIL_SOCK_H
7
8#include <compat/compat.h>
9#include <util/time.h>
10
11#include <cstdint>
12#include <limits>
13#include <memory>
14#include <span>
15#include <string>
16#include <unordered_map>
17
18class CThreadInterrupt;
19
20/**
21 * Maximum time to wait for I/O readiness.
22 * It will take up until this time to break off in case of an interruption.
23 */
24inline constexpr auto MAX_WAIT_FOR_IO = 1s;
25
26inline bool IOErrorIsPermanent(int err)
27{
28    return err != WSAEAGAIN && err != WSAEINTR && err != WSAEWOULDBLOCK && err != WSAEINPROGRESS;
29}
30
31/**
32 * RAII helper class that manages a socket and closes it automatically when it goes out of scope.
33 */
34class Sock
35{
36public:
37    Sock() = delete;
38
39    /**
40     * Take ownership of an existent socket.
41     */
42    explicit Sock(SOCKET s);
43
44    /**
45     * Copy constructor, disabled because closing the same socket twice is undesirable.
46     */
47    Sock(const Sock&) = delete;
48
49    /**
50     * Move constructor, grab the socket from another object and close ours (if set).
51     */
52    Sock(Sock&& other);
53
54    /**
55     * Destructor, close the socket or do nothing if empty.
56     */
57    virtual ~Sock();
58
59    /**
60     * Copy assignment operator, disabled because closing the same socket twice is undesirable.
61     */
62    Sock& operator=(const Sock&) = delete;
63
64    /**
65     * Move assignment operator, grab the socket from another object and close ours (if set).
66     */
67    virtual Sock& operator=(Sock&& other);
68
69    /**
70     * send(2) wrapper. Equivalent to `send(m_socket, data, len, flags);`. Code that uses this
71     * wrapper can be unit tested if this method is overridden by a mock Sock implementation.
72     */
73    [[nodiscard]] virtual ssize_t Send(const void* data, size_t len, int flags) const;
74
75    /**
76     * recv(2) wrapper. Equivalent to `recv(m_socket, buf, len, flags);`. Code that uses this
77     * wrapper can be unit tested if this method is overridden by a mock Sock implementation.
78     */
79    [[nodiscard]] virtual ssize_t Recv(void* buf, size_t len, int flags) const;
80
81    /**
82     * connect(2) wrapper. Equivalent to `connect(m_socket, addr, addrlen)`. Code that uses this
83     * wrapper can be unit tested if this method is overridden by a mock Sock implementation.
84     */
85    [[nodiscard]] virtual int Connect(const sockaddr* addr, socklen_t addr_len) const;
86
87    /**
88     * bind(2) wrapper. Equivalent to `bind(m_socket, addr, addr_len)`. Code that uses this
89     * wrapper can be unit tested if this method is overridden by a mock Sock implementation.
90     */
91    [[nodiscard]] virtual int Bind(const sockaddr* addr, socklen_t addr_len) const;
92
93    /**
94     * listen(2) wrapper. Equivalent to `listen(m_socket, backlog)`. Code that uses this
95     * wrapper can be unit tested if this method is overridden by a mock Sock implementation.
96     */
97    [[nodiscard]] virtual int Listen(int backlog) const;
98
99    /**
100     * accept(2) wrapper. Equivalent to `std::make_unique<Sock>(accept(m_socket, addr, addr_len))`.
101     * Code that uses this wrapper can be unit tested if this method is overridden by a mock Sock
102     * implementation.
103     * The returned unique_ptr is empty if `accept()` failed in which case errno will be set.
104     */
105    [[nodiscard]] virtual std::unique_ptr<Sock> Accept(sockaddr* addr, socklen_t* addr_len) const;
106
107    /**
108     * getsockopt(2) wrapper. Equivalent to
109     * `getsockopt(m_socket, level, opt_name, opt_val, opt_len)`. Code that uses this
110     * wrapper can be unit tested if this method is overridden by a mock Sock implementation.
111     */
112    [[nodiscard]] virtual int GetSockOpt(int level,
113                                         int opt_name,
114                                         void* opt_val,
115                                         socklen_t* opt_len) const;
116
117    /**
118     * setsockopt(2) wrapper. Equivalent to
119     * `setsockopt(m_socket, level, opt_name, opt_val, opt_len)`. Code that uses this
120     * wrapper can be unit tested if this method is overridden by a mock Sock implementation.
121     */
122    [[nodiscard]] virtual int SetSockOpt(int level,
123                                         int opt_name,
124                                         const void* opt_val,
125                                         socklen_t opt_len) const;
126
127    /**
128     * getsockname(2) wrapper. Equivalent to
129     * `getsockname(m_socket, name, name_len)`. Code that uses this
130     * wrapper can be unit tested if this method is overridden by a mock Sock implementation.
131     */
132    [[nodiscard]] virtual int GetSockName(sockaddr* name, socklen_t* name_len) const;
133
134    /**
135     * Set the non-blocking option on the socket.
136     * @return true if set successfully
137     */
138    [[nodiscard]] virtual bool SetNonBlocking() const;
139
140    /**
141     * Check if the underlying socket can be used for `select(2)` (or the `Wait()` method).
142     * @return true if selectable
143     */
144    [[nodiscard]] virtual bool IsSelectable() const;
145
146    using Event = uint8_t;
147
148    /**
149     * If passed to `Wait()`, then it will wait for readiness to read from the socket.
150     */
151    static constexpr Event RecvEvent = 0b001;
152
153    /**
154     * If passed to `Wait()`, then it will wait for readiness to send to the socket.
155     */
156    static constexpr Event SendEvent = 0b010;
157
158    /**
159     * Ignored if passed to `Wait()`, but could be set in the occurred events if an
160     * exceptional condition has occurred on the socket or if it has been disconnected.
161     */
162    static constexpr Event ErrorEvent = 0b100;
163
164    /**
165     * Wait for readiness for input (recv) or output (send).
166     * @param[in] timeout Wait this much for at least one of the requested events to occur.
167     * @param[in] requested Wait for those events, bitwise-or of `RecvEvent` and `SendEvent`.
168     * @param[out] occurred If not nullptr and the function returns `true`, then this
169     * indicates which of the requested events occurred (`ErrorEvent` will be added, even if
170     * not requested, if an exceptional event occurs on the socket).
171     * A timeout is indicated by return value of `true` and `occurred` being set to 0.
172     * @return true on success (or timeout, if `occurred` of 0 is returned), false otherwise
173     */
174    [[nodiscard]] virtual bool Wait(std::chrono::milliseconds timeout,
175                                    Event requested,
176                                    Event* occurred = nullptr) const;
177
178    /**
179     * Auxiliary requested/occurred events to wait for in `WaitMany()`.
180     */
181    struct Events {
182        explicit Events(Event req) : requested{req} {}
183        Event requested;
184        Event occurred{0};
185    };
186
187    struct HashSharedPtrSock {
188        size_t operator()(const std::shared_ptr<const Sock>& s) const
189        {
190            return s ? s->m_socket : std::numeric_limits<SOCKET>::max();
191        }
192    };
193
194    struct EqualSharedPtrSock {
195        bool operator()(const std::shared_ptr<const Sock>& lhs,
196                        const std::shared_ptr<const Sock>& rhs) const
197        {
198            if (lhs && rhs) {
199                return lhs->m_socket == rhs->m_socket;
200            }
201            if (!lhs && !rhs) {
202                return true;
203            }
204            return false;
205        }
206    };
207
208    /**
209     * On which socket to wait for what events in `WaitMany()`.
210     * The `shared_ptr` is copied into the map to ensure that the `Sock` object
211     * is not destroyed (its destructor would close the underlying socket).
212     * If this happens shortly before or after we call `poll(2)` and a new
213     * socket gets created under the same file descriptor number then the report
214     * from `WaitMany()` will be bogus.
215     */
216    using EventsPerSock = std::unordered_map<std::shared_ptr<const Sock>, Events, HashSharedPtrSock, EqualSharedPtrSock>;
217
218    /**
219     * Same as `Wait()`, but wait on many sockets within the same timeout.
220     * @param[in] timeout Wait this long for at least one of the requested events to occur.
221     * @param[in,out] events_per_sock Wait for the requested events on these sockets and set
222     * `occurred` for the events that actually occurred.
223     * @return true on success (or timeout, if all `what[].occurred` are returned as 0),
224     * false otherwise
225     */
226    [[nodiscard]] virtual bool WaitMany(std::chrono::milliseconds timeout,
227                                        EventsPerSock& events_per_sock) const;
228
229    /* Higher level, convenience, methods. These may throw. */
230
231    /**
232     * Send the given data, retrying on transient errors.
233     * @param[in] data Data to send.
234     * @param[in] timeout Timeout for the entire operation.
235     * @param[in] interrupt If this is signaled then the operation is canceled.
236     * @throws std::runtime_error if the operation cannot be completed. In this case only some of
237     * the data will be written to the socket.
238     */
239    virtual void SendComplete(std::span<const unsigned char> data,
240                              std::chrono::milliseconds timeout,
241                              CThreadInterrupt& interrupt) const;
242
243    /**
244     * Convenience method, equivalent to `SendComplete(MakeUCharSpan(data), timeout, interrupt)`.
245     */
246    virtual void SendComplete(std::span<const char> data,
247                              std::chrono::milliseconds timeout,
248                              CThreadInterrupt& interrupt) const;
249
250    /**