@bytecodealliance/preview2-shim 0.0.8 → 0.0.9

package/types/imports/{default-outgoing-HTTP.d.ts → http-outgoing-handler.d.ts}

@@ -1,4 +1,4 @@
-export namespace DefaultOutgoingHttp {
+export namespace HttpOutgoingHandler {
   export function handle(request: OutgoingRequest, options: RequestOptions | null): FutureIncomingResponse;
 }
 import type { OutgoingRequest } from '../imports/types';

package/types/imports/{types.d.ts → http-types.d.ts}

@@ -1,4 +1,4 @@
-export namespace Types {
+export namespace HttpTypes {
   export function dropFields(fields: Fields): void;
   export function newFields(entries: [string, string][]): Fields;
   export function fieldsGet(fields: Fields, name: string): string[];
@@ -33,15 +33,32 @@ export namespace Types {
   export function futureIncomingResponseGet(f: FutureIncomingResponse): Result<IncomingResponse, Error> | null;
   export function listenToFutureIncomingResponse(f: FutureIncomingResponse): Pollable;
 }
-export type Fields = number;
 import type { InputStream } from '../imports/streams';
 export { InputStream };
-export type IncomingStream = InputStream;
-export type Trailers = Fields;
 import type { OutputStream } from '../imports/streams';
 export { OutputStream };
+import type { Pollable } from '../imports/poll';
+export { Pollable };
+export type StatusCode = number;
+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 ResponseOutparam = number;
+export interface RequestOptions {
+  connectTimeoutMs?: number,
+  firstByteTimeoutMs?: number,
+  betweenBytesTimeoutMs?: number,
+}
 export type OutgoingStream = OutputStream;
-export type IncomingRequest = number;
+export type OutgoingResponse = number;
 export type OutgoingRequest = number;
 export type Method = MethodGet | MethodHead | MethodPost | MethodPut | MethodDelete | MethodConnect | MethodOptions | MethodTrace | MethodPatch | MethodOther;
 export interface MethodGet {
@@ -75,20 +92,13 @@ 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 IncomingStream = InputStream;
+export type IncomingResponse = number;
+export type IncomingRequest = number;
+export type FutureIncomingResponse = number;
+export type Fields = number;
+export type Trailers = Fields;
 export type Headers = Fields;
-export type ResponseOutparam = number;
-export type OutgoingResponse = number;
 export type Error = ErrorInvalidUrl | ErrorTimeoutError | ErrorProtocolError | ErrorUnexpectedError;
 export interface ErrorInvalidUrl {
   tag: 'invalid-url',
@@ -106,14 +116,4 @@ export interface ErrorUnexpectedError {
   tag: 'unexpected-error',
   val: string,
 }
-export type IncomingResponse = number;
-export type StatusCode = number;
-export type FutureIncomingResponse = number;
-import type { Pollable } from '../imports/poll';
-export { Pollable };
-export interface RequestOptions {
-  connectTimeoutMs?: number,
-  firstByteTimeoutMs?: number,
-  betweenBytesTimeoutMs?: number,
-}
 export type Result<T, E> = { tag: 'ok', val: T } | { tag: 'err', val: E };

package/types/imports/io-streams.d.ts

@@ -0,0 +1,180 @@
+export namespace IoStreams {
+  /**
+   * Read bytes from a stream.
+   * 
+   * This function returns a list of bytes containing the data that was
+   * read, along with a bool which, when true, indicates that the end of the
+   * stream was reached. The returned list will contain up to `len` bytes; it
+   * may return fewer than requested, but not more.
+   * 
+   * Once a stream has reached the end, subsequent calls to read or
+   * `skip` will always report end-of-stream rather than producing more
+   * data.
+   * 
+   * If `len` is 0, it represents a request to read 0 bytes, which should
+   * always succeed, assuming the stream hasn't reached its end yet, and
+   * return an empty list.
+   * 
+   * The len here is a `u64`, but some callees may not be able to allocate
+   * a buffer as large as that would imply.
+   * FIXME: describe what happens if allocation fails.
+   */
+  export function read(this: InputStream, len: bigint): [Uint8Array | ArrayBuffer, boolean];
+  /**
+   * Read bytes from a stream, with blocking.
+   * 
+   * This is similar to `read`, except that it blocks until at least one
+   * byte can be read.
+   */
+  export function blockingRead(this: InputStream, len: bigint): [Uint8Array | ArrayBuffer, boolean];
+  /**
+   * 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 bool
+   * 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, boolean];
+  /**
+   * Skip bytes from a stream, with blocking.
+   * 
+   * This is similar to `skip`, except that it blocks until at least one
+   * byte can be consumed.
+   */
+  export function blockingSkip(this: InputStream, len: bigint): [bigint, boolean];
+  /**
+   * 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.
+   */
+  export function subscribeToInputStream(this: InputStream): Pollable;
+  /**
+   * Dispose of the specified `input-stream`, after which it may no longer
+   * be used.
+   */
+  export function dropInputStream(this: InputStream): void;
+  /**
+   * Write bytes to a stream.
+   * 
+   * This function returns a `u64` indicating the number of bytes from
+   * `buf` that were written; it may be less than the full list.
+   */
+  export function write(this: OutputStream, buf: Uint8Array): bigint;
+  /**
+   * Write bytes to a stream, with blocking.
+   * 
+   * This is similar to `write`, except that it blocks until at least one
+   * byte can be written.
+   */
+  export function blockingWrite(this: OutputStream, buf: Uint8Array): bigint;
+  /**
+   * 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`.
+   */
+  export function writeZeroes(this: OutputStream, len: bigint): bigint;
+  /**
+   * 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.
+   */
+  export function blockingWriteZeroes(this: OutputStream, len: bigint): bigint;
+  /**
+   * 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, boolean];
+  /**
+   * 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, boolean];
+  /**
+   * 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.
+   */
+  export function forward(this: OutputStream, src: InputStream): bigint;
+  /**
+   * Create a `pollable` which will resolve once either the specified stream
+   * is ready to accept bytes or the other end of the stream has been closed.
+   */
+  export function subscribeToOutputStream(this: OutputStream): Pollable;
+  /**
+   * Dispose of the specified `output-stream`, after which it may no longer
+   * be used.
+   */
+  export function dropOutputStream(this: OutputStream): void;
+}
+import type { Pollable } from '../imports/poll';
+export { Pollable };
+/**
+ * An error type returned from a stream operation. Currently this
+ * doesn't provide any additional information.
+ */
+export interface StreamError {
+}
+/**
+ * An output bytestream. In the future, this will be replaced by handle
+ * types.
+ * 
+ * This conceptually represents a `stream<u8, _>`. It's temporary
+ * scaffolding until component-model's async features are ready.
+ * 
+ * `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;
+/**
+ * An input bytestream. In the future, this will be replaced by handle
+ * types.
+ * 
+ * This conceptually represents a `stream<u8, _>`. It's temporary
+ * scaffolding until component-model's async features are ready.
+ * 
+ * `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`.
+ * 
+ * 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;

package/types/imports/logging-handler.d.ts

@@ -0,0 +1,40 @@
+export namespace LoggingHandler {
+  /**
+   * Emit a log message.
+   * 
+   * A log message has a `level` describing what kind of message is being
+   * sent, a context, which is an uninterpreted string meant to help
+   * consumers group similar messages, and a string containing the message
+   * text.
+   */
+  export function log(level: Level, context: string, message: string): void;
+}
+/**
+ * A log level, describing a kind of message.
+ * 
+ * # Variants
+ * 
+ * ## `"trace"`
+ * 
+ * Describes messages about the values of variables and the flow of
+ * control within a program.
+ * 
+ * ## `"debug"`
+ * 
+ * Describes messages likely to be of interest to someone debugging a
+ * program.
+ * 
+ * ## `"info"`
+ * 
+ * Describes messages likely to be of interest to someone monitoring a
+ * program.
+ * 
+ * ## `"warn"`
+ * 
+ * Describes messages indicating hazardous situations.
+ * 
+ * ## `"error"`
+ * 
+ * Describes messages indicating serious errors.
+ */
+export type Level = 'trace' | 'debug' | 'info' | 'warn' | 'error';

package/types/imports/poll-poll.d.ts

@@ -0,0 +1,41 @@
+export namespace PollPoll {
+  /**
+   * 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.
+   * 
+   * Note that the return type would ideally be `list<bool>`, but that would
+   * be more difficult to polyfill given the current state of `wit-bindgen`.
+   * See <https://github.com/bytecodealliance/preview2-prototyping/pull/11#issuecomment-1329873061>
+   * for details.  For now, we use zero to mean "not ready" and non-zero to
+   * mean "ready".
+   */
+  export function pollOneoff(in: Uint32Array): Uint8Array | ArrayBuffer;
+}
+/**
+ * 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/imports/random-insecure-seed.d.ts

@@ -0,0 +1,22 @@
+export namespace RandomInsecureSeed {
+  /**
+   * 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/imports/random-insecure.d.ts

@@ -0,0 +1,20 @@
+export namespace RandomInsecure {
+  /**
+   * 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 | ArrayBuffer;
+  /**
+   * 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/imports/random-random.d.ts

@@ -0,0 +1,22 @@
+export namespace RandomRandom {
+  /**
+   * 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 | ArrayBuffer;
+  /**
+   * 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/imports/{instance-network.d.ts → sockets-instance-network.d.ts}

@@ -1,4 +1,7 @@
-export namespace InstanceNetwork {
+export namespace SocketsInstanceNetwork {
+  /**
+   * Get a handle to the default network.
+   */
   export function instanceNetwork(): Network;
 }
 import type { Network } from '../imports/network';

package/types/imports/sockets-ip-name-lookup.d.ts

@@ -0,0 +1,76 @@
+export namespace SocketsIpNameLookup {
+  /**
+   * 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 '../imports/poll';
+export { Pollable };
+import type { Network } from '../imports/network';
+export { Network };
+import type { ErrorCode } from '../imports/network';
+export { ErrorCode };
+import type { IpAddress } from '../imports/network';
+export { IpAddress };
+import type { IpAddressFamily } from '../imports/network';
+export { IpAddressFamily };
+export type ResolveAddressStream = number;