use resource input-streamsince 0.2.0

from wasi:io/streams@0.2.3

• functionread: func(len: u64) -> result<list<u8>, stream-error>since 0.2.0

  Perform a non-blocking read from the stream.

  When the source of a read is binary data, the bytes from the source are returned verbatim. When the source of a read is known to the implementation to be text, bytes containing the UTF-8 encoding of the text are returned.

  This function returns a list of bytes containing the read data, when successful. The returned list will contain up to len bytes; it may return fewer than requested, but not more. The list is empty when no bytes are available for reading at this time. The pollable given by subscribe will be ready when more bytes are available.

  This function fails with a stream-error when the operation encounters an error, giving last-operation-failed, or when the stream is closed, giving closed.

  When the caller gives a len of 0, it represents a request to read 0 bytes. If the stream is still open, this call should succeed and return an empty list, or otherwise fail with closed.

  The len parameter is a u64, which could represent a list of u8 which is not possible to allocate in wasm32, or not desirable to allocate as as a return value by the callee. The callee may return a list of bytes less than len in size while more bytes are available for reading.

• functionblocking-read: func(len: u64) -> result<list<u8>, stream-error>since 0.2.0

  Read bytes from a stream, after blocking until at least one byte can be read. Except for blocking, behavior is identical to read.

• functionskip: func(len: u64) -> result<u64, stream-error>since 0.2.0

  Skip bytes from a stream. Returns number of bytes skipped.

  Behaves identical to read, except instead of returning a list of bytes, returns the number of bytes consumed from the stream.

• functionblocking-skip: func(len: u64) -> result<u64, stream-error>since 0.2.0

  Skip bytes from a stream, after blocking until at least one byte can be skipped. Except for blocking behavior, identical to skip.

• functionsubscribe: func() -> pollablesince 0.2.0

  Create a pollable which will resolve once either the specified stream has bytes available to read or the other end of the stream has been closed. The created pollable is a child resource of the input-stream. Implementations may trap if the input-stream is dropped before all derived pollables created with this function are dropped.

use resource output-streamsince 0.2.0

from wasi:io/streams@0.2.3

• functioncheck-write: func() -> result<u64, stream-error>since 0.2.0

  Check readiness for writing. This function never blocks.

  Returns the number of bytes permitted for the next call to write, or an error. Calling write with more bytes than this function has permitted will trap.

  When this function returns 0 bytes, the subscribe pollable will become ready when this function will report at least 1 byte, or an error.

• functionwrite: func(contents: list<u8>) -> result<_, stream-error>since 0.2.0

  Perform a write. This function never blocks.

  When the destination of a write is binary data, the bytes from contents are written verbatim. When the destination of a write is known to the implementation to be text, the bytes of contents are transcoded from UTF-8 into the encoding of the destination and then written.

  Precondition: check-write gave permit of Ok(n) and contents has a length of less than or equal to n. Otherwise, this function will trap.

  returns Err(closed) without writing if the stream has closed since the last call to check-write provided a permit.

• functionblocking-write-and-flush: func( contents: list<u8>, ) -> result<_, stream-error>since 0.2.0

  Perform a write of up to 4096 bytes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

  This is a convenience wrapper around the use of check-write, subscribe, write, and flush, and is implemented with the following pseudo-code:

  let pollable = this.subscribe();
  while !contents.is_empty() {
  // Wait for the stream to become writable
  pollable.block();
  let Ok(n) = this.check-write(); // eliding error handling
  let len = min(n, contents.len());
  let (chunk, rest) = contents.split_at(len);
  this.write(chunk  );            // eliding error handling
  contents = rest;
  }
  this.flush();
  // Wait for completion of `flush`
  pollable.block();
  // Check for any errors that arose during `flush`
  let _ = this.check-write();         // eliding error handling
  

• functionflush: func() -> result<_, stream-error>since 0.2.0

  Request to flush buffered output. This function never blocks.

  This tells the output-stream that the caller intends any buffered output to be flushed. the output which is expected to be flushed is all that has been passed to write prior to this call.

  Upon calling this function, the output-stream will not accept any writes (check-write will return ok(0)) until the flush has completed. The subscribe pollable will become ready when the flush has completed and the stream can accept more writes.

• functionblocking-flush: func() -> result<_, stream-error>since 0.2.0

  Request to flush buffered output, and block until flush completes and stream is ready for writing again.

• functionsubscribe: func() -> pollablesince 0.2.0

  Create a pollable which will resolve once the output-stream is ready for more writing, or an error has occurred. When this pollable is ready, check-write will return ok(n) with n>0, or an error.

  If the stream is closed, this pollable is always ready immediately.

  The created pollable is a child resource of the output-stream. Implementations may trap if the output-stream is dropped before all derived pollables created with this function are dropped.

• functionwrite-zeroes: func(len: u64) -> result<_, stream-error>since 0.2.0

  Write zeroes to a stream.

  This should be used precisely like write with the exact same preconditions (must use check-write first), but instead of passing a list of bytes, you simply pass the number of zero-bytes that should be written.

• functionblocking-write-zeroes-and-flush: func( len: u64, ) -> result<_, stream-error>since 0.2.0

  Perform a write of up to 4096 zeroes, and then flush the stream. Block until all of these operations are complete, or an error occurs.

  This is a convenience wrapper around the use of check-write, subscribe, write-zeroes, and flush, and is implemented with the following pseudo-code:

  let pollable = this.subscribe();
  while num_zeroes != 0 {
  // Wait for the stream to become writable
  pollable.block();
  let Ok(n) = this.check-write(); // eliding error handling
  let len = min(n, num_zeroes);
  this.write-zeroes(len);         // eliding error handling
  num_zeroes -= len;
  }
  this.flush();
  // Wait for completion of `flush`
  pollable.block();
  // Check for any errors that arose during `flush`
  let _ = this.check-write();         // eliding error handling
  

• functionsplice: func( src: borrow<input-stream>, len: u64, ) -> result<u64, stream-error>since 0.2.0

  Read from one stream and write to another.

  The behavior of splice is equivalent to:

  1. calling check-write on the output-stream
  2. calling read on the input-stream with the smaller of the check-write permitted length and the len provided to splice
  3. calling write on the output-stream with that read data.

  Any error reported by the call to check-write, read, or write ends the splice and reports that error.

  This function returns the number of bytes transferred; it may be less than len.

• functionblocking-splice: func( src: borrow<input-stream>, len: u64, ) -> result<u64, stream-error>since 0.2.0

  Read from one stream and write to another, with blocking.

  This is similar to splice, except that it blocks until the output-stream is ready for writing, and the input-stream is ready for reading, before performing the splice.

use resource pollablesince 0.2.0

from wasi:io/poll@0.2.3

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

• functionblock: 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 type durationsince 0.2.0

from wasi:clocks/monotonic-clock@0.2.3

• u64

use resource networksince 0.2.0

from wasi:sockets/network@0.2.3

use enum error-codesince 0.2.0

from wasi:sockets/network@0.2.3

• 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-socket-addresssince 0.2.0

from wasi:sockets/network@0.2.3

• ipv4: ipv4-socket-address
• ipv6: ipv6-socket-address

use enum ip-address-familysince 0.2.0

from wasi:sockets/network@0.2.3

• ipv4

  Similar to AF_INET in POSIX.

• ipv6

  Similar to AF_INET6 in POSIX.

enum shutdown-typesince 0.2.0

• receive

  Similar to SHUT_RD in POSIX.

• send

  Similar to SHUT_WR in POSIX.

• both

  Similar to SHUT_RDWR in POSIX.

resource tcp-socketsince 0.2.0

• functionstart-bind: func( network: borrow<network>, local-address: ip-socket-address, ) -> result<_, error-code>since 0.2.0

  Bind the socket to a specific network on 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 the network can bind to. (EADDRNOTAVAIL)
  • not-in-progress: A bind operation is not in progress.
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)

  Implementors note

  When binding to a non-zero port, this 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 entirely.

  Unlike in POSIX, in WASI the bind operation is async. This enables interactive WASI hosts to inject permission prompts. Runtimes that don't want to make use of this ability can simply call the native bind as part of either start-bind or finish-bind.

  References

  • https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
  • https://man7.org/linux/man-pages/man2/bind.2.html
  • https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind
  • https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html
• functionfinish-bind: func() -> result<_, error-code>since 0.2.0
• functionstart-connect: func( network: borrow<network>, remote-address: ip-socket-address, ) -> result<_, error-code>since 0.2.0

  Connect to a remote endpoint.

  On success:

  • the socket is transitioned into the connected state.
  • a pair of streams is returned that can be used to read & write to the connection

  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-argument: The socket is already attached to a different network. The network passed to connect must be identical to the one passed to bind.
  • 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)
  • not-in-progress: A connect operation is not in progress.
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)

  Implementors note

  The POSIX equivalent of start-connect is the regular connect syscall. Because all WASI sockets are non-blocking this is expected to return EINPROGRESS, which should be translated to ok() in WASI.

  The POSIX equivalent of finish-connect is a poll for event POLLOUT with a timeout of 0 on the socket descriptor. Followed by a check for the SO_ERROR socket option, in case the poll signaled readiness.

  References

  • https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
  • https://man7.org/linux/man-pages/man2/connect.2.html
  • https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
  • https://man.freebsd.org/cgi/man.cgi?connect
• functionfinish-connect: func() -> result<tuple<input-stream, output-stream>, error-code>since 0.2.0
• functionstart-listen: func() -> result<_, error-code>since 0.2.0

  Start listening for new connections.

  Transitions the socket into the listening state.

  Unlike POSIX, the socket must already be explicitly bound.

  Typical errors

  • invalid-state: The socket is not bound to any local address. (EDESTADDRREQ)
  • 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)
  • not-in-progress: A listen operation is not in progress.
  • would-block: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)

  Implementors note

  Unlike in POSIX, in WASI the listen operation is async. This enables interactive WASI hosts to inject permission prompts. Runtimes that don't want to make use of this ability can simply call the native listen as part of either start-listen or finish-listen.

  References

  • https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html
  • https://man7.org/linux/man-pages/man2/listen.2.html
  • https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen
  • https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2
• functionfinish-listen: func() -> result<_, error-code>since 0.2.0
• functionaccept: func() -> result<tuple<tcp-socket, input-stream, output-stream>, error-code>since 0.2.0

  Accept a new client socket.

  The returned socket is bound and in the connected state. 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

  On success, this function returns the newly accepted client socket along with a pair of streams that can be used to read & write to the connection.

  Typical errors

  • invalid-state: Socket is not in the listening state. (EINVAL)
  • would-block: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
  • connection-aborted: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
  • new-socket-limit: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)

  References

  • https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html
  • https://man7.org/linux/man-pages/man2/accept.2.html
  • https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept
  • https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2
• functionlocal-address: func() -> result<ip-socket-address, error-code>since 0.2.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 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

  • https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
  • https://man7.org/linux/man-pages/man2/getsockname.2.html
  • https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname
  • https://man.freebsd.org/cgi/man.cgi?getsockname
• functionremote-address: func() -> result<ip-socket-address, error-code>since 0.2.0

  Get the remote address.

  Typical errors

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

  References

  • https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
  • https://man7.org/linux/man-pages/man2/getpeername.2.html
  • https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername
  • https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1
• functionis-listening: func() -> boolsince 0.2.0

  Whether the socket is in the listening state.

  Equivalent to the SO_ACCEPTCONN socket option.

• functionaddress-family: func() -> ip-address-familysince 0.2.0

  Whether this is a IPv4 or IPv6 socket.

  Equivalent to the SO_DOMAIN socket option.

• functionset-listen-backlog-size: func(value: u64) -> result<_, error-code>since 0.2.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 connect-in-progress or connected state.
• functionkeep-alive-enabled: func() -> result<bool, error-code>since 0.2.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.

• functionset-keep-alive-enabled: func(value: bool) -> result<_, error-code>since 0.2.0
• functionkeep-alive-idle-time: func() -> result<duration, error-code>since 0.2.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. Any other value will never cause an error, but it might be silently clamped and/or rounded. I.e. after setting a value, reading the same setting back may return a different value.

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

  Typical errors

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

  The time between keepalive packets.

  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. I.e. after setting a value, reading the same setting back may return a different value.

  Equivalent to the TCP_KEEPINTVL socket option.

  Typical errors

  • invalid-argument: (set) The provided value was 0.
• functionset-keep-alive-interval: func(value: duration) -> result<_, error-code>since 0.2.0
• functionkeep-alive-count: func() -> result<u32, error-code>since 0.2.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. Any other value will never cause an error, but it might be silently clamped and/or rounded. I.e. after setting a value, reading the same setting back may return a different value.

  Equivalent to the TCP_KEEPCNT socket option.

  Typical errors

  • invalid-argument: (set) The provided value was 0.
• functionset-keep-alive-count: func(value: u32) -> result<_, error-code>since 0.2.0
• functionhop-limit: func() -> result<u8, error-code>since 0.2.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.
• functionset-hop-limit: func(value: u8) -> result<_, error-code>since 0.2.0
• functionreceive-buffer-size: func() -> result<u64, error-code>since 0.2.0

  The kernel buffer space reserved for sends/receives on this socket.

  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. I.e. after setting a value, reading the same setting back may return a different value.

  Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

  Typical errors

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

  Create a pollable which can be used to poll for, or block on, completion of any of the asynchronous operations of this socket.

  When finish-bind, finish-listen, finish-connect or accept return error(would-block), this pollable can be used to wait for their success or failure, after which the method can be retried.

  The pollable is not limited to the async operation that happens to be in progress at the time of calling subscribe (if any). Theoretically, subscribe only has to be called once per socket and can then be (re)used for the remainder of the socket's lifetime.

  See https://github.com/WebAssembly/wasi-sockets/blob/main/TcpSocketOperationalSemantics.md#pollable-readiness for more information.

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

• functionshutdown: func(shutdown-type: shutdown-type) -> result<_, error-code>since 0.2.0

  Initiate a graceful shutdown.

  • receive: The socket is not expecting to receive any data from the peer. The input-stream associated with this socket will be closed. Any data still in the receive queue at time of calling this method will be discarded.
  • send: The socket has no more data to send to the peer. The output-stream associated with this socket will be closed and a FIN packet will be sent.
  • both: Same effect as receive & send combined.

  This function is idempotent; shutting down a direction more than once has no effect and returns ok.

  The shutdown function does not close (drop) the socket.

  Typical errors

  • invalid-state: The socket is not in the connected state. (ENOTCONN)

  References

  • https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html
  • https://man7.org/linux/man-pages/man2/shutdown.2.html
  • https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown
  • https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2