Merge pull request #102 from yoshuawuyts/since-gates

Document per-item versions using `@since` gates

Author: badeend

.github/workflows/main.yml

@@ -18,4 +18,4 @@ jobs:
         ./wit-deps lock
         git add -N wit/deps
         git diff --exit-code
-    - uses: WebAssembly/wit-abi-up-to-date@v17
+    - uses: WebAssembly/wit-abi-up-to-date@v21

imports.md

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

wit/instance-network.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 {
     /// - <https://man7.org/linux/man-pages/man3/getaddrinfo.3.html>
     /// - <https://learn.microsoft.com/en-us/windows/win32/api/ws2tcpip/nf-ws2tcpip-getaddrinfo>
     /// - <https://man.freebsd.org/cgi/man.cgi?query=getaddrinfo&sektion=3>
+    @since(version = 0.2.0)
     resolve-addresses: func(network: borrow<network>, name: string) -> result<resolve-address-stream, error-code>;
 
+    @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<option<ip-address>, 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;
     }
 }

wit/ip-name-lookup.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,
@@ -61,6 +63,7 @@ interface network {
         /// Note: this is scheduled to be removed when `future`s are natively supported.
         would-block,
 
+
         /// The operation is not valid in the socket's current state.
         invalid-state,
 
@@ -76,6 +79,7 @@ interface network {
         /// The remote address is not reachable
         remote-unreachable,
 
+
         /// The TCP connection was forcefully rejected
         connection-refused,
 
@@ -85,10 +89,12 @@ interface network {
         /// A TCP connection was aborted.
         connection-aborted,
 
+
         /// The size of a datagram sent to a UDP socket exceeded the maximum
         /// supported size.
         datagram-too-large,
 
+
         /// Name does not exist or has no suitable associated IP addresses.
         name-unresolvable,
 
@@ -99,6 +105,7 @@ interface network {
         permanent-resolver-failure,
     }
 
+    @since(version = 0.2.0)
     enum ip-address-family {
         /// Similar to `AF_INET` in POSIX.
         ipv4,
@@ -107,21 +114,26 @@ interface network {
         ipv6,
     }
 
+    @since(version = 0.2.0)
     type ipv4-address = tuple<u8, u8, u8, u8>;
+    @since(version = 0.2.0)
     type ipv6-address = tuple<u16, u16, u16, u16, u16, u16, u16, u16>;
 
+    @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,
         /// sin_addr
         address: ipv4-address,
     }
 
+    @since(version = 0.2.0)
     record ipv6-socket-address {
         /// sin6_port
         port: u16,
@@ -133,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),
     }
-
 }

wit/network.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 {
     /// - <https://man7.org/linux/man-pages/man2/socket.2.html>
     /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
     /// - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
+    @since(version = 0.2.0)
     create-tcp-socket: func(address-family: ip-address-family) -> result<tcp-socket, error-code>;
 }

wit/tcp-create-socket.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,
@@ -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,7 +82,9 @@ interface tcp {
         /// - <https://man7.org/linux/man-pages/man2/bind.2.html>
         /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
         /// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
+        @since(version = 0.2.0)
         start-bind: func(network: borrow<network>, local-address: ip-socket-address) -> result<_, error-code>;
+        @since(version = 0.2.0)
         finish-bind: func() -> result<_, error-code>;
 
         /// Connect to a remote endpoint.
@@ -121,7 +129,9 @@ interface tcp {
         /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
         /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
         /// - <https://man.freebsd.org/cgi/man.cgi?connect>
+        @since(version = 0.2.0)
         start-connect: func(network: borrow<network>, remote-address: ip-socket-address) -> result<_, error-code>;
+        @since(version = 0.2.0)
         finish-connect: func() -> result<tuple<input-stream, output-stream>, error-code>;
 
         /// Start listening for new connections.
@@ -149,7 +159,9 @@ interface tcp {
         /// - <https://man7.org/linux/man-pages/man2/listen.2.html>
         /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen>
         /// - <https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2>
+        @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 {
         /// - <https://man7.org/linux/man-pages/man2/accept.2.html>
         /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept>
         /// - <https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2>
+        @since(version = 0.2.0)
         accept: func() -> result<tuple<tcp-socket, input-stream, output-stream>, error-code>;
 
         /// Get the bound local address.
@@ -196,6 +209,7 @@ interface tcp {
         /// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
         /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
         /// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
+        @since(version = 0.2.0)
         local-address: func() -> result<ip-socket-address, error-code>;
 
         /// Get the remote address.
@@ -208,16 +222,19 @@ interface tcp {
         /// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
         /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
         /// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
+        @since(version = 0.2.0)
         remote-address: func() -> result<ip-socket-address, error-code>;
 
         /// 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<bool, error-code>;
+        @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<duration, error-code>;
+        @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<duration, error-code>;
+        @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<u32, error-code>;
+        @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<u8, error-code>;
+        @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<u64, error-code>;
+        @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<u64, error-code>;
+        @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,
@@ -323,6 +355,7 @@ interface tcp {
         ///
         /// 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.
@@ -348,6 +381,7 @@ interface tcp {
         /// - <https://man7.org/linux/man-pages/man2/shutdown.2.html>
         /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown>
         /// - <https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2>
+        @since(version = 0.2.0)
         shutdown: func(shutdown-type: shutdown-type) -> result<_, error-code>;
     }
 }

wit/tcp.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 {
     /// - <https://man7.org/linux/man-pages/man2/socket.2.html>
     /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasocketw>
     /// - <https://man.freebsd.org/cgi/man.cgi?query=socket&sektion=2>
+    @since(version = 0.2.0)
     create-udp-socket: func(address-family: ip-address-family) -> result<udp-socket, error-code>;
 }