incoming value size returns a result

Signed-off-by: Jiaxiao Zhou (Mossaka) <[email protected]>

Author: Mossaka

README.md

@@ -112,7 +112,8 @@ This proposal was inspired by Dapr's [State API]
 [State API](https://docs.dapr.io/developing-applications/building-blocks/state-management/)
 
 ### Change log
-
+- 2023-12-19:
+  - Changed the `size` to `incoming-value-size` and it's signature
 - 2023-11-30: 
   - Changed the `get` and `get-many` and `keys` signatures
   - Updated comments in all the interfaces.

keyvalue-handle-watch.md

@@ -501,13 +501,16 @@ to the output-stream defined in the `wasi-io` interface.
 #### <a name="incoming_value">`type incoming-value`</a>
 `u32`
 <p>A incoming-value is a wrapper around a value. It provides a way to read the value
-from the input-stream defined in the `wasi-io` interface.
+from the `input-stream` defined in the `wasi-io` interface.
 <p>The incoming-value provides two ways to consume the value:</p>
 <ol>
 <li><a href="#incoming_value_consume_sync"><code>incoming-value-consume-sync</code></a> consumes the value synchronously and returns the
-value as a list of bytes.</li>
+value as a <code>list&lt;u8&gt;</code>.</li>
 <li><a href="#incoming_value_consume_async"><code>incoming-value-consume-async</code></a> consumes the value asynchronously and returns the
-value as an input-stream.</li>
+value as an <a href="#input_stream"><code>input-stream</code></a>.
+In addition, it provides a <a href="#incoming_value_size"><code>incoming-value-size</code></a> function to get the size of the value.
+This is useful when the value is large and the caller wants to allocate a buffer of
+the right size to consume the value.</li>
 </ol>
 <h4><a name="incoming_value_async_body"><code>type incoming-value-async-body</code></a></h4>
 <p><a href="#input_stream"><a href="#input_stream"><code>input-stream</code></a></a></p>
@@ -523,6 +526,8 @@ value as an input-stream.</li>
 <li><a name="drop_bucket.bucket"><a href="#bucket"><code>bucket</code></a></a>: <a href="#bucket"><a href="#bucket"><code>bucket</code></a></a></li>
 </ul>
 <h4><a name="open_bucket"><code>open-bucket: func</code></a></h4>
+<p>Opens a bucket with the given name.</p>
+<p>If any error occurs, including if the bucket does not exist, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="open_bucket.name"><code>name</code></a>: <code>string</code></li>
@@ -542,6 +547,8 @@ value as an input-stream.</li>
 <li><a name="new_outgoing_value.0"></a> <a href="#outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a></li>
 </ul>
 <h4><a name="outgoing_value_write_body_async"><code>outgoing-value-write-body-async: func</code></a></h4>
+<p>Writes the value to the output-stream asynchronously.
+If any other error occurs, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="outgoing_value_write_body_async.outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a>: <a href="#outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a></li>
@@ -551,6 +558,8 @@ value as an input-stream.</li>
 <li><a name="outgoing_value_write_body_async.0"></a> result&lt;own&lt;<a href="#outgoing_value_body_async"><a href="#outgoing_value_body_async"><code>outgoing-value-body-async</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="outgoing_value_write_body_sync"><code>outgoing-value-write-body-sync: func</code></a></h4>
+<p>Writes the value to the output-stream synchronously.
+If any other error occurs, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="outgoing_value_write_body_sync.outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a>: <a href="#outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a></li>
@@ -566,6 +575,8 @@ value as an input-stream.</li>
 <li><a name="drop_incoming_value.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
 </ul>
 <h4><a name="incoming_value_consume_sync"><code>incoming-value-consume-sync: func</code></a></h4>
+<p>Consumes the value synchronously and returns the value as a list of bytes.
+If any other error occurs, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="incoming_value_consume_sync.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
@@ -575,6 +586,8 @@ value as an input-stream.</li>
 <li><a name="incoming_value_consume_sync.0"></a> result&lt;<a href="#incoming_value_sync_body"><a href="#incoming_value_sync_body"><code>incoming-value-sync-body</code></a></a>, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="incoming_value_consume_async"><code>incoming-value-consume-async: func</code></a></h4>
+<p>Consumes the value asynchronously and returns the value as an <a href="#input_stream"><code>input-stream</code></a>.
+If any other error occurs, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="incoming_value_consume_async.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
@@ -583,14 +596,16 @@ value as an input-stream.</li>
 <ul>
 <li><a name="incoming_value_consume_async.0"></a> result&lt;own&lt;<a href="#incoming_value_async_body"><a href="#incoming_value_async_body"><code>incoming-value-async-body</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
-<h4><a name="size"><code>size: func</code></a></h4>
+<h4><a name="incoming_value_size"><code>incoming-value-size: func</code></a></h4>
+<p>The size of the value in bytes.
+If the size is unknown or unavailable, this function returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
-<li><a name="size.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
+<li><a name="incoming_value_size.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="size.0"></a> <code>u64</code></li>
+<li><a name="incoming_value_size.0"></a> result&lt;<code>u64</code>, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
 <h2><a name="wasi:keyvalue_readwrite">Import interface wasi:keyvalue/readwrite</a></h2>
 <p>A keyvalue interface that provides simple read and write operations.</p>

keyvalue.md

@@ -504,13 +504,16 @@ to the output-stream defined in the `wasi-io` interface.
 #### <a name="incoming_value">`type incoming-value`</a>
 `u32`
 <p>A incoming-value is a wrapper around a value. It provides a way to read the value
-from the input-stream defined in the `wasi-io` interface.
+from the `input-stream` defined in the `wasi-io` interface.
 <p>The incoming-value provides two ways to consume the value:</p>
 <ol>
 <li><a href="#incoming_value_consume_sync"><code>incoming-value-consume-sync</code></a> consumes the value synchronously and returns the
-value as a list of bytes.</li>
+value as a <code>list&lt;u8&gt;</code>.</li>
 <li><a href="#incoming_value_consume_async"><code>incoming-value-consume-async</code></a> consumes the value asynchronously and returns the
-value as an input-stream.</li>
+value as an <a href="#input_stream"><code>input-stream</code></a>.
+In addition, it provides a <a href="#incoming_value_size"><code>incoming-value-size</code></a> function to get the size of the value.
+This is useful when the value is large and the caller wants to allocate a buffer of
+the right size to consume the value.</li>
 </ol>
 <h4><a name="incoming_value_async_body"><code>type incoming-value-async-body</code></a></h4>
 <p><a href="#input_stream"><a href="#input_stream"><code>input-stream</code></a></a></p>
@@ -526,6 +529,8 @@ value as an input-stream.</li>
 <li><a name="drop_bucket.bucket"><a href="#bucket"><code>bucket</code></a></a>: <a href="#bucket"><a href="#bucket"><code>bucket</code></a></a></li>
 </ul>
 <h4><a name="open_bucket"><code>open-bucket: func</code></a></h4>
+<p>Opens a bucket with the given name.</p>
+<p>If any error occurs, including if the bucket does not exist, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="open_bucket.name"><code>name</code></a>: <code>string</code></li>
@@ -545,6 +550,8 @@ value as an input-stream.</li>
 <li><a name="new_outgoing_value.0"></a> <a href="#outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a></li>
 </ul>
 <h4><a name="outgoing_value_write_body_async"><code>outgoing-value-write-body-async: func</code></a></h4>
+<p>Writes the value to the output-stream asynchronously.
+If any other error occurs, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="outgoing_value_write_body_async.outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a>: <a href="#outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a></li>
@@ -554,6 +561,8 @@ value as an input-stream.</li>
 <li><a name="outgoing_value_write_body_async.0"></a> result&lt;own&lt;<a href="#outgoing_value_body_async"><a href="#outgoing_value_body_async"><code>outgoing-value-body-async</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="outgoing_value_write_body_sync"><code>outgoing-value-write-body-sync: func</code></a></h4>
+<p>Writes the value to the output-stream synchronously.
+If any other error occurs, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="outgoing_value_write_body_sync.outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a>: <a href="#outgoing_value"><a href="#outgoing_value"><code>outgoing-value</code></a></a></li>
@@ -569,6 +578,8 @@ value as an input-stream.</li>
 <li><a name="drop_incoming_value.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
 </ul>
 <h4><a name="incoming_value_consume_sync"><code>incoming-value-consume-sync: func</code></a></h4>
+<p>Consumes the value synchronously and returns the value as a list of bytes.
+If any other error occurs, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="incoming_value_consume_sync.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
@@ -578,6 +589,8 @@ value as an input-stream.</li>
 <li><a name="incoming_value_consume_sync.0"></a> result&lt;<a href="#incoming_value_sync_body"><a href="#incoming_value_sync_body"><code>incoming-value-sync-body</code></a></a>, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="incoming_value_consume_async"><code>incoming-value-consume-async: func</code></a></h4>
+<p>Consumes the value asynchronously and returns the value as an <a href="#input_stream"><code>input-stream</code></a>.
+If any other error occurs, it returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="incoming_value_consume_async.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
@@ -586,14 +599,16 @@ value as an input-stream.</li>
 <ul>
 <li><a name="incoming_value_consume_async.0"></a> result&lt;own&lt;<a href="#incoming_value_async_body"><a href="#incoming_value_async_body"><code>incoming-value-async-body</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
-<h4><a name="size"><code>size: func</code></a></h4>
+<h4><a name="incoming_value_size"><code>incoming-value-size: func</code></a></h4>
+<p>The size of the value in bytes.
+If the size is unknown or unavailable, this function returns an <code>Err(error)</code>.</p>
 <h5>Params</h5>
 <ul>
-<li><a name="size.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
+<li><a name="incoming_value_size.incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a>: <a href="#incoming_value"><a href="#incoming_value"><code>incoming-value</code></a></a></li>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="size.0"></a> <code>u64</code></li>
+<li><a name="incoming_value_size.0"></a> result&lt;<code>u64</code>, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
 <h2><a name="wasi:keyvalue_readwrite">Import interface wasi:keyvalue/readwrite</a></h2>
 <p>A keyvalue interface that provides simple read and write operations.</p>

wit/types.wit

@@ -18,6 +18,9 @@ interface types {
 	// Soon: switch to `resource bucket { ... }`
 	type bucket = u32;
 	drop-bucket: func(bucket: bucket);
+	/// Opens a bucket with the given name.
+	/// 
+	/// If any error occurs, including if the bucket does not exist, it returns an `Err(error)`.
 	open-bucket: func(name: string) -> result<bucket, error>;
 
 	/// A key is a unique identifier for a value in a bucket. The key is used to
@@ -35,23 +38,36 @@ interface types {
 	type outgoing-value-body-sync = list<u8>;
 	drop-outgoing-value: func(outgoing-value: outgoing-value);
 	new-outgoing-value: func() -> outgoing-value;
+	/// Writes the value to the output-stream asynchronously.
+	/// If any other error occurs, it returns an `Err(error)`.
 	outgoing-value-write-body-async: func(outgoing-value: outgoing-value) -> result<outgoing-value-body-async, error>;
+	/// Writes the value to the output-stream synchronously.
+	/// If any other error occurs, it returns an `Err(error)`.
 	outgoing-value-write-body-sync: func(outgoing-value: outgoing-value, value: outgoing-value-body-sync) -> result<_, error>;
 
 	/// A incoming-value is a wrapper around a value. It provides a way to read the value
-	/// from the input-stream defined in the `wasi-io` interface.
+	/// from the `input-stream` defined in the `wasi-io` interface.
 	///
 	/// The incoming-value provides two ways to consume the value:
 	/// 1. `incoming-value-consume-sync` consumes the value synchronously and returns the
-	///    value as a list of bytes.
+	///    value as a `list<u8>`.
 	/// 2. `incoming-value-consume-async` consumes the value asynchronously and returns the
-	///    value as an input-stream.
+	///    value as an `input-stream`.
+	/// In addition, it provides a `incoming-value-size` function to get the size of the value.
+	/// This is useful when the value is large and the caller wants to allocate a buffer of
+	/// the right size to consume the value.
 	// Soon: switch to `resource incoming-value { ... }`
 	type incoming-value = u32;
 	type incoming-value-async-body = input-stream;
 	type incoming-value-sync-body = list<u8>;
 	drop-incoming-value: func(incoming-value: incoming-value);
+	/// Consumes the value synchronously and returns the value as a list of bytes.
+	/// If any other error occurs, it returns an `Err(error)`.
 	incoming-value-consume-sync: func(incoming-value: incoming-value) -> result<incoming-value-sync-body, error>;
+	/// Consumes the value asynchronously and returns the value as an `input-stream`.
+	/// If any other error occurs, it returns an `Err(error)`.
 	incoming-value-consume-async: func(incoming-value: incoming-value) -> result<incoming-value-async-body, error>;
-	size: func(incoming-value: incoming-value) -> u64;
+	/// The size of the value in bytes.
+	/// If the size is unknown or unavailable, this function returns an `Err(error)`.
+	incoming-value-size: func(incoming-value: incoming-value) -> result<u64, error>;
 }