| 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 |
} |