From b59de1b60571bdfe4fe11e5deb79d7363e13ba9e Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Mon, 8 Jan 2024 18:05:05 -0800 Subject: [PATCH 1/3] Convert `//`-style comments to `///`. Per the discussion in WebAssembly/component-model#273, the Wit format is moving to only have documentation comments. A as of WebAssembly/component-model#286, the syntax for documentation commments is `///`. This patch converts a few of the remaining `//` comments in network.wit to `///` comments. --- wit/network.wit | 36 +++++++++++++++++------------------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/wit/network.wit b/wit/network.wit index 6bb07cd..9cadf06 100644 --- a/wit/network.wit +++ b/wit/network.wit @@ -18,8 +18,6 @@ interface network { /// /// See each individual API for what the POSIX equivalents are. They sometimes differ per API. enum error-code { - // ### GENERAL ERRORS ### - /// Unknown error unknown, @@ -64,9 +62,6 @@ interface network { would-block, - - // ### TCP & UDP SOCKET ERRORS ### - /// The operation is not valid in the socket's current state. invalid-state, @@ -83,24 +78,21 @@ interface network { remote-unreachable, - // ### TCP SOCKET ERRORS ### - - /// The connection was forcefully rejected + /// The TCP connection was forcefully rejected connection-refused, - /// The connection was reset. + /// The TCP connection was reset. connection-reset, - /// A connection was aborted. + /// A TCP connection was aborted. connection-aborted, - // ### UDP SOCKET ERRORS ### + /// The size of a datagram sent to a UDP socket exceeded the maximum + /// supported size. datagram-too-large, - // ### NAME LOOKUP ERRORS ### - /// Name does not exist or has no suitable associated IP addresses. name-unresolvable, @@ -128,15 +120,21 @@ interface network { } record ipv4-socket-address { - port: u16, // sin_port - address: ipv4-address, // sin_addr + /// sin_port + port: u16, + /// sin_addr + address: ipv4-address, } record ipv6-socket-address { - port: u16, // sin6_port - flow-info: u32, // sin6_flowinfo - address: ipv6-address, // sin6_addr - scope-id: u32, // sin6_scope_id + /// sin6_port + port: u16, + /// sin6_flowinfo + flow-info: u32, + /// sin6_addr + address: ipv6-address, + /// sin6_scope_id + scope-id: u32, } variant ip-socket-address { From 12460b4568c7a45d20db433b15555a41eb0c6985 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Mon, 8 Jan 2024 18:09:49 -0800 Subject: [PATCH 2/3] Update imports.md. --- imports.md | 77 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 64 insertions(+), 13 deletions(-) diff --git a/imports.md b/imports.md index cdbe6e6..4cc6c2c 100644 --- a/imports.md +++ b/imports.md @@ -20,6 +20,9 @@

Types

resource network

+

An opaque resource that represents access to (a subset of) the network. +This enables context-based security for networking. +There is no need for this to map 1:1 to a physical network interface.

enum error-code

Error codes.

In theory, every API can return any error code. @@ -102,18 +105,20 @@ combined with a couple of errors that are always possible:

  • connection-refused

    -

    The connection was forcefully rejected +

    The TCP connection was forcefully rejected

  • connection-reset

    -

    The connection was reset. +

    The TCP connection was reset.

  • connection-aborted

    -

    A connection was aborted. +

    A TCP connection was aborted.

  • datagram-too-large

    +

    The size of a datagram sent to a UDP socket exceeded the maximum +supported size.

  • name-unresolvable

    @@ -169,16 +174,34 @@ combined with a couple of errors that are always possible:

    record ipv4-socket-address

    Record Fields

    record ipv6-socket-address

    Record Fields

    variant ip-socket-address

    Variant Cases
    @@ -207,7 +230,7 @@ at once.

    Types

    resource pollable

    -
    +

    pollable epresents a single I/O event which may be ready, or not.

    Functions

    [method]pollable.ready: func

    Return the readiness of a pollable. This function never blocks.

    @@ -305,6 +328,7 @@ being reaedy for I/O.

    • resource udp-socket

    +

    A UDP socket handle.

    resource incoming-datagram-stream

    resource outgoing-datagram-stream

    @@ -740,7 +764,21 @@ the socket is effectively an in-memory configuration object, unable to communica

    Types

    resource error

    -
    +

    A resource which represents some error information.

    +

    The only method provided by this resource is to-debug-string, +which provides some human-readable information about the error.

    +

    In the wasi:io package, this resource is returned through the +wasi:io/streams/stream-error type.

    +

    To provide more specific error information, other interfaces may +provide functions to further "downcast" this error into more specific +error information. For example, errors returned in streams derived +from filesystem types to be described using the filesystem's own +error-code type, using the function +wasi:filesystem/types/filesystem-error-code, which takes a parameter +borrow<error> and returns +option<wasi:filesystem/types/error-code>.

    +

    The set of functions which can "downcast" an error into a more +concrete type is open.

    Functions

    [method]error.to-debug-string: func

    Returns a string that is suitable to assist humans in debugging @@ -787,8 +825,21 @@ future operations.

    resource input-stream

    +

    An input bytestream.

    +

    input-streams are non-blocking to the extent practical on underlying +platforms. I/O operations always return promptly; if fewer bytes are +promptly available than requested, they return the number of bytes promptly +available, which could even be zero. To wait for data to be available, +use the subscribe function to obtain a pollable which can be polled +for using wasi:io/poll.

    resource output-stream

    -
    +

    An output bytestream.

    +

    output-streams are non-blocking to the extent practical on +underlying platforms. Except where specified otherwise, I/O operations also +always return promptly, after the number of bytes that can be written +promptly, which could even be zero. To wait for the stream to be ready to +accept data, the subscribe function to obtain a pollable which can be +polled for using wasi:io/poll.

    Functions

    [method]input-stream.read: func

    Perform a non-blocking read from the stream.

    @@ -1165,7 +1216,7 @@ occured.

    resource tcp-socket

    -
    +

    A TCP socket handle.

    Functions

    [method]tcp-socket.start-bind: func

    Bind the socket to a specific network on the provided IP address and port.

    From 6a7f88354e4a2680ddd8d0f81697c6b970a0555d Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Mon, 8 Jan 2024 18:14:25 -0800 Subject: [PATCH 3/3] Update CI dependencies. --- .github/workflows/main.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index af3c079..185f6a1 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -10,7 +10,7 @@ jobs: name: Check ABI files are up-to-date runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: ensure `./wit/deps` are in sync run: | curl -Lo 'wit-deps' https://github.com/bytecodealliance/wit-deps/releases/download/v0.3.3/wit-deps-x86_64-unknown-linux-musl @@ -18,4 +18,4 @@ jobs: ./wit-deps lock git add -N wit/deps git diff --exit-code - - uses: WebAssembly/wit-abi-up-to-date@v16 + - uses: WebAssembly/wit-abi-up-to-date@v17