componentized/directory

componentized:sockets

interface dev

A collection of utility components that remix wasi:sockets types and interfaces.

interface latch componentized:sockets/latch@0.1.1-dev since 0.1.0

Access control for wasi:sockets.

A gate consults a latch before performing each socket operation. The latch either defers, raising no objection, or denies the operation. A latch never grants an operation, an operation proceeds when the latch defers. Several latches can be aggregated into one, the operation is denied when any of them denies it.

Deciding and acting on a decision are separate steps. authorize decides without side effects, then the gate reports the final decision to observe-decision, where a latch updates any state it keeps. A latch aggregated with others may not be asked to authorize an operation another latch already denied, but it always observes the final decision.

Types

use variant ip-addresssince 0.1.0

from wasi:sockets/types@0.3.0

use enum ip-address-familysince 0.1.0

from wasi:sockets/types@0.3.0

  • ipv4

    Similar to AF_INET in POSIX.

  • ipv6

    Similar to AF_INET6 in POSIX.

use variant ip-socket-addresssince 0.1.0

from wasi:sockets/types@0.3.0

use resource tcp-socketsince 0.1.0

from wasi:sockets/types@0.3.0

A TCP socket resource.

The socket can be in one of the following states:

Note: Except where explicitly mentioned, whenever this documentation uses the term "bound" without backticks it actually means: in the bound state or higher. (i.e. bound, listening, connecting or connected)

WASI uses shared ownership semantics: the tcp-socket handle and all derived stream and future values reference a single underlying OS socket:

  • Send/receive streams remain functional after the original tcp-socket handle is dropped.
  • The stream returned by listen behaves similarly.
  • Client sockets returned by tcp-socket::listen are independent and do not keep the listening socket alive.

The OS socket is closed only after the last handle is dropped. This model has observable effects; for example, it affects when the local port binding is released.

In addition to the general error codes documented on the types::error-code type, TCP socket methods may always return error(invalid-state) when in the closed state.

  • create: static func( address-family: ip-address-family, ) -> result<tcp-socket, error-code>since 0.3.0

    Create a new TCP socket.

    Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP) in POSIX. On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.

    Unlike POSIX, WASI sockets have no notion of a socket-level O_NONBLOCK flag. Instead they fully rely on the Component Model's async support.

    Typical errors

    • not-supported: The address-family is not supported. (EAFNOSUPPORT)

    References

  • bind: func(local-address: ip-socket-address) -> result<_, error-code>since 0.3.0

    Bind the socket to the provided IP address and port.

    If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which network interface(s) to bind to. If the TCP/UDP port is zero, the socket will be bound to a random free port.

    Bind can be attempted multiple times on the same socket, even with different arguments on each iteration. But never concurrently and only as long as the previous bind failed. Once a bind succeeds, the binding can't be changed anymore.

    Typical errors

    • invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    • invalid-argument: local-address is not a unicast address. (EINVAL)
    • invalid-argument: local-address is an IPv4-mapped IPv6 address. (EINVAL)
    • invalid-state: The socket is already bound. (EINVAL)
    • address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
    • address-in-use: Address is already in use. (EADDRINUSE)
    • address-not-bindable: local-address is not an address that can be bound to. (EADDRNOTAVAIL)

    Implementors note

    The bind operation shouldn't be affected by the TIME_WAIT state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR socket option should be set implicitly on all platforms, except on Windows where this is the default behavior and SO_REUSEADDR performs something different.

    References

  • connect: async func( remote-address: ip-socket-address, ) -> result<_, error-code>since 0.3.0

    Connect to a remote endpoint.

    On success, the socket is transitioned into the connected state and the remote-address of the socket is updated. The local-address may be updated as well, based on the best network path to remote-address. If the socket was not already explicitly bound, this function will implicitly bind the socket to a random free port.

    After a failed connection attempt, the socket will be in the closed state and the only valid action left is to drop the socket. A single socket can not be used to connect more than once.

    Typical errors

    • invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
    • invalid-argument: remote-address is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
    • invalid-argument: remote-address is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)
    • invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EADDRNOTAVAIL on Windows)
    • invalid-argument: The port in remote-address is set to 0. (EADDRNOTAVAIL on Windows)
    • invalid-state: The socket is already in the connecting state. (EALREADY)
    • invalid-state: The socket is already in the connected state. (EISCONN)
    • invalid-state: The socket is already in the listening state. (EOPNOTSUPP, EINVAL on Windows)
    • timeout: Connection timed out. (ETIMEDOUT)
    • connection-refused: The connection was forcefully rejected. (ECONNREFUSED)
    • connection-reset: The connection was reset. (ECONNRESET)
    • connection-aborted: The connection was aborted. (ECONNABORTED)
    • remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
    • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)

    References

  • listen: func() -> result<stream<tcp-socket>, error-code>since 0.3.0

    Start listening and return a stream of new inbound connections.

    Transitions the socket into the listening state. This can be called at most once per socket.

    If the socket is not already explicitly bound, this function will implicitly bind the socket to a random free port.

    Normally, the returned sockets are bound, in the connected state and immediately ready for I/O. Though, depending on exact timing and circumstances, a newly accepted connection may already be closed by the time the server attempts to perform its first I/O on it. This is true regardless of whether the WASI implementation uses "synthesized" sockets or not (see Implementors Notes below).

    The following properties are inherited from the listener socket:

    • address-family
    • keep-alive-enabled
    • keep-alive-idle-time
    • keep-alive-interval
    • keep-alive-count
    • hop-limit
    • receive-buffer-size
    • send-buffer-size

    Typical errors

    • invalid-state: The socket is already in the connected state. (EISCONN, EINVAL on BSD)
    • invalid-state: The socket is already in the listening state.
    • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)

    Implementors note

    This method returns a single perpetual stream that should only close on fatal errors (if any). Yet, the POSIX' accept function may also return transient errors (e.g. ECONNABORTED). The exact details differ per operation system. For example, the Linux manual mentions:

    Linux accept() passes already-pending network errors on the new socket as an error code from accept(). This behavior differs from other BSD socket implementations. For reliable operation the application should detect the network errors defined for the protocol after accept() and treat them like EAGAIN by retrying. In the case of TCP/IP, these are ENETDOWN, EPROTO, ENOPROTOOPT, EHOSTDOWN, ENONET, EHOSTUNREACH, EOPNOTSUPP, and ENETUNREACH. Source: https://man7.org/linux/man-pages/man2/accept.2.html

    WASI implementations have two options to handle this:

    • Optionally log it and then skip over non-fatal errors returned by accept. Guest code never gets to see these failures. Or:
    • Synthesize a tcp-socket resource that exposes the error when attempting to send or receive on it. Guest code then sees these failures as regular I/O errors.

    In either case, the stream returned by this listen method remains operational.

    WASI requires listen to perform an implicit bind if the socket has not already been bound. Not all platforms (notably Windows) exhibit this behavior out of the box. On platforms that require it, the WASI implementation can emulate this behavior by performing the bind itself if the guest hasn't already done so.

    References

  • send: func(data: stream<u8>) -> future<result<_, error-code>>since 0.3.0

    Transmit data to peer.

    The caller should close the stream when it has no more data to send to the peer. Under normal circumstances this will cause a FIN packet to be sent out. Closing the stream is equivalent to calling shutdown(SHUT_WR) in POSIX.

    This function may be called at most once and returns once the full contents of the stream are transmitted or an error is encountered.

    Typical errors

    • invalid-state: The socket is not in the connected state. (ENOTCONN)
    • invalid-state: send has already been called on this socket.
    • connection-broken: The connection is not writable anymore. (EPIPE, ECONNABORTED on Windows)
    • connection-reset: The connection was reset. (ECONNRESET)
    • remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)

    References

  • receive: func() -> tuple<stream<u8>, future<result<_, error-code>>>since 0.3.0

    Read data from peer.

    Returns a stream of data sent by the peer. The implementation drops the stream once no more data is available. At that point, the returned future resolves to:

    • ok after a graceful shutdown from the peer (i.e. a FIN packet), or
    • err if the socket was closed abnormally.

    receive may be called only once per socket. Subsequent calls return a closed stream and a future resolved to err(invalid-state).

    If the caller is not expecting to receive any more data from the peer, they should drop the stream. Any data still in the receive queue will be discarded. This is equivalent to calling shutdown(SHUT_RD) in POSIX.

    Typical errors

    • invalid-state: The socket is not in the connected state. (ENOTCONN)
    • invalid-state: receive has already been called on this socket.
    • connection-reset: The connection was reset. (ECONNRESET)
    • remote-unreachable: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)

    References

  • get-local-address: func() -> result<ip-socket-address, error-code>since 0.3.0

    Get the bound local address.

    POSIX mentions:

    If the socket has not been bound to a local name, the value stored in the object pointed to by address is unspecified.

    WASI is stricter and requires get-local-address to return invalid-state when the socket hasn't been bound yet.

    Typical errors

    • invalid-state: The socket is not bound to any local address.

    References

  • get-remote-address: func() -> result<ip-socket-address, error-code>since 0.3.0

    Get the remote address.

    Typical errors

    • invalid-state: The socket is not connected to a remote address. (ENOTCONN)

    References

  • get-is-listening: func() -> boolsince 0.3.0

    Whether the socket is in the listening state.

    Equivalent to the SO_ACCEPTCONN socket option.

  • get-address-family: func() -> ip-address-familysince 0.3.0

    Whether this is a IPv4 or IPv6 socket.

    This is the value passed to the constructor.

    Equivalent to the SO_DOMAIN socket option.

  • set-listen-backlog-size: func(value: u64) -> result<_, error-code>since 0.3.0

    Hints the desired listen queue size. Implementations are free to ignore this.

    If the provided value is 0, an invalid-argument error is returned. Any other value will never cause an error, but it might be silently clamped and/or rounded.

    Typical errors

    • not-supported: (set) The platform does not support changing the backlog size after the initial listen.
    • invalid-argument: (set) The provided value was 0.
    • invalid-state: (set) The socket is in the connecting or connected state.
  • get-keep-alive-enabled: func() -> result<bool, error-code>since 0.3.0

    Enables or disables keepalive.

    The keepalive behavior can be adjusted using:

    • keep-alive-idle-time
    • keep-alive-interval
    • keep-alive-count These properties can be configured while keep-alive-enabled is false, but only come into effect when keep-alive-enabled is true.

    Equivalent to the SO_KEEPALIVE socket option.

  • set-keep-alive-enabled: func(value: bool) -> result<_, error-code>since 0.3.0
  • get-keep-alive-idle-time: func() -> result<duration, error-code>since 0.3.0

    Amount of time the connection has to be idle before TCP starts sending keepalive packets.

    If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

    Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)

    Typical errors

    • invalid-argument: (set) The provided value was 0.
  • set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>since 0.3.0
  • get-keep-alive-interval: func() -> result<duration, error-code>since 0.3.0

    The time between keepalive packets.

    If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

    Equivalent to the TCP_KEEPINTVL socket option.

    Typical errors

    • invalid-argument: (set) The provided value was 0.
  • set-keep-alive-interval: func(value: duration) -> result<_, error-code>since 0.3.0
  • get-keep-alive-count: func() -> result<u32, error-code>since 0.3.0

    The maximum amount of keepalive packets TCP should send before aborting the connection.

    If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

    Equivalent to the TCP_KEEPCNT socket option.

    Typical errors

    • invalid-argument: (set) The provided value was 0.
  • set-keep-alive-count: func(value: u32) -> result<_, error-code>since 0.3.0
  • get-hop-limit: func() -> result<u8, error-code>since 0.3.0

    Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

    If the provided value is 0, an invalid-argument error is returned.

    Typical errors

    • invalid-argument: (set) The TTL value must be 1 or higher.
  • set-hop-limit: func(value: u8) -> result<_, error-code>since 0.3.0
  • get-receive-buffer-size: func() -> result<u64, error-code>since 0.3.0

    Kernel buffer space reserved for sending/receiving on this socket. Implementations usually treat this as a cap the buffer can grow to, rather than allocating the full amount immediately.

    If the provided value is 0, an invalid-argument error is returned. All other values are accepted without error, but may be clamped or rounded. As a result, the value read back from this setting may differ from the value that was set.

    This is only a performance hint. The implementation may ignore it or tweak it based on real traffic patterns. Linux and macOS appear to behave differently depending on whether a buffer size was explicitly set. When set, they tend to honor it; when not set, they dynamically adjust the buffer size as the connection progresses. This is especially noticeable when comparing the values from before and after connection establishment.

    Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

    Typical errors

    • invalid-argument: (set) The provided value was 0.
  • set-receive-buffer-size: func(value: u64) -> result<_, error-code>since 0.3.0
  • get-send-buffer-size: func() -> result<u64, error-code>since 0.3.0
  • set-send-buffer-size: func(value: u64) -> result<_, error-code>since 0.3.0

use resource udp-socketsince 0.1.0

from wasi:sockets/types@0.3.0

A UDP socket handle.

record resolve-addresses-argssince 0.1.0

Arguments to wasi:sockets/ip-name-lookup#resolve-addresses.

  • name: string

    The name to look up, as passed by the caller. DNS search paths are not applied.

record resolve-addresses-returns-itemsince 0.1.0

Items returned from calls to wasi:sockets/ip-name-lookup#resolve-addresses.

  • ip-address: ip-address

    An address the lookup returned.

variant ip-name-lookup-operationsince 0.1.0

Operations of the wasi:sockets/ip-name-lookup interface.

  • resolve-addresses: resolve-addresses-args

    Authorized before the name is looked up. A denial fails the lookup.

  • resolve-addresses-return: resolve-addresses-returns-item

    Authorized for each address the lookup returned. A denied address is removed from the result, the lookup succeeds with the remaining addresses.

record tcp-socket-create-argssince 0.1.0

Arguments to wasi:sockets/types#tcp-socket.create.

record tcp-socket-bind-argssince 0.1.0

Arguments to wasi:sockets/types#tcp-socket.bind.

record tcp-socket-connect-argssince 0.1.0

Arguments to wasi:sockets/types#tcp-socket.connect.

variant tcp-socket-operationsince 0.1.0

Operations of the wasi:sockets/types#tcp-socket interface.

The borrowed socket is the socket the operation is performed on, a latch may query it, for example for its local or remote address.

  • create: tcp-socket-create-args

    Authorized before the socket is created. A denial fails the create.

  • bind: tuple<borrow<tcp-socket>, tcp-socket-bind-args>

    Authorized before the socket is bound. A denial fails the bind.

  • connect: tuple<borrow<tcp-socket>, tcp-socket-connect-args>

    Authorized before the socket connects. A denial fails the connect, nothing is sent to the remote address.

  • listen: tuple<borrow<tcp-socket>>

    Authorized before the socket starts listening. A denial fails the listen.

  • listen-connection: tuple<borrow<tcp-socket>>

    Authorized for each connection a listening socket accepts, the borrowed socket is the accepted connection. A denied connection is closed before it reaches the caller, the listening socket keeps accepting other connections.

  • send: tuple<borrow<tcp-socket>>

    Authorized once per socket before data is sent, send can only be called once and streams all of its data. A denial fails the send.

  • receive: tuple<borrow<tcp-socket>>

    Authorized once per socket before data is received, receive can only be called once and streams all of its data. A denial fails the receive.

record udp-socket-create-argssince 0.1.0

Arguments to wasi:sockets/types#udp-socket.create.

record udp-socket-bind-argssince 0.1.0

Arguments to wasi:sockets/types#udp-socket.bind.

record udp-socket-connect-argssince 0.1.0

Arguments to wasi:sockets/types#udp-socket.connect.

record udp-socket-send-argssince 0.1.0

Arguments to wasi:sockets/types#udp-socket.send.

  • data-length: u64

    The length of the datagram in bytes.

  • remote-address: option<ip-socket-address>

    Where the datagram is sent. none for a connected socket sending to the remote address it is connected to.

record udp-socket-receive-returnssince 0.1.0

Returned value from calls to wasi:sockets/types#udp-socket.receive.

  • data-length: u64

    The length of the datagram in bytes.

  • remote-address: ip-socket-address

    Where the datagram was sent from. UDP source addresses are not authenticated.

variant udp-socket-operationsince 0.1.0

Operations of wasi:sockets/types#udp-socket.

The borrowed socket is the socket the operation is performed on, a latch may query it, for example for its local or remote address.

variant operationsince 0.1.0

Operations for the wasi:sockets package.

type latch-namesince 0.1.0

The name of a latch component, identifying which latch reported an error.

  • string

variant error-codesince 0.1.0

A latch was unable to decide or observe. The gate fails the operation, except for an accepted connection, which is closed as if it were denied.

  • invalid-config: latch-name

    The latch's configuration is invalid, the cause is logged by the latch.

  • observation-failed: latch-name

    The latch was unable to act on the final decision.

  • other: option<string>

    Any other error.

variant sockets-error-codesince 0.1.0

The reason an operation is denied, returned to the caller as the wasi:sockets error code.

  • access-denied

    Access denied.

    POSIX equivalent: EACCES, EPERM

  • invalid-argument

    One of the arguments is invalid.

    POSIX equivalent: EINVAL, EDESTADDRREQ, EAFNOSUPPORT

  • 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.

variant decisionsince 0.1.0

Whether the operation is allowed to proceed.

  • deferred

    No objection to the operation.

  • denied: sockets-error-code

    The operation must not proceed. The error code is returned to the caller for operations that fail. For traffic that is dropped instead, like an accepted connection or a received datagram, it is only logged.

Functions

authorize: func(operation: operation) -> result<decision, error-code>since 0.1.0

Decide whether the operation may proceed.

Must not have side effects. When latches are aggregated, a latch is not asked about an operation another latch already denied, so state changed here could disagree with what actually happened. Act on decisions in observe-decision instead.

observe-decision: func( final-decision: decision, operation: operation, ) -> result<_, error-code>since 0.1.0

Observe the final decision for an operation, after authorize returned a decision.

Called for both deferred and denied operations, including operations this latch was not asked to authorize because an aggregated latch denied them first. The final decision is what the gate enforces, so this is where a latch updates any state it keeps, for example remembering peers the caller is allowed to exchange traffic with. Not called when authorize returned an error.

An error fails the operation, since the latch could not act on the decision.

WIT

/// Access control for wasi:sockets.
///
/// A gate consults a latch before performing each socket operation. The latch either defers,
/// raising no objection, or denies the operation. A latch never grants an operation, an
/// operation proceeds when the latch defers. Several latches can be aggregated into one, the
/// operation is denied when any of them denies it.
///
/// Deciding and acting on a decision are separate steps. `authorize` decides without side
/// effects, then the gate reports the final decision to `observe-decision`, where a latch updates
/// any state it keeps. A latch aggregated with others may not be asked to authorize an operation
/// another latch already denied, but it always observes the final decision.
@since(version = 0.1.0)
interface latch {
  @since(version = 0.1.0)
  use wasi:sockets/types@0.3.0.{ip-address, ip-address-family, ip-socket-address, tcp-socket, udp-socket};

  /// Arguments to wasi:sockets/ip-name-lookup#resolve-addresses.
  @since(version = 0.1.0)
  record resolve-addresses-args {
    /// The name to look up, as passed by the caller. DNS search paths are not applied.
    name: string,
  }

  /// Items returned from calls to wasi:sockets/ip-name-lookup#resolve-addresses.
  @since(version = 0.1.0)
  record resolve-addresses-returns-item {
    /// An address the lookup returned.
    ip-address: ip-address,
  }

  /// Operations of the wasi:sockets/ip-name-lookup interface.
  @since(version = 0.1.0)
  variant ip-name-lookup-operation {
    /// Authorized before the name is looked up. A denial fails the lookup.
    resolve-addresses(resolve-addresses-args),
    /// Authorized for each address the lookup returned. A denied address is removed from the
    /// result, the lookup succeeds with the remaining addresses.
    resolve-addresses-return(resolve-addresses-returns-item),
  }

  /// Arguments to wasi:sockets/types#tcp-socket.create.
  @since(version = 0.1.0)
  record tcp-socket-create-args {
    address-family: ip-address-family,
  }

  /// Arguments to wasi:sockets/types#tcp-socket.bind.
  @since(version = 0.1.0)
  record tcp-socket-bind-args {
    local-address: ip-socket-address,
  }

  /// Arguments to wasi:sockets/types#tcp-socket.connect.
  @since(version = 0.1.0)
  record tcp-socket-connect-args {
    remote-address: ip-socket-address,
  }

  /// Operations of the wasi:sockets/types#tcp-socket interface.
  ///
  /// The borrowed socket is the socket the operation is performed on, a latch may query it, for
  /// example for its local or remote address.
  @since(version = 0.1.0)
  variant tcp-socket-operation {
    /// Authorized before the socket is created. A denial fails the create.
    create(tcp-socket-create-args),
    /// Authorized before the socket is bound. A denial fails the bind.
    bind(tuple<borrow<tcp-socket>, tcp-socket-bind-args>),
    /// Authorized before the socket connects. A denial fails the connect, nothing is sent to
    /// the remote address.
    connect(tuple<borrow<tcp-socket>, tcp-socket-connect-args>),
    /// Authorized before the socket starts listening. A denial fails the listen.
    listen(tuple<borrow<tcp-socket>>),
    /// Authorized for each connection a listening socket accepts, the borrowed socket is the
    /// accepted connection. A denied connection is closed before it reaches the caller, the
    /// listening socket keeps accepting other connections.
    listen-connection(tuple<borrow<tcp-socket>>),
    /// Authorized once per socket before data is sent, `send` can only be called once and
    /// streams all of its data. A denial fails the send.
    send(tuple<borrow<tcp-socket>>),
    /// Authorized once per socket before data is received, `receive` can only be called once
    /// and streams all of its data. A denial fails the receive.
    receive(tuple<borrow<tcp-socket>>),
  }

  /// Arguments to wasi:sockets/types#udp-socket.create.
  @since(version = 0.1.0)
  record udp-socket-create-args {
    address-family: ip-address-family,
  }

  /// Arguments to wasi:sockets/types#udp-socket.bind.
  @since(version = 0.1.0)
  record udp-socket-bind-args {
    local-address: ip-socket-address,
  }

  /// Arguments to wasi:sockets/types#udp-socket.connect.
  @since(version = 0.1.0)
  record udp-socket-connect-args {
    remote-address: ip-socket-address,
  }

  /// Arguments to wasi:sockets/types#udp-socket.send.
  @since(version = 0.1.0)
  record udp-socket-send-args {
    /// The length of the datagram in bytes.
    data-length: u64,
    /// Where the datagram is sent. `none` for a connected socket sending to the remote
    /// address it is connected to.
    remote-address: option<ip-socket-address>,
  }

  /// Returned value from calls to wasi:sockets/types#udp-socket.receive.
  @since(version = 0.1.0)
  record udp-socket-receive-returns {
    /// The length of the datagram in bytes.
    data-length: u64,
    /// Where the datagram was sent from. UDP source addresses are not authenticated.
    remote-address: ip-socket-address,
  }

  /// Operations of wasi:sockets/types#udp-socket.
  ///
  /// The borrowed socket is the socket the operation is performed on, a latch may query it, for
  /// example for its local or remote address.
  @since(version = 0.1.0)
  variant udp-socket-operation {
    /// Authorized before the socket is created. A denial fails the create.
    create(udp-socket-create-args),
    /// Authorized before the socket is bound. A denial fails the bind.
    bind(tuple<borrow<udp-socket>, udp-socket-bind-args>),
    /// Authorized before the socket connects. A denial fails the connect.
    connect(tuple<borrow<udp-socket>, udp-socket-connect-args>),
    /// Authorized for each datagram before it is sent. A denial fails the send, nothing is
    /// sent.
    send(tuple<borrow<udp-socket>, udp-socket-send-args>),
    /// Authorized for each datagram after it is received, before it reaches the caller. A
    /// denied datagram is dropped and the receive continues with the next datagram, so a
    /// sender cannot fail the caller's receive.
    receive(tuple<borrow<udp-socket>, udp-socket-receive-returns>),
  }

  /// Operations for the wasi:sockets package.
  @since(version = 0.1.0)
  variant operation {
    ip-name-lookup(ip-name-lookup-operation),
    tcp-socket(tcp-socket-operation),
    udp-socket(udp-socket-operation),
  }

  /// The name of a latch component, identifying which latch reported an error.
  @since(version = 0.1.0)
  type latch-name = string;

  /// A latch was unable to decide or observe. The gate fails the operation, except for an
  /// accepted connection, which is closed as if it were denied.
  @since(version = 0.1.0)
  variant error-code {
    /// The latch's configuration is invalid, the cause is logged by the latch.
    invalid-config(latch-name),
    /// The latch was unable to act on the final decision.
    observation-failed(latch-name),
    /// Any other error.
    other(option<string>),
  }

  /// The reason an operation is denied, returned to the caller as the wasi:sockets error code.
  @since(version = 0.1.0)
  variant sockets-error-code {
    /// Access denied.
    ///
    /// POSIX equivalent: EACCES, EPERM
    access-denied,
    /// One of the arguments is invalid.
    ///
    /// POSIX equivalent: EINVAL, EDESTADDRREQ, EAFNOSUPPORT
    invalid-argument,
    /// 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>),
  }

  /// Whether the operation is allowed to proceed.
  @since(version = 0.1.0)
  variant decision {
    /// No objection to the operation.
    deferred,
    /// The operation must not proceed. The error code is returned to the caller for
    /// operations that fail. For traffic that is dropped instead, like an accepted connection
    /// or a received datagram, it is only logged.
    denied(sockets-error-code),
  }

  /// Decide whether the operation may proceed.
  ///
  /// Must not have side effects. When latches are aggregated, a latch is not asked about an
  /// operation another latch already denied, so state changed here could disagree with what
  /// actually happened. Act on decisions in `observe-decision` instead.
  @since(version = 0.1.0)
  authorize: func(operation: operation) -> result<decision, error-code>;

  /// Observe the final decision for an operation, after `authorize` returned a decision.
  ///
  /// Called for both deferred and denied operations, including operations this latch was not
  /// asked to authorize because an aggregated latch denied them first. The final decision is
  /// what the gate enforces, so this is where a latch updates any state it keeps, for example
  /// remembering peers the caller is allowed to exchange traffic with. Not called when
  /// `authorize` returned an error.
  ///
  /// An error fails the operation, since the latch could not act on the decision.
  @since(version = 0.1.0)
  observe-decision: func(final-decision: decision, operation: operation) -> result<_, error-code>;
}