From 18f12880524a0bca0596197ca64819b8d2147bb2 Mon Sep 17 00:00:00 2001
From: Roman Volosatovs <rvolosatovs@riseup.net>
Date: Fri, 16 Aug 2024 14:35:31 +0200
Subject: [PATCH] fix: add `outgoing-value.finish`

Without an explicit `outgoing-value.finish`, the host may not know when
the data stream has finished and when to stop writing.

Additionally, this allows for errors to be communicated to the guest,
which may have happened asynchronously

Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>
---
 imports.md    | 20 ++++++++++++++++++++
 wit/types.wit | 16 ++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/imports.md b/imports.md
index 6e50d1a..03f0a7b 100644
--- a/imports.md
+++ b/imports.md
@@ -521,6 +521,13 @@ Soon: switch to <code>resource incoming-value { ... }</code></li>
 <li><a name="static_outgoing_value.new_outgoing_value.0"></a> own&lt;<a href="#outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a>&gt;</li>
 </ul>
 <h4><a name="method_outgoing_value.outgoing_value_write_body"></a><code>[method]outgoing-value.outgoing-value-write-body: func</code></h4>
+<p>Returns a stream for writing the value contents.</p>
+<p>The returned <a href="#output_stream"><code>output-stream</code></a> is a child resource: it must be dropped
+before the parent <a href="#outgoing_value"><code>outgoing-value</code></a> resource is dropped (or finished),
+otherwise the <a href="#outgoing_value"><code>outgoing-value</code></a> drop or <code>finish</code> will trap.</p>
+<p>Returns success on the first call: the <a href="#output_stream"><code>output-stream</code></a> resource for
+this <a href="#outgoing_value"><code>outgoing-value</code></a> may be retrieved at most once. Subsequent calls
+will return error.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_outgoing_value.outgoing_value_write_body.self"></a><code>self</code>: borrow&lt;<a href="#outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a>&gt;</li>
@@ -529,6 +536,19 @@ Soon: switch to <code>resource incoming-value { ... }</code></li>
 <ul>
 <li><a name="method_outgoing_value.outgoing_value_write_body.0"></a> result&lt;own&lt;<a href="#output_stream"><a href="#output_stream"><code>output-stream</code></a></a>&gt;&gt;</li>
 </ul>
+<h4><a name="static_outgoing_value.finish"></a><code>[static]outgoing-value.finish: func</code></h4>
+<p>Finalize an outgoing value. This must be
+called to signal that the outgoing value is complete. If the <a href="#outgoing_value"><code>outgoing-value</code></a>
+is dropped without calling <code>outgoing-value.finalize</code>, the implementation
+should treat the value as corrupted.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="static_outgoing_value.finish.this"></a><code>this</code>: own&lt;<a href="#outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="static_outgoing_value.finish.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
+</ul>
 <h4><a name="static_incoming_value.incoming_value_consume_sync"></a><code>[static]incoming-value.incoming-value-consume-sync: func</code></h4>
 <h5>Params</h5>
 <ul>
diff --git a/wit/types.wit b/wit/types.wit
index 979b054..ca59724 100644
--- a/wit/types.wit
+++ b/wit/types.wit
@@ -52,7 +52,23 @@ interface types {
   // Soon: switch to `resource value { ... }`
   resource outgoing-value {
     new-outgoing-value: static func() -> outgoing-value;
+
+    /// Returns a stream for writing the value contents.
+    ///
+    /// The returned `output-stream` is a child resource: it must be dropped
+    /// before the parent `outgoing-value` resource is dropped (or finished),
+    /// otherwise the `outgoing-value` drop or `finish` will trap.
+    ///
+    /// Returns success on the first call: the `output-stream` resource for
+    /// this `outgoing-value` may be retrieved at most once. Subsequent calls
+    /// will return error.
     outgoing-value-write-body: func() -> result<output-stream>;
+
+    /// Finalize an outgoing value. This must be
+    /// called to signal that the outgoing value is complete. If the `outgoing-value`
+    /// is dropped without calling `outgoing-value.finalize`, the implementation
+    /// should treat the value as corrupted.
+    finish: static func(this: outgoing-value) -> result<_, error>;
   }
 
   /// A incoming-value is a wrapper around a value. It provides a way to read the value