@bytecodealliance/preview2-shim 0.15.0 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bytecodealliance/preview2-shim",
-  "version": "0.15.0",
+  "version": "0.15.1",
   "description": "WASI Preview2 shim for JS environments",
   "author": "Guy Bedford, Eduardo Rodrigues<16357187+eduardomourar@users.noreply.github.com>",
   "type": "module",

package/types/cli.d.ts

@@ -0,0 +1,23 @@
+import type { WasiCliEnvironment } from './interfaces/wasi-cli-environment.d.ts';
+import type { WasiCliExit } from './interfaces/wasi-cli-exit.d.ts';
+import type { WasiCliRun } from './interfaces/wasi-cli-run.d.ts';
+import type { WasiCliStderr } from './interfaces/wasi-cli-stderr.d.ts';
+import type { WasiCliStdin } from './interfaces/wasi-cli-stdin.d.ts';
+import type { WasiCliStdout } from './interfaces/wasi-cli-stdout.d.ts';
+import type { WasiCliTerminalInput } from './interfaces/wasi-cli-terminal-input.d.ts';
+import type { WasiCliTerminalOutput } from './interfaces/wasi-cli-terminal-output.d.ts';
+import type { WasiCliTerminalStderr } from './interfaces/wasi-cli-terminal-stderr.d.ts';
+import type { WasiCliTerminalStdin } from './interfaces/wasi-cli-terminal-stdin.d.ts';
+import type { WasiCliTerminalStdout } from './interfaces/wasi-cli-terminal-stdout.d.ts';
+
+export const environment: typeof WasiCliEnvironment;
+export const exit: typeof WasiCliExit;
+export const run: typeof WasiCliRun;
+export const stderr: typeof WasiCliStderr;
+export const stdin: typeof WasiCliStdin;
+export const stdout: typeof WasiCliStdout;
+export const terminalInput: typeof WasiCliTerminalInput;
+export const terminalOutput: typeof WasiCliTerminalOutput;
+export const terminalStderr: typeof WasiCliTerminalStderr;
+export const terminalStdin: typeof WasiCliTerminalStdin;
+export const terminalStdout: typeof WasiCliTerminalStdout;

package/types/clocks.d.ts

@@ -0,0 +1,5 @@
+import type { WasiClocksMonotonicClock } from './interfaces/wasi-clocks-monotonic-clock.d.ts';
+import type { WasiClocksWallClock } from './interfaces/wasi-clocks-wall-clock.d.ts';
+
+export const wallClock: typeof WasiClocksMonotonicClock;
+export const monotonicClock: typeof WasiClocksWallClock;

package/types/filesystem.d.ts

@@ -0,0 +1,5 @@
+import type { WasiFilesystemPreopens } from './interfaces/wasi-filesystem-preopens.d.ts';
+import type { WasiFilesystemTypes } from './interfaces/wasi-filesystem-types.d.ts';
+
+export const preopens: typeof WasiFilesystemPreopens;
+export const types: typeof WasiFilesystemTypes;

package/types/http.d.ts

@@ -0,0 +1,7 @@
+import type { WasiHttpIncomingHandler } from './interfaces/wasi-http-incoming-handler.d.ts';
+import type { WasiHttpOutgoingHandler } from './interfaces/wasi-http-outgoing-handler.d.ts';
+import type { WasiHttpTypes } from './interfaces/wasi-http-types.d.ts';
+
+export const incomingHandler: typeof WasiHttpIncomingHandler;
+export const outgoingHandler: typeof WasiHttpOutgoingHandler;
+export const types: typeof WasiHttpTypes;

package/types/index.d.ts

@@ -0,0 +1,15 @@
+import type * as WasiCli from "./cli.d.ts";
+import type * as WasiClocks from './clocks.d.ts';
+import type * as WasiFilesystem from './filesystem.d.ts';
+import type * as WasiHttp from "./http.d.ts";
+import type * as WasiIo from "./io.d.ts";
+import type * as WasiRandom from "./random.d.ts";
+import type * as WasiSockets from "./sockets.d.ts";
+
+export const cli: typeof WasiCli;
+export const clocks: typeof WasiClocks;
+export const filesystem: typeof WasiFilesystem;
+export const http: typeof WasiHttp;
+export const io: typeof WasiIo;
+export const random: typeof WasiRandom;
+export const sockets: typeof WasiSockets;

package/types/interfaces/wasi-http-types.d.ts

@@ -629,6 +629,18 @@ export type Trailers = Fields;
 export type StatusCode = number;
 export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };
 
+export class ResponseOutparam {
+  static set(param: ResponseOutparam, response: Result<OutgoingResponse, ErrorCode>): void;
+}
+
+export class OutgoingResponse {
+  constructor(headers: Headers)
+  statusCode(): StatusCode;
+  setStatusCode(statusCode: StatusCode): void;
+  headers(): Headers;
+  body(): OutgoingBody;
+}
+
 export class OutgoingBody {
   write(): OutputStream;
   static finish(this_: OutgoingBody, trailers: Trailers | undefined): void;
@@ -640,50 +652,36 @@ export class Fields {
   get(name: FieldKey): FieldValue[];
   has(name: FieldKey): boolean;
   set(name: FieldKey, value: FieldValue[]): void;
-  delete(name: FieldKey): void;
+  'delete'(name: FieldKey): void;
   append(name: FieldKey, value: FieldValue): void;
   entries(): [FieldKey, FieldValue][];
   clone(): Fields;
 }
 
-export class FutureIncomingResponse {
-  subscribe(): Pollable;
-  get(): Result<Result<IncomingResponse, ErrorCode>, void> | undefined;
-}
-
-export class IncomingRequest {
-  method(): Method;
-  pathWithQuery(): string | undefined;
-  scheme(): Scheme | undefined;
-  authority(): string | undefined;
-  headers(): Headers;
-  consume(): IncomingBody;
-}
-
 export class IncomingBody {
   stream(): InputStream;
   static finish(this_: IncomingBody): FutureTrailers;
 }
 
+export class FutureIncomingResponse {
+  subscribe(): Pollable;
+  get(): Result<Result<IncomingResponse, ErrorCode>, void> | undefined;
+}
+
 export class FutureTrailers {
   subscribe(): Pollable;
   get(): Result<Result<Trailers | undefined, ErrorCode>, void> | undefined;
 }
 
-export class IncomingResponse {
-  status(): StatusCode;
+export class IncomingRequest {
+  method(): Method;
+  pathWithQuery(): string | undefined;
+  scheme(): Scheme | undefined;
+  authority(): string | undefined;
   headers(): Headers;
   consume(): IncomingBody;
 }
 
-export class OutgoingResponse {
-  constructor(headers: Headers)
-  statusCode(): StatusCode;
-  setStatusCode(statusCode: StatusCode): void;
-  headers(): Headers;
-  body(): OutgoingBody;
-}
-
 export class OutgoingRequest {
   constructor(headers: Headers)
   body(): OutgoingBody;
@@ -698,6 +696,12 @@ export class OutgoingRequest {
   headers(): Headers;
 }
 
+export class IncomingResponse {
+  status(): StatusCode;
+  headers(): Headers;
+  consume(): IncomingBody;
+}
+
 export class RequestOptions {
   constructor()
   connectTimeout(): Duration | undefined;
@@ -707,7 +711,3 @@ export class RequestOptions {
   betweenBytesTimeout(): Duration | undefined;
   setBetweenBytesTimeout(duration: Duration | undefined): void;
 }
-
-export class ResponseOutparam {
-  static set(param: ResponseOutparam, response: Result<OutgoingResponse, ErrorCode>): void;
-}

package/types/interfaces/wasi-io-streams.d.ts

@@ -2,6 +2,11 @@ export namespace WasiIoStreams {
   /**
    * 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
@@ -60,6 +65,12 @@ export namespace WasiIoStreams {
   /**
    * 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.
    * 
@@ -78,7 +89,7 @@ export namespace WasiIoStreams {
    * let pollable = this.subscribe();
    * while !contents.is_empty() {
      * // Wait for the stream to become writable
-     * poll-one(pollable);
+     * pollable.block();
      * let Ok(n) = this.check-write(); // eliding error handling
      * let len = min(n, contents.len());
      * let (chunk, rest) = contents.split_at(len);
@@ -87,7 +98,7 @@ export namespace WasiIoStreams {
      * }
      * this.flush();
      * // Wait for completion of `flush`
-     * poll-one(pollable);
+     * pollable.block();
      * // Check for any errors that arose during `flush`
      * let _ = this.check-write();         // eliding error handling
      * ```
@@ -123,7 +134,7 @@ export namespace WasiIoStreams {
     /**
      * Write zeroes to a stream.
      * 
-     * this should be used precisely like `write` with the exact same
+     * 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.
@@ -141,7 +152,7 @@ export namespace WasiIoStreams {
      * let pollable = this.subscribe();
      * while num_zeroes != 0 {
        * // Wait for the stream to become writable
-       * poll-one(pollable);
+       * pollable.block();
        * let Ok(n) = this.check-write(); // eliding error handling
        * let len = min(n, num_zeroes);
        * this.write-zeroes(len);         // eliding error handling
@@ -149,7 +160,7 @@ export namespace WasiIoStreams {
        * }
        * this.flush();
        * // Wait for completion of `flush`
-       * poll-one(pollable);
+       * pollable.block();
        * // Check for any errors that arose during `flush`
        * let _ = this.check-write();         // eliding error handling
        * ```

package/types/interfaces/wasi-sockets-network.d.ts

@@ -76,15 +76,17 @@ export namespace WasiSocketsNetwork {
  * The remote address is not reachable
  * ## `"connection-refused"`
  * 
- * The connection was forcefully rejected
+ * The TCP connection was forcefully rejected
  * ## `"connection-reset"`
  * 
- * The connection was reset.
+ * The TCP connection was reset.
  * ## `"connection-aborted"`
  * 
- * A connection was 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.
@@ -119,13 +121,31 @@ export interface IpAddressIpv6 {
   val: Ipv6Address,
 }
 export interface Ipv4SocketAddress {
+  /**
+   * sin_port
+   */
   port: number,
+  /**
+   * sin_addr
+   */
   address: Ipv4Address,
 }
 export interface Ipv6SocketAddress {
+  /**
+   * sin6_port
+   */
   port: number,
+  /**
+   * sin6_flowinfo
+   */
   flowInfo: number,
+  /**
+   * sin6_addr
+   */
   address: Ipv6Address,
+  /**
+   * sin6_scope_id
+   */
   scopeId: number,
 }
 export type IpSocketAddress = IpSocketAddressIpv4 | IpSocketAddressIpv6;

package/types/interfaces/wasi-sockets-tcp-create-socket.d.ts

@@ -3,9 +3,10 @@ export namespace WasiSocketsTcpCreateSocket {
    * 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.
    * 
    * This function does not require a network capability handle. This is considered to be safe because
-   * at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind`/`listen`/`connect`
+   * at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind`/`connect`
    * is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.
    * 
    * All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

package/types/interfaces/wasi-sockets-tcp.d.ts

@@ -6,18 +6,16 @@ export namespace WasiSocketsTcp {
    * network interface(s) to bind to.
    * If the TCP/UDP port is zero, the socket will be bound to a random free port.
    * 
-   * When a socket is not explicitly bound, the first invocation to a listen or connect operation will
-   * implicitly bind the socket.
+   * 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.
    * 
-   * Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
-   * 
-   * # Typical `start` errors
+   * # 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, but the socket has `ipv6-only` enabled. (EINVAL)
+   * - `invalid-argument`:          `local-address` is an IPv4-mapped IPv6 address. (EINVAL)
    * - `invalid-state`:             The socket is already bound. (EINVAL)
-   * 
-   * # Typical `finish` errors
    * - `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)
@@ -26,8 +24,14 @@ export namespace WasiSocketsTcp {
    * 
    * # 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 (i.e. the SO_REUSEADDR socket
-   * option should be set implicitly on platforms that require it).
+   * 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>
@@ -40,39 +44,40 @@ export namespace WasiSocketsTcp {
    * Connect to a remote endpoint.
    * 
    * On success:
-   * - the socket is transitioned into the Connection state
+   * - the socket is transitioned into the `connection` state.
    * - a pair of streams is returned that can be used to read & write to the connection
    * 
-   * POSIX mentions:
-   * > If connect() fails, the state of the socket is unspecified. Conforming applications should
-   * > close the file descriptor and create a new socket before attempting to reconnect.
-   * 
-   * WASI prescribes the following behavior:
-   * - If `connect` fails because an input/state validation error, the socket should remain usable.
-   * - If a connection was actually attempted but failed, the socket should become unusable for further network communication.
-   * Besides `drop`, any method after such a failure may return an error.
+   * 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 `start` errors
+   * # 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, but the socket has `ipv6-only` enabled. (EINVAL, EADDRNOTAVAIL on Illumos)
-   * - `invalid-argument`:          `remote-address` is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
+   * - `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 Connection state. (EISCONN)
-   * - `invalid-state`:             The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)
-   * 
-   * # Typical `finish` errors
+   * - `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.
+   * - `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>
@@ -82,22 +87,24 @@ export namespace WasiSocketsTcp {
   /**
    * Start listening for new connections.
    * 
-   * Transitions the socket into the Listener state.
+   * Transitions the socket into the `listening` state.
    * 
-   * Unlike POSIX:
-   * - this function is async. This enables interactive WASI hosts to inject permission prompts.
-   * - the socket must already be explicitly bound.
+   * Unlike POSIX, the socket must already be explicitly bound.
    * 
-   * # Typical `start` errors
+   * # Typical errors
    * - `invalid-state`:             The socket is not bound to any local address. (EDESTADDRREQ)
-   * - `invalid-state`:             The socket is already in the Connection state. (EISCONN, EINVAL on BSD)
-   * - `invalid-state`:             The socket is already in the Listener state.
-   * 
-   * # Typical `finish` 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)
-   * - `not-in-progress`:           A `listen` operation is not in progress.
+   * - `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>
@@ -107,9 +114,8 @@ export namespace WasiSocketsTcp {
   /**
    * Accept a new client socket.
    * 
-   * The returned socket is bound and in the Connection state. The following properties are inherited from the listener socket:
+   * The returned socket is bound and in the `connected` state. The following properties are inherited from the listener socket:
    * - `address-family`
-   * - `ipv6-only`
    * - `keep-alive-enabled`
    * - `keep-alive-idle-time`
    * - `keep-alive-interval`
@@ -122,7 +128,7 @@ export namespace WasiSocketsTcp {
    * a pair of streams that can be used to read & write to the connection.
    * 
    * # Typical errors
-   * - `invalid-state`:      Socket is not in the Listener state. (EINVAL)
+   * - `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)
@@ -164,7 +170,7 @@ export namespace WasiSocketsTcp {
    * - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
    */
   /**
-   * Whether the socket is listening for new connections.
+   * Whether the socket is in the `listening` state.
    * 
    * Equivalent to the SO_ACCEPTCONN socket option.
    */
@@ -173,16 +179,6 @@ export namespace WasiSocketsTcp {
    * 
    * Equivalent to the SO_DOMAIN socket option.
    */
-  /**
-   * Whether IPv4 compatibility (dual-stack) mode is disabled or not.
-   * 
-   * Equivalent to the IPV6_V6ONLY socket option.
-   * 
-   * # Typical errors
-   * - `invalid-state`:        (set) The socket is already bound.
-   * - `not-supported`:        (get/set) `this` socket is an IPv4 socket.
-   * - `not-supported`:        (set) Host does not support dual-stack sockets. (Implementations are not required to.)
-   */
   /**
    * Hints the desired listen queue size. Implementations are free to ignore this.
    * 
@@ -192,7 +188,7 @@ export namespace WasiSocketsTcp {
    * # 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 already in the Connection state.
+   * - `invalid-state`:        (set) The socket is in the `connect-in-progress` or `connected` state.
    */
   /**
    * Enables or disables keepalive.
@@ -248,8 +244,6 @@ export namespace WasiSocketsTcp {
    * 
    * # Typical errors
    * - `invalid-argument`:     (set) The TTL value must be 1 or higher.
-   * - `invalid-state`:        (set) The socket is already in the Connection state.
-   * - `invalid-state`:        (set) The socket is already in the Listener state.
    */
   /**
    * The kernel buffer space reserved for sends/receives on this socket.
@@ -262,11 +256,22 @@ export namespace WasiSocketsTcp {
    * 
    * # Typical errors
    * - `invalid-argument`:     (set) The provided value was 0.
-   * - `invalid-state`:        (set) The socket is already in the Connection state.
-   * - `invalid-state`:        (set) The socket is already in the Listener state.
    */
   /**
-   * Create a `pollable` which will resolve once the socket is ready for I/O.
+   * 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/TcpSocketOperationalSemantics.md#Pollable-readiness>
+   * for a more information.
    * 
    * Note: this function is here for WASI Preview2 only.
    * It's planned to be removed when `future` is natively supported in Preview3.
@@ -274,17 +279,21 @@ export namespace WasiSocketsTcp {
   /**
    * Initiate a graceful shutdown.
    * 
-   * - receive: the socket is not expecting to receive any more data from the peer. All subsequent read
-   * operations on the `input-stream` associated with this socket will return an End Of Stream indication.
-   * Any data still in the receive queue at time of calling `shutdown` will be discarded.
-   * - send: the socket is not expecting to send any more data to the peer. All subsequent write
-   * operations on the `output-stream` associated with this socket will return an error.
-   * - both: same effect as receive & send combined.
+   * - `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 a 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 Connection state. (ENOTCONN)
+   * - `invalid-state`: The socket is not in the `connected` state. (ENOTCONN)
    * 
    * # References
    * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html>
@@ -336,8 +345,6 @@ export class TcpSocket {
   remoteAddress(): IpSocketAddress;
   isListening(): boolean;
   addressFamily(): IpAddressFamily;
-  ipv6Only(): boolean;
-  setIpv6Only(value: boolean): void;
   setListenBacklogSize(value: bigint): void;
   keepAliveEnabled(): boolean;
   setKeepAliveEnabled(value: boolean): void;

package/types/interfaces/wasi-sockets-udp-create-socket.d.ts

@@ -3,6 +3,7 @@ export namespace WasiSocketsUdpCreateSocket {
    * Create a new UDP socket.
    * 
    * Similar to `socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP)` in POSIX.
+   * On IPv6 sockets, IPV6_V6ONLY is enabled by default and can't be configured otherwise.
    * 
    * This function does not require a network capability handle. This is considered to be safe because
    * at time of creation, the socket is not bound to any `network` yet. Up to the moment `bind` is called,

package/types/interfaces/wasi-sockets-udp.d.ts

@@ -6,19 +6,21 @@ export namespace WasiSocketsUdp {
    * network interface(s) to bind to.
    * If the port is zero, the socket will be bound to a random free port.
    * 
-   * Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
-   * 
-   * # Typical `start` errors
+   * # Typical errors
    * - `invalid-argument`:          The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
    * - `invalid-state`:             The socket is already bound. (EINVAL)
-   * 
-   * # Typical `finish` errors
    * - `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
+   * 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>
@@ -55,7 +57,6 @@ export namespace WasiSocketsUdp {
        * 
        * # Typical errors
        * - `invalid-argument`:          The `remote-address` has the wrong address family. (EAFNOSUPPORT)
-       * - `invalid-argument`:          `remote-address` is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
        * - `invalid-argument`:          The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
        * - `invalid-argument`:          The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
        * - `invalid-state`:             The socket is not bound.
@@ -104,16 +105,6 @@ export namespace WasiSocketsUdp {
        * 
        * Equivalent to the SO_DOMAIN socket option.
        */
-      /**
-       * Whether IPv4 compatibility (dual-stack) mode is disabled or not.
-       * 
-       * Equivalent to the IPV6_V6ONLY socket option.
-       * 
-       * # Typical errors
-       * - `not-supported`:        (get/set) `this` socket is an IPv4 socket.
-       * - `invalid-state`:        (set) The socket is already bound.
-       * - `not-supported`:        (set) Host does not support dual-stack sockets. (Implementations are not required to.)
-       */
       /**
        * Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
        * 
@@ -204,7 +195,6 @@ export namespace WasiSocketsUdp {
        * 
        * # Typical errors
        * - `invalid-argument`:        The `remote-address` has the wrong address family. (EAFNOSUPPORT)
-       * - `invalid-argument`:        `remote-address` is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
        * - `invalid-argument`:        The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
        * - `invalid-argument`:        The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
        * - `invalid-argument`:        The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `stream`. (EISCONN)
@@ -279,6 +269,17 @@ export namespace WasiSocketsUdp {
       remoteAddress?: IpSocketAddress,
     }
     
+    export class IncomingDatagramStream {
+      receive(maxResults: bigint): IncomingDatagram[];
+      subscribe(): Pollable;
+    }
+    
+    export class OutgoingDatagramStream {
+      checkSend(): bigint;
+      send(datagrams: OutgoingDatagram[]): bigint;
+      subscribe(): Pollable;
+    }
+    
     export class UdpSocket {
       startBind(network: Network, localAddress: IpSocketAddress): void;
       finishBind(): void;
@@ -286,8 +287,6 @@ export namespace WasiSocketsUdp {
       localAddress(): IpSocketAddress;
       remoteAddress(): IpSocketAddress;
       addressFamily(): IpAddressFamily;
-      ipv6Only(): boolean;
-      setIpv6Only(value: boolean): void;
       unicastHopLimit(): number;
       setUnicastHopLimit(value: number): void;
       receiveBufferSize(): bigint;
@@ -296,15 +295,4 @@ export namespace WasiSocketsUdp {
       setSendBufferSize(value: bigint): void;
       subscribe(): Pollable;
     }
-    
-    export class IncomingDatagramStream {
-      receive(maxResults: bigint): IncomingDatagram[];
-      subscribe(): Pollable;
-    }
-    
-    export class OutgoingDatagramStream {
-      checkSend(): bigint;
-      send(datagrams: OutgoingDatagram[]): bigint;
-      subscribe(): Pollable;
-    }
     

package/types/io.d.ts

@@ -0,0 +1,7 @@
+import type { WasiIoError } from './interfaces/wasi-io-error.d.ts';
+import type { WasiIoPoll } from './interfaces/wasi-io-poll.d.ts';
+import type { WasiIoStreams } from './interfaces/wasi-io-streams.d.ts';
+
+export const error: typeof WasiIoError;
+export const poll: typeof WasiIoPoll;
+export const streams: typeof WasiIoStreams;

package/types/random.d.ts

@@ -0,0 +1,7 @@
+import type { WasiRandomInsecureSeed } from './interfaces/wasi-random-insecure-seed.d.ts';
+import type { WasiRandomInsecure } from './interfaces/wasi-random-insecure.d.ts';
+import type { WasiRandomRandom } from './interfaces/wasi-random-random.d.ts';
+
+export const insecureSeed: typeof WasiRandomInsecureSeed;
+export const insecure: typeof WasiRandomInsecure;
+export const random: typeof WasiRandomRandom;

package/types/sockets.d.ts

@@ -0,0 +1,15 @@
+import type { WasiSocketsInstanceNetwork } from './interfaces/wasi-sockets-instance-network.d.ts';
+import type { WasiSocketsIpNameLookup } from './interfaces/wasi-sockets-ip-name-lookup.d.ts';
+import type { WasiSocketsNetwork } from './interfaces/wasi-sockets-network.d.ts';
+import type { WasiSocketsTcpCreateSocket } from './interfaces/wasi-sockets-tcp-create-socket.d.ts';
+import type { WasiSocketsTcp } from './interfaces/wasi-sockets-tcp.d.ts';
+import type { WasiSocketsUdpCreateSocket } from './interfaces/wasi-sockets-udp-create-socket.d.ts';
+import type { WasiSocketsUdp } from './interfaces/wasi-sockets-udp.d.ts';
+
+export const instanceNetwork: typeof WasiSocketsInstanceNetwork;
+export const ipNameLookup: typeof WasiSocketsIpNameLookup;
+export const network: typeof WasiSocketsNetwork;
+export const tcpCreateSocket: typeof WasiSocketsTcpCreateSocket;
+export const tcp: typeof WasiSocketsTcp;
+export const udpCreateSocket: typeof WasiSocketsUdpCreateSocket;
+export const udp: typeof WasiSocketsUdp;