componentized

Types

use resource errorunstable: network-error-code

from wasi:io/error@0.2.5

A resource which represents some error information.

The only method provided by this resource is to-debug-string, which provides some human-readable information about the error.

In the wasi:io package, this resource is returned through the wasi:io/streams/stream-error type.

To provide more specific error information, other interfaces may offer functions to "downcast" this error into more specific types. For example, errors returned from streams derived from filesystem types can be described using the filesystem's own error-code type. This is done using the function wasi:filesystem/types/filesystem-error-code, which takes a borrow<error> parameter and returns an option<wasi:filesystem/types/error-code>.

The set of functions which can "downcast" an error into a more concrete type is open.

  • functionto-debug-string: func() -> stringsince 0.2.0

    Returns a string that is suitable to assist humans in debugging this error.

    WARNING: The returned string should not be consumed mechanically! It may change across platforms, hosts, or other implementation details. Parsing this string is a major platform-compatibility hazard.

resource networksince 0.2.0

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.

enum error-codesince 0.2.0

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.

enum ip-address-familysince 0.2.0

  • ipv4

    Similar to AF_INET in POSIX.

  • ipv6

    Similar to AF_INET6 in POSIX.

type ipv4-addresssince 0.2.0

  • tuple<u8, u8, u8, u8>

type ipv6-addresssince 0.2.0

  • tuple<u16, u16, u16, u16, u16, u16, u16, u16>

variant ip-addresssince 0.2.0

record ipv4-socket-addresssince 0.2.0

record ipv6-socket-addresssince 0.2.0

  • port: u16

    sin6_port

  • flow-info: u32

    sin6_flowinfo

  • address: ipv6-address

    sin6_addr

  • scope-id: u32

    sin6_scope_id

variant ip-socket-addresssince 0.2.0

Functions

functionnetwork-error-code: func(err: borrow<error>) -> option<error-code>unstable: network-error-code

Attempts to extract a network-related error-code from the stream error provided.

Stream operations which return stream-error::last-operation-failed have a payload with more information about the operation that failed. This payload can be passed through to this function to see if there's network-related information about the error to return.

Note that this function is fallible because not all stream-related errors are network-related errors.

WIT

@since(version = 0.2.0)
interface network {
  @unstable(feature = network-error-code)
  use wasi:io/error@0.2.5.{error};

  /// 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.
  @since(version = 0.2.0)
  resource network;

  /// 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.
  @since(version = 0.2.0)
  enum error-code {
    /// Unknown error
    unknown,
    /// Access denied.
    ///
    /// POSIX equivalent: EACCES, EPERM
    access-denied,
    /// The operation is not supported.
    ///
    /// POSIX equivalent: EOPNOTSUPP
    not-supported,
    /// One of the arguments is invalid.
    ///
    /// POSIX equivalent: EINVAL
    invalid-argument,
    /// Not enough memory to complete the operation.
    ///
    /// POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY
    out-of-memory,
    /// The operation timed out before it could finish completely.
    timeout,
    /// This operation is incompatible with another asynchronous operation that is already in progress.
    ///
    /// POSIX equivalent: EALREADY
    concurrency-conflict,
    /// 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 `future`s are natively supported.
    not-in-progress,
    /// The operation has been aborted because it could not be completed immediately.
    ///
    /// Note: this is scheduled to be removed when `future`s are natively supported.
    would-block,
    /// The operation is not valid in the socket's current state.
    invalid-state,
    /// A new socket resource could not be created because of a system limit.
    new-socket-limit,
    /// A bind operation failed because the provided address is not an address that the `network` can bind to.
    address-not-bindable,
    /// A bind operation failed because the provided address is already in use or because there are no ephemeral ports available.
    address-in-use,
    /// The remote address is not reachable
    remote-unreachable,
    /// The TCP connection was forcefully rejected
    connection-refused,
    /// The TCP connection was reset.
    connection-reset,
    /// A TCP connection was aborted.
    connection-aborted,
    /// The size of a datagram sent to a UDP socket exceeded the maximum
    /// supported size.
    datagram-too-large,
    /// Name does not exist or has no suitable associated IP addresses.
    name-unresolvable,
    /// A temporary failure in name resolution occurred.
    temporary-resolver-failure,
    /// A permanent failure in name resolution occurred.
    permanent-resolver-failure,
  }

  @since(version = 0.2.0)
  enum ip-address-family {
    /// Similar to `AF_INET` in POSIX.
    ipv4,
    /// Similar to `AF_INET6` in POSIX.
    ipv6,
  }

  @since(version = 0.2.0)
  type ipv4-address = tuple<u8, u8, u8, u8>;

  @since(version = 0.2.0)
  type ipv6-address = tuple<u16, u16, u16, u16, u16, u16, u16, u16>;

  @since(version = 0.2.0)
  variant ip-address {
    ipv4(ipv4-address),
    ipv6(ipv6-address),
  }

  @since(version = 0.2.0)
  record ipv4-socket-address {
    /// sin_port
    port: u16,
    /// sin_addr
    address: ipv4-address,
  }

  @since(version = 0.2.0)
  record ipv6-socket-address {
    /// sin6_port
    port: u16,
    /// sin6_flowinfo
    flow-info: u32,
    /// sin6_addr
    address: ipv6-address,
    /// sin6_scope_id
    scope-id: u32,
  }

  @since(version = 0.2.0)
  variant ip-socket-address {
    ipv4(ipv4-socket-address),
    ipv6(ipv6-socket-address),
  }

  /// Attempts to extract a network-related `error-code` from the stream
  /// `error` provided.
  ///
  /// Stream operations which return `stream-error::last-operation-failed`
  /// have a payload with more information about the operation that failed.
  /// This payload can be passed through to this function to see if there's
  /// network-related information about the error to return.
  ///
  /// Note that this function is fallible because not all stream-related
  /// errors are network-related errors.
  @unstable(feature = network-error-code)
  network-error-code: func(err: borrow<error>) -> option<error-code>;
}