Debian Codegraph @

wasi/p2/wit/deps/wasi-http-0.2.0/package.wit

raw
1 package wasi:[email protected];
2
3 /// This interface defines all of the types and methods for implementing
4 /// HTTP Requests and Responses, both incoming and outgoing, as well as
5 /// their headers, trailers, and bodies.
6 interface types {
7 use wasi:clocks/[email protected].{duration};
8 use wasi:io/[email protected].{input-stream, output-stream};
9 use wasi:io/[email protected].{error as io-error};
10 use wasi:io/[email protected].{pollable};
11
12 /// This type corresponds to HTTP standard Methods.
13 variant method {
14 get,
15 head,
16 post,
17 put,
18 delete,
19 connect,
20 options,
21 trace,
22 patch,
23 other(string),
24 }
25
26 /// This type corresponds to HTTP standard Related Schemes.
27 variant scheme {
28 HTTP,
29 HTTPS,
30 other(string),
31 }
32
33 /// Defines the case payload type for `DNS-error` above:
34 record DNS-error-payload {
35 rcode: option<string>,
36 info-code: option<u16>,
37 }
38
39 /// Defines the case payload type for `TLS-alert-received` above:
40 record TLS-alert-received-payload {
41 alert-id: option<u8>,
42 alert-message: option<string>,
43 }
44
45 /// Defines the case payload type for `HTTP-response-{header,trailer}-size` above:
46 record field-size-payload {
47 field-name: option<string>,
48 field-size: option<u32>,
49 }
50
51 /// These cases are inspired by the IANA HTTP Proxy Error Types:
52 /// https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types
53 variant error-code {
54 DNS-timeout,
55 DNS-error(DNS-error-payload),
56 destination-not-found,
57 destination-unavailable,
58 destination-IP-prohibited,
59 destination-IP-unroutable,
60 connection-refused,
61 connection-terminated,
62 connection-timeout,
63 connection-read-timeout,
64 connection-write-timeout,
65 connection-limit-reached,
66 TLS-protocol-error,
67 TLS-certificate-error,
68 TLS-alert-received(TLS-alert-received-payload),
69 HTTP-request-denied,
70 HTTP-request-length-required,
71 HTTP-request-body-size(option<u64>),
72 HTTP-request-method-invalid,
73 HTTP-request-URI-invalid,
74 HTTP-request-URI-too-long,
75 HTTP-request-header-section-size(option<u32>),
76 HTTP-request-header-size(option<field-size-payload>),
77 HTTP-request-trailer-section-size(option<u32>),
78 HTTP-request-trailer-size(field-size-payload),
79 HTTP-response-incomplete,
80 HTTP-response-header-section-size(option<u32>),
81 HTTP-response-header-size(field-size-payload),
82 HTTP-response-body-size(option<u64>),
83 HTTP-response-trailer-section-size(option<u32>),
84 HTTP-response-trailer-size(field-size-payload),
85 HTTP-response-transfer-coding(option<string>),
86 HTTP-response-content-coding(option<string>),
87 HTTP-response-timeout,
88 HTTP-upgrade-failed,
89 HTTP-protocol-error,
90 loop-detected,
91 configuration-error,
92 /// This is a catch-all error for anything that doesn't fit cleanly into a
93 /// more specific case. It also includes an optional string for an
94 /// unstructured description of the error. Users should not depend on the
95 /// string for diagnosing errors, as it's not required to be consistent
96 /// between implementations.
97 internal-error(option<string>),
98 }
99
100 /// This type enumerates the different kinds of errors that may occur when
101 /// setting or appending to a `fields` resource.
102 variant header-error {
103 /// This error indicates that a `field-key` or `field-value` was
104 /// syntactically invalid when used with an operation that sets headers in a
105 /// `fields`.
106 invalid-syntax,
107 /// This error indicates that a forbidden `field-key` was used when trying
108 /// to set a header in a `fields`.
109 forbidden,
110 /// This error indicates that the operation on the `fields` was not
111 /// permitted because the fields are immutable.
112 immutable,
113 }
114
115 /// Field keys are always strings.
116 type field-key = string;
117
118 /// Field values should always be ASCII strings. However, in
119 /// reality, HTTP implementations often have to interpret malformed values,
120 /// so they are provided as a list of bytes.
121 type field-value = list<u8>;
122
123 /// This following block defines the `fields` resource which corresponds to
124 /// HTTP standard Fields. Fields are a common representation used for both
125 /// Headers and Trailers.
126 ///
127 /// A `fields` may be mutable or immutable. A `fields` created using the
128 /// constructor, `from-list`, or `clone` will be mutable, but a `fields`
129 /// resource given by other means (including, but not limited to,
130 /// `incoming-request.headers`, `outgoing-request.headers`) might be be
131 /// immutable. In an immutable fields, the `set`, `append`, and `delete`
132 /// operations will fail with `header-error.immutable`.
133 resource fields {
134 /// Construct an empty HTTP Fields.
135 ///
136 /// The resulting `fields` is mutable.
137 constructor();
138 /// Construct an HTTP Fields.
139 ///
140 /// The resulting `fields` is mutable.
141 ///
142 /// The list represents each key-value pair in the Fields. Keys
143 /// which have multiple values are represented by multiple entries in this
144 /// list with the same key.
145 ///
146 /// The tuple is a pair of the field key, represented as a string, and
147 /// Value, represented as a list of bytes. In a valid Fields, all keys
148 /// and values are valid UTF-8 strings. However, values are not always
149 /// well-formed, so they are represented as a raw list of bytes.
150 ///
151 /// An error result will be returned if any header or value was
152 /// syntactically invalid, or if a header was forbidden.
153 from-list: static func(entries: list<tuple<field-key, field-value>>) -> result<fields, header-error>;
154 /// Get all of the values corresponding to a key. If the key is not present
155 /// in this `fields`, an empty list is returned. However, if the key is
156 /// present but empty, this is represented by a list with one or more
157 /// empty field-values present.
158 get: func(name: field-key) -> list<field-value>;
159 /// Returns `true` when the key is present in this `fields`. If the key is
160 /// syntactically invalid, `false` is returned.
161 has: func(name: field-key) -> bool;
162 /// Set all of the values for a key. Clears any existing values for that
163 /// key, if they have been set.
164 ///
165 /// Fails with `header-error.immutable` if the `fields` are immutable.
166 set: func(name: field-key, value: list<field-value>) -> result<_, header-error>;
167 /// Delete all values for a key. Does nothing if no values for the key
168 /// exist.
169 ///
170 /// Fails with `header-error.immutable` if the `fields` are immutable.
171 delete: func(name: field-key) -> result<_, header-error>;
172 /// Append a value for a key. Does not change or delete any existing
173 /// values for that key.
174 ///
175 /// Fails with `header-error.immutable` if the `fields` are immutable.
176 append: func(name: field-key, value: field-value) -> result<_, header-error>;
177 /// Retrieve the full set of keys and values in the Fields. Like the
178 /// constructor, the list represents each key-value pair.
179 ///
180 /// The outer list represents each key-value pair in the Fields. Keys
181 /// which have multiple values are represented by multiple entries in this
182 /// list with the same key.
183 entries: func() -> list<tuple<field-key, field-value>>;
184 /// Make a deep copy of the Fields. Equivelant in behavior to calling the
185 /// `fields` constructor on the return value of `entries`. The resulting
186 /// `fields` is mutable.
187 clone: func() -> fields;
188 }
189
190 /// Headers is an alias for Fields.
191 type headers = fields;
192
193 /// Trailers is an alias for Fields.
194 type trailers = fields;
195
196 /// Represents an incoming HTTP Request.
197 resource incoming-request {
198 /// Returns the method of the incoming request.
199 method: func() -> method;
200 /// Returns the path with query parameters from the request, as a string.
201 path-with-query: func() -> option<string>;
202 /// Returns the protocol scheme from the request.
203 scheme: func() -> option<scheme>;
204 /// Returns the authority from the request, if it was present.
205 authority: func() -> option<string>;
206 /// Get the `headers` associated with the request.
207 ///
208 /// The returned `headers` resource is immutable: `set`, `append`, and
209 /// `delete` operations will fail with `header-error.immutable`.
210 ///
211 /// The `headers` returned are a child resource: it must be dropped before
212 /// the parent `incoming-request` is dropped. Dropping this
213 /// `incoming-request` before all children are dropped will trap.
214 headers: func() -> headers;
215 /// Gives the `incoming-body` associated with this request. Will only
216 /// return success at most once, and subsequent calls will return error.
217 consume: func() -> result<incoming-body>;
218 }
219
220 /// Represents an outgoing HTTP Request.
221 resource outgoing-request {
222 /// Construct a new `outgoing-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 /// It is possible to construct, or manipulate with the accessor functions
228 /// below, an `outgoing-request` with an invalid combination of `scheme`
229 /// and `authority`, or `headers` which are not permitted to be sent.
230 /// It is the obligation of the `outgoing-handler.handle` implementation
231 /// to reject invalid constructions of `outgoing-request`.
232 constructor(headers: headers);
233 /// Returns the resource corresponding to the outgoing Body for this
234 /// Request.
235 ///
236 /// Returns success on the first call: the `outgoing-body` resource for
237 /// this `outgoing-request` can be retrieved at most once. Subsequent
238 /// calls will return error.
239 body: func() -> result<outgoing-body>;
240 /// Get the Method for the Request.
241 method: func() -> method;
242 /// Set the Method for the Request. Fails if the string present in a
243 /// `method.other` argument is not a syntactically valid method.
244 set-method: func(method: method) -> result;
245 /// Get the combination of the HTTP Path and Query for the Request.
246 /// When `none`, this represents an empty Path and empty Query.
247 path-with-query: func() -> option<string>;
248 /// Set the combination of the HTTP Path and Query for the Request.
249 /// When `none`, this represents an empty Path and empty Query. Fails is the
250 /// string given is not a syntactically valid path and query uri component.
251 set-path-with-query: func(path-with-query: option<string>) -> result;
252 /// Get the HTTP Related Scheme for the Request. When `none`, the
253 /// implementation may choose an appropriate default scheme.
254 scheme: func() -> option<scheme>;
255 /// Set the HTTP Related Scheme for the Request. When `none`, the
256 /// implementation may choose an appropriate default scheme. Fails if the
257 /// string given is not a syntactically valid uri scheme.
258 set-scheme: func(scheme: option<scheme>) -> result;
259 /// Get the HTTP Authority for the Request. A value of `none` may be used
260 /// with Related Schemes which do not require an Authority. The HTTP and
261 /// HTTPS schemes always require an authority.
262 authority: func() -> option<string>;
263 /// Set the HTTP Authority for the Request. 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. Fails if the string given is
266 /// not a syntactically valid uri authority.
267 set-authority: func(authority: option<string>) -> result;
268 /// Get the headers associated with the Request.
269 ///
270 /// The returned `headers` resource is immutable: `set`, `append`, and
271 /// `delete` operations will fail with `header-error.immutable`.
272 ///
273 /// This headers resource is a child: it must be dropped before the parent
274 /// `outgoing-request` is dropped, or its ownership is transfered to
275 /// another component by e.g. `outgoing-handler.handle`.
276 headers: func() -> headers;
277 }
278
279 /// Parameters for making an HTTP Request. Each of these parameters is
280 /// currently an optional timeout applicable to the transport layer of the
281 /// HTTP protocol.
282 ///
283 /// These timeouts are separate from any the user may use to bound a
284 /// blocking call to `wasi:io/poll.poll`.
285 resource request-options {
286 /// Construct a default `request-options` value.
287 constructor();
288 /// The timeout for the initial connect to the HTTP Server.
289 connect-timeout: func() -> option<duration>;
290 /// Set the timeout for the initial connect to the HTTP Server. An error
291 /// return value indicates that this timeout is not supported.
292 set-connect-timeout: func(duration: option<duration>) -> result;
293 /// The timeout for receiving the first byte of the Response body.
294 first-byte-timeout: func() -> option<duration>;
295 /// Set the timeout for receiving the first byte of the Response body. An
296 /// error return value indicates that this timeout is not supported.
297 set-first-byte-timeout: func(duration: option<duration>) -> result;
298 /// The timeout for receiving subsequent chunks of bytes in the Response
299 /// body stream.
300 between-bytes-timeout: func() -> option<duration>;
301 /// Set the timeout for receiving subsequent chunks of bytes in the Response
302 /// body stream. An error return value indicates that this timeout is not
303 /// supported.
304 set-between-bytes-timeout: func(duration: option<duration>) -> result;
305 }
306
307 /// Represents the ability to send an HTTP Response.
308 ///
309 /// This resource is used by the `wasi:http/incoming-handler` interface to
310 /// allow a Response to be sent corresponding to the Request provided as the
311 /// other argument to `incoming-handler.handle`.
312 resource response-outparam {
313 /// Set the value of the `response-outparam` to either send a response,
314 /// or indicate an error.
315 ///
316 /// This method consumes the `response-outparam` to ensure that it is
317 /// called at most once. If it is never called, the implementation
318 /// will respond with an error.
319 ///
320 /// The user may provide an `error` to `response` to allow the
321 /// implementation determine how to respond with an HTTP error response.
322 set: static func(param: response-outparam, response: result<outgoing-response, error-code>);
323 }
324
325 /// This type corresponds to the HTTP standard Status Code.
326 type status-code = u16;
327
328 /// Represents an incoming HTTP Response.
329 resource incoming-response {
330 /// Returns the status code from the incoming response.
331 status: func() -> status-code;
332 /// Returns the headers from the incoming response.
333 ///
334 /// The returned `headers` resource is immutable: `set`, `append`, and
335 /// `delete` operations will fail with `header-error.immutable`.
336 ///
337 /// This headers resource is a child: it must be dropped before the parent
338 /// `incoming-response` is dropped.
339 headers: func() -> headers;
340 /// Returns the incoming body. May be called at most once. Returns error
341 /// if called additional times.
342 consume: func() -> result<incoming-body>;
343 }
344
345 /// Represents an incoming HTTP Request or Response's Body.
346 ///
347 /// A body has both its contents - a stream of bytes - and a (possibly
348 /// empty) set of trailers, indicating that the full contents of the
349 /// body have been received. This resource represents the contents as
350 /// an `input-stream` and the delivery of trailers as a `future-trailers`,
351 /// and ensures that the user of this interface may only be consuming either
352 /// the body contents or waiting on trailers at any given time.
353 resource incoming-body {
354 /// Returns the contents of the body, as a stream of bytes.
355 ///
356 /// Returns success on first call: the stream representing the contents
357 /// can be retrieved at most once. Subsequent calls will return error.
358 ///
359 /// The returned `input-stream` resource is a child: it must be dropped
360 /// before the parent `incoming-body` is dropped, or consumed by
361 /// `incoming-body.finish`.
362 ///
363 /// This invariant ensures that the implementation can determine whether
364 /// the user is consuming the contents of the body, waiting on the
365 /// `future-trailers` to be ready, or neither. This allows for network
366 /// backpressure is to be applied when the user is consuming the body,
367 /// and for that backpressure to not inhibit delivery of the trailers if
368 /// the user does not read the entire body.
369 %stream: func() -> result<input-stream>;
370 /// Takes ownership of `incoming-body`, and returns a `future-trailers`.
371 /// This function will trap if the `input-stream` child is still alive.
372 finish: static func(this: incoming-body) -> future-trailers;
373 }
374
375 /// Represents a future which may eventaully return trailers, or an error.
376 ///
377 /// In the case that the incoming HTTP Request or Response did not have any
378 /// trailers, this future will resolve to the empty set of trailers once the
379 /// complete Request or Response body has been received.
380 resource future-trailers {
381 /// Returns a pollable which becomes ready when either the trailers have
382 /// been received, or an error has occured. When this pollable is ready,
383 /// the `get` method will return `some`.
384 subscribe: func() -> pollable;
385 /// Returns the contents of the trailers, or an error which occured,
386 /// once the future is ready.
387 ///
388 /// The outer `option` represents future readiness. Users can wait on this
389 /// `option` to become `some` using the `subscribe` method.
390 ///
391 /// The outer `result` is used to retrieve the trailers or error at most
392 /// once. It will be success on the first call in which the outer option
393 /// is `some`, and error on subsequent calls.
394 ///
395 /// The inner `result` represents that either the HTTP Request or Response
396 /// body, as well as any trailers, were received successfully, or that an
397 /// error occured receiving them. The optional `trailers` indicates whether
398 /// or not trailers were present in the body.
399 ///
400 /// When some `trailers` are returned by this method, the `trailers`
401 /// resource is immutable, and a child. Use of the `set`, `append`, or
402 /// `delete` methods will return an error, and the resource must be
403 /// dropped before the parent `future-trailers` is dropped.
404 get: func() -> option<result<result<option<trailers>, error-code>>>;
405 }
406
407 /// Represents an outgoing HTTP Response.
408 resource outgoing-response {
409 /// Construct an `outgoing-response`, with a default `status-code` of `200`.
410 /// If a different `status-code` is needed, it must be set via the
411 /// `set-status-code` method.
412 ///
413 /// * `headers` is the HTTP Headers for the Response.
414 constructor(headers: headers);
415 /// Get the HTTP Status Code for the Response.
416 status-code: func() -> status-code;
417 /// Set the HTTP Status Code for the Response. Fails if the status-code
418 /// given is not a valid http status code.
419 set-status-code: func(status-code: status-code) -> result;
420 /// Get the headers associated with the Request.
421 ///
422 /// The returned `headers` resource is immutable: `set`, `append`, and
423 /// `delete` operations will fail with `header-error.immutable`.
424 ///
425 /// This headers resource is a child: it must be dropped before the parent
426 /// `outgoing-request` is dropped, or its ownership is transfered to
427 /// another component by e.g. `outgoing-handler.handle`.
428 headers: func() -> headers;
429 /// Returns the resource corresponding to the outgoing Body for this Response.
430 ///
431 /// Returns success on the first call: the `outgoing-body` resource for
432 /// this `outgoing-response` can be retrieved at most once. Subsequent
433 /// calls will return error.
434 body: func() -> result<outgoing-body>;
435 }
436
437 /// Represents an outgoing HTTP Request or Response's Body.
438 ///
439 /// A body has both its contents - a stream of bytes - and a (possibly
440 /// empty) set of trailers, inducating the full contents of the body
441 /// have been sent. This resource represents the contents as an
442 /// `output-stream` child resource, and the completion of the body (with
443 /// optional trailers) with a static function that consumes the
444 /// `outgoing-body` resource, and ensures that the user of this interface
445 /// may not write to the body contents after the body has been finished.
446 ///
447 /// If the user code drops this resource, as opposed to calling the static
448 /// method `finish`, the implementation should treat the body as incomplete,
449 /// and that an error has occured. The implementation should propogate this
450 /// error to the HTTP protocol by whatever means it has available,
451 /// including: corrupting the body on the wire, aborting the associated
452 /// Request, or sending a late status code for the Response.
453 resource outgoing-body {
454 /// Returns a stream for writing the body contents.
455 ///
456 /// The returned `output-stream` is a child resource: it must be dropped
457 /// before the parent `outgoing-body` resource is dropped (or finished),
458 /// otherwise the `outgoing-body` drop or `finish` will trap.
459 ///
460 /// Returns success on the first call: the `output-stream` resource for
461 /// this `outgoing-body` may be retrieved at most once. Subsequent calls
462 /// will return error.
463 write: func() -> result<output-stream>;
464 /// Finalize an outgoing body, optionally providing trailers. This must be
465 /// called to signal that the response is complete. If the `outgoing-body`
466 /// is dropped without calling `outgoing-body.finalize`, the implementation
467 /// should treat the body as corrupted.
468 ///
469 /// Fails if the body's `outgoing-request` or `outgoing-response` was
470 /// constructed with a Content-Length header, and the contents written
471 /// to the body (via `write`) does not match the value given in the
472 /// Content-Length.
473 finish: static func(this: outgoing-body, trailers: option<trailers>) -> result<_, error-code>;
474 }
475
476 /// Represents a future which may eventaully return an incoming HTTP
477 /// Response, or an error.
478 ///
479 /// This resource is returned by the `wasi:http/outgoing-handler` interface to
480 /// provide the HTTP Response corresponding to the sent Request.
481 resource future-incoming-response {
482 /// Returns a pollable which becomes ready when either the Response has
483 /// been received, or an error has occured. When this pollable is ready,
484 /// the `get` method will return `some`.
485 subscribe: func() -> pollable;
486 /// Returns the incoming HTTP Response, or an error, once one is ready.
487 ///
488 /// The outer `option` represents future readiness. Users can wait on this
489 /// `option` to become `some` using the `subscribe` method.
490 ///
491 /// The outer `result` is used to retrieve the response or error at most
492 /// once. It will be success on the first call in which the outer option
493 /// is `some`, and error on subsequent calls.
494 ///
495 /// The inner `result` represents that either the incoming HTTP Response
496 /// status and headers have recieved successfully, or that an error
497 /// occured. Errors may also occur while consuming the response body,
498 /// but those will be reported by the `incoming-body` and its
499 /// `output-stream` child.
500 get: func() -> option<result<result<incoming-response, error-code>>>;
501 }
502
503 /// Attempts to extract a http-related `error` from the wasi:io `error`
504 /// provided.
505 ///
506 /// Stream operations which return
507 /// `wasi:io/stream/stream-error::last-operation-failed` have a payload of
508 /// type `wasi:io/error/error` with more information about the operation
509 /// that failed. This payload can be passed through to this function to see
510 /// if there's http-related information about the error to return.
511 ///
512 /// Note that this function is fallible because not all io-errors are
513 /// http-related errors.
514 http-error-code: func(err: borrow<io-error>) -> option<error-code>;
515 }
516
517 /// This interface defines a handler of incoming HTTP Requests. It should
518 /// be exported by components which can respond to HTTP Requests.
519 interface incoming-handler {
520 use types.{incoming-request, response-outparam};
521
522 /// This function is invoked with an incoming HTTP Request, and a resource
523 /// `response-outparam` which provides the capability to reply with an HTTP
524 /// Response. The response is sent by calling the `response-outparam.set`
525 /// method, which allows execution to continue after the response has been
526 /// sent. This enables both streaming to the response body, and performing other
527 /// work.
528 ///
529 /// The implementor of this function must write a response to the
530 /// `response-outparam` before returning, or else the caller will respond
531 /// with an error on its behalf.
532 handle: func(request: incoming-request, response-out: response-outparam);
533 }
534
535 /// This interface defines a handler of outgoing HTTP Requests. It should be
536 /// imported by components which wish to make HTTP Requests.
537 interface outgoing-handler {
538 use types.{outgoing-request, request-options, future-incoming-response, error-code};
539
540 /// This function is invoked with an outgoing HTTP Request, and it returns
541 /// a resource `future-incoming-response` which represents an HTTP Response
542 /// which may arrive in the future.
543 ///
544 /// The `options` argument accepts optional parameters for the HTTP
545 /// protocol's transport layer.
546 ///
547 /// This function may return an error if the `outgoing-request` is invalid
548 /// or not allowed to be made. Otherwise, protocol errors are reported
549 /// through the `future-incoming-response`.
550 handle: func(request: outgoing-request, options: option<request-options>) -> result<future-incoming-response, error-code>;
551 }
552
553 /// The `wasi:http/proxy` world captures a widely-implementable intersection of
554 /// hosts that includes HTTP forward and reverse proxies. Components targeting
555 /// this world may concurrently stream in and out any number of incoming and
556 /// outgoing HTTP requests.
557 world proxy {
558 import wasi:random/[email protected];
559 import wasi:io/[email protected];
560 import wasi:io/[email protected];
561 import wasi:io/[email protected];
562 import wasi:cli/[email protected];
563 import wasi:cli/[email protected];
564 import wasi:cli/[email protected];
565 import wasi:clocks/[email protected];
566 import types;
567 import outgoing-handler;
568 import wasi:clocks/[email protected];
569
570 export incoming-handler;
571 }