Add forward

Author: badeend

imports.md

@@ -132,12 +132,14 @@ use the <code>subscribe</code> function to obtain a <a href="#pollable"><code>po
 for using <code>wasi:io/poll</code>.</p>
 <h4><a name="output_stream"><code>resource output-stream</code></a></h4>
 <p>An output bytestream.</p>
-<h2><a href="#output_stream"><code>output-stream</code></a>s are <em>non-blocking</em> to the extent practical on
+<p><a href="#output_stream"><code>output-stream</code></a>s are <em>non-blocking</em> 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
 promptly, which could even be zero. To wait for the stream to be ready to
 accept data, the <code>subscribe</code> function to obtain a <a href="#pollable"><code>pollable</code></a> which can be
-polled for using <code>wasi:io/poll</code>.</h2>
+polled for using <code>wasi:io/poll</code>.</p>
+<h4><a name="future_forward_result"><code>resource future-forward-result</code></a></h4>
+<h2>Represents a future which may eventually return trailers, or an error.</h2>
 <h3>Functions</h3>
 <h4><a name="method_input_stream.read"><code>[method]input-stream.read: func</code></a></h4>
 <p>Perform a non-blocking read from the stream.</p>
@@ -418,3 +420,56 @@ is ready for reading, before performing the <code>splice</code>.</p>
 <ul>
 <li><a name="method_output_stream.blocking_splice.0"></a> result&lt;<code>u64</code>, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
 </ul>
+<h4><a name="forward"><code>forward: func</code></a></h4>
+<p>Continuously read all data from the input stream and write it to the
+output stream.</p>
+<p>Forwarding is done on a background task. The tasks runs until either
+stream closes or fails. After that, the streams are dropped and the
+returned future is resolved. Dropping the future before it has been
+resolved aborts the background task and drops the streams.</p>
+<p>The future resolves with the reason that caused the forwarding to terminate.
+In case one of the streams ended normally, this will be <a href="#stream_error.closed"><code>stream-error::closed</code></a>.</p>
+<p>This function requires exclusive access to the provided streams,
+yet it does not change the ownership structure of them. I.e. they remain
+children of their parent resources. If the parents place any lifetimes
+restrictions on their children, those continue to apply.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="forward.src"><code>src</code></a>: own&lt;<a href="#input_stream"><a href="#input_stream"><code>input-stream</code></a></a>&gt;</li>
+<li><a name="forward.dst"><code>dst</code></a>: own&lt;<a href="#output_stream"><a href="#output_stream"><code>output-stream</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="forward.0"></a> own&lt;<a href="#future_forward_result"><a href="#future_forward_result"><code>future-forward-result</code></a></a>&gt;</li>
+</ul>
+<h4><a name="method_future_forward_result.subscribe"><code>[method]future-forward-result.subscribe: func</code></a></h4>
+<p>Returns a pollable which becomes ready when either the result is
+available. When this pollable is ready, the <code>get</code> method will return
+<code>some</code>.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="method_future_forward_result.subscribe.self"><code>self</code></a>: borrow&lt;<a href="#future_forward_result"><a href="#future_forward_result"><code>future-forward-result</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="method_future_forward_result.subscribe.0"></a> own&lt;<a href="#pollable"><a href="#pollable"><code>pollable</code></a></a>&gt;</li>
+</ul>
+<h4><a name="method_future_forward_result.get"><code>[method]future-forward-result.get: func</code></a></h4>
+<p>Get the resolved value.</p>
+<p>Returns:</p>
+<ul>
+<li><code>none</code>: when the future hasn't resolved yet. Use <code>subscribe</code> to wait
+for its completion.</li>
+<li><code>some(error(_))</code>: when the future is resolved, but the result value
+has already been taken before.</li>
+<li><code>some(ok(value))</code>: when the future is ready with a value. This is
+returned only once.</li>
+</ul>
+<h5>Params</h5>
+<ul>
+<li><a name="method_future_forward_result.get.self"><code>self</code></a>: borrow&lt;<a href="#future_forward_result"><a href="#future_forward_result"><code>future-forward-result</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="method_future_forward_result.get.0"></a> option&lt;result&lt;<a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;&gt;</li>
+</ul>

wit/streams.wit

@@ -259,4 +259,40 @@ interface streams {
             len: u64,
         ) -> result<u64, stream-error>;
     }
+
+    /// Continuously read all data from the input stream and write it to the
+    /// output stream.
+    ///
+    /// Forwarding is done on a background task. The tasks runs until either
+    /// stream closes or fails. After that, the streams are dropped and the
+    /// returned future is resolved. Dropping the future before it has been
+    /// resolved aborts the background task and drops the streams.
+    ///
+    /// The future resolves with the reason that caused the forwarding to terminate.
+    /// In case one of the streams ended normally, this will be `stream-error::closed`.
+    ///
+    /// This function requires exclusive access to the provided streams,
+    /// yet it does not change the ownership structure of them. I.e. they remain
+    /// children of their parent resources. If the parents place any lifetimes
+    /// restrictions on their children, those continue to apply.
+    forward: func(src: input-stream, dst: output-stream) -> future-forward-result;
+
+    /// Represents a future which may eventually return trailers, or an error.
+    resource future-forward-result {
+        /// Returns a pollable which becomes ready when either the result is
+        /// available. When this pollable is ready, the `get` method will return
+        /// `some`.
+        subscribe: func() -> pollable;
+
+        /// Get the resolved value.
+        ///
+        /// Returns:
+        /// - `none`: when the future hasn't resolved yet. Use `subscribe` to wait
+        ///   for its completion.
+        /// - `some(error(_))`: when the future is resolved, but the result value
+        ///   has already been taken before.
+        /// - `some(ok(value))`: when the future is ready with a value. This is
+        ///   returned only once.
+        get: func() -> option<result<stream-error>>;
+    }
 }