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