From a39776e6fa21c96fb33b52bdeb89d2c8b8f4cca7 Mon Sep 17 00:00:00 2001
From: Pat Hickey <phickey@fastly.com>
Date: Fri, 10 Nov 2023 14:32:05 -0800
Subject: [PATCH] move error resource to its own interface. (#56)

* Move error resource to its own interface

Two reasons for this design change:

it is confusing having one type named stream/stream-error and another named stream/error.
this error resource seems useful outside of just streams.
Therefore, we are moving it to a separate interface error in the same package. There are no functional changes to this type.

The doc comments are now more general.

* generate markdown
---
 imports.md      | 46 ++++++++++++++++++++++++++++------------------
 wit/error.wit   | 34 ++++++++++++++++++++++++++++++++++
 wit/streams.wit | 21 +--------------------
 3 files changed, 63 insertions(+), 38 deletions(-)
 create mode 100644 wit/error.wit

diff --git a/imports.md b/imports.md
index e08b326..dbca06e 100644
--- a/imports.md
+++ b/imports.md
@@ -2,11 +2,33 @@
 <ul>
 <li>Imports:
 <ul>
+<li>interface <a href="#wasi:io_error"><code>wasi:io/error</code></a></li>
 <li>interface <a href="#wasi:io_poll"><code>wasi:io/poll</code></a></li>
 <li>interface <a href="#wasi:io_streams"><code>wasi:io/streams</code></a></li>
 </ul>
 </li>
 </ul>
+<h2><a name="wasi:io_error">Import interface wasi:io/error</a></h2>
+<hr />
+<h3>Types</h3>
+<h4><a name="error"><code>resource error</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 is suitable to assist humans in debugging
+this error.</p>
+<p>WARNING: The returned string should not be consumed mechanically!
+It may change across platforms, hosts, or other implementation
+details. Parsing this string is a major 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>
 <h2><a name="wasi:io_poll">Import interface wasi:io/poll</a></h2>
 <p>A poll API intended to let users wait for I/O events on multiple handles
 at once.</p>
@@ -64,11 +86,13 @@ stream types.</p>
 when it does, they are expected to subsume this API.</p>
 <hr />
 <h3>Types</h3>
-<h4><a name="pollable"><code>type pollable</code></a></h4>
-<p><a href="#pollable"><a href="#pollable"><code>pollable</code></a></a></p>
+<h4><a name="error"><code>type error</code></a></h4>
+<p><a href="#error"><a href="#error"><code>error</code></a></a></p>
+<p>
+#### <a name="pollable">`type pollable`</a>
+[`pollable`](#pollable)
 <p>
-#### <a name="error">`resource error`</a>
-<h4><a name="stream_error"><code>variant stream-error</code></a></h4>
+#### <a name="stream_error">`variant stream-error`</a>
 <p>An error for input-stream and output-stream operations.</p>
 <h5>Variant Cases</h5>
 <ul>
@@ -88,20 +112,6 @@ future operations.
 <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 read data,
diff --git a/wit/error.wit b/wit/error.wit
new file mode 100644
index 0000000..66519ef
--- /dev/null
+++ b/wit/error.wit
@@ -0,0 +1,34 @@
+package wasi:io;
+
+
+interface error {
+    /// A resource which represents some error information.
+    ///
+    /// The only method provided by this resource is `to-debug-string`,
+    /// which provides some human-readable information about the error.
+    ///
+    /// In the `wasi:io` package, this resource is returned through the
+    /// `wasi:io/streams/stream-error` type.
+    ///
+    /// To provide more specific error information, other interfaces may
+    /// provide functions to further "downcast" this error into more specific
+    /// error information. For example, `error`s returned in streams derived
+    /// from filesystem types to be described using the filesystem's own
+    /// error-code type, using the function
+    /// `wasi:filesystem/types/filesystem-error-code`, which takes a parameter
+    /// `borrow<error>` and returns
+    /// `option<wasi:filesystem/types/error-code>`.
+    ///
+    /// The set of functions which can "downcast" an `error` into a more
+    /// concrete type is open.
+    resource error {
+        /// Returns a string that is suitable to assist humans in debugging
+        /// this error.
+        ///
+        /// WARNING: The returned string should not be consumed mechanically!
+        /// It may change across platforms, hosts, or other implementation
+        /// details. Parsing this string is a major platform-compatibility
+        /// hazard.
+        to-debug-string: func() -> string;
+    }
+}
diff --git a/wit/streams.wit b/wit/streams.wit
index 8999b28..643d7b7 100644
--- a/wit/streams.wit
+++ b/wit/streams.wit
@@ -6,6 +6,7 @@ package wasi:io;
 /// In the future, the component model is expected to add built-in stream types;
 /// when it does, they are expected to subsume this API.
 interface streams {
+    use error.{error};
     use poll.{pollable};
 
     /// An error for input-stream and output-stream operations.
@@ -20,26 +21,6 @@ interface streams {
         closed
     }
 
-    /// Contextual error information about the last failure that happened on
-    /// a read, write, or flush from an `input-stream` or `output-stream`.
-    ///
-    /// This type is returned through the `stream-error` type whenever an
-    /// operation on a stream directly fails or an error is discovered
-    /// after-the-fact, for example when a write's failure shows up through a
-    /// later `flush` or `check-write`.
-    ///
-    /// Interfaces such as `wasi:filesystem/types` provide functionality to
-    /// further "downcast" this error into interface-specific error information.
-    resource error {
-        /// Returns a string that's suitable to assist humans in debugging this
-        /// error.
-        ///
-        /// The returned string will change across platforms and hosts which
-        /// means that parsing it, for example, would be a
-        /// platform-compatibility hazard.
-        to-debug-string: func() -> string;
-    }
-
     /// An input bytestream.
     ///
     /// `input-stream`s are *non-blocking* to the extent practical on underlying