@bytecodealliance/preview2-shim 0.0.13 → 0.0.14

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

@@ -0,0 +1,228 @@
+export namespace WasiSocketsUdp {
+  /**
+   * 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.
+   * 
+   * When a socket is not explicitly bound, the first invocation to connect will implicitly bind the socket.
+   * 
+   * Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
+   * 
+   * # Typical `start` errors
+   * - `address-family-mismatch`:   The `local-address` has the wrong address family. (EINVAL)
+   * - `already-bound`:             The socket is already bound. (EINVAL)
+   * - `concurrency-conflict`:      Another `bind` or `connect` operation is already in progress. (EALREADY)
+   * 
+   * # Typical `finish` errors
+   * - `ephemeral-ports-exhausted`: 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)
+   * 
+   * # 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>
+   */
+  export function startBind(this_: UdpSocket, network: Network, localAddress: IpSocketAddress): void;
+  export function finishBind(this_: UdpSocket): void;
+  /**
+   * Set the destination address.
+   * 
+   * The local-address is updated based on the best network path to `remote-address`.
+   * 
+   * When a destination address is set:
+   * - all receive operations will only return datagrams sent from the provided `remote-address`.
+   * - the `send` function can only be used to send to this destination.
+   * 
+   * Note that this function does not generate any network traffic and the peer is not aware of this "connection".
+   * 
+   * Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
+   * 
+   * # Typical `start` errors
+   * - `address-family-mismatch`:   The `remote-address` has the wrong address family. (EAFNOSUPPORT)
+   * - `invalid-remote-address`:    The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
+   * - `invalid-remote-address`:    The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
+   * - `already-attached`:          The socket is already bound to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
+   * - `concurrency-conflict`:      Another `bind` or `connect` operation is already in progress. (EALREADY)
+   * 
+   * # Typical `finish` errors
+   * - `ephemeral-ports-exhausted`: 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)
+   * 
+   * # 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>
+   */
+  export function startConnect(this_: UdpSocket, network: Network, remoteAddress: IpSocketAddress): void;
+  export function finishConnect(this_: UdpSocket): void;
+  /**
+   * Receive messages on the socket.
+   * 
+   * This function attempts to receive up to `max-results` datagrams on the socket without blocking.
+   * The returned list may contain fewer elements than requested, but never more.
+   * If `max-results` is 0, this function returns successfully with an empty list.
+   * 
+   * # Typical errors
+   * - `not-bound`:          The socket is not bound to any local address. (EINVAL)
+   * - `remote-unreachable`: The remote address is not reachable. (ECONNREFUSED, ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)
+   * - `would-block`:        There is no pending data available to be read at the moment. (EWOULDBLOCK, EAGAIN)
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html>
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvmsg.html>
+   * - <https://man7.org/linux/man-pages/man2/recv.2.html>
+   * - <https://man7.org/linux/man-pages/man2/recvmmsg.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recv>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom>
+   * - <https://learn.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms741687(v=vs.85)>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2>
+   */
+  export function receive(this_: UdpSocket, maxResults: bigint): Datagram[];
+  /**
+   * Send messages on the socket.
+   * 
+   * This function attempts to send all provided `datagrams` on the socket without blocking and
+   * returns how many messages were actually sent (or queued for sending).
+   * 
+   * This function semantically behaves the same as iterating the `datagrams` list and sequentially
+   * sending each individual datagram until either the end of the list has been reached or the first error occurred.
+   * If at least one datagram has been sent successfully, this function never returns an error.
+   * 
+   * If the input list is empty, the function returns `ok(0)`.
+   * 
+   * The remote address option is required. To send a message to the "connected" peer,
+   * call `remote-address` to get their address.
+   * 
+   * # Typical errors
+   * - `address-family-mismatch`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
+   * - `invalid-remote-address`:  The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
+   * - `invalid-remote-address`:  The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
+   * - `already-connected`:       The socket is in "connected" mode and the `datagram.remote-address` does not match the address passed to `connect`. (EISCONN)
+   * - `not-bound`:               The socket is not bound to any local address. Unlike POSIX, this function does not perform an implicit bind.
+   * - `remote-unreachable`:      The remote address is not reachable. (ECONNREFUSED, ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN)
+   * - `datagram-too-large`:      The datagram is too large. (EMSGSIZE)
+   * - `would-block`:             The send buffer is currently full. (EWOULDBLOCK, EAGAIN)
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html>
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html>
+   * - <https://man7.org/linux/man-pages/man2/send.2.html>
+   * - <https://man7.org/linux/man-pages/man2/sendmmsg.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-sendto>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2>
+   */
+  export function send(this_: UdpSocket, datagrams: Datagram[]): bigint;
+  /**
+   * Get the current bound address.
+   * 
+   * # Typical errors
+   * - `not-bound`: 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>
+   */
+  export function localAddress(this_: UdpSocket): IpSocketAddress;
+  /**
+   * Get the address set with `connect`.
+   * 
+   * # Typical errors
+   * - `not-connected`: 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>
+   */
+  export function remoteAddress(this_: UdpSocket): IpSocketAddress;
+  /**
+   * Whether this is a IPv4 or IPv6 socket.
+   * 
+   * Equivalent to the SO_DOMAIN socket option.
+   */
+  export function addressFamily(this_: UdpSocket): IpAddressFamily;
+  /**
+   * Whether IPv4 compatibility (dual-stack) mode is disabled or not.
+   * 
+   * Equivalent to the IPV6_V6ONLY socket option.
+   * 
+   * # Typical errors
+   * - `ipv6-only-operation`:  (get/set) `this` socket is an IPv4 socket.
+   * - `already-bound`:        (set) The socket is already bound.
+   * - `not-supported`:        (set) Host does not support dual-stack sockets. (Implementations are not required to.)
+   * - `concurrency-conflict`: (set) Another `bind` or `connect` operation is already in progress. (EALREADY)
+   */
+  export function ipv6Only(this_: UdpSocket): boolean;
+  export function setIpv6Only(this_: UdpSocket, value: boolean): void;
+  /**
+   * Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
+   * 
+   * # Typical errors
+   * - `concurrency-conflict`: (set) Another `bind` or `connect` operation is already in progress. (EALREADY)
+   */
+  export function unicastHopLimit(this_: UdpSocket): number;
+  export function setUnicastHopLimit(this_: UdpSocket, value: number): void;
+  /**
+   * The kernel buffer space reserved for sends/receives on this socket.
+   * 
+   * Note #1: an implementation may choose to cap or round the buffer size when setting the value.
+   * In other words, after setting a value, reading the same setting back may return a different value.
+   * 
+   * Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of
+   * actual data to be sent/received by the application, because the kernel might also use the buffer space
+   * for internal metadata structures.
+   * 
+   * Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
+   * 
+   * # Typical errors
+   * - `concurrency-conflict`: (set) Another `bind` or `connect` operation is already in progress. (EALREADY)
+   */
+  export function receiveBufferSize(this_: UdpSocket): bigint;
+  export function setReceiveBufferSize(this_: UdpSocket, value: bigint): void;
+  export function sendBufferSize(this_: UdpSocket): bigint;
+  export function setSendBufferSize(this_: UdpSocket, value: bigint): void;
+  /**
+   * Create a `pollable` which will resolve once the socket is ready for I/O.
+   * 
+   * Note: this function is here for WASI Preview2 only.
+   * It's planned to be removed when `future` is natively supported in Preview3.
+   */
+  export function subscribe(this_: UdpSocket): Pollable;
+  /**
+   * Dispose of the specified `udp-socket`, after which it may no longer be used.
+   * 
+   * Note: this function is scheduled to be removed when Resources are natively supported in Wit.
+   */
+  export function dropUdpSocket(this_: UdpSocket): void;
+}
+import type { Pollable } from '../exports/wasi-poll-poll';
+export { Pollable };
+import type { Network } from '../exports/wasi-sockets-network';
+export { Network };
+import type { ErrorCode } from '../exports/wasi-sockets-network';
+export { ErrorCode };
+import type { IpSocketAddress } from '../exports/wasi-sockets-network';
+export { IpSocketAddress };
+import type { IpAddressFamily } from '../exports/wasi-sockets-network';
+export { IpAddressFamily };
+/**
+ * A UDP socket handle.
+ */
+export type UdpSocket = number;
+export interface Datagram {
+  data: Uint8Array,
+  remoteAddress: IpSocketAddress,
+}

package/types/imports/wasi-cli-environment.d.ts

@@ -0,0 +1,22 @@
+export namespace WasiCliEnvironment {
+  /**
+   * Get the POSIX-style environment variables.
+   * 
+   * Each environment variable is provided as a pair of string variable names
+   * and string value.
+   * 
+   * Morally, these are a value import, but until value imports are available
+   * in the component model, this import function should return the same
+   * values each time it is called.
+   */
+  export function getEnvironment(): [string, string][];
+  /**
+   * Get the POSIX-style arguments to the program.
+   */
+  export function getArguments(): string[];
+  /**
+   * Return a path that programs should use as their initial current working
+   * directory, interpreting `.` as shorthand for this.
+   */
+  export function initialCwd(): string | null;
+}

package/types/imports/wasi-cli-exit.d.ts

@@ -0,0 +1,7 @@
+export namespace WasiCliExit {
+  /**
+   * Exit the current instance and any linked instances.
+   */
+  export function exit(status: Result<void, void>): void;
+}
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/types/imports/wasi-cli-stderr.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliStderr {
+  export function getStderr(): OutputStream;
+}
+import type { OutputStream } from '../imports/wasi-io-streams';
+export { OutputStream };

package/types/imports/wasi-cli-stdin.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliStdin {
+  export function getStdin(): InputStream;
+}
+import type { InputStream } from '../imports/wasi-io-streams';
+export { InputStream };

package/types/imports/wasi-cli-stdout.d.ts

@@ -0,0 +1,5 @@
+export namespace WasiCliStdout {
+  export function getStdout(): OutputStream;
+}
+import type { OutputStream } from '../imports/wasi-io-streams';
+export { OutputStream };

package/types/imports/wasi-cli-terminal-input.d.ts

@@ -0,0 +1,13 @@
+export namespace WasiCliTerminalInput {
+  /**
+   * Dispose of the specified terminal-input after which it may no longer
+   * be used.
+   */
+  export function dropTerminalInput(this_: TerminalInput): void;
+}
+/**
+ * The input side of a terminal.
+ * 
+ * This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
+ */
+export type TerminalInput = number;

package/types/imports/wasi-cli-terminal-output.d.ts

@@ -0,0 +1,13 @@
+export namespace WasiCliTerminalOutput {
+  /**
+   * Dispose of the specified terminal-output, after which it may no longer
+   * be used.
+   */
+  export function dropTerminalOutput(this_: TerminalOutput): void;
+}
+/**
+ * The output side of a terminal.
+ * 
+ * This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
+ */
+export type TerminalOutput = number;

package/types/imports/wasi-cli-terminal-stderr.d.ts

@@ -0,0 +1,9 @@
+export namespace WasiCliTerminalStderr {
+  /**
+   * If stderr is connected to a terminal, return a `terminal-output` handle
+   * allowing further interaction with it.
+   */
+  export function getTerminalStderr(): TerminalOutput | null;
+}
+import type { TerminalOutput } from '../imports/wasi-cli-terminal-output';
+export { TerminalOutput };

package/types/imports/wasi-cli-terminal-stdin.d.ts

@@ -0,0 +1,9 @@
+export namespace WasiCliTerminalStdin {
+  /**
+   * If stdin is connected to a terminal, return a `terminal-input` handle
+   * allowing further interaction with it.
+   */
+  export function getTerminalStdin(): TerminalInput | null;
+}
+import type { TerminalInput } from '../imports/wasi-cli-terminal-input';
+export { TerminalInput };

package/types/imports/wasi-cli-terminal-stdout.d.ts

@@ -0,0 +1,9 @@
+export namespace WasiCliTerminalStdout {
+  /**
+   * If stdout is connected to a terminal, return a `terminal-output` handle
+   * allowing further interaction with it.
+   */
+  export function getTerminalStdout(): TerminalOutput | null;
+}
+import type { TerminalOutput } from '../imports/wasi-cli-terminal-output';
+export { TerminalOutput };

package/types/imports/wasi-clocks-monotonic-clock.d.ts

@@ -0,0 +1,24 @@
+export namespace WasiClocksMonotonicClock {
+  /**
+   * Read the current value of the clock.
+   * 
+   * The clock is monotonic, therefore calling this function repeatedly will
+   * produce a sequence of non-decreasing values.
+   */
+  export function now(): Instant;
+  /**
+   * Query the resolution of the clock.
+   */
+  export function resolution(): Instant;
+  /**
+   * Create a `pollable` which will resolve once the specified time has been
+   * reached.
+   */
+  export function subscribe(when: Instant, absolute: boolean): Pollable;
+}
+import type { Pollable } from '../imports/wasi-poll-poll';
+export { Pollable };
+/**
+ * A timestamp in nanoseconds.
+ */
+export type Instant = bigint;

package/types/imports/wasi-clocks-timezone.d.ts

@@ -0,0 +1,71 @@
+export namespace WasiClocksTimezone {
+  /**
+   * Return information needed to display the given `datetime`. This includes
+   * the UTC offset, the time zone name, and a flag indicating whether
+   * daylight saving time is active.
+   * 
+   * If the timezone cannot be determined for the given `datetime`, return a
+   * `timezone-display` for `UTC` with a `utc-offset` of 0 and no daylight
+   * saving time.
+   */
+  export function display(this_: Timezone, when: Datetime): TimezoneDisplay;
+  /**
+   * The same as `display`, but only return the UTC offset.
+   */
+  export function utcOffset(this_: Timezone, when: Datetime): number;
+  /**
+   * Dispose of the specified input-stream, after which it may no longer
+   * be used.
+   */
+  export function dropTimezone(this_: Timezone): void;
+}
+import type { Datetime } from '../imports/wasi-clocks-wall-clock';
+export { Datetime };
+/**
+ * A timezone.
+ * 
+ * In timezones that recognize daylight saving time, also known as daylight
+ * time and summer time, the information returned from the functions varies
+ * over time to reflect these adjustments.
+ * 
+ * This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
+ */
+export type Timezone = number;
+/**
+ * Information useful for displaying the timezone of a specific `datetime`.
+ * 
+ * This information may vary within a single `timezone` to reflect daylight
+ * saving time adjustments.
+ */
+export interface TimezoneDisplay {
+  /**
+   * The number of seconds difference between UTC time and the local
+   * time of the timezone.
+   * 
+   * The returned value will always be less than 86400 which is the
+   * number of seconds in a day (24*60*60).
+   * 
+   * In implementations that do not expose an actual time zone, this
+   * should return 0.
+   */
+  utcOffset: number,
+  /**
+   * The abbreviated name of the timezone to display to a user. The name
+   * `UTC` indicates Coordinated Universal Time. Otherwise, this should
+   * reference local standards for the name of the time zone.
+   * 
+   * In implementations that do not expose an actual time zone, this
+   * should be the string `UTC`.
+   * 
+   * In time zones that do not have an applicable name, a formatted
+   * representation of the UTC offset may be returned, such as `-04:00`.
+   */
+  name: string,
+  /**
+   * Whether daylight saving time is active.
+   * 
+   * In implementations that do not expose an actual time zone, this
+   * should return false.
+   */
+  inDaylightSavingTime: boolean,
+}

package/types/imports/wasi-clocks-wall-clock.d.ts

@@ -0,0 +1,31 @@
+export namespace WasiClocksWallClock {
+  /**
+   * Read the current value of the clock.
+   * 
+   * This clock is not monotonic, therefore calling this function repeatedly
+   * will not necessarily produce a sequence of non-decreasing values.
+   * 
+   * The returned timestamps represent the number of seconds since
+   * 1970-01-01T00:00:00Z, also known as [POSIX's Seconds Since the Epoch],
+   * also known as [Unix Time].
+   * 
+   * The nanoseconds field of the output is always less than 1000000000.
+   * 
+   * [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16
+   * [Unix Time]: https://en.wikipedia.org/wiki/Unix_time
+   */
+  export function now(): Datetime;
+  /**
+   * Query the resolution of the clock.
+   * 
+   * The nanoseconds field of the output is always less than 1000000000.
+   */
+  export function resolution(): Datetime;
+}
+/**
+ * A time and date in seconds plus nanoseconds.
+ */
+export interface Datetime {
+  seconds: bigint,
+  nanoseconds: number,
+}

package/types/imports/wasi-filesystem-preopens.d.ts

@@ -0,0 +1,8 @@
+export namespace WasiFilesystemPreopens {
+  /**
+   * Return the set of preopened directories, and their path.
+   */
+  export function getDirectories(): [Descriptor, string][];
+}
+import type { Descriptor } from '../imports/wasi-filesystem-types';
+export { Descriptor };