Debian Codegraph @

wasi/p2/wit/deps/wasi-sockets-0.2.0/package.wit

raw
1 package wasi:[email protected];
2
3 interface network {
4 /// An opaque resource that represents access to (a subset of) the network.
5 /// This enables context-based security for networking.
6 /// There is no need for this to map 1:1 to a physical network interface.
7 resource network;
8
9 /// Error codes.
10 ///
11 /// In theory, every API can return any error code.
12 /// In practice, API's typically only return the errors documented per API
13 /// combined with a couple of errors that are always possible:
14 /// - `unknown`
15 /// - `access-denied`
16 /// - `not-supported`
17 /// - `out-of-memory`
18 /// - `concurrency-conflict`
19 ///
20 /// See each individual API for what the POSIX equivalents are. They sometimes differ per API.
21 enum error-code {
22 /// Unknown error
23 unknown,
24 /// Access denied.
25 ///
26 /// POSIX equivalent: EACCES, EPERM
27 access-denied,
28 /// The operation is not supported.
29 ///
30 /// POSIX equivalent: EOPNOTSUPP
31 not-supported,
32 /// One of the arguments is invalid.
33 ///
34 /// POSIX equivalent: EINVAL
35 invalid-argument,
36 /// Not enough memory to complete the operation.
37 ///
38 /// POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY
39 out-of-memory,
40 /// The operation timed out before it could finish completely.
41 timeout,
42 /// This operation is incompatible with another asynchronous operation that is already in progress.
43 ///
44 /// POSIX equivalent: EALREADY
45 concurrency-conflict,
46 /// Trying to finish an asynchronous operation that:
47 /// - has not been started yet, or:
48 /// - was already finished by a previous `finish-*` call.
49 ///
50 /// Note: this is scheduled to be removed when `future`s are natively supported.
51 not-in-progress,
52 /// The operation has been aborted because it could not be completed immediately.
53 ///
54 /// Note: this is scheduled to be removed when `future`s are natively supported.
55 would-block,
56 /// The operation is not valid in the socket's current state.
57 invalid-state,
58 /// A new socket resource could not be created because of a system limit.
59 new-socket-limit,
60 /// A bind operation failed because the provided address is not an address that the `network` can bind to.
61 address-not-bindable,
62 /// A bind operation failed because the provided address is already in use or because there are no ephemeral ports available.
63 address-in-use,
64 /// The remote address is not reachable
65 remote-unreachable,
66 /// The TCP connection was forcefully rejected
67 connection-refused,
68 /// The TCP connection was reset.
69 connection-reset,
70 /// A TCP connection was aborted.
71 connection-aborted,
72 /// The size of a datagram sent to a UDP socket exceeded the maximum
73 /// supported size.
74 datagram-too-large,
75 /// Name does not exist or has no suitable associated IP addresses.
76 name-unresolvable,
77 /// A temporary failure in name resolution occurred.
78 temporary-resolver-failure,
79 /// A permanent failure in name resolution occurred.
80 permanent-resolver-failure,
81 }
82
83 enum ip-address-family {
84 /// Similar to `AF_INET` in POSIX.
85 ipv4,
86 /// Similar to `AF_INET6` in POSIX.
87 ipv6,
88 }
89
90 type ipv4-address = tuple<u8, u8, u8, u8>;
91
92 type ipv6-address = tuple<u16, u16, u16, u16, u16, u16, u16, u16>;
93
94 variant ip-address {
95 ipv4(ipv4-address),
96 ipv6(ipv6-address),
97 }
98
99 record ipv4-socket-address {
100 /// sin_port
101 port: u16,
102 /// sin_addr
103 address: ipv4-address,
104 }
105
106 record ipv6-socket-address {
107 /// sin6_port
108 port: u16,
109 /// sin6_flowinfo
110 flow-info: u32,
111 /// sin6_addr
112 address: ipv6-address,
113 /// sin6_scope_id
114 scope-id: u32,
115 }
116
117 variant ip-socket-address {
118 ipv4(ipv4-socket-address),
119 ipv6(ipv6-socket-address),
120 }
121 }
122
123 /// This interface provides a value-export of the default network handle..
124 interface instance-network {
125 use network.{network};
126
127 /// Get a handle to the default network.
128 instance-network: func() -> network;
129 }
130
131 interface ip-name-lookup {
132 use wasi:io/[email protected].{pollable};
133 use network.{network, error-code, ip-address};
134
135 resource resolve-address-stream {
136 /// Returns the next address from the resolver.
137 ///
138 /// This function should be called multiple times. On each call, it will
139 /// return the next address in connection order preference. If all
140 /// addresses have been exhausted, this function returns `none`.
141 ///
142 /// This function never returns IPv4-mapped IPv6 addresses.
143 ///
144 /// # Typical errors
145 /// - `name-unresolvable`: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
146 /// - `temporary-resolver-failure`: A temporary failure in name resolution occurred. (EAI_AGAIN)
147 /// - `permanent-resolver-failure`: A permanent failure in name resolution occurred. (EAI_FAIL)
148 /// - `would-block`: A result is not available yet. (EWOULDBLOCK, EAGAIN)
149 resolve-next-address: func() -> result<option<ip-address>, error-code>;
150 /// Create a `pollable` which will resolve once the stream is ready for I/O.
151 ///
152 /// Note: this function is here for WASI Preview2 only.
153 /// It's planned to be removed when `future` is natively supported in Preview3.
154 subscribe: func() -> pollable;
155 }
156
157 /// Resolve an internet host name to a list of IP addresses.
158 ///
159 /// Unicode domain names are automatically converted to ASCII using IDNA encoding.
160 /// If the input is an IP address string, the address is parsed and returned
161 /// as-is without making any external requests.
162 ///
163 /// See the wasi-socket proposal README.md for a comparison with getaddrinfo.
164 ///
165 /// This function never blocks. It either immediately fails or immediately
166 /// returns successfully with a `resolve-address-stream` that can be used
167 /// to (asynchronously) fetch the results.
168 ///
169 /// # Typical errors
170 /// - `invalid-argument`: `name` is a syntactically invalid domain name or IP address.
171 ///
172 /// # References:
173 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html>
174 /// - <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>
175 /// - <https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo>
176 /// - <https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3>
177 resolve-addresses: func(network: borrow<network>, name: string) -> result<resolve-address-stream, error-code>;
178 }
179
180 interface tcp {
181 use wasi:io/[email protected].{input-stream, output-stream};
182 use wasi:io/[email protected].{pollable};
183 use wasi:clocks/[email protected].{duration};
184 use network.{network, error-code, ip-socket-address, ip-address-family};
185
186 enum shutdown-type {
187 /// Similar to `SHUT_RD` in POSIX.
188 receive,
189 /// Similar to `SHUT_WR` in POSIX.
190 send,
191 /// Similar to `SHUT_RDWR` in POSIX.
192 both,
193 }
194
195 /// A TCP socket resource.
196 ///
197 /// The socket can be in one of the following states:
198 /// - `unbound`
199 /// - `bind-in-progress`
200 /// - `bound` (See note below)
201 /// - `listen-in-progress`
202 /// - `listening`
203 /// - `connect-in-progress`
204 /// - `connected`
205 /// - `closed`
206 /// See <https://github.com/WebAssembly/wasi-sockets/TcpSocketOperationalSemantics.md>
207 /// for a more information.
208 ///
209 /// Note: Except where explicitly mentioned, whenever this documentation uses
210 /// the term "bound" without backticks it actually means: in the `bound` state *or higher*.
211 /// (i.e. `bound`, `listen-in-progress`, `listening`, `connect-in-progress` or `connected`)
212 ///
213 /// In addition to the general error codes documented on the
214 /// `network::error-code` type, TCP socket methods may always return
215 /// `error(invalid-state)` when in the `closed` state.
216 resource tcp-socket {
217 /// Bind the socket to a specific network on the provided IP address and port.
218 ///
219 /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
220 /// network interface(s) to bind to.
221 /// If the TCP/UDP port is zero, the socket will be bound to a random free port.
222 ///
223 /// Bind can be attempted multiple times on the same socket, even with
224 /// different arguments on each iteration. But never concurrently and
225 /// only as long as the previous bind failed. Once a bind succeeds, the
226 /// binding can't be changed anymore.
227 ///
228 /// # Typical errors
229 /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
230 /// - `invalid-argument`: `local-address` is not a unicast address. (EINVAL)
231 /// - `invalid-argument`: `local-address` is an IPv4-mapped IPv6 address. (EINVAL)
232 /// - `invalid-state`: The socket is already bound. (EINVAL)
233 /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
234 /// - `address-in-use`: Address is already in use. (EADDRINUSE)
235 /// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
236 /// - `not-in-progress`: A `bind` operation is not in progress.
237 /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
238 ///
239 /// # Implementors note
240 /// When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
241 /// state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
242 /// socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
243 /// and SO_REUSEADDR performs something different entirely.
244 ///
245 /// Unlike in POSIX, in WASI the bind operation is async. This enables
246 /// interactive WASI hosts to inject permission prompts. Runtimes that
247 /// don't want to make use of this ability can simply call the native
248 /// `bind` as part of either `start-bind` or `finish-bind`.
249 ///
250 /// # References
251 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
252 /// - <https://man7.org/linux/man-pages/man2/bind.2.html>
253 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
254 /// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
255 start-bind: func(network: borrow<network>, local-address: ip-socket-address) -> result<_, error-code>;
256 finish-bind: func() -> result<_, error-code>;
257 /// Connect to a remote endpoint.
258 ///
259 /// On success:
260 /// - the socket is transitioned into the `connection` state.
261 /// - a pair of streams is returned that can be used to read & write to the connection
262 ///
263 /// After a failed connection attempt, the socket will be in the `closed`
264 /// state and the only valid action left is to `drop` the socket. A single
265 /// socket can not be used to connect more than once.
266 ///
267 /// # Typical errors
268 /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
269 /// - `invalid-argument`: `remote-address` is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
270 /// - `invalid-argument`: `remote-address` is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)
271 /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows)
272 /// - `invalid-argument`: The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows)
273 /// - `invalid-argument`: The socket is already attached to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
274 /// - `invalid-state`: The socket is already in the `connected` state. (EISCONN)
275 /// - `invalid-state`: The socket is already in the `listening` state. (EOPNOTSUPP, EINVAL on Windows)
276 /// - `timeout`: Connection timed out. (ETIMEDOUT)
277 /// - `connection-refused`: The connection was forcefully rejected. (ECONNREFUSED)
278 /// - `connection-reset`: The connection was reset. (ECONNRESET)
279 /// - `connection-aborted`: The connection was aborted. (ECONNABORTED)
280 /// - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
281 /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
282 /// - `not-in-progress`: A connect operation is not in progress.
283 /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
284 ///
285 /// # Implementors note
286 /// The POSIX equivalent of `start-connect` is the regular `connect` syscall.
287 /// Because all WASI sockets are non-blocking this is expected to return
288 /// EINPROGRESS, which should be translated to `ok()` in WASI.
289 ///
290 /// The POSIX equivalent of `finish-connect` is a `poll` for event `POLLOUT`
291 /// with a timeout of 0 on the socket descriptor. Followed by a check for
292 /// the `SO_ERROR` socket option, in case the poll signaled readiness.
293 ///
294 /// # References
295 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
296 /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
297 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
298 /// - <https://man.freebsd.org/cgi/man.cgi?connect>
299 start-connect: func(network: borrow<network>, remote-address: ip-socket-address) -> result<_, error-code>;
300 finish-connect: func() -> result<tuple<input-stream, output-stream>, error-code>;
301 /// Start listening for new connections.
302 ///
303 /// Transitions the socket into the `listening` state.
304 ///
305 /// Unlike POSIX, the socket must already be explicitly bound.
306 ///
307 /// # Typical errors
308 /// - `invalid-state`: The socket is not bound to any local address. (EDESTADDRREQ)
309 /// - `invalid-state`: The socket is already in the `connected` state. (EISCONN, EINVAL on BSD)
310 /// - `invalid-state`: The socket is already in the `listening` state.
311 /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
312 /// - `not-in-progress`: A listen operation is not in progress.
313 /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
314 ///
315 /// # Implementors note
316 /// Unlike in POSIX, in WASI the listen operation is async. This enables
317 /// interactive WASI hosts to inject permission prompts. Runtimes that
318 /// don't want to make use of this ability can simply call the native
319 /// `listen` as part of either `start-listen` or `finish-listen`.
320 ///
321 /// # References
322 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html>
323 /// - <https://man7.org/linux/man-pages/man2/listen.2.html>
324 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen>
325 /// - <https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2>
326 start-listen: func() -> result<_, error-code>;
327 finish-listen: func() -> result<_, error-code>;
328 /// Accept a new client socket.
329 ///
330 /// The returned socket is bound and in the `connected` state. The following properties are inherited from the listener socket:
331 /// - `address-family`
332 /// - `keep-alive-enabled`
333 /// - `keep-alive-idle-time`
334 /// - `keep-alive-interval`
335 /// - `keep-alive-count`
336 /// - `hop-limit`
337 /// - `receive-buffer-size`
338 /// - `send-buffer-size`
339 ///
340 /// On success, this function returns the newly accepted client socket along with
341 /// a pair of streams that can be used to read & write to the connection.
342 ///
343 /// # Typical errors
344 /// - `invalid-state`: Socket is not in the `listening` state. (EINVAL)
345 /// - `would-block`: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
346 /// - `connection-aborted`: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
347 /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
348 ///
349 /// # References
350 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html>
351 /// - <https://man7.org/linux/man-pages/man2/accept.2.html>
352 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept>
353 /// - <https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2>
354 accept: func() -> result<tuple<tcp-socket, input-stream, output-stream>, error-code>;
355 /// Get the bound local address.
356 ///
357 /// POSIX mentions:
358 /// > If the socket has not been bound to a local name, the value
359 /// > stored in the object pointed to by `address` is unspecified.
360 ///
361 /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
362 ///
363 /// # Typical errors
364 /// - `invalid-state`: The socket is not bound to any local address.
365 ///
366 /// # References
367 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
368 /// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
369 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
370 /// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
371 local-address: func() -> result<ip-socket-address, error-code>;
372 /// Get the remote address.
373 ///
374 /// # Typical errors
375 /// - `invalid-state`: The socket is not connected to a remote address. (ENOTCONN)
376 ///
377 /// # References
378 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
379 /// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
380 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
381 /// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
382 remote-address: func() -> result<ip-socket-address, error-code>;
383 /// Whether the socket is in the `listening` state.
384 ///
385 /// Equivalent to the SO_ACCEPTCONN socket option.
386 is-listening: func() -> bool;
387 /// Whether this is a IPv4 or IPv6 socket.
388 ///
389 /// Equivalent to the SO_DOMAIN socket option.
390 address-family: func() -> ip-address-family;
391 /// Hints the desired listen queue size. Implementations are free to ignore this.
392 ///
393 /// If the provided value is 0, an `invalid-argument` error is returned.
394 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
395 ///
396 /// # Typical errors
397 /// - `not-supported`: (set) The platform does not support changing the backlog size after the initial listen.
398 /// - `invalid-argument`: (set) The provided value was 0.
399 /// - `invalid-state`: (set) The socket is in the `connect-in-progress` or `connected` state.
400 set-listen-backlog-size: func(value: u64) -> result<_, error-code>;
401 /// Enables or disables keepalive.
402 ///
403 /// The keepalive behavior can be adjusted using:
404 /// - `keep-alive-idle-time`
405 /// - `keep-alive-interval`
406 /// - `keep-alive-count`
407 /// These properties can be configured while `keep-alive-enabled` is false, but only come into effect when `keep-alive-enabled` is true.
408 ///
409 /// Equivalent to the SO_KEEPALIVE socket option.
410 keep-alive-enabled: func() -> result<bool, error-code>;
411 set-keep-alive-enabled: func(value: bool) -> result<_, error-code>;
412 /// Amount of time the connection has to be idle before TCP starts sending keepalive packets.
413 ///
414 /// If the provided value is 0, an `invalid-argument` error is returned.
415 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
416 /// I.e. after setting a value, reading the same setting back may return a different value.
417 ///
418 /// Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
419 ///
420 /// # Typical errors
421 /// - `invalid-argument`: (set) The provided value was 0.
422 keep-alive-idle-time: func() -> result<duration, error-code>;
423 set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>;
424 /// The time between keepalive packets.
425 ///
426 /// If the provided value is 0, an `invalid-argument` error is returned.
427 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
428 /// I.e. after setting a value, reading the same setting back may return a different value.
429 ///
430 /// Equivalent to the TCP_KEEPINTVL socket option.
431 ///
432 /// # Typical errors
433 /// - `invalid-argument`: (set) The provided value was 0.
434 keep-alive-interval: func() -> result<duration, error-code>;
435 set-keep-alive-interval: func(value: duration) -> result<_, error-code>;
436 /// The maximum amount of keepalive packets TCP should send before aborting the connection.
437 ///
438 /// If the provided value is 0, an `invalid-argument` error is returned.
439 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
440 /// I.e. after setting a value, reading the same setting back may return a different value.
441 ///
442 /// Equivalent to the TCP_KEEPCNT socket option.
443 ///
444 /// # Typical errors
445 /// - `invalid-argument`: (set) The provided value was 0.
446 keep-alive-count: func() -> result<u32, error-code>;
447 set-keep-alive-count: func(value: u32) -> result<_, error-code>;
448 /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
449 ///
450 /// If the provided value is 0, an `invalid-argument` error is returned.
451 ///
452 /// # Typical errors
453 /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
454 hop-limit: func() -> result<u8, error-code>;
455 set-hop-limit: func(value: u8) -> result<_, error-code>;
456 /// The kernel buffer space reserved for sends/receives on this socket.
457 ///
458 /// If the provided value is 0, an `invalid-argument` error is returned.
459 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
460 /// I.e. after setting a value, reading the same setting back may return a different value.
461 ///
462 /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
463 ///
464 /// # Typical errors
465 /// - `invalid-argument`: (set) The provided value was 0.
466 receive-buffer-size: func() -> result<u64, error-code>;
467 set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
468 send-buffer-size: func() -> result<u64, error-code>;
469 set-send-buffer-size: func(value: u64) -> result<_, error-code>;
470 /// Create a `pollable` which can be used to poll for, or block on,
471 /// completion of any of the asynchronous operations of this socket.
472 ///
473 /// When `finish-bind`, `finish-listen`, `finish-connect` or `accept`
474 /// return `error(would-block)`, this pollable can be used to wait for
475 /// their success or failure, after which the method can be retried.
476 ///
477 /// The pollable is not limited to the async operation that happens to be
478 /// in progress at the time of calling `subscribe` (if any). Theoretically,
479 /// `subscribe` only has to be called once per socket and can then be
480 /// (re)used for the remainder of the socket's lifetime.
481 ///
482 /// See <https://github.com/WebAssembly/wasi-sockets/TcpSocketOperationalSemantics.md#Pollable-readiness>
483 /// for a more information.
484 ///
485 /// Note: this function is here for WASI Preview2 only.
486 /// It's planned to be removed when `future` is natively supported in Preview3.
487 subscribe: func() -> pollable;
488 /// Initiate a graceful shutdown.
489 ///
490 /// - `receive`: The socket is not expecting to receive any data from
491 /// the peer. The `input-stream` associated with this socket will be
492 /// closed. Any data still in the receive queue at time of calling
493 /// this method will be discarded.
494 /// - `send`: The socket has no more data to send to the peer. The `output-stream`
495 /// associated with this socket will be closed and a FIN packet will be sent.
496 /// - `both`: Same effect as `receive` & `send` combined.
497 ///
498 /// This function is idempotent. Shutting a down a direction more than once
499 /// has no effect and returns `ok`.
500 ///
501 /// The shutdown function does not close (drop) the socket.
502 ///
503 /// # Typical errors
504 /// - `invalid-state`: The socket is not in the `connected` state. (ENOTCONN)
505 ///
506 /// # References
507 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html>
508 /// - <https://man7.org/linux/man-pages/man2/shutdown.2.html>
509 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown>
510 /// - <https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2>
511 shutdown: func(shutdown-type: shutdown-type) -> result<_, error-code>;
512 }
513 }
514
515 interface tcp-create-socket {
516 use network.{network, error-code, ip-address-family};
517 use tcp.{tcp-socket};
518
519 /// Create a new TCP socket.
520 ///
521 /// Similar to `socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)` in POSIX.
522 /// On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.
523 ///
524 /// This function does not require a network capability handle. This is considered to be safe because
525 /// at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind`/`connect`
526 /// is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
527 ///
528 /// All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
529 ///
530 /// # Typical errors
531 /// - `not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
532 /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
533 ///
534 /// # References
535 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html>
536 /// - <https://man7.org/linux/man-pages/man2/socket.2.html>
537 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
538 /// - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
539 create-tcp-socket: func(address-family: ip-address-family) -> result<tcp-socket, error-code>;
540 }
541
542 interface udp {
543 use wasi:io/[email protected].{pollable};
544 use network.{network, error-code, ip-socket-address, ip-address-family};
545
546 /// A received datagram.
547 record incoming-datagram {
548 /// The payload.
549 ///
550 /// Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
551 data: list<u8>,
552 /// The source address.
553 ///
554 /// This field is guaranteed to match the remote address the stream was initialized with, if any.
555 ///
556 /// Equivalent to the `src_addr` out parameter of `recvfrom`.
557 remote-address: ip-socket-address,
558 }
559
560 /// A datagram to be sent out.
561 record outgoing-datagram {
562 /// The payload.
563 data: list<u8>,
564 /// The destination address.
565 ///
566 /// The requirements on this field depend on how the stream was initialized:
567 /// - with a remote address: this field must be None or match the stream's remote address exactly.
568 /// - without a remote address: this field is required.
569 ///
570 /// If this value is None, the send operation is equivalent to `send` in POSIX. Otherwise it is equivalent to `sendto`.
571 remote-address: option<ip-socket-address>,
572 }
573
574 /// A UDP socket handle.
575 resource udp-socket {
576 /// Bind the socket to a specific network on the provided IP address and port.
577 ///
578 /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
579 /// network interface(s) to bind to.
580 /// If the port is zero, the socket will be bound to a random free port.
581 ///
582 /// # Typical errors
583 /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
584 /// - `invalid-state`: The socket is already bound. (EINVAL)
585 /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
586 /// - `address-in-use`: Address is already in use. (EADDRINUSE)
587 /// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
588 /// - `not-in-progress`: A `bind` operation is not in progress.
589 /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
590 ///
591 /// # Implementors note
592 /// Unlike in POSIX, in WASI the bind operation is async. This enables
593 /// interactive WASI hosts to inject permission prompts. Runtimes that
594 /// don't want to make use of this ability can simply call the native
595 /// `bind` as part of either `start-bind` or `finish-bind`.
596 ///
597 /// # References
598 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
599 /// - <https://man7.org/linux/man-pages/man2/bind.2.html>
600 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
601 /// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
602 start-bind: func(network: borrow<network>, local-address: ip-socket-address) -> result<_, error-code>;
603 finish-bind: func() -> result<_, error-code>;
604 /// Set up inbound & outbound communication channels, optionally to a specific peer.
605 ///
606 /// This function only changes the local socket configuration and does not generate any network traffic.
607 /// On success, the `remote-address` of the socket is updated. The `local-address` may be updated as well,
608 /// based on the best network path to `remote-address`.
609 ///
610 /// When a `remote-address` is provided, the returned streams are limited to communicating with that specific peer:
611 /// - `send` can only be used to send to this destination.
612 /// - `receive` will only return datagrams sent from the provided `remote-address`.
613 ///
614 /// This method may be called multiple times on the same socket to change its association, but
615 /// only the most recently returned pair of streams will be operational. Implementations may trap if
616 /// the streams returned by a previous invocation haven't been dropped yet before calling `stream` again.
617 ///
618 /// The POSIX equivalent in pseudo-code is:
619 /// ```text
620 /// if (was previously connected) {
621 /// connect(s, AF_UNSPEC)
622 /// }
623 /// if (remote_address is Some) {
624 /// connect(s, remote_address)
625 /// }
626 /// ```
627 ///
628 /// Unlike in POSIX, the socket must already be explicitly bound.
629 ///
630 /// # Typical errors
631 /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
632 /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
633 /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
634 /// - `invalid-state`: The socket is not bound.
635 /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
636 /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
637 /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
638 ///
639 /// # References
640 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
641 /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
642 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
643 /// - <https://man.freebsd.org/cgi/man.cgi?connect>
644 %stream: func(remote-address: option<ip-socket-address>) -> result<tuple<incoming-datagram-stream, outgoing-datagram-stream>, error-code>;
645 /// Get the current bound address.
646 ///
647 /// POSIX mentions:
648 /// > If the socket has not been bound to a local name, the value
649 /// > stored in the object pointed to by `address` is unspecified.
650 ///
651 /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
652 ///
653 /// # Typical errors
654 /// - `invalid-state`: The socket is not bound to any local address.
655 ///
656 /// # References
657 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
658 /// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
659 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
660 /// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
661 local-address: func() -> result<ip-socket-address, error-code>;
662 /// Get the address the socket is currently streaming to.
663 ///
664 /// # Typical errors
665 /// - `invalid-state`: The socket is not streaming to a specific remote address. (ENOTCONN)
666 ///
667 /// # References
668 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
669 /// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
670 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
671 /// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
672 remote-address: func() -> result<ip-socket-address, error-code>;
673 /// Whether this is a IPv4 or IPv6 socket.
674 ///
675 /// Equivalent to the SO_DOMAIN socket option.
676 address-family: func() -> ip-address-family;
677 /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
678 ///
679 /// If the provided value is 0, an `invalid-argument` error is returned.
680 ///
681 /// # Typical errors
682 /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
683 unicast-hop-limit: func() -> result<u8, error-code>;
684 set-unicast-hop-limit: func(value: u8) -> result<_, error-code>;
685 /// The kernel buffer space reserved for sends/receives on this socket.
686 ///
687 /// If the provided value is 0, an `invalid-argument` error is returned.
688 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
689 /// I.e. after setting a value, reading the same setting back may return a different value.
690 ///
691 /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
692 ///
693 /// # Typical errors
694 /// - `invalid-argument`: (set) The provided value was 0.
695 receive-buffer-size: func() -> result<u64, error-code>;
696 set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
697 send-buffer-size: func() -> result<u64, error-code>;
698 set-send-buffer-size: func(value: u64) -> result<_, error-code>;
699 /// Create a `pollable` which will resolve once the socket is ready for I/O.
700 ///
701 /// Note: this function is here for WASI Preview2 only.
702 /// It's planned to be removed when `future` is natively supported in Preview3.
703 subscribe: func() -> pollable;
704 }
705
706 resource incoming-datagram-stream {
707 /// Receive messages on the socket.
708 ///
709 /// This function attempts to receive up to `max-results` datagrams on the socket without blocking.
710 /// The returned list may contain fewer elements than requested, but never more.
711 ///
712 /// This function returns successfully with an empty list when either:
713 /// - `max-results` is 0, or:
714 /// - `max-results` is greater than 0, but no results are immediately available.
715 /// This function never returns `error(would-block)`.
716 ///
717 /// # Typical errors
718 /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
719 /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
720 ///
721 /// # References
722 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html>
723 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvmsg.html>
724 /// - <https://man7.org/linux/man-pages/man2/recv.2.html>
725 /// - <https://man7.org/linux/man-pages/man2/recvmmsg.2.html>
726 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recv>
727 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom>
728 /// - <https://learn.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms741687(v=vs.85)>
729 /// - <https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2>
730 receive: func(max-results: u64) -> result<list<incoming-datagram>, error-code>;
731 /// Create a `pollable` which will resolve once the stream is ready to receive again.
732 ///
733 /// Note: this function is here for WASI Preview2 only.
734 /// It's planned to be removed when `future` is natively supported in Preview3.
735 subscribe: func() -> pollable;
736 }
737
738 resource outgoing-datagram-stream {
739 /// Check readiness for sending. This function never blocks.
740 ///
741 /// Returns the number of datagrams permitted for the next call to `send`,
742 /// or an error. Calling `send` with more datagrams than this function has
743 /// permitted will trap.
744 ///
745 /// When this function returns ok(0), the `subscribe` pollable will
746 /// become ready when this function will report at least ok(1), or an
747 /// error.
748 ///
749 /// Never returns `would-block`.
750 check-send: func() -> result<u64, error-code>;
751 /// Send messages on the socket.
752 ///
753 /// This function attempts to send all provided `datagrams` on the socket without blocking and
754 /// returns how many messages were actually sent (or queued for sending). This function never
755 /// returns `error(would-block)`. If none of the datagrams were able to be sent, `ok(0)` is returned.
756 ///
757 /// This function semantically behaves the same as iterating the `datagrams` list and sequentially
758 /// sending each individual datagram until either the end of the list has been reached or the first error occurred.
759 /// If at least one datagram has been sent successfully, this function never returns an error.
760 ///
761 /// If the input list is empty, the function returns `ok(0)`.
762 ///
763 /// Each call to `send` must be permitted by a preceding `check-send`. Implementations must trap if
764 /// either `check-send` was not called or `datagrams` contains more items than `check-send` permitted.
765 ///
766 /// # Typical errors
767 /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
768 /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
769 /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
770 /// - `invalid-argument`: The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `stream`. (EISCONN)
771 /// - `invalid-argument`: The socket is not "connected" and no value for `remote-address` was provided. (EDESTADDRREQ)
772 /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
773 /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
774 /// - `datagram-too-large`: The datagram is too large. (EMSGSIZE)
775 ///
776 /// # References
777 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html>
778 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html>
779 /// - <https://man7.org/linux/man-pages/man2/send.2.html>
780 /// - <https://man7.org/linux/man-pages/man2/sendmmsg.2.html>
781 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send>
782 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-sendto>
783 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg>
784 /// - <https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2>
785 send: func(datagrams: list<outgoing-datagram>) -> result<u64, error-code>;
786 /// Create a `pollable` which will resolve once the stream is ready to send again.
787 ///
788 /// Note: this function is here for WASI Preview2 only.
789 /// It's planned to be removed when `future` is natively supported in Preview3.
790 subscribe: func() -> pollable;
791 }
792 }
793
794 interface udp-create-socket {
795 use network.{network, error-code, ip-address-family};
796 use udp.{udp-socket};
797
798 /// Create a new UDP socket.
799 ///
800 /// Similar to `socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)` in POSIX.
801 /// On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.
802 ///
803 /// This function does not require a network capability handle. This is considered to be safe because
804 /// at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind` is called,
805 /// the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
806 ///
807 /// All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.
808 ///
809 /// # Typical errors
810 /// - `not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
811 /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
812 ///
813 /// # References:
814 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html>
815 /// - <https://man7.org/linux/man-pages/man2/socket.2.html>
816 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
817 /// - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
818 create-udp-socket: func(address-family: ip-address-family) -> result<udp-socket, error-code>;
819 }
820
821 world imports {
822 import network;
823 import instance-network;
824 import wasi:io/[email protected];
825 import udp;
826 import udp-create-socket;
827 import wasi:io/[email protected];
828 import wasi:io/[email protected];
829 import wasi:clocks/[email protected];
830 import tcp;
831 import tcp-create-socket;
832 import ip-name-lookup;
833 }