├── wit
    ├── producer.wit
    ├── guest.wit
    ├── messaging.wit
    ├── types.wit
    └── request-reply.wit
├── .github
    └── workflows
    │   └── main.yml
├── README.md
├── messaging.md
├── imports.md
├── messaging-core.md
├── imports-request-reply.md
└── messaging-request-reply.md


/wit/producer.wit:
--------------------------------------------------------------------------------
1 | /// The producer interface is used to send messages to a channel/topic.
2 | interface producer {
3 |     use types.{client, message, error, topic};
4 |     
5 |     /// Sends the message using the given client.
6 |     send: func(c: borrow<client>, topic: topic, message: message) -> result<_, error>;
7 | }
8 | 


--------------------------------------------------------------------------------
/.github/workflows/main.yml:
--------------------------------------------------------------------------------
 1 | name: CI
 2 | on:
 3 |   push:
 4 |     branches: [main]
 5 |   pull_request:
 6 |     branches: [main]
 7 | 
 8 | jobs:
 9 |   abi-up-to-date:
10 |     name: Check ABI files are up-to-date
11 |     runs-on: ubuntu-latest
12 |     steps:
13 |     - uses: actions/checkout@v2
14 |     - uses: WebAssembly/wit-abi-up-to-date@v17
15 |       with:
16 |         wit-bindgen: '0.34.0'
17 |         worlds: 'imports imports-request-reply messaging-core messaging-request-reply'
18 | 


--------------------------------------------------------------------------------
/wit/guest.wit:
--------------------------------------------------------------------------------
 1 | interface incoming-handler {
 2 |     use types.{message, error, topic};
 3 | 
 4 |     /// Whenever this guest receives a message in one of the subscribed topics, the message is
 5 |     /// sent to this handler. The guest is responsible for matching on the topic and handling the
 6 |     /// message accordingly. Implementors (such as hosts) calling this interface should make their
 7 |     /// own decisions on how to handle errors returned from this function.
 8 |     handle: func(message: message) -> result<_, error>;
 9 | }
10 | 


--------------------------------------------------------------------------------
/wit/messaging.wit:
--------------------------------------------------------------------------------
 1 | package wasi:messaging@0.2.0-draft;
 2 | 
 3 | /// The `imports` world defines the interfaces that the component will import from the host.
 4 | /// It includes the `producer` interface for sending messages.
 5 | world imports {
 6 |   import producer;
 7 | }
 8 | 
 9 | /// The `imports-request-reply` world extends `imports` by including the `request-reply` interface.
10 | /// This allows the component to perform request/reply messaging patterns.
11 | world imports-request-reply {
12 |   include imports;
13 |   import request-reply;
14 | }
15 | 
16 | /// The `messaging-request-reply` world combines `imports-request-reply` with the `incoming-handler`
17 | /// export. This setup allows the host to interact with the component for both sending messages and
18 | /// handling incoming messages with request/reply capabilities.
19 | world messaging-request-reply {
20 |   include imports-request-reply;
21 |   export incoming-handler;
22 | }
23 | 
24 | /// The `messaging-core` world includes the basic `imports` and exports the `incoming-handler`,
25 | /// enabling the component to handle incoming messages without request/reply capabilities.
26 | world messaging-core {
27 |   include imports;
28 |   export incoming-handler;
29 | }
30 | 


--------------------------------------------------------------------------------
/wit/types.wit:
--------------------------------------------------------------------------------
 1 | interface types {
 2 |     /// A type alias for list<tuple<string, string>> to represent metadata attached to a message
 3 |     type metadata = list<tuple<string, string>>;
 4 | 
 5 |     /// A type alias for string to represent a message topic
 6 |     type topic = string;
 7 | 
 8 |     /// A connection to a message-exchange service (e.g., buffer, broker, etc.).
 9 |     resource client {
10 |         connect: static func(name: string) -> result<client, error>;
11 |         disconnect: func() -> result<_, error>;
12 |     }
13 |     
14 |     /// Errors that can occur when using the messaging interface.
15 |     variant error {
16 |         /// The request or operation timed out.
17 |         timeout,
18 |         /// An error occurred with the connection. Includes a message for additional context
19 |         connection(string),
20 |         /// A permission error occurred. Includes a message for additional context
21 |         permission-denied(string),
22 |         /// A catch all for other types of errors
23 |         other(string),
24 |     }
25 |   
26 |     /// A message with a binary payload and additional information
27 |     resource message {
28 |         constructor(data: list<u8>);
29 |         /// The topic/subject/channel this message was received on, if any
30 |         topic: func() -> option<topic>;
31 |         /// An optional content-type describing the format of the data in the message. This is 
32 |         /// sometimes described as the "format" type
33 |         content-type: func() -> option<string>;
34 |         /// Set the content-type describing the format of the data in the message. This is
35 |         /// sometimes described as the "format" type
36 |         set-content-type: func(content-type: string);
37 |         /// An opaque blob of data
38 |         data: func() -> list<u8>;
39 |         /// Set the opaque blob of data for this message, discarding the old value
40 |         set-data: func(data: list<u8>);
41 |         /// Optional metadata (also called headers or attributes in some systems) attached to the
42 |         /// message. This metadata is simply decoration and should not be interpreted by a host
43 |         /// to ensure portability across different implementors (e.g., Kafka -> NATS, etc.).
44 |         metadata: func() -> option<metadata>;
45 |         /// Add a new key-value pair to the metadata, overwriting any existing value for the same key
46 |         add-metadata: func(key: string, value: string);
47 |         /// Set the metadata
48 |         set-metadata: func(meta: metadata);
49 |         /// Remove a key-value pair from the metadata
50 |         remove-metadata: func(key: string);
51 |     }
52 | }
53 | 


--------------------------------------------------------------------------------
/wit/request-reply.wit:
--------------------------------------------------------------------------------
 1 | /// The request-reply interface allows a guest to send a message and await a response. This
 2 | /// interface is considered optional as not all message services support the concept of
 3 | /// request/reply. However, request/reply is a very common pattern in messaging and as such, we have
 4 | /// included it as a core interface.
 5 | interface request-reply {
 6 |     use types.{client, message, error, topic};
 7 | 
 8 |     /// Options for a request/reply operation. This is a resource to allow for future expansion of
 9 |     /// options.
10 |     resource request-options {
11 |         /// Creates a new request options resource with no options set.
12 |         constructor();
13 | 
14 |         /// The maximum amount of time to wait for a response. If the timeout value is not set, then
15 |         /// the request/reply operation will block until a message is received in response.
16 |         set-timeout-ms: func(timeout-ms: u32);
17 | 
18 |         /// The maximum number of replies to expect before returning.
19 |         set-expected-replies: func(expected-replies: u32);
20 |     }
21 | 
22 |     /// Performs a blocking request/reply operation with an optional set of request options. 
23 |     /// 
24 |     /// The behavior of this function is largely dependent on the options given to the function.
25 |     /// If no options are provided, then the request/reply operation will block until a single 
26 |     /// message is received in response. If a timeout is provided, then the request/reply operation
27 |     /// will block for the specified amount of time before returning an error if no messages were
28 |     /// received (or the list of messages that were received). If both a timeout and an expected
29 |     /// number of replies are provided, the function should return when either condition is met
30 |     /// (whichever comes first)—e.g., (1) if no replies were received within the timeout return an
31 |     /// error, (2) if the maximum expected number of replies were received before timeout, return
32 |     /// the list of messages, or (3) if the timeout is reached before the expected number of replies,
33 |     /// return the list of messages received up to that point.
34 |     request: func(c: borrow<client>, topic: topic, message: borrow<message>, options: option<request-options>) -> result<list<message>, error>;
35 | 
36 |     /// Replies to the given message with the given response message. The details of which topic
37 |     /// the message is sent to is up to the implementation. This allows for reply-to details to be
38 |     /// handled in the best way possible for the underlying messaging system.
39 |     /// 
40 |     /// Please note that this reply functionality is different than something like HTTP because there
41 |     /// are several use cases in which a reply might not be required for every message (so this would
42 |     /// be a noop). There are also cases when you might want to reply and then continue processing.
43 |     /// Additionally, you might want to reply to a message several times (such as providing an
44 |     /// update). So this function is allowed to be called multiple times, unlike something like HTTP
45 |     /// where the reply is sent and the connection is closed.
46 |     reply: func(reply-to: borrow<message>, message: message) -> result<_, error>;
47 | }
48 | 


--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
  1 | # `wasi-messaging`
  2 | 
  3 | A proposed [WebAssembly System Interface](https://github.com/WebAssembly/WASI) API.
  4 | 
  5 | ## Table of Contents
  6 | 
  7 | - [`wasi-messaging`](#wasi-messaging)
  8 |   - [Table of Contents](#table-of-contents)
  9 |   - [Current Phase](#current-phase)
 10 |   - [Champions](#champions)
 11 |   - [Phase 4 Advancement Criteria](#phase-4-advancement-criteria)
 12 |   - [Introduction](#introduction)
 13 |   - [Goals](#goals)
 14 |   - [Portability criteria](#portability-criteria)
 15 |   - [Dev notes](#dev-notes)
 16 | 
 17 | ## Current Phase
 18 | 
 19 | `wasi-messaging` is currently in [Phase
 20 | 1](https://github.com/WebAssembly/WASI/blob/main/Proposals.md#phase-1---feature-proposal-cg).
 21 | 
 22 | ## Champions
 23 | 
 24 | - [Dan Chiarlone](https://github.com/danbugs)
 25 | - [David Justice](https://github.com/devigned)
 26 | - [Jiaxiao Zhou](https://github.com/Mossaka)
 27 | 
 28 | ## Phase 4 Advancement Criteria
 29 | 
 30 | For `wasi-messaging` to advance to Phase 4, it must have at least two independent implementations 
 31 | for open-source message brokers (such as Kafka, NATS, MQTT brokers) and two for cloud service providers 
 32 | (e.g., Azure Service Bus, AWS SQS).
 33 | 
 34 | ## Introduction
 35 | 
 36 | In modern software systems, different components or applications often need to communicate with each other 
 37 | to exchange information and coordinate their actions. Messaging systems facilitate this communication by
 38 | allowing messages to be sent and received between different parts of a system.
 39 | 
 40 | However, implementing message-based communication can be challenging. It requires dealing with the details
 41 | of message brokers, such as connection management, channel setup, and message serialization. This complexity
 42 | can hinder development and lead to inconsistent implementations.
 43 | 
 44 | The `wasi-messaging` interface is a purposefully small interface focused purely on message passing. It is
 45 | designed to express the bare minimum of receiving a message and sending a message, along with an optional
 46 | request/reply interface that allows for message-based APIs and/or RPC.
 47 | 
 48 | By providing a standard way to interact with message brokers, the `wasi-messaging` interface aims to simplify
 49 | this process, hiding the underlying complexity from the user. This aligns with the broader goals of WASI by
 50 | promoting interoperability, modularity, and security in WebAssembly applications.
 51 | 
 52 | ## Goals
 53 | 
 54 | The primary goal of this interface is to focus on message passing. The only guarantee offered is 
 55 | that publishing a message is handled successfully. No other guarantees are made about the delivery 
 56 | of the message or being able to ack/nack a message directly. This minimalist approach provides the 
 57 | most basic foundation of messaging, which can be expanded upon by future interfaces or proposals as 
 58 | use cases emerge.
 59 | 
 60 | This simplicity allows:
 61 | - **Ease of Integration**: Components can easily implement the message handler in this interface, 
 62 | with details such as work dispatch and queuing handled behind the scenes, invisible to the business logic.
 63 | - **Flexibility**: Anything that can send a message can easily be passed into a queue 
 64 | (such as a Kafka stream or NATS JetStream) without the knowledge that it is being sent into a queue.
 65 | - **Extensibility**: The paradigm can be expanded by future interfaces (like a queue-based work interface) to handle 
 66 | more complex messaging scenarios. By focusing solely on message passing, the wasi-messaging interface simplifies the 
 67 | development of interoperable WebAssembly modules that can communicate over various messaging systems without being 
 68 | tied to any specific implementation.
 69 | 
 70 | ## Portability criteria
 71 | 
 72 | The main portability criteria on which this should be judged is whether a component can receive and send a message 
 73 | from all major messaging systems. This includes:
 74 | - Message standards like MQTT and AMQP.
 75 | - Specific technologies like NATS and Kafka.
 76 | - Cloud provider implementations like Azure Service Bus and AWS SQS.
 77 | 
 78 | This _does not_ mean it implements the full set of features of each of the messaging systems. In fact, it is expected 
 79 | that most implementations will need to do work to adapt their system to this interface (e.g., in Kafka, you'd have 
 80 | to mark the message as completed once the call to handle returns).
 81 | 
 82 | As mentioned above, this should still be completely compatible with any more advanced use cases of the various 
 83 | message systems. For example, if you have a queue of work that is currently being handled by pre-existing software
 84 | outside of Wasm components, a component could use this interface to publish messages that get ingested into this queue.
 85 | 
 86 | Another way to state the portability criteria is that this implementation should not break the possibility of a 
 87 | component consuming this interface to be integrated with a more advanced messaging use case.
 88 | 
 89 | ## Dev notes
 90 | 
 91 | To regenerate the `.md` files, run: 
 92 | ```sh
 93 | wit-bindgen markdown ./wit/ -w imports --html-in-md
 94 | wit-bindgen markdown ./wit/ -w imports-request-reply --html-in-md
 95 | wit-bindgen markdown ./wit/ -w messaging-core --html-in-md
 96 | wit-bindgen markdown ./wit/ -w messaging-request-reply --html-in-md
 97 | ```
 98 | 
 99 | It would make sense for a lot of these functions to be asynchronous, but that is not currently natively supported in 
100 | the component model. Asynchronous support will be added as part of WASI Preview 3. When async support becomes 
101 | available, we plan to update the wasi-messaging interface to incorporate asynchronous patterns.
102 | 
103 | > **Note**: Ensure you have version 0.34.0 of `wit-bindgen` installed to avoid compatibility issues.
104 | 


--------------------------------------------------------------------------------
/messaging.md:
--------------------------------------------------------------------------------
  1 | <h1><a id="messaging"></a>World messaging</h1>
  2 | <ul>
  3 | <li>Imports:
  4 | <ul>
  5 | <li>interface <a href="#wasi_messaging_types_0_2_0_draft"><code>wasi:messaging/types@0.2.0-draft</code></a></li>
  6 | <li>interface <a href="#wasi_messaging_producer_0_2_0_draft"><code>wasi:messaging/producer@0.2.0-draft</code></a></li>
  7 | </ul>
  8 | </li>
  9 | <li>Exports:
 10 | <ul>
 11 | <li>interface <a href="#wasi_messaging_incoming_handler_0_2_0_draft"><code>wasi:messaging/incoming-handler@0.2.0-draft</code></a></li>
 12 | </ul>
 13 | </li>
 14 | </ul>
 15 | <h2><a id="wasi_messaging_types_0_2_0_draft"></a>Import interface wasi:messaging/types@0.2.0-draft</h2>
 16 | <hr />
 17 | <h3>Types</h3>
 18 | <h4><a id="client"></a><code>resource client</code></h4>
 19 | <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
 20 | <h4><a id="error"></a><code>variant error</code></h4>
 21 | <p>Errors that can occur when using the messaging interface.</p>
 22 | <h5>Variant Cases</h5>
 23 | <ul>
 24 | <li>
 25 | <p><a id="error.timeout"></a><code>timeout</code></p>
 26 | <p>The request or operation timed out.
 27 | </li>
 28 | <li>
 29 | <p><a id="error.connection"></a><code>connection</code>: <code>string</code></p>
 30 | <p>An error occurred with the connection. Includes a message for additional context
 31 | </li>
 32 | <li>
 33 | <p><a id="error.other"></a><code>other</code>: <code>string</code></p>
 34 | <p>A catch all for other types of errors
 35 | </li>
 36 | </ul>
 37 | <h4><a id="message"></a><code>resource message</code></h4>
 38 | <h2>A message with a binary payload and additional information</h2>
 39 | <h3>Functions</h3>
 40 | <h4><a id="static_client_connect"></a><code>[static]client.connect: func</code></h4>
 41 | <h5>Params</h5>
 42 | <ul>
 43 | <li><a id="static_client_connect.name"></a><code>name</code>: <code>string</code></li>
 44 | </ul>
 45 | <h5>Return values</h5>
 46 | <ul>
 47 | <li><a id="static_client_connect.0"></a> result&lt;own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 48 | </ul>
 49 | <h4><a id="constructor_message"></a><code>[constructor]message: func</code></h4>
 50 | <h5>Params</h5>
 51 | <ul>
 52 | <li><a id="constructor_message.topic"></a><code>topic</code>: <code>string</code></li>
 53 | <li><a id="constructor_message.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
 54 | </ul>
 55 | <h5>Return values</h5>
 56 | <ul>
 57 | <li><a id="constructor_message.0"></a> own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 58 | </ul>
 59 | <h4><a id="method_message_topic"></a><code>[method]message.topic: func</code></h4>
 60 | <p>The topic/subject/channel this message was received or should be sent on</p>
 61 | <h5>Params</h5>
 62 | <ul>
 63 | <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>
 64 | </ul>
 65 | <h5>Return values</h5>
 66 | <ul>
 67 | <li><a id="method_message_topic.0"></a> <code>string</code></li>
 68 | </ul>
 69 | <h4><a id="method_message_set_topic"></a><code>[method]message.set-topic: func</code></h4>
 70 | <p>Set the topic/subject/channel this message should be sent on</p>
 71 | <h5>Params</h5>
 72 | <ul>
 73 | <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>
 74 | <li><a id="method_message_set_topic.topic"></a><code>topic</code>: <code>string</code></li>
 75 | </ul>
 76 | <h4><a id="method_message_content_type"></a><code>[method]message.content-type: func</code></h4>
 77 | <p>An optional content-type describing the format of the data in the message. This is
 78 | sometimes described as the &quot;format&quot; type</p>
 79 | <h5>Params</h5>
 80 | <ul>
 81 | <li><a id="method_message_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 82 | </ul>
 83 | <h5>Return values</h5>
 84 | <ul>
 85 | <li><a id="method_message_content_type.0"></a> option&lt;<code>string</code>&gt;</li>
 86 | </ul>
 87 | <h4><a id="method_message_set_content_type"></a><code>[method]message.set-content-type: func</code></h4>
 88 | <p>Set the content-type describing the format of the data in the message. This is
 89 | sometimes described as the &quot;format&quot; type</p>
 90 | <h5>Params</h5>
 91 | <ul>
 92 | <li><a id="method_message_set_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 93 | <li><a id="method_message_set_content_type.content_type"></a><code>content-type</code>: <code>string</code></li>
 94 | </ul>
 95 | <h4><a id="method_message_data"></a><code>[method]message.data: func</code></h4>
 96 | <p>An opaque blob of data</p>
 97 | <h5>Params</h5>
 98 | <ul>
 99 | <li><a id="method_message_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
100 | </ul>
101 | <h5>Return values</h5>
102 | <ul>
103 | <li><a id="method_message_data.0"></a> list&lt;<code>u8</code>&gt;</li>
104 | </ul>
105 | <h4><a id="method_message_set_data"></a><code>[method]message.set-data: func</code></h4>
106 | <p>Set the opaque blob of data for this message, discarding the old value</p>
107 | <h5>Params</h5>
108 | <ul>
109 | <li><a id="method_message_set_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
110 | <li><a id="method_message_set_data.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
111 | </ul>
112 | <h4><a id="method_message_metadata"></a><code>[method]message.metadata: func</code></h4>
113 | <p>Optional metadata (also called headers or attributes in some systems) attached to the
114 | message</p>
115 | <h5>Params</h5>
116 | <ul>
117 | <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>
118 | </ul>
119 | <h5>Return values</h5>
120 | <ul>
121 | <li><a id="method_message_metadata.0"></a> option&lt;list&lt;(<code>string</code>, <code>string</code>)&gt;&gt;</li>
122 | </ul>
123 | <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
124 | <p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
125 | <h5>Params</h5>
126 | <ul>
127 | <li><a id="method_message_add_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
128 | <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
129 | <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
130 | </ul>
131 | <h2><a id="wasi_messaging_producer_0_2_0_draft"></a>Import interface wasi:messaging/producer@0.2.0-draft</h2>
132 | <p>The producer interface is used to send messages to a channel/topic.</p>
133 | <hr />
134 | <h3>Types</h3>
135 | <h4><a id="client"></a><code>type client</code></h4>
136 | <p><a href="#client"><a href="#client"><code>client</code></a></a></p>
137 | <p>
138 | #### <a id="message"></a>`type message`
139 | [`message`](#message)
140 | <p>
141 | #### <a id="error"></a>`type error`
142 | [`error`](#error)
143 | <p>
144 | ----
145 | <h3>Functions</h3>
146 | <h4><a id="send"></a><code>send: func</code></h4>
147 | <p>Sends the message using the given client.</p>
148 | <h5>Params</h5>
149 | <ul>
150 | <li><a id="send.c"></a><code>c</code>: own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
151 | <li><a id="send.m"></a><code>m</code>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
152 | </ul>
153 | <h5>Return values</h5>
154 | <ul>
155 | <li><a id="send.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
156 | </ul>
157 | <h2><a id="wasi_messaging_incoming_handler_0_2_0_draft"></a>Export interface wasi:messaging/incoming-handler@0.2.0-draft</h2>
158 | <hr />
159 | <h3>Types</h3>
160 | <h4><a id="message"></a><code>type message</code></h4>
161 | <p><a href="#message"><a href="#message"><code>message</code></a></a></p>
162 | <p>
163 | #### <a id="error"></a>`type error`
164 | [`error`](#error)
165 | <p>
166 | ----
167 | <h3>Functions</h3>
168 | <h4><a id="handle"></a><code>handle: func</code></h4>
169 | <p>Whenever this guest receives a message in one of the subscribed channels, the message is
170 | sent to this handler. The guest is responsible for matching on the channel and handling the
171 | message accordingly. Implementors (such as hosts) calling this interface should make their
172 | own decisions on how to handle errors returned from this function.</p>
173 | <h5>Params</h5>
174 | <ul>
175 | <li><a id="handle.ms"></a><code>ms</code>: own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
176 | </ul>
177 | <h5>Return values</h5>
178 | <ul>
179 | <li><a id="handle.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
180 | </ul>
181 | <h4><a id="subscribe"></a><code>subscribe: func</code></h4>
182 | <p>Subscribe to a list of topics (represented as <code>string</code>s) at runtime.
183 | Implementors should consider also allowing subscriptions to be made at compile time via
184 | some sort of configuration file.</p>
185 | <h5>Return values</h5>
186 | <ul>
187 | <li><a id="subscribe.0"></a> result&lt;list&lt;<code>string</code>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
188 | </ul>
189 | 


--------------------------------------------------------------------------------
/imports.md:
--------------------------------------------------------------------------------
  1 | <h1><a id="imports"></a>World imports</h1>
  2 | <p>The <a href="#imports"><code>imports</code></a> world defines the interfaces that the component will import from the host.
  3 | It includes the <code>producer</code> interface for sending messages.</p>
  4 | <ul>
  5 | <li>Imports:
  6 | <ul>
  7 | <li>interface <a href="#wasi_messaging_types_0_2_0_draft"><code>wasi:messaging/types@0.2.0-draft</code></a></li>
  8 | <li>interface <a href="#wasi_messaging_producer_0_2_0_draft"><code>wasi:messaging/producer@0.2.0-draft</code></a></li>
  9 | </ul>
 10 | </li>
 11 | </ul>
 12 | <h2><a id="wasi_messaging_types_0_2_0_draft"></a>Import interface wasi:messaging/types@0.2.0-draft</h2>
 13 | <hr />
 14 | <h3>Types</h3>
 15 | <h4><a id="metadata"></a><code>type metadata</code></h4>
 16 | <p><a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></p>
 17 | <p>A type alias for list<tuple<string, string>> to represent metadata attached to a message
 18 | <h4><a id="topic"></a><code>type topic</code></h4>
 19 | <p><code>string</code></p>
 20 | <p>A type alias for string to represent a message topic
 21 | <h4><a id="client"></a><code>resource client</code></h4>
 22 | <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
 23 | <h4><a id="error"></a><code>variant error</code></h4>
 24 | <p>Errors that can occur when using the messaging interface.</p>
 25 | <h5>Variant Cases</h5>
 26 | <ul>
 27 | <li>
 28 | <p><a id="error.timeout"></a><code>timeout</code></p>
 29 | <p>The request or operation timed out.
 30 | </li>
 31 | <li>
 32 | <p><a id="error.connection"></a><code>connection</code>: <code>string</code></p>
 33 | <p>An error occurred with the connection. Includes a message for additional context
 34 | </li>
 35 | <li>
 36 | <p><a id="error.permission_denied"></a><code>permission-denied</code>: <code>string</code></p>
 37 | <p>A permission error occurred. Includes a message for additional context
 38 | </li>
 39 | <li>
 40 | <p><a id="error.other"></a><code>other</code>: <code>string</code></p>
 41 | <p>A catch all for other types of errors
 42 | </li>
 43 | </ul>
 44 | <h4><a id="message"></a><code>resource message</code></h4>
 45 | <h2>A message with a binary payload and additional information</h2>
 46 | <h3>Functions</h3>
 47 | <h4><a id="static_client_connect"></a><code>[static]client.connect: func</code></h4>
 48 | <h5>Params</h5>
 49 | <ul>
 50 | <li><a id="static_client_connect.name"></a><code>name</code>: <code>string</code></li>
 51 | </ul>
 52 | <h5>Return values</h5>
 53 | <ul>
 54 | <li><a id="static_client_connect.0"></a> result&lt;own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 55 | </ul>
 56 | <h4><a id="method_client_disconnect"></a><code>[method]client.disconnect: func</code></h4>
 57 | <h5>Params</h5>
 58 | <ul>
 59 | <li><a id="method_client_disconnect.self"></a><code>self</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
 60 | </ul>
 61 | <h5>Return values</h5>
 62 | <ul>
 63 | <li><a id="method_client_disconnect.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 64 | </ul>
 65 | <h4><a id="constructor_message"></a><code>[constructor]message: func</code></h4>
 66 | <h5>Params</h5>
 67 | <ul>
 68 | <li><a id="constructor_message.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
 69 | </ul>
 70 | <h5>Return values</h5>
 71 | <ul>
 72 | <li><a id="constructor_message.0"></a> own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 73 | </ul>
 74 | <h4><a id="method_message_topic"></a><code>[method]message.topic: func</code></h4>
 75 | <p>The topic/subject/channel this message was received on, if any</p>
 76 | <h5>Params</h5>
 77 | <ul>
 78 | <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>
 79 | </ul>
 80 | <h5>Return values</h5>
 81 | <ul>
 82 | <li><a id="method_message_topic.0"></a> option&lt;<a href="#topic"><a href="#topic"><code>topic</code></a></a>&gt;</li>
 83 | </ul>
 84 | <h4><a id="method_message_content_type"></a><code>[method]message.content-type: func</code></h4>
 85 | <p>An optional content-type describing the format of the data in the message. This is
 86 | sometimes described as the &quot;format&quot; type</p>
 87 | <h5>Params</h5>
 88 | <ul>
 89 | <li><a id="method_message_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 90 | </ul>
 91 | <h5>Return values</h5>
 92 | <ul>
 93 | <li><a id="method_message_content_type.0"></a> option&lt;<code>string</code>&gt;</li>
 94 | </ul>
 95 | <h4><a id="method_message_set_content_type"></a><code>[method]message.set-content-type: func</code></h4>
 96 | <p>Set the content-type describing the format of the data in the message. This is
 97 | sometimes described as the &quot;format&quot; type</p>
 98 | <h5>Params</h5>
 99 | <ul>
100 | <li><a id="method_message_set_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
101 | <li><a id="method_message_set_content_type.content_type"></a><code>content-type</code>: <code>string</code></li>
102 | </ul>
103 | <h4><a id="method_message_data"></a><code>[method]message.data: func</code></h4>
104 | <p>An opaque blob of data</p>
105 | <h5>Params</h5>
106 | <ul>
107 | <li><a id="method_message_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
108 | </ul>
109 | <h5>Return values</h5>
110 | <ul>
111 | <li><a id="method_message_data.0"></a> list&lt;<code>u8</code>&gt;</li>
112 | </ul>
113 | <h4><a id="method_message_set_data"></a><code>[method]message.set-data: func</code></h4>
114 | <p>Set the opaque blob of data for this message, discarding the old value</p>
115 | <h5>Params</h5>
116 | <ul>
117 | <li><a id="method_message_set_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
118 | <li><a id="method_message_set_data.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
119 | </ul>
120 | <h4><a id="method_message_metadata"></a><code>[method]message.metadata: func</code></h4>
121 | <p>Optional metadata (also called headers or attributes in some systems) attached to the
122 | message. This metadata is simply decoration and should not be interpreted by a host
123 | to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc.).</p>
124 | <h5>Params</h5>
125 | <ul>
126 | <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>
127 | </ul>
128 | <h5>Return values</h5>
129 | <ul>
130 | <li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
131 | </ul>
132 | <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
133 | <p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
134 | <h5>Params</h5>
135 | <ul>
136 | <li><a id="method_message_add_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
137 | <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
138 | <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
139 | </ul>
140 | <h4><a id="method_message_set_metadata"></a><code>[method]message.set-metadata: func</code></h4>
141 | <p>Set the metadata</p>
142 | <h5>Params</h5>
143 | <ul>
144 | <li><a id="method_message_set_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
145 | <li><a id="method_message_set_metadata.meta"></a><code>meta</code>: <a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></li>
146 | </ul>
147 | <h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
148 | <p>Remove a key-value pair from the metadata</p>
149 | <h5>Params</h5>
150 | <ul>
151 | <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>
152 | <li><a id="method_message_remove_metadata.key"></a><code>key</code>: <code>string</code></li>
153 | </ul>
154 | <h2><a id="wasi_messaging_producer_0_2_0_draft"></a>Import interface wasi:messaging/producer@0.2.0-draft</h2>
155 | <p>The producer interface is used to send messages to a channel/topic.</p>
156 | <hr />
157 | <h3>Types</h3>
158 | <h4><a id="client"></a><code>type client</code></h4>
159 | <p><a href="#client"><a href="#client"><code>client</code></a></a></p>
160 | <p>
161 | #### <a id="message"></a>`type message`
162 | [`message`](#message)
163 | <p>
164 | #### <a id="error"></a>`type error`
165 | [`error`](#error)
166 | <p>
167 | #### <a id="topic"></a>`type topic`
168 | [`topic`](#topic)
169 | <p>
170 | ----
171 | <h3>Functions</h3>
172 | <h4><a id="send"></a><code>send: func</code></h4>
173 | <p>Sends the message using the given client.</p>
174 | <h5>Params</h5>
175 | <ul>
176 | <li><a id="send.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
177 | <li><a id="send.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
178 | <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>
179 | </ul>
180 | <h5>Return values</h5>
181 | <ul>
182 | <li><a id="send.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
183 | </ul>
184 | 


--------------------------------------------------------------------------------
/messaging-core.md:
--------------------------------------------------------------------------------
  1 | <h1><a id="messaging_core"></a>World messaging-core</h1>
  2 | <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>,
  3 | enabling the component to handle incoming messages without request/reply capabilities.</p>
  4 | <ul>
  5 | <li>Imports:
  6 | <ul>
  7 | <li>interface <a href="#wasi_messaging_types_0_2_0_draft"><code>wasi:messaging/types@0.2.0-draft</code></a></li>
  8 | <li>interface <a href="#wasi_messaging_producer_0_2_0_draft"><code>wasi:messaging/producer@0.2.0-draft</code></a></li>
  9 | </ul>
 10 | </li>
 11 | <li>Exports:
 12 | <ul>
 13 | <li>interface <a href="#wasi_messaging_incoming_handler_0_2_0_draft"><code>wasi:messaging/incoming-handler@0.2.0-draft</code></a></li>
 14 | </ul>
 15 | </li>
 16 | </ul>
 17 | <h2><a id="wasi_messaging_types_0_2_0_draft"></a>Import interface wasi:messaging/types@0.2.0-draft</h2>
 18 | <hr />
 19 | <h3>Types</h3>
 20 | <h4><a id="metadata"></a><code>type metadata</code></h4>
 21 | <p><a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></p>
 22 | <p>A type alias for list<tuple<string, string>> to represent metadata attached to a message
 23 | <h4><a id="topic"></a><code>type topic</code></h4>
 24 | <p><code>string</code></p>
 25 | <p>A type alias for string to represent a message topic
 26 | <h4><a id="client"></a><code>resource client</code></h4>
 27 | <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
 28 | <h4><a id="error"></a><code>variant error</code></h4>
 29 | <p>Errors that can occur when using the messaging interface.</p>
 30 | <h5>Variant Cases</h5>
 31 | <ul>
 32 | <li>
 33 | <p><a id="error.timeout"></a><code>timeout</code></p>
 34 | <p>The request or operation timed out.
 35 | </li>
 36 | <li>
 37 | <p><a id="error.connection"></a><code>connection</code>: <code>string</code></p>
 38 | <p>An error occurred with the connection. Includes a message for additional context
 39 | </li>
 40 | <li>
 41 | <p><a id="error.permission_denied"></a><code>permission-denied</code>: <code>string</code></p>
 42 | <p>A permission error occurred. Includes a message for additional context
 43 | </li>
 44 | <li>
 45 | <p><a id="error.other"></a><code>other</code>: <code>string</code></p>
 46 | <p>A catch all for other types of errors
 47 | </li>
 48 | </ul>
 49 | <h4><a id="message"></a><code>resource message</code></h4>
 50 | <h2>A message with a binary payload and additional information</h2>
 51 | <h3>Functions</h3>
 52 | <h4><a id="static_client_connect"></a><code>[static]client.connect: func</code></h4>
 53 | <h5>Params</h5>
 54 | <ul>
 55 | <li><a id="static_client_connect.name"></a><code>name</code>: <code>string</code></li>
 56 | </ul>
 57 | <h5>Return values</h5>
 58 | <ul>
 59 | <li><a id="static_client_connect.0"></a> result&lt;own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 60 | </ul>
 61 | <h4><a id="method_client_disconnect"></a><code>[method]client.disconnect: func</code></h4>
 62 | <h5>Params</h5>
 63 | <ul>
 64 | <li><a id="method_client_disconnect.self"></a><code>self</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
 65 | </ul>
 66 | <h5>Return values</h5>
 67 | <ul>
 68 | <li><a id="method_client_disconnect.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 69 | </ul>
 70 | <h4><a id="constructor_message"></a><code>[constructor]message: func</code></h4>
 71 | <h5>Params</h5>
 72 | <ul>
 73 | <li><a id="constructor_message.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
 74 | </ul>
 75 | <h5>Return values</h5>
 76 | <ul>
 77 | <li><a id="constructor_message.0"></a> own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 78 | </ul>
 79 | <h4><a id="method_message_topic"></a><code>[method]message.topic: func</code></h4>
 80 | <p>The topic/subject/channel this message was received on, if any</p>
 81 | <h5>Params</h5>
 82 | <ul>
 83 | <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>
 84 | </ul>
 85 | <h5>Return values</h5>
 86 | <ul>
 87 | <li><a id="method_message_topic.0"></a> option&lt;<a href="#topic"><a href="#topic"><code>topic</code></a></a>&gt;</li>
 88 | </ul>
 89 | <h4><a id="method_message_content_type"></a><code>[method]message.content-type: func</code></h4>
 90 | <p>An optional content-type describing the format of the data in the message. This is
 91 | sometimes described as the &quot;format&quot; type</p>
 92 | <h5>Params</h5>
 93 | <ul>
 94 | <li><a id="method_message_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 95 | </ul>
 96 | <h5>Return values</h5>
 97 | <ul>
 98 | <li><a id="method_message_content_type.0"></a> option&lt;<code>string</code>&gt;</li>
 99 | </ul>
100 | <h4><a id="method_message_set_content_type"></a><code>[method]message.set-content-type: func</code></h4>
101 | <p>Set the content-type describing the format of the data in the message. This is
102 | sometimes described as the &quot;format&quot; type</p>
103 | <h5>Params</h5>
104 | <ul>
105 | <li><a id="method_message_set_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
106 | <li><a id="method_message_set_content_type.content_type"></a><code>content-type</code>: <code>string</code></li>
107 | </ul>
108 | <h4><a id="method_message_data"></a><code>[method]message.data: func</code></h4>
109 | <p>An opaque blob of data</p>
110 | <h5>Params</h5>
111 | <ul>
112 | <li><a id="method_message_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
113 | </ul>
114 | <h5>Return values</h5>
115 | <ul>
116 | <li><a id="method_message_data.0"></a> list&lt;<code>u8</code>&gt;</li>
117 | </ul>
118 | <h4><a id="method_message_set_data"></a><code>[method]message.set-data: func</code></h4>
119 | <p>Set the opaque blob of data for this message, discarding the old value</p>
120 | <h5>Params</h5>
121 | <ul>
122 | <li><a id="method_message_set_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
123 | <li><a id="method_message_set_data.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
124 | </ul>
125 | <h4><a id="method_message_metadata"></a><code>[method]message.metadata: func</code></h4>
126 | <p>Optional metadata (also called headers or attributes in some systems) attached to the
127 | message. This metadata is simply decoration and should not be interpreted by a host
128 | to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc.).</p>
129 | <h5>Params</h5>
130 | <ul>
131 | <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>
132 | </ul>
133 | <h5>Return values</h5>
134 | <ul>
135 | <li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
136 | </ul>
137 | <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
138 | <p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
139 | <h5>Params</h5>
140 | <ul>
141 | <li><a id="method_message_add_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
142 | <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
143 | <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
144 | </ul>
145 | <h4><a id="method_message_set_metadata"></a><code>[method]message.set-metadata: func</code></h4>
146 | <p>Set the metadata</p>
147 | <h5>Params</h5>
148 | <ul>
149 | <li><a id="method_message_set_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
150 | <li><a id="method_message_set_metadata.meta"></a><code>meta</code>: <a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></li>
151 | </ul>
152 | <h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
153 | <p>Remove a key-value pair from the metadata</p>
154 | <h5>Params</h5>
155 | <ul>
156 | <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>
157 | <li><a id="method_message_remove_metadata.key"></a><code>key</code>: <code>string</code></li>
158 | </ul>
159 | <h2><a id="wasi_messaging_producer_0_2_0_draft"></a>Import interface wasi:messaging/producer@0.2.0-draft</h2>
160 | <p>The producer interface is used to send messages to a channel/topic.</p>
161 | <hr />
162 | <h3>Types</h3>
163 | <h4><a id="client"></a><code>type client</code></h4>
164 | <p><a href="#client"><a href="#client"><code>client</code></a></a></p>
165 | <p>
166 | #### <a id="message"></a>`type message`
167 | [`message`](#message)
168 | <p>
169 | #### <a id="error"></a>`type error`
170 | [`error`](#error)
171 | <p>
172 | #### <a id="topic"></a>`type topic`
173 | [`topic`](#topic)
174 | <p>
175 | ----
176 | <h3>Functions</h3>
177 | <h4><a id="send"></a><code>send: func</code></h4>
178 | <p>Sends the message using the given client.</p>
179 | <h5>Params</h5>
180 | <ul>
181 | <li><a id="send.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
182 | <li><a id="send.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
183 | <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>
184 | </ul>
185 | <h5>Return values</h5>
186 | <ul>
187 | <li><a id="send.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
188 | </ul>
189 | <h2><a id="wasi_messaging_incoming_handler_0_2_0_draft"></a>Export interface wasi:messaging/incoming-handler@0.2.0-draft</h2>
190 | <hr />
191 | <h3>Types</h3>
192 | <h4><a id="message"></a><code>type message</code></h4>
193 | <p><a href="#message"><a href="#message"><code>message</code></a></a></p>
194 | <p>
195 | #### <a id="error"></a>`type error`
196 | [`error`](#error)
197 | <p>
198 | #### <a id="topic"></a>`type topic`
199 | [`topic`](#topic)
200 | <p>
201 | ----
202 | <h3>Functions</h3>
203 | <h4><a id="handle"></a><code>handle: func</code></h4>
204 | <p>Whenever this guest receives a message in one of the subscribed topics, the message is
205 | sent to this handler. The guest is responsible for matching on the topic and handling the
206 | message accordingly. Implementors (such as hosts) calling this interface should make their
207 | own decisions on how to handle errors returned from this function.</p>
208 | <h5>Params</h5>
209 | <ul>
210 | <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>
211 | </ul>
212 | <h5>Return values</h5>
213 | <ul>
214 | <li><a id="handle.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
215 | </ul>
216 | 


--------------------------------------------------------------------------------
/imports-request-reply.md:
--------------------------------------------------------------------------------
  1 | <h1><a id="imports_request_reply"></a>World imports-request-reply</h1>
  2 | <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.
  3 | This allows the component to perform request/reply messaging patterns.</p>
  4 | <ul>
  5 | <li>Imports:
  6 | <ul>
  7 | <li>interface <a href="#wasi_messaging_types_0_2_0_draft"><code>wasi:messaging/types@0.2.0-draft</code></a></li>
  8 | <li>interface <a href="#wasi_messaging_request_reply_0_2_0_draft"><code>wasi:messaging/request-reply@0.2.0-draft</code></a></li>
  9 | <li>interface <a href="#wasi_messaging_producer_0_2_0_draft"><code>wasi:messaging/producer@0.2.0-draft</code></a></li>
 10 | </ul>
 11 | </li>
 12 | </ul>
 13 | <h2><a id="wasi_messaging_types_0_2_0_draft"></a>Import interface wasi:messaging/types@0.2.0-draft</h2>
 14 | <hr />
 15 | <h3>Types</h3>
 16 | <h4><a id="metadata"></a><code>type metadata</code></h4>
 17 | <p><a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></p>
 18 | <p>A type alias for list<tuple<string, string>> to represent metadata attached to a message
 19 | <h4><a id="topic"></a><code>type topic</code></h4>
 20 | <p><code>string</code></p>
 21 | <p>A type alias for string to represent a message topic
 22 | <h4><a id="client"></a><code>resource client</code></h4>
 23 | <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
 24 | <h4><a id="error"></a><code>variant error</code></h4>
 25 | <p>Errors that can occur when using the messaging interface.</p>
 26 | <h5>Variant Cases</h5>
 27 | <ul>
 28 | <li>
 29 | <p><a id="error.timeout"></a><code>timeout</code></p>
 30 | <p>The request or operation timed out.
 31 | </li>
 32 | <li>
 33 | <p><a id="error.connection"></a><code>connection</code>: <code>string</code></p>
 34 | <p>An error occurred with the connection. Includes a message for additional context
 35 | </li>
 36 | <li>
 37 | <p><a id="error.permission_denied"></a><code>permission-denied</code>: <code>string</code></p>
 38 | <p>A permission error occurred. Includes a message for additional context
 39 | </li>
 40 | <li>
 41 | <p><a id="error.other"></a><code>other</code>: <code>string</code></p>
 42 | <p>A catch all for other types of errors
 43 | </li>
 44 | </ul>
 45 | <h4><a id="message"></a><code>resource message</code></h4>
 46 | <h2>A message with a binary payload and additional information</h2>
 47 | <h3>Functions</h3>
 48 | <h4><a id="static_client_connect"></a><code>[static]client.connect: func</code></h4>
 49 | <h5>Params</h5>
 50 | <ul>
 51 | <li><a id="static_client_connect.name"></a><code>name</code>: <code>string</code></li>
 52 | </ul>
 53 | <h5>Return values</h5>
 54 | <ul>
 55 | <li><a id="static_client_connect.0"></a> result&lt;own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 56 | </ul>
 57 | <h4><a id="method_client_disconnect"></a><code>[method]client.disconnect: func</code></h4>
 58 | <h5>Params</h5>
 59 | <ul>
 60 | <li><a id="method_client_disconnect.self"></a><code>self</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
 61 | </ul>
 62 | <h5>Return values</h5>
 63 | <ul>
 64 | <li><a id="method_client_disconnect.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 65 | </ul>
 66 | <h4><a id="constructor_message"></a><code>[constructor]message: func</code></h4>
 67 | <h5>Params</h5>
 68 | <ul>
 69 | <li><a id="constructor_message.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
 70 | </ul>
 71 | <h5>Return values</h5>
 72 | <ul>
 73 | <li><a id="constructor_message.0"></a> own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 74 | </ul>
 75 | <h4><a id="method_message_topic"></a><code>[method]message.topic: func</code></h4>
 76 | <p>The topic/subject/channel this message was received on, if any</p>
 77 | <h5>Params</h5>
 78 | <ul>
 79 | <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>
 80 | </ul>
 81 | <h5>Return values</h5>
 82 | <ul>
 83 | <li><a id="method_message_topic.0"></a> option&lt;<a href="#topic"><a href="#topic"><code>topic</code></a></a>&gt;</li>
 84 | </ul>
 85 | <h4><a id="method_message_content_type"></a><code>[method]message.content-type: func</code></h4>
 86 | <p>An optional content-type describing the format of the data in the message. This is
 87 | sometimes described as the &quot;format&quot; type</p>
 88 | <h5>Params</h5>
 89 | <ul>
 90 | <li><a id="method_message_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 91 | </ul>
 92 | <h5>Return values</h5>
 93 | <ul>
 94 | <li><a id="method_message_content_type.0"></a> option&lt;<code>string</code>&gt;</li>
 95 | </ul>
 96 | <h4><a id="method_message_set_content_type"></a><code>[method]message.set-content-type: func</code></h4>
 97 | <p>Set the content-type describing the format of the data in the message. This is
 98 | sometimes described as the &quot;format&quot; type</p>
 99 | <h5>Params</h5>
100 | <ul>
101 | <li><a id="method_message_set_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
102 | <li><a id="method_message_set_content_type.content_type"></a><code>content-type</code>: <code>string</code></li>
103 | </ul>
104 | <h4><a id="method_message_data"></a><code>[method]message.data: func</code></h4>
105 | <p>An opaque blob of data</p>
106 | <h5>Params</h5>
107 | <ul>
108 | <li><a id="method_message_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
109 | </ul>
110 | <h5>Return values</h5>
111 | <ul>
112 | <li><a id="method_message_data.0"></a> list&lt;<code>u8</code>&gt;</li>
113 | </ul>
114 | <h4><a id="method_message_set_data"></a><code>[method]message.set-data: func</code></h4>
115 | <p>Set the opaque blob of data for this message, discarding the old value</p>
116 | <h5>Params</h5>
117 | <ul>
118 | <li><a id="method_message_set_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
119 | <li><a id="method_message_set_data.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
120 | </ul>
121 | <h4><a id="method_message_metadata"></a><code>[method]message.metadata: func</code></h4>
122 | <p>Optional metadata (also called headers or attributes in some systems) attached to the
123 | message. This metadata is simply decoration and should not be interpreted by a host
124 | to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc.).</p>
125 | <h5>Params</h5>
126 | <ul>
127 | <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>
128 | </ul>
129 | <h5>Return values</h5>
130 | <ul>
131 | <li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
132 | </ul>
133 | <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
134 | <p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
135 | <h5>Params</h5>
136 | <ul>
137 | <li><a id="method_message_add_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
138 | <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
139 | <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
140 | </ul>
141 | <h4><a id="method_message_set_metadata"></a><code>[method]message.set-metadata: func</code></h4>
142 | <p>Set the metadata</p>
143 | <h5>Params</h5>
144 | <ul>
145 | <li><a id="method_message_set_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
146 | <li><a id="method_message_set_metadata.meta"></a><code>meta</code>: <a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></li>
147 | </ul>
148 | <h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
149 | <p>Remove a key-value pair from the metadata</p>
150 | <h5>Params</h5>
151 | <ul>
152 | <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>
153 | <li><a id="method_message_remove_metadata.key"></a><code>key</code>: <code>string</code></li>
154 | </ul>
155 | <h2><a id="wasi_messaging_request_reply_0_2_0_draft"></a>Import interface wasi:messaging/request-reply@0.2.0-draft</h2>
156 | <p>The request-reply interface allows a guest to send a message and await a response. This
157 | interface is considered optional as not all message services support the concept of
158 | request/reply. However, request/reply is a very common pattern in messaging and as such, we have
159 | included it as a core interface.</p>
160 | <hr />
161 | <h3>Types</h3>
162 | <h4><a id="client"></a><code>type client</code></h4>
163 | <p><a href="#client"><a href="#client"><code>client</code></a></a></p>
164 | <p>
165 | #### <a id="message"></a>`type message`
166 | [`message`](#message)
167 | <p>
168 | #### <a id="error"></a>`type error`
169 | [`error`](#error)
170 | <p>
171 | #### <a id="topic"></a>`type topic`
172 | [`topic`](#topic)
173 | <p>
174 | #### <a id="request_options"></a>`resource request-options`
175 | <h2>Options for a request/reply operation. This is a resource to allow for future expansion of
176 | options.</h2>
177 | <h3>Functions</h3>
178 | <h4><a id="constructor_request_options"></a><code>[constructor]request-options: func</code></h4>
179 | <p>Creates a new request options resource with no options set.</p>
180 | <h5>Return values</h5>
181 | <ul>
182 | <li><a id="constructor_request_options.0"></a> own&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;</li>
183 | </ul>
184 | <h4><a id="method_request_options_set_timeout_ms"></a><code>[method]request-options.set-timeout-ms: func</code></h4>
185 | <p>The maximum amount of time to wait for a response. If the timeout value is not set, then
186 | the request/reply operation will block until a message is received in response.</p>
187 | <h5>Params</h5>
188 | <ul>
189 | <li><a id="method_request_options_set_timeout_ms.self"></a><code>self</code>: borrow&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;</li>
190 | <li><a id="method_request_options_set_timeout_ms.timeout_ms"></a><code>timeout-ms</code>: <code>u32</code></li>
191 | </ul>
192 | <h4><a id="method_request_options_set_expected_replies"></a><code>[method]request-options.set-expected-replies: func</code></h4>
193 | <p>The maximum number of replies to expect before returning.</p>
194 | <h5>Params</h5>
195 | <ul>
196 | <li><a id="method_request_options_set_expected_replies.self"></a><code>self</code>: borrow&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;</li>
197 | <li><a id="method_request_options_set_expected_replies.expected_replies"></a><code>expected-replies</code>: <code>u32</code></li>
198 | </ul>
199 | <h4><a id="request"></a><code>request: func</code></h4>
200 | <p>Performs a blocking request/reply operation with an optional set of request options.</p>
201 | <p>The behavior of this function is largely dependent on the options given to the function.
202 | If no options are provided, then the request/reply operation will block until a single
203 | message is received in response. If a timeout is provided, then the request/reply operation
204 | will block for the specified amount of time before returning an error if no messages were
205 | received (or the list of messages that were received). If both a timeout and an expected
206 | number of replies are provided, the function should return when either condition is met
207 | (whichever comes first)—e.g., (1) if no replies were received within the timeout return an
208 | error, (2) if the maximum expected number of replies were received before timeout, return
209 | the list of messages, or (3) if the timeout is reached before the expected number of replies,
210 | return the list of messages received up to that point.</p>
211 | <h5>Params</h5>
212 | <ul>
213 | <li><a id="request.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
214 | <li><a id="request.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
215 | <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>
216 | <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>
217 | </ul>
218 | <h5>Return values</h5>
219 | <ul>
220 | <li><a id="request.0"></a> result&lt;list&lt;own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
221 | </ul>
222 | <h4><a id="reply"></a><code>reply: func</code></h4>
223 | <p>Replies to the given message with the given response message. The details of which topic
224 | the message is sent to is up to the implementation. This allows for reply-to details to be
225 | handled in the best way possible for the underlying messaging system.</p>
226 | <p>Please note that this reply functionality is different than something like HTTP because there
227 | are several use cases in which a reply might not be required for every message (so this would
228 | be a noop). There are also cases when you might want to reply and then continue processing.
229 | Additionally, you might want to reply to a message several times (such as providing an
230 | update). So this function is allowed to be called multiple times, unlike something like HTTP
231 | where the reply is sent and the connection is closed.</p>
232 | <h5>Params</h5>
233 | <ul>
234 | <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>
235 | <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>
236 | </ul>
237 | <h5>Return values</h5>
238 | <ul>
239 | <li><a id="reply.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
240 | </ul>
241 | <h2><a id="wasi_messaging_producer_0_2_0_draft"></a>Import interface wasi:messaging/producer@0.2.0-draft</h2>
242 | <p>The producer interface is used to send messages to a channel/topic.</p>
243 | <hr />
244 | <h3>Types</h3>
245 | <h4><a id="client"></a><code>type client</code></h4>
246 | <p><a href="#client"><a href="#client"><code>client</code></a></a></p>
247 | <p>
248 | #### <a id="message"></a>`type message`
249 | [`message`](#message)
250 | <p>
251 | #### <a id="error"></a>`type error`
252 | [`error`](#error)
253 | <p>
254 | #### <a id="topic"></a>`type topic`
255 | [`topic`](#topic)
256 | <p>
257 | ----
258 | <h3>Functions</h3>
259 | <h4><a id="send"></a><code>send: func</code></h4>
260 | <p>Sends the message using the given client.</p>
261 | <h5>Params</h5>
262 | <ul>
263 | <li><a id="send.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
264 | <li><a id="send.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
265 | <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>
266 | </ul>
267 | <h5>Return values</h5>
268 | <ul>
269 | <li><a id="send.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
270 | </ul>
271 | 


--------------------------------------------------------------------------------
/messaging-request-reply.md:
--------------------------------------------------------------------------------
  1 | <h1><a id="messaging_request_reply"></a>World messaging-request-reply</h1>
  2 | <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>
  3 | export. This setup allows the host to interact with the component for both sending messages and
  4 | handling incoming messages with request/reply capabilities.</p>
  5 | <ul>
  6 | <li>Imports:
  7 | <ul>
  8 | <li>interface <a href="#wasi_messaging_types_0_2_0_draft"><code>wasi:messaging/types@0.2.0-draft</code></a></li>
  9 | <li>interface <a href="#wasi_messaging_request_reply_0_2_0_draft"><code>wasi:messaging/request-reply@0.2.0-draft</code></a></li>
 10 | <li>interface <a href="#wasi_messaging_producer_0_2_0_draft"><code>wasi:messaging/producer@0.2.0-draft</code></a></li>
 11 | </ul>
 12 | </li>
 13 | <li>Exports:
 14 | <ul>
 15 | <li>interface <a href="#wasi_messaging_incoming_handler_0_2_0_draft"><code>wasi:messaging/incoming-handler@0.2.0-draft</code></a></li>
 16 | </ul>
 17 | </li>
 18 | </ul>
 19 | <h2><a id="wasi_messaging_types_0_2_0_draft"></a>Import interface wasi:messaging/types@0.2.0-draft</h2>
 20 | <hr />
 21 | <h3>Types</h3>
 22 | <h4><a id="metadata"></a><code>type metadata</code></h4>
 23 | <p><a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></p>
 24 | <p>A type alias for list<tuple<string, string>> to represent metadata attached to a message
 25 | <h4><a id="topic"></a><code>type topic</code></h4>
 26 | <p><code>string</code></p>
 27 | <p>A type alias for string to represent a message topic
 28 | <h4><a id="client"></a><code>resource client</code></h4>
 29 | <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
 30 | <h4><a id="error"></a><code>variant error</code></h4>
 31 | <p>Errors that can occur when using the messaging interface.</p>
 32 | <h5>Variant Cases</h5>
 33 | <ul>
 34 | <li>
 35 | <p><a id="error.timeout"></a><code>timeout</code></p>
 36 | <p>The request or operation timed out.
 37 | </li>
 38 | <li>
 39 | <p><a id="error.connection"></a><code>connection</code>: <code>string</code></p>
 40 | <p>An error occurred with the connection. Includes a message for additional context
 41 | </li>
 42 | <li>
 43 | <p><a id="error.permission_denied"></a><code>permission-denied</code>: <code>string</code></p>
 44 | <p>A permission error occurred. Includes a message for additional context
 45 | </li>
 46 | <li>
 47 | <p><a id="error.other"></a><code>other</code>: <code>string</code></p>
 48 | <p>A catch all for other types of errors
 49 | </li>
 50 | </ul>
 51 | <h4><a id="message"></a><code>resource message</code></h4>
 52 | <h2>A message with a binary payload and additional information</h2>
 53 | <h3>Functions</h3>
 54 | <h4><a id="static_client_connect"></a><code>[static]client.connect: func</code></h4>
 55 | <h5>Params</h5>
 56 | <ul>
 57 | <li><a id="static_client_connect.name"></a><code>name</code>: <code>string</code></li>
 58 | </ul>
 59 | <h5>Return values</h5>
 60 | <ul>
 61 | <li><a id="static_client_connect.0"></a> result&lt;own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 62 | </ul>
 63 | <h4><a id="method_client_disconnect"></a><code>[method]client.disconnect: func</code></h4>
 64 | <h5>Params</h5>
 65 | <ul>
 66 | <li><a id="method_client_disconnect.self"></a><code>self</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
 67 | </ul>
 68 | <h5>Return values</h5>
 69 | <ul>
 70 | <li><a id="method_client_disconnect.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
 71 | </ul>
 72 | <h4><a id="constructor_message"></a><code>[constructor]message: func</code></h4>
 73 | <h5>Params</h5>
 74 | <ul>
 75 | <li><a id="constructor_message.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
 76 | </ul>
 77 | <h5>Return values</h5>
 78 | <ul>
 79 | <li><a id="constructor_message.0"></a> own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 80 | </ul>
 81 | <h4><a id="method_message_topic"></a><code>[method]message.topic: func</code></h4>
 82 | <p>The topic/subject/channel this message was received on, if any</p>
 83 | <h5>Params</h5>
 84 | <ul>
 85 | <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>
 86 | </ul>
 87 | <h5>Return values</h5>
 88 | <ul>
 89 | <li><a id="method_message_topic.0"></a> option&lt;<a href="#topic"><a href="#topic"><code>topic</code></a></a>&gt;</li>
 90 | </ul>
 91 | <h4><a id="method_message_content_type"></a><code>[method]message.content-type: func</code></h4>
 92 | <p>An optional content-type describing the format of the data in the message. This is
 93 | sometimes described as the &quot;format&quot; type</p>
 94 | <h5>Params</h5>
 95 | <ul>
 96 | <li><a id="method_message_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
 97 | </ul>
 98 | <h5>Return values</h5>
 99 | <ul>
100 | <li><a id="method_message_content_type.0"></a> option&lt;<code>string</code>&gt;</li>
101 | </ul>
102 | <h4><a id="method_message_set_content_type"></a><code>[method]message.set-content-type: func</code></h4>
103 | <p>Set the content-type describing the format of the data in the message. This is
104 | sometimes described as the &quot;format&quot; type</p>
105 | <h5>Params</h5>
106 | <ul>
107 | <li><a id="method_message_set_content_type.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
108 | <li><a id="method_message_set_content_type.content_type"></a><code>content-type</code>: <code>string</code></li>
109 | </ul>
110 | <h4><a id="method_message_data"></a><code>[method]message.data: func</code></h4>
111 | <p>An opaque blob of data</p>
112 | <h5>Params</h5>
113 | <ul>
114 | <li><a id="method_message_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
115 | </ul>
116 | <h5>Return values</h5>
117 | <ul>
118 | <li><a id="method_message_data.0"></a> list&lt;<code>u8</code>&gt;</li>
119 | </ul>
120 | <h4><a id="method_message_set_data"></a><code>[method]message.set-data: func</code></h4>
121 | <p>Set the opaque blob of data for this message, discarding the old value</p>
122 | <h5>Params</h5>
123 | <ul>
124 | <li><a id="method_message_set_data.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
125 | <li><a id="method_message_set_data.data"></a><code>data</code>: list&lt;<code>u8</code>&gt;</li>
126 | </ul>
127 | <h4><a id="method_message_metadata"></a><code>[method]message.metadata: func</code></h4>
128 | <p>Optional metadata (also called headers or attributes in some systems) attached to the
129 | message. This metadata is simply decoration and should not be interpreted by a host
130 | to ensure portability across different implementors (e.g., Kafka -&gt; NATS, etc.).</p>
131 | <h5>Params</h5>
132 | <ul>
133 | <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>
134 | </ul>
135 | <h5>Return values</h5>
136 | <ul>
137 | <li><a id="method_message_metadata.0"></a> option&lt;<a href="#metadata"><a href="#metadata"><code>metadata</code></a></a>&gt;</li>
138 | </ul>
139 | <h4><a id="method_message_add_metadata"></a><code>[method]message.add-metadata: func</code></h4>
140 | <p>Add a new key-value pair to the metadata, overwriting any existing value for the same key</p>
141 | <h5>Params</h5>
142 | <ul>
143 | <li><a id="method_message_add_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
144 | <li><a id="method_message_add_metadata.key"></a><code>key</code>: <code>string</code></li>
145 | <li><a id="method_message_add_metadata.value"></a><code>value</code>: <code>string</code></li>
146 | </ul>
147 | <h4><a id="method_message_set_metadata"></a><code>[method]message.set-metadata: func</code></h4>
148 | <p>Set the metadata</p>
149 | <h5>Params</h5>
150 | <ul>
151 | <li><a id="method_message_set_metadata.self"></a><code>self</code>: borrow&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
152 | <li><a id="method_message_set_metadata.meta"></a><code>meta</code>: <a href="#metadata"><a href="#metadata"><code>metadata</code></a></a></li>
153 | </ul>
154 | <h4><a id="method_message_remove_metadata"></a><code>[method]message.remove-metadata: func</code></h4>
155 | <p>Remove a key-value pair from the metadata</p>
156 | <h5>Params</h5>
157 | <ul>
158 | <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>
159 | <li><a id="method_message_remove_metadata.key"></a><code>key</code>: <code>string</code></li>
160 | </ul>
161 | <h2><a id="wasi_messaging_request_reply_0_2_0_draft"></a>Import interface wasi:messaging/request-reply@0.2.0-draft</h2>
162 | <p>The request-reply interface allows a guest to send a message and await a response. This
163 | interface is considered optional as not all message services support the concept of
164 | request/reply. However, request/reply is a very common pattern in messaging and as such, we have
165 | included it as a core interface.</p>
166 | <hr />
167 | <h3>Types</h3>
168 | <h4><a id="client"></a><code>type client</code></h4>
169 | <p><a href="#client"><a href="#client"><code>client</code></a></a></p>
170 | <p>
171 | #### <a id="message"></a>`type message`
172 | [`message`](#message)
173 | <p>
174 | #### <a id="error"></a>`type error`
175 | [`error`](#error)
176 | <p>
177 | #### <a id="topic"></a>`type topic`
178 | [`topic`](#topic)
179 | <p>
180 | #### <a id="request_options"></a>`resource request-options`
181 | <h2>Options for a request/reply operation. This is a resource to allow for future expansion of
182 | options.</h2>
183 | <h3>Functions</h3>
184 | <h4><a id="constructor_request_options"></a><code>[constructor]request-options: func</code></h4>
185 | <p>Creates a new request options resource with no options set.</p>
186 | <h5>Return values</h5>
187 | <ul>
188 | <li><a id="constructor_request_options.0"></a> own&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;</li>
189 | </ul>
190 | <h4><a id="method_request_options_set_timeout_ms"></a><code>[method]request-options.set-timeout-ms: func</code></h4>
191 | <p>The maximum amount of time to wait for a response. If the timeout value is not set, then
192 | the request/reply operation will block until a message is received in response.</p>
193 | <h5>Params</h5>
194 | <ul>
195 | <li><a id="method_request_options_set_timeout_ms.self"></a><code>self</code>: borrow&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;</li>
196 | <li><a id="method_request_options_set_timeout_ms.timeout_ms"></a><code>timeout-ms</code>: <code>u32</code></li>
197 | </ul>
198 | <h4><a id="method_request_options_set_expected_replies"></a><code>[method]request-options.set-expected-replies: func</code></h4>
199 | <p>The maximum number of replies to expect before returning.</p>
200 | <h5>Params</h5>
201 | <ul>
202 | <li><a id="method_request_options_set_expected_replies.self"></a><code>self</code>: borrow&lt;<a href="#request_options"><a href="#request_options"><code>request-options</code></a></a>&gt;</li>
203 | <li><a id="method_request_options_set_expected_replies.expected_replies"></a><code>expected-replies</code>: <code>u32</code></li>
204 | </ul>
205 | <h4><a id="request"></a><code>request: func</code></h4>
206 | <p>Performs a blocking request/reply operation with an optional set of request options.</p>
207 | <p>The behavior of this function is largely dependent on the options given to the function.
208 | If no options are provided, then the request/reply operation will block until a single
209 | message is received in response. If a timeout is provided, then the request/reply operation
210 | will block for the specified amount of time before returning an error if no messages were
211 | received (or the list of messages that were received). If both a timeout and an expected
212 | number of replies are provided, the function should return when either condition is met
213 | (whichever comes first)—e.g., (1) if no replies were received within the timeout return an
214 | error, (2) if the maximum expected number of replies were received before timeout, return
215 | the list of messages, or (3) if the timeout is reached before the expected number of replies,
216 | return the list of messages received up to that point.</p>
217 | <h5>Params</h5>
218 | <ul>
219 | <li><a id="request.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
220 | <li><a id="request.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
221 | <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>
222 | <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>
223 | </ul>
224 | <h5>Return values</h5>
225 | <ul>
226 | <li><a id="request.0"></a> result&lt;list&lt;own&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;&gt;, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
227 | </ul>
228 | <h4><a id="reply"></a><code>reply: func</code></h4>
229 | <p>Replies to the given message with the given response message. The details of which topic
230 | the message is sent to is up to the implementation. This allows for reply-to details to be
231 | handled in the best way possible for the underlying messaging system.</p>
232 | <p>Please note that this reply functionality is different than something like HTTP because there
233 | are several use cases in which a reply might not be required for every message (so this would
234 | be a noop). There are also cases when you might want to reply and then continue processing.
235 | Additionally, you might want to reply to a message several times (such as providing an
236 | update). So this function is allowed to be called multiple times, unlike something like HTTP
237 | where the reply is sent and the connection is closed.</p>
238 | <h5>Params</h5>
239 | <ul>
240 | <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>
241 | <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>
242 | </ul>
243 | <h5>Return values</h5>
244 | <ul>
245 | <li><a id="reply.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
246 | </ul>
247 | <h2><a id="wasi_messaging_producer_0_2_0_draft"></a>Import interface wasi:messaging/producer@0.2.0-draft</h2>
248 | <p>The producer interface is used to send messages to a channel/topic.</p>
249 | <hr />
250 | <h3>Types</h3>
251 | <h4><a id="client"></a><code>type client</code></h4>
252 | <p><a href="#client"><a href="#client"><code>client</code></a></a></p>
253 | <p>
254 | #### <a id="message"></a>`type message`
255 | [`message`](#message)
256 | <p>
257 | #### <a id="error"></a>`type error`
258 | [`error`](#error)
259 | <p>
260 | #### <a id="topic"></a>`type topic`
261 | [`topic`](#topic)
262 | <p>
263 | ----
264 | <h3>Functions</h3>
265 | <h4><a id="send"></a><code>send: func</code></h4>
266 | <p>Sends the message using the given client.</p>
267 | <h5>Params</h5>
268 | <ul>
269 | <li><a id="send.c"></a><code>c</code>: borrow&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
270 | <li><a id="send.topic"></a><a href="#topic"><code>topic</code></a>: <a href="#topic"><a href="#topic"><code>topic</code></a></a></li>
271 | <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>
272 | </ul>
273 | <h5>Return values</h5>
274 | <ul>
275 | <li><a id="send.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
276 | </ul>
277 | <h2><a id="wasi_messaging_incoming_handler_0_2_0_draft"></a>Export interface wasi:messaging/incoming-handler@0.2.0-draft</h2>
278 | <hr />
279 | <h3>Types</h3>
280 | <h4><a id="message"></a><code>type message</code></h4>
281 | <p><a href="#message"><a href="#message"><code>message</code></a></a></p>
282 | <p>
283 | #### <a id="error"></a>`type error`
284 | [`error`](#error)
285 | <p>
286 | #### <a id="topic"></a>`type topic`
287 | [`topic`](#topic)
288 | <p>
289 | ----
290 | <h3>Functions</h3>
291 | <h4><a id="handle"></a><code>handle: func</code></h4>
292 | <p>Whenever this guest receives a message in one of the subscribed topics, the message is
293 | sent to this handler. The guest is responsible for matching on the topic and handling the
294 | message accordingly. Implementors (such as hosts) calling this interface should make their
295 | own decisions on how to handle errors returned from this function.</p>
296 | <h5>Params</h5>
297 | <ul>
298 | <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>
299 | </ul>
300 | <h5>Return values</h5>
301 | <ul>
302 | <li><a id="handle.0"></a> result&lt;_, <a href="#error"><a href="#error"><code>error</code></a></a>&gt;</li>
303 | </ul>
304 | 


--------------------------------------------------------------------------------