Add static into-parts for incoming messages; deprecate consume

Closes #102. See discussion in that issue for the motivation and design of this change.

Author: acfoltzer

imports.md

@@ -974,6 +974,7 @@ the parent <a href="#incoming_request"><code>incoming-request</code></a> is drop
 <h4><a name="method_incoming_request.consume"></a><code>[method]incoming-request.consume: func</code></h4>
 <p>Gives the <a href="#incoming_body"><code>incoming-body</code></a> associated with this request. Will only
 return success at most once, and subsequent calls will return error.</p>
+<p>Deprecated in favor of <code>into-parts</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_incoming_request.consume.self"></a><code>self</code>: borrow&lt;<a href="#incoming_request"><a href="#incoming_request"><code>incoming-request</code></a></a>&gt;</li>
@@ -982,6 +983,17 @@ return success at most once, and subsequent calls will return error.</p>
 <ul>
 <li><a name="method_incoming_request.consume.0"></a> result&lt;own&lt;<a href="#incoming_body"><a href="#incoming_body"><code>incoming-body</code></a></a>&gt;&gt;</li>
 </ul>
+<h4><a name="static_incoming_request.into_parts"></a><code>[static]incoming-request.into-parts: func</code></h4>
+<p>Decompose the incoming request into its component parts.</p>
+<p>All resources returned by this function are owned.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="static_incoming_request.into_parts.response"></a><code>response</code>: own&lt;<a href="#incoming_request"><a href="#incoming_request"><code>incoming-request</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="static_incoming_request.into_parts.0"></a> (<a href="#method"><a href="#method"><code>method</code></a></a>, option&lt;<code>string</code>&gt;, option&lt;<a href="#scheme"><a href="#scheme"><code>scheme</code></a></a>&gt;, option&lt;<code>string</code>&gt;, own&lt;<a href="#headers"><a href="#headers"><code>headers</code></a></a>&gt;, own&lt;<a href="#incoming_body"><a href="#incoming_body"><code>incoming-body</code></a></a>&gt;)</li>
+</ul>
 <h4><a name="constructor_outgoing_request"></a><code>[constructor]outgoing-request: func</code></h4>
 <p>Construct a new <a href="#outgoing_request"><code>outgoing-request</code></a> with a default <a href="#method"><code>method</code></a> of <code>GET</code>, and
 <code>none</code> values for <code>path-with-query</code>, <a href="#scheme"><code>scheme</code></a>, and <code>authority</code>.</p>
@@ -1240,6 +1252,7 @@ implementation determine how to respond with an HTTP error response.</p>
 <h4><a name="method_incoming_response.consume"></a><code>[method]incoming-response.consume: func</code></h4>
 <p>Returns the incoming body. May be called at most once. Returns error
 if called additional times.</p>
+<p>Deprecated in favor of <code>into-parts</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_incoming_response.consume.self"></a><code>self</code>: borrow&lt;<a href="#incoming_response"><a href="#incoming_response"><code>incoming-response</code></a></a>&gt;</li>
@@ -1248,6 +1261,17 @@ if called additional times.</p>
 <ul>
 <li><a name="method_incoming_response.consume.0"></a> result&lt;own&lt;<a href="#incoming_body"><a href="#incoming_body"><code>incoming-body</code></a></a>&gt;&gt;</li>
 </ul>
+<h4><a name="static_incoming_response.into_parts"></a><code>[static]incoming-response.into-parts: func</code></h4>
+<p>Decompose the incoming response into its component parts.</p>
+<p>All resources returned by this function are owned.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="static_incoming_response.into_parts.response"></a><code>response</code>: own&lt;<a href="#incoming_response"><a href="#incoming_response"><code>incoming-response</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="static_incoming_response.into_parts.0"></a> (<a href="#status_code"><a href="#status_code"><code>status-code</code></a></a>, own&lt;<a href="#headers"><a href="#headers"><code>headers</code></a></a>&gt;, own&lt;<a href="#incoming_body"><a href="#incoming_body"><code>incoming-body</code></a></a>&gt;)</li>
+</ul>
 <h4><a name="method_incoming_body.stream"></a><code>[method]incoming-body.stream: func</code></h4>
 <p>Returns the contents of the body, as a stream of bytes.</p>
 <p>Returns success on first call: the stream representing the contents

proxy.md

@@ -909,6 +909,7 @@ the parent <a href="#incoming_request"><code>incoming-request</code></a> is drop
 <h4><a name="method_incoming_request.consume"></a><code>[method]incoming-request.consume: func</code></h4>
 <p>Gives the <a href="#incoming_body"><code>incoming-body</code></a> associated with this request. Will only
 return success at most once, and subsequent calls will return error.</p>
+<p>Deprecated in favor of <code>into-parts</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_incoming_request.consume.self"></a><code>self</code>: borrow&lt;<a href="#incoming_request"><a href="#incoming_request"><code>incoming-request</code></a></a>&gt;</li>
@@ -917,6 +918,17 @@ return success at most once, and subsequent calls will return error.</p>
 <ul>
 <li><a name="method_incoming_request.consume.0"></a> result&lt;own&lt;<a href="#incoming_body"><a href="#incoming_body"><code>incoming-body</code></a></a>&gt;&gt;</li>
 </ul>
+<h4><a name="static_incoming_request.into_parts"></a><code>[static]incoming-request.into-parts: func</code></h4>
+<p>Decompose the incoming request into its component parts.</p>
+<p>All resources returned by this function are owned.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="static_incoming_request.into_parts.response"></a><code>response</code>: own&lt;<a href="#incoming_request"><a href="#incoming_request"><code>incoming-request</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="static_incoming_request.into_parts.0"></a> (<a href="#method"><a href="#method"><code>method</code></a></a>, option&lt;<code>string</code>&gt;, option&lt;<a href="#scheme"><a href="#scheme"><code>scheme</code></a></a>&gt;, option&lt;<code>string</code>&gt;, own&lt;<a href="#headers"><a href="#headers"><code>headers</code></a></a>&gt;, own&lt;<a href="#incoming_body"><a href="#incoming_body"><code>incoming-body</code></a></a>&gt;)</li>
+</ul>
 <h4><a name="constructor_outgoing_request"></a><code>[constructor]outgoing-request: func</code></h4>
 <p>Construct a new <a href="#outgoing_request"><code>outgoing-request</code></a> with a default <a href="#method"><code>method</code></a> of <code>GET</code>, and
 <code>none</code> values for <code>path-with-query</code>, <a href="#scheme"><code>scheme</code></a>, and <code>authority</code>.</p>
@@ -1175,6 +1187,7 @@ implementation determine how to respond with an HTTP error response.</p>
 <h4><a name="method_incoming_response.consume"></a><code>[method]incoming-response.consume: func</code></h4>
 <p>Returns the incoming body. May be called at most once. Returns error
 if called additional times.</p>
+<p>Deprecated in favor of <code>into-parts</code>.</p>
 <h5>Params</h5>
 <ul>
 <li><a name="method_incoming_response.consume.self"></a><code>self</code>: borrow&lt;<a href="#incoming_response"><a href="#incoming_response"><code>incoming-response</code></a></a>&gt;</li>
@@ -1183,6 +1196,17 @@ if called additional times.</p>
 <ul>
 <li><a name="method_incoming_response.consume.0"></a> result&lt;own&lt;<a href="#incoming_body"><a href="#incoming_body"><code>incoming-body</code></a></a>&gt;&gt;</li>
 </ul>
+<h4><a name="static_incoming_response.into_parts"></a><code>[static]incoming-response.into-parts: func</code></h4>
+<p>Decompose the incoming response into its component parts.</p>
+<p>All resources returned by this function are owned.</p>
+<h5>Params</h5>
+<ul>
+<li><a name="static_incoming_response.into_parts.response"></a><code>response</code>: own&lt;<a href="#incoming_response"><a href="#incoming_response"><code>incoming-response</code></a></a>&gt;</li>
+</ul>
+<h5>Return values</h5>
+<ul>
+<li><a name="static_incoming_response.into_parts.0"></a> (<a href="#status_code"><a href="#status_code"><code>status-code</code></a></a>, own&lt;<a href="#headers"><a href="#headers"><code>headers</code></a></a>&gt;, own&lt;<a href="#incoming_body"><a href="#incoming_body"><code>incoming-body</code></a></a>&gt;)</li>
+</ul>
 <h4><a name="method_incoming_body.stream"></a><code>[method]incoming-body.stream: func</code></h4>
 <p>Returns the contents of the body, as a stream of bytes.</p>
 <p>Returns success on first call: the stream representing the contents

wit/types.wit

@@ -244,7 +244,23 @@ interface types {
 
     /// Gives the `incoming-body` associated with this request. Will only
     /// return success at most once, and subsequent calls will return error.
+    ///
+    /// Deprecated in favor of `into-parts`.
     consume: func() -> result<incoming-body>;
+
+    /// Decompose the incoming request into its component parts.
+    ///
+    /// All resources returned by this function are owned.
+    into-parts: static func(
+      response: incoming-request
+    ) -> tuple<
+      method,
+      option<string>, // path-with-query
+      option<scheme>,
+      option<string>, // authority
+      headers,
+      incoming-body
+    >;
   }
 
   /// Represents an outgoing HTTP Request.
@@ -391,7 +407,16 @@ interface types {
 
     /// Returns the incoming body. May be called at most once. Returns error
     /// if called additional times.
+    ///
+    /// Deprecated in favor of `into-parts`.
     consume: func() -> result<incoming-body>;
+
+    /// Decompose the incoming response into its component parts.
+    ///
+    /// All resources returned by this function are owned.
+    into-parts: static func(
+      response: incoming-response
+    ) -> tuple<status-code, headers, incoming-body>;
   }
 
   /// Represents an incoming HTTP Request or Response's Body.