Branch data Line data Source code
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 : :
18 : : class 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 : : */
24 : : inline constexpr auto MAX_WAIT_FOR_IO = 1s;
25 : :
26 : 6780 : inline bool IOErrorIsPermanent(int err)
27 : : {
28 [ # # # # ]: 6780 : 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 : : */
34 : : class Sock
35 : : {
36 : : public:
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 : : * Maximum timeout supported by `Wait()` and `WaitMany()` (about 24.8 days).
166 : : * Longer timeouts are capped because `poll()` takes an `int` timeout in
167 : : * milliseconds, and `select()` rejects large timeouts on some platforms
168 : : * (e.g. macOS). Expressed in seconds so that callers can use the same value.
169 : : */
170 : : static constexpr std::chrono::seconds MAX_WAIT_TIMEOUT{std::numeric_limits<int>::max() / 1000};
171 : :
172 : : /**
173 : : * Wait for readiness for input (recv) or output (send).
174 : : * @param[in] timeout Wait this much for at least one of the requested events to occur.
175 : : * Capped at `MAX_WAIT_TIMEOUT`.
176 : : * @param[in] requested Wait for those events, bitwise-or of `RecvEvent` and `SendEvent`.
177 : : * @param[out] occurred If not nullptr and the function returns `true`, then this
178 : : * indicates which of the requested events occurred (`ErrorEvent` will be added, even if
179 : : * not requested, if an exceptional event occurs on the socket).
180 : : * A timeout is indicated by return value of `true` and `occurred` being set to 0.
181 : : * @return true on success (or timeout, if `occurred` of 0 is returned), false otherwise
182 : : */
183 : : [[nodiscard]] virtual bool Wait(std::chrono::milliseconds timeout,
184 : : Event requested,
185 : : Event* occurred = nullptr) const;
186 : :
187 : : /**
188 : : * Auxiliary requested/occurred events to wait for in `WaitMany()`.
189 : : */
190 : : struct Events {
191 [ # # ][ # # ]: 1849724 : explicit Events(Event req) : requested{req} {}
[ + - + - ]
192 : : Event requested;
193 : : Event occurred{0};
194 : : };
195 : :
196 : : struct HashSharedPtrSock {
197 : 1859534 : size_t operator()(const std::shared_ptr<const Sock>& s) const
198 : : {
199 [ + - ]: 1859534 : return s ? s->m_socket : std::numeric_limits<SOCKET>::max();
[ # # # # ]
200 : : }
201 : : };
202 : :
203 : : struct EqualSharedPtrSock {
204 : 1829136 : bool operator()(const std::shared_ptr<const Sock>& lhs,
205 : : const std::shared_ptr<const Sock>& rhs) const
206 : : {
207 [ + - + - ]: 1829136 : if (lhs && rhs) {
208 : 1829136 : return lhs->m_socket == rhs->m_socket;
209 : : }
210 [ # # # # ]: 0 : if (!lhs && !rhs) {
211 : 0 : return true;
212 : : }
213 : : return false;
214 : : }
215 : : };
216 : :
217 : : /**
218 : : * On which socket to wait for what events in `WaitMany()`.
219 : : * The `shared_ptr` is copied into the map to ensure that the `Sock` object
220 : : * is not destroyed (its destructor would close the underlying socket).
221 : : * If this happens shortly before or after we call `poll(2)` and a new
222 : : * socket gets created under the same file descriptor number then the report
223 : : * from `WaitMany()` will be bogus.
224 : : */
225 : : using EventsPerSock = std::unordered_map<std::shared_ptr<const Sock>, Events, HashSharedPtrSock, EqualSharedPtrSock>;
226 : :
227 : : /**
228 : : * Same as `Wait()`, but wait on many sockets within the same timeout.
229 : : * @param[in] timeout Wait this long for at least one of the requested events to occur.
230 : : * Capped at `MAX_WAIT_TIMEOUT`.
231 : : * @param[in,out] events_per_sock Wait for the requested events on these sockets and set
232 : : * `occurred` for the events that actually occurred.
233 : : * @return true on success (or timeout, if all `what[].occurred` are returned as 0),
234 : : * false otherwise
235 : : */
236 : : [[nodiscard]] virtual bool WaitMany(std::chrono::milliseconds timeout,
237 : : EventsPerSock& events_per_sock) const;
238 : :
239 : : /* Higher level, convenience, methods. These may throw. */
240 : :
241 : : /**
242 : : * Send the given data, retrying on transient errors.
243 : : * @param[in] data Data to send.
244 : : * @param[in] timeout Timeout for the entire operation.
245 : : * @param[in] interrupt If this is signaled then the operation is canceled.
246 : : * @throws std::runtime_error if the operation cannot be completed. In this case only some of
247 : : * the data will be written to the socket.
248 : : */
249 : : virtual void SendComplete(std::span<const unsigned char> data,
250 : : std::chrono::milliseconds timeout,
251 : : CThreadInterrupt& interrupt) const;
252 : :
253 : : /**
254 : : * Convenience method, equivalent to `SendComplete(MakeUCharSpan(data), timeout, interrupt)`.
255 : : */
256 : : virtual void SendComplete(std::span<const char> data,
257 : : std::chrono::milliseconds timeout,
258 : : CThreadInterrupt& interrupt) const;
259 : :
260 : : /**
261 : : * Read from socket until a terminator character is encountered. Will never consume bytes past
262 : : * the terminator from the socket.
263 : : * @param[in] terminator Character up to which to read from the socket.
264 : : * @param[in] timeout Timeout for the entire operation.
265 : : * @param[in] interrupt If this is signaled then the operation is canceled.
266 : : * @param[in] max_data The maximum amount of data (in bytes) to receive. If this many bytes
267 : : * are received and there is still no terminator, then this method will throw an exception.
268 : : * @return The data that has been read, without the terminating character.
269 : : * @throws std::runtime_error if the operation cannot be completed. In this case some bytes may
270 : : * have been consumed from the socket.
271 : : */
272 : : [[nodiscard]] virtual std::string RecvUntilTerminator(uint8_t terminator,
273 : : std::chrono::milliseconds timeout,
274 : : CThreadInterrupt& interrupt,
275 : : size_t max_data) const;
276 : :
277 : : /**
278 : : * Check if still connected.
279 : : * @param[out] errmsg The error string, if the socket has been disconnected.
280 : : * @return true if connected
281 : : */
282 : : [[nodiscard]] virtual bool IsConnected(std::string& errmsg) const;
283 : :
284 : : /**
285 : : * Check if the internal socket is equal to `s`. Use only in tests.
286 : : */
287 : : bool operator==(SOCKET s) const;
288 : :
289 : : protected:
290 : : /**
291 : : * Contained socket. `INVALID_SOCKET` designates the object is empty.
292 : : */
293 : : SOCKET m_socket;
294 : :
295 : : private:
296 : : /**
297 : : * Close `m_socket` if it is not `INVALID_SOCKET`.
298 : : */
299 : : void Close();
300 : : };
301 : :
302 : : /** Return readable error string for a network error code */
303 : : std::string NetworkErrorString(int err);
304 : :
305 : : #endif // BITCOIN_UTIL_SOCK_H
|
