Skip to main content

wasmtime_wasi_io/
streams.rs

1use crate::poll::Pollable;
2use alloc::boxed::Box;
3use bytes::Bytes;
4use wasmtime::Result;
5
6/// `Pollable::ready()` for `InputStream` and `OutputStream` may return
7/// prematurely due to `io::ErrorKind::WouldBlock`.
8///
9/// To ensure that `blocking_` functions return a valid non-empty result,
10/// we use a loop with a maximum iteration limit.
11///
12/// This constant defines the maximum number of loop attempts allowed.
13const MAX_BLOCKING_ATTEMPTS: u8 = 10;
14
15/// Host trait for implementing the `wasi:io/streams.input-stream` resource: A
16/// bytestream which can be read from.
17#[async_trait::async_trait]
18pub trait InputStream: Pollable {
19    /// Reads up to `size` bytes, returning a buffer holding these bytes on
20    /// success.
21    ///
22    /// This function does not block the current thread and is the equivalent of
23    /// a non-blocking read. On success all bytes read are returned through
24    /// `Bytes`, which is no larger than the `size` provided. If the returned
25    /// list of `Bytes` is empty then no data is ready to be read at this time.
26    ///
27    /// # Errors
28    ///
29    /// The [`StreamError`] return value communicates when this stream is
30    /// closed, when a read fails, or when a trap should be generated.
31    fn read(&mut self, size: usize) -> StreamResult<Bytes>;
32
33    /// Similar to `read`, except that it blocks until at least one byte can be
34    /// read.
35    async fn blocking_read(&mut self, size: usize) -> StreamResult<Bytes> {
36        if size == 0 {
37            return self.read(size);
38        }
39
40        let mut i = 0;
41        loop {
42            // This `ready` call may return prematurely due to `io::ErrorKind::WouldBlock`.
43            self.ready().await;
44            let data = self.read(size)?;
45            if !data.is_empty() {
46                return Ok(data);
47            }
48            if i >= MAX_BLOCKING_ATTEMPTS {
49                return Err(StreamError::trap("max blocking attempts exceeded"));
50            }
51            i += 1;
52        }
53    }
54
55    /// Same as the `read` method except that bytes are skipped.
56    ///
57    /// Note that this method is non-blocking like `read` and returns the same
58    /// errors.
59    fn skip(&mut self, nelem: usize) -> StreamResult<usize> {
60        let bs = self.read(nelem)?;
61        Ok(bs.len())
62    }
63
64    /// Similar to `skip`, except that it blocks until at least one byte can be
65    /// skipped.
66    async fn blocking_skip(&mut self, nelem: usize) -> StreamResult<usize> {
67        let bs = self.blocking_read(nelem).await?;
68        Ok(bs.len())
69    }
70
71    /// Cancel any asynchronous work and wait for it to wrap up.
72    async fn cancel(&mut self) {}
73}
74
75/// Representation of the `error` resource type in the `wasi:io/error`
76/// interface.
77///
78/// This is currently `wasmtime::Error` to retain full type information for
79/// errors.
80pub type Error = wasmtime::Error;
81
82pub type StreamResult<T> = Result<T, StreamError>;
83
84#[derive(Debug)]
85pub enum StreamError {
86    Closed,
87    LastOperationFailed(wasmtime::Error),
88    Trap(wasmtime::Error),
89}
90
91impl StreamError {
92    pub fn trap(msg: &str) -> StreamError {
93        StreamError::Trap(wasmtime::format_err!("{msg}"))
94    }
95}
96
97impl alloc::fmt::Display for StreamError {
98    fn fmt(&self, f: &mut alloc::fmt::Formatter<'_>) -> alloc::fmt::Result {
99        match self {
100            StreamError::Closed => write!(f, "closed"),
101            StreamError::LastOperationFailed(e) => write!(f, "last operation failed: {e}"),
102            StreamError::Trap(e) => write!(f, "trap: {e}"),
103        }
104    }
105}
106
107impl core::error::Error for StreamError {
108    fn source(&self) -> Option<&(dyn core::error::Error + 'static)> {
109        match self {
110            StreamError::Closed => None,
111            StreamError::LastOperationFailed(e) | StreamError::Trap(e) => e.source(),
112        }
113    }
114}
115
116impl From<wasmtime::component::ResourceTableError> for StreamError {
117    fn from(error: wasmtime::component::ResourceTableError) -> Self {
118        Self::Trap(error.into())
119    }
120}
121
122/// Host trait for implementing the `wasi:io/streams.output-stream` resource:
123/// A bytestream which can be written to.
124#[async_trait::async_trait]
125pub trait OutputStream: Pollable {
126    /// Write bytes after obtaining a permit to write those bytes
127    ///
128    /// Prior to calling [`write`](Self::write) the caller must call
129    /// [`check_write`](Self::check_write), which resolves to a non-zero permit
130    ///
131    /// This method must never block.  The [`check_write`](Self::check_write)
132    /// permit indicates the maximum amount of bytes that are permitted to be
133    /// written in a single [`write`](Self::write) following the
134    /// [`check_write`](Self::check_write) resolution.
135    ///
136    /// # Errors
137    ///
138    /// Returns a [`StreamError`] if:
139    /// - stream is closed
140    /// - prior operation ([`write`](Self::write) or [`flush`](Self::flush)) failed
141    /// - caller performed an illegal operation (e.g. wrote more bytes than were permitted)
142    fn write(&mut self, bytes: Bytes) -> StreamResult<()>;
143
144    /// Trigger a flush of any bytes buffered in this stream implementation.
145    ///
146    /// This method may be called at any time and must never block.
147    ///
148    /// After this method is called, [`check_write`](Self::check_write) must
149    /// pend until flush is complete.
150    ///
151    /// When [`check_write`](Self::check_write) becomes ready after a flush,
152    /// that guarantees that all prior writes have been flushed from the
153    /// implementation successfully, or that any error associated with those
154    /// writes is reported in the return value of [`flush`](Self::flush) or
155    /// [`check_write`](Self::check_write)
156    ///
157    /// # Errors
158    ///
159    /// Returns a [`StreamError`] if:
160    /// - stream is closed
161    /// - prior operation ([`write`](Self::write) or [`flush`](Self::flush)) failed
162    /// - caller performed an illegal operation (e.g. wrote more bytes than were permitted)
163    fn flush(&mut self) -> StreamResult<()>;
164
165    /// Returns the number of bytes that are ready to be written to this stream.
166    ///
167    /// Zero bytes indicates that this stream is not currently ready for writing
168    /// and `ready()` must be awaited first.
169    ///
170    /// Note that this method does not block.
171    ///
172    /// Additionally note that this method controls the allowed allocation size
173    /// of other methods. For example `write_zeroes` will allow up to the
174    /// allowance of `check_write` and will allocate that many zeroes currently.
175    /// This should not be an overly-large value as otherwise guests will be
176    /// able to force the host to perform such an allocation. This number is
177    /// typicall ~64k for WASI streams at this time.
178    ///
179    /// # Errors
180    ///
181    /// Returns an [`StreamError`] if:
182    /// - stream is closed
183    /// - prior operation ([`write`](Self::write) or [`flush`](Self::flush)) failed
184    fn check_write(&mut self) -> StreamResult<usize>;
185
186    /// Perform a write of up to 4096 bytes, and then flush the stream. Block
187    /// until all of these operations are complete, or an error occurs.
188    ///
189    /// This is a convenience wrapper around the use of `check-write`,
190    /// `subscribe`, `write`, and `flush`, and is implemented with the
191    /// following pseudo-code:
192    ///
193    /// ```text
194    /// let pollable = this.subscribe();
195    /// while !contents.is_empty() {
196    ///     // Wait for the stream to become writable
197    ///     pollable.block();
198    ///     let Ok(n) = this.check-write(); // eliding error handling
199    ///     let len = min(n, contents.len());
200    ///     let (chunk, rest) = contents.split_at(len);
201    ///     this.write(chunk  );            // eliding error handling
202    ///     contents = rest;
203    /// }
204    /// this.flush();
205    /// // Wait for completion of `flush`
206    /// pollable.block();
207    /// // Check for any errors that arose during `flush`
208    /// let _ = this.check-write();         // eliding error handling
209    /// ```
210    async fn blocking_write_and_flush(&mut self, mut bytes: Bytes) -> StreamResult<()> {
211        loop {
212            let permit = self.write_ready().await?;
213            let len = bytes.len().min(permit);
214            let chunk = bytes.split_to(len);
215            self.write(chunk)?;
216            if bytes.is_empty() {
217                break;
218            }
219        }
220
221        // If the stream encounters an error, return it, but if the stream
222        // has become closed, do not.
223        match self.flush() {
224            Ok(_) => {}
225            Err(StreamError::Closed) => {}
226            Err(e) => Err(e)?,
227        };
228        match self.write_ready().await {
229            Ok(_) => {}
230            Err(StreamError::Closed) => {}
231            Err(e) => Err(e)?,
232        };
233
234        Ok(())
235    }
236
237    /// Repeatedly write a byte to a stream.
238    /// Important: this write must be non-blocking!
239    /// Returning an Err which downcasts to a [`StreamError`] will be
240    /// reported to Wasm as the empty error result. Otherwise, errors will trap.
241    fn write_zeroes(&mut self, nelem: usize) -> StreamResult<()> {
242        let n = self.check_write()?;
243        if nelem > n {
244            return Err(StreamError::trap(
245                "cannot write more zeroes than `check_write` allows",
246            ));
247        };
248        // TODO: We could optimize this to not allocate one big zeroed buffer, and instead write
249        // repeatedly from a 'static buffer of zeros.
250        let bs = Bytes::from_iter(core::iter::repeat(0).take(nelem));
251        self.write(bs)?;
252        Ok(())
253    }
254
255    /// Simultaneously waits for this stream to be writable and then returns how
256    /// much may be written or the last error that happened.
257    async fn write_ready(&mut self) -> StreamResult<usize> {
258        let mut i = 0;
259        loop {
260            // This `ready` call may return prematurely due to `io::ErrorKind::WouldBlock`.
261            self.ready().await;
262            let n = self.check_write()?;
263            if n > 0 {
264                return Ok(n);
265            }
266            if i >= MAX_BLOCKING_ATTEMPTS {
267                return Err(StreamError::trap("max blocking attempts exceeded"));
268            }
269            i += 1;
270        }
271    }
272
273    /// Cancel any asynchronous work and wait for it to wrap up.
274    async fn cancel(&mut self) {}
275}
276
277#[async_trait::async_trait]
278impl Pollable for Box<dyn OutputStream> {
279    async fn ready(&mut self) {
280        (**self).ready().await
281    }
282}
283
284#[async_trait::async_trait]
285impl Pollable for Box<dyn InputStream> {
286    async fn ready(&mut self) {
287        (**self).ready().await
288    }
289}
290
291pub type DynInputStream = Box<dyn InputStream>;
292
293pub type DynOutputStream = Box<dyn OutputStream>;