Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More →
Socket
Sign inDemoInstall
Socket
Sign inDemoInstall

@bytecodealliance/preview2-shim

Package Overview
Dependencies
Maintainers
3
Versions
36
Alerts
File Explorer

Advanced tools

License
Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@bytecodealliance/preview2-shim - npm Package Compare versions

Comparing version 0.16.1 to 0.16.2

2

lib/nodejs/http.js

@@ -287,2 +287,4 @@ import {

}
if (!request.#pathWithQuery)
throw { tag: 'HTTP-request-URI-invalid' };
return futureIncomingResponseCreate(

@@ -289,0 +291,0 @@ request.#method.val || request.#method.tag,

2

package.json
{
"name": "@bytecodealliance/preview2-shim",
"version": "0.16.1",
"version": "0.16.2",
"description": "WASI Preview2 shim for JS environments",

@@ -5,0 +5,0 @@ "author": "Guy Bedford, Eduardo Rodrigues<16357187+eduardomourar@users.noreply.github.com>",

4

types/clocks.d.ts
import type { WasiClocksMonotonicClock } from './interfaces/wasi-clocks-monotonic-clock.d.ts';
import type { WasiClocksWallClock } from './interfaces/wasi-clocks-wall-clock.d.ts';
export const wallClock: typeof WasiClocksMonotonicClock;
export const monotonicClock: typeof WasiClocksWallClock;
export const wallClock: typeof WasiClocksWallClock;
export const monotonicClock: typeof WasiClocksMonotonicClock;

498

types/interfaces/wasi-filesystem-types.d.ts
export namespace WasiFilesystemTypes {
/**
* Return a stream for reading from a file, if available.
*
* May fail with an error-code describing why the file cannot be read.
*
* Multiple read, write, and append streams may be active on the same open
* file and they do not interfere with each other.
*
* Note: This allows using `read-stream`, which is similar to `read` in POSIX.
*/
export { Descriptor };
/**
* Return a stream for writing to a file, if available.
*
* May fail with an error-code describing why the file cannot be written.
*
* Note: This allows using `write-stream`, which is similar to `write` in
* POSIX.
*/
/**
* Return a stream for appending to a file, if available.
*
* May fail with an error-code describing why the file cannot be appended.
*
* Note: This allows using `write-stream`, which is similar to `write` with
* `O_APPEND` in in POSIX.
*/
/**
* Provide file advisory information on a descriptor.
*
* This is similar to `posix_fadvise` in POSIX.
*/
/**
* Synchronize the data of a file to disk.
*
* This function succeeds with no effect if the file descriptor is not
* opened for writing.
*
* Note: This is similar to `fdatasync` in POSIX.
*/
/**
* Get flags associated with a descriptor.
*
* Note: This returns similar flags to `fcntl(fd, F_GETFL)` in POSIX.
*
* Note: This returns the value that was the `fs_flags` value returned
* from `fdstat_get` in earlier versions of WASI.
*/
/**
* Get the dynamic type of a descriptor.
*
* Note: This returns the same value as the `type` field of the `fd-stat`
* returned by `stat`, `stat-at` and similar.
*
* Note: This returns similar flags to the `st_mode & S_IFMT` value provided
* by `fstat` in POSIX.
*
* Note: This returns the value that was the `fs_filetype` value returned
* from `fdstat_get` in earlier versions of WASI.
*/
/**
* Adjust the size of an open file. If this increases the file's size, the
* extra bytes are filled with zeros.
*
* Note: This was called `fd_filestat_set_size` in earlier versions of WASI.
*/
/**
* Adjust the timestamps of an open file or directory.
*
* Note: This is similar to `futimens` in POSIX.
*
* Note: This was called `fd_filestat_set_times` in earlier versions of WASI.
*/
/**
* Read from a descriptor, without using and updating the descriptor's offset.
*
* 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
* file was reached. The returned list will contain up to `length` bytes; it
* may return fewer than requested, if the end of the file is reached or
* if the I/O operation is interrupted.
*
* In the future, this may change to return a `stream<u8, error-code>`.
*
* Note: This is similar to `pread` in POSIX.
*/
/**
* Write to a descriptor, without using and updating the descriptor's offset.
*
* It is valid to write past the end of a file; the file is extended to the
* extent of the write, with bytes between the previous end and the start of
* the write set to zero.
*
* In the future, this may change to take a `stream<u8, error-code>`.
*
* Note: This is similar to `pwrite` in POSIX.
*/
/**
* Read directory entries from a directory.
*
* On filesystems where directories contain entries referring to themselves
* and their parents, often named `.` and `..` respectively, these entries
* are omitted.
*
* This always returns a new stream which starts at the beginning of the
* directory. Multiple streams may be active on the same directory, and they
* do not interfere with each other.
*/
/**
* Synchronize the data and metadata of a file to disk.
*
* This function succeeds with no effect if the file descriptor is not
* opened for writing.
*
* Note: This is similar to `fsync` in POSIX.
*/
/**
* Create a directory.
*
* Note: This is similar to `mkdirat` in POSIX.
*/
/**
* Return the attributes of an open file or directory.
*
* Note: This is similar to `fstat` in POSIX, except that it does not return
* device and inode information. For testing whether two descriptors refer to
* the same underlying filesystem object, use `is-same-object`. To obtain
* additional data that can be used do determine whether a file has been
* modified, use `metadata-hash`.
*
* Note: This was called `fd_filestat_get` in earlier versions of WASI.
*/
/**
* Return the attributes of a file or directory.
*
* Note: This is similar to `fstatat` in POSIX, except that it does not
* return device and inode information. See the `stat` description for a
* discussion of alternatives.
*
* Note: This was called `path_filestat_get` in earlier versions of WASI.
*/
/**
* Adjust the timestamps of a file or directory.
*
* Note: This is similar to `utimensat` in POSIX.
*
* Note: This was called `path_filestat_set_times` in earlier versions of
* WASI.
*/
/**
* Create a hard link.
*
* Note: This is similar to `linkat` in POSIX.
*/
/**
* Open a file or directory.
*
* The returned descriptor is not guaranteed to be the lowest-numbered
* descriptor not currently open/ it is randomized to prevent applications
* from depending on making assumptions about indexes, since this is
* error-prone in multi-threaded contexts. The returned descriptor is
* guaranteed to be less than 2**31.
*
* If `flags` contains `descriptor-flags::mutate-directory`, and the base
* descriptor doesn't have `descriptor-flags::mutate-directory` set,
* `open-at` fails with `error-code::read-only`.
*
* If `flags` contains `write` or `mutate-directory`, or `open-flags`
* contains `truncate` or `create`, and the base descriptor doesn't have
* `descriptor-flags::mutate-directory` set, `open-at` fails with
* `error-code::read-only`.
*
* Note: This is similar to `openat` in POSIX.
*/
/**
* Read the contents of a symbolic link.
*
* If the contents contain an absolute or rooted path in the underlying
* filesystem, this function fails with `error-code::not-permitted`.
*
* Note: This is similar to `readlinkat` in POSIX.
*/
/**
* Remove a directory.
*
* Return `error-code::not-empty` if the directory is not empty.
*
* Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX.
*/
/**
* Rename a filesystem object.
*
* Note: This is similar to `renameat` in POSIX.
*/
/**
* Create a symbolic link (also known as a "symlink").
*
* If `old-path` starts with `/`, the function fails with
* `error-code::not-permitted`.
*
* Note: This is similar to `symlinkat` in POSIX.
*/
/**
* Unlink a filesystem object that is not a directory.
*
* Return `error-code::is-directory` if the path refers to a directory.
* Note: This is similar to `unlinkat(fd, path, 0)` in POSIX.
*/
/**
* Test whether two descriptors refer to the same filesystem object.
*
* In POSIX, this corresponds to testing whether the two descriptors have the
* same device (`st_dev`) and inode (`st_ino` or `d_ino`) numbers.
* wasi-filesystem does not expose device and inode numbers, so this function
* may be used instead.
*/
/**
* Return a hash of the metadata associated with a filesystem object referred
* to by a descriptor.
*
* This returns a hash of the last-modification timestamp and file size, and
* may also include the inode number, device number, birth timestamp, and
* other metadata fields that may change when the file is modified or
* replaced. It may also include a secret value chosen by the
* implementation and not otherwise exposed.
*
* Implementations are encourated to provide the following properties:
*
* - If the file is not modified or replaced, the computed hash value should
* usually not change.
* - If the object is modified or replaced, the computed hash value should
* usually change.
* - The inputs to the hash should not be easily computable from the
* computed hash.
*
* However, none of these is required.
*/
/**
* Return a hash of the metadata associated with a filesystem object referred
* to by a directory descriptor and a relative path.
*
* This performs the same hash computation as `metadata-hash`.
*/
/**
* Read a single directory entry from a `directory-entry-stream`.
*/
export { DirectoryEntryStream };

@@ -642,34 +397,279 @@ /**

export class DirectoryEntryStream {
readDirectoryEntry(): DirectoryEntry | undefined;
}
export class Descriptor {
/**
* Return a stream for reading from a file, if available.
*
* May fail with an error-code describing why the file cannot be read.
*
* Multiple read, write, and append streams may be active on the same open
* file and they do not interfere with each other.
*
* Note: This allows using `read-stream`, which is similar to `read` in POSIX.
*/
readViaStream(offset: Filesize): InputStream;
/**
* Return a stream for writing to a file, if available.
*
* May fail with an error-code describing why the file cannot be written.
*
* Note: This allows using `write-stream`, which is similar to `write` in
* POSIX.
*/
writeViaStream(offset: Filesize): OutputStream;
/**
* Return a stream for appending to a file, if available.
*
* May fail with an error-code describing why the file cannot be appended.
*
* Note: This allows using `write-stream`, which is similar to `write` with
* `O_APPEND` in in POSIX.
*/
appendViaStream(): OutputStream;
/**
* Provide file advisory information on a descriptor.
*
* This is similar to `posix_fadvise` in POSIX.
*/
advise(offset: Filesize, length: Filesize, advice: Advice): void;
/**
* Synchronize the data of a file to disk.
*
* This function succeeds with no effect if the file descriptor is not
* opened for writing.
*
* Note: This is similar to `fdatasync` in POSIX.
*/
syncData(): void;
/**
* Get flags associated with a descriptor.
*
* Note: This returns similar flags to `fcntl(fd, F_GETFL)` in POSIX.
*
* Note: This returns the value that was the `fs_flags` value returned
* from `fdstat_get` in earlier versions of WASI.
*/
getFlags(): DescriptorFlags;
/**
* Get the dynamic type of a descriptor.
*
* Note: This returns the same value as the `type` field of the `fd-stat`
* returned by `stat`, `stat-at` and similar.
*
* Note: This returns similar flags to the `st_mode & S_IFMT` value provided
* by `fstat` in POSIX.
*
* Note: This returns the value that was the `fs_filetype` value returned
* from `fdstat_get` in earlier versions of WASI.
*/
getType(): DescriptorType;
/**
* Adjust the size of an open file. If this increases the file's size, the
* extra bytes are filled with zeros.
*
* Note: This was called `fd_filestat_set_size` in earlier versions of WASI.
*/
setSize(size: Filesize): void;
/**
* Adjust the timestamps of an open file or directory.
*
* Note: This is similar to `futimens` in POSIX.
*
* Note: This was called `fd_filestat_set_times` in earlier versions of WASI.
*/
setTimes(dataAccessTimestamp: NewTimestamp, dataModificationTimestamp: NewTimestamp): void;
/**
* Read from a descriptor, without using and updating the descriptor's offset.
*
* 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
* file was reached. The returned list will contain up to `length` bytes; it
* may return fewer than requested, if the end of the file is reached or
* if the I/O operation is interrupted.
*
* In the future, this may change to return a `stream<u8, error-code>`.
*
* Note: This is similar to `pread` in POSIX.
*/
read(length: Filesize, offset: Filesize): [Uint8Array, boolean];
/**
* Write to a descriptor, without using and updating the descriptor's offset.
*
* It is valid to write past the end of a file; the file is extended to the
* extent of the write, with bytes between the previous end and the start of
* the write set to zero.
*
* In the future, this may change to take a `stream<u8, error-code>`.
*
* Note: This is similar to `pwrite` in POSIX.
*/
write(buffer: Uint8Array, offset: Filesize): Filesize;
/**
* Read directory entries from a directory.
*
* On filesystems where directories contain entries referring to themselves
* and their parents, often named `.` and `..` respectively, these entries
* are omitted.
*
* This always returns a new stream which starts at the beginning of the
* directory. Multiple streams may be active on the same directory, and they
* do not interfere with each other.
*/
readDirectory(): DirectoryEntryStream;
/**
* Synchronize the data and metadata of a file to disk.
*
* This function succeeds with no effect if the file descriptor is not
* opened for writing.
*
* Note: This is similar to `fsync` in POSIX.
*/
sync(): void;
/**
* Create a directory.
*
* Note: This is similar to `mkdirat` in POSIX.
*/
createDirectoryAt(path: string): void;
/**
* Return the attributes of an open file or directory.
*
* Note: This is similar to `fstat` in POSIX, except that it does not return
* device and inode information. For testing whether two descriptors refer to
* the same underlying filesystem object, use `is-same-object`. To obtain
* additional data that can be used do determine whether a file has been
* modified, use `metadata-hash`.
*
* Note: This was called `fd_filestat_get` in earlier versions of WASI.
*/
stat(): DescriptorStat;
/**
* Return the attributes of a file or directory.
*
* Note: This is similar to `fstatat` in POSIX, except that it does not
* return device and inode information. See the `stat` description for a
* discussion of alternatives.
*
* Note: This was called `path_filestat_get` in earlier versions of WASI.
*/
statAt(pathFlags: PathFlags, path: string): DescriptorStat;
/**
* Adjust the timestamps of a file or directory.
*
* Note: This is similar to `utimensat` in POSIX.
*
* Note: This was called `path_filestat_set_times` in earlier versions of
* WASI.
*/
setTimesAt(pathFlags: PathFlags, path: string, dataAccessTimestamp: NewTimestamp, dataModificationTimestamp: NewTimestamp): void;
/**
* Create a hard link.
*
* Note: This is similar to `linkat` in POSIX.
*/
linkAt(oldPathFlags: PathFlags, oldPath: string, newDescriptor: Descriptor, newPath: string): void;
/**
* Open a file or directory.
*
* The returned descriptor is not guaranteed to be the lowest-numbered
* descriptor not currently open/ it is randomized to prevent applications
* from depending on making assumptions about indexes, since this is
* error-prone in multi-threaded contexts. The returned descriptor is
* guaranteed to be less than 2**31.
*
* If `flags` contains `descriptor-flags::mutate-directory`, and the base
* descriptor doesn't have `descriptor-flags::mutate-directory` set,
* `open-at` fails with `error-code::read-only`.
*
* If `flags` contains `write` or `mutate-directory`, or `open-flags`
* contains `truncate` or `create`, and the base descriptor doesn't have
* `descriptor-flags::mutate-directory` set, `open-at` fails with
* `error-code::read-only`.
*
* Note: This is similar to `openat` in POSIX.
*/
openAt(pathFlags: PathFlags, path: string, openFlags: OpenFlags, flags: DescriptorFlags): Descriptor;
/**
* Read the contents of a symbolic link.
*
* If the contents contain an absolute or rooted path in the underlying
* filesystem, this function fails with `error-code::not-permitted`.
*
* Note: This is similar to `readlinkat` in POSIX.
*/
readlinkAt(path: string): string;
/**
* Remove a directory.
*
* Return `error-code::not-empty` if the directory is not empty.
*
* Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX.
*/
removeDirectoryAt(path: string): void;
/**
* Rename a filesystem object.
*
* Note: This is similar to `renameat` in POSIX.
*/
renameAt(oldPath: string, newDescriptor: Descriptor, newPath: string): void;
/**
* Create a symbolic link (also known as a "symlink").
*
* If `old-path` starts with `/`, the function fails with
* `error-code::not-permitted`.
*
* Note: This is similar to `symlinkat` in POSIX.
*/
symlinkAt(oldPath: string, newPath: string): void;
/**
* Unlink a filesystem object that is not a directory.
*
* Return `error-code::is-directory` if the path refers to a directory.
* Note: This is similar to `unlinkat(fd, path, 0)` in POSIX.
*/
unlinkFileAt(path: string): void;
/**
* Test whether two descriptors refer to the same filesystem object.
*
* In POSIX, this corresponds to testing whether the two descriptors have the
* same device (`st_dev`) and inode (`st_ino` or `d_ino`) numbers.
* wasi-filesystem does not expose device and inode numbers, so this function
* may be used instead.
*/
isSameObject(other: Descriptor): boolean;
/**
* Return a hash of the metadata associated with a filesystem object referred
* to by a descriptor.
*
* This returns a hash of the last-modification timestamp and file size, and
* may also include the inode number, device number, birth timestamp, and
* other metadata fields that may change when the file is modified or
* replaced. It may also include a secret value chosen by the
* implementation and not otherwise exposed.
*
* Implementations are encourated to provide the following properties:
*
* - If the file is not modified or replaced, the computed hash value should
* usually not change.
* - If the object is modified or replaced, the computed hash value should
* usually change.
* - The inputs to the hash should not be easily computable from the
* computed hash.
*
* However, none of these is required.
*/
metadataHash(): MetadataHashValue;
/**
* Return a hash of the metadata associated with a filesystem object referred
* to by a directory descriptor and a relative path.
*
* This performs the same hash computation as `metadata-hash`.
*/
metadataHashAt(pathFlags: PathFlags, path: string): MetadataHashValue;
}
export class DirectoryEntryStream {
/**
* Read a single directory entry from a `directory-entry-stream`.
*/
readDirectoryEntry(): DirectoryEntry | undefined;
}

752

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

@@ -16,342 +16,13 @@ export namespace WasiHttpTypes {

export function httpErrorCode(err: IoError): ErrorCode | undefined;
/**
* Construct an empty HTTP Fields.
*
* The resulting `fields` is mutable.
*/
export { Fields };
/**
* Construct an HTTP Fields.
*
* The resulting `fields` is mutable.
*
* The list represents each key-value pair in the Fields. Keys
* which have multiple values are represented by multiple entries in this
* list with the same key.
*
* The tuple is a pair of the field key, represented as a string, and
* Value, represented as a list of bytes. In a valid Fields, all keys
* and values are valid UTF-8 strings. However, values are not always
* well-formed, so they are represented as a raw list of bytes.
*
* An error result will be returned if any header or value was
* syntactically invalid, or if a header was forbidden.
*/
/**
* Get all of the values corresponding to a key. If the key is not present
* in this `fields`, an empty list is returned. However, if the key is
* present but empty, this is represented by a list with one or more
* empty field-values present.
*/
/**
* Returns `true` when the key is present in this `fields`. If the key is
* syntactically invalid, `false` is returned.
*/
/**
* Set all of the values for a key. Clears any existing values for that
* key, if they have been set.
*
* Fails with `header-error.immutable` if the `fields` are immutable.
*/
/**
* Delete all values for a key. Does nothing if no values for the key
* exist.
*
* Fails with `header-error.immutable` if the `fields` are immutable.
*/
/**
* Append a value for a key. Does not change or delete any existing
* values for that key.
*
* Fails with `header-error.immutable` if the `fields` are immutable.
*/
/**
* Retrieve the full set of keys and values in the Fields. Like the
* constructor, the list represents each key-value pair.
*
* The outer list represents each key-value pair in the Fields. Keys
* which have multiple values are represented by multiple entries in this
* list with the same key.
*/
/**
* Make a deep copy of the Fields. Equivelant in behavior to calling the
* `fields` constructor on the return value of `entries`. The resulting
* `fields` is mutable.
*/
/**
* Returns the method of the incoming request.
*/
export { IncomingRequest };
/**
* Returns the path with query parameters from the request, as a string.
*/
/**
* Returns the protocol scheme from the request.
*/
/**
* Returns the authority from the request, if it was present.
*/
/**
* Get the `headers` associated with the request.
*
* The returned `headers` resource is immutable: `set`, `append`, and
* `delete` operations will fail with `header-error.immutable`.
*
* The `headers` returned are a child resource: it must be dropped before
* the parent `incoming-request` is dropped. Dropping this
* `incoming-request` before all children are dropped will trap.
*/
/**
* Gives the `incoming-body` associated with this request. Will only
* return success at most once, and subsequent calls will return error.
*/
/**
* Construct a new `outgoing-request` with a default `method` of `GET`, and
* `none` values for `path-with-query`, `scheme`, and `authority`.
*
* * `headers` is the HTTP Headers for the Request.
*
* It is possible to construct, or manipulate with the accessor functions
* below, an `outgoing-request` with an invalid combination of `scheme`
* and `authority`, or `headers` which are not permitted to be sent.
* It is the obligation of the `outgoing-handler.handle` implementation
* to reject invalid constructions of `outgoing-request`.
*/
export { OutgoingRequest };
/**
* Returns the resource corresponding to the outgoing Body for this
* Request.
*
* Returns success on the first call: the `outgoing-body` resource for
* this `outgoing-request` can be retrieved at most once. Subsequent
* calls will return error.
*/
/**
* Get the Method for the Request.
*/
/**
* Set the Method for the Request. Fails if the string present in a
* `method.other` argument is not a syntactically valid method.
*/
/**
* Get the combination of the HTTP Path and Query for the Request.
* When `none`, this represents an empty Path and empty Query.
*/
/**
* Set the combination of the HTTP Path and Query for the Request.
* When `none`, this represents an empty Path and empty Query. Fails is the
* string given is not a syntactically valid path and query uri component.
*/
/**
* Get the HTTP Related Scheme for the Request. When `none`, the
* implementation may choose an appropriate default scheme.
*/
/**
* Set the HTTP Related Scheme for the Request. When `none`, the
* implementation may choose an appropriate default scheme. Fails if the
* string given is not a syntactically valid uri scheme.
*/
/**
* Get the HTTP Authority for the Request. A value of `none` may be used
* with Related Schemes which do not require an Authority. The HTTP and
* HTTPS schemes always require an authority.
*/
/**
* Set the HTTP Authority for the Request. A value of `none` may be used
* with Related Schemes which do not require an Authority. The HTTP and
* HTTPS schemes always require an authority. Fails if the string given is
* not a syntactically valid uri authority.
*/
/**
* Get the headers associated with the Request.
*
* The returned `headers` resource is immutable: `set`, `append`, and
* `delete` operations will fail with `header-error.immutable`.
*
* This headers resource is a child: it must be dropped before the parent
* `outgoing-request` is dropped, or its ownership is transfered to
* another component by e.g. `outgoing-handler.handle`.
*/
/**
* Construct a default `request-options` value.
*/
export { RequestOptions };
/**
* The timeout for the initial connect to the HTTP Server.
*/
/**
* Set the timeout for the initial connect to the HTTP Server. An error
* return value indicates that this timeout is not supported.
*/
/**
* The timeout for receiving the first byte of the Response body.
*/
/**
* Set the timeout for receiving the first byte of the Response body. An
* error return value indicates that this timeout is not supported.
*/
/**
* The timeout for receiving subsequent chunks of bytes in the Response
* body stream.
*/
/**
* Set the timeout for receiving subsequent chunks of bytes in the Response
* body stream. An error return value indicates that this timeout is not
* supported.
*/
/**
* Set the value of the `response-outparam` to either send a response,
* or indicate an error.
*
* This method consumes the `response-outparam` to ensure that it is
* called at most once. If it is never called, the implementation
* will respond with an error.
*
* The user may provide an `error` to `response` to allow the
* implementation determine how to respond with an HTTP error response.
*/
export { ResponseOutparam };
/**
* Returns the status code from the incoming response.
*/
export { IncomingResponse };
/**
* Returns the headers from the incoming response.
*
* The returned `headers` resource is immutable: `set`, `append`, and
* `delete` operations will fail with `header-error.immutable`.
*
* This headers resource is a child: it must be dropped before the parent
* `incoming-response` is dropped.
*/
/**
* Returns the incoming body. May be called at most once. Returns error
* if called additional times.
*/
/**
* Returns the contents of the body, as a stream of bytes.
*
* Returns success on first call: the stream representing the contents
* can be retrieved at most once. Subsequent calls will return error.
*
* The returned `input-stream` resource is a child: it must be dropped
* before the parent `incoming-body` is dropped, or consumed by
* `incoming-body.finish`.
*
* This invariant ensures that the implementation can determine whether
* the user is consuming the contents of the body, waiting on the
* `future-trailers` to be ready, or neither. This allows for network
* backpressure is to be applied when the user is consuming the body,
* and for that backpressure to not inhibit delivery of the trailers if
* the user does not read the entire body.
*/
export { IncomingBody };
/**
* Takes ownership of `incoming-body`, and returns a `future-trailers`.
* This function will trap if the `input-stream` child is still alive.
*/
/**
* Returns a pollable which becomes ready when either the trailers have
* been received, or an error has occured. When this pollable is ready,
* the `get` method will return `some`.
*/
export { FutureTrailers };
/**
* Returns the contents of the trailers, or an error which occured,
* once the future is ready.
*
* The outer `option` represents future readiness. Users can wait on this
* `option` to become `some` using the `subscribe` method.
*
* The outer `result` is used to retrieve the trailers or error at most
* once. It will be success on the first call in which the outer option
* is `some`, and error on subsequent calls.
*
* The inner `result` represents that either the HTTP Request or Response
* body, as well as any trailers, were received successfully, or that an
* error occured receiving them. The optional `trailers` indicates whether
* or not trailers were present in the body.
*
* When some `trailers` are returned by this method, the `trailers`
* resource is immutable, and a child. Use of the `set`, `append`, or
* `delete` methods will return an error, and the resource must be
* dropped before the parent `future-trailers` is dropped.
*/
/**
* Construct an `outgoing-response`, with a default `status-code` of `200`.
* If a different `status-code` is needed, it must be set via the
* `set-status-code` method.
*
* * `headers` is the HTTP Headers for the Response.
*/
export { OutgoingResponse };
/**
* Get the HTTP Status Code for the Response.
*/
/**
* Set the HTTP Status Code for the Response. Fails if the status-code
* given is not a valid http status code.
*/
/**
* Get the headers associated with the Request.
*
* The returned `headers` resource is immutable: `set`, `append`, and
* `delete` operations will fail with `header-error.immutable`.
*
* This headers resource is a child: it must be dropped before the parent
* `outgoing-request` is dropped, or its ownership is transfered to
* another component by e.g. `outgoing-handler.handle`.
*/
/**
* Returns the resource corresponding to the outgoing Body for this Response.
*
* Returns success on the first call: the `outgoing-body` resource for
* this `outgoing-response` can be retrieved at most once. Subsequent
* calls will return error.
*/
/**
* Returns a stream for writing the body contents.
*
* The returned `output-stream` is a child resource: it must be dropped
* before the parent `outgoing-body` resource is dropped (or finished),
* otherwise the `outgoing-body` drop or `finish` will trap.
*
* Returns success on the first call: the `output-stream` resource for
* this `outgoing-body` may be retrieved at most once. Subsequent calls
* will return error.
*/
export { OutgoingBody };
/**
* Finalize an outgoing body, optionally providing trailers. This must be
* called to signal that the response is complete. If the `outgoing-body`
* is dropped without calling `outgoing-body.finalize`, the implementation
* should treat the body as corrupted.
*
* Fails if the body's `outgoing-request` or `outgoing-response` was
* constructed with a Content-Length header, and the contents written
* to the body (via `write`) does not match the value given in the
* Content-Length.
*/
/**
* Returns a pollable which becomes ready when either the Response has
* been received, or an error has occured. When this pollable is ready,
* the `get` method will return `some`.
*/
export { FutureIncomingResponse };
/**
* Returns the incoming HTTP Response, or an error, once one is ready.
*
* The outer `option` represents future readiness. Users can wait on this
* `option` to become `some` using the `subscribe` method.
*
* The outer `result` is used to retrieve the response or error at most
* once. It will be success on the first call in which the outer option
* is `some`, and error on subsequent calls.
*
* The inner `result` represents that either the incoming HTTP Response
* status and headers have recieved successfully, or that an error
* occured. Errors may also occur while consuming the response body,
* but those will be reported by the `incoming-body` and its
* `output-stream` child.
*/
}

@@ -633,83 +304,412 @@ import type { Duration } from './wasi-clocks-monotonic-clock.js';

export class OutgoingResponse {
constructor(headers: Headers)
statusCode(): StatusCode;
setStatusCode(statusCode: StatusCode): void;
headers(): Headers;
body(): OutgoingBody;
export class Fields {
/**
* Construct an empty HTTP Fields.
*
* The resulting `fields` is mutable.
*/
constructor()
/**
* Construct an HTTP Fields.
*
* The resulting `fields` is mutable.
*
* The list represents each key-value pair in the Fields. Keys
* which have multiple values are represented by multiple entries in this
* list with the same key.
*
* The tuple is a pair of the field key, represented as a string, and
* Value, represented as a list of bytes. In a valid Fields, all keys
* and values are valid UTF-8 strings. However, values are not always
* well-formed, so they are represented as a raw list of bytes.
*
* An error result will be returned if any header or value was
* syntactically invalid, or if a header was forbidden.
*/
static fromList(entries: [FieldKey, FieldValue][]): Fields;
/**
* Get all of the values corresponding to a key. If the key is not present
* in this `fields`, an empty list is returned. However, if the key is
* present but empty, this is represented by a list with one or more
* empty field-values present.
*/
get(name: FieldKey): FieldValue[];
/**
* Returns `true` when the key is present in this `fields`. If the key is
* syntactically invalid, `false` is returned.
*/
has(name: FieldKey): boolean;
/**
* Set all of the values for a key. Clears any existing values for that
* key, if they have been set.
*
* Fails with `header-error.immutable` if the `fields` are immutable.
*/
set(name: FieldKey, value: FieldValue[]): void;
/**
* Delete all values for a key. Does nothing if no values for the key
* exist.
*
* Fails with `header-error.immutable` if the `fields` are immutable.
*/
'delete'(name: FieldKey): void;
/**
* Append a value for a key. Does not change or delete any existing
* values for that key.
*
* Fails with `header-error.immutable` if the `fields` are immutable.
*/
append(name: FieldKey, value: FieldValue): void;
/**
* Retrieve the full set of keys and values in the Fields. Like the
* constructor, the list represents each key-value pair.
*
* The outer list represents each key-value pair in the Fields. Keys
* which have multiple values are represented by multiple entries in this
* list with the same key.
*/
entries(): [FieldKey, FieldValue][];
/**
* Make a deep copy of the Fields. Equivelant in behavior to calling the
* `fields` constructor on the return value of `entries`. The resulting
* `fields` is mutable.
*/
clone(): Fields;
}
export class OutgoingBody {
write(): OutputStream;
static finish(this_: OutgoingBody, trailers: Trailers | undefined): void;
export class FutureIncomingResponse {
/**
* Returns a pollable which becomes ready when either the Response has
* been received, or an error has occured. When this pollable is ready,
* the `get` method will return `some`.
*/
subscribe(): Pollable;
/**
* Returns the incoming HTTP Response, or an error, once one is ready.
*
* The outer `option` represents future readiness. Users can wait on this
* `option` to become `some` using the `subscribe` method.
*
* The outer `result` is used to retrieve the response or error at most
* once. It will be success on the first call in which the outer option
* is `some`, and error on subsequent calls.
*
* The inner `result` represents that either the incoming HTTP Response
* status and headers have recieved successfully, or that an error
* occured. Errors may also occur while consuming the response body,
* but those will be reported by the `incoming-body` and its
* `output-stream` child.
*/
get(): Result<Result<IncomingResponse, ErrorCode>, void> | undefined;
}
export class FutureTrailers {
/**
* Returns a pollable which becomes ready when either the trailers have
* been received, or an error has occured. When this pollable is ready,
* the `get` method will return `some`.
*/
subscribe(): Pollable;
/**
* Returns the contents of the trailers, or an error which occured,
* once the future is ready.
*
* The outer `option` represents future readiness. Users can wait on this
* `option` to become `some` using the `subscribe` method.
*
* The outer `result` is used to retrieve the trailers or error at most
* once. It will be success on the first call in which the outer option
* is `some`, and error on subsequent calls.
*
* The inner `result` represents that either the HTTP Request or Response
* body, as well as any trailers, were received successfully, or that an
* error occured receiving them. The optional `trailers` indicates whether
* or not trailers were present in the body.
*
* When some `trailers` are returned by this method, the `trailers`
* resource is immutable, and a child. Use of the `set`, `append`, or
* `delete` methods will return an error, and the resource must be
* dropped before the parent `future-trailers` is dropped.
*/
get(): Result<Result<Trailers | undefined, ErrorCode>, void> | undefined;
}
export class IncomingBody {
/**
* Returns the contents of the body, as a stream of bytes.
*
* Returns success on first call: the stream representing the contents
* can be retrieved at most once. Subsequent calls will return error.
*
* The returned `input-stream` resource is a child: it must be dropped
* before the parent `incoming-body` is dropped, or consumed by
* `incoming-body.finish`.
*
* This invariant ensures that the implementation can determine whether
* the user is consuming the contents of the body, waiting on the
* `future-trailers` to be ready, or neither. This allows for network
* backpressure is to be applied when the user is consuming the body,
* and for that backpressure to not inhibit delivery of the trailers if
* the user does not read the entire body.
*/
stream(): InputStream;
/**
* Takes ownership of `incoming-body`, and returns a `future-trailers`.
* This function will trap if the `input-stream` child is still alive.
*/
static finish(this_: IncomingBody): FutureTrailers;
}
export class IncomingRequest {
/**
* Returns the method of the incoming request.
*/
method(): Method;
/**
* Returns the path with query parameters from the request, as a string.
*/
pathWithQuery(): string | undefined;
/**
* Returns the protocol scheme from the request.
*/
scheme(): Scheme | undefined;
/**
* Returns the authority from the request, if it was present.
*/
authority(): string | undefined;
/**
* Get the `headers` associated with the request.
*
* The returned `headers` resource is immutable: `set`, `append`, and
* `delete` operations will fail with `header-error.immutable`.
*
* The `headers` returned are a child resource: it must be dropped before
* the parent `incoming-request` is dropped. Dropping this
* `incoming-request` before all children are dropped will trap.
*/
headers(): Headers;
/**
* Gives the `incoming-body` associated with this request. Will only
* return success at most once, and subsequent calls will return error.
*/
consume(): IncomingBody;
}
export class IncomingResponse {
/**
* Returns the status code from the incoming response.
*/
status(): StatusCode;
/**
* Returns the headers from the incoming response.
*
* The returned `headers` resource is immutable: `set`, `append`, and
* `delete` operations will fail with `header-error.immutable`.
*
* This headers resource is a child: it must be dropped before the parent
* `incoming-response` is dropped.
*/
headers(): Headers;
/**
* Returns the incoming body. May be called at most once. Returns error
* if called additional times.
*/
consume(): IncomingBody;
}
export class RequestOptions {
constructor()
connectTimeout(): Duration | undefined;
setConnectTimeout(duration: Duration | undefined): void;
firstByteTimeout(): Duration | undefined;
setFirstByteTimeout(duration: Duration | undefined): void;
betweenBytesTimeout(): Duration | undefined;
setBetweenBytesTimeout(duration: Duration | undefined): void;
export class OutgoingBody {
/**
* Returns a stream for writing the body contents.
*
* The returned `output-stream` is a child resource: it must be dropped
* before the parent `outgoing-body` resource is dropped (or finished),
* otherwise the `outgoing-body` drop or `finish` will trap.
*
* Returns success on the first call: the `output-stream` resource for
* this `outgoing-body` may be retrieved at most once. Subsequent calls
* will return error.
*/
write(): OutputStream;
/**
* Finalize an outgoing body, optionally providing trailers. This must be
* called to signal that the response is complete. If the `outgoing-body`
* is dropped without calling `outgoing-body.finalize`, the implementation
* should treat the body as corrupted.
*
* Fails if the body's `outgoing-request` or `outgoing-response` was
* constructed with a Content-Length header, and the contents written
* to the body (via `write`) does not match the value given in the
* Content-Length.
*/
static finish(this_: OutgoingBody, trailers: Trailers | undefined): void;
}
export class OutgoingRequest {
/**
* Construct a new `outgoing-request` with a default `method` of `GET`, and
* `none` values for `path-with-query`, `scheme`, and `authority`.
*
* * `headers` is the HTTP Headers for the Request.
*
* It is possible to construct, or manipulate with the accessor functions
* below, an `outgoing-request` with an invalid combination of `scheme`
* and `authority`, or `headers` which are not permitted to be sent.
* It is the obligation of the `outgoing-handler.handle` implementation
* to reject invalid constructions of `outgoing-request`.
*/
constructor(headers: Headers)
/**
* Returns the resource corresponding to the outgoing Body for this
* Request.
*
* Returns success on the first call: the `outgoing-body` resource for
* this `outgoing-request` can be retrieved at most once. Subsequent
* calls will return error.
*/
body(): OutgoingBody;
/**
* Get the Method for the Request.
*/
method(): Method;
/**
* Set the Method for the Request. Fails if the string present in a
* `method.other` argument is not a syntactically valid method.
*/
setMethod(method: Method): void;
/**
* Get the combination of the HTTP Path and Query for the Request.
* When `none`, this represents an empty Path and empty Query.
*/
pathWithQuery(): string | undefined;
/**
* Set the combination of the HTTP Path and Query for the Request.
* When `none`, this represents an empty Path and empty Query. Fails is the
* string given is not a syntactically valid path and query uri component.
*/
setPathWithQuery(pathWithQuery: string | undefined): void;
/**
* Get the HTTP Related Scheme for the Request. When `none`, the
* implementation may choose an appropriate default scheme.
*/
scheme(): Scheme | undefined;
/**
* Set the HTTP Related Scheme for the Request. When `none`, the
* implementation may choose an appropriate default scheme. Fails if the
* string given is not a syntactically valid uri scheme.
*/
setScheme(scheme: Scheme | undefined): void;
/**
* Get the HTTP Authority for the Request. A value of `none` may be used
* with Related Schemes which do not require an Authority. The HTTP and
* HTTPS schemes always require an authority.
*/
authority(): string | undefined;
/**
* Set the HTTP Authority for the Request. A value of `none` may be used
* with Related Schemes which do not require an Authority. The HTTP and
* HTTPS schemes always require an authority. Fails if the string given is
* not a syntactically valid uri authority.
*/
setAuthority(authority: string | undefined): void;
/**
* Get the headers associated with the Request.
*
* The returned `headers` resource is immutable: `set`, `append`, and
* `delete` operations will fail with `header-error.immutable`.
*
* This headers resource is a child: it must be dropped before the parent
* `outgoing-request` is dropped, or its ownership is transfered to
* another component by e.g. `outgoing-handler.handle`.
*/
headers(): Headers;
}
export class IncomingRequest {
method(): Method;
pathWithQuery(): string | undefined;
scheme(): Scheme | undefined;
authority(): string | undefined;
export class OutgoingResponse {
/**
* Construct an `outgoing-response`, with a default `status-code` of `200`.
* If a different `status-code` is needed, it must be set via the
* `set-status-code` method.
*
* * `headers` is the HTTP Headers for the Response.
*/
constructor(headers: Headers)
/**
* Get the HTTP Status Code for the Response.
*/
statusCode(): StatusCode;
/**
* Set the HTTP Status Code for the Response. Fails if the status-code
* given is not a valid http status code.
*/
setStatusCode(statusCode: StatusCode): void;
/**
* Get the headers associated with the Request.
*
* The returned `headers` resource is immutable: `set`, `append`, and
* `delete` operations will fail with `header-error.immutable`.
*
* This headers resource is a child: it must be dropped before the parent
* `outgoing-request` is dropped, or its ownership is transfered to
* another component by e.g. `outgoing-handler.handle`.
*/
headers(): Headers;
consume(): IncomingBody;
/**
* Returns the resource corresponding to the outgoing Body for this Response.
*
* Returns success on the first call: the `outgoing-body` resource for
* this `outgoing-response` can be retrieved at most once. Subsequent
* calls will return error.
*/
body(): OutgoingBody;
}
export class Fields {
export class RequestOptions {
/**
* Construct a default `request-options` value.
*/
constructor()
static fromList(entries: [FieldKey, FieldValue][]): Fields;
get(name: FieldKey): FieldValue[];
has(name: FieldKey): boolean;
set(name: FieldKey, value: FieldValue[]): void;
'delete'(name: FieldKey): void;
append(name: FieldKey, value: FieldValue): void;
entries(): [FieldKey, FieldValue][];
clone(): Fields;
/**
* The timeout for the initial connect to the HTTP Server.
*/
connectTimeout(): Duration | undefined;
/**
* Set the timeout for the initial connect to the HTTP Server. An error
* return value indicates that this timeout is not supported.
*/
setConnectTimeout(duration: Duration | undefined): void;
/**
* The timeout for receiving the first byte of the Response body.
*/
firstByteTimeout(): Duration | undefined;
/**
* Set the timeout for receiving the first byte of the Response body. An
* error return value indicates that this timeout is not supported.
*/
setFirstByteTimeout(duration: Duration | undefined): void;
/**
* The timeout for receiving subsequent chunks of bytes in the Response
* body stream.
*/
betweenBytesTimeout(): Duration | undefined;
/**
* Set the timeout for receiving subsequent chunks of bytes in the Response
* body stream. An error return value indicates that this timeout is not
* supported.
*/
setBetweenBytesTimeout(duration: Duration | undefined): void;
}
export class FutureTrailers {
subscribe(): Pollable;
get(): Result<Result<Trailers | undefined, ErrorCode>, void> | undefined;
}
export class FutureIncomingResponse {
subscribe(): Pollable;
get(): Result<Result<IncomingResponse, ErrorCode>, void> | undefined;
}
export class IncomingBody {
stream(): InputStream;
static finish(this_: IncomingBody): FutureTrailers;
}
export class ResponseOutparam {
/**
* Set the value of the `response-outparam` to either send a response,
* or indicate an error.
*
* This method consumes the `response-outparam` to ensure that it is
* called at most once. If it is never called, the implementation
* will respond with an error.
*
* The user may provide an `error` to `response` to allow the
* implementation determine how to respond with an HTTP error response.
*/
static set(param: ResponseOutparam, response: Result<OutgoingResponse, ErrorCode>): void;
}

18

types/interfaces/wasi-io-error.d.ts
export namespace WasiIoError {
/**
* Returns a string that is suitable to assist humans in debugging
* this error.
*
* WARNING: The returned string should not be consumed mechanically!
* It may change across platforms, hosts, or other implementation
* details. Parsing this string is a major platform-compatibility
* hazard.
*/
export { Error };

@@ -15,3 +6,12 @@ }

export class Error {
/**
* Returns a string that is suitable to assist humans in debugging
* this error.
*
* WARNING: The returned string should not be consumed mechanically!
* It may change across platforms, hosts, or other implementation
* details. Parsing this string is a major platform-compatibility
* hazard.
*/
toDebugString(): string;
}

24

types/interfaces/wasi-io-poll.d.ts
export namespace WasiIoPoll {
/**
* Return the readiness of a pollable. This function never blocks.
*
* Returns `true` when the pollable is ready, and `false` otherwise.
*/
export { Pollable };
/**
* `block` returns immediately if the pollable is ready, and otherwise
* blocks until ready.
*
* This function is equivalent to calling `poll.poll` on a list
* containing only this pollable.
*/
/**
* Poll for completion on a set of pollables.

@@ -39,4 +27,16 @@ *

export class Pollable {
/**
* Return the readiness of a pollable. This function never blocks.
*
* Returns `true` when the pollable is ready, and `false` otherwise.
*/
ready(): boolean;
/**
* `block` returns immediately if the pollable is ready, and otherwise
* blocks until ready.
*
* This function is equivalent to calling `poll.poll` on a list
* containing only this pollable.
*/
block(): void;
}

436

types/interfaces/wasi-io-streams.d.ts
export namespace WasiIoStreams {
/**
* Perform a non-blocking read from the stream.
*
* When the source of a `read` is binary data, the bytes from the source
* are returned verbatim. When the source of a `read` is known to the
* implementation to be text, bytes containing the UTF-8 encoding of the
* text are returned.
*
* This function returns a list of bytes containing the read data,
* when successful. The returned list will contain up to `len` bytes;
* it may return fewer than requested, but not more. The list is
* empty when no bytes are available for reading at this time. The
* pollable given by `subscribe` will be ready when more bytes are
* available.
*
* This function fails with a `stream-error` when the operation
* encounters an error, giving `last-operation-failed`, or when the
* stream is closed, giving `closed`.
*
* When the caller gives a `len` of 0, it represents a request to
* read 0 bytes. If the stream is still open, this call should
* succeed and return an empty list, or otherwise fail with `closed`.
*
* 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 { InputStream };
export { OutputStream };
}
import type { Error } from './wasi-io-error.js';
export { Error };
import type { Pollable } from './wasi-io-poll.js';
export { Pollable };
/**
* An error for input-stream and output-stream operations.
*/
export type StreamError = StreamErrorLastOperationFailed | StreamErrorClosed;
/**
* The last operation (a write or flush) failed before completion.
*
* More information is available in the `error` payload.
*/
export interface StreamErrorLastOperationFailed {
tag: 'last-operation-failed',
val: Error,
}
/**
* 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 interface StreamErrorClosed {
tag: 'closed',
}
export class InputStream {
/**
* Read bytes from a stream, after blocking until at least one byte can
* be read. Except for blocking, behavior is identical to `read`.
*/
* Perform a non-blocking read from the stream.
*
* When the source of a `read` is binary data, the bytes from the source
* are returned verbatim. When the source of a `read` is known to the
* implementation to be text, bytes containing the UTF-8 encoding of the
* text are returned.
*
* This function returns a list of bytes containing the read data,
* when successful. The returned list will contain up to `len` bytes;
* it may return fewer than requested, but not more. The list is
* empty when no bytes are available for reading at this time. The
* pollable given by `subscribe` will be ready when more bytes are
* available.
*
* This function fails with a `stream-error` when the operation
* encounters an error, giving `last-operation-failed`, or when the
* stream is closed, giving `closed`.
*
* When the caller gives a `len` of 0, it represents a request to
* read 0 bytes. If the stream is still open, this call should
* succeed and return an empty list, or otherwise fail with `closed`.
*
* 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.
*/
read(len: bigint): Uint8Array;
/**
* Skip bytes from a stream. Returns number of bytes skipped.
*
* Behaves identical to `read`, except instead of returning a list
* of bytes, returns the number of bytes consumed from the stream.
*/
* Read bytes from a stream, after blocking until at least one byte can
* be read. Except for blocking, behavior is identical to `read`.
*/
blockingRead(len: bigint): Uint8Array;
/**
* Skip bytes from a stream, after blocking until at least one byte
* can be skipped. Except for blocking behavior, identical to `skip`.
*/
* Skip bytes from a stream. Returns number of bytes skipped.
*
* Behaves identical to `read`, except instead of returning a list
* of bytes, returns the number of bytes consumed from the stream.
*/
skip(len: bigint): bigint;
/**
* 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.
*/
* Skip bytes from a stream, after blocking until at least one byte
* can be skipped. Except for blocking behavior, identical to `skip`.
*/
blockingSkip(len: bigint): bigint;
/**
* 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` pollable will
* become ready when this function will report at least 1 byte, or an
* error.
*/
export { OutputStream };
* 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.
*/
subscribe(): Pollable;
}
export class OutputStream {
/**
* Perform a write. This function never blocks.
*
* When the destination of a `write` is binary data, the bytes from
* `contents` are written verbatim. When the destination of a `write` is
* known to the implementation to be text, the bytes of `contents` are
* transcoded from UTF-8 into the encoding of the destination and then
* written.
*
* Precondition: check-write gave permit of Ok(n) and contents has a
* length of less than or equal to n. Otherwise, this function will trap.
*
* returns Err(closed) without writing if the stream has closed since
* the last call to check-write provided a permit.
*/
* 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` pollable will
* become ready when this function will report at least 1 byte, or an
* error.
*/
checkWrite(): bigint;
/**
* 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`, `write`, and `flush`, and is implemented with the
* following pseudo-code:
*
* ```text
* let pollable = this.subscribe();
* while !contents.is_empty() {
* // Wait for the stream to become writable
* pollable.block();
* let Ok(n) = this.check-write(); // eliding error handling
* let len = min(n, contents.len());
* let (chunk, rest) = contents.split_at(len);
* this.write(chunk ); // eliding error handling
* contents = rest;
* }
* this.flush();
* // Wait for completion of `flush`
* pollable.block();
* // Check for any errors that arose during `flush`
* let _ = this.check-write(); // eliding error handling
* ```
*/
* Perform a write. This function never blocks.
*
* When the destination of a `write` is binary data, the bytes from
* `contents` are written verbatim. When the destination of a `write` is
* known to the implementation to be text, the bytes of `contents` are
* transcoded from UTF-8 into the encoding of the destination and then
* written.
*
* Precondition: check-write gave permit of Ok(n) and contents has a
* length of less than or equal to n. Otherwise, this function will trap.
*
* returns Err(closed) without writing if the stream has closed since
* the last call to check-write provided a permit.
*/
write(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`, `write`, and `flush`, and is implemented with the
* following pseudo-code:
*
* ```text
* let pollable = this.subscribe();
* while !contents.is_empty() {
* // Wait for the stream to become writable
* pollable.block();
* let Ok(n) = this.check-write(); // eliding error handling
* let len = min(n, contents.len());
* let (chunk, rest) = contents.split_at(len);
* this.write(chunk ); // eliding error handling
* contents = rest;
* }
* this.flush();
* // Wait for completion of `flush`
* pollable.block();
* // Check for any errors that arose during `flush`
* let _ = this.check-write(); // eliding error handling
* ```
*/
blockingWriteAndFlush(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` pollable will become ready when the
* flush has completed and the stream can accept more writes.
*/
* 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` pollable will become ready when the
* flush has completed and the stream can accept more writes.
*/
flush(): void;
/**
* Request to flush buffered output, and block until flush completes
* and stream is ready for writing again.
*/
* Request to flush buffered output, and block until flush completes
* and stream is ready for writing again.
*/
blockingFlush(): 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.
*/
* 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.
*/
subscribe(): 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.
*/
* 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.
*/
writeZeroes(len: bigint): void;
/**
* Perform a write of up to 4096 zeroes, 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`, `write-zeroes`, and `flush`, and is implemented with
* the following pseudo-code:
*
* ```text
* let pollable = this.subscribe();
* while num_zeroes != 0 {
* // Wait for the stream to become writable
* pollable.block();
* let Ok(n) = this.check-write(); // eliding error handling
* let len = min(n, num_zeroes);
* this.write-zeroes(len); // eliding error handling
* num_zeroes -= len;
* }
* this.flush();
* // Wait for completion of `flush`
* pollable.block();
* // Check for any errors that arose during `flush`
* let _ = this.check-write(); // eliding error handling
* ```
*/
* Perform a write of up to 4096 zeroes, 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`, `write-zeroes`, and `flush`, and is implemented with
* the following pseudo-code:
*
* ```text
* let pollable = this.subscribe();
* while num_zeroes != 0 {
* // Wait for the stream to become writable
* pollable.block();
* let Ok(n) = this.check-write(); // eliding error handling
* let len = min(n, num_zeroes);
* this.write-zeroes(len); // eliding error handling
* num_zeroes -= len;
* }
* this.flush();
* // Wait for completion of `flush`
* pollable.block();
* // Check for any errors that arose during `flush`
* let _ = this.check-write(); // eliding error handling
* ```
*/
blockingWriteZeroesAndFlush(len: bigint): void;
/**
* Read from one stream and write to another.
*
* The behavior of splice is equivelant to:
* 1. calling `check-write` on the `output-stream`
* 2. calling `read` on the `input-stream` with the smaller of the
* `check-write` permitted length and the `len` provided to `splice`
* 3. calling `write` on the `output-stream` with that read data.
*
* Any error reported by the call to `check-write`, `read`, or
* `write` ends the splice and reports that error.
*
* This function returns the number of bytes transferred; it may be less
* than `len`.
*/
* Read from one stream and write to another.
*
* The behavior of splice is equivelant to:
* 1. calling `check-write` on the `output-stream`
* 2. calling `read` on the `input-stream` with the smaller of the
* `check-write` permitted length and the `len` provided to `splice`
* 3. calling `write` on the `output-stream` with that read data.
*
* Any error reported by the call to `check-write`, `read`, or
* `write` ends the splice and reports that error.
*
* This function returns the number of bytes transferred; it may be less
* than `len`.
*/
splice(src: InputStream, len: bigint): bigint;
/**
* Read from one stream and write to another, with blocking.
*
* This is similar to `splice`, except that it blocks until the
* `output-stream` is ready for writing, and the `input-stream`
* is ready for reading, before performing the `splice`.
*/
}
import type { Error } from './wasi-io-error.js';
export { Error };
import type { Pollable } from './wasi-io-poll.js';
export { Pollable };
/**
* An error for input-stream and output-stream operations.
*/
export type StreamError = StreamErrorLastOperationFailed | StreamErrorClosed;
/**
* The last operation (a write or flush) failed before completion.
*
* More information is available in the `error` payload.
*/
export interface StreamErrorLastOperationFailed {
tag: 'last-operation-failed',
val: Error,
}
/**
* 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 interface StreamErrorClosed {
tag: 'closed',
}
export class InputStream {
read(len: bigint): Uint8Array;
blockingRead(len: bigint): Uint8Array;
skip(len: bigint): bigint;
blockingSkip(len: bigint): bigint;
subscribe(): Pollable;
}
export class OutputStream {
checkWrite(): bigint;
write(contents: Uint8Array): void;
blockingWriteAndFlush(contents: Uint8Array): void;
flush(): void;
blockingFlush(): void;
subscribe(): Pollable;
writeZeroes(len: bigint): void;
blockingWriteZeroesAndFlush(len: bigint): void;
splice(src: InputStream, len: bigint): bigint;
* Read from one stream and write to another, with blocking.
*
* This is similar to `splice`, except that it blocks until the
* `output-stream` is ready for writing, and the `input-stream`
* is ready for reading, before performing the `splice`.
*/
blockingSplice(src: InputStream, len: bigint): bigint;
}

42

types/interfaces/wasi-sockets-ip-name-lookup.d.ts

@@ -25,24 +25,3 @@ export namespace WasiSocketsIpNameLookup {

export function resolveAddresses(network: Network, name: string): 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`.
*
* 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 { ResolveAddressStream };
/**
* 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.
*/
}

@@ -59,4 +38,25 @@ import type { Pollable } from './wasi-io-poll.js';

export class 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`.
*
* 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)
*/
resolveNextAddress(): IpAddress | undefined;
/**
* 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.
*/
subscribe(): Pollable;
}

602

types/interfaces/wasi-sockets-tcp.d.ts
export namespace WasiSocketsTcp {
/**
* 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.
*
* Bind can be attempted multiple times on the same socket, even with
* different arguments on each iteration. But never concurrently and
* only as long as the previous bind failed. Once a bind succeeds, the
* binding can't be changed anymore.
*
* # Typical errors
* - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
* - `invalid-argument`: `local-address` is not a unicast address. (EINVAL)
* - `invalid-argument`: `local-address` is an IPv4-mapped IPv6 address. (EINVAL)
* - `invalid-state`: The socket is already bound. (EINVAL)
* - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
* - `address-in-use`: Address is already in use. (EADDRINUSE)
* - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
* - `not-in-progress`: A `bind` operation is not in progress.
* - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
*
* # Implementors note
* When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
* state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
* socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
* and SO_REUSEADDR performs something different entirely.
*
* Unlike in POSIX, in WASI the bind operation is async. This enables
* interactive WASI hosts to inject permission prompts. Runtimes that
* don't want to make use of this ability can simply call the native
* `bind` as part of either `start-bind` or `finish-bind`.
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
* - <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 { TcpSocket };
/**
* Connect to a remote endpoint.
*
* On success:
* - the socket is transitioned into the `connection` state.
* - a pair of streams is returned that can be used to read & write to the connection
*
* After a failed connection attempt, the socket will be in the `closed`
* state and the only valid action left is to `drop` the socket. A single
* socket can not be used to connect more than once.
*
* # Typical errors
* - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
* - `invalid-argument`: `remote-address` is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
* - `invalid-argument`: `remote-address` is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)
* - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows)
* - `invalid-argument`: The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows)
* - `invalid-argument`: The socket is already attached to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
* - `invalid-state`: The socket is already in the `connected` state. (EISCONN)
* - `invalid-state`: The socket is already in the `listening` state. (EOPNOTSUPP, EINVAL on Windows)
* - `timeout`: Connection timed out. (ETIMEDOUT)
* - `connection-refused`: The connection was forcefully rejected. (ECONNREFUSED)
* - `connection-reset`: The connection was reset. (ECONNRESET)
* - `connection-aborted`: The connection was aborted. (ECONNABORTED)
* - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
* - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
* - `not-in-progress`: A connect operation is not in progress.
* - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
*
* # Implementors note
* The POSIX equivalent of `start-connect` is the regular `connect` syscall.
* Because all WASI sockets are non-blocking this is expected to return
* EINPROGRESS, which should be translated to `ok()` in WASI.
*
* The POSIX equivalent of `finish-connect` is a `poll` for event `POLLOUT`
* with a timeout of 0 on the socket descriptor. Followed by a check for
* the `SO_ERROR` socket option, in case the poll signaled readiness.
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
* - <https://man7.org/linux/man-pages/man2/connect.2.html>
* - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
* - <https://man.freebsd.org/cgi/man.cgi?connect>
*/
/**
* Start listening for new connections.
*
* Transitions the socket into the `listening` state.
*
* Unlike POSIX, the socket must already be explicitly bound.
*
* # Typical errors
* - `invalid-state`: The socket is not bound to any local address. (EDESTADDRREQ)
* - `invalid-state`: The socket is already in the `connected` state. (EISCONN, EINVAL on BSD)
* - `invalid-state`: The socket is already in the `listening` state.
* - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
* - `not-in-progress`: A listen operation is not in progress.
* - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
*
* # Implementors note
* Unlike in POSIX, in WASI the listen operation is async. This enables
* interactive WASI hosts to inject permission prompts. Runtimes that
* don't want to make use of this ability can simply call the native
* `listen` as part of either `start-listen` or `finish-listen`.
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html>
* - <https://man7.org/linux/man-pages/man2/listen.2.html>
* - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen>
* - <https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2>
*/
/**
* Accept a new client socket.
*
* The returned socket is bound and in the `connected` state. The following properties are inherited from the listener socket:
* - `address-family`
* - `keep-alive-enabled`
* - `keep-alive-idle-time`
* - `keep-alive-interval`
* - `keep-alive-count`
* - `hop-limit`
* - `receive-buffer-size`
* - `send-buffer-size`
*
* On success, this function returns the newly accepted client socket along with
* a pair of streams that can be used to read & write to the connection.
*
* # Typical errors
* - `invalid-state`: Socket is not in the `listening` state. (EINVAL)
* - `would-block`: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
* - `connection-aborted`: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
* - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html>
* - <https://man7.org/linux/man-pages/man2/accept.2.html>
* - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept>
* - <https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2>
*/
/**
* Get the bound local address.
*
* POSIX mentions:
* > If the socket has not been bound to a local name, the value
* > stored in the object pointed to by `address` is unspecified.
*
* WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
*
* # Typical errors
* - `invalid-state`: 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>
*/
/**
* Get the remote address.
*
* # Typical errors
* - `invalid-state`: 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>
*/
/**
* Whether the socket is in the `listening` state.
*
* Equivalent to the SO_ACCEPTCONN socket option.
*/
/**
* Whether this is a IPv4 or IPv6 socket.
*
* Equivalent to the SO_DOMAIN socket option.
*/
/**
* Hints the desired listen queue size. Implementations are free to ignore this.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
*
* # Typical errors
* - `not-supported`: (set) The platform does not support changing the backlog size after the initial listen.
* - `invalid-argument`: (set) The provided value was 0.
* - `invalid-state`: (set) The socket is in the `connect-in-progress` or `connected` state.
*/
/**
* Enables or disables keepalive.
*
* The keepalive behavior can be adjusted using:
* - `keep-alive-idle-time`
* - `keep-alive-interval`
* - `keep-alive-count`
* These properties can be configured while `keep-alive-enabled` is false, but only come into effect when `keep-alive-enabled` is true.
*
* Equivalent to the SO_KEEPALIVE socket option.
*/
/**
* Amount of time the connection has to be idle before TCP starts sending keepalive packets.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
/**
* The time between keepalive packets.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the TCP_KEEPINTVL socket option.
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
/**
* The maximum amount of keepalive packets TCP should send before aborting the connection.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the TCP_KEEPCNT socket option.
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
/**
* Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
*
* If the provided value is 0, an `invalid-argument` error is returned.
*
* # Typical errors
* - `invalid-argument`: (set) The TTL value must be 1 or higher.
*/
/**
* The kernel buffer space reserved for sends/receives on this socket.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
/**
* Create a `pollable` which can be used to poll for, or block on,
* completion of any of the asynchronous operations of this socket.
*
* When `finish-bind`, `finish-listen`, `finish-connect` or `accept`
* return `error(would-block)`, this pollable can be used to wait for
* their success or failure, after which the method can be retried.
*
* The pollable is not limited to the async operation that happens to be
* in progress at the time of calling `subscribe` (if any). Theoretically,
* `subscribe` only has to be called once per socket and can then be
* (re)used for the remainder of the socket's lifetime.
*
* See <https://github.com/WebAssembly/wasi-sockets/TcpSocketOperationalSemantics.md#Pollable-readiness>
* for a more information.
*
* Note: this function is here for WASI Preview2 only.
* It's planned to be removed when `future` is natively supported in Preview3.
*/
/**
* Initiate a graceful shutdown.
*
* - `receive`: The socket is not expecting to receive any data from
* the peer. The `input-stream` associated with this socket will be
* closed. Any data still in the receive queue at time of calling
* this method will be discarded.
* - `send`: The socket has no more data to send to the peer. The `output-stream`
* associated with this socket will be closed and a FIN packet will be sent.
* - `both`: Same effect as `receive` & `send` combined.
*
* This function is idempotent. Shutting a down a direction more than once
* has no effect and returns `ok`.
*
* The shutdown function does not close (drop) the socket.
*
* # Typical errors
* - `invalid-state`: The socket is not in the `connected` state. (ENOTCONN)
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html>
* - <https://man7.org/linux/man-pages/man2/shutdown.2.html>
* - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown>
* - <https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2>
*/
}

@@ -337,24 +36,281 @@ import type { InputStream } from './wasi-io-streams.js';

export class TcpSocket {
/**
* 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.
*
* Bind can be attempted multiple times on the same socket, even with
* different arguments on each iteration. But never concurrently and
* only as long as the previous bind failed. Once a bind succeeds, the
* binding can't be changed anymore.
*
* # Typical errors
* - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
* - `invalid-argument`: `local-address` is not a unicast address. (EINVAL)
* - `invalid-argument`: `local-address` is an IPv4-mapped IPv6 address. (EINVAL)
* - `invalid-state`: The socket is already bound. (EINVAL)
* - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
* - `address-in-use`: Address is already in use. (EADDRINUSE)
* - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
* - `not-in-progress`: A `bind` operation is not in progress.
* - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
*
* # Implementors note
* When binding to a non-zero port, this bind operation shouldn't be affected by the TIME_WAIT
* state of a recently closed socket on the same local address. In practice this means that the SO_REUSEADDR
* socket option should be set implicitly on all platforms, except on Windows where this is the default behavior
* and SO_REUSEADDR performs something different entirely.
*
* Unlike in POSIX, in WASI the bind operation is async. This enables
* interactive WASI hosts to inject permission prompts. Runtimes that
* don't want to make use of this ability can simply call the native
* `bind` as part of either `start-bind` or `finish-bind`.
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
* - <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>
*/
startBind(network: Network, localAddress: IpSocketAddress): void;
finishBind(): void;
/**
* Connect to a remote endpoint.
*
* On success:
* - the socket is transitioned into the `connection` state.
* - a pair of streams is returned that can be used to read & write to the connection
*
* After a failed connection attempt, the socket will be in the `closed`
* state and the only valid action left is to `drop` the socket. A single
* socket can not be used to connect more than once.
*
* # Typical errors
* - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
* - `invalid-argument`: `remote-address` is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
* - `invalid-argument`: `remote-address` is an IPv4-mapped IPv6 address. (EINVAL, EADDRNOTAVAIL on Illumos)
* - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows)
* - `invalid-argument`: The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows)
* - `invalid-argument`: The socket is already attached to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
* - `invalid-state`: The socket is already in the `connected` state. (EISCONN)
* - `invalid-state`: The socket is already in the `listening` state. (EOPNOTSUPP, EINVAL on Windows)
* - `timeout`: Connection timed out. (ETIMEDOUT)
* - `connection-refused`: The connection was forcefully rejected. (ECONNREFUSED)
* - `connection-reset`: The connection was reset. (ECONNRESET)
* - `connection-aborted`: The connection was aborted. (ECONNABORTED)
* - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
* - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
* - `not-in-progress`: A connect operation is not in progress.
* - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
*
* # Implementors note
* The POSIX equivalent of `start-connect` is the regular `connect` syscall.
* Because all WASI sockets are non-blocking this is expected to return
* EINPROGRESS, which should be translated to `ok()` in WASI.
*
* The POSIX equivalent of `finish-connect` is a `poll` for event `POLLOUT`
* with a timeout of 0 on the socket descriptor. Followed by a check for
* the `SO_ERROR` socket option, in case the poll signaled readiness.
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
* - <https://man7.org/linux/man-pages/man2/connect.2.html>
* - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
* - <https://man.freebsd.org/cgi/man.cgi?connect>
*/
startConnect(network: Network, remoteAddress: IpSocketAddress): void;
finishConnect(): [InputStream, OutputStream];
/**
* Start listening for new connections.
*
* Transitions the socket into the `listening` state.
*
* Unlike POSIX, the socket must already be explicitly bound.
*
* # Typical errors
* - `invalid-state`: The socket is not bound to any local address. (EDESTADDRREQ)
* - `invalid-state`: The socket is already in the `connected` state. (EISCONN, EINVAL on BSD)
* - `invalid-state`: The socket is already in the `listening` state.
* - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
* - `not-in-progress`: A listen operation is not in progress.
* - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
*
* # Implementors note
* Unlike in POSIX, in WASI the listen operation is async. This enables
* interactive WASI hosts to inject permission prompts. Runtimes that
* don't want to make use of this ability can simply call the native
* `listen` as part of either `start-listen` or `finish-listen`.
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html>
* - <https://man7.org/linux/man-pages/man2/listen.2.html>
* - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen>
* - <https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2>
*/
startListen(): void;
finishListen(): void;
/**
* Accept a new client socket.
*
* The returned socket is bound and in the `connected` state. The following properties are inherited from the listener socket:
* - `address-family`
* - `keep-alive-enabled`
* - `keep-alive-idle-time`
* - `keep-alive-interval`
* - `keep-alive-count`
* - `hop-limit`
* - `receive-buffer-size`
* - `send-buffer-size`
*
* On success, this function returns the newly accepted client socket along with
* a pair of streams that can be used to read & write to the connection.
*
* # Typical errors
* - `invalid-state`: Socket is not in the `listening` state. (EINVAL)
* - `would-block`: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
* - `connection-aborted`: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
* - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html>
* - <https://man7.org/linux/man-pages/man2/accept.2.html>
* - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept>
* - <https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2>
*/
accept(): [TcpSocket, InputStream, OutputStream];
/**
* Get the bound local address.
*
* POSIX mentions:
* > If the socket has not been bound to a local name, the value
* > stored in the object pointed to by `address` is unspecified.
*
* WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
*
* # Typical errors
* - `invalid-state`: 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>
*/
localAddress(): IpSocketAddress;
/**
* Get the remote address.
*
* # Typical errors
* - `invalid-state`: 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>
*/
remoteAddress(): IpSocketAddress;
/**
* Whether the socket is in the `listening` state.
*
* Equivalent to the SO_ACCEPTCONN socket option.
*/
isListening(): boolean;
/**
* Whether this is a IPv4 or IPv6 socket.
*
* Equivalent to the SO_DOMAIN socket option.
*/
addressFamily(): IpAddressFamily;
/**
* Hints the desired listen queue size. Implementations are free to ignore this.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
*
* # Typical errors
* - `not-supported`: (set) The platform does not support changing the backlog size after the initial listen.
* - `invalid-argument`: (set) The provided value was 0.
* - `invalid-state`: (set) The socket is in the `connect-in-progress` or `connected` state.
*/
setListenBacklogSize(value: bigint): void;
/**
* Enables or disables keepalive.
*
* The keepalive behavior can be adjusted using:
* - `keep-alive-idle-time`
* - `keep-alive-interval`
* - `keep-alive-count`
* These properties can be configured while `keep-alive-enabled` is false, but only come into effect when `keep-alive-enabled` is true.
*
* Equivalent to the SO_KEEPALIVE socket option.
*/
keepAliveEnabled(): boolean;
setKeepAliveEnabled(value: boolean): void;
/**
* Amount of time the connection has to be idle before TCP starts sending keepalive packets.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
keepAliveIdleTime(): Duration;
setKeepAliveIdleTime(value: Duration): void;
/**
* The time between keepalive packets.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the TCP_KEEPINTVL socket option.
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
keepAliveInterval(): Duration;
setKeepAliveInterval(value: Duration): void;
/**
* The maximum amount of keepalive packets TCP should send before aborting the connection.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the TCP_KEEPCNT socket option.
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
keepAliveCount(): number;
setKeepAliveCount(value: number): void;
/**
* Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
*
* If the provided value is 0, an `invalid-argument` error is returned.
*
* # Typical errors
* - `invalid-argument`: (set) The TTL value must be 1 or higher.
*/
hopLimit(): number;
setHopLimit(value: number): void;
/**
* The kernel buffer space reserved for sends/receives on this socket.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
receiveBufferSize(): bigint;

@@ -364,4 +320,48 @@ setReceiveBufferSize(value: bigint): void;

setSendBufferSize(value: bigint): void;
/**
* Create a `pollable` which can be used to poll for, or block on,
* completion of any of the asynchronous operations of this socket.
*
* When `finish-bind`, `finish-listen`, `finish-connect` or `accept`
* return `error(would-block)`, this pollable can be used to wait for
* their success or failure, after which the method can be retried.
*
* The pollable is not limited to the async operation that happens to be
* in progress at the time of calling `subscribe` (if any). Theoretically,
* `subscribe` only has to be called once per socket and can then be
* (re)used for the remainder of the socket's lifetime.
*
* See <https://github.com/WebAssembly/wasi-sockets/TcpSocketOperationalSemantics.md#Pollable-readiness>
* for a more information.
*
* Note: this function is here for WASI Preview2 only.
* It's planned to be removed when `future` is natively supported in Preview3.
*/
subscribe(): Pollable;
/**
* Initiate a graceful shutdown.
*
* - `receive`: The socket is not expecting to receive any data from
* the peer. The `input-stream` associated with this socket will be
* closed. Any data still in the receive queue at time of calling
* this method will be discarded.
* - `send`: The socket has no more data to send to the peer. The `output-stream`
* associated with this socket will be closed and a FIN packet will be sent.
* - `both`: Same effect as `receive` & `send` combined.
*
* This function is idempotent. Shutting a down a direction more than once
* has no effect and returns `ok`.
*
* The shutdown function does not close (drop) the socket.
*
* # Typical errors
* - `invalid-state`: The socket is not in the `connected` state. (ENOTCONN)
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html>
* - <https://man7.org/linux/man-pages/man2/shutdown.2.html>
* - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown>
* - <https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2>
*/
shutdown(shutdownType: ShutdownType): void;
}

552

types/interfaces/wasi-sockets-udp.d.ts
export namespace WasiSocketsUdp {
export { UdpSocket };
export { IncomingDatagramStream };
export { OutgoingDatagramStream };
}
import type { Pollable } from './wasi-io-poll.js';
export { Pollable };
import type { Network } from './wasi-sockets-network.js';
export { Network };
import type { ErrorCode } from './wasi-sockets-network.js';
export { ErrorCode };
import type { IpSocketAddress } from './wasi-sockets-network.js';
export { IpSocketAddress };
import type { IpAddressFamily } from './wasi-sockets-network.js';
export { IpAddressFamily };
/**
* A received datagram.
*/
export interface IncomingDatagram {
/**
* Bind the socket to a specific network on the provided IP address and port.
* The payload.
*
* 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 port is zero, the socket will be bound to a random free port.
* Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
*/
data: Uint8Array,
/**
* The source address.
*
* # Typical errors
* - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
* - `invalid-state`: The socket is already bound. (EINVAL)
* - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
* - `address-in-use`: Address is already in use. (EADDRINUSE)
* - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
* - `not-in-progress`: A `bind` operation is not in progress.
* - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
* This field is guaranteed to match the remote address the stream was initialized with, if any.
*
* # Implementors note
* Unlike in POSIX, in WASI the bind operation is async. This enables
* interactive WASI hosts to inject permission prompts. Runtimes that
* don't want to make use of this ability can simply call the native
* `bind` as part of either `start-bind` or `finish-bind`.
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
* - <https://man7.org/linux/man-pages/man2/bind.2.html>
* - <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>
* Equivalent to the `src_addr` out parameter of `recvfrom`.
*/
export { UdpSocket };
remoteAddress: IpSocketAddress,
}
/**
* A datagram to be sent out.
*/
export interface OutgoingDatagram {
/**
* Set up inbound & outbound communication channels, optionally to a specific peer.
* The payload.
*/
data: Uint8Array,
/**
* The destination address.
*
* This function only changes the local socket configuration and does not generate any network traffic.
* On success, the `remote-address` of the socket is updated. The `local-address` may be updated as well,
* based on the best network path to `remote-address`.
* The requirements on this field depend on how the stream was initialized:
* - with a remote address: this field must be None or match the stream's remote address exactly.
* - without a remote address: this field is required.
*
* When a `remote-address` is provided, the returned streams are limited to communicating with that specific peer:
* - `send` can only be used to send to this destination.
* - `receive` will only return datagrams sent from the provided `remote-address`.
*
* This method may be called multiple times on the same socket to change its association, but
* only the most recently returned pair of streams will be operational. Implementations may trap if
* the streams returned by a previous invocation haven't been dropped yet before calling `stream` again.
*
* The POSIX equivalent in pseudo-code is:
* ```text
* if (was previously connected) {
* connect(s, AF_UNSPEC)
* }
* if (remote_address is Some) {
* connect(s, remote_address)
* }
* ```
*
* Unlike in POSIX, the socket must already be explicitly bound.
*
* # Typical errors
* - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
* - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
* - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
* - `invalid-state`: The socket is not bound.
* - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
* - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
* - `connection-refused`: The connection was refused. (ECONNREFUSED)
*
* # 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>
*/
* If this value is None, the send operation is equivalent to `send` in POSIX. Otherwise it is equivalent to `sendto`.
*/
remoteAddress?: IpSocketAddress,
}
export class IncomingDatagramStream {
/**
* 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.
*
* This function returns successfully with an empty list when either:
* - `max-results` is 0, or:
* - `max-results` is greater than 0, but no results are immediately available.
* This function never returns `error(would-block)`.
*
* # Typical errors
* - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
* - `connection-refused`: The connection was refused. (ECONNREFUSED)
*
* # 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>
*/
receive(maxResults: bigint): IncomingDatagram[];
/**
* Create a `pollable` which will resolve once the stream is ready to receive again.
*
* Note: this function is here for WASI Preview2 only.
* It's planned to be removed when `future` is natively supported in Preview3.
*/
subscribe(): Pollable;
}
export class OutgoingDatagramStream {
/**
* Check readiness for sending. This function never blocks.
*
* Returns the number of datagrams permitted for the next call to `send`,
* or an error. Calling `send` with more datagrams than this function has
* permitted will trap.
*
* When this function returns ok(0), the `subscribe` pollable will
* become ready when this function will report at least ok(1), or an
* error.
*
* Never returns `would-block`.
*/
checkSend(): bigint;
/**
* 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 never
* returns `error(would-block)`. If none of the datagrams were able to be sent, `ok(0)` is returned.
*
* 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)`.
*
* Each call to `send` must be permitted by a preceding `check-send`. Implementations must trap if
* either `check-send` was not called or `datagrams` contains more items than `check-send` permitted.
*
* # Typical errors
* - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
* - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
* - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
* - `invalid-argument`: The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `stream`. (EISCONN)
* - `invalid-argument`: The socket is not "connected" and no value for `remote-address` was provided. (EDESTADDRREQ)
* - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
* - `connection-refused`: The connection was refused. (ECONNREFUSED)
* - `datagram-too-large`: The datagram is too large. (EMSGSIZE)
*
* # 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>
*/
send(datagrams: OutgoingDatagram[]): bigint;
/**
* Create a `pollable` which will resolve once the stream is ready to send again.
*
* Note: this function is here for WASI Preview2 only.
* It's planned to be removed when `future` is natively supported in Preview3.
*/
subscribe(): Pollable;
}
export class UdpSocket {
/**
* 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 port is zero, the socket will be bound to a random free port.
*
* # Typical errors
* - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
* - `invalid-state`: The socket is already bound. (EINVAL)
* - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
* - `address-in-use`: Address is already in use. (EADDRINUSE)
* - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
* - `not-in-progress`: A `bind` operation is not in progress.
* - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
*
* # Implementors note
* Unlike in POSIX, in WASI the bind operation is async. This enables
* interactive WASI hosts to inject permission prompts. Runtimes that
* don't want to make use of this ability can simply call the native
* `bind` as part of either `start-bind` or `finish-bind`.
*
* # References
* - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
* - <https://man7.org/linux/man-pages/man2/bind.2.html>
* - <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>
*/
startBind(network: Network, localAddress: IpSocketAddress): void;
finishBind(): void;
/**
* Set up inbound & outbound communication channels, optionally to a specific peer.
*
* This function only changes the local socket configuration and does not generate any network traffic.
* On success, the `remote-address` of the socket is updated. The `local-address` may be updated as well,
* based on the best network path to `remote-address`.
*
* When a `remote-address` is provided, the returned streams are limited to communicating with that specific peer:
* - `send` can only be used to send to this destination.
* - `receive` will only return datagrams sent from the provided `remote-address`.
*
* This method may be called multiple times on the same socket to change its association, but
* only the most recently returned pair of streams will be operational. Implementations may trap if
* the streams returned by a previous invocation haven't been dropped yet before calling `stream` again.
*
* The POSIX equivalent in pseudo-code is:
* ```text
* if (was previously connected) {
* connect(s, AF_UNSPEC)
* }
* if (remote_address is Some) {
* connect(s, remote_address)
* }
* ```
*
* Unlike in POSIX, the socket must already be explicitly bound.
*
* # Typical errors
* - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
* - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
* - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
* - `invalid-state`: The socket is not bound.
* - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
* - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
* - `connection-refused`: The connection was refused. (ECONNREFUSED)
*
* # 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>
*/
stream(remoteAddress: IpSocketAddress | undefined): [IncomingDatagramStream, OutgoingDatagramStream];
/**
* Get the current bound address.
*
* POSIX mentions:
* > If the socket has not been bound to a local name, the value
* > stored in the object pointed to by `address` is unspecified.
*
* WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
*
* # Typical errors
* - `invalid-state`: 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>
*/
* Get the current bound address.
*
* POSIX mentions:
* > If the socket has not been bound to a local name, the value
* > stored in the object pointed to by `address` is unspecified.
*
* WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
*
* # Typical errors
* - `invalid-state`: 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>
*/
localAddress(): IpSocketAddress;
/**
* Get the address the socket is currently streaming to.
*
* # Typical errors
* - `invalid-state`: The socket is not streaming to a specific 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>
*/
* Get the address the socket is currently streaming to.
*
* # Typical errors
* - `invalid-state`: The socket is not streaming to a specific 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>
*/
remoteAddress(): IpSocketAddress;
/**
* Whether this is a IPv4 or IPv6 socket.
*
* Equivalent to the SO_DOMAIN socket option.
*/
* Whether this is a IPv4 or IPv6 socket.
*
* Equivalent to the SO_DOMAIN socket option.
*/
addressFamily(): IpAddressFamily;
/**
* Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
*
* If the provided value is 0, an `invalid-argument` error is returned.
*
* # Typical errors
* - `invalid-argument`: (set) The TTL value must be 1 or higher.
*/
/**
* The kernel buffer space reserved for sends/receives on this socket.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
/**
* 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.
*/
/**
* 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.
*
* This function returns successfully with an empty list when either:
* - `max-results` is 0, or:
* - `max-results` is greater than 0, but no results are immediately available.
* This function never returns `error(would-block)`.
*
* # Typical errors
* - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
* - `connection-refused`: The connection was refused. (ECONNREFUSED)
*
* # 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 { IncomingDatagramStream };
/**
* Create a `pollable` which will resolve once the stream is ready to receive again.
*
* Note: this function is here for WASI Preview2 only.
* It's planned to be removed when `future` is natively supported in Preview3.
*/
/**
* Check readiness for sending. This function never blocks.
*
* Returns the number of datagrams permitted for the next call to `send`,
* or an error. Calling `send` with more datagrams than this function has
* permitted will trap.
*
* When this function returns ok(0), the `subscribe` pollable will
* become ready when this function will report at least ok(1), or an
* error.
*
* Never returns `would-block`.
*/
export { OutgoingDatagramStream };
/**
* 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 never
* returns `error(would-block)`. If none of the datagrams were able to be sent, `ok(0)` is returned.
*
* 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)`.
*
* Each call to `send` must be permitted by a preceding `check-send`. Implementations must trap if
* either `check-send` was not called or `datagrams` contains more items than `check-send` permitted.
*
* # Typical errors
* - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
* - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
* - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
* - `invalid-argument`: The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `stream`. (EISCONN)
* - `invalid-argument`: The socket is not "connected" and no value for `remote-address` was provided. (EDESTADDRREQ)
* - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
* - `connection-refused`: The connection was refused. (ECONNREFUSED)
* - `datagram-too-large`: The datagram is too large. (EMSGSIZE)
*
* # 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>
*/
/**
* Create a `pollable` which will resolve once the stream is ready to send again.
*
* Note: this function is here for WASI Preview2 only.
* It's planned to be removed when `future` is natively supported in Preview3.
*/
}
import type { Pollable } from './wasi-io-poll.js';
export { Pollable };
import type { Network } from './wasi-sockets-network.js';
export { Network };
import type { ErrorCode } from './wasi-sockets-network.js';
export { ErrorCode };
import type { IpSocketAddress } from './wasi-sockets-network.js';
export { IpSocketAddress };
import type { IpAddressFamily } from './wasi-sockets-network.js';
export { IpAddressFamily };
/**
* A received datagram.
*/
export interface IncomingDatagram {
/**
* The payload.
*
* Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
*/
data: Uint8Array,
/**
* The source address.
*
* This field is guaranteed to match the remote address the stream was initialized with, if any.
*
* Equivalent to the `src_addr` out parameter of `recvfrom`.
*/
remoteAddress: IpSocketAddress,
}
/**
* A datagram to be sent out.
*/
export interface OutgoingDatagram {
/**
* The payload.
*/
data: Uint8Array,
/**
* The destination address.
*
* The requirements on this field depend on how the stream was initialized:
* - with a remote address: this field must be None or match the stream's remote address exactly.
* - without a remote address: this field is required.
*
* If this value is None, the send operation is equivalent to `send` in POSIX. Otherwise it is equivalent to `sendto`.
*/
remoteAddress?: IpSocketAddress,
}
export class IncomingDatagramStream {
receive(maxResults: bigint): IncomingDatagram[];
subscribe(): Pollable;
}
export class OutgoingDatagramStream {
checkSend(): bigint;
send(datagrams: OutgoingDatagram[]): bigint;
subscribe(): Pollable;
}
export class UdpSocket {
startBind(network: Network, localAddress: IpSocketAddress): void;
finishBind(): void;
stream(remoteAddress: IpSocketAddress | undefined): [IncomingDatagramStream, OutgoingDatagramStream];
localAddress(): IpSocketAddress;
remoteAddress(): IpSocketAddress;
addressFamily(): IpAddressFamily;
* Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
*
* If the provided value is 0, an `invalid-argument` error is returned.
*
* # Typical errors
* - `invalid-argument`: (set) The TTL value must be 1 or higher.
*/
unicastHopLimit(): number;
setUnicastHopLimit(value: number): void;
/**
* The kernel buffer space reserved for sends/receives on this socket.
*
* If the provided value is 0, an `invalid-argument` error is returned.
* Any other value will never cause an error, but it might be silently clamped and/or rounded.
* I.e. after setting a value, reading the same setting back may return a different value.
*
* Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
*
* # Typical errors
* - `invalid-argument`: (set) The provided value was 0.
*/
receiveBufferSize(): bigint;

@@ -296,4 +290,10 @@ setReceiveBufferSize(value: bigint): void;

setSendBufferSize(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.
*/
subscribe(): Pollable;
}
SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

About

Packages

npm

Go

Maven

PyPI

Rubygems

Stay in touch

Get open source security insights delivered straight into your inbox.

  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc