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
288
|
@since(version = 0.2.0)
interface udp {
@since(version = 0.2.0)
use wasi:io/poll@0.2.1.{pollable};
@since(version = 0.2.0)
use network.{network, error-code, ip-socket-address, ip-address-family};
/// A received datagram.
@since(version = 0.2.0)
record incoming-datagram {
/// The payload.
///
/// Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
data: list<u8>,
/// The source address.
///
/// This field is guaranteed to match the remote address the stream was initialized with, if any.
///
/// Equivalent to the `src_addr` out parameter of `recvfrom`.
remote-address: ip-socket-address,
}
/// A datagram to be sent out.
@since(version = 0.2.0)
record outgoing-datagram {
/// The payload.
data: list<u8>,
/// The destination address.
///
/// The requirements on this field depend on how the stream was initialized:
/// - with a remote address: this field must be None or match the stream's remote address exactly.
/// - without a remote address: this field is required.
///
/// If this value is None, the send operation is equivalent to `send` in POSIX. Otherwise it is equivalent to `sendto`.
remote-address: option<ip-socket-address>,
}
/// A UDP socket handle.
@since(version = 0.2.0)
resource udp-socket {
/// Bind the socket to a specific network on the provided IP address and port.
///
/// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
/// network interface(s) to bind to.
/// If the port is zero, the socket will be bound to a random free port.
///
/// # Typical errors
/// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
/// - `invalid-state`: The socket is already bound. (EINVAL)
/// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
/// - `address-in-use`: Address is already in use. (EADDRINUSE)
/// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
/// - `not-in-progress`: A `bind` operation is not in progress.
/// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
///
/// # Implementors note
/// Unlike in POSIX, in WASI the bind operation is async. This enables
/// interactive WASI hosts to inject permission prompts. Runtimes that
/// don't want to make use of this ability can simply call the native
/// `bind` as part of either `start-bind` or `finish-bind`.
///
/// # References
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
/// - <https://man7.org/linux/man-pages/man2/bind.2.html>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
/// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
@since(version = 0.2.0)
start-bind: func(network: borrow<network>, local-address: ip-socket-address) -> result<_, error-code>;
@since(version = 0.2.0)
finish-bind: func() -> result<_, error-code>;
/// Set up inbound & outbound communication channels, optionally to a specific peer.
///
/// This function only changes the local socket configuration and does not generate any network traffic.
/// On success, the `remote-address` of the socket is updated. The `local-address` may be updated as well,
/// based on the best network path to `remote-address`.
///
/// When a `remote-address` is provided, the returned streams are limited to communicating with that specific peer:
/// - `send` can only be used to send to this destination.
/// - `receive` will only return datagrams sent from the provided `remote-address`.
///
/// This method may be called multiple times on the same socket to change its association, but
/// only the most recently returned pair of streams will be operational. Implementations may trap if
/// the streams returned by a previous invocation haven't been dropped yet before calling `stream` again.
///
/// The POSIX equivalent in pseudo-code is:
/// ```text
/// if (was previously connected) {
/// connect(s, AF_UNSPEC)
/// }
/// if (remote_address is Some) {
/// connect(s, remote_address)
/// }
/// ```
///
/// Unlike in POSIX, the socket must already be explicitly bound.
///
/// # Typical errors
/// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
/// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
/// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
/// - `invalid-state`: The socket is not bound.
/// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
/// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
/// - `connection-refused`: The connection was refused. (ECONNREFUSED)
///
/// # References
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
/// - <https://man7.org/linux/man-pages/man2/connect.2.html>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
/// - <https://man.freebsd.org/cgi/man.cgi?connect>
@since(version = 0.2.0)
%stream: func(remote-address: option<ip-socket-address>) -> result<tuple<incoming-datagram-stream, outgoing-datagram-stream>, error-code>;
/// Get the current bound address.
///
/// POSIX mentions:
/// > If the socket has not been bound to a local name, the value
/// > stored in the object pointed to by `address` is unspecified.
///
/// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
///
/// # Typical errors
/// - `invalid-state`: The socket is not bound to any local address.
///
/// # References
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
/// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
/// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
@since(version = 0.2.0)
local-address: func() -> result<ip-socket-address, error-code>;
/// Get the address the socket is currently streaming to.
///
/// # Typical errors
/// - `invalid-state`: The socket is not streaming to a specific remote address. (ENOTCONN)
///
/// # References
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
/// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
/// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
@since(version = 0.2.0)
remote-address: func() -> result<ip-socket-address, error-code>;
/// Whether this is a IPv4 or IPv6 socket.
///
/// Equivalent to the SO_DOMAIN socket option.
@since(version = 0.2.0)
address-family: func() -> ip-address-family;
/// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
///
/// If the provided value is 0, an `invalid-argument` error is returned.
///
/// # Typical errors
/// - `invalid-argument`: (set) The TTL value must be 1 or higher.
@since(version = 0.2.0)
unicast-hop-limit: func() -> result<u8, error-code>;
@since(version = 0.2.0)
set-unicast-hop-limit: func(value: u8) -> result<_, error-code>;
/// The kernel buffer space reserved for sends/receives on this socket.
///
/// If the provided value is 0, an `invalid-argument` error is returned.
/// Any other value will never cause an error, but it might be silently clamped and/or rounded.
/// I.e. after setting a value, reading the same setting back may return a different value.
///
/// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
///
/// # Typical errors
/// - `invalid-argument`: (set) The provided value was 0.
@since(version = 0.2.0)
receive-buffer-size: func() -> result<u64, error-code>;
@since(version = 0.2.0)
set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
@since(version = 0.2.0)
send-buffer-size: func() -> result<u64, error-code>;
@since(version = 0.2.0)
set-send-buffer-size: func(value: u64) -> result<_, error-code>;
/// Create a `pollable` which will resolve once the socket is ready for I/O.
///
/// Note: this function is here for WASI Preview2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
@since(version = 0.2.0)
subscribe: func() -> pollable;
}
@since(version = 0.2.0)
resource incoming-datagram-stream {
/// Receive messages on the socket.
///
/// This function attempts to receive up to `max-results` datagrams on the socket without blocking.
/// The returned list may contain fewer elements than requested, but never more.
///
/// This function returns successfully with an empty list when either:
/// - `max-results` is 0, or:
/// - `max-results` is greater than 0, but no results are immediately available.
/// This function never returns `error(would-block)`.
///
/// # Typical errors
/// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
/// - `connection-refused`: The connection was refused. (ECONNREFUSED)
///
/// # References
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html>
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvmsg.html>
/// - <https://man7.org/linux/man-pages/man2/recv.2.html>
/// - <https://man7.org/linux/man-pages/man2/recvmmsg.2.html>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recv>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom>
/// - <https://learn.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms741687(v=vs.85)>
/// - <https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2>
@since(version = 0.2.0)
receive: func(max-results: u64) -> result<list<incoming-datagram>, error-code>;
/// Create a `pollable` which will resolve once the stream is ready to receive again.
///
/// Note: this function is here for WASI Preview2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
@since(version = 0.2.0)
subscribe: func() -> pollable;
}
@since(version = 0.2.0)
resource outgoing-datagram-stream {
/// Check readiness for sending. This function never blocks.
///
/// Returns the number of datagrams permitted for the next call to `send`,
/// or an error. Calling `send` with more datagrams than this function has
/// permitted will trap.
///
/// When this function returns ok(0), the `subscribe` pollable will
/// become ready when this function will report at least ok(1), or an
/// error.
///
/// Never returns `would-block`.
check-send: func() -> result<u64, error-code>;
/// Send messages on the socket.
///
/// This function attempts to send all provided `datagrams` on the socket without blocking and
/// returns how many messages were actually sent (or queued for sending). This function never
/// returns `error(would-block)`. If none of the datagrams were able to be sent, `ok(0)` is returned.
///
/// This function semantically behaves the same as iterating the `datagrams` list and sequentially
/// sending each individual datagram until either the end of the list has been reached or the first error occurred.
/// If at least one datagram has been sent successfully, this function never returns an error.
///
/// If the input list is empty, the function returns `ok(0)`.
///
/// Each call to `send` must be permitted by a preceding `check-send`. Implementations must trap if
/// either `check-send` was not called or `datagrams` contains more items than `check-send` permitted.
///
/// # Typical errors
/// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
/// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
/// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
/// - `invalid-argument`: The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `stream`. (EISCONN)
/// - `invalid-argument`: The socket is not "connected" and no value for `remote-address` was provided. (EDESTADDRREQ)
/// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
/// - `connection-refused`: The connection was refused. (ECONNREFUSED)
/// - `datagram-too-large`: The datagram is too large. (EMSGSIZE)
///
/// # References
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html>
/// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html>
/// - <https://man7.org/linux/man-pages/man2/send.2.html>
/// - <https://man7.org/linux/man-pages/man2/sendmmsg.2.html>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-sendto>
/// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg>
/// - <https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2>
@since(version = 0.2.0)
send: func(datagrams: list<outgoing-datagram>) -> result<u64, error-code>;
/// Create a `pollable` which will resolve once the stream is ready to send again.
///
/// Note: this function is here for WASI Preview2 only.
/// It's planned to be removed when `future` is natively supported in Preview3.
@since(version = 0.2.0)
subscribe: func() -> pollable;
}
}
|
