@bytecodealliance/preview2-shim 0.0.13 → 0.0.14

package/types/exports/wasi-http-incoming-handler.d.ts

@@ -0,0 +1,7 @@
+export namespace WasiHttpIncomingHandler {
+  export function handle(request: IncomingRequest, responseOut: ResponseOutparam): void;
+}
+import type { IncomingRequest } from '../exports/wasi-http-types';
+export { IncomingRequest };
+import type { ResponseOutparam } from '../exports/wasi-http-types';
+export { ResponseOutparam };

package/types/exports/wasi-http-outgoing-handler.d.ts

@@ -0,0 +1,9 @@
+export namespace WasiHttpOutgoingHandler {
+  export function handle(request: OutgoingRequest, options: RequestOptions | null): FutureIncomingResponse;
+}
+import type { OutgoingRequest } from '../exports/wasi-http-types';
+export { OutgoingRequest };
+import type { RequestOptions } from '../exports/wasi-http-types';
+export { RequestOptions };
+import type { FutureIncomingResponse } from '../exports/wasi-http-types';
+export { FutureIncomingResponse };

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

@@ -0,0 +1,118 @@
+export namespace WasiHttpTypes {
+  export function dropFields(fields: Fields): void;
+  export function newFields(entries: [string, string][]): Fields;
+  export function fieldsGet(fields: Fields, name: string): Uint8Array[];
+  export function fieldsSet(fields: Fields, name: string, value: Uint8Array | ArrayBuffer[]): void;
+  export function fieldsDelete(fields: Fields, name: string): void;
+  export function fieldsAppend(fields: Fields, name: string, value: Uint8Array | ArrayBuffer): void;
+  export function fieldsEntries(fields: Fields): [string, Uint8Array][];
+  export function fieldsClone(fields: Fields): Fields;
+  export function finishIncomingStream(s: IncomingStream): Trailers | null;
+  export function finishOutgoingStream(s: OutgoingStream, trailers: Trailers | null): void;
+  export function dropIncomingRequest(request: IncomingRequest): void;
+  export function dropOutgoingRequest(request: OutgoingRequest): void;
+  export function incomingRequestMethod(request: IncomingRequest): Method;
+  export function incomingRequestPathWithQuery(request: IncomingRequest): string | null;
+  export function incomingRequestScheme(request: IncomingRequest): Scheme | null;
+  export function incomingRequestAuthority(request: IncomingRequest): string | null;
+  export function incomingRequestHeaders(request: IncomingRequest): Headers;
+  export function incomingRequestConsume(request: IncomingRequest): IncomingStream;
+  export function newOutgoingRequest(method: Method, pathWithQuery: string | null, scheme: Scheme | null, authority: string | null, headers: Headers): OutgoingRequest;
+  export function outgoingRequestWrite(request: OutgoingRequest): OutgoingStream;
+  export function dropResponseOutparam(response: ResponseOutparam): void;
+  export function setResponseOutparam(param: ResponseOutparam, response: Result<OutgoingResponse, Error>): void;
+  export function dropIncomingResponse(response: IncomingResponse): void;
+  export function dropOutgoingResponse(response: OutgoingResponse): void;
+  export function incomingResponseStatus(response: IncomingResponse): StatusCode;
+  export function incomingResponseHeaders(response: IncomingResponse): Headers;
+  export function incomingResponseConsume(response: IncomingResponse): IncomingStream;
+  export function newOutgoingResponse(statusCode: StatusCode, headers: Headers): OutgoingResponse;
+  export function outgoingResponseWrite(response: OutgoingResponse): OutgoingStream;
+  export function dropFutureIncomingResponse(f: FutureIncomingResponse): void;
+  export function futureIncomingResponseGet(f: FutureIncomingResponse): Result<IncomingResponse, Error> | null;
+  export function listenToFutureIncomingResponse(f: FutureIncomingResponse): Pollable;
+}
+import type { InputStream } from '../exports/wasi-io-streams';
+export { InputStream };
+import type { OutputStream } from '../exports/wasi-io-streams';
+export { OutputStream };
+import type { Pollable } from '../exports/wasi-poll-poll';
+export { Pollable };
+export type Method = MethodGet | MethodHead | MethodPost | MethodPut | MethodDelete | MethodConnect | MethodOptions | MethodTrace | MethodPatch | MethodOther;
+export interface MethodGet {
+  tag: 'get',
+}
+export interface MethodHead {
+  tag: 'head',
+}
+export interface MethodPost {
+  tag: 'post',
+}
+export interface MethodPut {
+  tag: 'put',
+}
+export interface MethodDelete {
+  tag: 'delete',
+}
+export interface MethodConnect {
+  tag: 'connect',
+}
+export interface MethodOptions {
+  tag: 'options',
+}
+export interface MethodTrace {
+  tag: 'trace',
+}
+export interface MethodPatch {
+  tag: 'patch',
+}
+export interface MethodOther {
+  tag: 'other',
+  val: string,
+}
+export type Scheme = SchemeHttp | SchemeHttps | SchemeOther;
+export interface SchemeHttp {
+  tag: 'HTTP',
+}
+export interface SchemeHttps {
+  tag: 'HTTPS',
+}
+export interface SchemeOther {
+  tag: 'other',
+  val: string,
+}
+export type Error = ErrorInvalidUrl | ErrorTimeoutError | ErrorProtocolError | ErrorUnexpectedError;
+export interface ErrorInvalidUrl {
+  tag: 'invalid-url',
+  val: string,
+}
+export interface ErrorTimeoutError {
+  tag: 'timeout-error',
+  val: string,
+}
+export interface ErrorProtocolError {
+  tag: 'protocol-error',
+  val: string,
+}
+export interface ErrorUnexpectedError {
+  tag: 'unexpected-error',
+  val: string,
+}
+export type Fields = number;
+export type Headers = Fields;
+export type Trailers = Fields;
+export type IncomingStream = InputStream;
+export type OutgoingStream = OutputStream;
+export type IncomingRequest = number;
+export type OutgoingRequest = number;
+export interface RequestOptions {
+  connectTimeoutMs?: number,
+  firstByteTimeoutMs?: number,
+  betweenBytesTimeoutMs?: number,
+}
+export type ResponseOutparam = number;
+export type StatusCode = number;
+export type IncomingResponse = number;
+export type OutgoingResponse = number;
+export type FutureIncomingResponse = number;
+export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

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

@@ -0,0 +1,220 @@
+export namespace WasiIoStreams {
+  /**
+   * Perform a non-blocking read from the stream.
+   * 
+   * This function returns a list of bytes containing the data that was
+   * read, along with a `stream-status` which, indicates whether further
+   * reads are expected to produce data. The returned list will contain up to
+   * `len` bytes; it may return fewer than requested, but not more. An
+   * empty list and `stream-status:open` indicates no more data is
+   * available at this time, and that the pollable given by
+   * `subscribe-to-input-stream` will be ready when more data is available.
+   * 
+   * Once a stream has reached the end, subsequent calls to `read` or
+   * `skip` will always report `stream-status:ended` rather than producing more
+   * data.
+   * 
+   * When the caller gives a `len` of 0, it represents a request to read 0
+   * bytes. This read should  always succeed and return an empty list and
+   * the current `stream-status`.
+   * 
+   * 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.
+   */
+  export function read(this_: InputStream, len: bigint): [Uint8Array, StreamStatus];
+  /**
+   * Read bytes from a stream, after blocking until at least one byte can
+   * be read. Except for blocking, identical to `read`.
+   */
+  export function blockingRead(this_: InputStream, len: bigint): [Uint8Array, StreamStatus];
+  /**
+   * Skip bytes from a stream.
+   * 
+   * This is similar to the `read` function, but avoids copying the
+   * bytes into the instance.
+   * 
+   * Once a stream has reached the end, subsequent calls to read or
+   * `skip` will always report end-of-stream rather than producing more
+   * data.
+   * 
+   * This function returns the number of bytes skipped, along with a
+   * `stream-status` indicating whether the end of the stream was
+   * reached. The returned value will be at most `len`; it may be less.
+   */
+  export function skip(this_: InputStream, len: bigint): [bigint, StreamStatus];
+  /**
+   * Skip bytes from a stream, after blocking until at least one byte
+   * can be skipped. Except for blocking behavior, identical to `skip`.
+   */
+  export function blockingSkip(this_: InputStream, len: bigint): [bigint, StreamStatus];
+  /**
+   * 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 `pollable`s created with this function are dropped.
+   */
+  export function subscribeToInputStream(this_: InputStream): Pollable;
+  /**
+   * Dispose of the specified `input-stream`, after which it may no longer
+   * be used.
+   * Implementations may trap if this `input-stream` is dropped while child
+   * `pollable` resources are still alive.
+   * After this `input-stream` is dropped, implementations may report any
+   * corresponding `output-stream` has `stream-state.closed`.
+   */
+  export function dropInputStream(this_: InputStream): void;
+  /**
+   * Perform a non-blocking write of bytes to a stream.
+   * 
+   * This function returns a `u64` and a `stream-status`. The `u64` indicates
+   * the number of bytes from `buf` that were written, which may be less than
+   * the length of `buf`. The `stream-status` indicates if further writes to
+   * the stream are expected to be read.
+   * 
+   * When the returned `stream-status` is `open`, the `u64` return value may
+   * be less than the length of `buf`. This indicates that no more bytes may
+   * be written to the stream promptly. In that case the
+   * `subscribe-to-output-stream` pollable will indicate when additional bytes
+   * may be promptly written.
+   * 
+   * Writing an empty list must return a non-error result with `0` for the
+   * `u64` return value, and the current `stream-status`.
+   */
+  export function write(this_: OutputStream, buf: Uint8Array | ArrayBuffer): [bigint, StreamStatus];
+  /**
+   * Blocking write of bytes to a stream.
+   * 
+   * This is similar to `write`, except that it blocks until at least one
+   * byte can be written.
+   */
+  export function blockingWrite(this_: OutputStream, buf: Uint8Array | ArrayBuffer): [bigint, StreamStatus];
+  /**
+   * Write multiple zero-bytes to a stream.
+   * 
+   * This function returns a `u64` indicating the number of zero-bytes
+   * that were written; it may be less than `len`. Equivelant to a call to
+   * `write` with a list of zeroes of the given length.
+   */
+  export function writeZeroes(this_: OutputStream, len: bigint): [bigint, StreamStatus];
+  /**
+   * Write multiple zero bytes to a stream, with blocking.
+   * 
+   * This is similar to `write-zeroes`, except that it blocks until at least
+   * one byte can be written. Equivelant to a call to `blocking-write` with
+   * a list of zeroes of the given length.
+   */
+  export function blockingWriteZeroes(this_: OutputStream, len: bigint): [bigint, StreamStatus];
+  /**
+   * Read from one stream and write to another.
+   * 
+   * This function returns the number of bytes transferred; it may be less
+   * than `len`.
+   * 
+   * Unlike other I/O functions, this function blocks until all the data
+   * read from the input stream has been written to the output stream.
+   */
+  export function splice(this_: OutputStream, src: InputStream, len: bigint): [bigint, StreamStatus];
+  /**
+   * Read from one stream and write to another, with blocking.
+   * 
+   * This is similar to `splice`, except that it blocks until at least
+   * one byte can be read.
+   */
+  export function blockingSplice(this_: OutputStream, src: InputStream, len: bigint): [bigint, StreamStatus];
+  /**
+   * Forward the entire contents of an input stream to an output stream.
+   * 
+   * This function repeatedly reads from the input stream and writes
+   * the data to the output stream, until the end of the input stream
+   * is reached, or an error is encountered.
+   * 
+   * Unlike other I/O functions, this function blocks until the end
+   * of the input stream is seen and all the data has been written to
+   * the output stream.
+   * 
+   * This function returns the number of bytes transferred, and the status of
+   * the output stream.
+   */
+  export function forward(this_: OutputStream, src: InputStream): [bigint, StreamStatus];
+  /**
+   * Create a `pollable` which will resolve once either the specified stream
+   * is ready to accept bytes or the `stream-state` has become closed.
+   * 
+   * Once the stream-state 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 `pollable`s created with this function are dropped.
+   */
+  export function subscribeToOutputStream(this_: OutputStream): Pollable;
+  /**
+   * Dispose of the specified `output-stream`, after which it may no longer
+   * be used.
+   * Implementations may trap if this `output-stream` is dropped while
+   * child `pollable` resources are still alive.
+   * After this `output-stream` is dropped, implementations may report any
+   * corresponding `input-stream` has `stream-state.closed`.
+   */
+  export function dropOutputStream(this_: OutputStream): void;
+}
+import type { Pollable } from '../exports/wasi-poll-poll';
+export { Pollable };
+/**
+ * Streams provide a sequence of data and then end; once they end, they
+ * no longer provide any further data.
+ * 
+ * For example, a stream reading from a file ends when the stream reaches
+ * the end of the file. For another example, a stream reading from a
+ * socket ends when the socket is closed.
+ * # Variants
+ * 
+ * ## `"open"`
+ * 
+ * The stream is open and may produce further data.
+ * ## `"ended"`
+ * 
+ * When reading, this indicates that the stream will not produce
+ * further data.
+ * When writing, this indicates that the stream will no longer be read.
+ * Further writes are still permitted.
+ */
+export type StreamStatus = 'open' | 'ended';
+/**
+ * An input bytestream. In the future, this will be replaced by handle
+ * types.
+ * 
+ * `input-stream`s are *non-blocking* to the extent practical on underlying
+ * platforms. I/O operations always return promptly; if fewer bytes are
+ * promptly available than requested, they return the number of bytes promptly
+ * available, which could even be zero. To wait for data to be available,
+ * use the `subscribe-to-input-stream` function to obtain a `pollable` which
+ * can be polled for using `wasi:poll/poll.poll_oneoff`.
+ * 
+ * And at present, it is a `u32` instead of being an actual handle, until
+ * the wit-bindgen implementation of handles and resources is ready.
+ * 
+ * This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
+ */
+export type InputStream = number;
+/**
+ * An output bytestream. In the future, this will be replaced by handle
+ * types.
+ * 
+ * `output-stream`s are *non-blocking* to the extent practical on
+ * underlying platforms. Except where specified otherwise, I/O operations also
+ * always return promptly, after the number of bytes that can be written
+ * promptly, which could even be zero. To wait for the stream to be ready to
+ * accept data, the `subscribe-to-output-stream` function to obtain a
+ * `pollable` which can be polled for using `wasi:poll`.
+ * 
+ * And at present, it is a `u32` instead of being an actual handle, until
+ * the wit-bindgen implementation of handles and resources is ready.
+ * 
+ * This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
+ */
+export type OutputStream = number;

package/types/exports/wasi-poll-poll.d.ts

@@ -0,0 +1,39 @@
+export namespace WasiPollPoll {
+  /**
+   * Dispose of the specified `pollable`, after which it may no longer
+   * be used.
+   */
+  export function dropPollable(this_: Pollable): void;
+  /**
+   * Poll for completion on a set of pollables.
+   * 
+   * The "oneoff" in the name refers to the fact that this function must do a
+   * linear scan through the entire list of subscriptions, which may be
+   * inefficient if the number is large and the same subscriptions are used
+   * many times. In the future, this is expected to be obsoleted by the
+   * component model async proposal, which will include a scalable waiting
+   * facility.
+   * 
+   * The result list<bool> is the same length as the argument
+   * list<pollable>, and indicates the readiness of each corresponding
+   * element in that / list, with true indicating ready.
+   */
+  export function pollOneoff(in_: Uint32Array): boolean[];
+}
+/**
+ * A "pollable" handle.
+ * 
+ * This is conceptually represents a `stream<_, _>`, or in other words,
+ * a stream that one can wait on, repeatedly, but which does not itself
+ * produce any data. It's temporary scaffolding until component-model's
+ * async features are ready.
+ * 
+ * And at present, it is a `u32` instead of being an actual handle, until
+ * the wit-bindgen implementation of handles and resources is ready.
+ * 
+ * `pollable` lifetimes are not automatically managed. Users must ensure
+ * that they do not outlive the resource they reference.
+ * 
+ * This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources).
+ */
+export type Pollable = number;

package/types/exports/wasi-random-insecure-seed.d.ts

@@ -0,0 +1,22 @@
+export namespace WasiRandomInsecureSeed {
+  /**
+   * Return a 128-bit value that may contain a pseudo-random value.
+   * 
+   * The returned value is not required to be computed from a CSPRNG, and may
+   * even be entirely deterministic. Host implementations are encouraged to
+   * provide pseudo-random values to any program exposed to
+   * attacker-controlled content, to enable DoS protection built into many
+   * languages' hash-map implementations.
+   * 
+   * This function is intended to only be called once, by a source language
+   * to initialize Denial Of Service (DoS) protection in its hash-map
+   * implementation.
+   * 
+   * # Expected future evolution
+   * 
+   * This will likely be changed to a value import, to prevent it from being
+   * called multiple times and potentially used for purposes other than DoS
+   * protection.
+   */
+  export function insecureSeed(): [bigint, bigint];
+}

package/types/exports/wasi-random-insecure.d.ts

@@ -0,0 +1,20 @@
+export namespace WasiRandomInsecure {
+  /**
+   * Return `len` insecure pseudo-random bytes.
+   * 
+   * This function is not cryptographically secure. Do not use it for
+   * anything related to security.
+   * 
+   * There are no requirements on the values of the returned bytes, however
+   * implementations are encouraged to return evenly distributed values with
+   * a long period.
+   */
+  export function getInsecureRandomBytes(len: bigint): Uint8Array;
+  /**
+   * Return an insecure pseudo-random `u64` value.
+   * 
+   * This function returns the same type of pseudo-random data as
+   * `get-insecure-random-bytes`, represented as a `u64`.
+   */
+  export function getInsecureRandomU64(): bigint;
+}

package/types/exports/wasi-random-random.d.ts

@@ -0,0 +1,22 @@
+export namespace WasiRandomRandom {
+  /**
+   * Return `len` cryptographically-secure pseudo-random bytes.
+   * 
+   * This function must produce data from an adequately seeded
+   * cryptographically-secure pseudo-random number generator (CSPRNG), so it
+   * must not block, from the perspective of the calling program, and the
+   * returned data is always unpredictable.
+   * 
+   * This function must always return fresh pseudo-random data. Deterministic
+   * environments must omit this function, rather than implementing it with
+   * deterministic data.
+   */
+  export function getRandomBytes(len: bigint): Uint8Array;
+  /**
+   * Return a cryptographically-secure pseudo-random `u64` value.
+   * 
+   * This function returns the same type of pseudo-random data as
+   * `get-random-bytes`, represented as a `u64`.
+   */
+  export function getRandomU64(): bigint;
+}

package/types/exports/wasi-sockets-instance-network.d.ts

@@ -0,0 +1,8 @@
+export namespace WasiSocketsInstanceNetwork {
+  /**
+   * Get a handle to the default network.
+   */
+  export function instanceNetwork(): Network;
+}
+import type { Network } from '../exports/wasi-sockets-network';
+export { Network };

package/types/exports/wasi-sockets-ip-name-lookup.d.ts

@@ -0,0 +1,76 @@
+export namespace WasiSocketsIpNameLookup {
+  /**
+   * Resolve an internet host name to a list of IP addresses.
+   * 
+   * See the wasi-socket proposal README.md for a comparison with getaddrinfo.
+   * 
+   * # Parameters
+   * - `name`: The name to look up. IP addresses are not allowed. Unicode domain names are automatically converted
+   * to ASCII using IDNA encoding.
+   * - `address-family`: If provided, limit the results to addresses of this specific address family.
+   * - `include-unavailable`: When set to true, this function will also return addresses of which the runtime
+   * thinks (or knows) can't be connected to at the moment. For example, this will return IPv6 addresses on
+   * systems without an active IPv6 interface. Notes:
+   * - Even when no public IPv6 interfaces are present or active, names like "localhost" can still resolve to an IPv6 address.
+   * - Whatever is "available" or "unavailable" is volatile and can change everytime a network cable is unplugged.
+   * 
+   * This function never blocks. It either immediately fails or immediately returns successfully with a `resolve-address-stream`
+   * that can be used to (asynchronously) fetch the results.
+   * 
+   * At the moment, the stream never completes successfully with 0 items. Ie. the first call
+   * to `resolve-next-address` never returns `ok(none)`. This may change in the future.
+   * 
+   * # Typical errors
+   * - `invalid-name`:                 `name` is a syntactically invalid domain name.
+   * - `invalid-name`:                 `name` is an IP address.
+   * - `address-family-not-supported`: The specified `address-family` is not supported. (EAI_FAMILY)
+   * 
+   * # References:
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getaddrinfo.html>
+   * - <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3>
+   */
+  export function resolveAddresses(network: Network, name: string, addressFamily: IpAddressFamily | null, includeUnavailable: boolean): ResolveAddressStream;
+  /**
+   * Returns the next address from the resolver.
+   * 
+   * This function should be called multiple times. On each call, it will
+   * return the next address in connection order preference. If all
+   * addresses have been exhausted, this function returns `none`.
+   * After which, you should release the stream with `drop-resolve-address-stream`.
+   * 
+   * This function never returns IPv4-mapped IPv6 addresses.
+   * 
+   * # Typical errors
+   * - `name-unresolvable`:          Name does not exist or has no suitable associated IP addresses. (EAI_NONAME, EAI_NODATA, EAI_ADDRFAMILY)
+   * - `temporary-resolver-failure`: A temporary failure in name resolution occurred. (EAI_AGAIN)
+   * - `permanent-resolver-failure`: A permanent failure in name resolution occurred. (EAI_FAIL)
+   * - `would-block`:                A result is not available yet. (EWOULDBLOCK, EAGAIN)
+   */
+  export function resolveNextAddress(this_: ResolveAddressStream): IpAddress | null;
+  /**
+   * Dispose of the specified `resolve-address-stream`, 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 dropResolveAddressStream(this_: ResolveAddressStream): void;
+  /**
+   * Create a `pollable` which will resolve once the stream 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_: ResolveAddressStream): Pollable;
+}
+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 { IpAddress } from '../exports/wasi-sockets-network';
+export { IpAddress };
+import type { IpAddressFamily } from '../exports/wasi-sockets-network';
+export { IpAddressFamily };
+export type ResolveAddressStream = number;