Debian Codegraph @

.cargo/vendor/wasip2/wit/deps/sockets/ip-name-lookup.wit

raw
1 @since(version = 0.2.0)
2 interface ip-name-lookup {
3 @since(version = 0.2.0)
4 use wasi:io/[email protected].{pollable};
5 @since(version = 0.2.0)
6 use network.{network, error-code, ip-address};
7
8 /// Resolve an internet host name to a list of IP addresses.
9 ///
10 /// Unicode domain names are automatically converted to ASCII using IDNA encoding.
11 /// If the input is an IP address string, the address is parsed and returned
12 /// as-is without making any external requests.
13 ///
14 /// See the wasi-socket proposal README.md for a comparison with getaddrinfo.
15 ///
16 /// This function never blocks. It either immediately fails or immediately
17 /// returns successfully with a `resolve-address-stream` that can be used
18 /// to (asynchronously) fetch the results.
19 ///
20 /// # Typical errors
21 /// - `invalid-argument`: `name` is a syntactically invalid domain name or IP address.
22 ///
23 /// # References:
24 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html>
25 /// - <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>
26 /// - <https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo>
27 /// - <https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3>
28 @since(version = 0.2.0)
29 resolve-addresses: func(network: borrow<network>, name: string) -> result<resolve-address-stream, error-code>;
30
31 @since(version = 0.2.0)
32 resource resolve-address-stream {
33 /// Returns the next address from the resolver.
34 ///
35 /// This function should be called multiple times. On each call, it will
36 /// return the next address in connection order preference. If all
37 /// addresses have been exhausted, this function returns `none`.
38 ///
39 /// This function never returns IPv4-mapped IPv6 addresses.
40 ///
41 /// # Typical errors
42 /// - `name-unresolvable`: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
43 /// - `temporary-resolver-failure`: A temporary failure in name resolution occurred. (EAI_AGAIN)
44 /// - `permanent-resolver-failure`: A permanent failure in name resolution occurred. (EAI_FAIL)
45 /// - `would-block`: A result is not available yet. (EWOULDBLOCK, EAGAIN)
46 @since(version = 0.2.0)
47 resolve-next-address: func() -> result<option<ip-address>, error-code>;
48
49 /// Create a `pollable` which will resolve once the stream is ready for I/O.
50 ///
51 /// Note: this function is here for WASI 0.2 only.
52 /// It's planned to be removed when `future` is natively supported in Preview3.
53 @since(version = 0.2.0)
54 subscribe: func() -> pollable;
55 }
56 }