Debian Codegraph @

vendor/wit-component/tests/interfaces/wasi-http/deps/sockets/udp.wit

raw
1
2 interface udp {
3 use wasi:io/[email protected].{pollable};
4 use network.{network, error-code, ip-socket-address, ip-address-family};
5
6 /// A received datagram.
7 record incoming-datagram {
8 /// The payload.
9 ///
10 /// Theoretical max size: ~64 KiB. In practice, typically less than 1500 bytes.
11 data: list<u8>,
12
13 /// The source address.
14 ///
15 /// This field is guaranteed to match the remote address the stream was initialized with, if any.
16 ///
17 /// Equivalent to the `src_addr` out parameter of `recvfrom`.
18 remote-address: ip-socket-address,
19 }
20
21 /// A datagram to be sent out.
22 record outgoing-datagram {
23 /// The payload.
24 data: list<u8>,
25
26 /// The destination address.
27 ///
28 /// The requirements on this field depend on how the stream was initialized:
29 /// - with a remote address: this field must be None or match the stream's remote address exactly.
30 /// - without a remote address: this field is required.
31 ///
32 /// If this value is None, the send operation is equivalent to `send` in POSIX. Otherwise it is equivalent to `sendto`.
33 remote-address: option<ip-socket-address>,
34 }
35
36
37
38 /// A UDP socket handle.
39 resource udp-socket {
40 /// Bind the socket to a specific network on the provided IP address and port.
41 ///
42 /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
43 /// network interface(s) to bind to.
44 /// If the port is zero, the socket will be bound to a random free port.
45 ///
46 /// Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
47 ///
48 /// # Typical `start` errors
49 /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
50 /// - `invalid-state`: The socket is already bound. (EINVAL)
51 ///
52 /// # Typical `finish` errors
53 /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
54 /// - `address-in-use`: Address is already in use. (EADDRINUSE)
55 /// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
56 /// - `not-in-progress`: A `bind` operation is not in progress.
57 /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
58 ///
59 /// # References
60 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
61 /// - <https://man7.org/linux/man-pages/man2/bind.2.html>
62 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
63 /// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
64 start-bind: func(network: borrow<network>, local-address: ip-socket-address) -> result<_, error-code>;
65 finish-bind: func() -> result<_, error-code>;
66
67 /// Set up inbound & outbound communication channels, optionally to a specific peer.
68 ///
69 /// This function only changes the local socket configuration and does not generate any network traffic.
70 /// On success, the `remote-address` of the socket is updated. The `local-address` may be updated as well,
71 /// based on the best network path to `remote-address`.
72 ///
73 /// When a `remote-address` is provided, the returned streams are limited to communicating with that specific peer:
74 /// - `send` can only be used to send to this destination.
75 /// - `receive` will only return datagrams sent from the provided `remote-address`.
76 ///
77 /// This method may be called multiple times on the same socket to change its association, but
78 /// only the most recently returned pair of streams will be operational. Implementations may trap if
79 /// the streams returned by a previous invocation haven't been dropped yet before calling `stream` again.
80 ///
81 /// The POSIX equivalent in pseudo-code is:
82 /// ```text
83 /// if (was previously connected) {
84 /// connect(s, AF_UNSPEC)
85 /// }
86 /// if (remote_address is Some) {
87 /// connect(s, remote_address)
88 /// }
89 /// ```
90 ///
91 /// Unlike in POSIX, the socket must already be explicitly bound.
92 ///
93 /// # Typical errors
94 /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
95 /// - `invalid-argument`: `remote-address` is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
96 /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
97 /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
98 /// - `invalid-state`: The socket is not bound.
99 /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
100 /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
101 /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
102 ///
103 /// # References
104 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
105 /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
106 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
107 /// - <https://man.freebsd.org/cgi/man.cgi?connect>
108 %stream: func(remote-address: option<ip-socket-address>) -> result<tuple<incoming-datagram-stream, outgoing-datagram-stream>, error-code>;
109
110 /// Get the current bound address.
111 ///
112 /// POSIX mentions:
113 /// > If the socket has not been bound to a local name, the value
114 /// > stored in the object pointed to by `address` is unspecified.
115 ///
116 /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
117 ///
118 /// # Typical errors
119 /// - `invalid-state`: The socket is not bound to any local address.
120 ///
121 /// # References
122 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
123 /// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
124 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
125 /// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
126 local-address: func() -> result<ip-socket-address, error-code>;
127
128 /// Get the address the socket is currently streaming to.
129 ///
130 /// # Typical errors
131 /// - `invalid-state`: The socket is not streaming to a specific remote address. (ENOTCONN)
132 ///
133 /// # References
134 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
135 /// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
136 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
137 /// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
138 remote-address: func() -> result<ip-socket-address, error-code>;
139
140 /// Whether this is a IPv4 or IPv6 socket.
141 ///
142 /// Equivalent to the SO_DOMAIN socket option.
143 address-family: func() -> ip-address-family;
144
145 /// Whether IPv4 compatibility (dual-stack) mode is disabled or not.
146 ///
147 /// Equivalent to the IPV6_V6ONLY socket option.
148 ///
149 /// # Typical errors
150 /// - `not-supported`: (get/set) `this` socket is an IPv4 socket.
151 /// - `invalid-state`: (set) The socket is already bound.
152 /// - `not-supported`: (set) Host does not support dual-stack sockets. (Implementations are not required to.)
153 ipv6-only: func() -> result<bool, error-code>;
154 set-ipv6-only: func(value: bool) -> result<_, error-code>;
155
156 /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
157 ///
158 /// If the provided value is 0, an `invalid-argument` error is returned.
159 ///
160 /// # Typical errors
161 /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
162 unicast-hop-limit: func() -> result<u8, error-code>;
163 set-unicast-hop-limit: func(value: u8) -> result<_, error-code>;
164
165 /// The kernel buffer space reserved for sends/receives on this socket.
166 ///
167 /// If the provided value is 0, an `invalid-argument` error is returned.
168 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
169 /// I.e. after setting a value, reading the same setting back may return a different value.
170 ///
171 /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
172 ///
173 /// # Typical errors
174 /// - `invalid-argument`: (set) The provided value was 0.
175 receive-buffer-size: func() -> result<u64, error-code>;
176 set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
177 send-buffer-size: func() -> result<u64, error-code>;
178 set-send-buffer-size: func(value: u64) -> result<_, error-code>;
179
180 /// Create a `pollable` which will resolve once the socket is ready for I/O.
181 ///
182 /// Note: this function is here for WASI Preview2 only.
183 /// It's planned to be removed when `future` is natively supported in Preview3.
184 subscribe: func() -> pollable;
185 }
186
187 resource incoming-datagram-stream {
188 /// Receive messages on the socket.
189 ///
190 /// This function attempts to receive up to `max-results` datagrams on the socket without blocking.
191 /// The returned list may contain fewer elements than requested, but never more.
192 ///
193 /// This function returns successfully with an empty list when either:
194 /// - `max-results` is 0, or:
195 /// - `max-results` is greater than 0, but no results are immediately available.
196 /// This function never returns `error(would-block)`.
197 ///
198 /// # Typical errors
199 /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
200 /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
201 ///
202 /// # References
203 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvfrom.html>
204 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/recvmsg.html>
205 /// - <https://man7.org/linux/man-pages/man2/recv.2.html>
206 /// - <https://man7.org/linux/man-pages/man2/recvmmsg.2.html>
207 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recv>
208 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-recvfrom>
209 /// - <https://learn.microsoft.com/en-us/previous-versions/windows/desktop/legacy/ms741687(v=vs.85)>
210 /// - <https://man.freebsd.org/cgi/man.cgi?query=recv&sektion=2>
211 receive: func(max-results: u64) -> result<list<incoming-datagram>, error-code>;
212
213 /// Create a `pollable` which will resolve once the stream is ready to receive again.
214 ///
215 /// Note: this function is here for WASI Preview2 only.
216 /// It's planned to be removed when `future` is natively supported in Preview3.
217 subscribe: func() -> pollable;
218 }
219
220 resource outgoing-datagram-stream {
221 /// Check readiness for sending. This function never blocks.
222 ///
223 /// Returns the number of datagrams permitted for the next call to `send`,
224 /// or an error. Calling `send` with more datagrams than this function has
225 /// permitted will trap.
226 ///
227 /// When this function returns ok(0), the `subscribe` pollable will
228 /// become ready when this function will report at least ok(1), or an
229 /// error.
230 ///
231 /// Never returns `would-block`.
232 check-send: func() -> result<u64, error-code>;
233
234 /// Send messages on the socket.
235 ///
236 /// This function attempts to send all provided `datagrams` on the socket without blocking and
237 /// returns how many messages were actually sent (or queued for sending). This function never
238 /// returns `error(would-block)`. If none of the datagrams were able to be sent, `ok(0)` is returned.
239 ///
240 /// This function semantically behaves the same as iterating the `datagrams` list and sequentially
241 /// sending each individual datagram until either the end of the list has been reached or the first error occurred.
242 /// If at least one datagram has been sent successfully, this function never returns an error.
243 ///
244 /// If the input list is empty, the function returns `ok(0)`.
245 ///
246 /// Each call to `send` must be permitted by a preceding `check-send`. Implementations must trap if
247 /// either `check-send` was not called or `datagrams` contains more items than `check-send` permitted.
248 ///
249 /// # Typical errors
250 /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
251 /// - `invalid-argument`: `remote-address` is a non-IPv4-mapped IPv6 address, but the socket was bound to a specific IPv4-mapped IPv6 address. (or vice versa)
252 /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EDESTADDRREQ, EADDRNOTAVAIL)
253 /// - `invalid-argument`: The port in `remote-address` is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
254 /// - `invalid-argument`: The socket is in "connected" mode and `remote-address` is `some` value that does not match the address passed to `stream`. (EISCONN)
255 /// - `invalid-argument`: The socket is not "connected" and no value for `remote-address` was provided. (EDESTADDRREQ)
256 /// - `remote-unreachable`: The remote address is not reachable. (ECONNRESET, ENETRESET on Windows, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
257 /// - `connection-refused`: The connection was refused. (ECONNREFUSED)
258 /// - `datagram-too-large`: The datagram is too large. (EMSGSIZE)
259 ///
260 /// # References
261 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendto.html>
262 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/sendmsg.html>
263 /// - <https://man7.org/linux/man-pages/man2/send.2.html>
264 /// - <https://man7.org/linux/man-pages/man2/sendmmsg.2.html>
265 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-send>
266 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-sendto>
267 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-wsasendmsg>
268 /// - <https://man.freebsd.org/cgi/man.cgi?query=send&sektion=2>
269 send: func(datagrams: list<outgoing-datagram>) -> result<u64, error-code>;
270
271 /// Create a `pollable` which will resolve once the stream is ready to send again.
272 ///
273 /// Note: this function is here for WASI Preview2 only.
274 /// It's planned to be removed when `future` is natively supported in Preview3.
275 subscribe: func() -> pollable;
276 }
277 }