componentized/directory

wasi:sockets

interface dependency

A WASI API for TCP & UDP sockets and domain name lookup.

interface ip-name-lookup wasi:sockets/ip-name-lookup@0.2.3 since 0.2.0

Types

use resource pollablesince 0.2.0

from wasi:io/poll@0.2.3

pollable represents a single I/O event which may be ready, or not.

  • ready: func() -> boolsince 0.2.0

    Return the readiness of a pollable. This function never blocks.

    Returns true when the pollable is ready, and false otherwise.

  • block: func()since 0.2.0

    block returns immediately if the pollable is ready, and otherwise blocks until ready.

    This function is equivalent to calling poll.poll on a list containing only this pollable.

use resource networksince 0.2.0

from wasi:sockets/network@0.2.3

An opaque resource that represents access to (a subset of) the network. This enables context-based security for networking. There is no need for this to map 1:1 to a physical network interface.

use enum error-codesince 0.2.0

from wasi:sockets/network@0.2.3

Error codes.

In theory, every API can return any error code. In practice, API's typically only return the errors documented per API combined with a couple of errors that are always possible:

  • unknown
  • access-denied
  • not-supported
  • out-of-memory
  • concurrency-conflict

See each individual API for what the POSIX equivalents are. They sometimes differ per API.

  • unknown

    Unknown error

  • access-denied

    Access denied.

    POSIX equivalent: EACCES, EPERM

  • not-supported

    The operation is not supported.

    POSIX equivalent: EOPNOTSUPP

  • invalid-argument

    One of the arguments is invalid.

    POSIX equivalent: EINVAL

  • out-of-memory

    Not enough memory to complete the operation.

    POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY

  • timeout

    The operation timed out before it could finish completely.

  • concurrency-conflict

    This operation is incompatible with another asynchronous operation that is already in progress.

    POSIX equivalent: EALREADY

  • not-in-progress

    Trying to finish an asynchronous operation that:

    • has not been started yet, or:
    • was already finished by a previous finish-* call.

    Note: this is scheduled to be removed when futures are natively supported.

  • would-block

    The operation has been aborted because it could not be completed immediately.

    Note: this is scheduled to be removed when futures are natively supported.

  • invalid-state

    The operation is not valid in the socket's current state.

  • new-socket-limit

    A new socket resource could not be created because of a system limit.

  • address-not-bindable

    A bind operation failed because the provided address is not an address that the network can bind to.

  • address-in-use

    A bind operation failed because the provided address is already in use or because there are no ephemeral ports available.

  • remote-unreachable

    The remote address is not reachable

  • connection-refused

    The TCP connection was forcefully rejected

  • connection-reset

    The TCP connection was reset.

  • connection-aborted

    A TCP connection was aborted.

  • datagram-too-large

    The size of a datagram sent to a UDP socket exceeded the maximum supported size.

  • name-unresolvable

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

  • temporary-resolver-failure

    A temporary failure in name resolution occurred.

  • permanent-resolver-failure

    A permanent failure in name resolution occurred.

use variant ip-addresssince 0.2.0

from wasi:sockets/network@0.2.3

resource resolve-address-streamsince 0.2.0

  • resolve-next-address: func() -> result<option<ip-address>, error-code>since 0.2.0

    Returns the next address from the resolver.

    This function should be called multiple times. On each call, it will return the next address in connection order preference. If all addresses have been exhausted, this function returns none.

    This function never returns IPv4-mapped IPv6 addresses.

    Typical errors

    • name-unresolvable: Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
    • temporary-resolver-failure: A temporary failure in name resolution occurred. (EAI_AGAIN)
    • permanent-resolver-failure: A permanent failure in name resolution occurred. (EAI_FAIL)
    • would-block: A result is not available yet. (EWOULDBLOCK, EAGAIN)
  • subscribe: func() -> pollablesince 0.2.0

    Create a pollable which will resolve once the stream is ready for I/O.

    Note: this function is here for WASI 0.2 only. It's planned to be removed when future is natively supported in Preview3.

Functions

resolve-addresses: func( network: borrow<network>, name: string, ) -> result<resolve-address-stream, error-code>since 0.2.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.

This function never blocks. It either immediately fails or immediately returns successfully with a resolve-address-stream that can be used to (asynchronously) fetch the results.

Typical errors

  • invalid-argument: name is a syntactically invalid domain name or IP address.

References:

WIT

@since(version = 0.2.0)
interface ip-name-lookup {
  @since(version = 0.2.0)
  use wasi:io/poll@0.2.3.{pollable};
  @since(version = 0.2.0)
  use network.{network, error-code, ip-address};

  @since(version = 0.2.0)
  resource resolve-address-stream {
    /// Returns the next address from the resolver.
    ///
    /// This function should be called multiple times. On each call, it will
    /// return the next address in connection order preference. If all
    /// addresses have been exhausted, this function returns `none`.
    ///
    /// This function never returns IPv4-mapped IPv6 addresses.
    ///
    /// # Typical errors
    /// - `name-unresolvable`:          Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
    /// - `temporary-resolver-failure`: A temporary failure in name resolution occurred. (EAI_AGAIN)
    /// - `permanent-resolver-failure`: A permanent failure in name resolution occurred. (EAI_FAIL)
    /// - `would-block`:                A result is not available yet. (EWOULDBLOCK, EAGAIN)
    @since(version = 0.2.0)
    resolve-next-address: func() -> result<option<ip-address>, error-code>;
    /// Create a `pollable` which will resolve once the stream is ready for I/O.
    ///
    /// Note: this function is here for WASI 0.2 only.
    /// It's planned to be removed when `future` is natively supported in Preview3.
    @since(version = 0.2.0)
    subscribe: func() -> pollable;
  }

  /// 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.
  ///
  /// This function never blocks. It either immediately fails or immediately
  /// returns successfully with a `resolve-address-stream` that can be used
  /// to (asynchronously) fetch the results.
  ///
  /// # Typical errors
  /// - `invalid-argument`: `name` is a syntactically invalid domain name or IP address.
  ///
  /// # 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.2.0)
  resolve-addresses: func(network: borrow<network>, name: string) -> result<resolve-address-stream, error-code>;
}