From 49ac282b6ac6ee3bd3b45ae2d2763e59afbaca21 Mon Sep 17 00:00:00 2001
From: danbugs <danilochiarlone@gmail.com>
Date: Fri, 4 Oct 2024 16:49:44 +0000
Subject: [PATCH] addressing first round of feedback: added type aliases, added
 remove-metadata method, added new-line at the end of files, improved argument
 names, removed .gitignore, improved documentation, changed get-subscriptions
 function name

Signed-off-by: danbugs <danilochiarlone@gmail.com>
---
 .gitignore                 |  2 --
 README.md                  |  2 +-
 imports-request-reply.md   | 31 ++++++++++++++++++-------
 imports.md                 | 25 ++++++++++++++++----
 messaging-core.md          | 40 +++++++++++++++++++++++---------
 messaging-request-reply.md | 47 ++++++++++++++++++++++++++------------
 wit/guest.wit              | 12 +++++-----
 wit/messaging.wit          | 23 +++++++++++++------
 wit/producer.wit           |  2 +-
 wit/request-reply.wit      |  6 ++---
 wit/types.wit              | 16 +++++++++----
 11 files changed, 144 insertions(+), 62 deletions(-)
 delete mode 100644 .gitignore

diff --git a/.gitignore b/.gitignore
deleted file mode 100644
index 00741cb..0000000
--- a/.gitignore
+++ /dev/null
@@ -1,2 +0,0 @@
-.DS_Store
-.idea/
\ No newline at end of file
diff --git a/README.md b/README.md
index 94212c5..01f7bbe 100644
--- a/README.md
+++ b/README.md
@@ -101,4 +101,4 @@ It would make sense for a lot of these functions to be asynchronous, but that is
 the component model. Asynchronous support will be added as part of WASI Preview 3. When async support becomes 
 available, we plan to update the wasi-messaging interface to incorporate asynchronous patterns.
 
-> **Note**: Ensure you have version 0.30.0 of `wit-bindgen` installed to avoid compatibility issues.
\ No newline at end of file
+> **Note**: Ensure you have version 0.30.0 of `wit-bindgen` installed to avoid compatibility issues.
diff --git a/imports-request-reply.md b/imports-request-reply.md
index 4c6d3be..bdfa2d6 100644
--- a/imports-request-reply.md
+++ b/imports-request-reply.md
@@ -1,4 +1,6 @@
 <h1><a id="imports_request_reply"></a>World imports-request-reply</h1>
+<p>The <a href="#imports_request_reply"><code>imports-request-reply</code></a> world extends <code>imports</code> by including the <code>request-reply</code> interface.
+This allows the component to perform request/reply messaging patterns.</p>
 <ul>
 <li>Imports:
 <ul>
@@ -11,6 +13,12 @@
 <h2><a id="wasi_messaging_types_0_2_0_draft"></a>Import interface wasi:messaging/types@0.2.0-draft</h2>
 <hr />
 <h3>Types</h3>
+<h4><a id="metadata"></a><code>type metadata</code></h4>
+<p><a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></p>
+<p>A type alias for list<tuple<string, string>> to represent metadata attached to a message
+<h4><a id="topic"></a><code>type topic</code></h4>
+<p><code>string</code></p>
+<p>A type alias for string to represent a message topic
 <h4><a id="client"></a><code>resource client</code></h4>
 <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
 <h4><a id="error"></a><code>variant error</code></h4>
@@ -58,7 +66,7 @@
 <h4><a id="constructor_message"></a><code>[constructor]message: func</code></h4>
 <h5>Params</h5>
 <ul>
-<li><a id="constructor_message.topic"></a><code>topic</code>: <code>string</code></li>
+<li><a id="constructor_message.topic"></a><a href="#topic"><code>topic</code></a>: <code>string</code></li>
 <li><a id="constructor_message.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
 </ul>
 <h5>Return values</h5>
@@ -73,14 +81,14 @@
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a id="method_message_topic.0"></a> <code>string</code></li>
+<li><a id="method_message_topic.0"></a> <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
 </ul>
 <h4><a id="method_message_set_topic"></a><code>[method]message.set-topic: func</code></h4>
 <p>Set the topic/subject/channel this message should be sent on</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_topic.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
-<li><a id="method_message_set_topic.topic"></a><code>topic</code>: <code>string</code></li>
+<li><a id="method_message_set_topic.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
 </ul>
 <h4><a id="method_message_content_type"></a><code>[method]message.content-type: func</code></h4>
 <p>An optional content-type describing the format of the data in the message. This is
@@ -127,7 +135,7 @@ message</p>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a id="method_message_metadata.0"></a> option&lt;list&lt;(<code>string</code>, <code>string</code>)&gt;&gt;</li>
+<li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
 <p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
@@ -137,6 +145,13 @@ message</p>
 <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
 <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
 </ul>
+<h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
+<p>Remove a key-value pair from the metadata</p>
+<h5>Params</h5>
+<ul>
+<li><a id="method_message_remove_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="method_message_remove_metadata.key"></a><code>key</code>: <code>string</code></li>
+</ul>
 <h2><a id="wasi_messaging_request_reply_0_2_0_draft"></a>Import interface wasi:messaging/request-reply@0.2.0-draft</h2>
 <p>The request-reply interface allows a guest to send a message and await a response. This
 interface is considered optional as not all message services support the concept of
@@ -193,8 +208,8 @@ return the list of messages received up to that point.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="request.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
-<li><a id="request.msg"></a><code>msg</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
-<li><a id="request.opts"></a><code>opts</code>: option&lt;own&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;&gt;</li>
+<li><a id="request.message"></a><a href="#message"><code>message</code></a>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="request.options"></a><code>options</code>: option&lt;own&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;&gt;</li>
 </ul>
 <h5>Return values</h5>
 <ul>
@@ -213,7 +228,7 @@ where the reply is sent and the connection is closed.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="reply.reply_to"></a><code>reply-to</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
-<li><a id="reply.reply"></a><a href="#reply"><code>reply</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="reply.message"></a><a href="#message"><code>message</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h5>Return values</h5>
 <ul>
@@ -239,7 +254,7 @@ where the reply is sent and the connection is closed.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="send.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
-<li><a id="send.m"></a><code>m</code>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="send.message"></a><a href="#message"><code>message</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h5>Return values</h5>
 <ul>
diff --git a/imports.md b/imports.md
index 4b552b8..5e16128 100644
--- a/imports.md
+++ b/imports.md
@@ -1,4 +1,6 @@
 <h1><a id="imports"></a>World imports</h1>
+<p>The <a href="#imports"><code>imports</code></a> world defines the interfaces that the component will import from the host.
+It includes the <code>producer</code> interface for sending messages.</p>
 <ul>
 <li>Imports:
 <ul>
@@ -10,6 +12,12 @@
 <h2><a id="wasi_messaging_types_0_2_0_draft"></a>Import interface wasi:messaging/types@0.2.0-draft</h2>
 <hr />
 <h3>Types</h3>
+<h4><a id="metadata"></a><code>type metadata</code></h4>
+<p><a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></p>
+<p>A type alias for list<tuple<string, string>> to represent metadata attached to a message
+<h4><a id="topic"></a><code>type topic</code></h4>
+<p><code>string</code></p>
+<p>A type alias for string to represent a message topic
 <h4><a id="client"></a><code>resource client</code></h4>
 <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
 <h4><a id="error"></a><code>variant error</code></h4>
@@ -57,7 +65,7 @@
 <h4><a id="constructor_message"></a><code>[constructor]message: func</code></h4>
 <h5>Params</h5>
 <ul>
-<li><a id="constructor_message.topic"></a><code>topic</code>: <code>string</code></li>
+<li><a id="constructor_message.topic"></a><a href="#topic"><code>topic</code></a>: <code>string</code></li>
 <li><a id="constructor_message.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
 </ul>
 <h5>Return values</h5>
@@ -72,14 +80,14 @@
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a id="method_message_topic.0"></a> <code>string</code></li>
+<li><a id="method_message_topic.0"></a> <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
 </ul>
 <h4><a id="method_message_set_topic"></a><code>[method]message.set-topic: func</code></h4>
 <p>Set the topic/subject/channel this message should be sent on</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_topic.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
-<li><a id="method_message_set_topic.topic"></a><code>topic</code>: <code>string</code></li>
+<li><a id="method_message_set_topic.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
 </ul>
 <h4><a id="method_message_content_type"></a><code>[method]message.content-type: func</code></h4>
 <p>An optional content-type describing the format of the data in the message. This is
@@ -126,7 +134,7 @@ message</p>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a id="method_message_metadata.0"></a> option&lt;list&lt;(<code>string</code>, <code>string</code>)&gt;&gt;</li>
+<li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
 <p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
@@ -136,6 +144,13 @@ message</p>
 <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
 <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
 </ul>
+<h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
+<p>Remove a key-value pair from the metadata</p>
+<h5>Params</h5>
+<ul>
+<li><a id="method_message_remove_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="method_message_remove_metadata.key"></a><code>key</code>: <code>string</code></li>
+</ul>
 <h2><a id="wasi_messaging_producer_0_2_0_draft"></a>Import interface wasi:messaging/producer@0.2.0-draft</h2>
 <p>The producer interface is used to send messages to a channel/topic.</p>
 <hr />
@@ -156,7 +171,7 @@ message</p>
 <h5>Params</h5>
 <ul>
 <li><a id="send.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
-<li><a id="send.m"></a><code>m</code>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="send.message"></a><a href="#message"><code>message</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h5>Return values</h5>
 <ul>
diff --git a/messaging-core.md b/messaging-core.md
index d704832..e20f1cd 100644
--- a/messaging-core.md
+++ b/messaging-core.md
@@ -1,4 +1,6 @@
 <h1><a id="messaging_core"></a>World messaging-core</h1>
+<p>The <a href="#messaging_core"><code>messaging-core</code></a> world includes the basic <code>imports</code> and exports the <code>incoming-handler</code>,
+enabling the component to handle incoming messages without request/reply capabilities.</p>
 <ul>
 <li>Imports:
 <ul>
@@ -15,6 +17,12 @@
 <h2><a id="wasi_messaging_types_0_2_0_draft"></a>Import interface wasi:messaging/types@0.2.0-draft</h2>
 <hr />
 <h3>Types</h3>
+<h4><a id="metadata"></a><code>type metadata</code></h4>
+<p><a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></p>
+<p>A type alias for list<tuple<string, string>> to represent metadata attached to a message
+<h4><a id="topic"></a><code>type topic</code></h4>
+<p><code>string</code></p>
+<p>A type alias for string to represent a message topic
 <h4><a id="client"></a><code>resource client</code></h4>
 <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
 <h4><a id="error"></a><code>variant error</code></h4>
@@ -62,7 +70,7 @@
 <h4><a id="constructor_message"></a><code>[constructor]message: func</code></h4>
 <h5>Params</h5>
 <ul>
-<li><a id="constructor_message.topic"></a><code>topic</code>: <code>string</code></li>
+<li><a id="constructor_message.topic"></a><a href="#topic"><code>topic</code></a>: <code>string</code></li>
 <li><a id="constructor_message.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
 </ul>
 <h5>Return values</h5>
@@ -77,14 +85,14 @@
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a id="method_message_topic.0"></a> <code>string</code></li>
+<li><a id="method_message_topic.0"></a> <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
 </ul>
 <h4><a id="method_message_set_topic"></a><code>[method]message.set-topic: func</code></h4>
 <p>Set the topic/subject/channel this message should be sent on</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_topic.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
-<li><a id="method_message_set_topic.topic"></a><code>topic</code>: <code>string</code></li>
+<li><a id="method_message_set_topic.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
 </ul>
 <h4><a id="method_message_content_type"></a><code>[method]message.content-type: func</code></h4>
 <p>An optional content-type describing the format of the data in the message. This is
@@ -131,7 +139,7 @@ message</p>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a id="method_message_metadata.0"></a> option&lt;list&lt;(<code>string</code>, <code>string</code>)&gt;&gt;</li>
+<li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
 <p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
@@ -141,6 +149,13 @@ message</p>
 <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
 <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
 </ul>
+<h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
+<p>Remove a key-value pair from the metadata</p>
+<h5>Params</h5>
+<ul>
+<li><a id="method_message_remove_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="method_message_remove_metadata.key"></a><code>key</code>: <code>string</code></li>
+</ul>
 <h2><a id="wasi_messaging_producer_0_2_0_draft"></a>Import interface wasi:messaging/producer@0.2.0-draft</h2>
 <p>The producer interface is used to send messages to a channel/topic.</p>
 <hr />
@@ -161,7 +176,7 @@ message</p>
 <h5>Params</h5>
 <ul>
 <li><a id="send.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
-<li><a id="send.m"></a><code>m</code>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="send.message"></a><a href="#message"><code>message</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h5>Return values</h5>
 <ul>
@@ -176,6 +191,9 @@ message</p>
 #### <a id="error"></a>`type error`
 [`error`](#error)
 <p>
+#### <a id="topic"></a>`type topic`
+[`topic`](#topic)
+<p>
 ----
 <h3>Functions</h3>
 <h4><a id="handle"></a><code>handle: func</code></h4>
@@ -185,18 +203,18 @@ message accordingly. Implementors (such as hosts) calling this interface should
 own decisions on how to handle errors returned from this function.</p>
 <h5>Params</h5>
 <ul>
-<li><a id="handle.ms"></a><code>ms</code>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="handle.message"></a><a href="#message"><code>message</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h5>Return values</h5>
 <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_subscriptions"></a><code>get-subscriptions: func</code></h4>
-<p>Subscribe to a list of topics (represented as <code>string</code>s) at runtime.
-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
+<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
+to at runtime. 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_subscriptions.0"></a> result&lt;list&lt;<code>string</code>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
+<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>
diff --git a/messaging-request-reply.md b/messaging-request-reply.md
index b3ffc73..f2ec63c 100644
--- a/messaging-request-reply.md
+++ b/messaging-request-reply.md
@@ -1,4 +1,7 @@
 <h1><a id="messaging_request_reply"></a>World messaging-request-reply</h1>
+<p>The <a href="#messaging_request_reply"><code>messaging-request-reply</code></a> world combines <code>imports-request-reply</code> with the <code>incoming-handler</code>
+export. This setup allows the host to interact with the component for both sending messages and
+handling incoming messages with request/reply capabilities.</p>
 <ul>
 <li>Imports:
 <ul>
@@ -16,6 +19,12 @@
 <h2><a id="wasi_messaging_types_0_2_0_draft"></a>Import interface wasi:messaging/types@0.2.0-draft</h2>
 <hr />
 <h3>Types</h3>
+<h4><a id="metadata"></a><code>type metadata</code></h4>
+<p><a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></p>
+<p>A type alias for list<tuple<string, string>> to represent metadata attached to a message
+<h4><a id="topic"></a><code>type topic</code></h4>
+<p><code>string</code></p>
+<p>A type alias for string to represent a message topic
 <h4><a id="client"></a><code>resource client</code></h4>
 <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
 <h4><a id="error"></a><code>variant error</code></h4>
@@ -63,7 +72,7 @@
 <h4><a id="constructor_message"></a><code>[constructor]message: func</code></h4>
 <h5>Params</h5>
 <ul>
-<li><a id="constructor_message.topic"></a><code>topic</code>: <code>string</code></li>
+<li><a id="constructor_message.topic"></a><a href="#topic"><code>topic</code></a>: <code>string</code></li>
 <li><a id="constructor_message.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
 </ul>
 <h5>Return values</h5>
@@ -78,14 +87,14 @@
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a id="method_message_topic.0"></a> <code>string</code></li>
+<li><a id="method_message_topic.0"></a> <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
 </ul>
 <h4><a id="method_message_set_topic"></a><code>[method]message.set-topic: func</code></h4>
 <p>Set the topic/subject/channel this message should be sent on</p>
 <h5>Params</h5>
 <ul>
 <li><a id="method_message_set_topic.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
-<li><a id="method_message_set_topic.topic"></a><code>topic</code>: <code>string</code></li>
+<li><a id="method_message_set_topic.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
 </ul>
 <h4><a id="method_message_content_type"></a><code>[method]message.content-type: func</code></h4>
 <p>An optional content-type describing the format of the data in the message. This is
@@ -132,7 +141,7 @@ message</p>
 </ul>
 <h5>Return values</h5>
 <ul>
-<li><a id="method_message_metadata.0"></a> option&lt;list&lt;(<code>string</code>, <code>string</code>)&gt;&gt;</li>
+<li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
 </ul>
 <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
 <p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
@@ -142,6 +151,13 @@ message</p>
 <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
 <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
 </ul>
+<h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
+<p>Remove a key-value pair from the metadata</p>
+<h5>Params</h5>
+<ul>
+<li><a id="method_message_remove_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="method_message_remove_metadata.key"></a><code>key</code>: <code>string</code></li>
+</ul>
 <h2><a id="wasi_messaging_request_reply_0_2_0_draft"></a>Import interface wasi:messaging/request-reply@0.2.0-draft</h2>
 <p>The request-reply interface allows a guest to send a message and await a response. This
 interface is considered optional as not all message services support the concept of
@@ -198,8 +214,8 @@ return the list of messages received up to that point.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="request.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
-<li><a id="request.msg"></a><code>msg</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
-<li><a id="request.opts"></a><code>opts</code>: option&lt;own&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;&gt;</li>
+<li><a id="request.message"></a><a href="#message"><code>message</code></a>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="request.options"></a><code>options</code>: option&lt;own&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;&gt;</li>
 </ul>
 <h5>Return values</h5>
 <ul>
@@ -218,7 +234,7 @@ where the reply is sent and the connection is closed.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="reply.reply_to"></a><code>reply-to</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
-<li><a id="reply.reply"></a><a href="#reply"><code>reply</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="reply.message"></a><a href="#message"><code>message</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h5>Return values</h5>
 <ul>
@@ -244,7 +260,7 @@ where the reply is sent and the connection is closed.</p>
 <h5>Params</h5>
 <ul>
 <li><a id="send.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
-<li><a id="send.m"></a><code>m</code>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="send.message"></a><a href="#message"><code>message</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h5>Return values</h5>
 <ul>
@@ -259,6 +275,9 @@ where the reply is sent and the connection is closed.</p>
 #### <a id="error"></a>`type error`
 [`error`](#error)
 <p>
+#### <a id="topic"></a>`type topic`
+[`topic`](#topic)
+<p>
 ----
 <h3>Functions</h3>
 <h4><a id="handle"></a><code>handle: func</code></h4>
@@ -268,18 +287,18 @@ message accordingly. Implementors (such as hosts) calling this interface should
 own decisions on how to handle errors returned from this function.</p>
 <h5>Params</h5>
 <ul>
-<li><a id="handle.ms"></a><code>ms</code>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
+<li><a id="handle.message"></a><a href="#message"><code>message</code></a>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 </ul>
 <h5>Return values</h5>
 <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_subscriptions"></a><code>get-subscriptions: func</code></h4>
-<p>Subscribe to a list of topics (represented as <code>string</code>s) at runtime.
-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
+<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
+to at runtime. 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_subscriptions.0"></a> result&lt;list&lt;<code>string</code>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
+<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>
diff --git a/wit/guest.wit b/wit/guest.wit
index 9850f15..940bb31 100644
--- a/wit/guest.wit
+++ b/wit/guest.wit
@@ -1,15 +1,15 @@
 interface incoming-handler {
-    use types.{message, error};
+    use types.{message, error, topic};
 
     /// Whenever this guest receives a message in one of the subscribed topics, the message is
     /// sent to this handler. The guest is responsible for matching on the channel and handling the
     /// 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(ms: message) -> result<_, error>;
+    handle: func(message: message) -> result<_, error>;
 
-    // Subscribe to a list of topics (represented as `string`s) at runtime.
-    // 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
+    // Returns a list of topics (represented as `string`s) at runtime the guest should be subscribed
+    // to at runtime. 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-subscriptions: func() -> result<list<string>, error>;
+    get-topics: func() -> result<list<topic>, error>;
 }
diff --git a/wit/messaging.wit b/wit/messaging.wit
index 3b70f73..d15544b 100644
--- a/wit/messaging.wit
+++ b/wit/messaging.wit
@@ -1,20 +1,29 @@
 package wasi:messaging@0.2.0-draft;
 
+/// The `imports` world defines the interfaces that the component will import from the host.
+/// It includes the `producer` interface for sending messages.
 world imports {
-	import producer;
+  import producer;
 }
 
+/// The `imports-request-reply` world extends `imports` by including the `request-reply` interface.
+/// This allows the component to perform request/reply messaging patterns.
 world imports-request-reply {
-	include imports;
-	import request-reply;
+  include imports;
+  import request-reply;
 }
 
+/// The `messaging-request-reply` world combines `imports-request-reply` with the `incoming-handler`
+/// export. This setup allows the host to interact with the component for both sending messages and
+/// handling incoming messages with request/reply capabilities.
 world messaging-request-reply {
-	include imports-request-reply;
-	export incoming-handler;
+  include imports-request-reply;
+  export incoming-handler;
 }
 
+/// The `messaging-core` world includes the basic `imports` and exports the `incoming-handler`,
+/// enabling the component to handle incoming messages without request/reply capabilities.
 world messaging-core {
-	include imports;
-	export incoming-handler;
+  include imports;
+  export incoming-handler;
 }
diff --git a/wit/producer.wit b/wit/producer.wit
index bc82e3c..86c509d 100644
--- a/wit/producer.wit
+++ b/wit/producer.wit
@@ -3,5 +3,5 @@ interface producer {
     use types.{client, message, error};
     
     /// Sends the message using the given client.
-    send: func(c: borrow<client>, m: message) -> result<_, error>;
+    send: func(c: borrow<client>, message: message) -> result<_, error>;
 }
diff --git a/wit/request-reply.wit b/wit/request-reply.wit
index 90041d0..8fe8031 100644
--- a/wit/request-reply.wit
+++ b/wit/request-reply.wit
@@ -31,7 +31,7 @@ interface request-reply {
     /// error, (2) if the maximum expected number of replies were received before timeout, return
     /// the list of messages, or (3) if the timeout is reached before the expected number of replies,
     /// return the list of messages received up to that point.
-    request: func(c: borrow<client>, msg: borrow<message>, opts: option<request-options>) -> result<list<message>, error>;
+    request: func(c: borrow<client>, message: borrow<message>, options: option<request-options>) -> result<list<message>, error>;
 
     /// Replies to the given message with the given response message. The details of which channel 
     /// the message is sent to is up to the implementation. This allows for reply-to details to be
@@ -43,5 +43,5 @@ interface request-reply {
     /// Additionally, you might want to reply to a message several times (such as providing an
     /// update). So this function is allowed to be called multiple times, unlike something like HTTP
     /// where the reply is sent and the connection is closed.
-    reply: func(reply-to: borrow<message>, reply: message) -> result<_, error>;
-}
\ No newline at end of file
+    reply: func(reply-to: borrow<message>, message: message) -> result<_, error>;
+}
diff --git a/wit/types.wit b/wit/types.wit
index 45ce25b..0c0b82b 100644
--- a/wit/types.wit
+++ b/wit/types.wit
@@ -1,4 +1,10 @@
 interface types {
+    /// A type alias for list<tuple<string, string>> to represent metadata attached to a message
+    type metadata = list<tuple<string, string>>;
+
+    /// A type alias for string to represent a message topic
+    type topic = string;
+
     /// A connection to a message-exchange service (e.g., buffer, broker, etc.).
     resource client {
         connect: static func(name: string) -> result<client, error>;
@@ -21,9 +27,9 @@ interface types {
     resource message {
         constructor(topic: string, data: list<u8>);
         /// The topic/subject/channel this message was received or should be sent on
-        topic: func() -> string;
+        topic: func() -> topic;
         /// Set the topic/subject/channel this message should be sent on
-        set-topic: func(topic: string);
+        set-topic: func(topic: topic);
         /// An optional content-type describing the format of the data in the message. This is 
         /// sometimes described as the "format" type
         content-type: func() -> option<string>;
@@ -36,8 +42,10 @@ interface types {
         set-data: func(data: list<u8>);
         /// Optional metadata (also called headers or attributes in some systems) attached to the
         /// message
-        metadata: func() -> option<list<tuple<string, string>>>;
+        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);
+        /// Remove a key-value pair from the metadata
+        remove-metadata: func(key: string);
     }
-}
\ No newline at end of file
+}