From 8b224f4945205d558363aed8e5332d4f20af70df Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Thu, 7 Sep 2023 14:24:07 -0700 Subject: [PATCH 1/4] Add a `reactor` world Similar to how there exists a `command` world this commit adds a `reactor` world which has everything that a `command` does except for the export of the `run` interface. This mirrors the `preview1-adapter-reactor` that Wasmtime currently has and is intended to make this available for other WIT-based projects as well. This commit additionally refactors the preexisting `command` world to replace all of its `import`s with a single `include` of this new `reactor` world. --- wit/command.wit | 29 ++--------------------------- wit/reactor.wit | 30 ++++++++++++++++++++++++++++++ 2 files changed, 32 insertions(+), 27 deletions(-) create mode 100644 wit/reactor.wit diff --git a/wit/command.wit b/wit/command.wit index c29b4a6..d28f5f6 100644 --- a/wit/command.wit +++ b/wit/command.wit @@ -1,32 +1,7 @@ package wasi:cli world command { - import wasi:clocks/wall-clock - import wasi:clocks/monotonic-clock - import wasi:clocks/timezone - import wasi:filesystem/types - import wasi:filesystem/preopens - import wasi:sockets/instance-network - import wasi:sockets/ip-name-lookup - import wasi:sockets/network - import wasi:sockets/tcp-create-socket - import wasi:sockets/tcp - import wasi:sockets/udp-create-socket - import wasi:sockets/udp - import wasi:random/random - import wasi:random/insecure - import wasi:random/insecure-seed - import wasi:poll/poll - import wasi:io/streams - import environment - import exit - import stdin - import stdout - import stderr - import terminal-input - import terminal-output - import terminal-stdin - import terminal-stdout - import terminal-stderr + include reactor + export run } diff --git a/wit/reactor.wit b/wit/reactor.wit new file mode 100644 index 0000000..30ff962 --- /dev/null +++ b/wit/reactor.wit @@ -0,0 +1,30 @@ +world reactor { + import wasi:clocks/wall-clock + import wasi:clocks/monotonic-clock + import wasi:clocks/timezone + import wasi:filesystem/types + import wasi:filesystem/preopens + import wasi:sockets/instance-network + import wasi:sockets/ip-name-lookup + import wasi:sockets/network + import wasi:sockets/tcp-create-socket + import wasi:sockets/tcp + import wasi:sockets/udp-create-socket + import wasi:sockets/udp + import wasi:random/random + import wasi:random/insecure + import wasi:random/insecure-seed + import wasi:poll/poll + import wasi:io/streams + import environment + import exit + import stdin + import stdout + import stderr + import terminal-input + import terminal-output + import terminal-stdin + import terminal-stdout + import terminal-stderr +} + From 2f3eac83168e7f89a745cb715c6d4175d0300ca6 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 12 Sep 2023 13:45:44 -0700 Subject: [PATCH 2/4] Update ABI files --- .github/workflows/main.yml | 4 +- command.md | 616 +++---- reactor.md | 3167 ++++++++++++++++++++++++++++++++++++ 3 files changed, 3477 insertions(+), 310 deletions(-) create mode 100644 reactor.md diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 3cba299..071dda3 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -18,6 +18,6 @@ jobs: ./wit-deps lock git add -N wit/deps git diff --exit-code - - uses: WebAssembly/wit-abi-up-to-date@v13 + - uses: alexcrichton/wasi-abi-up-to-date@update-to-wit-bindgen with: - wit-abi-tag: wit-abi-0.11.0 + worlds: "command reactor" diff --git a/command.md b/command.md index 336dd43..6634d0a 100644 --- a/command.md +++ b/command.md @@ -182,7 +182,14 @@ reached.

type datetime

datetime

-#### `record timezone-display` +#### `type timezone` +`u32` +

A timezone. +

In timezones that recognize daylight saving time, also known as daylight +time and summer time, the information returned from the functions varies +over time to reflect these adjustments.

+

This represents a resource.

+

record timezone-display

Information useful for displaying the timezone of a specific datetime.

This information may vary within a single timezone to reflect daylight saving time adjustments.

@@ -214,13 +221,6 @@ representation of the UTC offset may be returned, such as -04:00. -

type timezone

-

u32

-

A timezone. -

In timezones that recognize daylight saving time, also known as daylight -time and summer time, the information returned from the functions varies -over time to reflect these adjustments.

-

This represents a resource.

Functions

display: func

@@ -267,7 +267,11 @@ when it does, they are expected to subsume this API.

type pollable

pollable

-#### `enum stream-status` +#### `record stream-error` +

An error type returned from a stream operation. Currently this +doesn't provide any additional information.

+
Record Fields
+

enum stream-status

Streams provide a sequence of data and then end; once they end, they no longer provide any further data.

For example, a stream reading from a file ends when the stream reaches @@ -284,25 +288,6 @@ socket ends when the socket is closed.

The stream has ended and will not produce any further data. -

record stream-error

-

An error type returned from a stream operation. Currently this -doesn't provide any additional information.

-
Record Fields
-

type output-stream

-

u32

-

An output bytestream. In the future, this will be replaced by handle -types. -

This conceptually represents a stream<u8, _>. It's temporary -scaffolding until component-model's async features are ready.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe-to-output-stream function to obtain a -pollable which can be polled for using wasi_poll.

-

And at present, it is a u32 instead of being an actual handle, until -the wit-bindgen implementation of handles and resources is ready.

-

This represents a resource.

type input-stream

u32

An input bytestream. In the future, this will be replaced by handle @@ -318,6 +303,21 @@ can be polled for using wasi_poll.

And at present, it is a u32 instead of being an actual handle, until the wit-bindgen implementation of handles and resources is ready.

This represents a resource.

+

type output-stream

+

u32

+

An output bytestream. In the future, this will be replaced by handle +types. +

This conceptually represents a stream<u8, _>. It's temporary +scaffolding until component-model's async features are ready.

+

output-streams are non-blocking to the extent practical on +underlying platforms. Except where specified otherwise, I/O operations also +always return promptly, after the number of bytes that can be written +promptly, which could even be zero. To wait for the stream to be ready to +accept data, the subscribe-to-output-stream function to obtain a +pollable which can be polled for using wasi_poll.

+

And at present, it is a u32 instead of being an actual handle, until +the wit-bindgen implementation of handles and resources is ready.

+

This represents a resource.

Functions

read: func

@@ -553,7 +553,108 @@ underlying filesystem, the function fails with `type datetime` [`datetime`](#datetime)

-#### `flags path-flags` +#### `type filesize` +`u64` +

File size or length of a region within a file. +

enum descriptor-type

+

The type of a filesystem object referenced by a descriptor.

+

Note: This was called filetype in earlier versions of WASI.

+
Enum Cases
+ +

flags descriptor-flags

+

Descriptor flags.

+

Note: This was called fdflags in earlier versions of WASI.

+
Flags members
+ +

flags path-flags

Flags determining the method of how paths are resolved.

Flags members
-

record metadata-hash-value

-

A 128-bit hash value, split into parts because wasm doesn't have a -128-bit integer type.

-
Record Fields
+

variant access-type

+

Access type used by access-at.

+
Variant Cases

type link-count

u64

Number of hard links to an inode. -

type filesize

-

u64

-

File size or length of a region within a file. +

record descriptor-stat

+

File attributes.

+

Note: This was called filestat in earlier versions of WASI.

+
Record Fields
+ +

variant new-timestamp

+

When setting a timestamp, this gives the value to set it to.

+
Variant Cases
+ +

record directory-entry

+

A directory entry.

+
Record Fields
+

enum error-code

Error codes returned by functions, similar to errno in POSIX. Not all of these error codes are returned by the functions provided by this @@ -712,241 +871,71 @@ merely for alignment with POSIX.

  • no-entry

    -

    No such file or directory, similar to `ENOENT` in POSIX. -

    • -
  • -

    no-lock

    -

    No locks available, similar to `ENOLCK` in POSIX. -

    • -
  • -

    insufficient-memory

    -

    Not enough space, similar to `ENOMEM` in POSIX. -

    • -
  • -

    insufficient-space

    -

    No space left on device, similar to `ENOSPC` in POSIX. -

    • -
  • -

    not-directory

    -

    Not a directory or a symbolic link to a directory, similar to `ENOTDIR` in POSIX. -

    • -
  • -

    not-empty

    -

    Directory not empty, similar to `ENOTEMPTY` in POSIX. -

    • -
  • -

    not-recoverable

    -

    State not recoverable, similar to `ENOTRECOVERABLE` in POSIX. -

    • -
  • -

    unsupported

    -

    Not supported, similar to `ENOTSUP` and `ENOSYS` in POSIX. -

    • -
  • -

    no-tty

    -

    Inappropriate I/O control operation, similar to `ENOTTY` in POSIX. -

    • -
  • -

    no-such-device

    -

    No such device or address, similar to `ENXIO` in POSIX. -

    • -
  • -

    overflow

    -

    Value too large to be stored in data type, similar to `EOVERFLOW` in POSIX. -

    • -
  • -

    not-permitted

    -

    Operation not permitted, similar to `EPERM` in POSIX. -

    • -
  • -

    pipe

    -

    Broken pipe, similar to `EPIPE` in POSIX. -

    • -
  • -

    read-only

    -

    Read-only file system, similar to `EROFS` in POSIX. -

    • -
  • -

    invalid-seek

    -

    Invalid seek, similar to `ESPIPE` in POSIX. -

    • -
  • -

    text-file-busy

    -

    Text file busy, similar to `ETXTBSY` in POSIX. -

    • -
  • -

    cross-device

    -

    Cross-device link, similar to `EXDEV` in POSIX. -

    • - -

    type directory-entry-stream

    -

    u32

    -

    A stream of directory entries. -

    This represents a stream of dir-entry.

    -

    enum descriptor-type

    -

    The type of a filesystem object referenced by a descriptor.

    -

    Note: This was called filetype in earlier versions of WASI.

    -
    Enum Cases
    - -

    record directory-entry

    -

    A directory entry.

    -
    Record Fields
    - -

    flags descriptor-flags

    -

    Descriptor flags.

    -

    Note: This was called fdflags in earlier versions of WASI.

    -
    Flags members
    - -

    type descriptor

    -

    u32

    -

    A descriptor is a reference to a filesystem object, which may be a file, -directory, named pipe, special file, or other object on which filesystem -calls may be made. -

    This represents a resource.

    -

    variant new-timestamp

    -

    When setting a timestamp, this gives the value to set it to.

    -
    Variant Cases
    - -

    record descriptor-stat

    -

    File attributes.

    -

    Note: This was called filestat in earlier versions of WASI.

    -
    Record Fields
    -

    enum advice

    @@ -984,19 +973,30 @@ in the near future. not reuse it thereafter. -

    variant access-type

    -

    Access type used by access-at.

    -
    Variant Cases
    +

    type descriptor

    +

    u32

    +

    A descriptor is a reference to a filesystem object, which may be a file, +directory, named pipe, special file, or other object on which filesystem +calls may be made. +

    This represents a resource.

    +

    record metadata-hash-value

    +

    A 128-bit hash value, split into parts because wasm doesn't have a +128-bit integer type.

    +
    Record Fields
    +

    type directory-entry-stream

    +

    u32

    +

    A stream of directory entries. +

    This represents a stream of dir-entry.

    Functions

    read-via-stream: func

    @@ -1637,64 +1637,6 @@ to by a directory descriptor and a relative path.

    This enables context-based security for networking. There is no need for this to map 1:1 to a physical network interface.

    FYI, In the future this will be replaced by handle types.

    -

    tuple ipv6-address

    -
    Tuple Fields
    - -

    record ipv6-socket-address

    -
    Record Fields
    - -

    tuple ipv4-address

    -
    Tuple Fields
    - -

    record ipv4-socket-address

    -
    Record Fields
    - -

    variant ip-socket-address

    -
    Variant Cases
    - -

    enum ip-address-family

    -
    Enum Cases
    - -

    variant ip-address

    -
    Variant Cases
    -

    enum error-code

    Error codes.

    In theory, every API can return any error code. @@ -1844,6 +1786,64 @@ combined with a couple of errors that are always possible:

    A permanent failure in name resolution occurred. +

    enum ip-address-family

    +
    Enum Cases
    + +

    tuple ipv4-address

    +
    Tuple Fields
    + +

    tuple ipv6-address

    +
    Tuple Fields
    + +

    variant ip-address

    +
    Variant Cases
    + +

    record ipv4-socket-address

    +
    Record Fields
    + +

    record ipv6-socket-address

    +
    Record Fields
    + +

    variant ip-socket-address

    +
    Variant Cases
    +

    Functions

    drop-network: func

    diff --git a/reactor.md b/reactor.md new file mode 100644 index 0000000..6e0f5b7 --- /dev/null +++ b/reactor.md @@ -0,0 +1,3167 @@ +

    World reactor

    + +

    Import interface wasi:clocks/wall-clock

    +

    WASI Wall Clock is a clock API intended to let users query the current +time. The name "wall" makes an analogy to a "clock on the wall", which +is not necessarily monotonic as it may be reset.

    +

    It is intended to be portable at least between Unix-family platforms and +Windows.

    +

    A wall clock is a clock which measures the date and time according to +some external reference.

    +

    External references may be reset, so this clock is not necessarily +monotonic, making it unsuitable for measuring elapsed time.

    +

    It is intended for reporting the current date and time for humans.

    +
    +

    Types

    +

    record datetime

    +

    A time and date in seconds plus nanoseconds.

    +
    Record Fields
    + +
    +

    Functions

    +

    now: func

    +

    Read the current value of the clock.

    +

    This clock is not monotonic, therefore calling this function repeatedly +will not necessarily produce a sequence of non-decreasing values.

    +

    The returned timestamps represent the number of seconds since +1970-01-01T00:00:00Z, also known as POSIX's Seconds Since the Epoch, +also known as Unix Time.

    +

    The nanoseconds field of the output is always less than 1000000000.

    +
    Return values
    + +

    resolution: func

    +

    Query the resolution of the clock.

    +

    The nanoseconds field of the output is always less than 1000000000.

    +
    Return values
    + +

    Import interface wasi:poll/poll

    +

    A poll API intended to let users wait for I/O events on multiple handles +at once.

    +
    +

    Types

    +

    type pollable

    +

    u32

    +

    A "pollable" handle. +

    This is conceptually represents a stream<_, _>, or in other words, +a stream that one can wait on, repeatedly, but which does not itself +produce any data. It's temporary scaffolding until component-model's +async features are ready.

    +

    And at present, it is a u32 instead of being an actual handle, until +the wit-bindgen implementation of handles and resources is ready.

    +

    pollable lifetimes are not automatically managed. Users must ensure +that they do not outlive the resource they reference.

    +

    This represents a resource.

    +
    +

    Functions

    +

    drop-pollable: func

    +

    Dispose of the specified pollable, after which it may no longer +be used.

    +
    Params
    + +

    poll-oneoff: func

    +

    Poll for completion on a set of pollables.

    +

    This function takes a list of pollables, which identify I/O sources of +interest, and waits until one or more of the events is ready for I/O.

    +

    The result list<bool> is the same length as the argument +list<pollable>, and indicates the readiness of each corresponding +element in that list, with true indicating ready. A single call can +return multiple true elements.

    +

    A timeout can be implemented by adding a pollable from the +wasi-clocks API to the list.

    +

    This function does not return a result; polling in itself does not +do any I/O so it doesn't fail. If any of the I/O sources identified by +the pollables has an error, it is indicated by marking the source as +ready in the list<bool>.

    +

    The "oneoff" in the name refers to the fact that this function must do a +linear scan through the entire list of subscriptions, which may be +inefficient if the number is large and the same subscriptions are used +many times. In the future, this is expected to be obsoleted by the +component model async proposal, which will include a scalable waiting +facility.

    +
    Params
    + +
    Return values
    + +

    Import interface wasi:clocks/monotonic-clock

    +

    WASI Monotonic Clock is a clock API intended to let users measure elapsed +time.

    +

    It is intended to be portable at least between Unix-family platforms and +Windows.

    +

    A monotonic clock is a clock which has an unspecified initial value, and +successive reads of the clock will produce non-decreasing values.

    +

    It is intended for measuring elapsed time.

    +
    +

    Types

    +

    type pollable

    +

    pollable

    +

    +#### `type instant` +`u64` +

    A timestamp in nanoseconds. +

    +

    Functions

    +

    now: func

    +

    Read the current value of the clock.

    +

    The clock is monotonic, therefore calling this function repeatedly will +produce a sequence of non-decreasing values.

    +
    Return values
    + +

    resolution: func

    +

    Query the resolution of the clock.

    +
    Return values
    + +

    subscribe: func

    +

    Create a pollable which will resolve once the specified time has been +reached.

    +
    Params
    + +
    Return values
    + +

    Import interface wasi:clocks/timezone

    +
    +

    Types

    +

    type datetime

    +

    datetime

    +

    +#### `type timezone` +`u32` +

    A timezone. +

    In timezones that recognize daylight saving time, also known as daylight +time and summer time, the information returned from the functions varies +over time to reflect these adjustments.

    +

    This represents a resource.

    +

    record timezone-display

    +

    Information useful for displaying the timezone of a specific datetime.

    +

    This information may vary within a single timezone to reflect daylight +saving time adjustments.

    +
    Record Fields
    + +
    +

    Functions

    +

    display: func

    +

    Return information needed to display the given datetime. This includes +the UTC offset, the time zone name, and a flag indicating whether +daylight saving time is active.

    +

    If the timezone cannot be determined for the given datetime, return a +timezone-display for UTC with a utc-offset of 0 and no daylight +saving time.

    +
    Params
    + +
    Return values
    + +

    utc-offset: func

    +

    The same as display, but only return the UTC offset.

    +
    Params
    + +
    Return values
    + +

    drop-timezone: func

    +

    Dispose of the specified input-stream, after which it may no longer +be used.

    +
    Params
    + +

    Import interface wasi:io/streams

    +

    WASI I/O is an I/O abstraction API which is currently focused on providing +stream types.

    +

    In the future, the component model is expected to add built-in stream types; +when it does, they are expected to subsume this API.

    +
    +

    Types

    +

    type pollable

    +

    pollable

    +

    +#### `record stream-error` +

    An error type returned from a stream operation. Currently this +doesn't provide any additional information.

    +
    Record Fields
    +

    enum stream-status

    +

    Streams provide a sequence of data and then end; once they end, they +no longer provide any further data.

    +

    For example, a stream reading from a file ends when the stream reaches +the end of the file. For another example, a stream reading from a +socket ends when the socket is closed.

    +
    Enum Cases
    + +

    type input-stream

    +

    u32

    +

    An input bytestream. In the future, this will be replaced by handle +types. +

    This conceptually represents a stream<u8, _>. It's temporary +scaffolding until component-model's async features are ready.

    +

    input-streams are non-blocking to the extent practical on underlying +platforms. I/O operations always return promptly; if fewer bytes are +promptly available than requested, they return the number of bytes promptly +available, which could even be zero. To wait for data to be available, +use the subscribe-to-input-stream function to obtain a pollable which +can be polled for using wasi_poll.

    +

    And at present, it is a u32 instead of being an actual handle, until +the wit-bindgen implementation of handles and resources is ready.

    +

    This represents a resource.

    +

    type output-stream

    +

    u32

    +

    An output bytestream. In the future, this will be replaced by handle +types. +

    This conceptually represents a stream<u8, _>. It's temporary +scaffolding until component-model's async features are ready.

    +

    output-streams are non-blocking to the extent practical on +underlying platforms. Except where specified otherwise, I/O operations also +always return promptly, after the number of bytes that can be written +promptly, which could even be zero. To wait for the stream to be ready to +accept data, the subscribe-to-output-stream function to obtain a +pollable which can be polled for using wasi_poll.

    +

    And at present, it is a u32 instead of being an actual handle, until +the wit-bindgen implementation of handles and resources is ready.

    +

    This represents a resource.

    +
    +

    Functions

    +

    read: func

    +

    Read bytes from a stream.

    +

    This function returns a list of bytes containing the data that was +read, along with a stream-status which indicates whether the end of +the stream was reached. The returned list will contain up to len +bytes; it may return fewer than requested, but not more.

    +

    Once a stream has reached the end, subsequent calls to read or +skip will always report end-of-stream rather than producing more +data.

    +

    If len is 0, it represents a request to read 0 bytes, which should +always succeed, assuming the stream hasn't reached its end yet, and +return an empty list.

    +

    The len here is a u64, but some callees may not be able to allocate +a buffer as large as that would imply. +FIXME: describe what happens if allocation fails.

    +
    Params
    + +
    Return values
    + +

    blocking-read: func

    +

    Read bytes from a stream, with blocking.

    +

    This is similar to read, except that it blocks until at least one +byte can be read.

    +
    Params
    + +
    Return values
    + +

    skip: func

    +

    Skip bytes from a stream.

    +

    This is similar to the read function, but avoids copying the +bytes into the instance.

    +

    Once a stream has reached the end, subsequent calls to read or +skip will always report end-of-stream rather than producing more +data.

    +

    This function returns the number of bytes skipped, along with a +stream-status indicating whether the end of the stream was +reached. The returned value will be at most len; it may be less.

    +
    Params
    + +
    Return values
    + +

    blocking-skip: func

    +

    Skip bytes from a stream, with blocking.

    +

    This is similar to skip, except that it blocks until at least one +byte can be consumed.

    +
    Params
    + +
    Return values
    + +

    subscribe-to-input-stream: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    drop-input-stream: func

    +

    Dispose of the specified input-stream, after which it may no longer +be used.

    +
    Params
    + +

    write: func

    +

    Write bytes to a stream.

    +

    This function returns a u64 indicating the number of bytes from +buf that were written; it may be less than the full list.

    +
    Params
    + +
    Return values
    + +

    blocking-write: func

    +

    Write bytes to a stream, with blocking.

    +

    This is similar to write, except that it blocks until at least one +byte can be written.

    +
    Params
    + +
    Return values
    + +

    write-zeroes: func

    +

    Write multiple zero bytes to a stream.

    +

    This function returns a u64 indicating the number of zero bytes +that were written; it may be less than len.

    +
    Params
    + +
    Return values
    + +

    blocking-write-zeroes: func

    +

    Write multiple zero bytes to a stream, with blocking.

    +

    This is similar to write-zeroes, except that it blocks until at least +one byte can be written.

    +
    Params
    + +
    Return values
    + +

    splice: func

    +

    Read from one stream and write to another.

    +

    This function returns the number of bytes transferred; it may be less +than len.

    +

    Unlike other I/O functions, this function blocks until all the data +read from the input stream has been written to the output stream.

    +
    Params
    + +
    Return values
    + +

    blocking-splice: func

    +

    Read from one stream and write to another, with blocking.

    +

    This is similar to splice, except that it blocks until at least +one byte can be read.

    +
    Params
    + +
    Return values
    + +

    forward: func

    +

    Forward the entire contents of an input stream to an output stream.

    +

    This function repeatedly reads from the input stream and writes +the data to the output stream, until the end of the input stream +is reached, or an error is encountered.

    +

    Unlike other I/O functions, this function blocks until the end +of the input stream is seen and all the data has been written to +the output stream.

    +

    This function returns the number of bytes transferred.

    +
    Params
    + +
    Return values
    + +

    subscribe-to-output-stream: func

    +

    Create a pollable which will resolve once either the specified stream +is ready to accept bytes or the other end of the stream has been closed.

    +
    Params
    + +
    Return values
    + +

    drop-output-stream: func

    +

    Dispose of the specified output-stream, after which it may no longer +be used.

    +
    Params
    + +

    Import interface wasi:filesystem/types

    +

    WASI filesystem is a filesystem API primarily intended to let users run WASI +programs that access their files on their existing filesystems, without +significant overhead.

    +

    It is intended to be roughly portable between Unix-family platforms and +Windows, though it does not hide many of the major differences.

    +

    Paths are passed as interface-type strings, meaning they must consist of +a sequence of Unicode Scalar Values (USVs). Some filesystems may contain +paths which are not accessible by this API.

    +

    The directory separator in WASI is always the forward-slash (/).

    +

    All paths in WASI are relative paths, and are interpreted relative to a +descriptor referring to a base directory. If a path argument to any WASI +function starts with /, or if any step of resolving a path, including +.. and symbolic link steps, reaches a directory outside of the base +directory, or reaches a symlink to an absolute or rooted path in the +underlying filesystem, the function fails with error-code::not-permitted.

    +
    +

    Types

    +

    type input-stream

    +

    input-stream

    +

    +#### `type output-stream` +[`output-stream`](#output_stream) +

    +#### `type datetime` +[`datetime`](#datetime) +

    +#### `type filesize` +`u64` +

    File size or length of a region within a file. +

    enum descriptor-type

    +

    The type of a filesystem object referenced by a descriptor.

    +

    Note: This was called filetype in earlier versions of WASI.

    +
    Enum Cases
    + +

    flags descriptor-flags

    +

    Descriptor flags.

    +

    Note: This was called fdflags in earlier versions of WASI.

    +
    Flags members
    + +

    flags path-flags

    +

    Flags determining the method of how paths are resolved.

    +
    Flags members
    + +

    flags open-flags

    +

    Open flags used by open-at.

    +
    Flags members
    + +

    flags modes

    +

    Permissions mode used by open-at, change-file-permissions-at, and +similar.

    +
    Flags members
    + +

    variant access-type

    +

    Access type used by access-at.

    +
    Variant Cases
    + +

    type link-count

    +

    u64

    +

    Number of hard links to an inode. +

    record descriptor-stat

    +

    File attributes.

    +

    Note: This was called filestat in earlier versions of WASI.

    +
    Record Fields
    + +

    variant new-timestamp

    +

    When setting a timestamp, this gives the value to set it to.

    +
    Variant Cases
    + +

    record directory-entry

    +

    A directory entry.

    +
    Record Fields
    + +

    enum error-code

    +

    Error codes returned by functions, similar to errno in POSIX. +Not all of these error codes are returned by the functions provided by this +API; some are used in higher-level library layers, and others are provided +merely for alignment with POSIX.

    +
    Enum Cases
    + +

    enum advice

    +

    File or memory access pattern advisory information.

    +
    Enum Cases
    + +

    type descriptor

    +

    u32

    +

    A descriptor is a reference to a filesystem object, which may be a file, +directory, named pipe, special file, or other object on which filesystem +calls may be made. +

    This represents a resource.

    +

    record metadata-hash-value

    +

    A 128-bit hash value, split into parts because wasm doesn't have a +128-bit integer type.

    +
    Record Fields
    + +

    type directory-entry-stream

    +

    u32

    +

    A stream of directory entries. +

    This represents a stream of dir-entry.

    +
    +

    Functions

    +

    read-via-stream: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    write-via-stream: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    append-via-stream: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    advise: func

    +

    Provide file advisory information on a descriptor.

    +

    This is similar to posix_fadvise in POSIX.

    +
    Params
    + +
    Return values
    + +

    sync-data: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    get-flags: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    get-type: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    set-flags: func

    +

    Set status flags associated with a descriptor.

    +

    This function may only change the non-blocking flag.

    +

    Note: This is similar to fcntl(fd, F_SETFL, flags) in POSIX.

    +

    Note: This was called fd_fdstat_set_flags in earlier versions of WASI.

    +
    Params
    + +
    Return values
    + +

    set-size: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    set-times: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    read: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    write: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    read-directory: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    sync: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    create-directory-at: func

    +

    Create a directory.

    +

    Note: This is similar to mkdirat in POSIX.

    +
    Params
    + +
    Return values
    + +

    stat: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    stat-at: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    set-times-at: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    link-at: func

    +

    Create a hard link.

    +

    Note: This is similar to linkat in POSIX.

    +
    Params
    + +
    Return values
    + +

    open-at: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    readlink-at: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    remove-directory-at: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    rename-at: func

    +

    Rename a filesystem object.

    +

    Note: This is similar to renameat in POSIX.

    +
    Params
    + +
    Return values
    + +

    symlink-at: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    access-at: func

    +

    Check accessibility of a filesystem path.

    +

    Check whether the given filesystem path names an object which is +readable, writable, or executable, or whether it exists.

    +

    This does not a guarantee that subsequent accesses will succeed, as +filesystem permissions may be modified asynchronously by external +entities.

    +

    Note: This is similar to faccessat with the AT_EACCESS flag in POSIX.

    +
    Params
    + +
    Return values
    + +

    unlink-file-at: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    change-file-permissions-at: func

    +

    Change the permissions of a filesystem object that is not a directory.

    +

    Note that the ultimate meanings of these permissions is +filesystem-specific.

    +

    Note: This is similar to fchmodat in POSIX.

    +
    Params
    + +
    Return values
    + +

    change-directory-permissions-at: func

    +

    Change the permissions of a directory.

    +

    Note that the ultimate meanings of these permissions is +filesystem-specific.

    +

    Unlike in POSIX, the executable flag is not reinterpreted as a "search" +flag. read on a directory implies readability and searchability, and +execute is not valid for directories.

    +

    Note: This is similar to fchmodat in POSIX.

    +
    Params
    + +
    Return values
    + +

    lock-shared: func

    +

    Request a shared advisory lock for an open file.

    +

    This requests a shared lock; more than one shared lock can be held for +a file at the same time.

    +

    If the open file has an exclusive lock, this function downgrades the lock +to a shared lock. If it has a shared lock, this function has no effect.

    +

    This requests an advisory lock, meaning that the file could be accessed +by other programs that don't hold the lock.

    +

    It is unspecified how shared locks interact with locks acquired by +non-WASI programs.

    +

    This function blocks until the lock can be acquired.

    +

    Not all filesystems support locking; on filesystems which don't support +locking, this function returns error-code::unsupported.

    +

    Note: This is similar to flock(fd, LOCK_SH) in Unix.

    +
    Params
    + +
    Return values
    + +

    lock-exclusive: func

    +

    Request an exclusive advisory lock for an open file.

    +

    This requests an exclusive lock; no other locks may be held for the +file while an exclusive lock is held.

    +

    If the open file has a shared lock and there are no exclusive locks held +for the file, this function upgrades the lock to an exclusive lock. If the +open file already has an exclusive lock, this function has no effect.

    +

    This requests an advisory lock, meaning that the file could be accessed +by other programs that don't hold the lock.

    +

    It is unspecified whether this function succeeds if the file descriptor +is not opened for writing. It is unspecified how exclusive locks interact +with locks acquired by non-WASI programs.

    +

    This function blocks until the lock can be acquired.

    +

    Not all filesystems support locking; on filesystems which don't support +locking, this function returns error-code::unsupported.

    +

    Note: This is similar to flock(fd, LOCK_EX) in Unix.

    +
    Params
    + +
    Return values
    + +

    try-lock-shared: func

    +

    Request a shared advisory lock for an open file.

    +

    This requests a shared lock; more than one shared lock can be held for +a file at the same time.

    +

    If the open file has an exclusive lock, this function downgrades the lock +to a shared lock. If it has a shared lock, this function has no effect.

    +

    This requests an advisory lock, meaning that the file could be accessed +by other programs that don't hold the lock.

    +

    It is unspecified how shared locks interact with locks acquired by +non-WASI programs.

    +

    This function returns error-code::would-block if the lock cannot be +acquired.

    +

    Not all filesystems support locking; on filesystems which don't support +locking, this function returns error-code::unsupported.

    +

    Note: This is similar to flock(fd, LOCK_SH | LOCK_NB) in Unix.

    +
    Params
    + +
    Return values
    + +

    try-lock-exclusive: func

    +

    Request an exclusive advisory lock for an open file.

    +

    This requests an exclusive lock; no other locks may be held for the +file while an exclusive lock is held.

    +

    If the open file has a shared lock and there are no exclusive locks held +for the file, this function upgrades the lock to an exclusive lock. If the +open file already has an exclusive lock, this function has no effect.

    +

    This requests an advisory lock, meaning that the file could be accessed +by other programs that don't hold the lock.

    +

    It is unspecified whether this function succeeds if the file descriptor +is not opened for writing. It is unspecified how exclusive locks interact +with locks acquired by non-WASI programs.

    +

    This function returns error-code::would-block if the lock cannot be +acquired.

    +

    Not all filesystems support locking; on filesystems which don't support +locking, this function returns error-code::unsupported.

    +

    Note: This is similar to flock(fd, LOCK_EX | LOCK_NB) in Unix.

    +
    Params
    + +
    Return values
    + +

    unlock: func

    +

    Release a shared or exclusive lock on an open file.

    +

    Note: This is similar to flock(fd, LOCK_UN) in Unix.

    +
    Params
    + +
    Return values
    + +

    drop-descriptor: func

    +

    Dispose of the specified descriptor, after which it may no longer +be used.

    +
    Params
    + +

    read-directory-entry: func

    +

    Read a single directory entry from a directory-entry-stream.

    +
    Params
    + +
    Return values
    + +

    drop-directory-entry-stream: func

    +

    Dispose of the specified directory-entry-stream, after which it may no longer +be used.

    +
    Params
    + +

    is-same-object: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    metadata-hash: func

    +

    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:

    + +

    However, none of these is required.

    +
    Params
    + +
    Return values
    + +

    metadata-hash-at: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    Import interface wasi:filesystem/preopens

    +
    +

    Types

    +

    type descriptor

    +

    descriptor

    +

    +---- +

    Functions

    +

    get-directories: func

    +

    Return the set of preopened directories, and their path.

    +
    Return values
    + +

    Import interface wasi:sockets/network

    +
    +

    Types

    +

    type network

    +

    u32

    +

    An opaque resource that represents access to (a subset of) the network. +This enables context-based security for networking. +There is no need for this to map 1:1 to a physical network interface. +

    FYI, In the future this will be replaced by handle types.

    +

    enum error-code

    +

    Error codes.

    +

    In theory, every API can return any error code. +In practice, API's typically only return the errors documented per API +combined with a couple of errors that are always possible:

    + +

    See each individual API for what the POSIX equivalents are. They sometimes differ per API.

    +
    Enum Cases
    + +

    enum ip-address-family

    +
    Enum Cases
    + +

    tuple ipv4-address

    +
    Tuple Fields
    + +

    tuple ipv6-address

    +
    Tuple Fields
    + +

    variant ip-address

    +
    Variant Cases
    + +

    record ipv4-socket-address

    +
    Record Fields
    + +

    record ipv6-socket-address

    +
    Record Fields
    + +

    variant ip-socket-address

    +
    Variant Cases
    + +
    +

    Functions

    +

    drop-network: func

    +

    Dispose of the specified network, after which it may no longer be used.

    +

    Note: this function is scheduled to be removed when Resources are natively supported in Wit.

    +
    Params
    + +

    Import interface wasi:sockets/instance-network

    +

    This interface provides a value-export of the default network handle..

    +
    +

    Types

    +

    type network

    +

    network

    +

    +---- +

    Functions

    +

    instance-network: func

    +

    Get a handle to the default network.

    +
    Return values
    + +

    Import interface wasi:sockets/ip-name-lookup

    +
    +

    Types

    +

    type pollable

    +

    pollable

    +

    +#### `type network` +[`network`](#network) +

    +#### `type error-code` +[`error-code`](#error_code) +

    +#### `type ip-address` +[`ip-address`](#ip_address) +

    +#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +

    +#### `type resolve-address-stream` +`u32` +

    +---- +

    Functions

    +

    resolve-addresses: func

    +

    Resolve an internet host name to a list of IP addresses.

    +

    See the wasi-socket proposal README.md for a comparison with getaddrinfo.

    +

    Parameters

    + +

    This function never blocks. It either immediately fails or immediately returns successfully with a resolve-address-stream +that can be used to (asynchronously) fetch the results.

    +

    At the moment, the stream never completes successfully with 0 items. Ie. the first call +to resolve-next-address never returns ok(none). This may change in the future.

    +

    Typical errors

    + +

    References:

    + +
    Params
    + +
    Return values
    + +

    resolve-next-address: func

    +

    Returns the next address from the resolver.

    +

    This function should be called multiple times. On each call, it will +return the next address in connection order preference. If all +addresses have been exhausted, this function returns none. +After which, you should release the stream with drop-resolve-address-stream.

    +

    This function never returns IPv4-mapped IPv6 addresses.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    drop-resolve-address-stream: func

    +

    Dispose of the specified resolve-address-stream, after which it may no longer be used.

    +

    Note: this function is scheduled to be removed when Resources are natively supported in Wit.

    +
    Params
    + +

    subscribe: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    Import interface wasi:sockets/tcp

    +
    +

    Types

    +

    type input-stream

    +

    input-stream

    +

    +#### `type output-stream` +[`output-stream`](#output_stream) +

    +#### `type pollable` +[`pollable`](#pollable) +

    +#### `type network` +[`network`](#network) +

    +#### `type error-code` +[`error-code`](#error_code) +

    +#### `type ip-socket-address` +[`ip-socket-address`](#ip_socket_address) +

    +#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +

    +#### `type tcp-socket` +`u32` +

    A TCP socket handle. +

    enum shutdown-type

    +
    Enum Cases
    + +
    +

    Functions

    +

    start-bind: func

    +

    Bind the socket to a specific network on the provided IP address and port.

    +

    If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which +network interface(s) to bind to. +If the TCP/UDP port is zero, the socket will be bound to a random free port.

    +

    When a socket is not explicitly bound, the first invocation to a listen or connect operation will +implicitly bind the socket.

    +

    Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.

    +

    Typical start errors

    + +

    Typical finish errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    finish-bind: func

    +
    Params
    + +
    Return values
    + +

    start-connect: func

    +

    Connect to a remote endpoint.

    +

    On success:

    + +

    Typical start errors

    + +

    Typical finish errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    finish-connect: func

    +
    Params
    + +
    Return values
    + +

    start-listen: func

    +

    Start listening for new connections.

    +

    Transitions the socket into the Listener state.

    +

    Unlike POSIX:

    + +

    Typical start errors

    + +

    Typical finish errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    finish-listen: func

    +
    Params
    + +
    Return values
    + +

    accept: func

    +

    Accept a new client socket.

    +

    The returned socket is bound and in the Connection state.

    +

    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

    + +

    Host implementations must skip over transient errors returned by the native accept syscall.

    +

    References

    + +
    Params
    + +
    Return values
    + +

    local-address: func

    +

    Get the bound local address.

    +

    Typical errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    remote-address: func

    +

    Get the bound remote address.

    +

    Typical errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    address-family: func

    +

    Whether this is a IPv4 or IPv6 socket.

    +

    Equivalent to the SO_DOMAIN socket option.

    +
    Params
    + +
    Return values
    + +

    ipv6-only: func

    +

    Whether IPv4 compatibility (dual-stack) mode is disabled or not.

    +

    Equivalent to the IPV6_V6ONLY socket option.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    set-ipv6-only: func

    +
    Params
    + +
    Return values
    + +

    set-listen-backlog-size: func

    +

    Hints the desired listen queue size. Implementations are free to ignore this.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    keep-alive: func

    +

    Equivalent to the SO_KEEPALIVE socket option.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    set-keep-alive: func

    +
    Params
    + +
    Return values
    + +

    no-delay: func

    +

    Equivalent to the TCP_NODELAY socket option.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    set-no-delay: func

    +
    Params
    + +
    Return values
    + +

    unicast-hop-limit: func

    +

    Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    set-unicast-hop-limit: func

    +
    Params
    + +
    Return values
    + +

    receive-buffer-size: func

    +

    The kernel buffer space reserved for sends/receives on this socket.

    +

    Note #1: an implementation may choose to cap or round the buffer size when setting the value. +In other words, after setting a value, reading the same setting back may return a different value.

    +

    Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of +actual data to be sent/received by the application, because the kernel might also use the buffer space +for internal metadata structures.

    +

    Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    set-receive-buffer-size: func

    +
    Params
    + +
    Return values
    + +

    send-buffer-size: func

    +
    Params
    + +
    Return values
    + +

    set-send-buffer-size: func

    +
    Params
    + +
    Return values
    + +

    subscribe: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    shutdown: func

    +

    Initiate a graceful shutdown.

    + +

    The shutdown function does not close (drop) the socket.

    +

    Typical errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    drop-tcp-socket: func

    +

    Dispose of the specified tcp-socket, after which it may no longer be used.

    +

    Similar to the POSIX close function.

    +

    Note: this function is scheduled to be removed when Resources are natively supported in Wit.

    +
    Params
    + +

    Import interface wasi:sockets/tcp-create-socket

    +
    +

    Types

    +

    type network

    +

    network

    +

    +#### `type error-code` +[`error-code`](#error_code) +

    +#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +

    +#### `type tcp-socket` +[`tcp-socket`](#tcp_socket) +

    +---- +

    Functions

    +

    create-tcp-socket: func

    +

    Create a new TCP socket.

    +

    Similar to socket(AF_INET or AF_INET6, SOCK_STREAM, IPPROTO_TCP) in POSIX.

    +

    This function does not require a network capability handle. This is considered to be safe because +at time of creation, the socket is not bound to any network yet. Up to the moment bind/listen/connect +is called, the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

    +

    All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

    +

    Typical errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    Import interface wasi:sockets/udp

    +
    +

    Types

    +

    type pollable

    +

    pollable

    +

    +#### `type network` +[`network`](#network) +

    +#### `type error-code` +[`error-code`](#error_code) +

    +#### `type ip-socket-address` +[`ip-socket-address`](#ip_socket_address) +

    +#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +

    +#### `type udp-socket` +`u32` +

    A UDP socket handle. +

    record datagram

    +
    Record Fields
    + +
    +

    Functions

    +

    start-bind: func

    +

    Bind the socket to a specific network on the provided IP address and port.

    +

    If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which +network interface(s) to bind to. +If the TCP/UDP port is zero, the socket will be bound to a random free port.

    +

    When a socket is not explicitly bound, the first invocation to connect will implicitly bind the socket.

    +

    Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.

    +

    Typical start errors

    + +

    Typical finish errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    finish-bind: func

    +
    Params
    + +
    Return values
    + +

    start-connect: func

    +

    Set the destination address.

    +

    The local-address is updated based on the best network path to remote-address.

    +

    When a destination address is set:

    + +

    Note that this function does not generate any network traffic and the peer is not aware of this "connection".

    +

    Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.

    +

    Typical start errors

    + +

    Typical finish errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    finish-connect: func

    +
    Params
    + +
    Return values
    + +

    receive: func

    +

    Receive messages on the socket.

    +

    This function attempts to receive up to max-results datagrams on the socket without blocking. +The returned list may contain fewer elements than requested, but never more. +If max-results is 0, this function returns successfully with an empty list.

    +

    Typical errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    send: func

    +

    Send messages on the socket.

    +

    This function attempts to send all provided datagrams on the socket without blocking and +returns how many messages were actually sent (or queued for sending).

    +

    This function semantically behaves the same as iterating the datagrams list and sequentially +sending each individual datagram until either the end of the list has been reached or the first error occurred. +If at least one datagram has been sent successfully, this function never returns an error.

    +

    If the input list is empty, the function returns ok(0).

    +

    The remote address option is required. To send a message to the "connected" peer, +call remote-address to get their address.

    +

    Typical errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    local-address: func

    +

    Get the current bound address.

    +

    Typical errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    remote-address: func

    +

    Get the address set with connect.

    +

    Typical errors

    + +

    References

    + +
    Params
    + +
    Return values
    + +

    address-family: func

    +

    Whether this is a IPv4 or IPv6 socket.

    +

    Equivalent to the SO_DOMAIN socket option.

    +
    Params
    + +
    Return values
    + +

    ipv6-only: func

    +

    Whether IPv4 compatibility (dual-stack) mode is disabled or not.

    +

    Equivalent to the IPV6_V6ONLY socket option.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    set-ipv6-only: func

    +
    Params
    + +
    Return values
    + +

    unicast-hop-limit: func

    +

    Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    set-unicast-hop-limit: func

    +
    Params
    + +
    Return values
    + +

    receive-buffer-size: func

    +

    The kernel buffer space reserved for sends/receives on this socket.

    +

    Note #1: an implementation may choose to cap or round the buffer size when setting the value. +In other words, after setting a value, reading the same setting back may return a different value.

    +

    Note #2: there is not necessarily a direct relationship between the kernel buffer size and the bytes of +actual data to be sent/received by the application, because the kernel might also use the buffer space +for internal metadata structures.

    +

    Fails when this socket is in the Listening state.

    +

    Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

    +

    Typical errors

    + +
    Params
    + +
    Return values
    + +

    set-receive-buffer-size: func

    +
    Params
    + +
    Return values
    + +

    send-buffer-size: func

    +
    Params
    + +
    Return values
    + +

    set-send-buffer-size: func

    +
    Params
    + +
    Return values
    + +

    subscribe: func

    +

    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.

    +
    Params
    + +
    Return values
    + +

    drop-udp-socket: func

    +

    Dispose of the specified udp-socket, after which it may no longer be used.

    +

    Note: this function is scheduled to be removed when Resources are natively supported in Wit.

    +
    Params
    + +

    Import interface wasi:sockets/udp-create-socket

    +
    +

    Types

    +

    type network

    +

    network

    +

    +#### `type error-code` +[`error-code`](#error_code) +

    +#### `type ip-address-family` +[`ip-address-family`](#ip_address_family) +

    +#### `type udp-socket` +[`udp-socket`](#udp_socket) +

    +---- +

    Functions

    +

    create-udp-socket: func

    +

    Create a new UDP socket.

    +

    Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP) in POSIX.

    +

    This function does not require a network capability handle. This is considered to be safe because +at time of creation, the socket is not bound to any network yet. Up to the moment bind/connect is called, +the socket is effectively an in-memory configuration object, unable to communicate with the outside world.

    +

    All sockets are non-blocking. Use the wasi-poll interface to block on asynchronous operations.

    +

    Typical errors

    + +

    References:

    + +
    Params
    + +
    Return values
    + +

    Import interface wasi:random/random

    +

    WASI Random is a random data API.

    +

    It is intended to be portable at least between Unix-family platforms and +Windows.

    +
    +

    Functions

    +

    get-random-bytes: func

    +

    Return len cryptographically-secure random or pseudo-random bytes.

    +

    This function must produce data at least as cryptographically secure and +fast as an adequately seeded cryptographically-secure pseudo-random +number generator (CSPRNG). It must not block, from the perspective of +the calling program, under any circumstances, including on the first +request and on requests for numbers of bytes. The returned data must +always be unpredictable.

    +

    This function must always return fresh data. Deterministic environments +must omit this function, rather than implementing it with deterministic +data.

    +
    Params
    + +
    Return values
    + +

    get-random-u64: func

    +

    Return a cryptographically-secure random or pseudo-random u64 value.

    +

    This function returns the same type of data as get-random-bytes, +represented as a u64.

    +
    Return values
    + +

    Import interface wasi:random/insecure

    +

    The insecure interface for insecure pseudo-random numbers.

    +

    It is intended to be portable at least between Unix-family platforms and +Windows.

    +
    +

    Functions

    +

    get-insecure-random-bytes: func

    +

    Return len insecure pseudo-random bytes.

    +

    This function is not cryptographically secure. Do not use it for +anything related to security.

    +

    There are no requirements on the values of the returned bytes, however +implementations are encouraged to return evenly distributed values with +a long period.

    +
    Params
    + +
    Return values
    + +

    get-insecure-random-u64: func

    +

    Return an insecure pseudo-random u64 value.

    +

    This function returns the same type of pseudo-random data as +get-insecure-random-bytes, represented as a u64.

    +
    Return values
    + +

    Import interface wasi:random/insecure-seed

    +

    The insecure-seed interface for seeding hash-map DoS resistance.

    +

    It is intended to be portable at least between Unix-family platforms and +Windows.

    +
    +

    Functions

    +

    insecure-seed: func

    +

    Return a 128-bit value that may contain a pseudo-random value.

    +

    The returned value is not required to be computed from a CSPRNG, and may +even be entirely deterministic. Host implementations are encouraged to +provide pseudo-random values to any program exposed to +attacker-controlled content, to enable DoS protection built into many +languages' hash-map implementations.

    +

    This function is intended to only be called once, by a source language +to initialize Denial Of Service (DoS) protection in its hash-map +implementation.

    +

    Expected future evolution

    +

    This will likely be changed to a value import, to prevent it from being +called multiple times and potentially used for purposes other than DoS +protection.

    +
    Return values
    + +

    Import interface wasi:cli/environment

    +
    +

    Functions

    +

    get-environment: func

    +

    Get the POSIX-style environment variables.

    +

    Each environment variable is provided as a pair of string variable names +and string value.

    +

    Morally, these are a value import, but until value imports are available +in the component model, this import function should return the same +values each time it is called.

    +
    Return values
    + +

    get-arguments: func

    +

    Get the POSIX-style arguments to the program.

    +
    Return values
    + +

    initial-cwd: func

    +

    Return a path that programs should use as their initial current working +directory, interpreting . as shorthand for this.

    +
    Return values
    + +

    Import interface wasi:cli/exit

    +
    +

    Functions

    +

    exit: func

    +

    Exit the current instance and any linked instances.

    +
    Params
    + +

    Import interface wasi:cli/stdin

    +
    +

    Types

    +

    type input-stream

    +

    input-stream

    +

    +---- +

    Functions

    +

    get-stdin: func

    +
    Return values
    + +

    Import interface wasi:cli/stdout

    +
    +

    Types

    +

    type output-stream

    +

    output-stream

    +

    +---- +

    Functions

    +

    get-stdout: func

    +
    Return values
    + +

    Import interface wasi:cli/stderr

    +
    +

    Types

    +

    type output-stream

    +

    output-stream

    +

    +---- +

    Functions

    +

    get-stderr: func

    +
    Return values
    + +

    Import interface wasi:cli/terminal-input

    +
    +

    Types

    +

    type terminal-input

    +

    u32

    +

    The input side of a terminal. +

    This represents a resource.

    +
    +

    Functions

    +

    drop-terminal-input: func

    +

    Dispose of the specified terminal-input after which it may no longer +be used.

    +
    Params
    + +

    Import interface wasi:cli/terminal-output

    +
    +

    Types

    +

    type terminal-output

    +

    u32

    +

    The output side of a terminal. +

    This represents a resource.

    +
    +

    Functions

    +

    drop-terminal-output: func

    +

    Dispose of the specified terminal-output, after which it may no longer +be used.

    +
    Params
    + +

    Import interface wasi:cli/terminal-stdin

    +

    An interface providing an optional terminal-input for stdin as a +link-time authority.

    +
    +

    Types

    +

    type terminal-input

    +

    terminal-input

    +

    +---- +

    Functions

    +

    get-terminal-stdin: func

    +

    If stdin is connected to a terminal, return a terminal-input handle +allowing further interaction with it.

    +
    Return values
    + +

    Import interface wasi:cli/terminal-stdout

    +

    An interface providing an optional terminal-output for stdout as a +link-time authority.

    +
    +

    Types

    +

    type terminal-output

    +

    terminal-output

    +

    +---- +

    Functions

    +

    get-terminal-stdout: func

    +

    If stdout is connected to a terminal, return a terminal-output handle +allowing further interaction with it.

    +
    Return values
    + +

    Import interface wasi:cli/terminal-stderr

    +

    An interface providing an optional terminal-output for stderr as a +link-time authority.

    +
    +

    Types

    +

    type terminal-output

    +

    terminal-output

    +

    +---- +

    Functions

    +

    get-terminal-stderr: func

    +

    If stderr is connected to a terminal, return a terminal-output handle +allowing further interaction with it.

    +
    Return values
    + From 28ccb9535983a95a0ffc82cf09f62a61e0d813f7 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 12 Sep 2023 13:46:42 -0700 Subject: [PATCH 3/4] Fix repo name --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 071dda3..088a841 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -18,6 +18,6 @@ jobs: ./wit-deps lock git add -N wit/deps git diff --exit-code - - uses: alexcrichton/wasi-abi-up-to-date@update-to-wit-bindgen + - uses: alexcrichton/wai-abi-up-to-date@update-to-wit-bindgen with: worlds: "command reactor" From 909219eea5f5326e8976d44404a64d129a938283 Mon Sep 17 00:00:00 2001 From: Alex Crichton Date: Tue, 12 Sep 2023 13:55:40 -0700 Subject: [PATCH 4/4] Switch to official action --- .github/workflows/main.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 088a841..edf6612 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -18,6 +18,6 @@ jobs: ./wit-deps lock git add -N wit/deps git diff --exit-code - - uses: alexcrichton/wai-abi-up-to-date@update-to-wit-bindgen + - uses: WebAssembly/wit-abi-up-to-date@v14 with: worlds: "command reactor"