Debian Codegraph @

vendor/wit-component/tests/interfaces/wasi-http/deps/io/streams.wit

raw
1 package wasi:[email protected];
2
3 /// WASI I/O is an I/O abstraction API which is currently focused on providing
4 /// stream types.
5 ///
6 /// In the future, the component model is expected to add built-in stream types;
7 /// when it does, they are expected to subsume this API.
8 interface streams {
9 use error.{error};
10 use poll.{pollable};
11
12 /// An error for input-stream and output-stream operations.
13 variant stream-error {
14 /// The last operation (a write or flush) failed before completion.
15 ///
16 /// More information is available in the `error` payload.
17 last-operation-failed(error),
18 /// The stream is closed: no more input will be accepted by the
19 /// stream. A closed output-stream will return this error on all
20 /// future operations.
21 closed
22 }
23
24 /// An input bytestream.
25 ///
26 /// `input-stream`s are *non-blocking* to the extent practical on underlying
27 /// platforms. I/O operations always return promptly; if fewer bytes are
28 /// promptly available than requested, they return the number of bytes promptly
29 /// available, which could even be zero. To wait for data to be available,
30 /// use the `subscribe` function to obtain a `pollable` which can be polled
31 /// for using `wasi:io/poll`.
32 resource input-stream {
33 /// Perform a non-blocking read from the stream.
34 ///
35 /// This function returns a list of bytes containing the read data,
36 /// when successful. The returned list will contain up to `len` bytes;
37 /// it may return fewer than requested, but not more. The list is
38 /// empty when no bytes are available for reading at this time. The
39 /// pollable given by `subscribe` will be ready when more bytes are
40 /// available.
41 ///
42 /// This function fails with a `stream-error` when the operation
43 /// encounters an error, giving `last-operation-failed`, or when the
44 /// stream is closed, giving `closed`.
45 ///
46 /// When the caller gives a `len` of 0, it represents a request to
47 /// read 0 bytes. If the stream is still open, this call should
48 /// succeed and return an empty list, or otherwise fail with `closed`.
49 ///
50 /// The `len` parameter is a `u64`, which could represent a list of u8 which
51 /// is not possible to allocate in wasm32, or not desirable to allocate as
52 /// as a return value by the callee. The callee may return a list of bytes
53 /// less than `len` in size while more bytes are available for reading.
54 read: func(
55 /// The maximum number of bytes to read
56 len: u64
57 ) -> result<list<u8>, stream-error>;
58
59 /// Read bytes from a stream, after blocking until at least one byte can
60 /// be read. Except for blocking, behavior is identical to `read`.
61 blocking-read: func(
62 /// The maximum number of bytes to read
63 len: u64
64 ) -> result<list<u8>, stream-error>;
65
66 /// Skip bytes from a stream. Returns number of bytes skipped.
67 ///
68 /// Behaves identical to `read`, except instead of returning a list
69 /// of bytes, returns the number of bytes consumed from the stream.
70 skip: func(
71 /// The maximum number of bytes to skip.
72 len: u64,
73 ) -> result<u64, stream-error>;
74
75 /// Skip bytes from a stream, after blocking until at least one byte
76 /// can be skipped. Except for blocking behavior, identical to `skip`.
77 blocking-skip: func(
78 /// The maximum number of bytes to skip.
79 len: u64,
80 ) -> result<u64, stream-error>;
81
82 /// Create a `pollable` which will resolve once either the specified stream
83 /// has bytes available to read or the other end of the stream has been
84 /// closed.
85 /// The created `pollable` is a child resource of the `input-stream`.
86 /// Implementations may trap if the `input-stream` is dropped before
87 /// all derived `pollable`s created with this function are dropped.
88 subscribe: func() -> pollable;
89 }
90
91
92 /// An output bytestream.
93 ///
94 /// `output-stream`s are *non-blocking* to the extent practical on
95 /// underlying platforms. Except where specified otherwise, I/O operations also
96 /// always return promptly, after the number of bytes that can be written
97 /// promptly, which could even be zero. To wait for the stream to be ready to
98 /// accept data, the `subscribe` function to obtain a `pollable` which can be
99 /// polled for using `wasi:io/poll`.
100 resource output-stream {
101 /// Check readiness for writing. This function never blocks.
102 ///
103 /// Returns the number of bytes permitted for the next call to `write`,
104 /// or an error. Calling `write` with more bytes than this function has
105 /// permitted will trap.
106 ///
107 /// When this function returns 0 bytes, the `subscribe` pollable will
108 /// become ready when this function will report at least 1 byte, or an
109 /// error.
110 check-write: func() -> result<u64, stream-error>;
111
112 /// Perform a write. This function never blocks.
113 ///
114 /// Precondition: check-write gave permit of Ok(n) and contents has a
115 /// length of less than or equal to n. Otherwise, this function will trap.
116 ///
117 /// returns Err(closed) without writing if the stream has closed since
118 /// the last call to check-write provided a permit.
119 write: func(
120 contents: list<u8>
121 ) -> result<_, stream-error>;
122
123 /// Perform a write of up to 4096 bytes, and then flush the stream. Block
124 /// until all of these operations are complete, or an error occurs.
125 ///
126 /// This is a convenience wrapper around the use of `check-write`,
127 /// `subscribe`, `write`, and `flush`, and is implemented with the
128 /// following pseudo-code:
129 ///
130 /// ```text
131 /// let pollable = this.subscribe();
132 /// while !contents.is_empty() {
133 /// // Wait for the stream to become writable
134 /// pollable.block();
135 /// let Ok(n) = this.check-write(); // eliding error handling
136 /// let len = min(n, contents.len());
137 /// let (chunk, rest) = contents.split_at(len);
138 /// this.write(chunk ); // eliding error handling
139 /// contents = rest;
140 /// }
141 /// this.flush();
142 /// // Wait for completion of `flush`
143 /// pollable.block();
144 /// // Check for any errors that arose during `flush`
145 /// let _ = this.check-write(); // eliding error handling
146 /// ```
147 blocking-write-and-flush: func(
148 contents: list<u8>
149 ) -> result<_, stream-error>;
150
151 /// Request to flush buffered output. This function never blocks.
152 ///
153 /// This tells the output-stream that the caller intends any buffered
154 /// output to be flushed. the output which is expected to be flushed
155 /// is all that has been passed to `write` prior to this call.
156 ///
157 /// Upon calling this function, the `output-stream` will not accept any
158 /// writes (`check-write` will return `ok(0)`) until the flush has
159 /// completed. The `subscribe` pollable will become ready when the
160 /// flush has completed and the stream can accept more writes.
161 flush: func() -> result<_, stream-error>;
162
163 /// Request to flush buffered output, and block until flush completes
164 /// and stream is ready for writing again.
165 blocking-flush: func() -> result<_, stream-error>;
166
167 /// Create a `pollable` which will resolve once the output-stream
168 /// is ready for more writing, or an error has occured. When this
169 /// pollable is ready, `check-write` will return `ok(n)` with n>0, or an
170 /// error.
171 ///
172 /// If the stream is closed, this pollable is always ready immediately.
173 ///
174 /// The created `pollable` is a child resource of the `output-stream`.
175 /// Implementations may trap if the `output-stream` is dropped before
176 /// all derived `pollable`s created with this function are dropped.
177 subscribe: func() -> pollable;
178
179 /// Write zeroes to a stream.
180 ///
181 /// This should be used precisely like `write` with the exact same
182 /// preconditions (must use check-write first), but instead of
183 /// passing a list of bytes, you simply pass the number of zero-bytes
184 /// that should be written.
185 write-zeroes: func(
186 /// The number of zero-bytes to write
187 len: u64
188 ) -> result<_, stream-error>;
189
190 /// Perform a write of up to 4096 zeroes, and then flush the stream.
191 /// Block until all of these operations are complete, or an error
192 /// occurs.
193 ///
194 /// This is a convenience wrapper around the use of `check-write`,
195 /// `subscribe`, `write-zeroes`, and `flush`, and is implemented with
196 /// the following pseudo-code:
197 ///
198 /// ```text
199 /// let pollable = this.subscribe();
200 /// while num_zeroes != 0 {
201 /// // Wait for the stream to become writable
202 /// pollable.block();
203 /// let Ok(n) = this.check-write(); // eliding error handling
204 /// let len = min(n, num_zeroes);
205 /// this.write-zeroes(len); // eliding error handling
206 /// num_zeroes -= len;
207 /// }
208 /// this.flush();
209 /// // Wait for completion of `flush`
210 /// pollable.block();
211 /// // Check for any errors that arose during `flush`
212 /// let _ = this.check-write(); // eliding error handling
213 /// ```
214 blocking-write-zeroes-and-flush: func(
215 /// The number of zero-bytes to write
216 len: u64
217 ) -> result<_, stream-error>;
218
219 /// Read from one stream and write to another.
220 ///
221 /// The behavior of splice is equivelant to:
222 /// 1. calling `check-write` on the `output-stream`
223 /// 2. calling `read` on the `input-stream` with the smaller of the
224 /// `check-write` permitted length and the `len` provided to `splice`
225 /// 3. calling `write` on the `output-stream` with that read data.
226 ///
227 /// Any error reported by the call to `check-write`, `read`, or
228 /// `write` ends the splice and reports that error.
229 ///
230 /// This function returns the number of bytes transferred; it may be less
231 /// than `len`.
232 splice: func(
233 /// The stream to read from
234 src: borrow<input-stream>,
235 /// The number of bytes to splice
236 len: u64,
237 ) -> result<u64, stream-error>;
238
239 /// Read from one stream and write to another, with blocking.
240 ///
241 /// This is similar to `splice`, except that it blocks until the
242 /// `output-stream` is ready for writing, and the `input-stream`
243 /// is ready for reading, before performing the `splice`.
244 blocking-splice: func(
245 /// The stream to read from
246 src: borrow<input-stream>,
247 /// The number of bytes to splice
248 len: u64,
249 ) -> result<u64, stream-error>;
250 }
251 }