generated from WebAssembly/wasi-proposal-template
-
Notifications
You must be signed in to change notification settings - Fork 9
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(*): Updates interfaces to be more streamlined
This PR integrates various changes from talking to current users of messaging in the community as well as conversations among the champions Signed-off-by: Taylor Thomas <[email protected]>
- Loading branch information
1 parent
6231f8a
commit c0f5316
Showing
9 changed files
with
347 additions
and
120 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,216 @@ | ||
| <h1><a name="imports_request_reply">World imports-request-reply</a></h1> | ||
| <ul> | ||
| <li>Imports: | ||
| <ul> | ||
| <li>interface <a href="#wasi:messaging_types_0.2.0_draft"><code>wasi:messaging/[email protected]</code></a></li> | ||
| <li>interface <a href="#wasi:messaging_request_reply_0.2.0_draft"><code>wasi:messaging/[email protected]</code></a></li> | ||
| <li>interface <a href="#wasi:messaging_producer_0.2.0_draft"><code>wasi:messaging/[email protected]</code></a></li> | ||
| <li>interface <a href="#wasi:messaging_consumer_0.2.0_draft"><code>wasi:messaging/[email protected]</code></a></li> | ||
| </ul> | ||
| </li> | ||
| </ul> | ||
| <h2><a name="wasi:messaging_types_0.2.0_draft"></a>Import interface wasi:messaging/[email protected]</h2> | ||
| <hr /> | ||
| <h3>Types</h3> | ||
| <h4><a name="client"></a><code>resource client</code></h4> | ||
| <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p> | ||
| <h4><a name="error"></a><code>resource error</code></h4> | ||
| <p>TODO(danbugs): This should be eventually extracted as an underlying type for other | ||
| wasi-cloud-core interfaces.</p> | ||
| <h4><a name="channel"></a><code>type channel</code></h4> | ||
| <p><code>string</code></p> | ||
| <p>There are two types of channels: | ||
| - publish-subscribe channel, which is a broadcast channel, and | ||
| - point-to-point channel, which is a unicast channel. | ||
| <p>The interface doesn't highlight this difference in the type itself as that's uniquely a consumer issue.</p> | ||
| <h4><a name="guest_configuration"></a><code>record guest-configuration</code></h4> | ||
| <p>Configuration includes a required list of channels the guest is subscribing to, and an optional list of extensions key-value pairs | ||
| (e.g., partitions/offsets to read from in Kafka/EventHubs, QoS etc.).</p> | ||
| <h5>Record Fields</h5> | ||
| <ul> | ||
| <li><a name="guest_configuration.channels"></a><code>channels</code>: list<<a href="#channel"><a href="#channel"><code>channel</code></a></a>></li> | ||
| <li><a name="guest_configuration.extensions"></a><code>extensions</code>: option<list<(<code>string</code>, <code>string</code>)>></li> | ||
| </ul> | ||
| <h4><a name="message"></a><code>record message</code></h4> | ||
| <p>A message with a binary payload and additional information</p> | ||
| <h5>Record Fields</h5> | ||
| <ul> | ||
| <li> | ||
| <p><a name="message.topic"></a><code>topic</code>: <code>string</code></p> | ||
| <p>The topic or subject this message was received or should be sent on | ||
| </li> | ||
| <li> | ||
| <p><a name="message.content_type"></a><code>content-type</code>: <code>string</code></p> | ||
| <p>An optional content-type describing the format of the data in the message. This is | ||
| sometimes described as the "format" type | ||
| </li> | ||
| <li> | ||
| <p><a name="message.reply_to"></a><code>reply-to</code>: option<<code>string</code>></p> | ||
| <p>An optional topic for use in request/response scenarios. Senders and consumers of | ||
| messages must not assume that this field is set and should handle it in their code | ||
| accordingly. | ||
| </li> | ||
| <li> | ||
| <p><a name="message.data"></a><code>data</code>: list<<code>u8</code>></p> | ||
| <p>An opaque blob of data | ||
| </li> | ||
| <li> | ||
| <p><a name="message.metadata"></a><code>metadata</code>: option<list<(<code>string</code>, <code>string</code>)>></p> | ||
| <p>Optional metadata (also called headers or attributes in some systems) attached to the message | ||
| </li> | ||
| </ul> | ||
| <hr /> | ||
| <h3>Functions</h3> | ||
| <h4><a name="static_client.connect"></a><code>[static]client.connect: func</code></h4> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="static_client.connect.name"></a><code>name</code>: <code>string</code></li> | ||
| </ul> | ||
| <h5>Return values</h5> | ||
| <ul> | ||
| <li><a name="static_client.connect.0"></a> result<own<<a href="#client"><a href="#client"><code>client</code></a></a>>, own<<a href="#error"><a href="#error"><code>error</code></a></a>>></li> | ||
| </ul> | ||
| <h4><a name="static_error.trace"></a><code>[static]error.trace: func</code></h4> | ||
| <h5>Return values</h5> | ||
| <ul> | ||
| <li><a name="static_error.trace.0"></a> <code>string</code></li> | ||
| </ul> | ||
| <h2><a name="wasi:messaging_request_reply_0.2.0_draft"></a>Import interface wasi:messaging/[email protected]</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 | ||
| request/reply. However, request/reply is a very common pattern in messaging and as such, we have | ||
| included it as a core interface.</p> | ||
| <hr /> | ||
| <h3>Types</h3> | ||
| <h4><a name="client"></a><code>type client</code></h4> | ||
| <p><a href="#client"><a href="#client"><code>client</code></a></a></p> | ||
| <p> | ||
| #### <a name="message"></a>`type message` | ||
| [`message`](#message) | ||
| <p> | ||
| #### <a name="error"></a>`type error` | ||
| [`error`](#error) | ||
| <p> | ||
| ---- | ||
| <h3>Functions</h3> | ||
| <h4><a name="request"></a><code>request: func</code></h4> | ||
| <p>Performs a blocking request/reply operation with an optional timeout. If the timeout value | ||
| is not set, then the request/reply operation will block indefinitely.</p> | ||
| <p>Please note that implementations that provide <code>wasi:messaging</code> are responsible for ensuring | ||
| that guests are not allowed to subscribe to channels that they are not configured to | ||
| subscribe to (or have access to). Failure to do so can result in possible breakout or access | ||
| to resources that are not intended to be accessible to the guest. This means implementations | ||
| should validate that the reply-to field is a valid topic the guest should have access to or | ||
| enforce it via the credentials used to connect to the service.</p> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="request.c"></a><code>c</code>: own<<a href="#client"><a href="#client"><code>client</code></a></a>></li> | ||
| <li><a name="request.msg"></a><code>msg</code>: <a href="#message"><a href="#message"><code>message</code></a></a></li> | ||
| <li><a name="request.timeout_ms"></a><code>timeout-ms</code>: option<<code>u32</code>></li> | ||
| </ul> | ||
| <h5>Return values</h5> | ||
| <ul> | ||
| <li><a name="request.0"></a> result<option<list<<a href="#message"><a href="#message"><code>message</code></a></a>>>, own<<a href="#error"><a href="#error"><code>error</code></a></a>>></li> | ||
| </ul> | ||
| <h2><a name="wasi:messaging_producer_0.2.0_draft"></a>Import interface wasi:messaging/[email protected]</h2> | ||
| <p>The producer interface is uesed to send messages to a channel/topic.</p> | ||
| <hr /> | ||
| <h3>Types</h3> | ||
| <h4><a name="client"></a><code>type client</code></h4> | ||
| <p><a href="#client"><a href="#client"><code>client</code></a></a></p> | ||
| <p> | ||
| #### <a name="channel"></a>`type channel` | ||
| [`channel`](#channel) | ||
| <p> | ||
| #### <a name="message"></a>`type message` | ||
| [`message`](#message) | ||
| <p> | ||
| #### <a name="error"></a>`type error` | ||
| [`error`](#error) | ||
| <p> | ||
| ---- | ||
| <h3>Functions</h3> | ||
| <h4><a name="send"></a><code>send: func</code></h4> | ||
| <p>Sends a message to the given channel/topic. This topic can be overridden if a message has a | ||
| non-empty topic field</p> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="send.c"></a><code>c</code>: own<<a href="#client"><a href="#client"><code>client</code></a></a>></li> | ||
| <li><a name="send.ch"></a><code>ch</code>: <a href="#channel"><a href="#channel"><code>channel</code></a></a></li> | ||
| <li><a name="send.m"></a><code>m</code>: list<<a href="#message"><a href="#message"><code>message</code></a></a>></li> | ||
| </ul> | ||
| <h5>Return values</h5> | ||
| <ul> | ||
| <li><a name="send.0"></a> result<_, own<<a href="#error"><a href="#error"><code>error</code></a></a>>></li> | ||
| </ul> | ||
| <h2><a name="wasi:messaging_consumer_0.2.0_draft"></a>Import interface wasi:messaging/[email protected]</h2> | ||
| <p>The consumer interface allows a guest to dynamically update its subscriptions and configuration | ||
| as well as functionality for completing (acking) or abandoning (nacking) messages.</p> | ||
| <hr /> | ||
| <h3>Types</h3> | ||
| <h4><a name="client"></a><code>type client</code></h4> | ||
| <p><a href="#client"><a href="#client"><code>client</code></a></a></p> | ||
| <p> | ||
| #### <a name="message"></a>`type message` | ||
| [`message`](#message) | ||
| <p> | ||
| #### <a name="channel"></a>`type channel` | ||
| [`channel`](#channel) | ||
| <p> | ||
| #### <a name="error"></a>`type error` | ||
| [`error`](#error) | ||
| <p> | ||
| #### <a name="guest_configuration"></a>`type guest-configuration` | ||
| [`guest-configuration`](#guest_configuration) | ||
| <p> | ||
| ---- | ||
| <h3>Functions</h3> | ||
| <h4><a name="update_guest_configuration"></a><code>update-guest-configuration: func</code></h4> | ||
| <p>'Fit-all' type function for updating a guest's configuration – this could be useful for:</p> | ||
| <ul> | ||
| <li>unsubscribing from a channel,</li> | ||
| <li>checkpointing,</li> | ||
| <li>etc..</li> | ||
| </ul> | ||
| <p>Please note that implementations that provide <code>wasi:messaging</code> are responsible for ensuring | ||
| that guests are not allowed to subscribe to channels that they are not configured to | ||
| subscribe to (or have access to). Failure to do so can result in possible breakout or access | ||
| to resources that are not intended to be accessible to the guest. This means implementations | ||
| should validate that the configured topix are valid topics the guest should have access to or | ||
| enforce it via the credentials used to connect to the service.</p> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="update_guest_configuration.gc"></a><code>gc</code>: <a href="#guest_configuration"><a href="#guest_configuration"><code>guest-configuration</code></a></a></li> | ||
| </ul> | ||
| <h5>Return values</h5> | ||
| <ul> | ||
| <li><a name="update_guest_configuration.0"></a> result<_, own<<a href="#error"><a href="#error"><code>error</code></a></a>>></li> | ||
| </ul> | ||
| <h4><a name="complete_message"></a><code>complete-message: func</code></h4> | ||
| <p>A message can exist under several statuses: | ||
| (1) available: the message is ready to be read, | ||
| (2) acquired: the message has been sent to a consumer (but still exists in the queue), | ||
| (3) accepted (result of complete-message): the message has been received and ACK-ed by a consumer and can be safely removed from the queue, | ||
| (4) rejected (result of abandon-message): the message has been received and NACK-ed by a consumer, at which point it can be:</p> | ||
| <ul> | ||
| <li>deleted,</li> | ||
| <li>sent to a dead-letter queue, or</li> | ||
| <li>kept in the queue for further processing.</li> | ||
| </ul> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="complete_message.m"></a><code>m</code>: <a href="#message"><a href="#message"><code>message</code></a></a></li> | ||
| </ul> | ||
| <h5>Return values</h5> | ||
| <ul> | ||
| <li><a name="complete_message.0"></a> result<_, own<<a href="#error"><a href="#error"><code>error</code></a></a>>></li> | ||
| </ul> | ||
| <h4><a name="abandon_message"></a><code>abandon-message: func</code></h4> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="abandon_message.m"></a><code>m</code>: <a href="#message"><a href="#message"><code>message</code></a></a></li> | ||
| </ul> | ||
| <h5>Return values</h5> | ||
| <ul> | ||
| <li><a name="abandon_message.0"></a> result<_, own<<a href="#error"><a href="#error"><code>error</code></a></a>>></li> | ||
| </ul> |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -2,19 +2,20 @@ | |
| <ul> | ||
| <li>Imports: | ||
| <ul> | ||
| <li>interface <a href="#wasi:messaging_messaging_types_0.2.0_draft"><code>wasi:messaging/messaging-[email protected]</code></a></li> | ||
| <li>interface <a href="#wasi:messaging_types_0.2.0_draft"><code>wasi:messaging/[email protected]</code></a></li> | ||
| <li>interface <a href="#wasi:messaging_producer_0.2.0_draft"><code>wasi:messaging/[email protected]</code></a></li> | ||
| <li>interface <a href="#wasi:messaging_consumer_0.2.0_draft"><code>wasi:messaging/[email protected]</code></a></li> | ||
| </ul> | ||
| </li> | ||
| </ul> | ||
| <h2><a name="wasi:messaging_messaging_types_0.2.0_draft"></a>Import interface wasi:messaging/messaging-[email protected]</h2> | ||
| <h2><a name="wasi:messaging_types_0.2.0_draft"></a>Import interface wasi:messaging/[email protected]</h2> | ||
| <hr /> | ||
| <h3>Types</h3> | ||
| <h4><a name="client"></a><code>resource client</code></h4> | ||
| <p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p> | ||
| <h4><a name="error"></a><code>resource error</code></h4> | ||
| <p>TODO(danbugs): This should be eventually extracted as an underlying type for other wasi-cloud-core interfaces.</p> | ||
| <p>TODO(danbugs): This should be eventually extracted as an underlying type for other | ||
| wasi-cloud-core interfaces.</p> | ||
| <h4><a name="channel"></a><code>type channel</code></h4> | ||
| <p><code>string</code></p> | ||
| <p>There are two types of channels: | ||
|
|
@@ -29,28 +30,33 @@ | |
| <li><a name="guest_configuration.channels"></a><code>channels</code>: list<<a href="#channel"><a href="#channel"><code>channel</code></a></a>></li> | ||
| <li><a name="guest_configuration.extensions"></a><code>extensions</code>: option<list<(<code>string</code>, <code>string</code>)>></li> | ||
| </ul> | ||
| <h4><a name="format_spec"></a><code>enum format-spec</code></h4> | ||
| <p>Format specification for messages</p> | ||
| <ul> | ||
| <li>more info: https://github.com/clemensv/spec/blob/registry-extensions/registry/spec.md#message-formats</li> | ||
| <li>message metadata can further decorate w/ things like format version, and so on.</li> | ||
| </ul> | ||
| <h5>Enum Cases</h5> | ||
| <ul> | ||
| <li><a name="format_spec.cloudevents"></a><code>cloudevents</code></li> | ||
| <li><a name="format_spec.http"></a><code>http</code></li> | ||
| <li><a name="format_spec.amqp"></a><code>amqp</code></li> | ||
| <li><a name="format_spec.mqtt"></a><code>mqtt</code></li> | ||
| <li><a name="format_spec.kafka"></a><code>kafka</code></li> | ||
| <li><a name="format_spec.raw"></a><code>raw</code></li> | ||
| </ul> | ||
| <h4><a name="message"></a><code>record message</code></h4> | ||
| <p>A message with a binary payload, a format specification, and decorative metadata.</p> | ||
| <p>A message with a binary payload and additional information</p> | ||
| <h5>Record Fields</h5> | ||
| <ul> | ||
| <li><a name="message.data"></a><code>data</code>: list<<code>u8</code>></li> | ||
| <li><a name="message.format"></a><code>format</code>: <a href="#format_spec"><a href="#format_spec"><code>format-spec</code></a></a></li> | ||
| <li><a name="message.metadata"></a><code>metadata</code>: option<list<(<code>string</code>, <code>string</code>)>></li> | ||
| <li> | ||
| <p><a name="message.topic"></a><code>topic</code>: <code>string</code></p> | ||
| <p>The topic or subject this message was received or should be sent on | ||
| </li> | ||
| <li> | ||
| <p><a name="message.content_type"></a><code>content-type</code>: <code>string</code></p> | ||
| <p>An optional content-type describing the format of the data in the message. This is | ||
| sometimes described as the "format" type | ||
| </li> | ||
| <li> | ||
| <p><a name="message.reply_to"></a><code>reply-to</code>: option<<code>string</code>></p> | ||
| <p>An optional topic for use in request/response scenarios. Senders and consumers of | ||
| messages must not assume that this field is set and should handle it in their code | ||
| accordingly. | ||
| </li> | ||
| <li> | ||
| <p><a name="message.data"></a><code>data</code>: list<<code>u8</code>></p> | ||
| <p>An opaque blob of data | ||
| </li> | ||
| <li> | ||
| <p><a name="message.metadata"></a><code>metadata</code>: option<list<(<code>string</code>, <code>string</code>)>></p> | ||
| <p>Optional metadata (also called headers or attributes in some systems) attached to the message | ||
| </li> | ||
| </ul> | ||
| <hr /> | ||
| <h3>Functions</h3> | ||
|
|
@@ -69,6 +75,7 @@ | |
| <li><a name="static_error.trace.0"></a> <code>string</code></li> | ||
| </ul> | ||
| <h2><a name="wasi:messaging_producer_0.2.0_draft"></a>Import interface wasi:messaging/[email protected]</h2> | ||
| <p>The producer interface is uesed to send messages to a channel/topic.</p> | ||
| <hr /> | ||
| <h3>Types</h3> | ||
| <h4><a name="client"></a><code>type client</code></h4> | ||
|
|
@@ -86,6 +93,8 @@ | |
| ---- | ||
| <h3>Functions</h3> | ||
| <h4><a name="send"></a><code>send: func</code></h4> | ||
| <p>Sends a message to the given channel/topic. This topic can be overridden if a message has a | ||
| non-empty topic field</p> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="send.c"></a><code>c</code>: own<<a href="#client"><a href="#client"><code>client</code></a></a>></li> | ||
|
|
@@ -97,6 +106,8 @@ | |
| <li><a name="send.0"></a> result<_, own<<a href="#error"><a href="#error"><code>error</code></a></a>>></li> | ||
| </ul> | ||
| <h2><a name="wasi:messaging_consumer_0.2.0_draft"></a>Import interface wasi:messaging/[email protected]</h2> | ||
| <p>The consumer interface allows a guest to dynamically update its subscriptions and configuration | ||
| as well as functionality for completing (acking) or abandoning (nacking) messages.</p> | ||
| <hr /> | ||
| <h3>Types</h3> | ||
| <h4><a name="client"></a><code>type client</code></h4> | ||
|
|
@@ -116,36 +127,19 @@ | |
| <p> | ||
| ---- | ||
| <h3>Functions</h3> | ||
| <h4><a name="subscribe_try_receive"></a><code>subscribe-try-receive: func</code></h4> | ||
| <p>Blocking receive for t-milliseconds with ephemeral subscription – if no message is received, returns None</p> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="subscribe_try_receive.c"></a><code>c</code>: own<<a href="#client"><a href="#client"><code>client</code></a></a>></li> | ||
| <li><a name="subscribe_try_receive.ch"></a><code>ch</code>: <a href="#channel"><a href="#channel"><code>channel</code></a></a></li> | ||
| <li><a name="subscribe_try_receive.t_milliseconds"></a><code>t-milliseconds</code>: <code>u32</code></li> | ||
| </ul> | ||
| <h5>Return values</h5> | ||
| <ul> | ||
| <li><a name="subscribe_try_receive.0"></a> result<option<list<<a href="#message"><a href="#message"><code>message</code></a></a>>>, own<<a href="#error"><a href="#error"><code>error</code></a></a>>></li> | ||
| </ul> | ||
| <h4><a name="subscribe_receive"></a><code>subscribe-receive: func</code></h4> | ||
| <p>Blocking receive until message with ephemeral subscription</p> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="subscribe_receive.c"></a><code>c</code>: own<<a href="#client"><a href="#client"><code>client</code></a></a>></li> | ||
| <li><a name="subscribe_receive.ch"></a><code>ch</code>: <a href="#channel"><a href="#channel"><code>channel</code></a></a></li> | ||
| </ul> | ||
| <h5>Return values</h5> | ||
| <ul> | ||
| <li><a name="subscribe_receive.0"></a> result<list<<a href="#message"><a href="#message"><code>message</code></a></a>>, own<<a href="#error"><a href="#error"><code>error</code></a></a>>></li> | ||
| </ul> | ||
| <h4><a name="update_guest_configuration"></a><code>update-guest-configuration: func</code></h4> | ||
| <p>'Fit-all' type function for updating a guest's configuration – this could be useful for:</p> | ||
| <ul> | ||
| <li>unsubscribing from a channel,</li> | ||
| <li>checkpointing,</li> | ||
| <li>etc..</li> | ||
| </ul> | ||
| <p>Please note that implementations that provide <code>wasi:messaging</code> are responsible for ensuring | ||
| that guests are not allowed to subscribe to channels that they are not configured to | ||
| subscribe to (or have access to). Failure to do so can result in possible breakout or access | ||
| to resources that are not intended to be accessible to the guest. This means implementations | ||
| should validate that the configured topix are valid topics the guest should have access to or | ||
| enforce it via the credentials used to connect to the service.</p> | ||
| <h5>Params</h5> | ||
| <ul> | ||
| <li><a name="update_guest_configuration.gc"></a><code>gc</code>: <a href="#guest_configuration"><a href="#guest_configuration"><code>guest-configuration</code></a></a></li> | ||
|
|
||
Oops, something went wrong.