| 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 |
} |