Debian Codegraph @

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

raw
1
2 interface tcp {
3 use wasi:io/[email protected].{input-stream, output-stream};
4 use wasi:io/[email protected].{pollable};
5 use wasi:clocks/[email protected].{duration};
6 use network.{network, error-code, ip-socket-address, ip-address-family};
7
8 enum shutdown-type {
9 /// Similar to `SHUT_RD` in POSIX.
10 receive,
11
12 /// Similar to `SHUT_WR` in POSIX.
13 send,
14
15 /// Similar to `SHUT_RDWR` in POSIX.
16 both,
17 }
18
19
20 /// A TCP socket handle.
21 resource tcp-socket {
22 /// Bind the socket to a specific network on the provided IP address and port.
23 ///
24 /// If the IP address is zero (`0.0.0.0` in IPv4, `::` in IPv6), it is left to the implementation to decide which
25 /// network interface(s) to bind to.
26 /// If the TCP/UDP port is zero, the socket will be bound to a random free port.
27 ///
28 /// When a socket is not explicitly bound, the first invocation to a listen or connect operation will
29 /// implicitly bind the socket.
30 ///
31 /// Unlike in POSIX, this function is async. This enables interactive WASI hosts to inject permission prompts.
32 ///
33 /// # Typical `start` errors
34 /// - `invalid-argument`: The `local-address` has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
35 /// - `invalid-argument`: `local-address` is not a unicast address. (EINVAL)
36 /// - `invalid-argument`: `local-address` is an IPv4-mapped IPv6 address, but the socket has `ipv6-only` enabled. (EINVAL)
37 /// - `invalid-state`: The socket is already bound. (EINVAL)
38 ///
39 /// # Typical `finish` errors
40 /// - `address-in-use`: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
41 /// - `address-in-use`: Address is already in use. (EADDRINUSE)
42 /// - `address-not-bindable`: `local-address` is not an address that the `network` can bind to. (EADDRNOTAVAIL)
43 /// - `not-in-progress`: A `bind` operation is not in progress.
44 /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
45 ///
46 /// # References
47 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html>
48 /// - <https://man7.org/linux/man-pages/man2/bind.2.html>
49 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind>
50 /// - <https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html>
51 start-bind: func(network: borrow<network>, local-address: ip-socket-address) -> result<_, error-code>;
52 finish-bind: func() -> result<_, error-code>;
53
54 /// Connect to a remote endpoint.
55 ///
56 /// On success:
57 /// - the socket is transitioned into the Connection state
58 /// - a pair of streams is returned that can be used to read & write to the connection
59 ///
60 /// POSIX mentions:
61 /// > If connect() fails, the state of the socket is unspecified. Conforming applications should
62 /// > close the file descriptor and create a new socket before attempting to reconnect.
63 ///
64 /// WASI prescribes the following behavior:
65 /// - If `connect` fails because an input/state validation error, the socket should remain usable.
66 /// - If a connection was actually attempted but failed, the socket should become unusable for further network communication.
67 /// Besides `drop`, any method after such a failure may return an error.
68 ///
69 /// # Typical `start` errors
70 /// - `invalid-argument`: The `remote-address` has the wrong address family. (EAFNOSUPPORT)
71 /// - `invalid-argument`: `remote-address` is not a unicast address. (EINVAL, ENETUNREACH on Linux, EAFNOSUPPORT on MacOS)
72 /// - `invalid-argument`: `remote-address` is an IPv4-mapped IPv6 address, but the socket has `ipv6-only` enabled. (EINVAL, EADDRNOTAVAIL on Illumos)
73 /// - `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)
74 /// - `invalid-argument`: The IP address in `remote-address` is set to INADDR_ANY (`0.0.0.0` / `::`). (EADDRNOTAVAIL on Windows)
75 /// - `invalid-argument`: The port in `remote-address` is set to 0. (EADDRNOTAVAIL on Windows)
76 /// - `invalid-argument`: The socket is already attached to a different network. The `network` passed to `connect` must be identical to the one passed to `bind`.
77 /// - `invalid-state`: The socket is already in the Connection state. (EISCONN)
78 /// - `invalid-state`: The socket is already in the Listener state. (EOPNOTSUPP, EINVAL on Windows)
79 ///
80 /// # Typical `finish` errors
81 /// - `timeout`: Connection timed out. (ETIMEDOUT)
82 /// - `connection-refused`: The connection was forcefully rejected. (ECONNREFUSED)
83 /// - `connection-reset`: The connection was reset. (ECONNRESET)
84 /// - `connection-aborted`: The connection was aborted. (ECONNABORTED)
85 /// - `remote-unreachable`: The remote address is not reachable. (EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
86 /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
87 /// - `not-in-progress`: A `connect` operation is not in progress.
88 /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
89 ///
90 /// # References
91 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html>
92 /// - <https://man7.org/linux/man-pages/man2/connect.2.html>
93 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect>
94 /// - <https://man.freebsd.org/cgi/man.cgi?connect>
95 start-connect: func(network: borrow<network>, remote-address: ip-socket-address) -> result<_, error-code>;
96 finish-connect: func() -> result<tuple<input-stream, output-stream>, error-code>;
97
98 /// Start listening for new connections.
99 ///
100 /// Transitions the socket into the Listener state.
101 ///
102 /// Unlike POSIX:
103 /// - this function is async. This enables interactive WASI hosts to inject permission prompts.
104 /// - the socket must already be explicitly bound.
105 ///
106 /// # Typical `start` errors
107 /// - `invalid-state`: The socket is not bound to any local address. (EDESTADDRREQ)
108 /// - `invalid-state`: The socket is already in the Connection state. (EISCONN, EINVAL on BSD)
109 /// - `invalid-state`: The socket is already in the Listener state.
110 ///
111 /// # Typical `finish` errors
112 /// - `address-in-use`: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE)
113 /// - `not-in-progress`: A `listen` operation is not in progress.
114 /// - `would-block`: Can't finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)
115 ///
116 /// # References
117 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/listen.html>
118 /// - <https://man7.org/linux/man-pages/man2/listen.2.html>
119 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-listen>
120 /// - <https://man.freebsd.org/cgi/man.cgi?query=listen&sektion=2>
121 start-listen: func() -> result<_, error-code>;
122 finish-listen: func() -> result<_, error-code>;
123
124 /// Accept a new client socket.
125 ///
126 /// The returned socket is bound and in the Connection state. The following properties are inherited from the listener socket:
127 /// - `address-family`
128 /// - `ipv6-only`
129 /// - `keep-alive-enabled`
130 /// - `keep-alive-idle-time`
131 /// - `keep-alive-interval`
132 /// - `keep-alive-count`
133 /// - `hop-limit`
134 /// - `receive-buffer-size`
135 /// - `send-buffer-size`
136 ///
137 /// On success, this function returns the newly accepted client socket along with
138 /// a pair of streams that can be used to read & write to the connection.
139 ///
140 /// # Typical errors
141 /// - `invalid-state`: Socket is not in the Listener state. (EINVAL)
142 /// - `would-block`: No pending connections at the moment. (EWOULDBLOCK, EAGAIN)
143 /// - `connection-aborted`: An incoming connection was pending, but was terminated by the client before this listener could accept it. (ECONNABORTED)
144 /// - `new-socket-limit`: The new socket resource could not be created because of a system limit. (EMFILE, ENFILE)
145 ///
146 /// # References
147 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/accept.html>
148 /// - <https://man7.org/linux/man-pages/man2/accept.2.html>
149 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-accept>
150 /// - <https://man.freebsd.org/cgi/man.cgi?query=accept&sektion=2>
151 accept: func() -> result<tuple<tcp-socket, input-stream, output-stream>, error-code>;
152
153 /// Get the bound local address.
154 ///
155 /// POSIX mentions:
156 /// > If the socket has not been bound to a local name, the value
157 /// > stored in the object pointed to by `address` is unspecified.
158 ///
159 /// WASI is stricter and requires `local-address` to return `invalid-state` when the socket hasn't been bound yet.
160 ///
161 /// # Typical errors
162 /// - `invalid-state`: The socket is not bound to any local address.
163 ///
164 /// # References
165 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html>
166 /// - <https://man7.org/linux/man-pages/man2/getsockname.2.html>
167 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname>
168 /// - <https://man.freebsd.org/cgi/man.cgi?getsockname>
169 local-address: func() -> result<ip-socket-address, error-code>;
170
171 /// Get the remote address.
172 ///
173 /// # Typical errors
174 /// - `invalid-state`: The socket is not connected to a remote address. (ENOTCONN)
175 ///
176 /// # References
177 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html>
178 /// - <https://man7.org/linux/man-pages/man2/getpeername.2.html>
179 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername>
180 /// - <https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1>
181 remote-address: func() -> result<ip-socket-address, error-code>;
182
183 /// Whether the socket is listening for new connections.
184 ///
185 /// Equivalent to the SO_ACCEPTCONN socket option.
186 is-listening: func() -> bool;
187
188 /// Whether this is a IPv4 or IPv6 socket.
189 ///
190 /// Equivalent to the SO_DOMAIN socket option.
191 address-family: func() -> ip-address-family;
192
193 /// Whether IPv4 compatibility (dual-stack) mode is disabled or not.
194 ///
195 /// Equivalent to the IPV6_V6ONLY socket option.
196 ///
197 /// # Typical errors
198 /// - `invalid-state`: (set) The socket is already bound.
199 /// - `not-supported`: (get/set) `this` socket is an IPv4 socket.
200 /// - `not-supported`: (set) Host does not support dual-stack sockets. (Implementations are not required to.)
201 ipv6-only: func() -> result<bool, error-code>;
202 set-ipv6-only: func(value: bool) -> result<_, error-code>;
203
204 /// Hints the desired listen queue size. Implementations are free to ignore this.
205 ///
206 /// If the provided value is 0, an `invalid-argument` error is returned.
207 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
208 ///
209 /// # Typical errors
210 /// - `not-supported`: (set) The platform does not support changing the backlog size after the initial listen.
211 /// - `invalid-argument`: (set) The provided value was 0.
212 /// - `invalid-state`: (set) The socket is already in the Connection state.
213 set-listen-backlog-size: func(value: u64) -> result<_, error-code>;
214
215 /// Enables or disables keepalive.
216 ///
217 /// The keepalive behavior can be adjusted using:
218 /// - `keep-alive-idle-time`
219 /// - `keep-alive-interval`
220 /// - `keep-alive-count`
221 /// These properties can be configured while `keep-alive-enabled` is false, but only come into effect when `keep-alive-enabled` is true.
222 ///
223 /// Equivalent to the SO_KEEPALIVE socket option.
224 keep-alive-enabled: func() -> result<bool, error-code>;
225 set-keep-alive-enabled: func(value: bool) -> result<_, error-code>;
226
227 /// Amount of time the connection has to be idle before TCP starts sending keepalive packets.
228 ///
229 /// If the provided value is 0, an `invalid-argument` error is returned.
230 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
231 /// I.e. after setting a value, reading the same setting back may return a different value.
232 ///
233 /// Equivalent to the TCP_KEEPIDLE socket option. (TCP_KEEPALIVE on MacOS)
234 ///
235 /// # Typical errors
236 /// - `invalid-argument`: (set) The provided value was 0.
237 keep-alive-idle-time: func() -> result<duration, error-code>;
238 set-keep-alive-idle-time: func(value: duration) -> result<_, error-code>;
239
240 /// The time between keepalive packets.
241 ///
242 /// If the provided value is 0, an `invalid-argument` error is returned.
243 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
244 /// I.e. after setting a value, reading the same setting back may return a different value.
245 ///
246 /// Equivalent to the TCP_KEEPINTVL socket option.
247 ///
248 /// # Typical errors
249 /// - `invalid-argument`: (set) The provided value was 0.
250 keep-alive-interval: func() -> result<duration, error-code>;
251 set-keep-alive-interval: func(value: duration) -> result<_, error-code>;
252
253 /// The maximum amount of keepalive packets TCP should send before aborting the connection.
254 ///
255 /// If the provided value is 0, an `invalid-argument` error is returned.
256 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
257 /// I.e. after setting a value, reading the same setting back may return a different value.
258 ///
259 /// Equivalent to the TCP_KEEPCNT socket option.
260 ///
261 /// # Typical errors
262 /// - `invalid-argument`: (set) The provided value was 0.
263 keep-alive-count: func() -> result<u32, error-code>;
264 set-keep-alive-count: func(value: u32) -> result<_, error-code>;
265
266 /// Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.
267 ///
268 /// If the provided value is 0, an `invalid-argument` error is returned.
269 ///
270 /// # Typical errors
271 /// - `invalid-argument`: (set) The TTL value must be 1 or higher.
272 /// - `invalid-state`: (set) The socket is already in the Connection state.
273 /// - `invalid-state`: (set) The socket is already in the Listener state.
274 hop-limit: func() -> result<u8, error-code>;
275 set-hop-limit: func(value: u8) -> result<_, error-code>;
276
277 /// The kernel buffer space reserved for sends/receives on this socket.
278 ///
279 /// If the provided value is 0, an `invalid-argument` error is returned.
280 /// Any other value will never cause an error, but it might be silently clamped and/or rounded.
281 /// I.e. after setting a value, reading the same setting back may return a different value.
282 ///
283 /// Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.
284 ///
285 /// # Typical errors
286 /// - `invalid-argument`: (set) The provided value was 0.
287 /// - `invalid-state`: (set) The socket is already in the Connection state.
288 /// - `invalid-state`: (set) The socket is already in the Listener state.
289 receive-buffer-size: func() -> result<u64, error-code>;
290 set-receive-buffer-size: func(value: u64) -> result<_, error-code>;
291 send-buffer-size: func() -> result<u64, error-code>;
292 set-send-buffer-size: func(value: u64) -> result<_, error-code>;
293
294 /// Create a `pollable` which will resolve once the socket is ready for I/O.
295 ///
296 /// Note: this function is here for WASI Preview2 only.
297 /// It's planned to be removed when `future` is natively supported in Preview3.
298 subscribe: func() -> pollable;
299
300 /// Initiate a graceful shutdown.
301 ///
302 /// - receive: the socket is not expecting to receive any more data from the peer. All subsequent read
303 /// operations on the `input-stream` associated with this socket will return an End Of Stream indication.
304 /// Any data still in the receive queue at time of calling `shutdown` will be discarded.
305 /// - send: the socket is not expecting to send any more data to the peer. All subsequent write
306 /// operations on the `output-stream` associated with this socket will return an error.
307 /// - both: same effect as receive & send combined.
308 ///
309 /// The shutdown function does not close (drop) the socket.
310 ///
311 /// # Typical errors
312 /// - `invalid-state`: The socket is not in the Connection state. (ENOTCONN)
313 ///
314 /// # References
315 /// - <https://pubs.opengroup.org/onlinepubs/9699919799/functions/shutdown.html>
316 /// - <https://man7.org/linux/man-pages/man2/shutdown.2.html>
317 /// - <https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-shutdown>
318 /// - <https://man.freebsd.org/cgi/man.cgi?query=shutdown&sektion=2>
319 shutdown: func(shutdown-type: shutdown-type) -> result<_, error-code>;
320 }
321 }