Debian Codegraph @

wasi/p3/wit/deps/wasi-http-0.3.0-rc-2026-01-06/package.wit

raw
1 package wasi:[email protected];
2
3 /// This interface defines all of the types and methods for implementing HTTP
4 /// Requests and Responses, as well as their headers, trailers, and bodies.
5 interface types {
6 use wasi:clocks/[email protected].{duration};
7
8 /// This type corresponds to HTTP standard Methods.
9 variant method {
10 get,
11 head,
12 post,
13 put,
14 delete,
15 connect,
16 options,
17 trace,
18 patch,
19 other(string),
20 }
21
22 /// This type corresponds to HTTP standard Related Schemes.
23 variant scheme {
24 HTTP,
25 HTTPS,
26 other(string),
27 }
28
29 /// Defines the case payload type for `DNS-error` above:
30 record DNS-error-payload {
31 rcode: option<string>,
32 info-code: option<u16>,
33 }
34
35 /// Defines the case payload type for `TLS-alert-received` above:
36 record TLS-alert-received-payload {
37 alert-id: option<u8>,
38 alert-message: option<string>,
39 }
40
41 /// Defines the case payload type for `HTTP-response-{header,trailer}-size` above:
42 record field-size-payload {
43 field-name: option<string>,
44 field-size: option<u32>,
45 }
46
47 /// These cases are inspired by the IANA HTTP Proxy Error Types:
48 /// <https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types>
49 variant error-code {
50 DNS-timeout,
51 DNS-error(DNS-error-payload),
52 destination-not-found,
53 destination-unavailable,
54 destination-IP-prohibited,
55 destination-IP-unroutable,
56 connection-refused,
57 connection-terminated,
58 connection-timeout,
59 connection-read-timeout,
60 connection-write-timeout,
61 connection-limit-reached,
62 TLS-protocol-error,
63 TLS-certificate-error,
64 TLS-alert-received(TLS-alert-received-payload),
65 HTTP-request-denied,
66 HTTP-request-length-required,
67 HTTP-request-body-size(option<u64>),
68 HTTP-request-method-invalid,
69 HTTP-request-URI-invalid,
70 HTTP-request-URI-too-long,
71 HTTP-request-header-section-size(option<u32>),
72 HTTP-request-header-size(option<field-size-payload>),
73 HTTP-request-trailer-section-size(option<u32>),
74 HTTP-request-trailer-size(field-size-payload),
75 HTTP-response-incomplete,
76 HTTP-response-header-section-size(option<u32>),
77 HTTP-response-header-size(field-size-payload),
78 HTTP-response-body-size(option<u64>),
79 HTTP-response-trailer-section-size(option<u32>),
80 HTTP-response-trailer-size(field-size-payload),
81 HTTP-response-transfer-coding(option<string>),
82 HTTP-response-content-coding(option<string>),
83 HTTP-response-timeout,
84 HTTP-upgrade-failed,
85 HTTP-protocol-error,
86 loop-detected,
87 configuration-error,
88 /// This is a catch-all error for anything that doesn't fit cleanly into a
89 /// more specific case. It also includes an optional string for an
90 /// unstructured description of the error. Users should not depend on the
91 /// string for diagnosing errors, as it's not required to be consistent
92 /// between implementations.
93 internal-error(option<string>),
94 }
95
96 /// This type enumerates the different kinds of errors that may occur when
97 /// setting or appending to a `fields` resource.
98 variant header-error {
99 /// This error indicates that a `field-name` or `field-value` was
100 /// syntactically invalid when used with an operation that sets headers in a
101 /// `fields`.
102 invalid-syntax,
103 /// This error indicates that a forbidden `field-name` was used when trying
104 /// to set a header in a `fields`.
105 forbidden,
106 /// This error indicates that the operation on the `fields` was not
107 /// permitted because the fields are immutable.
108 immutable,
109 }
110
111 /// This type enumerates the different kinds of errors that may occur when
112 /// setting fields of a `request-options` resource.
113 variant request-options-error {
114 /// Indicates the specified field is not supported by this implementation.
115 not-supported,
116 /// Indicates that the operation on the `request-options` was not permitted
117 /// because it is immutable.
118 immutable,
119 }
120
121 /// Field names are always strings.
122 ///
123 /// Field names should always be treated as case insensitive by the `fields`
124 /// resource for the purposes of equality checking.
125 type field-name = string;
126
127 /// Field values should always be ASCII strings. However, in
128 /// reality, HTTP implementations often have to interpret malformed values,
129 /// so they are provided as a list of bytes.
130 type field-value = list<u8>;
131
132 /// This following block defines the `fields` resource which corresponds to
133 /// HTTP standard Fields. Fields are a common representation used for both
134 /// Headers and Trailers.
135 ///
136 /// A `fields` may be mutable or immutable. A `fields` created using the
137 /// constructor, `from-list`, or `clone` will be mutable, but a `fields`
138 /// resource given by other means (including, but not limited to,
139 /// `request.headers`) might be be immutable. In an immutable fields, the
140 /// `set`, `append`, and `delete` operations will fail with
141 /// `header-error.immutable`.
142 ///
143 /// A `fields` resource should store `field-name`s and `field-value`s in their
144 /// original casing used to construct or mutate the `fields` resource. The `fields`
145 /// resource should use that original casing when serializing the fields for
146 /// transport or when returning them from a method.
147 resource fields {
148 /// Construct an empty HTTP Fields.
149 ///
150 /// The resulting `fields` is mutable.
151 constructor();
152 /// Construct an HTTP Fields.
153 ///
154 /// The resulting `fields` is mutable.
155 ///
156 /// The list represents each name-value pair in the Fields. Names
157 /// which have multiple values are represented by multiple entries in this
158 /// list with the same name.
159 ///
160 /// The tuple is a pair of the field name, represented as a string, and
161 /// Value, represented as a list of bytes. In a valid Fields, all names
162 /// and values are valid UTF-8 strings. However, values are not always
163 /// well-formed, so they are represented as a raw list of bytes.
164 ///
165 /// An error result will be returned if any header or value was
166 /// syntactically invalid, or if a header was forbidden.
167 from-list: static func(entries: list<tuple<field-name, field-value>>) -> result<fields, header-error>;
168 /// Get all of the values corresponding to a name. If the name is not present
169 /// in this `fields`, an empty list is returned. However, if the name is
170 /// present but empty, this is represented by a list with one or more
171 /// empty field-values present.
172 get: func(name: field-name) -> list<field-value>;
173 /// Returns `true` when the name is present in this `fields`. If the name is
174 /// syntactically invalid, `false` is returned.
175 has: func(name: field-name) -> bool;
176 /// Set all of the values for a name. Clears any existing values for that
177 /// name, if they have been set.
178 ///
179 /// Fails with `header-error.immutable` if the `fields` are immutable.
180 set: func(name: field-name, value: list<field-value>) -> result<_, header-error>;
181 /// Delete all values for a name. Does nothing if no values for the name
182 /// exist.
183 ///
184 /// Fails with `header-error.immutable` if the `fields` are immutable.
185 delete: func(name: field-name) -> result<_, header-error>;
186 /// Delete all values for a name. Does nothing if no values for the name
187 /// exist.
188 ///
189 /// Returns all values previously corresponding to the name, if any.
190 ///
191 /// Fails with `header-error.immutable` if the `fields` are immutable.
192 get-and-delete: func(name: field-name) -> result<list<field-value>, header-error>;
193 /// Append a value for a name. Does not change or delete any existing
194 /// values for that name.
195 ///
196 /// Fails with `header-error.immutable` if the `fields` are immutable.
197 append: func(name: field-name, value: field-value) -> result<_, header-error>;
198 /// Retrieve the full set of names and values in the Fields. Like the
199 /// constructor, the list represents each name-value pair.
200 ///
201 /// The outer list represents each name-value pair in the Fields. Names
202 /// which have multiple values are represented by multiple entries in this
203 /// list with the same name.
204 ///
205 /// The names and values are always returned in the original casing and in
206 /// the order in which they will be serialized for transport.
207 copy-all: func() -> list<tuple<field-name, field-value>>;
208 /// Make a deep copy of the Fields. Equivalent in behavior to calling the
209 /// `fields` constructor on the return value of `copy-all`. The resulting
210 /// `fields` is mutable.
211 clone: func() -> fields;
212 }
213
214 /// Headers is an alias for Fields.
215 type headers = fields;
216
217 /// Trailers is an alias for Fields.
218 type trailers = fields;
219
220 /// Represents an HTTP Request.
221 resource request {
222 /// Construct a new `request` with a default `method` of `GET`, and
223 /// `none` values for `path-with-query`, `scheme`, and `authority`.
224 ///
225 /// `headers` is the HTTP Headers for the Request.
226 ///
227 /// `contents` is the optional body content stream with `none`
228 /// representing a zero-length content stream.
229 /// Once it is closed, `trailers` future must resolve to a result.
230 /// If `trailers` resolves to an error, underlying connection
231 /// will be closed immediately.
232 ///
233 /// `options` is optional `request-options` resource to be used
234 /// if the request is sent over a network connection.
235 ///
236 /// It is possible to construct, or manipulate with the accessor functions
237 /// below, a `request` with an invalid combination of `scheme`
238 /// and `authority`, or `headers` which are not permitted to be sent.
239 /// It is the obligation of the `handler.handle` implementation
240 /// to reject invalid constructions of `request`.
241 ///
242 /// The returned future resolves to result of transmission of this request.
243 new: static func(headers: headers, contents: option<stream<u8>>, trailers: future<result<option<trailers>, error-code>>, options: option<request-options>) -> tuple<request, future<result<_, error-code>>>;
244 /// Get the Method for the Request.
245 get-method: func() -> method;
246 /// Set the Method for the Request. Fails if the string present in a
247 /// `method.other` argument is not a syntactically valid method.
248 set-method: func(method: method) -> result;
249 /// Get the combination of the HTTP Path and Query for the Request. When
250 /// `none`, this represents an empty Path and empty Query.
251 get-path-with-query: func() -> option<string>;
252 /// Set the combination of the HTTP Path and Query for the Request. When
253 /// `none`, this represents an empty Path and empty Query. Fails is the
254 /// string given is not a syntactically valid path and query uri component.
255 set-path-with-query: func(path-with-query: option<string>) -> result;
256 /// Get the HTTP Related Scheme for the Request. When `none`, the
257 /// implementation may choose an appropriate default scheme.
258 get-scheme: func() -> option<scheme>;
259 /// Set the HTTP Related Scheme for the Request. When `none`, the
260 /// implementation may choose an appropriate default scheme. Fails if the
261 /// string given is not a syntactically valid uri scheme.
262 set-scheme: func(scheme: option<scheme>) -> result;
263 /// Get the authority of the Request's target URI. A value of `none` may be used
264 /// with Related Schemes which do not require an authority. The HTTP and
265 /// HTTPS schemes always require an authority.
266 get-authority: func() -> option<string>;
267 /// Set the authority of the Request's target URI. A value of `none` may be used
268 /// with Related Schemes which do not require an authority. The HTTP and
269 /// HTTPS schemes always require an authority. Fails if the string given is
270 /// not a syntactically valid URI authority.
271 set-authority: func(authority: option<string>) -> result;
272 /// Get the `request-options` to be associated with this request
273 ///
274 /// The returned `request-options` resource is immutable: `set-*` operations
275 /// will fail if invoked.
276 ///
277 /// This `request-options` resource is a child: it must be dropped before
278 /// the parent `request` is dropped, or its ownership is transferred to
279 /// another component by e.g. `handler.handle`.
280 get-options: func() -> option<request-options>;
281 /// Get the headers associated with the Request.
282 ///
283 /// The returned `headers` resource is immutable: `set`, `append`, and
284 /// `delete` operations will fail with `header-error.immutable`.
285 get-headers: func() -> headers;
286 /// Get body of the Request.
287 ///
288 /// Stream returned by this method represents the contents of the body.
289 /// Once the stream is reported as closed, callers should await the returned
290 /// future to determine whether the body was received successfully.
291 /// The future will only resolve after the stream is reported as closed.
292 ///
293 /// This function takes a `res` future as a parameter, which can be used to
294 /// communicate an error in handling of the request.
295 ///
296 /// Note that function will move the `request`, but references to headers or
297 /// request options acquired from it previously will remain valid.
298 consume-body: static func(this: request, res: future<result<_, error-code>>) -> tuple<stream<u8>, future<result<option<trailers>, error-code>>>;
299 }
300
301 /// Parameters for making an HTTP Request. Each of these parameters is
302 /// currently an optional timeout applicable to the transport layer of the
303 /// HTTP protocol.
304 ///
305 /// These timeouts are separate from any the user may use to bound an
306 /// asynchronous call.
307 resource request-options {
308 /// Construct a default `request-options` value.
309 constructor();
310 /// The timeout for the initial connect to the HTTP Server.
311 get-connect-timeout: func() -> option<duration>;
312 /// Set the timeout for the initial connect to the HTTP Server. An error
313 /// return value indicates that this timeout is not supported or that this
314 /// handle is immutable.
315 set-connect-timeout: func(duration: option<duration>) -> result<_, request-options-error>;
316 /// The timeout for receiving the first byte of the Response body.
317 get-first-byte-timeout: func() -> option<duration>;
318 /// Set the timeout for receiving the first byte of the Response body. An
319 /// error return value indicates that this timeout is not supported or that
320 /// this handle is immutable.
321 set-first-byte-timeout: func(duration: option<duration>) -> result<_, request-options-error>;
322 /// The timeout for receiving subsequent chunks of bytes in the Response
323 /// body stream.
324 get-between-bytes-timeout: func() -> option<duration>;
325 /// Set the timeout for receiving subsequent chunks of bytes in the Response
326 /// body stream. An error return value indicates that this timeout is not
327 /// supported or that this handle is immutable.
328 set-between-bytes-timeout: func(duration: option<duration>) -> result<_, request-options-error>;
329 /// Make a deep copy of the `request-options`.
330 /// The resulting `request-options` is mutable.
331 clone: func() -> request-options;
332 }
333
334 /// This type corresponds to the HTTP standard Status Code.
335 type status-code = u16;
336
337 /// Represents an HTTP Response.
338 resource response {
339 /// Construct a new `response`, with a default `status-code` of `200`.
340 /// If a different `status-code` is needed, it must be set via the
341 /// `set-status-code` method.
342 ///
343 /// `headers` is the HTTP Headers for the Response.
344 ///
345 /// `contents` is the optional body content stream with `none`
346 /// representing a zero-length content stream.
347 /// Once it is closed, `trailers` future must resolve to a result.
348 /// If `trailers` resolves to an error, underlying connection
349 /// will be closed immediately.
350 ///
351 /// The returned future resolves to result of transmission of this response.
352 new: static func(headers: headers, contents: option<stream<u8>>, trailers: future<result<option<trailers>, error-code>>) -> tuple<response, future<result<_, error-code>>>;
353 /// Get the HTTP Status Code for the Response.
354 get-status-code: func() -> status-code;
355 /// Set the HTTP Status Code for the Response. Fails if the status-code
356 /// given is not a valid http status code.
357 set-status-code: func(status-code: status-code) -> result;
358 /// Get the headers associated with the Response.
359 ///
360 /// The returned `headers` resource is immutable: `set`, `append`, and
361 /// `delete` operations will fail with `header-error.immutable`.
362 get-headers: func() -> headers;
363 /// Get body of the Response.
364 ///
365 /// Stream returned by this method represents the contents of the body.
366 /// Once the stream is reported as closed, callers should await the returned
367 /// future to determine whether the body was received successfully.
368 /// The future will only resolve after the stream is reported as closed.
369 ///
370 /// This function takes a `res` future as a parameter, which can be used to
371 /// communicate an error in handling of the response.
372 ///
373 /// Note that function will move the `response`, but references to headers
374 /// acquired from it previously will remain valid.
375 consume-body: static func(this: response, res: future<result<_, error-code>>) -> tuple<stream<u8>, future<result<option<trailers>, error-code>>>;
376 }
377 }
378
379 /// This interface defines a handler of HTTP Requests.
380 ///
381 /// In a `wasi:http/service` this interface is exported to respond to an
382 /// incoming HTTP Request with a Response.
383 ///
384 /// In `wasi:http/middleware` this interface is both exported and imported as
385 /// the "downstream" and "upstream" directions of the middleware chain.
386 interface handler {
387 use types.{request, response, error-code};
388
389 /// This function may be called with either an incoming request read from the
390 /// network or a request synthesized or forwarded by another component.
391 handle: async func(request: request) -> result<response, error-code>;
392 }
393
394 /// This interface defines an HTTP client for sending "outgoing" requests.
395 ///
396 /// Most components are expected to import this interface to provide the
397 /// capability to send HTTP requests to arbitrary destinations on a network.
398 ///
399 /// The type signature of `client.send` is the same as `handler.handle`. This
400 /// duplication is currently necessary because some Component Model tooling
401 /// (including WIT itself) is unable to represent a component importing two
402 /// instances of the same interface. A `client.send` import may be linked
403 /// directly to a `handler.handle` export to bypass the network.
404 interface client {
405 use types.{request, response, error-code};
406
407 /// This function may be used to either send an outgoing request over the
408 /// network or to forward it to another component.
409 send: async func(request: request) -> result<response, error-code>;
410 }
411
412 /// The `wasi:http/service` world captures a broad category of HTTP services
413 /// including web applications, API servers, and proxies. It may be `include`d
414 /// in more specific worlds such as `wasi:http/middleware`.
415 world service {
416 import wasi:cli/[email protected];
417 import wasi:cli/[email protected];
418 import wasi:cli/[email protected];
419 import wasi:cli/[email protected];
420 import wasi:clocks/[email protected];
421 import types;
422 import client;
423 import wasi:clocks/[email protected];
424 import wasi:clocks/[email protected];
425 @unstable(feature = clocks-timezone)
426 import wasi:clocks/[email protected];
427 import wasi:random/[email protected];
428 import wasi:random/[email protected];
429 import wasi:random/[email protected];
430
431 export handler;
432 }
433 /// The `wasi:http/middleware` world captures HTTP services that forward HTTP
434 /// Requests to another handler.
435 ///
436 /// Components may implement this world to allow them to participate in handler
437 /// "chains" where a `request` flows through handlers on its way to some terminal
438 /// `service` and corresponding `response` flows in the opposite direction.
439 world middleware {
440 import wasi:clocks/[email protected];
441 import types;
442 import handler;
443 import wasi:cli/[email protected];
444 import wasi:cli/[email protected];
445 import wasi:cli/[email protected];
446 import wasi:cli/[email protected];
447 import client;
448 import wasi:clocks/[email protected];
449 import wasi:clocks/[email protected];
450 @unstable(feature = clocks-timezone)
451 import wasi:clocks/[email protected];
452 import wasi:random/[email protected];
453 import wasi:random/[email protected];
454 import wasi:random/[email protected];
455
456 export handler;
457 }