componentized/directory

wasi:sockets

interface dependency

WASI socket interfaces for TCP and UDP

interface ip-name-lookup wasi:sockets/ip-name-lookup@0.3.0 since 0.3.0

Types

use variant ip-addresssince 0.3.0

from wasi:sockets/types@0.3.0

variant error-codesince 0.3.0

Lookup error codes.

  • access-denied

    Access denied.

    POSIX equivalent: EACCES, EPERM

  • invalid-argument

    name is a syntactically invalid domain name or IP address.

    POSIX equivalent: EINVAL

  • name-unresolvable

    Name does not exist or has no suitable associated IP addresses.

    POSIX equivalent: EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY

  • temporary-resolver-failure

    A temporary failure in name resolution occurred.

    POSIX equivalent: EAI_AGAIN

  • permanent-resolver-failure

    A permanent failure in name resolution occurred.

    POSIX equivalent: EAI_FAIL

  • other: option<string>

    A catch-all for errors not captured by the existing variants. Implementations can use this to extend the error type without breaking existing code.

Functions

resolve-addresses: async func( name: string, ) -> result<list<ip-address>, error-code>since 0.3.0

Resolve an internet host name to a list of IP addresses.

Unicode domain names are automatically converted to ASCII using IDNA encoding. If the input is an IP address string, the address is parsed and returned as-is without making any external requests.

See the wasi-socket proposal README.md for a comparison with getaddrinfo.

The results are returned in connection order preference.

This function never succeeds with 0 results. It either fails or succeeds with at least one address. Additionally, this function never returns IPv4-mapped IPv6 addresses.

References:

WIT

@since(version = 0.3.0)
interface ip-name-lookup {
  @since(version = 0.3.0)
  use types.{ip-address};

  /// Lookup error codes.
  @since(version = 0.3.0)
  variant error-code {
    /// Access denied.
    ///
    /// POSIX equivalent: EACCES, EPERM
    access-denied,
    /// `name` is a syntactically invalid domain name or IP address.
    ///
    /// POSIX equivalent: EINVAL
    invalid-argument,
    /// Name does not exist or has no suitable associated IP addresses.
    ///
    /// POSIX equivalent: EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY
    name-unresolvable,
    /// A temporary failure in name resolution occurred.
    ///
    /// POSIX equivalent: EAI_AGAIN
    temporary-resolver-failure,
    /// A permanent failure in name resolution occurred.
    ///
    /// POSIX equivalent: EAI_FAIL
    permanent-resolver-failure,
    /// A catch-all for errors not captured by the existing variants.
    /// Implementations can use this to extend the error type without
    /// breaking existing code.
    other(option<string>),
  }

  /// Resolve an internet host name to a list of IP addresses.
  ///
  /// Unicode domain names are automatically converted to ASCII using IDNA
  /// encoding. If the input is an IP address string, the address is parsed
  /// and returned as-is without making any external requests.
  ///
  /// See the wasi-socket proposal README.md for a comparison with getaddrinfo.
  ///
  /// The results are returned in connection order preference.
  ///
  /// This function never succeeds with 0 results. It either fails or succeeds
  /// with at least one address. Additionally, this function never returns
  /// IPv4-mapped IPv6 addresses.
  ///
  /// # References:
  /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html>
  /// - <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>
  /// - <https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo>
  /// - <https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3>
  @since(version = 0.3.0)
  resolve-addresses: async func(name: string) -> result<list<ip-address>, error-code>;
}