Specify that text in streams is transmitted in UTF-8. (#66)

* Specify that text in streams is transmitted in UTF-8.

The wasi-io stream types are byte streams capable of transmitting any
data encoding, including any text encoding.

However, sometimes an implementation knows the a particular data source
or destination uses text data of a particular encoding, for example in
an implementation of the stdio streams on Windows. In these cases, it's
useful to have the implementation transcode the data, so that guest code
doesn't need to be aware of where the data is coming from or going to,
and have extra code for performing transcoding itself.

Specify UTF-8 as the encoding to use, when transmitting data from
sources or to destinations where the implementation knows the data is
in a text format.

* Update imports.md.

Author: sunfishcode

.github/workflows/main.yml

@@ -10,5 +10,5 @@ jobs:
     name: Check ABI files are up-to-date
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: WebAssembly/wit-abi-up-to-date@v16
+    - uses: actions/checkout@v4
+    - uses: WebAssembly/wit-abi-up-to-date@v17

imports.md

@@ -12,7 +12,21 @@
 <hr />
 <h3>Types</h3>
 <h4><a name="error"><code>resource error</code></a></h4>
-<hr />
+<p>A resource which represents some error information.</p>
+<p>The only method provided by this resource is <code>to-debug-string</code>,
+which provides some human-readable information about the error.</p>
+<p>In the <code>wasi:io</code> package, this resource is returned through the
+<code>wasi:io/streams/stream-error</code> type.</p>
+<p>To provide more specific error information, other interfaces may
+provide functions to further &quot;downcast&quot; this error into more specific
+error information. For example, <a href="#error"><code>error</code></a>s returned in streams derived
+from filesystem types to be described using the filesystem's own
+error-code type, using the function
+<code>wasi:filesystem/types/filesystem-error-code</code>, which takes a parameter
+<code>borrow&lt;error&gt;</code> and returns
+<code>option&lt;wasi:filesystem/types/error-code&gt;</code>.</p>
+<h2>The set of functions which can &quot;downcast&quot; an <a href="#error"><code>error</code></a> into a more
+concrete type is open.</h2>
 <h3>Functions</h3>
 <h4><a name="method_error.to_debug_string"><code>[method]error.to-debug-string: func</code></a></h4>
 <p>Returns a string that is suitable to assist humans in debugging
@@ -35,7 +49,7 @@ at once.</p>
 <hr />
 <h3>Types</h3>
 <h4><a name="pollable"><code>resource pollable</code></a></h4>
-<hr />
+<h2><a href="#pollable"><code>pollable</code></a> represents a single I/O event which may be ready, or not.</h2>
 <h3>Functions</h3>
 <h4><a name="method_pollable.ready"><code>[method]pollable.ready: func</code></a></h4>
 <p>Return the readiness of a pollable. This function never blocks.</p>
@@ -109,11 +123,28 @@ future operations.
 </li>
 </ul>
 <h4><a name="input_stream"><code>resource input-stream</code></a></h4>
+<p>An input bytestream.</p>
+<p><a href="#input_stream"><code>input-stream</code></a>s are <em>non-blocking</em> to the extent practical on underlying
+platforms. I/O operations always return promptly; if fewer bytes are
+promptly available than requested, they return the number of bytes promptly
+available, which could even be zero. To wait for data to be available,
+use 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>.</p>
 <h4><a name="output_stream"><code>resource output-stream</code></a></h4>
-<hr />
+<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
+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>
 <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>
+<p>When the source of a <code>read</code> is binary data, the bytes from the source
+are returned verbatim. When the source of a <code>read</code> is known to the
+implementation to be text, bytes containing the UTF-8 encoding of the
+text are returned.</p>
 <p>This function returns a list of bytes containing the read data,
 when successful. The returned list will contain up to <code>len</code> bytes;
 it may return fewer than requested, but not more. The list is
@@ -209,6 +240,11 @@ error.</p>
 </ul>
 <h4><a name="method_output_stream.write"><code>[method]output-stream.write: func</code></a></h4>
 <p>Perform a write. This function never blocks.</p>
+<p>When the destination of a <code>write</code> is binary data, the bytes from
+<code>contents</code> are written verbatim. When the destination of a <code>write</code> is
+known to the implementation to be text, the bytes of <code>contents</code> are
+transcoded from UTF-8 into the encoding of the destination and then
+written.</p>
 <p>Precondition: check-write gave permit of Ok(n) and contents has a
 length of less than or equal to n. Otherwise, this function will trap.</p>
 <p>returns Err(closed) without writing if the stream has closed since

wit/streams.wit

@@ -32,6 +32,11 @@ interface streams {
     resource input-stream {
         /// Perform a non-blocking read from the stream.
         ///
+        /// When the source of a `read` is binary data, the bytes from the source
+        /// are returned verbatim. When the source of a `read` is known to the
+        /// implementation to be text, bytes containing the UTF-8 encoding of the
+        /// text are returned.
+        ///
         /// This function returns a list of bytes containing the read data,
         /// when successful. The returned list will contain up to `len` bytes;
         /// it may return fewer than requested, but not more. The list is
@@ -111,6 +116,12 @@ interface streams {
 
         /// Perform a write. This function never blocks.
         ///
+        /// When the destination of a `write` is binary data, the bytes from
+        /// `contents` are written verbatim. When the destination of a `write` is
+        /// known to the implementation to be text, the bytes of `contents` are
+        /// transcoded from UTF-8 into the encoding of the destination and then
+        /// written.
+        ///
         /// Precondition: check-write gave permit of Ok(n) and contents has a
         /// length of less than or equal to n. Otherwise, this function will trap.
         ///