wasmtime 21.0.1 → 22.0.0

data/ext/cargo-vendor/wasmtime-wasi-22.0.0/src/pipe.rs

@@ -0,0 +1,826 @@
+//! Virtual pipes.
+//!
+//! These types provide easy implementations of `WasiFile` that mimic much of the behavior of Unix
+//! pipes. These are particularly helpful for redirecting WASI stdio handles to destinations other
+//! than OS files.
+//!
+//! Some convenience constructors are included for common backing types like `Vec<u8>` and `String`,
+//! but the virtual pipes can be instantiated with any `Read` or `Write` type.
+//!
+use crate::poll::Subscribe;
+use crate::{HostInputStream, HostOutputStream, StreamError};
+use anyhow::anyhow;
+use bytes::Bytes;
+use std::sync::{Arc, Mutex};
+use tokio::sync::mpsc;
+
+pub use crate::write_stream::AsyncWriteStream;
+
+#[derive(Debug, Clone)]
+pub struct MemoryInputPipe {
+    buffer: Arc<Mutex<Bytes>>,
+}
+
+impl MemoryInputPipe {
+    pub fn new(bytes: impl Into<Bytes>) -> Self {
+        Self {
+            buffer: Arc::new(Mutex::new(bytes.into())),
+        }
+    }
+
+    pub fn is_empty(&self) -> bool {
+        self.buffer.lock().unwrap().is_empty()
+    }
+}
+
+#[async_trait::async_trait]
+impl HostInputStream for MemoryInputPipe {
+    fn read(&mut self, size: usize) -> Result<Bytes, StreamError> {
+        let mut buffer = self.buffer.lock().unwrap();
+        if buffer.is_empty() {
+            return Err(StreamError::Closed);
+        }
+
+        let size = size.min(buffer.len());
+        let read = buffer.split_to(size);
+        Ok(read)
+    }
+}
+
+#[async_trait::async_trait]
+impl Subscribe for MemoryInputPipe {
+    async fn ready(&mut self) {}
+}
+
+#[derive(Debug, Clone)]
+pub struct MemoryOutputPipe {
+    capacity: usize,
+    buffer: Arc<Mutex<bytes::BytesMut>>,
+}
+
+impl MemoryOutputPipe {
+    pub fn new(capacity: usize) -> Self {
+        MemoryOutputPipe {
+            capacity,
+            buffer: std::sync::Arc::new(std::sync::Mutex::new(bytes::BytesMut::new())),
+        }
+    }
+
+    pub fn contents(&self) -> bytes::Bytes {
+        self.buffer.lock().unwrap().clone().freeze()
+    }
+
+    pub fn try_into_inner(self) -> Option<bytes::BytesMut> {
+        std::sync::Arc::into_inner(self.buffer).map(|m| m.into_inner().unwrap())
+    }
+}
+
+impl HostOutputStream for MemoryOutputPipe {
+    fn write(&mut self, bytes: Bytes) -> Result<(), StreamError> {
+        let mut buf = self.buffer.lock().unwrap();
+        if bytes.len() > self.capacity - buf.len() {
+            return Err(StreamError::Trap(anyhow!(
+                "write beyond capacity of MemoryOutputPipe"
+            )));
+        }
+        buf.extend_from_slice(bytes.as_ref());
+        // Always ready for writing
+        Ok(())
+    }
+    fn flush(&mut self) -> Result<(), StreamError> {
+        // This stream is always flushed
+        Ok(())
+    }
+    fn check_write(&mut self) -> Result<usize, StreamError> {
+        let consumed = self.buffer.lock().unwrap().len();
+        if consumed < self.capacity {
+            Ok(self.capacity - consumed)
+        } else {
+            // Since the buffer is full, no more bytes will ever be written
+            Err(StreamError::Closed)
+        }
+    }
+}
+
+#[async_trait::async_trait]
+impl Subscribe for MemoryOutputPipe {
+    async fn ready(&mut self) {}
+}
+
+/// Provides a [`HostInputStream`] impl from a [`tokio::io::AsyncRead`] impl
+pub struct AsyncReadStream {
+    closed: bool,
+    buffer: Option<Result<Bytes, StreamError>>,
+    receiver: mpsc::Receiver<Result<Bytes, StreamError>>,
+    _join_handle: crate::runtime::AbortOnDropJoinHandle<()>,
+}
+
+impl AsyncReadStream {
+    /// Create a [`AsyncReadStream`]. In order to use the [`HostInputStream`] impl
+    /// provided by this struct, the argument must impl [`tokio::io::AsyncRead`].
+    pub fn new<T: tokio::io::AsyncRead + Send + Unpin + 'static>(mut reader: T) -> Self {
+        let (sender, receiver) = mpsc::channel(1);
+        let join_handle = crate::runtime::spawn(async move {
+            loop {
+                use tokio::io::AsyncReadExt;
+                let mut buf = bytes::BytesMut::with_capacity(4096);
+                let sent = match reader.read_buf(&mut buf).await {
+                    Ok(nbytes) if nbytes == 0 => sender.send(Err(StreamError::Closed)).await,
+                    Ok(_) => sender.send(Ok(buf.freeze())).await,
+                    Err(e) => {
+                        sender
+                            .send(Err(StreamError::LastOperationFailed(e.into())))
+                            .await
+                    }
+                };
+                if sent.is_err() {
+                    // no more receiver - stop trying to read
+                    break;
+                }
+            }
+        });
+        AsyncReadStream {
+            closed: false,
+            buffer: None,
+            receiver,
+            _join_handle: join_handle,
+        }
+    }
+}
+
+#[async_trait::async_trait]
+impl HostInputStream for AsyncReadStream {
+    fn read(&mut self, size: usize) -> Result<Bytes, StreamError> {
+        use mpsc::error::TryRecvError;
+
+        match self.buffer.take() {
+            Some(Ok(mut bytes)) => {
+                // TODO: de-duplicate the buffer management with the case below
+                let len = bytes.len().min(size);
+                let rest = bytes.split_off(len);
+                if !rest.is_empty() {
+                    self.buffer = Some(Ok(rest));
+                }
+                return Ok(bytes);
+            }
+            Some(Err(e)) => {
+                self.closed = true;
+                return Err(e);
+            }
+            None => {}
+        }
+
+        match self.receiver.try_recv() {
+            Ok(Ok(mut bytes)) => {
+                let len = bytes.len().min(size);
+                let rest = bytes.split_off(len);
+                if !rest.is_empty() {
+                    self.buffer = Some(Ok(rest));
+                }
+
+                Ok(bytes)
+            }
+            Ok(Err(e)) => {
+                self.closed = true;
+                Err(e)
+            }
+            Err(TryRecvError::Empty) => Ok(Bytes::new()),
+            Err(TryRecvError::Disconnected) => Err(StreamError::Trap(anyhow!(
+                "AsyncReadStream sender died - should be impossible"
+            ))),
+        }
+    }
+}
+#[async_trait::async_trait]
+impl Subscribe for AsyncReadStream {
+    async fn ready(&mut self) {
+        if self.buffer.is_some() || self.closed {
+            return;
+        }
+        match self.receiver.recv().await {
+            Some(res) => self.buffer = Some(res),
+            None => {
+                panic!("no more sender for an open AsyncReadStream - should be impossible")
+            }
+        }
+    }
+}
+
+/// An output stream that consumes all input written to it, and is always ready.
+#[derive(Copy, Clone)]
+pub struct SinkOutputStream;
+
+impl HostOutputStream for SinkOutputStream {
+    fn write(&mut self, _buf: Bytes) -> Result<(), StreamError> {
+        Ok(())
+    }
+    fn flush(&mut self) -> Result<(), StreamError> {
+        // This stream is always flushed
+        Ok(())
+    }
+
+    fn check_write(&mut self) -> Result<usize, StreamError> {
+        // This stream is always ready for writing.
+        Ok(usize::MAX)
+    }
+}
+
+#[async_trait::async_trait]
+impl Subscribe for SinkOutputStream {
+    async fn ready(&mut self) {}
+}
+
+/// A stream that is ready immediately, but will always report that it's closed.
+#[derive(Copy, Clone)]
+pub struct ClosedInputStream;
+
+#[async_trait::async_trait]
+impl HostInputStream for ClosedInputStream {
+    fn read(&mut self, _size: usize) -> Result<Bytes, StreamError> {
+        Err(StreamError::Closed)
+    }
+}
+
+#[async_trait::async_trait]
+impl Subscribe for ClosedInputStream {
+    async fn ready(&mut self) {}
+}
+
+/// An output stream that is always closed.
+#[derive(Copy, Clone)]
+pub struct ClosedOutputStream;
+
+impl HostOutputStream for ClosedOutputStream {
+    fn write(&mut self, _: Bytes) -> Result<(), StreamError> {
+        Err(StreamError::Closed)
+    }
+    fn flush(&mut self) -> Result<(), StreamError> {
+        Err(StreamError::Closed)
+    }
+
+    fn check_write(&mut self) -> Result<usize, StreamError> {
+        Err(StreamError::Closed)
+    }
+}
+
+#[async_trait::async_trait]
+impl Subscribe for ClosedOutputStream {
+    async fn ready(&mut self) {}
+}
+
+#[cfg(test)]
+mod test {
+    use super::*;
+    use std::time::Duration;
+    use tokio::io::{AsyncRead, AsyncReadExt, AsyncWrite, AsyncWriteExt};
+
+    // This is a gross way to handle CI running under qemu for non-x86 architectures.
+    #[cfg(not(target_arch = "x86_64"))]
+    const TEST_ITERATIONS: usize = 10;
+
+    #[cfg(target_arch = "x86_64")]
+    const TEST_ITERATIONS: usize = 100;
+
+    async fn resolves_immediately<F, O>(fut: F) -> O
+    where
+        F: futures::Future<Output = O>,
+    {
+        // The input `fut` should resolve immediately, but in case it
+        // accidentally doesn't don't hang the test indefinitely. Provide a
+        // generous timeout to account for CI sensitivity and various systems.
+        tokio::time::timeout(Duration::from_secs(2), fut)
+            .await
+            .expect("operation timed out")
+    }
+
+    async fn never_resolves<F: futures::Future>(fut: F) {
+        // The input `fut` should never resolve, so only give it a small window
+        // of budget before we time out. If `fut` is actually resolved this
+        // should show up as a flaky test.
+        tokio::time::timeout(Duration::from_millis(10), fut)
+            .await
+            .err()
+            .expect("operation should time out");
+    }
+
+    pub fn simplex(size: usize) -> (impl AsyncRead, impl AsyncWrite) {
+        let (a, b) = tokio::io::duplex(size);
+        let (_read_half, write_half) = tokio::io::split(a);
+        let (read_half, _write_half) = tokio::io::split(b);
+        (read_half, write_half)
+    }
+
+    #[test_log::test(tokio::test(flavor = "multi_thread"))]
+    async fn empty_read_stream() {
+        let mut reader = AsyncReadStream::new(tokio::io::empty());
+
+        // In a multi-threaded context, the value of state is not deterministic -- the spawned
+        // reader task may run on a different thread.
+        match reader.read(10) {
+            // The reader task ran before we tried to read, and noticed that the input was empty.
+            Err(StreamError::Closed) => {}
+
+            // The reader task hasn't run yet. Call `ready` to await and fill the buffer.
+            Ok(bs) => {
+                assert!(bs.is_empty());
+                resolves_immediately(reader.ready()).await;
+                assert!(matches!(reader.read(0), Err(StreamError::Closed)));
+            }
+            res => panic!("unexpected: {res:?}"),
+        }
+    }
+
+    #[test_log::test(tokio::test(flavor = "multi_thread"))]
+    async fn infinite_read_stream() {
+        let mut reader = AsyncReadStream::new(tokio::io::repeat(0));
+
+        let bs = reader.read(10).unwrap();
+        if bs.is_empty() {
+            // Reader task hasn't run yet. Call `ready` to await and fill the buffer.
+            resolves_immediately(reader.ready()).await;
+            // Now a read should succeed
+            let bs = reader.read(10).unwrap();
+            assert_eq!(bs.len(), 10);
+        } else {
+            assert_eq!(bs.len(), 10);
+        }
+
+        // Subsequent reads should succeed
+        let bs = reader.read(10).unwrap();
+        assert_eq!(bs.len(), 10);
+
+        // Even 0-length reads should succeed and show its open
+        let bs = reader.read(0).unwrap();
+        assert_eq!(bs.len(), 0);
+    }
+
+    async fn finite_async_reader(contents: &[u8]) -> impl AsyncRead + Send + 'static {
+        let (r, mut w) = simplex(contents.len());
+        w.write_all(contents).await.unwrap();
+        r
+    }
+
+    #[test_log::test(tokio::test(flavor = "multi_thread"))]
+    async fn finite_read_stream() {
+        let mut reader = AsyncReadStream::new(finite_async_reader(&[1; 123]).await);
+
+        let bs = reader.read(123).unwrap();
+        if bs.is_empty() {
+            // Reader task hasn't run yet. Call `ready` to await and fill the buffer.
+            resolves_immediately(reader.ready()).await;
+            // Now a read should succeed
+            let bs = reader.read(123).unwrap();
+            assert_eq!(bs.len(), 123);
+        } else {
+            assert_eq!(bs.len(), 123);
+        }
+
+        // The AsyncRead's should be empty now, but we have a race where the reader task hasn't
+        // yet send that to the AsyncReadStream.
+        match reader.read(0) {
+            Err(StreamError::Closed) => {} // Correct!
+            Ok(bs) => {
+                assert!(bs.is_empty());
+                // Need to await to give this side time to catch up
+                resolves_immediately(reader.ready()).await;
+                // Now a read should show closed
+                assert!(matches!(reader.read(0), Err(StreamError::Closed)));
+            }
+            res => panic!("unexpected: {res:?}"),
+        }
+    }
+
+    #[test_log::test(tokio::test(flavor = "multi_thread"))]
+    // Test that you can write items into the stream, and they get read out in the order they were
+    // written, with the proper indications of readiness for reading:
+    async fn multiple_chunks_read_stream() {
+        let (r, mut w) = simplex(1024);
+        let mut reader = AsyncReadStream::new(r);
+
+        w.write_all(&[123]).await.unwrap();
+
+        let bs = reader.read(1).unwrap();
+        if bs.is_empty() {
+            // Reader task hasn't run yet. Call `ready` to await and fill the buffer.
+            resolves_immediately(reader.ready()).await;
+            // Now a read should succeed
+            let bs = reader.read(1).unwrap();
+            assert_eq!(*bs, [123u8]);
+        } else {
+            assert_eq!(*bs, [123u8]);
+        }
+
+        // The stream should be empty and open now:
+        let bs = reader.read(1).unwrap();
+        assert!(bs.is_empty());
+
+        // We can wait on readiness and it will time out:
+        never_resolves(reader.ready()).await;
+
+        // Still open and empty:
+        let bs = reader.read(1).unwrap();
+        assert!(bs.is_empty());
+
+        // Put something else in the stream:
+        w.write_all(&[45]).await.unwrap();
+
+        // Wait readiness (yes we could possibly win the race and read it out faster, leaving that
+        // out of the test for simplicity)
+        resolves_immediately(reader.ready()).await;
+
+        // read the something else back out:
+        let bs = reader.read(1).unwrap();
+        assert_eq!(*bs, [45u8]);
+
+        // nothing else in there:
+        let bs = reader.read(1).unwrap();
+        assert!(bs.is_empty());
+
+        // We can wait on readiness and it will time out:
+        never_resolves(reader.ready()).await;
+
+        // nothing else in there:
+        let bs = reader.read(1).unwrap();
+        assert!(bs.is_empty());
+
+        // Now close the pipe:
+        drop(w);
+
+        // Wait readiness (yes we could possibly win the race and read it out faster, leaving that
+        // out of the test for simplicity)
+        resolves_immediately(reader.ready()).await;
+
+        // empty and now closed:
+        assert!(matches!(reader.read(1), Err(StreamError::Closed)));
+    }
+
+    #[test_log::test(tokio::test(flavor = "multi_thread"))]
+    // At the moment we are restricting AsyncReadStream from buffering more than 4k. This isn't a
+    // suitable design for all applications, and we will probably make a knob or change the
+    // behavior at some point, but this test shows the behavior as it is implemented:
+    async fn backpressure_read_stream() {
+        let (r, mut w) = simplex(16 * 1024); // Make sure this buffer isn't a bottleneck
+        let mut reader = AsyncReadStream::new(r);
+
+        let writer_task = tokio::task::spawn(async move {
+            // Write twice as much as we can buffer up in an AsyncReadStream:
+            w.write_all(&[123; 8192]).await.unwrap();
+            w
+        });
+
+        resolves_immediately(reader.ready()).await;
+
+        // Now we expect the reader task has sent 4k from the stream to the reader.
+        // Try to read out one bigger than the buffer available:
+        let bs = reader.read(4097).unwrap();
+        assert_eq!(bs.len(), 4096);
+
+        // Allow the crank to turn more:
+        resolves_immediately(reader.ready()).await;
+
+        // Again we expect the reader task has sent 4k from the stream to the reader.
+        // Try to read out one bigger than the buffer available:
+        let bs = reader.read(4097).unwrap();
+        assert_eq!(bs.len(), 4096);
+
+        // The writer task is now finished - join with it:
+        let w = resolves_immediately(writer_task).await;
+
+        // And close the pipe:
+        drop(w);
+
+        // Allow the crank to turn more:
+        resolves_immediately(reader.ready()).await;
+
+        // Now we expect the reader to be empty, and the stream closed:
+        assert!(matches!(reader.read(4097), Err(StreamError::Closed)));
+    }
+
+    #[test_log::test(test_log::test(tokio::test(flavor = "multi_thread")))]
+    async fn sink_write_stream() {
+        let mut writer = AsyncWriteStream::new(2048, tokio::io::sink());
+        let chunk = Bytes::from_static(&[0; 1024]);
+
+        let readiness = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write_ready does not trap");
+        assert_eq!(readiness, 2048);
+        // I can write whatever:
+        writer.write(chunk.clone()).expect("write does not error");
+
+        // This may consume 1k of the buffer:
+        let readiness = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write_ready does not trap");
+        assert!(
+            readiness == 1024 || readiness == 2048,
+            "readiness should be 1024 or 2048, got {readiness}"
+        );
+
+        if readiness == 1024 {
+            writer.write(chunk.clone()).expect("write does not error");
+
+            let readiness = resolves_immediately(writer.write_ready())
+                .await
+                .expect("write_ready does not trap");
+            assert!(
+                readiness == 1024 || readiness == 2048,
+                "readiness should be 1024 or 2048, got {readiness}"
+            );
+        }
+    }
+
+    #[test_log::test(tokio::test(flavor = "multi_thread"))]
+    async fn closed_write_stream() {
+        // Run many times because the test is nondeterministic:
+        for n in 0..TEST_ITERATIONS {
+            closed_write_stream_(n).await
+        }
+    }
+    #[tracing::instrument]
+    async fn closed_write_stream_(n: usize) {
+        let (reader, writer) = simplex(1);
+        let mut writer = AsyncWriteStream::new(1024, writer);
+
+        // Drop the reader to allow the worker to transition to the closed state eventually.
+        drop(reader);
+
+        // First the api is going to report the last operation failed, then subsequently
+        // it will be reported as closed. We set this flag once we see LastOperationFailed.
+        let mut should_be_closed = false;
+
+        // Write some data to the stream to ensure we have data that cannot be flushed.
+        let chunk = Bytes::from_static(&[0; 1]);
+        writer
+            .write(chunk.clone())
+            .expect("first write should succeed");
+
+        // The rest of this test should be valid whether or not we check write readiness:
+        let mut write_ready_res = None;
+        if n % 2 == 0 {
+            let r = resolves_immediately(writer.write_ready()).await;
+            // Check write readiness:
+            match r {
+                // worker hasn't processed write yet:
+                Ok(1023) => {}
+                // worker reports failure:
+                Err(StreamError::LastOperationFailed(_)) => {
+                    tracing::debug!("discovered stream failure in first write_ready");
+                    should_be_closed = true;
+                }
+                r => panic!("unexpected write_ready: {r:?}"),
+            }
+            write_ready_res = Some(r);
+        }
+
+        // When we drop the simplex reader, that causes the simplex writer to return BrokenPipe on
+        // its write. Now that the buffering crank has turned, our next write will give BrokenPipe.
+        let flush_res = writer.flush();
+        match flush_res {
+            // worker reports failure:
+            Err(StreamError::LastOperationFailed(_)) => {
+                tracing::debug!("discovered stream failure trying to flush");
+                assert!(!should_be_closed);
+                should_be_closed = true;
+            }
+            // Already reported failure, now closed
+            Err(StreamError::Closed) => {
+                assert!(
+                    should_be_closed,
+                    "expected a LastOperationFailed before we see Closed. {write_ready_res:?}"
+                );
+            }
+            // Also possible the worker hasn't processed write yet:
+            Ok(()) => {}
+            Err(e) => panic!("unexpected flush error: {e:?} {write_ready_res:?}"),
+        }
+
+        // Waiting for the flush to complete should always indicate that the channel has been
+        // closed.
+        match resolves_immediately(writer.write_ready()).await {
+            // worker reports failure:
+            Err(StreamError::LastOperationFailed(_)) => {
+                tracing::debug!("discovered stream failure trying to flush");
+                assert!(!should_be_closed);
+            }
+            // Already reported failure, now closed
+            Err(StreamError::Closed) => {
+                assert!(should_be_closed);
+            }
+            r => {
+                panic!("stream should be reported closed by the end of write_ready after flush, got {r:?}. {write_ready_res:?} {flush_res:?}")
+            }
+        }
+    }
+
+    #[test_log::test(tokio::test(flavor = "multi_thread"))]
+    async fn multiple_chunks_write_stream() {
+        // Run many times because the test is nondeterministic:
+        for n in 0..TEST_ITERATIONS {
+            multiple_chunks_write_stream_aux(n).await
+        }
+    }
+    #[tracing::instrument]
+    async fn multiple_chunks_write_stream_aux(_: usize) {
+        use std::ops::Deref;
+
+        let (mut reader, writer) = simplex(1024);
+        let mut writer = AsyncWriteStream::new(1024, writer);
+
+        // Write a chunk:
+        let chunk = Bytes::from_static(&[123; 1]);
+
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write should be ready");
+        assert_eq!(permit, 1024);
+
+        writer.write(chunk.clone()).expect("write does not trap");
+
+        // At this point the message will either be waiting for the worker to process the write, or
+        // it will be buffered in the simplex channel.
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write should be ready");
+        assert!(matches!(permit, 1023 | 1024));
+
+        let mut read_buf = vec![0; chunk.len()];
+        let read_len = reader.read_exact(&mut read_buf).await.unwrap();
+        assert_eq!(read_len, chunk.len());
+        assert_eq!(read_buf.as_slice(), chunk.deref());
+
+        // Write a second, different chunk:
+        let chunk2 = Bytes::from_static(&[45; 1]);
+
+        // We're only guaranteed to see a consistent write budget if we flush.
+        writer.flush().expect("channel is still alive");
+
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write should be ready");
+        assert_eq!(permit, 1024);
+
+        writer.write(chunk2.clone()).expect("write does not trap");
+
+        // At this point the message will either be waiting for the worker to process the write, or
+        // it will be buffered in the simplex channel.
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write should be ready");
+        assert!(matches!(permit, 1023 | 1024));
+
+        let mut read2_buf = vec![0; chunk2.len()];
+        let read2_len = reader.read_exact(&mut read2_buf).await.unwrap();
+        assert_eq!(read2_len, chunk2.len());
+        assert_eq!(read2_buf.as_slice(), chunk2.deref());
+
+        // We're only guaranteed to see a consistent write budget if we flush.
+        writer.flush().expect("channel is still alive");
+
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write should be ready");
+        assert_eq!(permit, 1024);
+    }
+
+    #[test_log::test(tokio::test(flavor = "multi_thread"))]
+    async fn backpressure_write_stream() {
+        // Run many times because the test is nondeterministic:
+        for n in 0..TEST_ITERATIONS {
+            backpressure_write_stream_aux(n).await
+        }
+    }
+    #[tracing::instrument]
+    async fn backpressure_write_stream_aux(_: usize) {
+        use futures::future::poll_immediate;
+
+        // The channel can buffer up to 1k, plus another 1k in the stream, before not
+        // accepting more input:
+        let (mut reader, writer) = simplex(1024);
+        let mut writer = AsyncWriteStream::new(1024, writer);
+
+        let chunk = Bytes::from_static(&[0; 1024]);
+
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write should be ready");
+        assert_eq!(permit, 1024);
+
+        writer.write(chunk.clone()).expect("write succeeds");
+
+        // We might still be waiting for the worker to process the message, or the worker may have
+        // processed it and released all the budget back to us.
+        let permit = poll_immediate(writer.write_ready()).await;
+        assert!(matches!(permit, None | Some(Ok(1024))));
+
+        // Given a little time, the worker will process the message and release all the budget
+        // back.
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write should be ready");
+        assert_eq!(permit, 1024);
+
+        // Now fill the buffer between here and the writer task. This should always indicate
+        // back-pressure because now both buffers (simplex and worker) are full.
+        writer.write(chunk.clone()).expect("write does not trap");
+
+        // Try shoving even more down there, and it shouldn't accept more input:
+        writer
+            .write(chunk.clone())
+            .err()
+            .expect("unpermitted write does trap");
+
+        // No amount of waiting will resolve the situation, as nothing is emptying the simplex
+        // buffer.
+        never_resolves(writer.write_ready()).await;
+
+        // There is 2k buffered between the simplex and worker buffers. I should be able to read
+        // all of it out:
+        let mut buf = [0; 2048];
+        reader.read_exact(&mut buf).await.unwrap();
+
+        // and no more:
+        never_resolves(reader.read(&mut buf)).await;
+
+        // Now the backpressure should be cleared, and an additional write should be accepted.
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("ready is ok");
+        assert_eq!(permit, 1024);
+
+        // and the write succeeds:
+        writer.write(chunk.clone()).expect("write does not trap");
+    }
+
+    #[test_log::test(tokio::test(flavor = "multi_thread"))]
+    async fn backpressure_write_stream_with_flush() {
+        for n in 0..TEST_ITERATIONS {
+            backpressure_write_stream_with_flush_aux(n).await;
+        }
+    }
+
+    async fn backpressure_write_stream_with_flush_aux(_: usize) {
+        // The channel can buffer up to 1k, plus another 1k in the stream, before not
+        // accepting more input:
+        let (mut reader, writer) = simplex(1024);
+        let mut writer = AsyncWriteStream::new(1024, writer);
+
+        let chunk = Bytes::from_static(&[0; 1024]);
+
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write should be ready");
+        assert_eq!(permit, 1024);
+
+        writer.write(chunk.clone()).expect("write succeeds");
+
+        writer.flush().expect("flush succeeds");
+
+        // Waiting for write_ready to resolve after a flush should always show that we have the
+        // full budget available, as the message will have flushed to the simplex channel.
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("write_ready succeeds");
+        assert_eq!(permit, 1024);
+
+        // Write enough to fill the simplex buffer:
+        writer.write(chunk.clone()).expect("write does not trap");
+
+        // Writes should be refused until this flush succeeds.
+        writer.flush().expect("flush succeeds");
+
+        // Try shoving even more down there, and it shouldn't accept more input:
+        writer
+            .write(chunk.clone())
+            .err()
+            .expect("unpermitted write does trap");
+
+        // No amount of waiting will resolve the situation, as nothing is emptying the simplex
+        // buffer.
+        never_resolves(writer.write_ready()).await;
+
+        // There is 2k buffered between the simplex and worker buffers. I should be able to read
+        // all of it out:
+        let mut buf = [0; 2048];
+        reader.read_exact(&mut buf).await.unwrap();
+
+        // and no more:
+        never_resolves(reader.read(&mut buf)).await;
+
+        // Now the backpressure should be cleared, and an additional write should be accepted.
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("ready is ok");
+        assert_eq!(permit, 1024);
+
+        // and the write succeeds:
+        writer.write(chunk.clone()).expect("write does not trap");
+
+        writer.flush().expect("flush succeeds");
+
+        let permit = resolves_immediately(writer.write_ready())
+            .await
+            .expect("ready is ok");
+        assert_eq!(permit, 1024);
+    }
+}