Debian Codegraph @

vendor/wit-component/tests/interfaces/wasi-http/deps/sockets/ip-name-lookup.wit

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