diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 113cfe9..8a72c4d 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -16,7 +16,7 @@ jobs: curl -Lo 'wit-deps' https://github.com/bytecodealliance/wit-deps/releases/download/v0.3.2/wit-deps-x86_64-unknown-linux-musl chmod +x ./wit-deps ./wit-deps lock --check - - uses: WebAssembly/wit-abi-up-to-date@v17 + - uses: WebAssembly/wit-abi-up-to-date@v21 with: - wit-bindgen: '0.17.0' - worlds: 'imports proxy' \ No newline at end of file + wit-bindgen: '0.26.0' + worlds: 'imports proxy' diff --git a/imports.md b/imports.md index db11f4c..e99ef31 100644 --- a/imports.md +++ b/imports.md @@ -4,21 +4,21 @@ It is intended to be included in other worlds.

-

Import interface wasi:random/random@0.2.0

+

Import interface wasi:random/random@0.2.0

WASI Random is a random data API.

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

@@ -51,7 +51,7 @@ represented as a u64.

-

Import interface wasi:io/error@0.2.0

+

Import interface wasi:io/error@0.2.0

Types

resource error

@@ -61,17 +61,15 @@ which provides some human-readable information about the error.

In the wasi:io package, this resource is returned through the wasi:io/streams/stream-error type.

To provide more specific error information, other interfaces may -provide functions to further "downcast" this error into more specific -error information. For example, errors returned in streams derived -from filesystem types to be described using the filesystem's own -error-code type, using the function -wasi:filesystem/types/filesystem-error-code, which takes a parameter -borrow<error> and returns -option<wasi:filesystem/types/error-code>.

+offer functions to "downcast" this error into more specific types. For example, +errors returned from streams derived from filesystem types can be described using +the filesystem's own error-code type. This is done using the function +wasi:filesystem/types/filesystem-error-code, which takes a borrow<error> +parameter and returns an option<wasi:filesystem/types/error-code>.

The set of functions which can "downcast" an error into a more concrete type is open.

Functions

-

[method]error.to-debug-string: func

+

[method]error.to-debug-string: func

Returns a string that is suitable to assist humans in debugging this error.

WARNING: The returned string should not be consumed mechanically! @@ -80,13 +78,13 @@ details. Parsing this string is a major platform-compatibility hazard.

Params
Return values
-

Import interface wasi:io/poll@0.2.0

+

Import interface wasi:io/poll@0.2.0

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

@@ -94,25 +92,25 @@ at once.

resource pollable

pollable represents a single I/O event which may be ready, or not.

Functions

-

[method]pollable.ready: func

+

[method]pollable.ready: func

Return the readiness of a pollable. This function never blocks.

Returns true when the pollable is ready, and false otherwise.

Params
Return values
-

[method]pollable.block: func

+

[method]pollable.block: func

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.

Params

poll: func

Poll for completion on a set of pollables.

@@ -120,14 +118,17 @@ containing only this pollable.

interest, and waits until one or more of the events is ready for I/O.

The result list<u32> contains one or more indices of handles in the argument list that is ready for I/O.

-

If the list contains more elements than can be indexed with a u32 -value, this function traps.

+

This function traps if either:

+

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 -being reaedy for I/O.

+being ready for I/O.

Params

subscribe-instant: func

Create a pollable which will resolve once the specified instant -occured.

+has occurred.

Params

subscribe-duration: func

-

Create a pollable which will resolve once the given duration has -elapsed, starting at the time at which this function was called. -occured.

+

Create a pollable that will resolve after the specified duration has +elapsed from the time this function is invoked.

Params
-

Import interface wasi:clocks/wall-clock@0.2.0

+

Import interface wasi:clocks/wall-clock@0.2.0

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.

diff --git a/proxy.md b/proxy.md index af5c193..ac879d4 100644 --- a/proxy.md +++ b/proxy.md @@ -6,26 +6,26 @@ outgoing HTTP requests.

-

Import interface wasi:io/poll@0.2.0

+

Import interface wasi:io/poll@0.2.0

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

@@ -33,25 +33,25 @@ at once.

resource pollable

pollable represents a single I/O event which may be ready, or not.

Functions

-

[method]pollable.ready: func

+

[method]pollable.ready: func

Return the readiness of a pollable. This function never blocks.

Returns true when the pollable is ready, and false otherwise.

Params
Return values
-

[method]pollable.block: func

+

[method]pollable.block: func

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.

Params

poll: func

Poll for completion on a set of pollables.

@@ -59,14 +59,17 @@ containing only this pollable.

interest, and waits until one or more of the events is ready for I/O.

The result list<u32> contains one or more indices of handles in the argument list that is ready for I/O.

-

If the list contains more elements than can be indexed with a u32 -value, this function traps.

+

This function traps if either:

+

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 -being reaedy for I/O.

+being ready for I/O.

Params

subscribe-instant: func

Create a pollable which will resolve once the specified instant -occured.

+has occurred.

Params

subscribe-duration: func

-

Create a pollable which will resolve once the given duration has -elapsed, starting at the time at which this function was called. -occured.

+

Create a pollable that will resolve after the specified duration has +elapsed from the time this function is invoked.

Params
-

Import interface wasi:clocks/wall-clock@0.2.0

+

Import interface wasi:clocks/wall-clock@0.2.0

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.

@@ -1536,7 +1538,7 @@ also known as Unix Time.
  • datetime
    • -

    Export interface wasi:http/incoming-handler@0.2.0

    +

    Export interface wasi:http/incoming-handler@0.2.0

    Types

    type incoming-request

    diff --git a/wit/deps.lock b/wit/deps.lock index 96be4b2..34441a5 100644 --- a/wit/deps.lock +++ b/wit/deps.lock @@ -1,29 +1,29 @@ [cli] url = "https://github.com/WebAssembly/wasi-cli/archive/main.tar.gz" -sha256 = "285865a31d777181b075f39e92bcfe59c89cd6bacce660be1b9a627646956258" -sha512 = "da2622210a9e3eea82b99f1a5b8a44ce5443d009cb943f7bca0bf9cf4360829b289913d7ee727c011f0f72994ea7dc8e661ebcc0a6b34b587297d80cd9b3f7e8" +sha256 = "a690bfee4b365af5ec012cb664c82ce53076bef5263d3da45c5da42271eaf98c" +sha512 = "21e687cb2d8d7ba2ba5bcf40ef43b8c68e4f2c1c6e8dd147166e695b3462a1650d2b806636c8608e8b42d24a498016a003d6127ebb784bf4f5b329ed1d07817e" [clocks] url = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz" -sha256 = "468b4d12892fe926b8eb5d398dbf579d566c93231fa44f415440572c695b7613" -sha512 = "e6b53a07221f1413953c9797c68f08b815fdaebf66419bbc1ea3e8b7dece73731062693634731f311a03957b268cf9cc509c518bd15e513c318aa04a8459b93a" +sha256 = "b7fbb753c70fe6727ea3456bc2cde3230df69d1f4f004cda7014625783959e50" +sha512 = "99310e017418553a0613247a65aef39e46b08b27f2d3d170465f5ecb97ec9c0ccbcb4e358526440ba6ef9d37cf991d04367ffa6b87d2d8db4e1b36a737f2191e" [filesystem] url = "https://github.com/WebAssembly/wasi-filesystem/archive/main.tar.gz" -sha256 = "498c465cfd04587db40f970fff2185daa597d074c20b68a8bcbae558f261499b" -sha512 = "ead452f9b7bfb88593a502ec00d76d4228003d51c40fd0408aebc32d35c94673551b00230d730873361567cc209ec218c41fb4e95bad194268592c49e7964347" +sha256 = "cc45d3ebf145274e7e4d1eb516099c87c68ef6062447e3f8bcd492d60dfa27a8" +sha512 = "0b0af2b253de228fb282f270f5337df728834421000b6a2a789cc47460b36548babd1f77eca698308fef00896ce3c8509071b0da636babd6e87599e4d1400e53" [io] url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz" -sha256 = "7210e5653539a15478f894d4da24cc69d61924cbcba21d2804d69314a88e5a4c" -sha512 = "49184a1b0945a889abd52d25271172ed3dc2db6968fcdddb1bab7ee0081f4a3eeee0977ad2291126a37631c0d86eeea75d822fa8af224c422134500bf9f0f2bb" +sha256 = "f1d1f111840529e06cd5f53726ebac82f344caf64f65a38dfef84e036643ef75" +sha512 = "8a09fb15e4a5d46c910d4a05ed90551166192dcfb28309f08f23237ad926fb4685ce95f06905929cb47e209b291b26d1baa92c3e3dbabf81308654453927ec26" [random] url = "https://github.com/WebAssembly/wasi-random/archive/main.tar.gz" -sha256 = "7371d03c037d924caba2587fb2e7c5773a0d3c5fcecbf7971e0e0ba57973c53d" -sha512 = "964c4e8925a53078e4d94ba907b54f89a0b7e154f46823a505391471466c17f53c8692682e5c85771712acd88b348686173fc07c53a3cfe3d301b8cd8ddd0de4" +sha256 = "2f0014e946e38947afe120836b17cdcfa608be993d38d55b81cc2d31e7e70b16" +sha512 = "51ee623509040de77b0ba236e29589102538aacd3dd67168b06a09bf6ae469c762818fc07b5039d2a8b1838f4b5a5965a7c81ed0e2d47b142bece9d1ab8b93a6" [sockets] url = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz" -sha256 = "622bd28bbeb43736375dc02bd003fd3a016ff8ee91e14bab488325c6b38bf966" -sha512 = "5a63c1f36de0c4548e1d2297bdbededb28721cbad94ef7825c469eae29d7451c97e00b4c1d6730ee1ec0c4a5aac922961a2795762d4a0c3bb54e30a391a84bae" +sha256 = "5321ba37115d503bfe0880349e99ecbd26ee812708fa83d2b276ec8ee7571443" +sha512 = "c3d71c2afa1475bf10d86b1e0623e2292e5dd407cf54103ad0d05c07fa95323bff9ad06e929d508b318a0a99a67132793fb9a04c17585843e24f090f5ee91367" diff --git a/wit/deps/cli/command.wit b/wit/deps/cli/command.wit index d8005bd..0fc85e9 100644 --- a/wit/deps/cli/command.wit +++ b/wit/deps/cli/command.wit @@ -1,7 +1,10 @@ package wasi:cli@0.2.0; +@since(version = 0.2.0) world command { + @since(version = 0.2.0) include imports; + @since(version = 0.2.0) export run; } diff --git a/wit/deps/cli/environment.wit b/wit/deps/cli/environment.wit index 7006523..2f449bd 100644 --- a/wit/deps/cli/environment.wit +++ b/wit/deps/cli/environment.wit @@ -1,3 +1,4 @@ +@since(version = 0.2.0) interface environment { /// Get the POSIX-style environment variables. /// @@ -7,12 +8,15 @@ interface environment { /// 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. + @since(version = 0.2.0) get-environment: func() -> list>; /// Get the POSIX-style arguments to the program. + @since(version = 0.2.0) get-arguments: func() -> list; /// Return a path that programs should use as their initial current working /// directory, interpreting `.` as shorthand for this. + @since(version = 0.2.0) initial-cwd: func() -> option; } diff --git a/wit/deps/cli/exit.wit b/wit/deps/cli/exit.wit index d0c2b82..357e670 100644 --- a/wit/deps/cli/exit.wit +++ b/wit/deps/cli/exit.wit @@ -1,4 +1,6 @@ +@since(version = 0.2.0) interface exit { /// Exit the current instance and any linked instances. + @since(version = 0.2.0) exit: func(status: result); } diff --git a/wit/deps/cli/imports.wit b/wit/deps/cli/imports.wit index 083b84a..cd59ba1 100644 --- a/wit/deps/cli/imports.wit +++ b/wit/deps/cli/imports.wit @@ -1,20 +1,36 @@ package wasi:cli@0.2.0; +@since(version = 0.2.0) world imports { + @since(version = 0.2.0) include wasi:clocks/imports@0.2.0; + @since(version = 0.2.0) include wasi:filesystem/imports@0.2.0; + @since(version = 0.2.0) include wasi:sockets/imports@0.2.0; + @since(version = 0.2.0) include wasi:random/imports@0.2.0; + @since(version = 0.2.0) include wasi:io/imports@0.2.0; + @since(version = 0.2.0) import environment; + @since(version = 0.2.0) import exit; + @since(version = 0.2.0) import stdin; + @since(version = 0.2.0) import stdout; + @since(version = 0.2.0) import stderr; + @since(version = 0.2.0) import terminal-input; + @since(version = 0.2.0) import terminal-output; + @since(version = 0.2.0) import terminal-stdin; + @since(version = 0.2.0) import terminal-stdout; + @since(version = 0.2.0) import terminal-stderr; } diff --git a/wit/deps/cli/run.wit b/wit/deps/cli/run.wit index a70ee8c..655346e 100644 --- a/wit/deps/cli/run.wit +++ b/wit/deps/cli/run.wit @@ -1,4 +1,6 @@ +@since(version = 0.2.0) interface run { /// Run the program. + @since(version = 0.2.0) run: func() -> result; } diff --git a/wit/deps/cli/stdio.wit b/wit/deps/cli/stdio.wit index 31ef35b..e9502a9 100644 --- a/wit/deps/cli/stdio.wit +++ b/wit/deps/cli/stdio.wit @@ -1,17 +1,26 @@ +@since(version = 0.2.0) interface stdin { + @since(version = 0.2.0) use wasi:io/streams@0.2.0.{input-stream}; + @since(version = 0.2.0) get-stdin: func() -> input-stream; } +@since(version = 0.2.0) interface stdout { + @since(version = 0.2.0) use wasi:io/streams@0.2.0.{output-stream}; + @since(version = 0.2.0) get-stdout: func() -> output-stream; } +@since(version = 0.2.0) interface stderr { + @since(version = 0.2.0) use wasi:io/streams@0.2.0.{output-stream}; + @since(version = 0.2.0) get-stderr: func() -> output-stream; } diff --git a/wit/deps/cli/terminal.wit b/wit/deps/cli/terminal.wit index 38c724e..d305498 100644 --- a/wit/deps/cli/terminal.wit +++ b/wit/deps/cli/terminal.wit @@ -3,8 +3,10 @@ /// In the future, this may include functions for disabling echoing, /// disabling input buffering so that keyboard events are sent through /// immediately, querying supported features, and so on. +@since(version = 0.2.0) interface terminal-input { /// The input side of a terminal. + @since(version = 0.2.0) resource terminal-input; } @@ -13,37 +15,48 @@ interface terminal-input { /// In the future, this may include functions for querying the terminal /// size, being notified of terminal size changes, querying supported /// features, and so on. +@since(version = 0.2.0) interface terminal-output { /// The output side of a terminal. + @since(version = 0.2.0) resource terminal-output; } /// An interface providing an optional `terminal-input` for stdin as a /// link-time authority. +@since(version = 0.2.0) interface terminal-stdin { + @since(version = 0.2.0) use terminal-input.{terminal-input}; /// If stdin is connected to a terminal, return a `terminal-input` handle /// allowing further interaction with it. + @since(version = 0.2.0) get-terminal-stdin: func() -> option; } /// An interface providing an optional `terminal-output` for stdout as a /// link-time authority. +@since(version = 0.2.0) interface terminal-stdout { + @since(version = 0.2.0) use terminal-output.{terminal-output}; /// If stdout is connected to a terminal, return a `terminal-output` handle /// allowing further interaction with it. + @since(version = 0.2.0) get-terminal-stdout: func() -> option; } /// An interface providing an optional `terminal-output` for stderr as a /// link-time authority. +@since(version = 0.2.0) interface terminal-stderr { + @since(version = 0.2.0) use terminal-output.{terminal-output}; /// If stderr is connected to a terminal, return a `terminal-output` handle /// allowing further interaction with it. + @since(version = 0.2.0) get-terminal-stderr: func() -> option; } diff --git a/wit/deps/clocks/monotonic-clock.wit b/wit/deps/clocks/monotonic-clock.wit index 4e4dc3a..afbd700 100644 --- a/wit/deps/clocks/monotonic-clock.wit +++ b/wit/deps/clocks/monotonic-clock.wit @@ -7,38 +7,43 @@ package wasi:clocks@0.2.0; /// /// 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. +@since(version = 0.2.0) interface monotonic-clock { + @since(version = 0.2.0) use wasi:io/poll@0.2.0.{pollable}; /// An instant in time, in nanoseconds. An instant is relative to an /// unspecified initial value, and can only be compared to instances from /// the same monotonic-clock. + @since(version = 0.2.0) type instant = u64; /// A duration of time, in nanoseconds. + @since(version = 0.2.0) type duration = u64; /// Read the current value of the clock. /// /// The clock is monotonic, therefore calling this function repeatedly will /// produce a sequence of non-decreasing values. + @since(version = 0.2.0) now: func() -> instant; /// Query the resolution of the clock. Returns the duration of time /// corresponding to a clock tick. + @since(version = 0.2.0) resolution: func() -> duration; /// Create a `pollable` which will resolve once the specified instant - /// occured. + /// has occurred. + @since(version = 0.2.0) subscribe-instant: func( when: instant, ) -> pollable; - /// Create a `pollable` which will resolve once the given duration has - /// elapsed, starting at the time at which this function was called. - /// occured. + /// Create a `pollable` that will resolve after the specified duration has + /// elapsed from the time this function is invoked. + @since(version = 0.2.0) subscribe-duration: func( when: duration, ) -> pollable; diff --git a/wit/deps/clocks/timezone.wit b/wit/deps/clocks/timezone.wit new file mode 100644 index 0000000..3c28688 --- /dev/null +++ b/wit/deps/clocks/timezone.wit @@ -0,0 +1,55 @@ +package wasi:clocks@0.2.0; + +@unstable(feature = clocks-timezone) +interface timezone { + @unstable(feature = clocks-timezone) + use wall-clock.{datetime}; + + /// 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. + @unstable(feature = clocks-timezone) + display: func(when: datetime) -> timezone-display; + + /// The same as `display`, but only return the UTC offset. + @unstable(feature = clocks-timezone) + utc-offset: func(when: datetime) -> s32; + + /// Information useful for displaying the timezone of a specific `datetime`. + /// + /// This information may vary within a single `timezone` to reflect daylight + /// saving time adjustments. + @unstable(feature = clocks-timezone) + record timezone-display { + /// The number of seconds difference between UTC time and the local + /// time of the timezone. + /// + /// The returned value will always be less than 86400 which is the + /// number of seconds in a day (24*60*60). + /// + /// In implementations that do not expose an actual time zone, this + /// should return 0. + utc-offset: s32, + + /// The abbreviated name of the timezone to display to a user. The name + /// `UTC` indicates Coordinated Universal Time. Otherwise, this should + /// reference local standards for the name of the time zone. + /// + /// In implementations that do not expose an actual time zone, this + /// should be the string `UTC`. + /// + /// In time zones that do not have an applicable name, a formatted + /// representation of the UTC offset may be returned, such as `-04:00`. + name: string, + + /// Whether daylight saving time is active. + /// + /// In implementations that do not expose an actual time zone, this + /// should return false. + in-daylight-saving-time: bool, + } +} diff --git a/wit/deps/clocks/wall-clock.wit b/wit/deps/clocks/wall-clock.wit index 440ca0f..4b08d71 100644 --- a/wit/deps/clocks/wall-clock.wit +++ b/wit/deps/clocks/wall-clock.wit @@ -13,8 +13,10 @@ package wasi:clocks@0.2.0; /// monotonic, making it unsuitable for measuring elapsed time. /// /// It is intended for reporting the current date and time for humans. +@since(version = 0.2.0) interface wall-clock { /// A time and date in seconds plus nanoseconds. + @since(version = 0.2.0) record datetime { seconds: u64, nanoseconds: u32, @@ -33,10 +35,12 @@ interface wall-clock { /// /// [POSIX's Seconds Since the Epoch]: https://pubs.opengroup.org/onlinepubs/9699919799/xrat/V4_xbd_chap04.html#tag_21_04_16 /// [Unix Time]: https://en.wikipedia.org/wiki/Unix_time + @since(version = 0.2.0) now: func() -> datetime; /// Query the resolution of the clock. /// /// The nanoseconds field of the output is always less than 1000000000. + @since(version = 0.2.0) resolution: func() -> datetime; } diff --git a/wit/deps/clocks/world.wit b/wit/deps/clocks/world.wit index c022457..76a9206 100644 --- a/wit/deps/clocks/world.wit +++ b/wit/deps/clocks/world.wit @@ -1,6 +1,11 @@ package wasi:clocks@0.2.0; +@since(version = 0.2.0) world imports { + @since(version = 0.2.0) import monotonic-clock; + @since(version = 0.2.0) import wall-clock; + @unstable(feature = clocks-timezone) + import timezone; } diff --git a/wit/deps/filesystem/preopens.wit b/wit/deps/filesystem/preopens.wit index da801f6..08094ab 100644 --- a/wit/deps/filesystem/preopens.wit +++ b/wit/deps/filesystem/preopens.wit @@ -1,8 +1,11 @@ package wasi:filesystem@0.2.0; +@since(version = 0.2.0) interface preopens { + @since(version = 0.2.0) use types.{descriptor}; /// Return the set of preopened directories, and their path. + @since(version = 0.2.0) get-directories: func() -> list>; } diff --git a/wit/deps/filesystem/types.wit b/wit/deps/filesystem/types.wit index 11108fc..d061d5f 100644 --- a/wit/deps/filesystem/types.wit +++ b/wit/deps/filesystem/types.wit @@ -23,16 +23,21 @@ package wasi:filesystem@0.2.0; /// [WASI filesystem path resolution]. /// /// [WASI filesystem path resolution]: https://github.com/WebAssembly/wasi-filesystem/blob/main/path-resolution.md +@since(version = 0.2.0) interface types { + @since(version = 0.2.0) use wasi:io/streams@0.2.0.{input-stream, output-stream, error}; + @since(version = 0.2.0) use wasi:clocks/wall-clock@0.2.0.{datetime}; /// File size or length of a region within a file. + @since(version = 0.2.0) type filesize = u64; /// The type of a filesystem object referenced by a descriptor. /// /// Note: This was called `filetype` in earlier versions of WASI. + @since(version = 0.2.0) enum descriptor-type { /// The type of the descriptor or file is unknown or is different from /// any of the other types specified. @@ -56,6 +61,7 @@ interface types { /// Descriptor flags. /// /// Note: This was called `fdflags` in earlier versions of WASI. + @since(version = 0.2.0) flags descriptor-flags { /// Read mode: Data can be read. read, @@ -77,7 +83,7 @@ interface types { /// WASI. At this time, it should be interpreted as a request, and not a /// requirement. data-integrity-sync, - /// Requests that reads be performed at the same level of integrety + /// Requests that reads be performed at the same level of integrity /// requested for writes. This is similar to `O_RSYNC` in POSIX. /// /// The precise semantics of this operation have not yet been defined for @@ -99,6 +105,7 @@ interface types { /// File attributes. /// /// Note: This was called `filestat` in earlier versions of WASI. + @since(version = 0.2.0) record descriptor-stat { /// File type. %type: descriptor-type, @@ -125,6 +132,7 @@ interface types { } /// Flags determining the method of how paths are resolved. + @since(version = 0.2.0) flags path-flags { /// As long as the resolved path corresponds to a symbolic link, it is /// expanded. @@ -132,6 +140,7 @@ interface types { } /// Open flags used by `open-at`. + @since(version = 0.2.0) flags open-flags { /// Create file if it does not exist, similar to `O_CREAT` in POSIX. create, @@ -144,9 +153,11 @@ interface types { } /// Number of hard links to an inode. + @since(version = 0.2.0) type link-count = u64; /// When setting a timestamp, this gives the value to set it to. + @since(version = 0.2.0) variant new-timestamp { /// Leave the timestamp set to its previous value. no-change, @@ -248,6 +259,7 @@ interface types { } /// File or memory access pattern advisory information. + @since(version = 0.2.0) enum advice { /// The application has no advice to give on its behavior with respect /// to the specified data. @@ -271,6 +283,7 @@ interface types { /// A 128-bit hash value, split into parts because wasm doesn't have a /// 128-bit integer type. + @since(version = 0.2.0) record metadata-hash-value { /// 64 bits of a 128-bit hash value. lower: u64, @@ -281,6 +294,7 @@ interface types { /// 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. + @since(version = 0.2.0) resource descriptor { /// Return a stream for reading from a file, if available. /// @@ -290,6 +304,7 @@ interface types { /// file and they do not interfere with each other. /// /// Note: This allows using `read-stream`, which is similar to `read` in POSIX. + @since(version = 0.2.0) read-via-stream: func( /// The offset within the file at which to start reading. offset: filesize, @@ -301,6 +316,7 @@ interface types { /// /// Note: This allows using `write-stream`, which is similar to `write` in /// POSIX. + @since(version = 0.2.0) write-via-stream: func( /// The offset within the file at which to start writing. offset: filesize, @@ -312,11 +328,13 @@ interface types { /// /// Note: This allows using `write-stream`, which is similar to `write` with /// `O_APPEND` in in POSIX. + @since(version = 0.2.0) append-via-stream: func() -> result; /// Provide file advisory information on a descriptor. /// /// This is similar to `posix_fadvise` in POSIX. + @since(version = 0.2.0) advise: func( /// The offset within the file to which the advisory applies. offset: filesize, @@ -332,6 +350,7 @@ interface types { /// opened for writing. /// /// Note: This is similar to `fdatasync` in POSIX. + @since(version = 0.2.0) sync-data: func() -> result<_, error-code>; /// Get flags associated with a descriptor. @@ -340,6 +359,7 @@ interface types { /// /// Note: This returns the value that was the `fs_flags` value returned /// from `fdstat_get` in earlier versions of WASI. + @since(version = 0.2.0) get-flags: func() -> result; /// Get the dynamic type of a descriptor. @@ -352,12 +372,14 @@ interface types { /// /// Note: This returns the value that was the `fs_filetype` value returned /// from `fdstat_get` in earlier versions of WASI. + @since(version = 0.2.0) get-type: func() -> result; /// 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. + @since(version = 0.2.0) set-size: func(size: filesize) -> result<_, error-code>; /// Adjust the timestamps of an open file or directory. @@ -365,6 +387,7 @@ interface types { /// Note: This is similar to `futimens` in POSIX. /// /// Note: This was called `fd_filestat_set_times` in earlier versions of WASI. + @since(version = 0.2.0) set-times: func( /// The desired values of the data access timestamp. data-access-timestamp: new-timestamp, @@ -383,6 +406,7 @@ interface types { /// In the future, this may change to return a `stream`. /// /// Note: This is similar to `pread` in POSIX. + @since(version = 0.2.0) read: func( /// The maximum number of bytes to read. length: filesize, @@ -399,6 +423,7 @@ interface types { /// In the future, this may change to take a `stream`. /// /// Note: This is similar to `pwrite` in POSIX. + @since(version = 0.2.0) write: func( /// Data to write buffer: list, @@ -415,6 +440,7 @@ interface types { /// 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. + @since(version = 0.2.0) read-directory: func() -> result; /// Synchronize the data and metadata of a file to disk. @@ -423,11 +449,13 @@ interface types { /// opened for writing. /// /// Note: This is similar to `fsync` in POSIX. + @since(version = 0.2.0) sync: func() -> result<_, error-code>; /// Create a directory. /// /// Note: This is similar to `mkdirat` in POSIX. + @since(version = 0.2.0) create-directory-at: func( /// The relative path at which to create the directory. path: string, @@ -442,6 +470,7 @@ interface types { /// modified, use `metadata-hash`. /// /// Note: This was called `fd_filestat_get` in earlier versions of WASI. + @since(version = 0.2.0) stat: func() -> result; /// Return the attributes of a file or directory. @@ -451,6 +480,7 @@ interface types { /// discussion of alternatives. /// /// Note: This was called `path_filestat_get` in earlier versions of WASI. + @since(version = 0.2.0) stat-at: func( /// Flags determining the method of how the path is resolved. path-flags: path-flags, @@ -464,6 +494,7 @@ interface types { /// /// Note: This was called `path_filestat_set_times` in earlier versions of /// WASI. + @since(version = 0.2.0) set-times-at: func( /// Flags determining the method of how the path is resolved. path-flags: path-flags, @@ -478,6 +509,7 @@ interface types { /// Create a hard link. /// /// Note: This is similar to `linkat` in POSIX. + @since(version = 0.2.0) link-at: func( /// Flags determining the method of how the path is resolved. old-path-flags: path-flags, @@ -507,6 +539,7 @@ interface types { /// `error-code::read-only`. /// /// Note: This is similar to `openat` in POSIX. + @since(version = 0.2.0) open-at: func( /// Flags determining the method of how the path is resolved. path-flags: path-flags, @@ -524,6 +557,7 @@ interface types { /// filesystem, this function fails with `error-code::not-permitted`. /// /// Note: This is similar to `readlinkat` in POSIX. + @since(version = 0.2.0) readlink-at: func( /// The relative path of the symbolic link from which to read. path: string, @@ -534,6 +568,7 @@ interface types { /// Return `error-code::not-empty` if the directory is not empty. /// /// Note: This is similar to `unlinkat(fd, path, AT_REMOVEDIR)` in POSIX. + @since(version = 0.2.0) remove-directory-at: func( /// The relative path to a directory to remove. path: string, @@ -542,6 +577,7 @@ interface types { /// Rename a filesystem object. /// /// Note: This is similar to `renameat` in POSIX. + @since(version = 0.2.0) rename-at: func( /// The relative source path of the file or directory to rename. old-path: string, @@ -557,6 +593,7 @@ interface types { /// `error-code::not-permitted`. /// /// Note: This is similar to `symlinkat` in POSIX. + @since(version = 0.2.0) symlink-at: func( /// The contents of the symbolic link. old-path: string, @@ -568,6 +605,7 @@ interface types { /// /// Return `error-code::is-directory` if the path refers to a directory. /// Note: This is similar to `unlinkat(fd, path, 0)` in POSIX. + @since(version = 0.2.0) unlink-file-at: func( /// The relative path to a file to unlink. path: string, @@ -579,6 +617,7 @@ interface types { /// 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. + @since(version = 0.2.0) is-same-object: func(other: borrow) -> bool; /// Return a hash of the metadata associated with a filesystem object referred @@ -600,12 +639,14 @@ interface types { /// computed hash. /// /// However, none of these is required. + @since(version = 0.2.0) metadata-hash: func() -> result; /// 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`. + @since(version = 0.2.0) metadata-hash-at: func( /// Flags determining the method of how the path is resolved. path-flags: path-flags, @@ -615,8 +656,10 @@ interface types { } /// A stream of directory entries. + @since(version = 0.2.0) resource directory-entry-stream { /// Read a single directory entry from a `directory-entry-stream`. + @since(version = 0.2.0) read-directory-entry: func() -> result, error-code>; } @@ -630,5 +673,6 @@ interface types { /// /// Note that this function is fallible because not all stream-related /// errors are filesystem-related errors. + @since(version = 0.2.0) filesystem-error-code: func(err: borrow) -> option; } diff --git a/wit/deps/filesystem/world.wit b/wit/deps/filesystem/world.wit index 663f579..c8d99f5 100644 --- a/wit/deps/filesystem/world.wit +++ b/wit/deps/filesystem/world.wit @@ -1,6 +1,9 @@ package wasi:filesystem@0.2.0; +@since(version = 0.2.0) world imports { + @since(version = 0.2.0) import types; + @since(version = 0.2.0) import preopens; } diff --git a/wit/deps/io/error.wit b/wit/deps/io/error.wit index 22e5b64..7e66dbb 100644 --- a/wit/deps/io/error.wit +++ b/wit/deps/io/error.wit @@ -1,6 +1,6 @@ package wasi:io@0.2.0; - +@since(version = 0.2.0) interface error { /// A resource which represents some error information. /// @@ -11,16 +11,15 @@ interface error { /// `wasi:io/streams/stream-error` type. /// /// To provide more specific error information, other interfaces may - /// provide functions to further "downcast" this error into more specific - /// error information. For example, `error`s returned in streams derived - /// from filesystem types to be described using the filesystem's own - /// error-code type, using the function - /// `wasi:filesystem/types/filesystem-error-code`, which takes a parameter - /// `borrow` and returns - /// `option`. + /// offer functions to "downcast" this error into more specific types. For example, + /// errors returned from streams derived from filesystem types can be described using + /// the filesystem's own error-code type. This is done using the function + /// `wasi:filesystem/types/filesystem-error-code`, which takes a `borrow` + /// parameter and returns an `option`. /// /// The set of functions which can "downcast" an `error` into a more /// concrete type is open. + @since(version = 0.2.0) resource error { /// Returns a string that is suitable to assist humans in debugging /// this error. @@ -29,6 +28,7 @@ interface error { /// It may change across platforms, hosts, or other implementation /// details. Parsing this string is a major platform-compatibility /// hazard. + @since(version = 0.2.0) to-debug-string: func() -> string; } } diff --git a/wit/deps/io/poll.wit b/wit/deps/io/poll.wit index ddc67f8..cbdc960 100644 --- a/wit/deps/io/poll.wit +++ b/wit/deps/io/poll.wit @@ -2,13 +2,16 @@ package wasi:io@0.2.0; /// A poll API intended to let users wait for I/O events on multiple handles /// at once. +@since(version = 0.2.0) interface poll { /// `pollable` represents a single I/O event which may be ready, or not. + @since(version = 0.2.0) resource pollable { /// Return the readiness of a pollable. This function never blocks. /// /// Returns `true` when the pollable is ready, and `false` otherwise. + @since(version = 0.2.0) ready: func() -> bool; /// `block` returns immediately if the pollable is ready, and otherwise @@ -16,6 +19,7 @@ interface poll { /// /// This function is equivalent to calling `poll.poll` on a list /// containing only this pollable. + @since(version = 0.2.0) block: func(); } @@ -27,8 +31,9 @@ interface poll { /// The result `list` contains one or more indices of handles in the /// argument list that is ready for I/O. /// - /// If the list contains more elements than can be indexed with a `u32` - /// value, this function traps. + /// This function traps if either: + /// - the list is empty, or: + /// - the list contains more elements than can be indexed with a `u32` value. /// /// A timeout can be implemented by adding a pollable from the /// wasi-clocks API to the list. @@ -36,6 +41,7 @@ interface poll { /// 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 - /// being reaedy for I/O. + /// being ready for I/O. + @since(version = 0.2.0) poll: func(in: list>) -> list; } diff --git a/wit/deps/io/streams.wit b/wit/deps/io/streams.wit index 6d2f871..b5e2a36 100644 --- a/wit/deps/io/streams.wit +++ b/wit/deps/io/streams.wit @@ -5,11 +5,15 @@ package wasi:io@0.2.0; /// /// In the future, the component model is expected to add built-in stream types; /// when it does, they are expected to subsume this API. +@since(version = 0.2.0) interface streams { + @since(version = 0.2.0) use error.{error}; + @since(version = 0.2.0) use poll.{pollable}; /// An error for input-stream and output-stream operations. + @since(version = 0.2.0) variant stream-error { /// The last operation (a write or flush) failed before completion. /// @@ -29,6 +33,7 @@ interface streams { /// available, which could even be zero. To wait for data to be available, /// use the `subscribe` function to obtain a `pollable` which can be polled /// for using `wasi:io/poll`. + @since(version = 0.2.0) resource input-stream { /// Perform a non-blocking read from the stream. /// @@ -56,6 +61,7 @@ interface streams { /// 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. + @since(version = 0.2.0) read: func( /// The maximum number of bytes to read len: u64 @@ -63,6 +69,7 @@ interface streams { /// Read bytes from a stream, after blocking until at least one byte can /// be read. Except for blocking, behavior is identical to `read`. + @since(version = 0.2.0) blocking-read: func( /// The maximum number of bytes to read len: u64 @@ -72,6 +79,7 @@ interface streams { /// /// Behaves identical to `read`, except instead of returning a list /// of bytes, returns the number of bytes consumed from the stream. + @since(version = 0.2.0) skip: func( /// The maximum number of bytes to skip. len: u64, @@ -79,6 +87,7 @@ interface streams { /// Skip bytes from a stream, after blocking until at least one byte /// can be skipped. Except for blocking behavior, identical to `skip`. + @since(version = 0.2.0) blocking-skip: func( /// The maximum number of bytes to skip. len: u64, @@ -90,6 +99,7 @@ interface streams { /// 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. + @since(version = 0.2.0) subscribe: func() -> pollable; } @@ -102,6 +112,11 @@ interface streams { /// promptly, which could even be zero. To wait for the stream to be ready to /// accept data, the `subscribe` function to obtain a `pollable` which can be /// polled for using `wasi:io/poll`. + /// + /// Dropping an `output-stream` while there's still an active write in + /// progress may result in the data being lost. Before dropping the stream, + /// be sure to fully flush your writes. + @since(version = 0.2.0) resource output-stream { /// Check readiness for writing. This function never blocks. /// @@ -112,6 +127,7 @@ interface streams { /// When this function returns 0 bytes, the `subscribe` pollable will /// become ready when this function will report at least 1 byte, or an /// error. + @since(version = 0.2.0) check-write: func() -> result; /// Perform a write. This function never blocks. @@ -127,6 +143,7 @@ interface streams { /// /// returns Err(closed) without writing if the stream has closed since /// the last call to check-write provided a permit. + @since(version = 0.2.0) write: func( contents: list ) -> result<_, stream-error>; @@ -155,6 +172,7 @@ interface streams { /// // Check for any errors that arose during `flush` /// let _ = this.check-write(); // eliding error handling /// ``` + @since(version = 0.2.0) blocking-write-and-flush: func( contents: list ) -> result<_, stream-error>; @@ -169,14 +187,16 @@ interface streams { /// 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. + @since(version = 0.2.0) flush: func() -> result<_, stream-error>; /// Request to flush buffered output, and block until flush completes /// and stream is ready for writing again. + @since(version = 0.2.0) blocking-flush: func() -> result<_, stream-error>; /// Create a `pollable` which will resolve once the output-stream - /// is ready for more writing, or an error has occured. When this + /// is ready for more writing, or an error has occurred. When this /// pollable is ready, `check-write` will return `ok(n)` with n>0, or an /// error. /// @@ -193,6 +213,7 @@ interface streams { /// 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. + @since(version = 0.2.0) write-zeroes: func( /// The number of zero-bytes to write len: u64 @@ -222,6 +243,7 @@ interface streams { /// // Check for any errors that arose during `flush` /// let _ = this.check-write(); // eliding error handling /// ``` + @since(version = 0.2.0) blocking-write-zeroes-and-flush: func( /// The number of zero-bytes to write len: u64 @@ -229,7 +251,7 @@ interface streams { /// Read from one stream and write to another. /// - /// The behavior of splice is equivelant to: + /// The behavior of splice is equivalent 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` @@ -240,6 +262,7 @@ interface streams { /// /// This function returns the number of bytes transferred; it may be less /// than `len`. + @since(version = 0.2.0) splice: func( /// The stream to read from src: borrow, @@ -252,6 +275,7 @@ interface streams { /// 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`. + @since(version = 0.2.0) blocking-splice: func( /// The stream to read from src: borrow, diff --git a/wit/deps/io/world.wit b/wit/deps/io/world.wit index 5f0b43f..f5c0987 100644 --- a/wit/deps/io/world.wit +++ b/wit/deps/io/world.wit @@ -1,6 +1,10 @@ package wasi:io@0.2.0; +@since(version = 0.2.0) world imports { + @since(version = 0.2.0) import streams; + + @since(version = 0.2.0) import poll; } diff --git a/wit/deps/random/insecure-seed.wit b/wit/deps/random/insecure-seed.wit index 47210ac..4cce628 100644 --- a/wit/deps/random/insecure-seed.wit +++ b/wit/deps/random/insecure-seed.wit @@ -3,6 +3,7 @@ package wasi:random@0.2.0; /// /// It is intended to be portable at least between Unix-family platforms and /// Windows. +@since(version = 0.2.0) interface insecure-seed { /// Return a 128-bit value that may contain a pseudo-random value. /// @@ -21,5 +22,6 @@ interface insecure-seed { /// 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. + @since(version = 0.2.0) insecure-seed: func() -> tuple; } diff --git a/wit/deps/random/insecure.wit b/wit/deps/random/insecure.wit index c58f4ee..3cea0c4 100644 --- a/wit/deps/random/insecure.wit +++ b/wit/deps/random/insecure.wit @@ -3,6 +3,7 @@ package wasi:random@0.2.0; /// /// It is intended to be portable at least between Unix-family platforms and /// Windows. +@since(version = 0.2.0) interface insecure { /// Return `len` insecure pseudo-random bytes. /// @@ -12,11 +13,13 @@ interface insecure { /// There are no requirements on the values of the returned bytes, however /// implementations are encouraged to return evenly distributed values with /// a long period. + @since(version = 0.2.0) get-insecure-random-bytes: func(len: u64) -> list; /// 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`. + @since(version = 0.2.0) get-insecure-random-u64: func() -> u64; } diff --git a/wit/deps/random/random.wit b/wit/deps/random/random.wit index 0c017f0..41c3a03 100644 --- a/wit/deps/random/random.wit +++ b/wit/deps/random/random.wit @@ -3,6 +3,7 @@ package wasi:random@0.2.0; /// /// It is intended to be portable at least between Unix-family platforms and /// Windows. +@since(version = 0.2.0) interface random { /// Return `len` cryptographically-secure random or pseudo-random bytes. /// @@ -16,11 +17,13 @@ interface random { /// This function must always return fresh data. Deterministic environments /// must omit this function, rather than implementing it with deterministic /// data. + @since(version = 0.2.0) get-random-bytes: func(len: u64) -> list; /// 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`. + @since(version = 0.2.0) get-random-u64: func() -> u64; } diff --git a/wit/deps/random/world.wit b/wit/deps/random/world.wit index 3da3491..b5560a6 100644 --- a/wit/deps/random/world.wit +++ b/wit/deps/random/world.wit @@ -1,7 +1,13 @@ package wasi:random@0.2.0; +@since(version = 0.2.0) world imports { + @since(version = 0.2.0) import random; + + @since(version = 0.2.0) import insecure; + + @since(version = 0.2.0) import insecure-seed; } diff --git a/wit/deps/sockets/instance-network.wit b/wit/deps/sockets/instance-network.wit index e455d0f..5f6e6c1 100644 --- a/wit/deps/sockets/instance-network.wit +++ b/wit/deps/sockets/instance-network.wit @@ -1,9 +1,11 @@ /// This interface provides a value-export of the default network handle.. +@since(version = 0.2.0) interface instance-network { + @since(version = 0.2.0) use network.{network}; /// Get a handle to the default network. + @since(version = 0.2.0) instance-network: func() -> network; - } diff --git a/wit/deps/sockets/ip-name-lookup.wit b/wit/deps/sockets/ip-name-lookup.wit index 8e639ec..0368b48 100644 --- a/wit/deps/sockets/ip-name-lookup.wit +++ b/wit/deps/sockets/ip-name-lookup.wit @@ -1,9 +1,10 @@ - +@since(version = 0.2.0) interface ip-name-lookup { + @since(version = 0.2.0) use wasi:io/poll@0.2.0.{pollable}; + @since(version = 0.2.0) use network.{network, error-code, ip-address}; - /// Resolve an internet host name to a list of IP addresses. /// /// Unicode domain names are automatically converted to ASCII using IDNA encoding. @@ -24,8 +25,10 @@ interface ip-name-lookup { /// - /// - /// - + @since(version = 0.2.0) resolve-addresses: func(network: borrow, name: string) -> result; + @since(version = 0.2.0) resource resolve-address-stream { /// Returns the next address from the resolver. /// @@ -40,12 +43,14 @@ interface ip-name-lookup { /// - `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) + @since(version = 0.2.0) resolve-next-address: func() -> result, error-code>; /// 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. + @since(version = 0.2.0) subscribe: func() -> pollable; } } diff --git a/wit/deps/sockets/network.wit b/wit/deps/sockets/network.wit index 9cadf06..8c13b34 100644 --- a/wit/deps/sockets/network.wit +++ b/wit/deps/sockets/network.wit @@ -1,8 +1,9 @@ - +@since(version = 0.2.0) interface network { /// 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. + @since(version = 0.2.0) resource network; /// Error codes. @@ -17,6 +18,7 @@ interface network { /// - `concurrency-conflict` /// /// See each individual API for what the POSIX equivalents are. They sometimes differ per API. + @since(version = 0.2.0) enum error-code { /// Unknown error unknown, @@ -103,6 +105,7 @@ interface network { permanent-resolver-failure, } + @since(version = 0.2.0) enum ip-address-family { /// Similar to `AF_INET` in POSIX. ipv4, @@ -111,14 +114,18 @@ interface network { ipv6, } + @since(version = 0.2.0) type ipv4-address = tuple; + @since(version = 0.2.0) type ipv6-address = tuple; + @since(version = 0.2.0) variant ip-address { ipv4(ipv4-address), ipv6(ipv6-address), } + @since(version = 0.2.0) record ipv4-socket-address { /// sin_port port: u16, @@ -126,6 +133,7 @@ interface network { address: ipv4-address, } + @since(version = 0.2.0) record ipv6-socket-address { /// sin6_port port: u16, @@ -137,9 +145,9 @@ interface network { scope-id: u32, } + @since(version = 0.2.0) variant ip-socket-address { ipv4(ipv4-socket-address), ipv6(ipv6-socket-address), } - } diff --git a/wit/deps/sockets/tcp-create-socket.wit b/wit/deps/sockets/tcp-create-socket.wit index c7ddf1f..eedbd30 100644 --- a/wit/deps/sockets/tcp-create-socket.wit +++ b/wit/deps/sockets/tcp-create-socket.wit @@ -1,6 +1,8 @@ - +@since(version = 0.2.0) interface tcp-create-socket { + @since(version = 0.2.0) use network.{network, error-code, ip-address-family}; + @since(version = 0.2.0) use tcp.{tcp-socket}; /// Create a new TCP socket. @@ -23,5 +25,6 @@ interface tcp-create-socket { /// - /// - /// - + @since(version = 0.2.0) create-tcp-socket: func(address-family: ip-address-family) -> result; } diff --git a/wit/deps/sockets/tcp.wit b/wit/deps/sockets/tcp.wit index 5902b9e..e4a6210 100644 --- a/wit/deps/sockets/tcp.wit +++ b/wit/deps/sockets/tcp.wit @@ -1,10 +1,15 @@ - +@since(version = 0.2.0) interface tcp { + @since(version = 0.2.0) use wasi:io/streams@0.2.0.{input-stream, output-stream}; + @since(version = 0.2.0) use wasi:io/poll@0.2.0.{pollable}; + @since(version = 0.2.0) use wasi:clocks/monotonic-clock@0.2.0.{duration}; + @since(version = 0.2.0) use network.{network, error-code, ip-socket-address, ip-address-family}; + @since(version = 0.2.0) enum shutdown-type { /// Similar to `SHUT_RD` in POSIX. receive, @@ -27,8 +32,8 @@ interface tcp { /// - `connect-in-progress` /// - `connected` /// - `closed` - /// See - /// for a more information. + /// See + /// for more information. /// /// Note: Except where explicitly mentioned, whenever this documentation uses /// the term "bound" without backticks it actually means: in the `bound` state *or higher*. @@ -37,6 +42,7 @@ interface tcp { /// In addition to the general error codes documented on the /// `network::error-code` type, TCP socket methods may always return /// `error(invalid-state)` when in the `closed` state. + @since(version = 0.2.0) resource tcp-socket { /// Bind the socket to a specific network on the provided IP address and port. /// @@ -76,13 +82,15 @@ interface tcp { /// - /// - /// - + @since(version = 0.2.0) start-bind: func(network: borrow, local-address: ip-socket-address) -> result<_, error-code>; + @since(version = 0.2.0) finish-bind: func() -> result<_, error-code>; /// Connect to a remote endpoint. /// /// On success: - /// - the socket is transitioned into the `connection` state. + /// - the socket is transitioned into the `connected` 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` @@ -121,7 +129,9 @@ interface tcp { /// - /// - /// - + @since(version = 0.2.0) start-connect: func(network: borrow, remote-address: ip-socket-address) -> result<_, error-code>; + @since(version = 0.2.0) finish-connect: func() -> result, error-code>; /// Start listening for new connections. @@ -149,7 +159,9 @@ interface tcp { /// - /// - /// - + @since(version = 0.2.0) start-listen: func() -> result<_, error-code>; + @since(version = 0.2.0) finish-listen: func() -> result<_, error-code>; /// Accept a new client socket. @@ -178,6 +190,7 @@ interface tcp { /// - /// - /// - + @since(version = 0.2.0) accept: func() -> result, error-code>; /// Get the bound local address. @@ -196,6 +209,7 @@ interface tcp { /// - /// - /// - + @since(version = 0.2.0) local-address: func() -> result; /// Get the remote address. @@ -208,16 +222,19 @@ interface tcp { /// - /// - /// - + @since(version = 0.2.0) remote-address: func() -> result; /// Whether the socket is in the `listening` state. /// /// Equivalent to the SO_ACCEPTCONN socket option. + @since(version = 0.2.0) is-listening: func() -> bool; /// Whether this is a IPv4 or IPv6 socket. /// /// Equivalent to the SO_DOMAIN socket option. + @since(version = 0.2.0) address-family: func() -> ip-address-family; /// Hints the desired listen queue size. Implementations are free to ignore this. @@ -229,6 +246,7 @@ interface tcp { /// - `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. + @since(version = 0.2.0) set-listen-backlog-size: func(value: u64) -> result<_, error-code>; /// Enables or disables keepalive. @@ -240,7 +258,9 @@ interface tcp { /// 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. + @since(version = 0.2.0) keep-alive-enabled: func() -> result; + @since(version = 0.2.0) set-keep-alive-enabled: func(value: bool) -> result<_, error-code>; /// Amount of time the connection has to be idle before TCP starts sending keepalive packets. @@ -253,7 +273,9 @@ interface tcp { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. + @since(version = 0.2.0) keep-alive-idle-time: func() -> result; + @since(version = 0.2.0) set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>; /// The time between keepalive packets. @@ -266,7 +288,9 @@ interface tcp { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. + @since(version = 0.2.0) keep-alive-interval: func() -> result; + @since(version = 0.2.0) set-keep-alive-interval: func(value: duration) -> result<_, error-code>; /// The maximum amount of keepalive packets TCP should send before aborting the connection. @@ -279,7 +303,9 @@ interface tcp { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. + @since(version = 0.2.0) keep-alive-count: func() -> result; + @since(version = 0.2.0) set-keep-alive-count: func(value: u32) -> result<_, error-code>; /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options. @@ -288,7 +314,9 @@ interface tcp { /// /// # Typical errors /// - `invalid-argument`: (set) The TTL value must be 1 or higher. + @since(version = 0.2.0) hop-limit: func() -> result; + @since(version = 0.2.0) set-hop-limit: func(value: u8) -> result<_, error-code>; /// The kernel buffer space reserved for sends/receives on this socket. @@ -301,9 +329,13 @@ interface tcp { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. + @since(version = 0.2.0) receive-buffer-size: func() -> result; + @since(version = 0.2.0) set-receive-buffer-size: func(value: u64) -> result<_, error-code>; + @since(version = 0.2.0) send-buffer-size: func() -> result; + @since(version = 0.2.0) set-send-buffer-size: func(value: u64) -> result<_, error-code>; /// Create a `pollable` which can be used to poll for, or block on, @@ -318,11 +350,12 @@ interface tcp { /// `subscribe` only has to be called once per socket and can then be /// (re)used for the remainder of the socket's lifetime. /// - /// See - /// for a more information. + /// See + /// for more information. /// /// Note: this function is here for WASI Preview2 only. /// It's planned to be removed when `future` is natively supported in Preview3. + @since(version = 0.2.0) subscribe: func() -> pollable; /// Initiate a graceful shutdown. @@ -335,7 +368,7 @@ interface tcp { /// 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 + /// This function is idempotent; shutting down a direction more than once /// has no effect and returns `ok`. /// /// The shutdown function does not close (drop) the socket. @@ -348,6 +381,7 @@ interface tcp { /// - /// - /// - + @since(version = 0.2.0) shutdown: func(shutdown-type: shutdown-type) -> result<_, error-code>; } } diff --git a/wit/deps/sockets/udp-create-socket.wit b/wit/deps/sockets/udp-create-socket.wit index 0482d1f..e8eeacb 100644 --- a/wit/deps/sockets/udp-create-socket.wit +++ b/wit/deps/sockets/udp-create-socket.wit @@ -1,6 +1,8 @@ - +@since(version = 0.2.0) interface udp-create-socket { + @since(version = 0.2.0) use network.{network, error-code, ip-address-family}; + @since(version = 0.2.0) use udp.{udp-socket}; /// Create a new UDP socket. @@ -23,5 +25,6 @@ interface udp-create-socket { /// - /// - /// - + @since(version = 0.2.0) create-udp-socket: func(address-family: ip-address-family) -> result; } diff --git a/wit/deps/sockets/udp.wit b/wit/deps/sockets/udp.wit index d987a0a..48e753c 100644 --- a/wit/deps/sockets/udp.wit +++ b/wit/deps/sockets/udp.wit @@ -1,9 +1,12 @@ - +@since(version = 0.2.0) interface udp { + @since(version = 0.2.0) use wasi:io/poll@0.2.0.{pollable}; + @since(version = 0.2.0) use network.{network, error-code, ip-socket-address, ip-address-family}; /// A received datagram. + @since(version = 0.2.0) record incoming-datagram { /// The payload. /// @@ -19,6 +22,7 @@ interface udp { } /// A datagram to be sent out. + @since(version = 0.2.0) record outgoing-datagram { /// The payload. data: list, @@ -33,9 +37,8 @@ interface udp { remote-address: option, } - - /// A UDP socket handle. + @since(version = 0.2.0) resource udp-socket { /// Bind the socket to a specific network on the provided IP address and port. /// @@ -63,7 +66,9 @@ interface udp { /// - /// - /// - + @since(version = 0.2.0) start-bind: func(network: borrow, local-address: ip-socket-address) -> result<_, error-code>; + @since(version = 0.2.0) finish-bind: func() -> result<_, error-code>; /// Set up inbound & outbound communication channels, optionally to a specific peer. @@ -106,6 +111,7 @@ interface udp { /// - /// - /// - + @since(version = 0.2.0) %stream: func(remote-address: option) -> result, error-code>; /// Get the current bound address. @@ -124,6 +130,7 @@ interface udp { /// - /// - /// - + @since(version = 0.2.0) local-address: func() -> result; /// Get the address the socket is currently streaming to. @@ -136,11 +143,13 @@ interface udp { /// - /// - /// - + @since(version = 0.2.0) remote-address: func() -> result; /// Whether this is a IPv4 or IPv6 socket. /// /// Equivalent to the SO_DOMAIN socket option. + @since(version = 0.2.0) address-family: func() -> ip-address-family; /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options. @@ -149,7 +158,9 @@ interface udp { /// /// # Typical errors /// - `invalid-argument`: (set) The TTL value must be 1 or higher. + @since(version = 0.2.0) unicast-hop-limit: func() -> result; + @since(version = 0.2.0) set-unicast-hop-limit: func(value: u8) -> result<_, error-code>; /// The kernel buffer space reserved for sends/receives on this socket. @@ -162,18 +173,24 @@ interface udp { /// /// # Typical errors /// - `invalid-argument`: (set) The provided value was 0. + @since(version = 0.2.0) receive-buffer-size: func() -> result; + @since(version = 0.2.0) set-receive-buffer-size: func(value: u64) -> result<_, error-code>; + @since(version = 0.2.0) send-buffer-size: func() -> result; + @since(version = 0.2.0) set-send-buffer-size: func(value: u64) -> result<_, error-code>; /// 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. + @since(version = 0.2.0) subscribe: func() -> pollable; } + @since(version = 0.2.0) resource incoming-datagram-stream { /// Receive messages on the socket. /// @@ -198,15 +215,18 @@ interface udp { /// - /// - /// - + @since(version = 0.2.0) receive: func(max-results: u64) -> result, error-code>; /// 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. + @since(version = 0.2.0) subscribe: func() -> pollable; } + @since(version = 0.2.0) resource outgoing-datagram-stream { /// Check readiness for sending. This function never blocks. /// @@ -255,12 +275,14 @@ interface udp { /// - /// - /// - + @since(version = 0.2.0) send: func(datagrams: list) -> result; /// 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. + @since(version = 0.2.0) subscribe: func() -> pollable; } } diff --git a/wit/deps/sockets/world.wit b/wit/deps/sockets/world.wit index f8bb92a..a1f7d14 100644 --- a/wit/deps/sockets/world.wit +++ b/wit/deps/sockets/world.wit @@ -1,11 +1,19 @@ package wasi:sockets@0.2.0; +@since(version = 0.2.0) world imports { + @since(version = 0.2.0) import instance-network; + @since(version = 0.2.0) import network; + @since(version = 0.2.0) import udp; + @since(version = 0.2.0) import udp-create-socket; + @since(version = 0.2.0) import tcp; + @since(version = 0.2.0) import tcp-create-socket; + @since(version = 0.2.0) import ip-name-lookup; } diff --git a/wit/handler.wit b/wit/handler.wit index a34a064..6a6c629 100644 --- a/wit/handler.wit +++ b/wit/handler.wit @@ -1,6 +1,8 @@ /// This interface defines a handler of incoming HTTP Requests. It should /// be exported by components which can respond to HTTP Requests. +@since(version = 0.2.0) interface incoming-handler { + @since(version = 0.2.0) use types.{incoming-request, response-outparam}; /// This function is invoked with an incoming HTTP Request, and a resource @@ -13,6 +15,7 @@ interface incoming-handler { /// The implementor of this function must write a response to the /// `response-outparam` before returning, or else the caller will respond /// with an error on its behalf. + @since(version = 0.2.0) handle: func( request: incoming-request, response-out: response-outparam @@ -21,7 +24,9 @@ interface incoming-handler { /// This interface defines a handler of outgoing HTTP Requests. It should be /// imported by components which wish to make HTTP Requests. +@since(version = 0.2.0) interface outgoing-handler { + @since(version = 0.2.0) use types.{ outgoing-request, request-options, future-incoming-response, error-code }; @@ -36,6 +41,7 @@ interface outgoing-handler { /// This function may return an error if the `outgoing-request` is invalid /// or not allowed to be made. Otherwise, protocol errors are reported /// through the `future-incoming-response`. + @since(version = 0.2.0) handle: func( request: outgoing-request, options: option diff --git a/wit/proxy.wit b/wit/proxy.wit index 26a975e..e8966b0 100644 --- a/wit/proxy.wit +++ b/wit/proxy.wit @@ -2,24 +2,31 @@ package wasi:http@0.2.0; /// The `wasi:http/imports` world imports all the APIs for HTTP proxies. /// It is intended to be `include`d in other worlds. +@since(version = 0.2.0) world imports { /// HTTP proxies have access to time and randomness. + @since(version = 0.2.0) include wasi:clocks/imports@0.2.0; + @since(version = 0.2.0) import wasi:random/random@0.2.0; /// Proxies have standard output and error streams which are expected to /// terminate in a developer-facing console provided by the host. + @since(version = 0.2.0) import wasi:cli/stdout@0.2.0; + @since(version = 0.2.0) import wasi:cli/stderr@0.2.0; /// TODO: this is a temporary workaround until component tooling is able to /// gracefully handle the absence of stdin. Hosts must return an eof stream /// for this import, which is what wasi-libc + tooling will do automatically /// when this import is properly removed. + @since(version = 0.2.0) import wasi:cli/stdin@0.2.0; /// This is the default handler to use when user code simply wants to make an /// HTTP request (e.g., via `fetch()`). + @since(version = 0.2.0) import outgoing-handler; } @@ -27,12 +34,15 @@ world imports { /// hosts that includes HTTP forward and reverse proxies. Components targeting /// this world may concurrently stream in and out any number of incoming and /// outgoing HTTP requests. +@since(version = 0.2.0) world proxy { + @since(version = 0.2.0) include imports; /// The host delivers incoming HTTP requests to a component by calling the /// `handle` function of this exported interface. A host may arbitrarily reuse /// or not reuse component instance when delivering incoming HTTP requests and /// thus a component must be able to handle 0..N calls to `handle`. + @since(version = 0.2.0) export incoming-handler; } diff --git a/wit/types.wit b/wit/types.wit index 0ead178..981c110 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -1,13 +1,19 @@ /// This interface defines all of the types and methods for implementing /// HTTP Requests and Responses, both incoming and outgoing, as well as /// their headers, trailers, and bodies. +@since(version = 0.2.0) interface types { + @since(version = 0.2.0) use wasi:clocks/monotonic-clock@0.2.0.{duration}; + @since(version = 0.2.0) use wasi:io/streams@0.2.0.{input-stream, output-stream}; + @since(version = 0.2.0) use wasi:io/error@0.2.0.{error as io-error}; + @since(version = 0.2.0) use wasi:io/poll@0.2.0.{pollable}; /// This type corresponds to HTTP standard Methods. + @since(version = 0.2.0) variant method { get, head, @@ -22,6 +28,7 @@ interface types { } /// This type corresponds to HTTP standard Related Schemes. + @since(version = 0.2.0) variant scheme { HTTP, HTTPS, @@ -30,6 +37,7 @@ interface types { /// These cases are inspired by the IANA HTTP Proxy Error Types: /// https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types + @since(version = 0.2.0) variant error-code { DNS-timeout, DNS-error(DNS-error-payload), @@ -78,18 +86,21 @@ interface types { } /// Defines the case payload type for `DNS-error` above: + @since(version = 0.2.0) record DNS-error-payload { rcode: option, info-code: option } /// Defines the case payload type for `TLS-alert-received` above: + @since(version = 0.2.0) record TLS-alert-received-payload { alert-id: option, alert-message: option } /// Defines the case payload type for `HTTP-response-{header,trailer}-size` above: + @since(version = 0.2.0) record field-size-payload { field-name: option, field-size: option @@ -106,10 +117,12 @@ interface types { /// /// Note that this function is fallible because not all io-errors are /// http-related errors. + @since(version = 0.2.0) http-error-code: func(err: borrow) -> option; /// This type enumerates the different kinds of errors that may occur when /// setting or appending to a `fields` resource. + @since(version = 0.2.0) variant header-error { /// This error indicates that a `field-key` or `field-value` was /// syntactically invalid when used with an operation that sets headers in a @@ -126,11 +139,13 @@ interface types { } /// Field keys are always strings. + @since(version = 0.2.0) type field-key = string; /// Field values should always be ASCII strings. However, in /// reality, HTTP implementations often have to interpret malformed values, /// so they are provided as a list of bytes. + @since(version = 0.2.0) type field-value = list; /// This following block defines the `fields` resource which corresponds to @@ -143,11 +158,13 @@ interface types { /// `incoming-request.headers`, `outgoing-request.headers`) might be be /// immutable. In an immutable fields, the `set`, `append`, and `delete` /// operations will fail with `header-error.immutable`. + @since(version = 0.2.0) resource fields { /// Construct an empty HTTP Fields. /// /// The resulting `fields` is mutable. + @since(version = 0.2.0) constructor(); /// Construct an HTTP Fields. @@ -163,6 +180,7 @@ interface types { /// /// An error result will be returned if any `field-key` or `field-value` is /// syntactically invalid, or if a field is forbidden. + @since(version = 0.2.0) from-list: static func( entries: list> ) -> result; @@ -171,10 +189,12 @@ interface types { /// in this `fields` or is syntactically invalid, 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. + @since(version = 0.2.0) get: func(name: field-key) -> list; /// Returns `true` when the key is present in this `fields`. If the key is /// syntactically invalid, `false` is returned. + @since(version = 0.2.0) has: func(name: field-key) -> bool; /// Set all of the values for a key. Clears any existing values for that @@ -184,6 +204,7 @@ interface types { /// /// Fails with `header-error.invalid-syntax` if the `field-key` or any of /// the `field-value`s are syntactically invalid. + @since(version = 0.2.0) set: func(name: field-key, value: list) -> result<_, header-error>; /// Delete all values for a key. Does nothing if no values for the key @@ -193,6 +214,7 @@ interface types { /// /// Fails with `header-error.invalid-syntax` if the `field-key` is /// syntactically invalid. + @since(version = 0.2.0) delete: func(name: field-key) -> result<_, header-error>; /// Append a value for a key. Does not change or delete any existing @@ -202,6 +224,7 @@ interface types { /// /// Fails with `header-error.invalid-syntax` if the `field-key` or /// `field-value` are syntactically invalid. + @since(version = 0.2.0) append: func(name: field-key, value: field-value) -> result<_, header-error>; /// Retrieve the full set of keys and values in the Fields. Like the @@ -210,33 +233,42 @@ interface types { /// 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. + @since(version = 0.2.0) entries: func() -> list>; /// Make a deep copy of the Fields. Equivalent in behavior to calling the /// `fields` constructor on the return value of `entries`. The resulting /// `fields` is mutable. + @since(version = 0.2.0) clone: func() -> fields; } /// Headers is an alias for Fields. + @since(version = 0.2.0) type headers = fields; /// Trailers is an alias for Fields. + @since(version = 0.2.0) type trailers = fields; /// Represents an incoming HTTP Request. + @since(version = 0.2.0) resource incoming-request { /// Returns the method of the incoming request. + @since(version = 0.2.0) method: func() -> method; /// Returns the path with query parameters from the request, as a string. + @since(version = 0.2.0) path-with-query: func() -> option; /// Returns the protocol scheme from the request. + @since(version = 0.2.0) scheme: func() -> option; /// Returns the authority from the request, if it was present. + @since(version = 0.2.0) authority: func() -> option; /// Get the `headers` associated with the request. @@ -247,14 +279,17 @@ interface types { /// 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. + @since(version = 0.2.0) headers: func() -> headers; /// Gives the `incoming-body` associated with this request. Will only /// return success at most once, and subsequent calls will return error. + @since(version = 0.2.0) consume: func() -> result; } /// Represents an outgoing HTTP Request. + @since(version = 0.2.0) resource outgoing-request { /// Construct a new `outgoing-request` with a default `method` of `GET`, and @@ -267,6 +302,7 @@ interface types { /// 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`. + @since(version = 0.2.0) constructor( headers: headers ); @@ -277,38 +313,47 @@ interface types { /// 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. + @since(version = 0.2.0) body: func() -> result; /// Get the Method for the Request. + @since(version = 0.2.0) method: func() -> method; /// Set the Method for the Request. Fails if the string present in a /// `method.other` argument is not a syntactically valid method. + @since(version = 0.2.0) set-method: func(method: method) -> result; /// Get the combination of the HTTP Path and Query for the Request. /// When `none`, this represents an empty Path and empty Query. + @since(version = 0.2.0) path-with-query: func() -> option; /// 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. + @since(version = 0.2.0) set-path-with-query: func(path-with-query: option) -> result; /// Get the HTTP Related Scheme for the Request. When `none`, the /// implementation may choose an appropriate default scheme. + @since(version = 0.2.0) scheme: func() -> option; /// 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. + @since(version = 0.2.0) set-scheme: func(scheme: option) -> result; /// 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. + @since(version = 0.2.0) authority: func() -> option; /// 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. + @since(version = 0.2.0) set-authority: func(authority: option) -> result; /// Get the headers associated with the Request. @@ -319,6 +364,7 @@ interface types { /// This headers resource is a child: it must be dropped before the parent /// `outgoing-request` is dropped, or its ownership is transferred to /// another component by e.g. `outgoing-handler.handle`. + @since(version = 0.2.0) headers: func() -> headers; } @@ -328,31 +374,39 @@ interface types { /// /// These timeouts are separate from any the user may use to bound a /// blocking call to `wasi:io/poll.poll`. + @since(version = 0.2.0) resource request-options { /// Construct a default `request-options` value. + @since(version = 0.2.0) constructor(); /// The timeout for the initial connect to the HTTP Server. + @since(version = 0.2.0) connect-timeout: func() -> option; /// Set the timeout for the initial connect to the HTTP Server. An error /// return value indicates that this timeout is not supported. + @since(version = 0.2.0) set-connect-timeout: func(duration: option) -> result; /// The timeout for receiving the first byte of the Response body. + @since(version = 0.2.0) first-byte-timeout: func() -> option; /// Set the timeout for receiving the first byte of the Response body. An /// error return value indicates that this timeout is not supported. + @since(version = 0.2.0) set-first-byte-timeout: func(duration: option) -> result; /// The timeout for receiving subsequent chunks of bytes in the Response /// body stream. + @since(version = 0.2.0) between-bytes-timeout: func() -> option; /// 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. + @since(version = 0.2.0) set-between-bytes-timeout: func(duration: option) -> result; } @@ -361,6 +415,7 @@ interface types { /// This resource is used by the `wasi:http/incoming-handler` interface to /// allow a Response to be sent corresponding to the Request provided as the /// other argument to `incoming-handler.handle`. + @since(version = 0.2.0) resource response-outparam { /// Set the value of the `response-outparam` to either send a response, @@ -372,6 +427,7 @@ interface types { /// /// The user may provide an `error` to `response` to allow the /// implementation determine how to respond with an HTTP error response. + @since(version = 0.2.0) set: static func( param: response-outparam, response: result, @@ -379,12 +435,15 @@ interface types { } /// This type corresponds to the HTTP standard Status Code. + @since(version = 0.2.0) type status-code = u16; /// Represents an incoming HTTP Response. + @since(version = 0.2.0) resource incoming-response { /// Returns the status code from the incoming response. + @since(version = 0.2.0) status: func() -> status-code; /// Returns the headers from the incoming response. @@ -394,10 +453,12 @@ interface types { /// /// This headers resource is a child: it must be dropped before the parent /// `incoming-response` is dropped. + @since(version = 0.2.0) headers: func() -> headers; /// Returns the incoming body. May be called at most once. Returns error /// if called additional times. + @since(version = 0.2.0) consume: func() -> result; } @@ -409,6 +470,7 @@ interface types { /// an `input-stream` and the delivery of trailers as a `future-trailers`, /// and ensures that the user of this interface may only be consuming either /// the body contents or waiting on trailers at any given time. + @since(version = 0.2.0) resource incoming-body { /// Returns the contents of the body, as a stream of bytes. @@ -426,10 +488,12 @@ interface types { /// 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. + @since(version = 0.2.0) %stream: func() -> result; /// Takes ownership of `incoming-body`, and returns a `future-trailers`. /// This function will trap if the `input-stream` child is still alive. + @since(version = 0.2.0) finish: static func(this: incoming-body) -> future-trailers; } @@ -438,11 +502,13 @@ interface types { /// In the case that the incoming HTTP Request or Response did not have any /// trailers, this future will resolve to the empty set of trailers once the /// complete Request or Response body has been received. + @since(version = 0.2.0) resource future-trailers { /// Returns a pollable which becomes ready when either the trailers have /// been received, or an error has occurred. When this pollable is ready, /// the `get` method will return `some`. + @since(version = 0.2.0) subscribe: func() -> pollable; /// Returns the contents of the trailers, or an error which occurred, @@ -464,10 +530,12 @@ interface types { /// 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. + @since(version = 0.2.0) get: func() -> option, error-code>>>; } /// Represents an outgoing HTTP Response. + @since(version = 0.2.0) resource outgoing-response { /// Construct an `outgoing-response`, with a default `status-code` of `200`. @@ -475,13 +543,16 @@ interface types { /// `set-status-code` method. /// /// * `headers` is the HTTP Headers for the Response. + @since(version = 0.2.0) constructor(headers: headers); /// Get the HTTP Status Code for the Response. + @since(version = 0.2.0) status-code: func() -> status-code; /// Set the HTTP Status Code for the Response. Fails if the status-code /// given is not a valid http status code. + @since(version = 0.2.0) set-status-code: func(status-code: status-code) -> result; /// Get the headers associated with the Request. @@ -492,6 +563,7 @@ interface types { /// This headers resource is a child: it must be dropped before the parent /// `outgoing-request` is dropped, or its ownership is transferred to /// another component by e.g. `outgoing-handler.handle`. + @since(version = 0.2.0) headers: func() -> headers; /// Returns the resource corresponding to the outgoing Body for this Response. @@ -499,6 +571,7 @@ interface types { /// 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. + @since(version = 0.2.0) body: func() -> result; } @@ -518,6 +591,7 @@ interface types { /// error to the HTTP protocol by whatever means it has available, /// including: corrupting the body on the wire, aborting the associated /// Request, or sending a late status code for the Response. + @since(version = 0.2.0) resource outgoing-body { /// Returns a stream for writing the body contents. @@ -529,6 +603,7 @@ interface types { /// 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. + @since(version = 0.2.0) write: func() -> result; /// Finalize an outgoing body, optionally providing trailers. This must be @@ -540,6 +615,7 @@ interface types { /// 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. + @since(version = 0.2.0) finish: static func( this: outgoing-body, trailers: option @@ -551,10 +627,12 @@ interface types { /// /// This resource is returned by the `wasi:http/outgoing-handler` interface to /// provide the HTTP Response corresponding to the sent Request. + @since(version = 0.2.0) resource future-incoming-response { /// Returns a pollable which becomes ready when either the Response has /// been received, or an error has occurred. When this pollable is ready, /// the `get` method will return `some`. + @since(version = 0.2.0) subscribe: func() -> pollable; /// Returns the incoming HTTP Response, or an error, once one is ready. @@ -571,7 +649,7 @@ interface types { /// occurred. Errors may also occur while consuming the response body, /// but those will be reported by the `incoming-body` and its /// `output-stream` child. + @since(version = 0.2.0) get: func() -> option>>; - } }