From e01ac854a0a1756576d12f67f222f5a56fd9b77a Mon Sep 17 00:00:00 2001 From: Eduardo de Moura Rodrigues <16357187+eduardomourar@users.noreply.github.com> Date: Sat, 5 Aug 2023 17:38:21 +0100 Subject: [PATCH] fix: update wit dependencies to latest (#47) * fix: update wit dependencies to latest * chore: update proxy world markdown --------- Co-authored-by: Eduardo Rodrigues --- proxy.md | 86 ++++++++++++++++---------- wit/deps.lock | 24 ++++---- wit/deps/cli/exit.wit | 2 +- wit/deps/filesystem/preopens.wit | 6 ++ wit/deps/filesystem/types.wit | 100 ++++++++++++++++++++++--------- wit/deps/filesystem/world.wit | 1 + wit/deps/io/streams.wit | 37 ++++++++---- wit/deps/poll/poll.wit | 24 +++++--- wit/deps/random/random.wit | 24 ++++---- wit/deps/sockets/udp.wit | 25 +++++--- 10 files changed, 221 insertions(+), 108 deletions(-) create mode 100644 wit/deps/filesystem/preopens.wit diff --git a/proxy.md b/proxy.md index c273342..e0d0288 100644 --- a/proxy.md +++ b/proxy.md @@ -90,24 +90,31 @@ be used.

poll-oneoff: func

Poll for completion on a set of pollables.

+

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

+

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

+

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

+

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

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

-

Note that the return type would ideally be list<bool>, but that would -be more difficult to polyfill given the current state of wit-bindgen. -See https://github.com/bytecodealliance/preview2-prototyping/pull/11#issuecomment-1329873061 -for details. For now, we use zero to mean "not ready" and non-zero to -mean "ready".

Params
Return values

Import interface wasi:clocks/monotonic-clock

WASI Monotonic Clock is a clock API intended to let users measure elapsed @@ -241,14 +248,16 @@ Windows.

Functions

get-random-bytes: func

-

Return len cryptographically-secure pseudo-random bytes.

-

This function must produce data from an adequately seeded -cryptographically-secure pseudo-random number generator (CSPRNG), so it -must not block, from the perspective of the calling program, and the -returned data is always unpredictable.

-

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

+

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

+

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

+

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

Params

get-random-u64: func

-

Return a cryptographically-secure pseudo-random u64 value.

-

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

+

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

+

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

Return values
Return values

blocking-read: func

Read bytes from a stream, with blocking.

@@ -346,7 +372,7 @@ byte can be read.

Return values

skip: func

Skip bytes from a stream.

@@ -355,9 +381,9 @@ bytes into the instance.

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

-

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

+

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

Params
Return values

blocking-skip: func

Skip bytes from a stream, with blocking.

@@ -378,7 +404,7 @@ byte can be consumed.

Return values

subscribe-to-input-stream: func

Create a pollable which will resolve once either the specified stream @@ -465,7 +491,7 @@ read from the input stream has been written to the output stream.

Return values

blocking-splice: func

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

@@ -479,7 +505,7 @@ one byte can be read.

Return values

forward: func

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

diff --git a/wit/deps.lock b/wit/deps.lock index 13b4b24..5cf8421 100644 --- a/wit/deps.lock +++ b/wit/deps.lock @@ -1,7 +1,7 @@ [cli] url = "https://github.com/WebAssembly/wasi-cli/archive/main.tar.gz" -sha256 = "ce53bedad0aa34bbcde6ffd8f98348e03fa170e191aaf6bb6ca57b4915ade435" -sha512 = "489ed4e04603df4763e75d4d2d056cf363922c4865052348993febfd2c9bd10ab864fb4b72090df58dcb60d5676148a7a1e7de3a8513073afd37b4d9027ca7e7" +sha256 = "f21b7722b9225b7ff4f040a67daacd4e412fe2c53c982568a2c25b97fc85d2a2" +sha512 = "ceec4b906f94ba53731dd9428e7e62b964de2284d6aa7cb3436cb856ca89405b0ca8b02e8a8d4575204b9e72dac0e3b29690221ca438324b89e0084117f1700f" [clocks] url = "https://github.com/WebAssembly/wasi-clocks/archive/main.tar.gz" @@ -10,25 +10,25 @@ sha512 = "ef1e23704a8a8436fd3718593d4c4d8b6d1c64dad3595b7496c0888ca14b725046f290 [filesystem] url = "https://github.com/WebAssembly/wasi-filesystem/archive/main.tar.gz" -sha256 = "a19dbd57208ef649980bb4088b96606fe3549e580574dc88dafed6f8a8537b01" -sha512 = "49a798126feeb1a714162a20d282e554c70d36cbfa827dfb54685577b13d584fa15e02fd653fbb940a4fa52cece6c0ca4d7cd85f27c041a5cc99a98392d03e50" +sha256 = "dc170645d8aa52f2f94ab8f71093fa0c101e509ed1a07318995dc0395e9d6cf2" +sha512 = "3195a3e0f9ec52c3a91c4b4fde0547694236c7b29bceecb7f38634894fafd809c69ed1c1c9acbf225b2d5d00f5036d70371c9fed121d85028162b202035cabef" [io] url = "https://github.com/WebAssembly/wasi-io/archive/main.tar.gz" -sha256 = "eeb4701c2becafa40a7ee3bf0d2c94e2170e15806b25abdcd1de1ed94f2c1036" -sha512 = "89be853b2acae211570cd6ad0ec9d8132881dafbdea83ac7b4cad600f0627003c61f310427379bf47ecf862724367bd5d6e976db70069f6f90a3c2d9c20dbfb7" +sha256 = "6e18239b0e20d1a3e6343cb961ebfd2c663ba7feb4c1aa3744b756fbdd1fb5b8" +sha512 = "53169b6e4fba0b2cf5fcf808f76e7fbb7cabb6ed66ab53f77d0966e7448312ccbe8571880ef4fc2ee86fbd6ba19bc48d46e10d22dcac6c51d217e8d7127c32db" [poll] url = "https://github.com/WebAssembly/wasi-poll/archive/main.tar.gz" -sha256 = "9f8bb4d9994e9b0684859bb1e8bee2a8b873e04d40695f260446760fc44d0c58" -sha512 = "aa8da395ba6e189ec113296996da5abf28bdc4460e4eb2aacc786698ced892e08f7054fb590fc8809c05554d5c83a11494d4ab68c755746f57d151e212415cfb" +sha256 = "d4c27124f4c137eb538b5c92ba5858ed9042e11b24a2eef85d14becd0b7f55de" +sha512 = "422c01b273b4b1377ece6f2e4ba0dfc609ca8ef30a3e0be0e172e1303fcf7b3ca4c470f4dea6c51bdf114b0f5c871ebc4934dfe3bf217d66ea689748df2b1e55" [random] url = "https://github.com/WebAssembly/wasi-random/archive/main.tar.gz" -sha256 = "30731531ec3453813d08765b428f34aec34ac343cbeafd9885e4e348d187ae04" -sha512 = "6656089f9297ee56cf58c2f95c466e3a22c371925404e6eb9cb5adcb37c1b92f27aaf8c2f9e690ac53ef12f90bd31ac64a84d5f5e06d3f06e24997478275327f" +sha256 = "9b622463e597b9ca94f41e4eaae589a77be38f71b4723142b60246ffed8eaae4" +sha512 = "21f03ca1e595b80d7ced522de1a47446526b49b900e2fb26fcbf410ce6aa267dbf247aebf3fbfa8123b46fc1a828e2fd64fb1e0198b40161a3257e8d86fd4546" [sockets] url = "https://github.com/WebAssembly/wasi-sockets/archive/main.tar.gz" -sha256 = "30c07587eda24676185f175323d5195817b5678815a3f6b64b8152a5b7532493" -sha512 = "8965e112c323e4535786361d864d3b5020791ce7e48da20a6a6b9a1fbec1f78bc10e0830c640f704bd8132fada56cd8a19b48e11e60ec6d9191c08e00550c91c" +sha256 = "871c211b12d87a5da87c42353338b652260840897efcd37e2afba3b9290058fc" +sha512 = "e436a5ff3145ca85d702a086499c03488523483dd3addc8d71e4946e9c186355291551bb6d38b157173836fcc318182403e6dba970de4512f6cfb3374ccad6b9" diff --git a/wit/deps/cli/exit.wit b/wit/deps/cli/exit.wit index 66835aa..4831d50 100644 --- a/wit/deps/cli/exit.wit +++ b/wit/deps/cli/exit.wit @@ -1,4 +1,4 @@ interface exit { - /// Exit the curerent instance and any linked instances. + /// Exit the current instance and any linked instances. exit: func(status: result) } diff --git a/wit/deps/filesystem/preopens.wit b/wit/deps/filesystem/preopens.wit new file mode 100644 index 0000000..f45661b --- /dev/null +++ b/wit/deps/filesystem/preopens.wit @@ -0,0 +1,6 @@ +interface preopens { + use types.{descriptor} + + /// Return the set of preopened directories, and their path. + get-directories: func() -> list> +} diff --git a/wit/deps/filesystem/types.wit b/wit/deps/filesystem/types.wit index 627b638..a437f22 100644 --- a/wit/deps/filesystem/types.wit +++ b/wit/deps/filesystem/types.wit @@ -102,10 +102,6 @@ interface types { /// /// Note: This was called `filestat` in earlier versions of WASI. record descriptor-stat { - /// Device ID of device containing the file. - device: device, - /// File serial number. - inode: inode, /// File type. %type: descriptor-type, /// Number of hard links to the file. @@ -166,14 +162,6 @@ interface types { /// Number of hard links to an inode. type link-count = u64 - /// Identifier for a device containing a file system. Can be used in - /// combination with `inode` to uniquely identify a file or directory in - /// the filesystem. - type device = u64 - - /// Filesystem object serial number that is unique within its file system. - type inode = u64 - /// When setting a timestamp, this gives the value to set it to. variant new-timestamp { /// Leave the timestamp set to its previous value. @@ -187,14 +175,6 @@ interface types { /// A directory entry. record directory-entry { - /// The serial number of the object referred to by this directory entry. - /// May be none if the inode value is not known. - /// - /// When this is none, libc implementations might do an extra `stat-at` - /// call to retrieve the inode number to fill their `d_ino` fields, so - /// implementations which can set this to a non-none value should do so. - inode: option, - /// The type of the file referred to by this directory entry. %type: descriptor-type, @@ -312,7 +292,18 @@ interface types { /// This [represents a resource](https://github.com/WebAssembly/WASI/blob/main/docs/WitInWasi.md#Resources). type descriptor = u32 - /// Return a stream for reading from a file. + /// A 128-bit hash value, split into parts because wasm doesn't have a + /// 128-bit integer type. + record metadata-hash-value { + /// 64 bits of a 128-bit hash value. + lower: u64, + /// Another 64 bits of a 128-bit hash value. + upper: u64, + } + + /// Return a stream for reading from a file, if available. + /// + /// May fail with an error-code describing why the file cannot be read. /// /// Multiple read, write, and append streams may be active on the same open /// file and they do not interfere with each other. @@ -322,9 +313,11 @@ interface types { this: descriptor, /// The offset within the file at which to start reading. offset: filesize, - ) -> input-stream + ) -> result - /// Return a stream for writing to a file. + /// Return a stream for writing to a file, if available. + /// + /// May fail with an error-code describing why the file cannot be written. /// /// Note: This allows using `write-stream`, which is similar to `write` in /// POSIX. @@ -332,15 +325,17 @@ interface types { this: descriptor, /// The offset within the file at which to start writing. offset: filesize, - ) -> output-stream + ) -> result - /// Return a stream for appending to a file. + /// Return a stream for appending to a file, if available. + /// + /// May fail with an error-code describing why the file cannot be appended. /// /// Note: This allows using `write-stream`, which is similar to `write` with /// `O_APPEND` in in POSIX. append-via-stream: func( this: descriptor, - ) -> output-stream + ) -> result /// Provide file advisory information on a descriptor. /// @@ -479,14 +474,20 @@ interface types { /// Return the attributes of an open file or directory. /// - /// Note: This is similar to `fstat` in POSIX. + /// Note: This is similar to `fstat` in POSIX, except that it does not return + /// device and inode information. For testing whether two descriptors refer to + /// the same underlying filesystem object, use `is-same-object`. To obtain + /// additional data that can be used do determine whether a file has been + /// modified, use `metadata-hash`. /// /// Note: This was called `fd_filestat_get` in earlier versions of WASI. stat: func(this: descriptor) -> result /// Return the attributes of a file or directory. /// - /// Note: This is similar to `fstatat` in POSIX. + /// Note: This is similar to `fstatat` in POSIX, except that it does not + /// return device and inode information. See the `stat` description for a + /// discussion of alternatives. /// /// Note: This was called `path_filestat_get` in earlier versions of WASI. stat-at: func( @@ -794,4 +795,47 @@ interface types { /// Dispose of the specified `directory-entry-stream`, after which it may no longer /// be used. drop-directory-entry-stream: func(this: directory-entry-stream) + + /// Test whether two descriptors refer to the same filesystem object. + /// + /// In POSIX, this corresponds to testing whether the two descriptors have the + /// same device (`st_dev`) and inode (`st_ino` or `d_ino`) numbers. + /// wasi-filesystem does not expose device and inode numbers, so this function + /// may be used instead. + is-same-object: func(this: descriptor, other: descriptor) -> bool + + /// Return a hash of the metadata associated with a filesystem object referred + /// to by a descriptor. + /// + /// This returns a hash of the last-modification timestamp and file size, and + /// may also include the inode number, device number, birth timestamp, and + /// other metadata fields that may change when the file is modified or + /// replaced. It may also include a secret value chosen by the + /// implementation and not otherwise exposed. + /// + /// Implementations are encourated to provide the following properties: + /// + /// - If the file is not modified or replaced, the computed hash value should + /// usually not change. + /// - If the object is modified or replaced, the computed hash value should + /// usually change. + /// - The inputs to the hash should not be easily computable from the + /// computed hash. + /// + /// However, none of these is required. + metadata-hash: func( + this: descriptor, + ) -> 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`. + metadata-hash-at: func( + this: descriptor, + /// Flags determining the method of how the path is resolved. + path-flags: path-flags, + /// The relative path of the file or directory to inspect. + path: string, + ) -> result } diff --git a/wit/deps/filesystem/world.wit b/wit/deps/filesystem/world.wit index f2ef782..b51f484 100644 --- a/wit/deps/filesystem/world.wit +++ b/wit/deps/filesystem/world.wit @@ -2,4 +2,5 @@ package wasi:filesystem world example-world { import types + import preopens } diff --git a/wit/deps/io/streams.wit b/wit/deps/io/streams.wit index 430c1d4..de8694b 100644 --- a/wit/deps/io/streams.wit +++ b/wit/deps/io/streams.wit @@ -10,6 +10,19 @@ interface streams { /// doesn't provide any additional information. record stream-error {} + /// Streams provide a sequence of data and then end; once they end, they + /// no longer provide any further data. + /// + /// For example, a stream reading from a file ends when the stream reaches + /// the end of the file. For another example, a stream reading from a + /// socket ends when the socket is closed. + enum stream-status { + /// The stream is open and may produce further data. + open, + /// The stream has ended and will not produce any further data. + ended, + } + /// An input bytestream. In the future, this will be replaced by handle /// types. /// @@ -32,9 +45,9 @@ interface streams { /// Read bytes from a stream. /// /// This function returns a list of bytes containing the data that was - /// read, along with a bool which, when true, indicates that the end of the - /// stream was reached. The returned list will contain up to `len` bytes; it - /// may return fewer than requested, but not more. + /// read, along with a `stream-status` which indicates whether the end of + /// the stream was reached. The returned list will contain up to `len` + /// bytes; it may return fewer than requested, but not more. /// /// Once a stream has reached the end, subsequent calls to read or /// `skip` will always report end-of-stream rather than producing more @@ -51,7 +64,7 @@ interface streams { this: input-stream, /// The maximum number of bytes to read len: u64 - ) -> result, bool>, stream-error> + ) -> result, stream-status>, stream-error> /// Read bytes from a stream, with blocking. /// @@ -61,7 +74,7 @@ interface streams { this: input-stream, /// The maximum number of bytes to read len: u64 - ) -> result, bool>, stream-error> + ) -> result, stream-status>, stream-error> /// Skip bytes from a stream. /// @@ -72,14 +85,14 @@ interface streams { /// `skip` will always report end-of-stream rather than producing more /// data. /// - /// This function returns the number of bytes skipped, along with a bool - /// indicating whether the end of the stream was reached. The returned - /// value will be at most `len`; it may be less. + /// This function returns the number of bytes skipped, along with a + /// `stream-status` indicating whether the end of the stream was + /// reached. The returned value will be at most `len`; it may be less. skip: func( this: input-stream, /// The maximum number of bytes to skip. len: u64, - ) -> result, stream-error> + ) -> result, stream-error> /// Skip bytes from a stream, with blocking. /// @@ -89,7 +102,7 @@ interface streams { this: input-stream, /// The maximum number of bytes to skip. len: u64, - ) -> result, stream-error> + ) -> result, stream-error> /// Create a `pollable` which will resolve once either the specified stream /// has bytes available to read or the other end of the stream has been @@ -172,7 +185,7 @@ interface streams { src: input-stream, /// The number of bytes to splice len: u64, - ) -> result, stream-error> + ) -> result, stream-error> /// Read from one stream and write to another, with blocking. /// @@ -184,7 +197,7 @@ interface streams { src: input-stream, /// The number of bytes to splice len: u64, - ) -> result, stream-error> + ) -> result, stream-error> /// Forward the entire contents of an input stream to an output stream. /// diff --git a/wit/deps/poll/poll.wit b/wit/deps/poll/poll.wit index 55eee00..fa82b60 100644 --- a/wit/deps/poll/poll.wit +++ b/wit/deps/poll/poll.wit @@ -23,17 +23,27 @@ interface poll { /// Poll for completion on a set of pollables. /// + /// This function takes a list of pollables, which identify I/O sources of + /// interest, and waits until one or more of the events is ready for I/O. + /// + /// The result `list` is the same length as the argument + /// `list`, and indicates the readiness of each corresponding + /// element in that list, with true indicating ready. A single call can + /// return multiple true elements. + /// + /// A timeout can be implemented by adding a pollable from the + /// wasi-clocks API to the list. + /// + /// This function does not return a `result`; polling in itself does not + /// do any I/O so it doesn't fail. If any of the I/O sources identified by + /// the pollables has an error, it is indicated by marking the source as + /// ready in the `list`. + /// /// The "oneoff" in the name refers to the fact that this function must do a /// linear scan through the entire list of subscriptions, which may be /// inefficient if the number is large and the same subscriptions are used /// many times. In the future, this is expected to be obsoleted by the /// component model async proposal, which will include a scalable waiting /// facility. - /// - /// Note that the return type would ideally be `list`, but that would - /// be more difficult to polyfill given the current state of `wit-bindgen`. - /// See - /// for details. For now, we use zero to mean "not ready" and non-zero to - /// mean "ready". - poll-oneoff: func(in: list) -> list + poll-oneoff: func(in: list) -> list } diff --git a/wit/deps/random/random.wit b/wit/deps/random/random.wit index e423862..2a282da 100644 --- a/wit/deps/random/random.wit +++ b/wit/deps/random/random.wit @@ -3,21 +3,23 @@ /// It is intended to be portable at least between Unix-family platforms and /// Windows. interface random { - /// Return `len` cryptographically-secure pseudo-random bytes. + /// Return `len` cryptographically-secure random or pseudo-random bytes. /// - /// This function must produce data from an adequately seeded - /// cryptographically-secure pseudo-random number generator (CSPRNG), so it - /// must not block, from the perspective of the calling program, and the - /// returned data is always unpredictable. + /// This function must produce data at least as cryptographically secure and + /// fast as an adequately seeded cryptographically-secure pseudo-random + /// number generator (CSPRNG). It must not block, from the perspective of + /// the calling program, under any circumstances, including on the first + /// request and on requests for numbers of bytes. The returned data must + /// always be unpredictable. /// - /// This function must always return fresh pseudo-random data. Deterministic - /// environments must omit this function, rather than implementing it with - /// deterministic data. + /// This function must always return fresh data. Deterministic environments + /// must omit this function, rather than implementing it with deterministic + /// data. get-random-bytes: func(len: u64) -> list - /// Return a cryptographically-secure pseudo-random `u64` value. + /// Return a cryptographically-secure random or pseudo-random `u64` value. /// - /// This function returns the same type of pseudo-random data as - /// `get-random-bytes`, represented as a `u64`. + /// This function returns the same type of data as `get-random-bytes`, + /// represented as a `u64`. get-random-u64: func() -> u64 } diff --git a/wit/deps/sockets/udp.wit b/wit/deps/sockets/udp.wit index 3a0c1bd..948ed58 100644 --- a/wit/deps/sockets/udp.wit +++ b/wit/deps/sockets/udp.wit @@ -84,11 +84,11 @@ interface udp { start-connect: func(this: udp-socket, network: network, remote-address: ip-socket-address) -> result<_, error-code> finish-connect: func(this: udp-socket) -> result<_, error-code> - /// Receive a message. + /// Receive messages on the socket. /// - /// Returns: - /// - The sender address of the datagram - /// - The number of bytes read. + /// This function attempts to receive up to `max-results` datagrams on the socket without blocking. + /// The returned list may contain fewer elements than requested, but never more. + /// If `max-results` is 0, this function returns successfully with an empty list. /// /// # Typical errors /// - `not-bound`: The socket is not bound to any local address. (EINVAL) @@ -99,13 +99,23 @@ interface udp { /// - /// - /// - + /// - /// - /// - /// - /// - - receive: func(this: udp-socket) -> result + receive: func(this: udp-socket, max-results: u64) -> result, error-code> - /// Send a message to a specific destination address. + /// Send messages on the socket. + /// + /// This function attempts to send all provided `datagrams` on the socket without blocking and + /// returns how many messages were actually sent (or queued for sending). + /// + /// This function semantically behaves the same as iterating the `datagrams` list and sequentially + /// sending each individual datagram until either the end of the list has been reached or the first error occurred. + /// If at least one datagram has been sent successfully, this function never returns an error. + /// + /// If the input list is empty, the function returns `ok(0)`. /// /// The remote address option is required. To send a message to the "connected" peer, /// call `remote-address` to get their address. @@ -124,11 +134,12 @@ interface udp { /// - /// - /// - + /// - /// - /// - /// - /// - - send: func(this: udp-socket, datagram: datagram) -> result<_, error-code> + send: func(this: udp-socket, datagrams: list) -> result /// Get the current bound address. ///