Add filesystem-error-code for elaborating stream.error (#137)

* wit-deps update to latest io streams.wit, which exposes `error`

* add `filesystem-error-code`, for elaborating `stream.error`

* generate markdown

imports.md

@@ -58,62 +58,55 @@ when it does, they are expected to subsume this API.</p>
 <h4><a name="pollable"><code>type pollable</code></a></h4>
 <p><a href="#pollable"><a href="#pollable"><code>pollable</code></a></a></p>
 <p>
-#### <a name="stream_status">`enum stream-status`</a>
-<p>Streams provide a sequence of data and then end; once they end, they
-no longer provide any further data.</p>
-<p>For example, a stream reading from a file ends when the stream reaches
-the end of the file. For another example, a stream reading from a
-socket ends when the socket is closed.</p>
-<h5>Enum Cases</h5>
-<ul>
-<li>
-<p><a name="stream_status.open"><code>open</code></a></p>
-<p>The stream is open and may produce further data.
-</li>
-<li>
-<p><a name="stream_status.ended"><code>ended</code></a></p>
-<p>When reading, this indicates that the stream will not produce
-further data.
-When writing, this indicates that the stream will no longer be read.
-Further writes are still permitted.
-</li>
-</ul>
-<h4><a name="input_stream"><code>resource input-stream</code></a></h4>
-<h4><a name="write_error"><code>enum write-error</code></a></h4>
-<p>An error for output-stream operations.</p>
-<p>Contrary to input-streams, a closed output-stream is reported using
-an error.</p>
-<h5>Enum Cases</h5>
+#### <a name="error">`resource error`</a>
+<h4><a name="stream_error"><code>variant stream-error</code></a></h4>
+<p>An error for input-stream and output-stream operations.</p>
+<h5>Variant Cases</h5>
 <ul>
 <li>
-<p><a name="write_error.last_operation_failed"><code>last-operation-failed</code></a></p>
+<p><a name="stream_error.last_operation_failed"><code>last-operation-failed</code></a>: own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;</p>
 <p>The last operation (a write or flush) failed before completion.
+<p>More information is available in the <a href="#error"><code>error</code></a> payload.</p>
 </li>
 <li>
-<p><a name="write_error.closed"><code>closed</code></a></p>
+<p><a name="stream_error.closed"><code>closed</code></a></p>
 <p>The stream is closed: no more input will be accepted by the
 stream. A closed output-stream will return this error on all
 future operations.
 </li>
 </ul>
+<h4><a name="input_stream"><code>resource input-stream</code></a></h4>
 <h4><a name="output_stream"><code>resource output-stream</code></a></h4>
 <hr />
 <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's suitable to assist humans in debugging this
+error.</p>
+<p>The returned string will change across platforms and hosts which
+means that parsing it, for example, would be a
+platform-compatibility hazard.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="method_error.to_debug_string.self"><code>self</code></a>: borrow&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="method_error.to_debug_string.0"></a> <code>string</code></li>
+</ul>
 <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>This function returns a list of bytes containing the data that was
-read, along with a <a href="#stream_status"><code>stream-status</code></a> which, indicates whether further
-reads are expected to produce data. The returned list will contain up to
-<code>len</code> bytes; it may return fewer than requested, but not more. An
-empty list and <code>stream-status:open</code> indicates no more data is
-available at this time, and that the pollable given by <code>subscribe</code>
-will be ready when more data is available.</p>
-<p>Once a stream has reached the end, subsequent calls to <code>read</code> or
-<code>skip</code> will always report <code>stream-status:ended</code> rather than producing more
-data.</p>
-<p>When the caller gives a <code>len</code> of 0, it represents a request to read 0
-bytes. This read should  always succeed and return an empty list and
-the current <a href="#stream_status"><code>stream-status</code></a>.</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
+empty when no bytes are available for reading at this time. The
+pollable given by <code>subscribe</code> will be ready when more bytes are
+available.</p>
+<p>This function fails with a <a href="#stream_error"><code>stream-error</code></a> when the operation
+encounters an error, giving <code>last-operation-failed</code>, or when the
+stream is closed, giving <code>closed</code>.</p>
+<p>When the caller gives a <code>len</code> of 0, it represents a request to
+read 0 bytes. If the stream is still open, this call should
+succeed and return an empty list, or otherwise fail with <code>closed</code>.</p>
 <p>The <code>len</code> parameter is a <code>u64</code>, which could represent a list of u8 which
 is not possible to allocate in wasm32, or not desirable to allocate as
 as a return value by the callee. The callee may return a list of bytes
@@ -125,38 +118,32 @@ less than <code>len</code> in size while more bytes are available for reading.</
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_input_stream.read.0"></a> result&lt;(list&lt;<code>u8</code>&gt;, <a href="#stream_status"><a href="#stream_status"><code>stream-status</code></a></a>)&gt;</li>
+<li><a name="method_input_stream.read.0"></a> result&lt;list&lt;<code>u8</code>&gt;, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="method_input_stream.blocking_read"><code>[method]input-stream.blocking-read: func</code></a></h4>
 <p>Read bytes from a stream, after blocking until at least one byte can
-be read. Except for blocking, identical to <code>read</code>.</p>
+be read. Except for blocking, behavior is identical to <code>read</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_input_stream.blocking_read.self"><code>self</code></a>: borrow&lt;<a href="#input_stream"><a href="#input_stream"><code>input-stream</code></a></a>&gt;</li>
 <li><a name="method_input_stream.blocking_read.len"><code>len</code></a>: <code>u64</code></li>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_input_stream.blocking_read.0"></a> result&lt;(list&lt;<code>u8</code>&gt;, <a href="#stream_status"><a href="#stream_status"><code>stream-status</code></a></a>)&gt;</li>
+<li><a name="method_input_stream.blocking_read.0"></a> result&lt;list&lt;<code>u8</code>&gt;, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="method_input_stream.skip"><code>[method]input-stream.skip: func</code></a></h4>
-<p>Skip bytes from a stream.</p>
-<p>This is similar to the <code>read</code> function, but avoids copying the
-bytes into the instance.</p>
-<p>Once a stream has reached the end, subsequent calls to read or
-<code>skip</code> will always report end-of-stream rather than producing more
-data.</p>
-<p>This function returns the number of bytes skipped, along with a
-<a href="#stream_status"><code>stream-status</code></a> indicating whether the end of the stream was
-reached. The returned value will be at most <code>len</code>; it may be less.</p>
+<p>Skip bytes from a stream. Returns number of bytes skipped.</p>
+<p>Behaves identical to <code>read</code>, except instead of returning a list
+of bytes, returns the number of bytes consumed from the stream.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_input_stream.skip.self"><code>self</code></a>: borrow&lt;<a href="#input_stream"><a href="#input_stream"><code>input-stream</code></a></a>&gt;</li>
 <li><a name="method_input_stream.skip.len"><code>len</code></a>: <code>u64</code></li>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_input_stream.skip.0"></a> result&lt;(<code>u64</code>, <a href="#stream_status"><a href="#stream_status"><code>stream-status</code></a></a>)&gt;</li>
+<li><a name="method_input_stream.skip.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="method_input_stream.blocking_skip"><code>[method]input-stream.blocking-skip: func</code></a></h4>
 <p>Skip bytes from a stream, after blocking until at least one byte
@@ -168,7 +155,7 @@ can be skipped. Except for blocking behavior, identical to <code>skip</code>.</p
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_input_stream.blocking_skip.0"></a> result&lt;(<code>u64</code>, <a href="#stream_status"><a href="#stream_status"><code>stream-status</code></a></a>)&gt;</li>
+<li><a name="method_input_stream.blocking_skip.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="method_input_stream.subscribe"><code>[method]input-stream.subscribe: func</code></a></h4>
 <p>Create a <a href="#pollable"><code>pollable</code></a> which will resolve once either the specified stream
@@ -199,7 +186,7 @@ error.</p>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_output_stream.check_write.0"></a> result&lt;<code>u64</code>, <a href="#write_error"><a href="#write_error"><code>write-error</code></a></a>&gt;</li>
+<li><a name="method_output_stream.check_write.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="method_output_stream.write"><code>[method]output-stream.write: func</code></a></h4>
 <p>Perform a write. This function never blocks.</p>
@@ -214,7 +201,7 @@ the last call to check-write provided a permit.</p>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_output_stream.write.0"></a> result&lt;_, <a href="#write_error"><a href="#write_error"><code>write-error</code></a></a>&gt;</li>
+<li><a name="method_output_stream.write.0"></a> result&lt;_, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="method_output_stream.blocking_write_and_flush"><code>[method]output-stream.blocking-write-and-flush: func</code></a></h4>
 <p>Perform a write of up to 4096 bytes, and then flush the stream. Block
@@ -245,7 +232,7 @@ let _ = this.check-write();         // eliding error handling
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_output_stream.blocking_write_and_flush.0"></a> result&lt;_, <a href="#write_error"><a href="#write_error"><code>write-error</code></a></a>&gt;</li>
+<li><a name="method_output_stream.blocking_write_and_flush.0"></a> result&lt;_, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="method_output_stream.flush"><code>[method]output-stream.flush: func</code></a></h4>
 <p>Request to flush buffered output. This function never blocks.</p>
@@ -262,7 +249,7 @@ flush has completed and the stream can accept more writes.</p>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_output_stream.flush.0"></a> result&lt;_, <a href="#write_error"><a href="#write_error"><code>write-error</code></a></a>&gt;</li>
+<li><a name="method_output_stream.flush.0"></a> result&lt;_, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="method_output_stream.blocking_flush"><code>[method]output-stream.blocking-flush: func</code></a></h4>
 <p>Request to flush buffered output, and block until flush completes
@@ -273,7 +260,7 @@ and stream is ready for writing again.</p>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_output_stream.blocking_flush.0"></a> result&lt;_, <a href="#write_error"><a href="#write_error"><code>write-error</code></a></a>&gt;</li>
+<li><a name="method_output_stream.blocking_flush.0"></a> result&lt;_, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="method_output_stream.subscribe"><code>[method]output-stream.subscribe: func</code></a></h4>
 <p>Create a <a href="#pollable"><code>pollable</code></a> which will resolve once the output-stream
@@ -305,7 +292,7 @@ that should be written.</p>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_output_stream.write_zeroes.0"></a> result&lt;_, <a href="#write_error"><a href="#write_error"><code>write-error</code></a></a>&gt;</li>
+<li><a name="method_output_stream.write_zeroes.0"></a> result&lt;_, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="method_output_stream.blocking_write_zeroes_and_flush"><code>[method]output-stream.blocking-write-zeroes-and-flush: func</code></a></h4>
 <p>Perform a write of up to 4096 zeroes, and then flush the stream.
@@ -336,56 +323,45 @@ let _ = this.check-write();         // eliding error handling
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_output_stream.blocking_write_zeroes_and_flush.0"></a> result&lt;_, <a href="#write_error"><a href="#write_error"><code>write-error</code></a></a>&gt;</li>
+<li><a name="method_output_stream.blocking_write_zeroes_and_flush.0"></a> result&lt;_, <a href="#stream_error"><a href="#stream_error"><code>stream-error</code></a></a>&gt;</li>
 </ul>
 <h4><a name="method_output_stream.splice"><code>[method]output-stream.splice: func</code></a></h4>
 <p>Read from one stream and write to another.</p>
+<p>The behavior of splice is equivelant to:</p>
+<ol>
+<li>calling <code>check-write</code> on the <a href="#output_stream"><code>output-stream</code></a></li>
+<li>calling <code>read</code> on the <a href="#input_stream"><code>input-stream</code></a> with the smaller of the
+<code>check-write</code> permitted length and the <code>len</code> provided to <code>splice</code></li>
+<li>calling <code>write</code> on the <a href="#output_stream"><code>output-stream</code></a> with that read data.</li>
+</ol>
+<p>Any error reported by the call to <code>check-write</code>, <code>read</code>, or
+<code>write</code> ends the splice and reports that error.</p>
 <p>This function returns the number of bytes transferred; it may be less
 than <code>len</code>.</p>
-<p>Unlike other I/O functions, this function blocks until all the data
-read from the input stream has been written to the output stream.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_output_stream.splice.self"><code>self</code></a>: borrow&lt;<a href="#output_stream"><a href="#output_stream"><code>output-stream</code></a></a>&gt;</li>
-<li><a name="method_output_stream.splice.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="method_output_stream.splice.src"><code>src</code></a>: borrow&lt;<a href="#input_stream"><a href="#input_stream"><code>input-stream</code></a></a>&gt;</li>
 <li><a name="method_output_stream.splice.len"><code>len</code></a>: <code>u64</code></li>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_output_stream.splice.0"></a> result&lt;(<code>u64</code>, <a href="#stream_status"><a href="#stream_status"><code>stream-status</code></a></a>)&gt;</li>
+<li><a name="method_output_stream.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="method_output_stream.blocking_splice"><code>[method]output-stream.blocking-splice: func</code></a></h4>
 <p>Read from one stream and write to another, with blocking.</p>
-<p>This is similar to <code>splice</code>, except that it blocks until at least
-one byte can be read.</p>
+<p>This is similar to <code>splice</code>, except that it blocks until the
+<a href="#output_stream"><code>output-stream</code></a> is ready for writing, and the <a href="#input_stream"><code>input-stream</code></a>
+is ready for reading, before performing the <code>splice</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_output_stream.blocking_splice.self"><code>self</code></a>: borrow&lt;<a href="#output_stream"><a href="#output_stream"><code>output-stream</code></a></a>&gt;</li>
-<li><a name="method_output_stream.blocking_splice.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="method_output_stream.blocking_splice.src"><code>src</code></a>: borrow&lt;<a href="#input_stream"><a href="#input_stream"><code>input-stream</code></a></a>&gt;</li>
 <li><a name="method_output_stream.blocking_splice.len"><code>len</code></a>: <code>u64</code></li>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a name="method_output_stream.blocking_splice.0"></a> result&lt;(<code>u64</code>, <a href="#stream_status"><a href="#stream_status"><code>stream-status</code></a></a>)&gt;</li>
-</ul>
-<h4><a name="method_output_stream.forward"><code>[method]output-stream.forward: func</code></a></h4>
-<p>Forward the entire contents of an input stream to an output stream.</p>
-<p>This function repeatedly reads from the input stream and writes
-the data to the output stream, until the end of the input stream
-is reached, or an error is encountered.</p>
-<p>Unlike other I/O functions, this function blocks until the end
-of the input stream is seen and all the data has been written to
-the output stream.</p>
-<p>This function returns the number of bytes transferred, and the status of
-the output stream.</p>
-<h5>Params</h5>
-<ul>
-<li><a name="method_output_stream.forward.self"><code>self</code></a>: borrow&lt;<a href="#output_stream"><a href="#output_stream"><code>output-stream</code></a></a>&gt;</li>
-<li><a name="method_output_stream.forward.src"><code>src</code></a>: own&lt;<a href="#input_stream"><a href="#input_stream"><code>input-stream</code></a></a>&gt;</li>
-</ul>
-<h5>Return values</h5>
-<ul>
-<li><a name="method_output_stream.forward.0"></a> result&lt;(<code>u64</code>, <a href="#stream_status"><a href="#stream_status"><code>stream-status</code></a></a>)&gt;</li>
+<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>
 <h2><a name="wasi:clocks_wall_clock">Import interface wasi:clocks/wall-clock</a></h2>
 <p>WASI Wall Clock is a clock API intended to let users query the current
@@ -454,6 +430,9 @@ underlying filesystem, the function fails with <a href="#error_code.not_permitte
 #### <a name="output_stream">`type output-stream`</a>
 [`output-stream`](#output_stream)
 <p>
+#### <a name="error">`type error`</a>
+[`error`](#error)
+<p>
 #### <a name="datetime">`type datetime`</a>
 [`datetime`](#datetime)
 <p>
@@ -1374,6 +1353,23 @@ to by a directory descriptor and a relative path.</p>
 <ul>
 <li><a name="method_directory_entry_stream.read_directory_entry.0"></a> result&lt;option&lt;<a href="#directory_entry"><a href="#directory_entry"><code>directory-entry</code></a></a>&gt;, <a href="#error_code"><a href="#error_code"><code>error-code</code></a></a>&gt;</li>
 </ul>
+<h4><a name="filesystem_error_code"><code>filesystem-error-code: func</code></a></h4>
+<p>Attempts to extract a filesystem-related <a href="#error_code"><code>error-code</code></a> from the stream
+<a href="#error"><code>error</code></a> provided.</p>
+<p>Stream operations which return <a href="#stream_error.last_operation_failed"><code>stream-error::last-operation-failed</code></a>
+have a payload with more information about the operation that failed.
+This payload can be passed through to this function to see if there's
+filesystem-related information about the error to return.</p>
+<p>Note that this function is fallible because not all stream-related
+errors are filesystem-related errors.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="filesystem_error_code.err"><code>err</code></a>: borrow&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="filesystem_error_code.0"></a> option&lt;<a href="#error_code"><a href="#error_code"><code>error-code</code></a></a>&gt;</li>
+</ul>
 <h2><a name="wasi:filesystem_preopens">Import interface wasi:filesystem/preopens</a></h2>
 <hr />
 <h3>Types</h3>