@bytecodealliance/preview2-shim 0.0.13 → 0.0.15

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

@@ -0,0 +1,274 @@
+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;
+  /**
+   * Check readiness for writing. This function never blocks.
+   * 
+   * Returns the number of bytes permitted for the next call to `write`,
+   * or an error. Calling `write` with more bytes than this function has
+   * permitted will trap.
+   * 
+   * When this function returns 0 bytes, the `subscribe-to-output-stream`
+   * pollable will become ready when this function will report at least
+   * 1 byte, or an error.
+   */
+  export function checkWrite(this_: OutputStream): bigint;
+  /**
+   * Perform a write. This function never blocks.
+   * 
+   * Precondition: check-write gave permit of Ok(n) and contents has a
+   * length of less than or equal to n. Otherwise, this function will trap.
+   * 
+   * returns Err(closed) without writing if the stream has closed since
+   * the last call to check-write provided a permit.
+   */
+  export function write(this_: OutputStream, contents: Uint8Array): void;
+  /**
+   * Perform a write of up to 4096 bytes, and then flush the stream. Block
+   * until all of these operations are complete, or an error occurs.
+   * 
+   * This is a convenience wrapper around the use of `check-write`,
+   * `subscribe-to-output-stream`, `write`, and `flush`, and is implemented
+   * with the following pseudo-code:
+   * 
+   * ```text
+   * let pollable = subscribe-to-output-stream(this);
+   * while !contents.is_empty() {
+     * // Wait for the stream to become writable
+     * poll-oneoff(pollable);
+     * let Ok(n) = check-write(this); // eliding error handling
+     * let len = min(n, contents.len());
+     * let (chunk, rest) = contents.split_at(len);
+     * write(this, chunk);            // eliding error handling
+     * contents = rest;
+     * }
+     * flush(this);
+     * // Wait for completion of `flush`
+     * poll-oneoff(pollable);
+     * // Check for any errors that arose during `flush`
+     * let _ = check-write(this);       // eliding error handling
+     * ```
+     */
+    export function blockingWriteAndFlush(this_: OutputStream, contents: Uint8Array): void;
+    /**
+     * Request to flush buffered output. This function never blocks.
+     * 
+     * This tells the output-stream that the caller intends any buffered
+     * output to be flushed. the output which is expected to be flushed
+     * is all that has been passed to `write` prior to this call.
+     * 
+     * Upon calling this function, the `output-stream` will not accept any
+     * writes (`check-write` will return `ok(0)`) until the flush has
+     * completed. The `subscribe-to-output-stream` pollable will become ready
+     * when the flush has completed and the stream can accept more writes.
+     */
+    export function flush(this_: OutputStream): void;
+    /**
+     * Request to flush buffered output, and block until flush completes
+     * and stream is ready for writing again.
+     */
+    export function blockingFlush(this_: OutputStream): void;
+    /**
+     * Create a `pollable` which will resolve once the output-stream
+     * is ready for more writing, or an error has occured. When this
+     * pollable is ready, `check-write` will return `ok(n)` with n>0, or an
+     * error.
+     * 
+     * If the stream is closed, this pollable is always ready immediately.
+     * 
+     * The created `pollable` is a child resource of the `output-stream`.
+     * Implementations may trap if the `output-stream` is dropped before
+     * all derived `pollable`s created with this function are dropped.
+     */
+    export function subscribeToOutputStream(this_: OutputStream): Pollable;
+    /**
+     * Write zeroes to a stream.
+     * 
+     * this should be used precisely like `write` with the exact same
+     * preconditions (must use check-write first), but instead of
+     * passing a list of bytes, you simply pass the number of zero-bytes
+     * that should be written.
+     */
+    export function writeZeroes(this_: OutputStream, len: bigint): void;
+    /**
+     * 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];
+    /**
+     * 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 '../interfaces/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;
+  /**
+   * An error for output-stream operations.
+   * 
+   * Contrary to input-streams, a closed output-stream is reported using
+   * an error.
+   * # Variants
+   * 
+   * ## `"last-operation-failed"`
+   * 
+   * The last operation (a write or flush) failed before completion.
+   * ## `"closed"`
+   * 
+   * The stream is closed: no more input will be accepted by the
+   * stream. A closed output-stream will return this error on all
+   * future operations.
+   */
+  export type WriteError = 'last-operation-failed' | 'closed';
+  

package/types/interfaces/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/interfaces/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/interfaces/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/interfaces/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/interfaces/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 '../interfaces/wasi-sockets-network';
+export { Network };

package/types/interfaces/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 | undefined, 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 | undefined;
+  /**
+   * 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 '../interfaces/wasi-poll-poll';
+export { Pollable };
+import type { Network } from '../interfaces/wasi-sockets-network';
+export { Network };
+import type { ErrorCode } from '../interfaces/wasi-sockets-network';
+export { ErrorCode };
+import type { IpAddress } from '../interfaces/wasi-sockets-network';
+export { IpAddress };
+import type { IpAddressFamily } from '../interfaces/wasi-sockets-network';
+export { IpAddressFamily };
+export type ResolveAddressStream = number;

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

@@ -0,0 +1,180 @@
+export namespace WasiSocketsNetwork {
+  /**
+   * Dispose of the specified `network`, 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 dropNetwork(this_: Network): void;
+}
+/**
+ * An opaque resource that represents access to (a subset of) the network.
+ * This enables context-based security for networking.
+ * There is no need for this to map 1:1 to a physical network interface.
+ * 
+ * FYI, In the future this will be replaced by handle types.
+ */
+export type Network = number;
+/**
+ * Error codes.
+ * 
+ * In theory, every API can return any error code.
+ * In practice, API's typically only return the errors documented per API
+ * combined with a couple of errors that are always possible:
+ * - `unknown`
+ * - `access-denied`
+ * - `not-supported`
+ * - `out-of-memory`
+ * 
+ * See each individual API for what the POSIX equivalents are. They sometimes differ per API.
+ * # Variants
+ * 
+ * ## `"unknown"`
+ * 
+ * Unknown error
+ * ## `"access-denied"`
+ * 
+ * Access denied.
+ * 
+ * POSIX equivalent: EACCES, EPERM
+ * ## `"not-supported"`
+ * 
+ * The operation is not supported.
+ * 
+ * POSIX equivalent: EOPNOTSUPP
+ * ## `"out-of-memory"`
+ * 
+ * Not enough memory to complete the operation.
+ * 
+ * POSIX equivalent: ENOMEM, ENOBUFS, EAI_MEMORY
+ * ## `"timeout"`
+ * 
+ * The operation timed out before it could finish completely.
+ * ## `"concurrency-conflict"`
+ * 
+ * This operation is incompatible with another asynchronous operation that is already in progress.
+ * ## `"not-in-progress"`
+ * 
+ * Trying to finish an asynchronous operation that:
+ * - has not been started yet, or:
+ * - was already finished by a previous `finish-*` call.
+ * 
+ * Note: this is scheduled to be removed when `future`s are natively supported.
+ * ## `"would-block"`
+ * 
+ * The operation has been aborted because it could not be completed immediately.
+ * 
+ * Note: this is scheduled to be removed when `future`s are natively supported.
+ * ## `"address-family-not-supported"`
+ * 
+ * The specified address-family is not supported.
+ * ## `"address-family-mismatch"`
+ * 
+ * An IPv4 address was passed to an IPv6 resource, or vice versa.
+ * ## `"invalid-remote-address"`
+ * 
+ * The socket address is not a valid remote address. E.g. the IP address is set to INADDR_ANY, or the port is set to 0.
+ * ## `"ipv4-only-operation"`
+ * 
+ * The operation is only supported on IPv4 resources.
+ * ## `"ipv6-only-operation"`
+ * 
+ * The operation is only supported on IPv6 resources.
+ * ## `"new-socket-limit"`
+ * 
+ * A new socket resource could not be created because of a system limit.
+ * ## `"already-attached"`
+ * 
+ * The socket is already attached to another network.
+ * ## `"already-bound"`
+ * 
+ * The socket is already bound.
+ * ## `"already-connected"`
+ * 
+ * The socket is already in the Connection state.
+ * ## `"not-bound"`
+ * 
+ * The socket is not bound to any local address.
+ * ## `"not-connected"`
+ * 
+ * The socket is not in the Connection state.
+ * ## `"address-not-bindable"`
+ * 
+ * A bind operation failed because the provided address is not an address that the `network` can bind to.
+ * ## `"address-in-use"`
+ * 
+ * A bind operation failed because the provided address is already in use.
+ * ## `"ephemeral-ports-exhausted"`
+ * 
+ * A bind operation failed because there are no ephemeral ports available.
+ * ## `"remote-unreachable"`
+ * 
+ * The remote address is not reachable
+ * ## `"already-listening"`
+ * 
+ * The socket is already in the Listener state.
+ * ## `"not-listening"`
+ * 
+ * The socket is already in the Listener state.
+ * ## `"connection-refused"`
+ * 
+ * The connection was forcefully rejected
+ * ## `"connection-reset"`
+ * 
+ * The connection was reset.
+ * ## `"datagram-too-large"`
+ * 
+ * ## `"invalid-name"`
+ * 
+ * The provided name is a syntactically invalid domain name.
+ * ## `"name-unresolvable"`
+ * 
+ * Name does not exist or has no suitable associated IP addresses.
+ * ## `"temporary-resolver-failure"`
+ * 
+ * A temporary failure in name resolution occurred.
+ * ## `"permanent-resolver-failure"`
+ * 
+ * A permanent failure in name resolution occurred.
+ */
+export type ErrorCode = 'unknown' | 'access-denied' | 'not-supported' | 'out-of-memory' | 'timeout' | 'concurrency-conflict' | 'not-in-progress' | 'would-block' | 'address-family-not-supported' | 'address-family-mismatch' | 'invalid-remote-address' | 'ipv4-only-operation' | 'ipv6-only-operation' | 'new-socket-limit' | 'already-attached' | 'already-bound' | 'already-connected' | 'not-bound' | 'not-connected' | 'address-not-bindable' | 'address-in-use' | 'ephemeral-ports-exhausted' | 'remote-unreachable' | 'already-listening' | 'not-listening' | 'connection-refused' | 'connection-reset' | 'datagram-too-large' | 'invalid-name' | 'name-unresolvable' | 'temporary-resolver-failure' | 'permanent-resolver-failure';
+/**
+ * # Variants
+ * 
+ * ## `"ipv4"`
+ * 
+ * Similar to `AF_INET` in POSIX.
+ * ## `"ipv6"`
+ * 
+ * Similar to `AF_INET6` in POSIX.
+ */
+export type IpAddressFamily = 'ipv4' | 'ipv6';
+export type Ipv4Address = [number, number, number, number];
+export type Ipv6Address = [number, number, number, number, number, number, number, number];
+export type IpAddress = IpAddressIpv4 | IpAddressIpv6;
+export interface IpAddressIpv4 {
+  tag: 'ipv4',
+  val: Ipv4Address,
+}
+export interface IpAddressIpv6 {
+  tag: 'ipv6',
+  val: Ipv6Address,
+}
+export interface Ipv4SocketAddress {
+  port: number,
+  address: Ipv4Address,
+}
+export interface Ipv6SocketAddress {
+  port: number,
+  flowInfo: number,
+  address: Ipv6Address,
+  scopeId: number,
+}
+export type IpSocketAddress = IpSocketAddressIpv4 | IpSocketAddressIpv6;
+export interface IpSocketAddressIpv4 {
+  tag: 'ipv4',
+  val: Ipv4SocketAddress,
+}
+export interface IpSocketAddressIpv6 {
+  tag: 'ipv6',
+  val: Ipv6SocketAddress,
+}

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

@@ -0,0 +1,33 @@
+export namespace WasiSocketsTcpCreateSocket {
+  /**
+   * Create a new TCP socket.
+   * 
+   * Similar to `socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP)` in POSIX.
+   * 
+   * 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`
+   * 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.
+   * 
+   * # Typical errors
+   * - `not-supported`:                The host does not support TCP sockets. (EOPNOTSUPP)
+   * - `address-family-not-supported`: The specified `address-family` is not supported. (EAFNOSUPPORT)
+   * - `new-socket-limit`:             The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
+   * 
+   * # References
+   * - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/socket.html>
+   * - <https://man7.org/linux/man-pages/man2/socket.2.html>
+   * - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
+   * - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
+   */
+  export function createTcpSocket(addressFamily: IpAddressFamily): TcpSocket;
+}
+import type { Network } from '../interfaces/wasi-sockets-network';
+export { Network };
+import type { ErrorCode } from '../interfaces/wasi-sockets-network';
+export { ErrorCode };
+import type { IpAddressFamily } from '../interfaces/wasi-sockets-network';
+export { IpAddressFamily };
+import type { TcpSocket } from '../interfaces/wasi-sockets-tcp';
+export { TcpSocket };