Skip to content

Commit 338f15d

Browse files
MossakaMossaka
authored
chore(*): convert to resources and add package version (#18)
* chore(*): convert to resources and add package version Signed-off-by: Jiaxiao Zhou (Mossaka) <[email protected]> * ci: renable the workflow Signed-off-by: Jiaxiao Zhou (Mossaka) <[email protected]> * chore(*): added the generated markdown file Signed-off-by: Jiaxiao Zhou (Mossaka) <[email protected]> --------- Signed-off-by: Jiaxiao Zhou (Mossaka) <[email protected]>
1 parent 1a22661 commit 338f15d

File tree

4 files changed

+231
-11
lines changed

4 files changed

+231
-11
lines changed

‎.github/workflows/main.yml‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,6 @@ jobs:
1111
runs-on: ubuntu-latest
1212
steps:
1313
- uses: actions/checkout@v2
14-
# - uses: WebAssembly/wit-abi-up-to-date@v6
15-
# with:
16-
# wit-abi-tag: wit-abi-0.6.0
14+
- uses: WebAssembly/wit-abi-up-to-date@v17
15+
with:
16+
wit-bindgen: '0.16.0'

‎messaging.md‎

Lines changed: 220 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,220 @@
1+
<h1><a name="messaging">World messaging</a></h1>
2+
<ul>
3+
<li>Imports:
4+
<ul>
5+
<li>interface <a href="#wasi:messaging_messaging_types_0.1.0"><code>wasi:messaging/[email protected]</code></a></li>
6+
<li>interface <a href="#wasi:messaging_producer_0.1.0"><code>wasi:messaging/[email protected]</code></a></li>
7+
<li>interface <a href="#wasi:messaging_consumer_0.1.0"><code>wasi:messaging/[email protected]</code></a></li>
8+
</ul>
9+
</li>
10+
<li>Exports:
11+
<ul>
12+
<li>interface <a href="#wasi:messaging_messaging_guest_0.1.0"><code>wasi:messaging/[email protected]</code></a></li>
13+
</ul>
14+
</li>
15+
</ul>
16+
<h2><a name="wasi:messaging_messaging_types_0.1.0">Import interface wasi:messaging/[email protected]</a></h2>
17+
<hr />
18+
<h3>Types</h3>
19+
<h4><a name="client"><code>resource client</code></a></h4>
20+
<p>A connection to a message-exchange service (e.g., buffer, broker, etc.).</p>
21+
<h4><a name="error"><code>resource error</code></a></h4>
22+
<p>TODO(danbugs): This should be eventually extracted as an underlying type for other wasi-cloud-core interfaces.</p>
23+
<h4><a name="channel"><code>type channel</code></a></h4>
24+
<p><code>string</code></p>
25+
<p>There are two types of channels:
26+
- publish-subscribe channel, which is a broadcast channel, and
27+
- point-to-point channel, which is a unicast channel.
28+
<p>The interface doesn't highlight this difference in the type itself as that's uniquely a consumer issue.</p>
29+
<h4><a name="guest_configuration"><code>record guest-configuration</code></a></h4>
30+
<p>Configuration includes a required list of channels the guest is subscribing to, and an optional list of extensions key-value pairs
31+
(e.g., partitions/offsets to read from in Kafka/EventHubs, QoS etc.).</p>
32+
<h5>Record Fields</h5>
33+
<ul>
34+
<li><a name="guest_configuration.channels"><code>channels</code></a>: list&lt;<a href="#channel"><a href="#channel"><code>channel</code></a></a>&gt;</li>
35+
<li><a name="guest_configuration.extensions"><code>extensions</code></a>: option&lt;list&lt;(<code>string</code>, <code>string</code>)&gt;&gt;</li>
36+
</ul>
37+
<h4><a name="format_spec"><code>enum format-spec</code></a></h4>
38+
<p>Format specification for messages</p>
39+
<ul>
40+
<li>more info: https://github.com/clemensv/spec/blob/registry-extensions/registry/spec.md#message-formats</li>
41+
<li>message metadata can further decorate w/ things like format version, and so on.</li>
42+
</ul>
43+
<h5>Enum Cases</h5>
44+
<ul>
45+
<li><a name="format_spec.cloudevents"><code>cloudevents</code></a></li>
46+
<li><a name="format_spec.http"><code>http</code></a></li>
47+
<li><a name="format_spec.amqp"><code>amqp</code></a></li>
48+
<li><a name="format_spec.mqtt"><code>mqtt</code></a></li>
49+
<li><a name="format_spec.kafka"><code>kafka</code></a></li>
50+
<li><a name="format_spec.raw"><code>raw</code></a></li>
51+
</ul>
52+
<h4><a name="message"><code>record message</code></a></h4>
53+
<p>A message with a binary payload, a format specification, and decorative metadata.</p>
54+
<h5>Record Fields</h5>
55+
<ul>
56+
<li><a name="message.data"><code>data</code></a>: list&lt;<code>u8</code>&gt;</li>
57+
<li><a name="message.format"><code>format</code></a>: <a href="#format_spec"><a href="#format_spec"><code>format-spec</code></a></a></li>
58+
<li><a name="message.metadata"><code>metadata</code></a>: option&lt;list&lt;(<code>string</code>, <code>string</code>)&gt;&gt;</li>
59+
</ul>
60+
<hr />
61+
<h3>Functions</h3>
62+
<h4><a name="static_client.connect"><code>[static]client.connect: func</code></a></h4>
63+
<h5>Params</h5>
64+
<ul>
65+
<li><a name="static_client.connect.name"><code>name</code></a>: <code>string</code></li>
66+
</ul>
67+
<h5>Return values</h5>
68+
<ul>
69+
<li><a name="static_client.connect.0"></a> result&lt;own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;, own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;&gt;</li>
70+
</ul>
71+
<h4><a name="static_error.trace"><code>[static]error.trace: func</code></a></h4>
72+
<h5>Return values</h5>
73+
<ul>
74+
<li><a name="static_error.trace.0"></a> <code>string</code></li>
75+
</ul>
76+
<h2><a name="wasi:messaging_producer_0.1.0">Import interface wasi:messaging/[email protected]</a></h2>
77+
<hr />
78+
<h3>Types</h3>
79+
<h4><a name="client"><code>type client</code></a></h4>
80+
<p><a href="#client"><a href="#client"><code>client</code></a></a></p>
81+
<p>
82+
#### <a name="channel">`type channel`</a>
83+
[`channel`](#channel)
84+
<p>
85+
#### <a name="message">`type message`</a>
86+
[`message`](#message)
87+
<p>
88+
#### <a name="error">`type error`</a>
89+
[`error`](#error)
90+
<p>
91+
----
92+
<h3>Functions</h3>
93+
<h4><a name="send"><code>send: func</code></a></h4>
94+
<h5>Params</h5>
95+
<ul>
96+
<li><a name="send.c"><code>c</code></a>: own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
97+
<li><a name="send.ch"><code>ch</code></a>: <a href="#channel"><a href="#channel"><code>channel</code></a></a></li>
98+
<li><a name="send.m"><code>m</code></a>: list&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
99+
</ul>
100+
<h5>Return values</h5>
101+
<ul>
102+
<li><a name="send.0"></a> result&lt;_, own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;&gt;</li>
103+
</ul>
104+
<h2><a name="wasi:messaging_consumer_0.1.0">Import interface wasi:messaging/[email protected]</a></h2>
105+
<hr />
106+
<h3>Types</h3>
107+
<h4><a name="client"><code>type client</code></a></h4>
108+
<p><a href="#client"><a href="#client"><code>client</code></a></a></p>
109+
<p>
110+
#### <a name="message">`type message`</a>
111+
[`message`](#message)
112+
<p>
113+
#### <a name="channel">`type channel`</a>
114+
[`channel`](#channel)
115+
<p>
116+
#### <a name="error">`type error`</a>
117+
[`error`](#error)
118+
<p>
119+
#### <a name="guest_configuration">`type guest-configuration`</a>
120+
[`guest-configuration`](#guest_configuration)
121+
<p>
122+
----
123+
<h3>Functions</h3>
124+
<h4><a name="subscribe_try_receive"><code>subscribe-try-receive: func</code></a></h4>
125+
<p>Blocking receive for t-milliseconds with ephemeral subscription – if no message is received, returns None</p>
126+
<h5>Params</h5>
127+
<ul>
128+
<li><a name="subscribe_try_receive.c"><code>c</code></a>: own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
129+
<li><a name="subscribe_try_receive.ch"><code>ch</code></a>: <a href="#channel"><a href="#channel"><code>channel</code></a></a></li>
130+
<li><a name="subscribe_try_receive.t_milliseconds"><code>t-milliseconds</code></a>: <code>u32</code></li>
131+
</ul>
132+
<h5>Return values</h5>
133+
<ul>
134+
<li><a name="subscribe_try_receive.0"></a> result&lt;option&lt;list&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;&gt;, own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;&gt;</li>
135+
</ul>
136+
<h4><a name="subscribe_receive"><code>subscribe-receive: func</code></a></h4>
137+
<p>Blocking receive until message with ephemeral subscription</p>
138+
<h5>Params</h5>
139+
<ul>
140+
<li><a name="subscribe_receive.c"><code>c</code></a>: own&lt;<a href="#client"><a href="#client"><code>client</code></a></a>&gt;</li>
141+
<li><a name="subscribe_receive.ch"><code>ch</code></a>: <a href="#channel"><a href="#channel"><code>channel</code></a></a></li>
142+
</ul>
143+
<h5>Return values</h5>
144+
<ul>
145+
<li><a name="subscribe_receive.0"></a> result&lt;list&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;, own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;&gt;</li>
146+
</ul>
147+
<h4><a name="update_guest_configuration"><code>update-guest-configuration: func</code></a></h4>
148+
<p>'Fit-all' type function for updating a guest's configuration – this could be useful for:</p>
149+
<ul>
150+
<li>unsubscribing from a channel,</li>
151+
<li>checkpointing,</li>
152+
<li>etc..</li>
153+
</ul>
154+
<h5>Params</h5>
155+
<ul>
156+
<li><a name="update_guest_configuration.gc"><code>gc</code></a>: <a href="#guest_configuration"><a href="#guest_configuration"><code>guest-configuration</code></a></a></li>
157+
</ul>
158+
<h5>Return values</h5>
159+
<ul>
160+
<li><a name="update_guest_configuration.0"></a> result&lt;_, own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;&gt;</li>
161+
</ul>
162+
<h4><a name="complete_message"><code>complete-message: func</code></a></h4>
163+
<p>A message can exist under several statuses:
164+
(1) available: the message is ready to be read,
165+
(2) acquired: the message has been sent to a consumer (but still exists in the queue),
166+
(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,
167+
(4) rejected (result of abandon-message): the message has been received and NACK-ed by a consumer, at which point it can be:</p>
168+
<ul>
169+
<li>deleted,</li>
170+
<li>sent to a dead-letter queue, or</li>
171+
<li>kept in the queue for further processing.</li>
172+
</ul>
173+
<h5>Params</h5>
174+
<ul>
175+
<li><a name="complete_message.m"><code>m</code></a>: <a href="#message"><a href="#message"><code>message</code></a></a></li>
176+
</ul>
177+
<h5>Return values</h5>
178+
<ul>
179+
<li><a name="complete_message.0"></a> result&lt;_, own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;&gt;</li>
180+
</ul>
181+
<h4><a name="abandon_message"><code>abandon-message: func</code></a></h4>
182+
<h5>Params</h5>
183+
<ul>
184+
<li><a name="abandon_message.m"><code>m</code></a>: <a href="#message"><a href="#message"><code>message</code></a></a></li>
185+
</ul>
186+
<h5>Return values</h5>
187+
<ul>
188+
<li><a name="abandon_message.0"></a> result&lt;_, own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;&gt;</li>
189+
</ul>
190+
<h2><a name="wasi:messaging_messaging_guest_0.1.0">Export interface wasi:messaging/[email protected]</a></h2>
191+
<hr />
192+
<h3>Types</h3>
193+
<h4><a name="message"><code>type message</code></a></h4>
194+
<p><a href="#message"><a href="#message"><code>message</code></a></a></p>
195+
<p>
196+
#### <a name="guest_configuration">`type guest-configuration`</a>
197+
[`guest-configuration`](#guest_configuration)
198+
<p>
199+
#### <a name="error">`type error`</a>
200+
[`error`](#error)
201+
<p>
202+
----
203+
<h3>Functions</h3>
204+
<h4><a name="configure"><code>configure: func</code></a></h4>
205+
<p>Returns the list of channels (and extension metadata within guest-configuration) that
206+
this component should subscribe to and be handled by the subsequent handler within guest-configuration</p>
207+
<h5>Return values</h5>
208+
<ul>
209+
<li><a name="configure.0"></a> result&lt;<a href="#guest_configuration"><a href="#guest_configuration"><code>guest-configuration</code></a></a>, own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;&gt;</li>
210+
</ul>
211+
<h4><a name="handler"><code>handler: func</code></a></h4>
212+
<p>Whenever this guest receives a message in one of the subscribed channels, the message is sent to this handler</p>
213+
<h5>Params</h5>
214+
<ul>
215+
<li><a name="handler.ms"><code>ms</code></a>: list&lt;<a href="#message"><a href="#message"><code>message</code></a></a>&gt;</li>
216+
</ul>
217+
<h5>Return values</h5>
218+
<ul>
219+
<li><a name="handler.0"></a> result&lt;_, own&lt;<a href="#error"><a href="#error"><code>error</code></a></a>&gt;&gt;</li>
220+
</ul>

‎wit/messaging.wit‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
package wasi:messaging;
1+
package wasi:messaging@0.1.0;
22

33
world messaging {
44
import producer;

‎wit/types.wit‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
11
interface messaging-types {
22
/// A connection to a message-exchange service (e.g., buffer, broker, etc.).
3-
type client = u32;
4-
disconnect: func(c: client);
5-
connect: func(name: string) -> result<client, error>;
6-
3+
resource client {
4+
connect: static func(name: string) -> result<client, error>;
5+
}
6+
77
/// TODO(danbugs): This should be eventually extracted as an underlying type for other wasi-cloud-core interfaces.
8-
type error = u32;
9-
drop-error: func(e: error);
10-
trace: func(e: error) -> string;
8+
resource error {
9+
trace: static func() -> string;
10+
}
1111

1212
/// There are two types of channels:
1313
/// - publish-subscribe channel, which is a broadcast channel, and

0 commit comments

Comments
 (0)