Merge pull request #114 from yoshuawuyts/since-gates

Document per-item versions using `@since` gates

.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'
+        wit-bindgen: '0.26.0'
+        worlds: 'imports proxy'

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"

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;
 }

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<tuple<string, string>>;
 
   /// Get the POSIX-style arguments to the program.
+  @since(version = 0.2.0)
   get-arguments: func() -> list<string>;
 
   /// 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<string>;
 }

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);
 }

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;
 }

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;
 }

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;
 }

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<terminal-input>;
 }
 
 /// 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<terminal-output>;
 }
 
 /// 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<terminal-output>;
 }

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;

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,
+    }
+}

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;
 }

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;
 }

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<tuple<descriptor, string>>;
 }