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