Debian Codegraph @

wasi/p3/wit/deps/wasi-sockets-0.3.0-rc-2026-01-06/package.wit

raw
1 package wasi:[email protected];
2
3 @since(version = 0.3.0-rc-2026-01-06)
4 interface types {
5 @since(version = 0.3.0-rc-2026-01-06)
6 use wasi:clocks/[email protected].{duration};
7
8 /// Error codes.
9 ///
10 /// In theory, every API can return any error code.
11 /// In practice, API's typically only return the errors documented per API
12 /// combined with a couple of errors that are always possible:
13 /// - `unknown`
14 /// - `access-denied`
15 /// - `not-supported`
16 /// - `out-of-memory`
17 ///
18 /// See each individual API for what the POSIX equivalents are. They sometimes differ per API.
19 @since(version = 0.3.0-rc-2026-01-06)
20 enum error-code {
21 /// Unknown error
22 unknown,
23 /// Access denied.
24 ///
25 /// POSIX equivalent: EACCES, EPERM
26 access-denied,
27 /// The operation is not supported.
28 ///
29 /// POSIX equivalent: EOPNOTSUPP
30 not-supported,
31 /// One of the arguments is invalid.
32 ///
33 /// POSIX equivalent: EINVAL
34 invalid-argument,
35 /// Not enough memory to complete the operation.
36 ///
37 /// POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY
38 out-of-memory,
39 /// The operation timed out before it could finish completely.
40 timeout,
41 /// The operation is not valid in the socket's current state.
42 invalid-state,
43 /// A bind operation failed because the provided address is not an address that the `network` can bind to.
44 address-not-bindable,
45 /// A bind operation failed because the provided address is already in use or because there are no ephemeral ports available.
46 address-in-use,
47 /// The remote address is not reachable
48 remote-unreachable,
49 /// The TCP connection was forcefully rejected
50 connection-refused,
51 /// The TCP connection was reset.
52 connection-reset,
53 /// A TCP connection was aborted.
54 connection-aborted,
55 /// The size of a datagram sent to a UDP socket exceeded the maximum
56 /// supported size.
57 datagram-too-large,
58 }
59
60 @since(version = 0.3.0-rc-2026-01-06)
61 enum ip-address-family {
62 /// Similar to `AF_INET` in POSIX.
63 ipv4,
64 /// Similar to `AF_INET6` in POSIX.
65 ipv6,
66 }
67
68 @since(version = 0.3.0-rc-2026-01-06)
69 type ipv4-address = tuple<u8, u8, u8, u8>;
70
71 @since(version = 0.3.0-rc-2026-01-06)
72 type ipv6-address = tuple<u16, u16, u16, u16, u16, u16, u16, u16>;
73
74 @since(version = 0.3.0-rc-2026-01-06)
75 variant ip-address {
76 ipv4(ipv4-address),
77 ipv6(ipv6-address),
78 }
79
80 @since(version = 0.3.0-rc-2026-01-06)
81 record ipv4-socket-address {
82 /// sin_port
83 port: u16,
84 /// sin_addr
85 address: ipv4-address,
86 }
87
88 @since(version = 0.3.0-rc-2026-01-06)
89 record ipv6-socket-address {
90 /// sin6_port
91 port: u16,
92 /// sin6_flowinfo
93 flow-info: u32,
94 /// sin6_addr
95 address: ipv6-address,
96 /// sin6_scope_id
97 scope-id: u32,
98 }
99
100 @since(version = 0.3.0-rc-2026-01-06)
101 variant ip-socket-address {
102 ipv4(ipv4-socket-address),
103 ipv6(ipv6-socket-address),
104 }
105
106 /// A TCP socket resource.
107 ///
108 /// The socket can be in one of the following states:
109 /// - `unbound`
110 /// - `bound` (See note below)
111 /// - `listening`
112 /// - `connecting`
113 /// - `connected`
114 /// - `closed`
115 /// See <https://github.com/WebAssembly/wasi-sockets/blob/main/TcpSocketOperationalSemantics-0.3.0-draft.md>
116 /// for more information.
117 ///
118 /// Note: Except where explicitly mentioned, whenever this documentation uses
119 /// the term "bound" without backticks it actually means: in the `bound` state *or higher*.
120 /// (i.e. `bound`, `listening`, `connecting` or `connected`)
121 ///
122 /// In addition to the general error codes documented on the
123 /// `types::error-code` type, TCP socket methods may always return
124 /// `error(invalid-state)` when in the `closed` state.
125 @since(version = 0.3.0-rc-2026-01-06)
126 resource tcp-socket {
127 /// Create a new TCP socket.
128 ///
129 /// Similar to `socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)` in POSIX.
130 /// On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.
131 ///
132 /// Unlike POSIX, WASI sockets have no notion of a socket-level
133 /// `O_NONBLOCK` flag. Instead they fully rely on the Component Model's
134 /// async support.
135 ///
136 /// # References
137 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html>
138 /// - <https://man7.org/linux/man-pages/man2/socket.2.html>
139 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
140 /// - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
141 @since(version = 0.3.0-rc-2026-01-06)
142 create: static func(address-family: ip-address-family) -> result<tcp-socket, error-code>;
143 /// Bind the socket to the provided IP address and port.
144 ///
145 /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
146 /// network interface(s) to bind to.
147 /// If the TCP/UDP port is zero, the socket will be bound to a random free port.
148 ///
149 /// Bind can be attempted multiple times on the same socket, even with
150 /// different arguments on each iteration. But never concurrently and
151 /// only as long as the previous bind failed. Once a bind succeeds, the
152 /// binding can't be changed anymore.
153 ///
154 /// # Typical errors
155 /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
156 /// - `invalid-argument`: `local-address` is not a unicast address. (EINVAL)
157 /// - `invalid-argument`: `local-address` is an IPv4-mapped IPv6 address. (EINVAL)
158 /// - `invalid-state`: The socket is already bound. (EINVAL)
159 /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
160 /// - `address-in-use`: Address is already in use. (EADDRINUSE)
161 /// - `address-not-bindable`: `local-address` is not an address that can be bound to. (EADDRNOTAVAIL)
162 ///
163 /// # Implementors note
164 /// When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
165 /// state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
166 /// socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
167 /// and SO_REUSEADDR performs something different entirely.
168 ///
169 /// # References
170 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
171 /// - <https://man7.org/linux/man-pages/man2/bind.2.html>
172 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
173 /// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
174 @since(version = 0.3.0-rc-2026-01-06)
175 bind: func(local-address: ip-socket-address) -> result<_, error-code>;
176 /// Connect to a remote endpoint.
177 ///
178 /// On success, the socket is transitioned into the `connected` state and this function returns a connection resource.
179 ///
180 /// After a failed connection attempt, the socket will be in the `closed`
181 /// state and the only valid action left is to `drop` the socket. A single
182 /// socket can not be used to connect more than once.
183 ///
184 /// # Typical errors
185 /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
186 /// - `invalid-argument`: `remote-address` is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
187 /// - `invalid-argument`: `remote-address` is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)
188 /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows)
189 /// - `invalid-argument`: The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows)
190 /// - `invalid-state`: The socket is already in the `connecting` state. (EALREADY)
191 /// - `invalid-state`: The socket is already in the `connected` state. (EISCONN)
192 /// - `invalid-state`: The socket is already in the `listening` state. (EOPNOTSUPP, EINVAL on Windows)
193 /// - `timeout`: Connection timed out. (ETIMEDOUT)
194 /// - `connection-refused`: The connection was forcefully rejected. (ECONNREFUSED)
195 /// - `connection-reset`: The connection was reset. (ECONNRESET)
196 /// - `connection-aborted`: The connection was aborted. (ECONNABORTED)
197 /// - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
198 /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
199 ///
200 /// # References
201 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
202 /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
203 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
204 /// - <https://man.freebsd.org/cgi/man.cgi?connect>
205 @since(version = 0.3.0-rc-2026-01-06)
206 connect: async func(remote-address: ip-socket-address) -> result<_, error-code>;
207 /// Start listening and return a stream of new inbound connections.
208 ///
209 /// Transitions the socket into the `listening` state. This can be called
210 /// at most once per socket.
211 ///
212 /// If the socket is not already explicitly bound, this function will
213 /// implicitly bind the socket to a random free port.
214 ///
215 /// Normally, the returned sockets are bound, in the `connected` state
216 /// and immediately ready for I/O. Though, depending on exact timing and
217 /// circumstances, a newly accepted connection may already be `closed`
218 /// by the time the server attempts to perform its first I/O on it. This
219 /// is true regardless of whether the WASI implementation uses
220 /// "synthesized" sockets or not (see Implementors Notes below).
221 ///
222 /// The following properties are inherited from the listener socket:
223 /// - `address-family`
224 /// - `keep-alive-enabled`
225 /// - `keep-alive-idle-time`
226 /// - `keep-alive-interval`
227 /// - `keep-alive-count`
228 /// - `hop-limit`
229 /// - `receive-buffer-size`
230 /// - `send-buffer-size`
231 ///
232 /// # Typical errors
233 /// - `invalid-state`: The socket is already in the `connected` state. (EISCONN, EINVAL on BSD)
234 /// - `invalid-state`: The socket is already in the `listening` state.
235 /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
236 ///
237 /// # Implementors note
238 /// This method returns a single perpetual stream that should only close
239 /// on fatal errors (if any). Yet, the POSIX' `accept` function may also
240 /// return transient errors (e.g. ECONNABORTED). The exact details differ
241 /// per operation system. For example, the Linux manual mentions:
242 ///
243 /// > Linux accept() passes already-pending network errors on the new
244 /// > socket as an error code from accept(). This behavior differs from
245 /// > other BSD socket implementations. For reliable operation the
246 /// > application should detect the network errors defined for the
247 /// > protocol after accept() and treat them like EAGAIN by retrying.
248 /// > In the case of TCP/IP, these are ENETDOWN, EPROTO, ENOPROTOOPT,
249 /// > EHOSTDOWN, ENONET, EHOSTUNREACH, EOPNOTSUPP, and ENETUNREACH.
250 /// Source: https://man7.org/linux/man-pages/man2/accept.2.html
251 ///
252 /// WASI implementations have two options to handle this:
253 /// - Optionally log it and then skip over non-fatal errors returned by
254 /// `accept`. Guest code never gets to see these failures. Or:
255 /// - Synthesize a `tcp-socket` resource that exposes the error when
256 /// attempting to send or receive on it. Guest code then sees these
257 /// failures as regular I/O errors.
258 ///
259 /// In either case, the stream returned by this `listen` method remains
260 /// operational.
261 ///
262 /// # References
263 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html>
264 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html>
265 /// - <https://man7.org/linux/man-pages/man2/listen.2.html>
266 /// - <https://man7.org/linux/man-pages/man2/accept.2.html>
267 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen>
268 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept>
269 /// - <https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2>
270 /// - <https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2>
271 @since(version = 0.3.0-rc-2026-01-06)
272 listen: func() -> result<stream<tcp-socket>, error-code>;
273 /// Transmit data to peer.
274 ///
275 /// The caller should close the stream when it has no more data to send
276 /// to the peer. Under normal circumstances this will cause a FIN packet
277 /// to be sent out. Closing the stream is equivalent to calling
278 /// `shutdown(SHUT_WR)` in POSIX.
279 ///
280 /// This function may be called at most once and returns once the full
281 /// contents of the stream are transmitted or an error is encountered.
282 ///
283 /// # Typical errors
284 /// - `invalid-state`: The socket is not in the `connected` state. (ENOTCONN)
285 /// - `connection-reset`: The connection was reset. (ECONNRESET)
286 /// - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
287 ///
288 /// # References
289 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/send.html>
290 /// - <https://man7.org/linux/man-pages/man2/send.2.html>
291 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send>
292 /// - <https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2>
293 @since(version = 0.3.0-rc-2026-01-06)
294 send: async func(data: stream<u8>) -> result<_, error-code>;
295 /// Read data from peer.
296 ///
297 /// This function returns a `stream` which provides the data received from the
298 /// socket, and a `future` providing additional error information in case the
299 /// socket is closed abnormally.
300 ///
301 /// If the socket is closed normally, `stream.read` on the `stream` will return
302 /// `read-status::closed` with no `error-context` and the future resolves to
303 /// the value `ok`. If the socket is closed abnormally, `stream.read` on the
304 /// `stream` returns `read-status::closed` with an `error-context` and the future
305 /// resolves to `err` with an `error-code`.
306 ///
307 /// `receive` is meant to be called only once per socket. If it is called more
308 /// than once, the subsequent calls return a new `stream` that fails as if it
309 /// were closed abnormally.
310 ///
311 /// If the caller is not expecting to receive any data from the peer,
312 /// they may drop the stream. Any data still in the receive queue
313 /// will be discarded. This is equivalent to calling `shutdown(SHUT_RD)`
314 /// in POSIX.
315 ///
316 /// # Typical errors
317 /// - `invalid-state`: The socket is not in the `connected` state. (ENOTCONN)
318 /// - `connection-reset`: The connection was reset. (ECONNRESET)
319 /// - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
320 ///
321 /// # References
322 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recv.html>
323 /// - <https://man7.org/linux/man-pages/man2/recv.2.html>
324 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recv>
325 /// - <https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2>
326 @since(version = 0.3.0-rc-2026-01-06)
327 receive: func() -> tuple<stream<u8>, future<result<_, error-code>>>;
328 /// Get the bound local address.
329 ///
330 /// POSIX mentions:
331 /// > If the socket has not been bound to a local name, the value
332 /// > stored in the object pointed to by `address` is unspecified.
333 ///
334 /// WASI is stricter and requires `get-local-address` to return `invalid-state` when the socket hasn't been bound yet.
335 ///
336 /// # Typical errors
337 /// - `invalid-state`: The socket is not bound to any local address.
338 ///
339 /// # References
340 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
341 /// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
342 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
343 /// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
344 @since(version = 0.3.0-rc-2026-01-06)
345 get-local-address: func() -> result<ip-socket-address, error-code>;
346 /// Get the remote address.
347 ///
348 /// # Typical errors
349 /// - `invalid-state`: The socket is not connected to a remote address. (ENOTCONN)
350 ///
351 /// # References
352 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
353 /// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
354 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
355 /// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
356 @since(version = 0.3.0-rc-2026-01-06)
357 get-remote-address: func() -> result<ip-socket-address, error-code>;
358 /// Whether the socket is in the `listening` state.
359 ///
360 /// Equivalent to the SO_ACCEPTCONN socket option.
361 @since(version = 0.3.0-rc-2026-01-06)
362 get-is-listening: func() -> bool;
363 /// Whether this is a IPv4 or IPv6 socket.
364 ///
365 /// This is the value passed to the constructor.
366 ///
367 /// Equivalent to the SO_DOMAIN socket option.
368 @since(version = 0.3.0-rc-2026-01-06)
369 get-address-family: func() -> ip-address-family;
370 /// Hints the desired listen queue size. Implementations are free to ignore this.
371 ///
372 /// If the provided value is 0, an `invalid-argument` error is returned.
373 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
374 ///
375 /// # Typical errors
376 /// - `not-supported`: (set) The platform does not support changing the backlog size after the initial listen.
377 /// - `invalid-argument`: (set) The provided value was 0.
378 /// - `invalid-state`: (set) The socket is in the `connecting` or `connected` state.
379 @since(version = 0.3.0-rc-2026-01-06)
380 set-listen-backlog-size: func(value: u64) -> result<_, error-code>;
381 /// Enables or disables keepalive.
382 ///
383 /// The keepalive behavior can be adjusted using:
384 /// - `keep-alive-idle-time`
385 /// - `keep-alive-interval`
386 /// - `keep-alive-count`
387 /// These properties can be configured while `keep-alive-enabled` is false, but only come into effect when `keep-alive-enabled` is true.
388 ///
389 /// Equivalent to the SO_KEEPALIVE socket option.
390 @since(version = 0.3.0-rc-2026-01-06)
391 get-keep-alive-enabled: func() -> result<bool, error-code>;
392 @since(version = 0.3.0-rc-2026-01-06)
393 set-keep-alive-enabled: func(value: bool) -> result<_, error-code>;
394 /// Amount of time the connection has to be idle before TCP starts sending keepalive packets.
395 ///
396 /// If the provided value is 0, an `invalid-argument` error is returned.
397 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
398 /// I.e. after setting a value, reading the same setting back may return a different value.
399 ///
400 /// Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
401 ///
402 /// # Typical errors
403 /// - `invalid-argument`: (set) The provided value was 0.
404 @since(version = 0.3.0-rc-2026-01-06)
405 get-keep-alive-idle-time: func() -> result<duration, error-code>;
406 @since(version = 0.3.0-rc-2026-01-06)
407 set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>;
408 /// The time between keepalive packets.
409 ///
410 /// If the provided value is 0, an `invalid-argument` error is returned.
411 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
412 /// I.e. after setting a value, reading the same setting back may return a different value.
413 ///
414 /// Equivalent to the TCP_KEEPINTVL socket option.
415 ///
416 /// # Typical errors
417 /// - `invalid-argument`: (set) The provided value was 0.
418 @since(version = 0.3.0-rc-2026-01-06)
419 get-keep-alive-interval: func() -> result<duration, error-code>;
420 @since(version = 0.3.0-rc-2026-01-06)
421 set-keep-alive-interval: func(value: duration) -> result<_, error-code>;
422 /// The maximum amount of keepalive packets TCP should send before aborting the connection.
423 ///
424 /// If the provided value is 0, an `invalid-argument` error is returned.
425 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
426 /// I.e. after setting a value, reading the same setting back may return a different value.
427 ///
428 /// Equivalent to the TCP_KEEPCNT socket option.
429 ///
430 /// # Typical errors
431 /// - `invalid-argument`: (set) The provided value was 0.
432 @since(version = 0.3.0-rc-2026-01-06)
433 get-keep-alive-count: func() -> result<u32, error-code>;
434 @since(version = 0.3.0-rc-2026-01-06)
435 set-keep-alive-count: func(value: u32) -> result<_, error-code>;
436 /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
437 ///
438 /// If the provided value is 0, an `invalid-argument` error is returned.
439 ///
440 /// # Typical errors
441 /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
442 @since(version = 0.3.0-rc-2026-01-06)
443 get-hop-limit: func() -> result<u8, error-code>;
444 @since(version = 0.3.0-rc-2026-01-06)
445 set-hop-limit: func(value: u8) -> result<_, error-code>;
446 /// The kernel buffer space reserved for sends/receives on this socket.
447 ///
448 /// If the provided value is 0, an `invalid-argument` error is returned.
449 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
450 /// I.e. after setting a value, reading the same setting back may return a different value.
451 ///
452 /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
453 ///
454 /// # Typical errors
455 /// - `invalid-argument`: (set) The provided value was 0.
456 @since(version = 0.3.0-rc-2026-01-06)
457 get-receive-buffer-size: func() -> result<u64, error-code>;
458 @since(version = 0.3.0-rc-2026-01-06)
459 set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
460 @since(version = 0.3.0-rc-2026-01-06)
461 get-send-buffer-size: func() -> result<u64, error-code>;
462 @since(version = 0.3.0-rc-2026-01-06)
463 set-send-buffer-size: func(value: u64) -> result<_, error-code>;
464 }
465
466 /// A UDP socket handle.
467 @since(version = 0.3.0-rc-2026-01-06)
468 resource udp-socket {
469 /// Create a new UDP socket.
470 ///
471 /// Similar to `socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)` in POSIX.
472 /// On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.
473 ///
474 /// Unlike POSIX, WASI sockets have no notion of a socket-level
475 /// `O_NONBLOCK` flag. Instead they fully rely on the Component Model's
476 /// async support.
477 ///
478 /// # References:
479 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html>
480 /// - <https://man7.org/linux/man-pages/man2/socket.2.html>
481 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
482 /// - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
483 @since(version = 0.3.0-rc-2026-01-06)
484 create: static func(address-family: ip-address-family) -> result<udp-socket, error-code>;
485 /// Bind the socket to the provided IP address and port.
486 ///
487 /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
488 /// network interface(s) to bind to.
489 /// If the port is zero, the socket will be bound to a random free port.
490 ///
491 /// # Typical errors
492 /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
493 /// - `invalid-state`: The socket is already bound. (EINVAL)
494 /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
495 /// - `address-in-use`: Address is already in use. (EADDRINUSE)
496 /// - `address-not-bindable`: `local-address` is not an address that can be bound to. (EADDRNOTAVAIL)
497 ///
498 /// # References
499 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
500 /// - <https://man7.org/linux/man-pages/man2/bind.2.html>
501 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
502 /// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
503 @since(version = 0.3.0-rc-2026-01-06)
504 bind: func(local-address: ip-socket-address) -> result<_, error-code>;
505 /// Associate this socket with a specific peer address.
506 ///
507 /// On success, the `remote-address` of the socket is updated.
508 /// The `local-address` may be updated as well, based on the best network
509 /// path to `remote-address`. If the socket was not already explicitly
510 /// bound, this function will implicitly bind the socket to a random
511 /// free port.
512 ///
513 /// When a UDP socket is "connected", the `send` and `receive` methods
514 /// are limited to communicating with that peer only:
515 /// - `send` can only be used to send to this destination.
516 /// - `receive` will only return datagrams sent from the provided `remote-address`.
517 ///
518 /// The name "connect" was kept to align with the existing POSIX
519 /// terminology. Other than that, this function only changes the local
520 /// socket configuration and does not generate any network traffic.
521 /// The peer is not aware of this "connection".
522 ///
523 /// This method may be called multiple times on the same socket to change
524 /// its association, but only the most recent one will be effective.
525 ///
526 /// # Typical errors
527 /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
528 /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
529 /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
530 /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
531 ///
532 /// # Implementors note
533 /// If the socket is already connected, some platforms (e.g. Linux)
534 /// require a disconnect before connecting to a different peer address.
535 ///
536 /// # References
537 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
538 /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
539 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
540 /// - <https://man.freebsd.org/cgi/man.cgi?connect>
541 @since(version = 0.3.0-rc-2026-01-06)
542 connect: func(remote-address: ip-socket-address) -> result<_, error-code>;
543 /// Dissociate this socket from its peer address.
544 ///
545 /// After calling this method, `send` & `receive` are free to communicate
546 /// with any address again.
547 ///
548 /// The POSIX equivalent of this is calling `connect` with an `AF_UNSPEC` address.
549 ///
550 /// # Typical errors
551 /// - `invalid-state`: The socket is not connected.
552 ///
553 /// # References
554 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
555 /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
556 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
557 /// - <https://man.freebsd.org/cgi/man.cgi?connect>
558 @since(version = 0.3.0-rc-2026-01-06)
559 disconnect: func() -> result<_, error-code>;
560 /// Send a message on the socket to a particular peer.
561 ///
562 /// If the socket is connected, the peer address may be left empty. In
563 /// that case this is equivalent to `send` in POSIX. Otherwise it is
564 /// equivalent to `sendto`.
565 ///
566 /// Additionally, if the socket is connected, a `remote-address` argument
567 /// _may_ be provided but then it must be identical to the address
568 /// passed to `connect`.
569 ///
570 /// Implementations may trap if the `data` length exceeds 64 KiB.
571 ///
572 /// # Typical errors
573 /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
574 /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
575 /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
576 /// - `invalid-argument`: The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `connect`. (EISCONN)
577 /// - `invalid-argument`: The socket is not "connected" and no value for `remote-address` was provided. (EDESTADDRREQ)
578 /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
579 /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
580 /// - `datagram-too-large`: The datagram is too large. (EMSGSIZE)
581 ///
582 /// # References
583 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html>
584 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html>
585 /// - <https://man7.org/linux/man-pages/man2/send.2.html>
586 /// - <https://man7.org/linux/man-pages/man2/sendmmsg.2.html>
587 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send>
588 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-sendto>
589 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg>
590 /// - <https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2>
591 @since(version = 0.3.0-rc-2026-01-06)
592 send: async func(data: list<u8>, remote-address: option<ip-socket-address>) -> result<_, error-code>;
593 /// Receive a message on the socket.
594 ///
595 /// On success, the return value contains a tuple of the received data
596 /// and the address of the sender. Theoretical maximum length of the
597 /// data is 64 KiB. Though in practice, it will typically be less than
598 /// 1500 bytes.
599 ///
600 /// If the socket is connected, the sender address is guaranteed to
601 /// match the remote address passed to `connect`.
602 ///
603 /// # Typical errors
604 /// - `invalid-state`: The socket has not been bound yet.
605 /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
606 /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
607 ///
608 /// # References
609 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html>
610 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvmsg.html>
611 /// - <https://man7.org/linux/man-pages/man2/recv.2.html>
612 /// - <https://man7.org/linux/man-pages/man2/recvmmsg.2.html>
613 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom>
614 /// - <https://learn.microsoft.com/en-us/windows/win32/api/mswsock/nc-mswsock-lpfn_wsarecvmsg>
615 /// - <https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2>
616 @since(version = 0.3.0-rc-2026-01-06)
617 receive: async func() -> result<tuple<list<u8>, ip-socket-address>, error-code>;
618 /// Get the current bound address.
619 ///
620 /// POSIX mentions:
621 /// > If the socket has not been bound to a local name, the value
622 /// > stored in the object pointed to by `address` is unspecified.
623 ///
624 /// WASI is stricter and requires `get-local-address` to return `invalid-state` when the socket hasn't been bound yet.
625 ///
626 /// # Typical errors
627 /// - `invalid-state`: The socket is not bound to any local address.
628 ///
629 /// # References
630 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
631 /// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
632 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
633 /// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
634 @since(version = 0.3.0-rc-2026-01-06)
635 get-local-address: func() -> result<ip-socket-address, error-code>;
636 /// Get the address the socket is currently "connected" to.
637 ///
638 /// # Typical errors
639 /// - `invalid-state`: The socket is not "connected" to a specific remote address. (ENOTCONN)
640 ///
641 /// # References
642 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
643 /// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
644 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
645 /// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
646 @since(version = 0.3.0-rc-2026-01-06)
647 get-remote-address: func() -> result<ip-socket-address, error-code>;
648 /// Whether this is a IPv4 or IPv6 socket.
649 ///
650 /// This is the value passed to the constructor.
651 ///
652 /// Equivalent to the SO_DOMAIN socket option.
653 @since(version = 0.3.0-rc-2026-01-06)
654 get-address-family: func() -> ip-address-family;
655 /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
656 ///
657 /// If the provided value is 0, an `invalid-argument` error is returned.
658 ///
659 /// # Typical errors
660 /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
661 @since(version = 0.3.0-rc-2026-01-06)
662 get-unicast-hop-limit: func() -> result<u8, error-code>;
663 @since(version = 0.3.0-rc-2026-01-06)
664 set-unicast-hop-limit: func(value: u8) -> result<_, error-code>;
665 /// The kernel buffer space reserved for sends/receives on this socket.
666 ///
667 /// If the provided value is 0, an `invalid-argument` error is returned.
668 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
669 /// I.e. after setting a value, reading the same setting back may return a different value.
670 ///
671 /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
672 ///
673 /// # Typical errors
674 /// - `invalid-argument`: (set) The provided value was 0.
675 @since(version = 0.3.0-rc-2026-01-06)
676 get-receive-buffer-size: func() -> result<u64, error-code>;
677 @since(version = 0.3.0-rc-2026-01-06)
678 set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
679 @since(version = 0.3.0-rc-2026-01-06)
680 get-send-buffer-size: func() -> result<u64, error-code>;
681 @since(version = 0.3.0-rc-2026-01-06)
682 set-send-buffer-size: func(value: u64) -> result<_, error-code>;
683 }
684 }
685
686 @since(version = 0.3.0-rc-2026-01-06)
687 interface ip-name-lookup {
688 @since(version = 0.3.0-rc-2026-01-06)
689 use types.{ip-address};
690
691 /// Lookup error codes.
692 @since(version = 0.3.0-rc-2026-01-06)
693 enum error-code {
694 /// Unknown error
695 unknown,
696 /// Access denied.
697 ///
698 /// POSIX equivalent: EACCES, EPERM
699 access-denied,
700 /// `name` is a syntactically invalid domain name or IP address.
701 ///
702 /// POSIX equivalent: EINVAL
703 invalid-argument,
704 /// Name does not exist or has no suitable associated IP addresses.
705 ///
706 /// POSIX equivalent: EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY
707 name-unresolvable,
708 /// A temporary failure in name resolution occurred.
709 ///
710 /// POSIX equivalent: EAI_AGAIN
711 temporary-resolver-failure,
712 /// A permanent failure in name resolution occurred.
713 ///
714 /// POSIX equivalent: EAI_FAIL
715 permanent-resolver-failure,
716 }
717
718 /// Resolve an internet host name to a list of IP addresses.
719 ///
720 /// Unicode domain names are automatically converted to ASCII using IDNA encoding.
721 /// If the input is an IP address string, the address is parsed and returned
722 /// as-is without making any external requests.
723 ///
724 /// See the wasi-socket proposal README.md for a comparison with getaddrinfo.
725 ///
726 /// The results are returned in connection order preference.
727 ///
728 /// This function never succeeds with 0 results. It either fails or succeeds
729 /// with at least one address. Additionally, this function never returns
730 /// IPv4-mapped IPv6 addresses.
731 ///
732 /// The returned future will resolve to an error code in case of failure.
733 /// It will resolve to success once the returned stream is exhausted.
734 ///
735 /// # References:
736 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html>
737 /// - <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>
738 /// - <https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo>
739 /// - <https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3>
740 @since(version = 0.3.0-rc-2026-01-06)
741 resolve-addresses: async func(name: string) -> result<list<ip-address>, error-code>;
742 }
743
744 @since(version = 0.3.0-rc-2026-01-06)
745 world imports {
746 @since(version = 0.3.0-rc-2026-01-06)
747 import wasi:clocks/[email protected];
748 @since(version = 0.3.0-rc-2026-01-06)
749 import types;
750 @since(version = 0.3.0-rc-2026-01-06)
751 import ip-name-lookup;
752 }