Skip to content

Commit c2a7421

Browse files
MossakaMossaka
authored
chore(*): split world to imports and re-version to 0.2.0-draft (#20)
this commit splits the existing messaging world into two worlds. 1. imports 2. messaging that includes imports world to follow the convention of other WIT packages in WASI. It also re-versions the wit package to `0.2.0-draft` Signed-off-by: Jiaxiao Zhou (Mossaka) <[email protected]>
1 parent b102727 commit c2a7421

File tree

4 files changed

+251
-63
lines changed

4 files changed

+251
-63
lines changed

‎.github/workflows/main.yml‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,4 +13,5 @@ jobs:
1313
- uses: actions/checkout@v2
1414
- uses: WebAssembly/wit-abi-up-to-date@v17
1515
with:
16-
wit-bindgen: '0.16.0'
16+
wit-bindgen: '0.18.0'
17+
worlds: 'imports messaging'

‎imports.md‎

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

0 commit comments

Comments
 (0)