Update streams.wit in wasi-http

Author: elliottt

crates/wasi-http/src/component_impl.rs

@@ -409,7 +409,10 @@ where
             Box::new(async move {
                 let ctx = get_cx(caller.data_mut());
 
-                let (bytes, status) = io::streams::Host::read(ctx, stream, len).await?;
+                let (bytes, status) = io::streams::Host::read(ctx, stream, len)
+                    .await?
+                    .map_err(|_| anyhow!("read failed"))?;
+
                 let done = match status {
                     io::streams::StreamStatus::Open => 0,
                     io::streams::StreamStatus::Ended => 1,
@@ -462,7 +465,9 @@ where
 
                 let ctx = get_cx(caller.data_mut());
 
-                let (len, status) = io::streams::Host::write(ctx, stream, body.into()).await?;
+                let (len, status) = io::streams::Host::write(ctx, stream, body.into())
+                    .await?
+                    .map_err(|_| anyhow!("write failed"))?;
                 let written: u32 = len.try_into()?;
                 let done: u32 = match status {
                     io::streams::StreamStatus::Open => 0,

crates/wasi-http/wit/deps/io/streams.wit

@@ -8,16 +8,6 @@ package wasi:io
 interface streams {
     use wasi:poll/poll.{pollable}
 
-    /// An error type returned from a stream operation.
-    ///
-    /// TODO: need to figure out the actual contents of this error. Used to be
-    /// an empty record but that's no longer allowed. The `dummy` field is
-    /// only here to have this be a valid in the component model by being
-    /// non-empty.
-    record stream-error {
-      dummy: u32,
-    }
-
     /// Streams provide a sequence of data and then end; once they end, they
     /// no longer provide any further data.
     ///
@@ -37,15 +27,12 @@ interface streams {
     /// An input bytestream. In the future, this will be replaced by handle
     /// types.
     ///
-    /// This conceptually represents a `stream<u8, _>`. It's temporary
-    /// scaffolding until component-model's async features are ready.
-    ///
     /// `input-stream`s are *non-blocking* to the extent practical on underlying
     /// platforms. I/O operations always return promptly; if fewer bytes are
     /// promptly available than requested, they return the number of bytes promptly
     /// available, which could even be zero. To wait for data to be available,
     /// use the `subscribe-to-input-stream` function to obtain a `pollable` which
-    /// can be polled for using `wasi_poll`.
+    /// can be polled for using `wasi:poll/poll.poll_oneoff`.
     ///
     /// And at present, it is a `u32` instead of being an actual handle, until
     /// the wit-bindgen implementation of handles and resources is ready.
@@ -58,40 +45,36 @@ interface streams {
     /// This function returns a list of bytes containing the data that was
     /// read, along with a `stream-status` which, indicates whether further
     /// reads are expected to produce data. 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
+    /// `len` bytes; it may return fewer than requested, but not more. An
+    /// empty list and `stream-status:open` indicates no more data is
+    /// available at this time, and that the pollable given by
+    /// `subscribe-to-input-stream` will be ready when more data is available.
+    /// 
+    /// Once a stream has reached the end, subsequent calls to `read` or
+    /// `skip` will always report `stream-status:ended` rather than producing more
     /// data.
     ///
-    /// If `len` is 0, it represents a request to read 0 bytes, which should
-    /// always succeed, assuming the stream hasn't reached its end yet, and
-    /// return an empty list.
-    ///
-    /// The len here is a `u64`, but some callees may not be able to allocate
-    /// a buffer as large as that would imply.
-    /// FIXME: describe what happens if allocation fails.
+    /// When the caller gives a `len` of 0, it represents a request to read 0
+    /// bytes. This read should  always succeed and return an empty list and
+    /// the current `stream-status`.
     ///
-    /// When the returned `stream-status` is `open`, the length of the returned
-    /// value may be less than `len`. When an empty list is returned, this
-    /// indicates that no more bytes were available from the stream at that
-    /// time. In that case the subscribe-to-input-stream pollable will indicate
-    /// when additional bytes are available for reading.
+    /// The `len` parameter is a `u64`, which could represent a list of u8 which
+    /// 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.
     read: func(
         this: input-stream,
         /// The maximum number of bytes to read
         len: u64
-    ) -> result<tuple<list<u8>, stream-status>, stream-error>
+    ) -> result<tuple<list<u8>, stream-status>>
 
-    /// Read bytes from a stream, with blocking.
-    ///
-    /// This is similar to `read`, except that it blocks until at least one
-    /// byte can be read.
+    /// Read bytes from a stream, after blocking until at least one byte can
+    /// be read. Except for blocking, identical to `read`.
     blocking-read: func(
         this: input-stream,
         /// The maximum number of bytes to read
         len: u64
-    ) -> result<tuple<list<u8>, stream-status>, stream-error>
+    ) -> result<tuple<list<u8>, stream-status>>
 
     /// Skip bytes from a stream.
     ///
@@ -102,40 +85,42 @@ 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<tuple<u64, stream-status>, stream-error>
+    ) -> result<tuple<u64, stream-status>>
 
-    /// Skip bytes from a stream, with blocking.
-    ///
-    /// This is similar to `skip`, except that it blocks until at least one
-    /// byte can be consumed.
+    /// Skip bytes from a stream, after blocking until at least one byte
+    /// can be skipped. Except for blocking behavior, identical to `skip`.
     blocking-skip: func(
         this: input-stream,
         /// The maximum number of bytes to skip.
         len: u64,
-    ) -> result<tuple<u64, stream-status>, stream-error>
+    ) -> result<tuple<u64, stream-status>>
 
     /// Create a `pollable` which will resolve once either the specified stream
     /// has bytes available to read or the other end of the stream has been
     /// closed.
+    /// 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.
     subscribe-to-input-stream: func(this: input-stream) -> pollable
 
     /// Dispose of the specified `input-stream`, after which it may no longer
     /// be used.
+    /// Implementations may trap if this `input-stream` is dropped while child
+    /// `pollable` resources are still alive.
+    /// After this `input-stream` is dropped, implementations may report any
+    /// corresponding `output-stream` has `stream-state.closed`.
     drop-input-stream: func(this: input-stream)
 
     /// An output bytestream. In the future, this will be replaced by handle
     /// types.
     ///
-    /// This conceptually represents a `stream<u8, _>`. It's temporary
-    /// scaffolding until component-model's async features are ready.
-    ///
     /// `output-stream`s are *non-blocking* to the extent practical on
     /// underlying platforms. Except where specified otherwise, I/O operations also
     /// always return promptly, after the number of bytes that can be written
@@ -159,45 +144,48 @@ interface streams {
     /// When the returned `stream-status` is `open`, the `u64` return value may
     /// be less than the length of `buf`. This indicates that no more bytes may
     /// be written to the stream promptly. In that case the
-    /// subscribe-to-output-stream pollable will indicate when additional bytes
+    /// `subscribe-to-output-stream` pollable will indicate when additional bytes
     /// may be promptly written.
     ///
-    /// TODO: document what happens when an empty list is written
+    /// Writing an empty list must return a non-error result with `0` for the
+    /// `u64` return value, and the current `stream-status`.
     write: func(
         this: output-stream,
         /// Data to write
         buf: list<u8>
-    ) -> result<tuple<u64, stream-status>, stream-error>
+    ) -> result<tuple<u64, stream-status>>
 
-    /// Write bytes to a stream, with blocking.
+    /// Blocking write of bytes to a stream.
     ///
     /// This is similar to `write`, except that it blocks until at least one
     /// byte can be written.
     blocking-write: func(
         this: output-stream,
         /// Data to write
         buf: list<u8>
-    ) -> result<tuple<u64, stream-status>, stream-error>
+    ) -> result<tuple<u64, stream-status>>
 
-    /// Write multiple zero bytes to a stream.
+    /// Write multiple zero-bytes to a stream.
     ///
-    /// This function returns a `u64` indicating the number of zero bytes
-    /// that were written; it may be less than `len`.
+    /// This function returns a `u64` indicating the number of zero-bytes
+    /// that were written; it may be less than `len`. Equivelant to a call to
+    /// `write` with a list of zeroes of the given length.
     write-zeroes: func(
         this: output-stream,
-        /// The number of zero bytes to write
+        /// The number of zero-bytes to write
         len: u64
-    ) -> result<tuple<u64, stream-status>, stream-error>
+    ) -> result<tuple<u64, stream-status>>
 
     /// Write multiple zero bytes to a stream, with blocking.
     ///
     /// This is similar to `write-zeroes`, except that it blocks until at least
-    /// one byte can be written.
+    /// one byte can be written. Equivelant to a call to `blocking-write` with
+    /// a list of zeroes of the given length.
     blocking-write-zeroes: func(
         this: output-stream,
         /// The number of zero bytes to write
         len: u64
-    ) -> result<tuple<u64, stream-status>, stream-error>
+    ) -> result<tuple<u64, stream-status>>
 
     /// Read from one stream and write to another.
     ///
@@ -212,7 +200,7 @@ interface streams {
         src: input-stream,
         /// The number of bytes to splice
         len: u64,
-    ) -> result<tuple<u64, stream-status>, stream-error>
+    ) -> result<tuple<u64, stream-status>>
 
     /// Read from one stream and write to another, with blocking.
     ///
@@ -224,7 +212,7 @@ interface streams {
         src: input-stream,
         /// The number of bytes to splice
         len: u64,
-    ) -> result<tuple<u64, stream-status>, stream-error>
+    ) -> result<tuple<u64, stream-status>>
 
     /// Forward the entire contents of an input stream to an output stream.
     ///
@@ -242,13 +230,24 @@ interface streams {
         this: output-stream,
         /// The stream to read from
         src: input-stream
-    ) -> result<tuple<u64, stream-status>, stream-error>
+    ) -> result<tuple<u64, stream-status>>
 
     /// Create a `pollable` which will resolve once either the specified stream
-    /// is ready to accept bytes or the other end of the stream has been closed.
+    /// is ready to accept bytes or the `stream-state` has become closed.
+    ///
+    /// Once the stream-state is closed, this pollable is always ready
+    /// immediately.
+    ///
+    /// The created `pollable` is a child resource of the `output-stream`.
+    /// Implementations may trap if the `output-stream` is dropped before
+    /// all derived `pollable`s created with this function are dropped.
     subscribe-to-output-stream: func(this: output-stream) -> pollable
 
     /// Dispose of the specified `output-stream`, after which it may no longer
     /// be used.
+    /// Implementations may trap if this `output-stream` is dropped while
+    /// child `pollable` resources are still alive.
+    /// After this `output-stream` is dropped, implementations may report any
+    /// corresponding `input-stream` has `stream-state.closed`.
     drop-output-stream: func(this: output-stream)
 }