Adressing feedback from upstream sync (#27)

* Adressing feedback from upstream sync

- clarified comment on `topic` function.
- added portability comment onto `metadata` to avoid it being used as an escape-hatch.
- removed `get-topics` func in favour of using wasi-config for runtime configuration.

* [chore] update markdown files

Signed-off-by: danbugs <[email protected]>

---------

Signed-off-by: danbugs <[email protected]>

Author: danbugs

imports-request-reply.md

@@ -73,7 +73,7 @@ This allows the component to perform request/reply messaging patterns.</p>
 <li><a id="constructor_message.0"></a> own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_topic"></a><code>[method]message.topic: func</code></h4>
-<p>The topic/subject/channel this message was received or should be sent on</p>
+<p>The topic/subject/channel this message was received on</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_topic.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
@@ -120,7 +120,8 @@ sometimes described as the &quot;format&quot; type</p>
 </ul>
 <h4><a id="method_message_metadata"></a><code>[method]message.metadata: func</code></h4>
 <p>Optional metadata (also called headers or attributes in some systems) attached to the
-message</p>
+message. This metadata is simply decoration and should not be interpreted by a host
+to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc.).</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>

imports.md

@@ -72,7 +72,7 @@ It includes the <code>producer</code> interface for sending messages.</p>
 <li><a id="constructor_message.0"></a> own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_topic"></a><code>[method]message.topic: func</code></h4>
-<p>The topic/subject/channel this message was received or should be sent on</p>
+<p>The topic/subject/channel this message was received on</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_topic.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
@@ -119,7 +119,8 @@ sometimes described as the &quot;format&quot; type</p>
 </ul>
 <h4><a id="method_message_metadata"></a><code>[method]message.metadata: func</code></h4>
 <p>Optional metadata (also called headers or attributes in some systems) attached to the
-message</p>
+message. This metadata is simply decoration and should not be interpreted by a host
+to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc.).</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>

messaging-core.md

@@ -77,7 +77,7 @@ enabling the component to handle incoming messages without request/reply capabil
 <li><a id="constructor_message.0"></a> own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_topic"></a><code>[method]message.topic: func</code></h4>
-<p>The topic/subject/channel this message was received or should be sent on</p>
+<p>The topic/subject/channel this message was received on</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_topic.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
@@ -124,7 +124,8 @@ sometimes described as the &quot;format&quot; type</p>
 </ul>
 <h4><a id="method_message_metadata"></a><code>[method]message.metadata: func</code></h4>
 <p>Optional metadata (also called headers or attributes in some systems) attached to the
-message</p>
+message. This metadata is simply decoration and should not be interpreted by a host
+to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc.).</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
@@ -212,12 +213,3 @@ own decisions on how to handle errors returned from this function.</p>
 <ul>
 <li><a id="handle.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
-<h4><a id="get_topics"></a><code>get-topics: func</code></h4>
-<p>Returns a list of topics (represented as <code>string</code>s) at runtime the guest should be subscribed
-Implementors should consider also allowing subscriptions to be made at compile time
-via some sort of configuration file. This function is intended to be called at the start of the
-guest's lifecycle before any messages are sent.</p>
-<h5>Return values</h5>
-<ul>
-<li><a id="get_topics.0"></a> result&lt;list&lt;<a href="#topic"><a href="#topic"><code>topic</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
-</ul>

messaging-request-reply.md

@@ -79,7 +79,7 @@ handling incoming messages with request/reply capabilities.</p>
 <li><a id="constructor_message.0"></a> own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_topic"></a><code>[method]message.topic: func</code></h4>
-<p>The topic/subject/channel this message was received or should be sent on</p>
+<p>The topic/subject/channel this message was received on</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_topic.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
@@ -126,7 +126,8 @@ sometimes described as the &quot;format&quot; type</p>
 </ul>
 <h4><a id="method_message_metadata"></a><code>[method]message.metadata: func</code></h4>
 <p>Optional metadata (also called headers or attributes in some systems) attached to the
-message</p>
+message. This metadata is simply decoration and should not be interpreted by a host
+to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc.).</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
@@ -296,12 +297,3 @@ own decisions on how to handle errors returned from this function.</p>
 <ul>
 <li><a id="handle.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 </ul>
-<h4><a id="get_topics"></a><code>get-topics: func</code></h4>
-<p>Returns a list of topics (represented as <code>string</code>s) at runtime the guest should be subscribed
-Implementors should consider also allowing subscriptions to be made at compile time
-via some sort of configuration file. This function is intended to be called at the start of the
-guest's lifecycle before any messages are sent.</p>
-<h5>Return values</h5>
-<ul>
-<li><a id="get_topics.0"></a> result&lt;list&lt;<a href="#topic"><a href="#topic"><code>topic</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
-</ul>

wit/guest.wit

@@ -6,10 +6,4 @@ interface incoming-handler {
     /// message accordingly. Implementors (such as hosts) calling this interface should make their
     /// own decisions on how to handle errors returned from this function.
     handle: func(message: message) -> result<_, error>;
-
-    // Returns a list of topics (represented as `string`s) at runtime the guest should be subscribed
-    // Implementors should consider also allowing subscriptions to be made at compile time
-    // via some sort of configuration file. This function is intended to be called at the start of the
-    // guest's lifecycle before any messages are sent.
-    get-topics: func() -> result<list<topic>, error>;
 }

wit/types.wit

@@ -26,7 +26,7 @@ interface types {
     /// A message with a binary payload and additional information
     resource message {
         constructor(data: list<u8>);
-        /// The topic/subject/channel this message was received or should be sent on
+        /// The topic/subject/channel this message was received on
         topic: func() -> topic;
         /// An optional content-type describing the format of the data in the message. This is 
         /// sometimes described as the "format" type
@@ -39,7 +39,8 @@ interface types {
         /// Set the opaque blob of data for this message, discarding the old value
         set-data: func(data: list<u8>);
         /// Optional metadata (also called headers or attributes in some systems) attached to the
-        /// message
+        /// message. This metadata is simply decoration and should not be interpreted by a host
+        /// to ensure portability across different implementors (e.g., Kafka -> NATS, etc.).
         metadata: func() -> option<metadata>;
         /// Add a new key-value pair to the metadata, overwriting any existing value for the same key
         add-metadata: func(key: string, value: string);