feat: add `wasi-0.3.0` draft by rvolosatovs · Pull Request #111 · WebAssembly/wasi-sockets

rvolosatovs · 2025-01-14T11:40:28Z

Followed the example of wasi-http and wasi-clocks duplicating the package in a subdirectory

This vendors wasi-clocks from WebAssembly/wasi-clocks#77

In wasip3 return values of functions are pollable by guests, therefore remove abstractions for which there is no need anymore:
- Replace start-X/finish-X function pairs by X
- Remove would-block error code
- Remove not-in-progress error code
Replace wasi:io/error.error usage by error-context
Replace wasi:io/streams.input-stream return values by stream<u8> in return position
Replace wasi:io/streams.output-stream return values by stream<u8> in parameter position - Guests should be able to rely on stream.new to construct streams

Followed the example of `wasi-http` and `wasi-clocks` duplicating the package in a subdirectory - In wasip3 return values of functions are pollable by guests, therefore remove abstractions for which there is no need anymore: - Replace `start-X`/`finish-X` function pairs by `X` - Remove `would-block` error code - Remove `not-in-progress` error code - Replace `wasi:io/error.error` usage by `error-context` - Replace `wasi:io/streams.input-stream` return values by `stream<u8>` in return position - Replace `wasi:io/streams.output-stream` return values by `stream<u8>` in parameter position - Guests should be able to rely on `stream.new` to construct streams Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

This seems to be better aligned with latest specification on error context https://github.com/WebAssembly/component-model/blob/cbdd15d9033446558571824af52a78022aaa3f58/design/mvp/Explainer.md#error-context-type > A consequence of this, however, is that components *must not* depend on the > contents of `error-context` values for behavioral correctness. In particular, > case analysis of the contents of an `error-context` should not determine > *error recovery*; explicit `result` or `variant` types must be used in the > function return type instead (e.g., > `(func (result (tuple (stream u8) (future $my-error)))`). Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

rvolosatovs · 2025-01-14T14:13:17Z

After reading the error-context spec a bit more, it seems these are not meant to be introspected, therefore I added 8cc04c8

https://github.com/WebAssembly/component-model/blob/cbdd15d9033446558571824af52a78022aaa3f58/design/mvp/Explainer.md#error-context-type

A consequence of this, however, is that components must not depend on the
contents of error-context values for behavioral correctness. In particular,
case analysis of the contents of an error-context should not determine
error recovery; explicit result or variant types must be used in the
function return type instead (e.g.,
(func (result (tuple (stream u8) (future $my-error)))).

@lukewagner perhaps you could confirm that the changes in that commit are moving in the direction you'd expect?

WebAssembly/wasi-filesystem#164 (comment) Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

lukewagner · 2025-01-14T23:34:59Z

Yes, you're right about the direction; thanks for asking! Indeed, error-context is a value type (not a resource type) and so borrow<error-context> shouldn't even validate.

I'm not that familiar with wasi-sockets, but I wonder if we could simplify connect a bit so that we didn't have one function returning such a complex type. Could it look a bit more like:

resource tcp-socket {
  connect:func(n: borrow<network>, remote: ip-socket-address) -> result<tcp-connection, error-code>;
}
resource tcp-connection {
  write: func(tx: stream<u8>) -> result<option<error-code>>;
  read: func() -> result<tuple<stream<u8>, future<option<error-code>>>>;
}

(where read and write return fail if called while a preceding read/write is active)? This is roughly analogous to what we do in wasi-http for consuming bodies.

To wit, once we add stream<T,U> (not in 0.3.0, but in some 0.3.x follow-up), tcp-connection.read could be simplified to:

  read: func() -> result<stream<u8, option<error-code>>

cc @dicej for any other thoughts

Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

…capability.

… `constructor`s

…oper streams with cancellation.

…ymore, `listen` is free to do an implicit bind again. Just like POSIX.

…of client sockets.

… already covers all its use-cases. Was an oversight in v0.2

…ymore, `stream` is free to do an implicit bind again. Just like POSIX.

Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

Co-authored-by: Roman Volosatovs <rvolosatovs@users.noreply.github.com>

badeend · 2025-01-16T18:45:24Z

The suggestion of @rvolosatovs seems the most natural to me:

receive: func() -> tuple<stream<u8>, future<result<_, error-code>>>;

especially since that may be shortened even further to:

receive: func() -> stream<u8, error-code>;

depending on the progress of error-contexts

wit-0.3.0-draft/types.wit

rvolosatovs · 2025-01-17T09:34:43Z

Thanks @badeend, your changes look good to me, just left one comment.

Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

This ensures that e.g.: ``` wit-bindgen markdown wit-0.3.0-draft -w imports --html-in-md ``` works with wit-bindgen 0.37 refs: WebAssembly/wasi-sockets@3abda6e refs: WebAssembly/wasi-sockets#111 (comment) Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

Co-authored-by: Roman Volosatovs <rvolosatovs@users.noreply.github.com>

…isten`, and provide guidance on how implementations may handle them.

… of `connect` & `listen` even further.

…hen they're done, whereas UDP packets should be able to fail/succeed independently without affecting the transmission of other packets. Without the stream parameter and return value, the `transfer` method is beginning to look an afwul lot like `connect` again, so we might as well call it that.

…tion of ComponentModel-level subtyping of value types, so that we could add additional fields (e.g. TTL, TOS, etc.) without breaking backwards-compatibility. AFAIK, that idea has been put on hold indefinitely, so we might as well make the 0.3.0 interface as simple as possible

badeend · 2025-01-19T22:08:40Z

Hi,

I've reverted the usage of streams on UDP sockets. streams are only able to fail once and then they're done, whereas UDP packets should be able to fail/succeed independently without affecting the transmission of other packets on the socket. Now, send & receive are regular methods as they were back in the day. Without the stream parameter and the stream return value, the transfer method is beginning to look an afwul lot like connect again, so we might as well call it that again.
I've removed the tcp-connection type and moved send & receive into tcp-socket. This simplifies the signatures of connect/listen and the general API design even further. This is at the expense of a bit of typestate, though at this point I've basically given up the hope this will ever be a pretty interface like that. Given the amount of existing invalid-state checks that already exist, I think it's more consistent to do these two final methods via runtime checks as well.
Removed outer result from tcp-socket::receive, as discussed above and already applied in wasi-filesystem.
Removed inbound/outbound-datagram records. They were added in anticipation of ComponentModel-level subtyping of value types, so that we could add additional fields (e.g. TTL, TOS, etc.) without breaking backwards-compatibility. AFAIK, that idea has been put on hold indefinitely, so we might as well make the 0.3.0 interface as simple as possible.
And some further documentation updates.

As before, let me know what you think!

rvolosatovs · 2025-01-21T10:33:52Z

I think this looks good. Especially, since this is still meant to be a draft, I'd prefer validating this API by implementing it in a runtime (Wasmtime) and a component.

wit-0.3.0-draft/deps/clocks/monotonic-clock.wit

badeend · 2025-01-21T18:18:31Z

Alright, I think this is already more than good enough for the first draft, so I'm going to merge it now.

* feat: add `wasi-0.3.0` draft Followed the example of `wasi-http` and `wasi-clocks` duplicating the package in a subdirectory - Remove `would-block` error code - Replace `wasi:io/error.error` usage by `error-context` - Replace `wasi:io/streams.input-stream` return values by `stream<u8>` in return position - Replace `wasi:io/streams.output-stream` return values by `stream<u8>` in parameter position - Guests should be able to rely on `stream.new` to construct streams - Merge `read{,via-stream}` into a singular `read`. Both functions take an offset as a parameter and since they now return `stream<u8>`, callers can limit the amount of bytes read by using the `stream<u8>` directly, therefore functionality of both is identical - Merge `write{,via-stream}` into a singular `write`. Both functions take an offset and `stream<u8>` as a parameter. It is assumed that `error-context` returned by writes to the stream and reads from the stream are sufficient for error handling. Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * refactor: avoid introspecting `error-context` This seems to be better aligned with latest specification on error context https://github.com/WebAssembly/component-model/blob/cbdd15d9033446558571824af52a78022aaa3f58/design/mvp/Explainer.md#error-context-type > A consequence of this, however, is that components *must not* depend on the > contents of `error-context` values for behavioral correctness. In particular, > case analysis of the contents of an `error-context` should not determine > *error recovery*; explicit `result` or `variant` types must be used in the > function return type instead (e.g., > `(func (result (tuple (stream u8) (future $my-error)))`). Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * chore: bump `@since` to `0.3.0` #164 (comment) Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * refactor(0.3): simplify error handling Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * refactor(0.3): asyncify `read-directory` Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * feat: update wit-deps to 0.5.0 Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * drop `-draft` version suffix This ensures that e.g.: ``` wit-bindgen markdown wit-0.3.0-draft -w imports --html-in-md ``` works with wit-bindgen 0.37 refs: WebAssembly/wasi-sockets@3abda6e refs: WebAssembly/wasi-sockets#111 (comment) Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> --------- Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

* feat: add `wasi-0.3.0` draft Followed the example of `wasi-http` and `wasi-clocks` duplicating the package in a subdirectory - Remove `would-block` error code - Replace `wasi:io/error.error` usage by `error-context` - Replace `wasi:io/streams.input-stream` return values by `stream<u8>` in return position - Replace `wasi:io/streams.output-stream` return values by `stream<u8>` in parameter position - Guests should be able to rely on `stream.new` to construct streams - Merge `read{,via-stream}` into a singular `read`. Both functions take an offset as a parameter and since they now return `stream<u8>`, callers can limit the amount of bytes read by using the `stream<u8>` directly, therefore functionality of both is identical - Merge `write{,via-stream}` into a singular `write`. Both functions take an offset and `stream<u8>` as a parameter. It is assumed that `error-context` returned by writes to the stream and reads from the stream are sufficient for error handling. Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * refactor: avoid introspecting `error-context` This seems to be better aligned with latest specification on error context https://github.com/WebAssembly/component-model/blob/cbdd15d9033446558571824af52a78022aaa3f58/design/mvp/Explainer.md#error-context-type > A consequence of this, however, is that components *must not* depend on the > contents of `error-context` values for behavioral correctness. In particular, > case analysis of the contents of an `error-context` should not determine > *error recovery*; explicit `result` or `variant` types must be used in the > function return type instead (e.g., > `(func (result (tuple (stream u8) (future $my-error)))`). Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * chore: bump `@since` to `0.3.0` WebAssembly/wasi-filesystem#164 (comment) Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * refactor(0.3): simplify error handling Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * refactor(0.3): asyncify `read-directory` Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * feat: update wit-deps to 0.5.0 Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> * drop `-draft` version suffix This ensures that e.g.: ``` wit-bindgen markdown wit-0.3.0-draft -w imports --html-in-md ``` works with wit-bindgen 0.37 refs: WebAssembly/wasi-sockets@3abda6e refs: WebAssembly/wasi-sockets#111 (comment) Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net> --------- Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

rvolosatovs force-pushed the feat/0.3.0-draft branch 2 times, most recently from 605a6b4 to 92f2c42 Compare January 14, 2025 11:44

rvolosatovs marked this pull request as ready for review January 14, 2025 11:44

rvolosatovs force-pushed the feat/0.3.0-draft branch from 92f2c42 to d0f8ab5 Compare January 14, 2025 11:55

rvolosatovs mentioned this pull request Jan 14, 2025

feat: add wasi-0.3.0 draft WebAssembly/wasi-filesystem#164

Merged

chore: bump @since to 0.3.0

8a3b482

WebAssembly/wasi-filesystem#164 (comment) Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

rvolosatovs force-pushed the feat/0.3.0-draft branch from dfc429e to 8a3b482 Compare January 14, 2025 15:25

rvolosatovs and others added 19 commits January 15, 2025 12:12

feat(0.3): introduce tcp-connection

a4ca7f6

Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

Add TcpSocketOperationalSemantics-0.3.0-draft.md

955b5a4

Remove resolve-address-stream

c5b9684

Split lookup errors off from the general socket errors type

26390db

Remove the runtime network capability and rely solely on link-time …

bee1ffd

…capability.

Remove create-tcp/udp-socket methods & interfaces in favor of plain…

6de677f

… `constructor`s

Rename write -> send, read -> receive

4417d18

Remove the TCP shutdown method. It is redundant now that we have pr…

544ec8c

…oper streams with cancellation.

Now that binding a socket doesn't require a runtime network handle an…

5134af0

…ymore, `listen` is free to do an implicit bind again. Just like POSIX.

Merge listen & accept into a single method that returns a stream …

3778219

…of client sockets.

Update state names

2752e1b

Clarify EALREADY equivalence

c48f6b9

Remove superfluous concurrency-conflict error code. invalid-state…

ee62973

… already covers all its use-cases. Was an oversight in v0.2

Add Since annotations to tcp-connection

c483c3a

Remove last references to wasi:io

401fc2b

Remove outdated doc now that we have tcp-connection.

762a3ab

Now that binding a socket doesn't require a runtime network handle an…

7f3ec8d

…ymore, `stream` is free to do an implicit bind again. Just like POSIX.

feat(0.3): asyncify resolve-address-stream

0e8554f

Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

Merge UDP send into %stream

dbe26c7

Update TcpSocketOperationalSemantics-0.3.0-draft.md

e92d144

Co-authored-by: Roman Volosatovs <rvolosatovs@users.noreply.github.com>

rvolosatovs commented Jan 17, 2025

View reviewed changes

wit-0.3.0-draft/types.wit Outdated Show resolved Hide resolved

rvolosatovs force-pushed the feat/0.3.0-draft branch from 6a44e3c to 2a47838 Compare January 17, 2025 09:37

feat: update wit-deps to 0.5.0

f646c25

Signed-off-by: Roman Volosatovs <rvolosatovs@riseup.net>

rvolosatovs force-pushed the feat/0.3.0-draft branch from 2a47838 to f646c25 Compare January 17, 2025 09:38

This was referenced Jan 17, 2025

feat(0.3): rework stream error handling/remove wasi:io usage WebAssembly/wasi-http#143

Merged

feat: add wit-0.3.0-draft WebAssembly/wasi-cli#52

Merged

ricochet assigned rvolosatovs Jan 17, 2025

badeend and others added 7 commits January 17, 2025 21:19

Update wit-0.3.0-draft/types.wit

bbebffa

Co-authored-by: Roman Volosatovs <rvolosatovs@users.noreply.github.com>

Fix WSARecvMsg link

074d948

Document the distinction between permanent and transient errors on `l…

5efd1e9

…isten`, and provide guidance on how implementations may handle them.

Move send & receive into tcp-socket, simplifying the signatures…

7545a4b

… of `connect` & `listen` even further.

Remove outer result from receive

dcf0b76

Clarify address-family

0e6b058

pavelsavara reviewed Jan 21, 2025

View reviewed changes

wit-0.3.0-draft/deps/clocks/monotonic-clock.wit Show resolved Hide resolved

badeend merged commit c754b33 into WebAssembly:main Jan 21, 2025

sunfishcode mentioned this pull request Jan 21, 2025

Revise the documentation for WASI 0.3.0's tcp-socket::receive. #112

Merged

This was referenced Feb 26, 2025

fix(wasip3): allow send on unbound UDP sockets #118

Merged

refactor(p3): clarify tcp-socket.receive semantics #119

Merged

badeend mentioned this pull request Dec 23, 2025

feat(p3): add client interface WebAssembly/wasi-tls#17

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add `wasi-0.3.0` draft#111

feat: add `wasi-0.3.0` draft#111
badeend merged 37 commits intoWebAssembly:mainfrom
rvolosatovs:feat/0.3.0-draft

rvolosatovs commented Jan 14, 2025 •

edited

Loading

Uh oh!

rvolosatovs commented Jan 14, 2025

Uh oh!

lukewagner commented Jan 14, 2025

Uh oh!

badeend commented Jan 16, 2025

Uh oh!

Uh oh!

rvolosatovs commented Jan 17, 2025

Uh oh!

badeend commented Jan 19, 2025

Uh oh!

rvolosatovs commented Jan 21, 2025

Uh oh!

Uh oh!

badeend commented Jan 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

rvolosatovs commented Jan 14, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

rvolosatovs commented Jan 14, 2025

Uh oh!

lukewagner commented Jan 14, 2025

Uh oh!

badeend commented Jan 16, 2025

Uh oh!

Uh oh!

rvolosatovs commented Jan 17, 2025

Uh oh!

badeend commented Jan 19, 2025

Uh oh!

rvolosatovs commented Jan 21, 2025

Uh oh!

Uh oh!

badeend commented Jan 21, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

rvolosatovs commented Jan 14, 2025 •

edited

Loading