From daab82027734e6bc246b17e73cad06aeb6da8b48 Mon Sep 17 00:00:00 2001 From: Eduardo Rodrigues <16357187+eduardomourar@users.noreply.github.com> Date: Sat, 23 Sep 2023 00:37:30 +0200 Subject: [PATCH] chore: update markdown for proxy world --- proxy.md | 263 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 179 insertions(+), 84 deletions(-) diff --git a/proxy.md b/proxy.md index e0d0288..6994ccb 100644 --- a/proxy.md +++ b/proxy.md @@ -1,4 +1,8 @@

World proxy

+

The wasi:http/proxy world captures a widely-implementable intersection of +hosts that includes HTTP forward and reverse proxies. Components targeting +this world may concurrently stream in and out any number of incoming and +outgoing HTTP requests.

-

record stream-error

-

An error type returned from a stream operation. Currently this -doesn't provide any additional information.

-
Record Fields
-

type output-stream

-

u32

-

An output bytestream. In the future, this will be replaced by handle -types. -

This conceptually represents a stream<u8, _>. It's temporary -scaffolding until component-model's async features are ready.

-

output-streams are non-blocking to the extent practical on -underlying platforms. Except where specified otherwise, I/O operations also -always return promptly, after the number of bytes that can be written -promptly, which could even be zero. To wait for the stream to be ready to -accept data, the subscribe-to-output-stream function to obtain a -pollable which can be polled for using wasi_poll.

-

And at present, it is a u32 instead of being an actual handle, until -the wit-bindgen implementation of handles and resources is ready.

-

This represents a resource.

type input-stream

u32

An input bytestream. In the future, this will be replaced by handle @@ -335,6 +324,21 @@ can be polled for using wasi_poll.

And at present, it is a u32 instead of being an actual handle, until the wit-bindgen implementation of handles and resources is ready.

This represents a resource.

+

type output-stream

+

u32

+

An output bytestream. In the future, this will be replaced by handle +types. +

This conceptually represents a stream<u8, _>. It's temporary +scaffolding until component-model's async features are ready.

+

output-streams are non-blocking to the extent practical on +underlying platforms. Except where specified otherwise, I/O operations also +always return promptly, after the number of bytes that can be written +promptly, which could even be zero. To wait for the stream to be ready to +accept data, the subscribe-to-output-stream function to obtain a +pollable which can be polled for using wasi_poll.

+

And at present, it is a u32 instead of being an actual handle, until +the wit-bindgen implementation of handles and resources is ready.

+

This represents a resource.

Functions

read: func

@@ -583,6 +587,9 @@ be used.

  • input-stream

    • Import interface wasi:http/types

    +

    The wasi:http/types interface is meant to be imported by components to +define the HTTP resource types and operations used by the component's +imported and exported interfaces.

    Types

    type input-stream

    @@ -594,36 +601,8 @@ be used.

    #### `type pollable` [`pollable`](#pollable)

    -#### `type status-code` -`u16` -

    -#### `variant scheme` -

    Variant Cases
    - -

    type response-outparam

    -

    u32

    -

    -#### `record request-options` -

    Record Fields
    - -

    type outgoing-stream

    -

    output-stream

    -

    -#### `type outgoing-response` -`u32` -

    -#### `type outgoing-request` -`u32` -

    #### `variant method` +

    This type corresponds to HTTP standard Methods.

    Variant Cases
    -

    type incoming-stream

    -

    input-stream

    -

    -#### `type incoming-response` -`u32` +

    variant scheme

    +

    This type corresponds to HTTP standard Related Schemes.

    +
    Variant Cases
    + +

    variant error

    +

    TODO: perhaps better align with HTTP semantics? +This type enumerates the different kinds of errors that may occur when +initially returning a response.

    +
    Variant Cases
    + +

    type fields

    +

    u32

    +

    This following block defines the `fields` resource which corresponds to +HTTP standard Fields. Soon, when resource types are added, the `type +fields = u32` type alias can be replaced by a proper `resource fields` +definition containing all the functions using the method syntactic sugar. +

    type headers

    +

    fields

    -#### `type incoming-request` -`u32` +#### `type trailers` +[`fields`](#fields)

    -#### `type future-write-trailers-result` -`u32` +#### `type incoming-stream` +[`input-stream`](#input_stream) +

    The following block defines stream types which corresponds to the HTTP +standard Contents and Trailers. With Preview3, all of these fields can be +replaced by a stream>. In the interim, we need to +build on separate resource types defined by `wasi:io/streams`. The +`finish-` functions emulate the stream's result value and MUST be called +exactly once after the final read/write from/to the stream before dropping +the stream. The optional `future-` types describe the asynchronous result of +reading/writing the optional HTTP trailers and MUST be waited on and dropped +to complete streaming the request/response. +

    type outgoing-stream

    +

    output-stream

    #### `type future-trailers` `u32` +

    The following block defines the `future-trailers` resource, which is +returned when finishing an `incoming-stream` to asychronously produce the +final trailers. +

    type future-write-trailers-result

    +

    u32

    +

    The following block defines the `future-write-trailers-result` resource, +which is returned when finishing an `outgoing-stream` and asychronously +indicates the success or failure of writing the trailers. +

    type incoming-request

    +

    u32

    +

    The following block defines the `incoming-request` and `outgoing-request` +resource types that correspond to HTTP standard Requests. Soon, when +resource types are added, the `u32` type aliases can be replaced by proper +`resource` type definitions containing all the functions as methods. +Later, Preview2 will allow both types to be merged together into a single +`request` type (that uses the single `stream` type mentioned above). The +`consume` and `write` methods may only be called once (and return failure +thereafter). The `headers` and `trailers` passed into and out of requests +are shared with the request, with all mutations visible to all uses. +Components MUST avoid updating `headers` and `trailers` after passing a +request that points to them to the outside world. +The streams returned by `consume` and `write` are owned by the request and +response objects. The streams are destroyed when the request/response is +dropped, thus a client MUST drop any handle referring to a request/response stream +before dropping the request/response or passing ownership of the request/response +to the outside world. The caller can also call drop on the stream before the +request/response is dropped if they want to release resources earlier. +

    type outgoing-request

    +

    u32

    -#### `type future-incoming-response` -`u32` -

    -#### `type fields` -`u32` -

    -#### `type trailers` -[`fields`](#fields) -

    -#### `type headers` -[`fields`](#fields) -

    -#### `variant error` -

    Variant Cases
    +#### `record request-options` +

    Additional optional parameters that can be set when making a request.

    +
    Record Fields
    +

    type response-outparam

    +

    u32

    +

    The following block defines a special resource type used by the +`wasi:http/incoming-handler` interface. When resource types are added, this +block can be replaced by a proper `resource response-outparam { ... }` +definition. Later, with Preview3, the need for an outparam goes away entirely +(the `wasi:http/handler` interface used for both incoming and outgoing can +simply return a `stream`). +

    type status-code

    +

    u16

    +

    This type corresponds to the HTTP standard Status Code. +

    type incoming-response

    +

    u32

    +

    The following block defines the `incoming-response` and `outgoing-response` +resource types that correspond to HTTP standard Responses. Soon, when +resource types are added, the `u32` type aliases can be replaced by proper +`resource` type definitions containing all the functions as methods. Later, +Preview2 will allow both types to be merged together into a single `response` +type (that uses the single `stream` type mentioned above). The `consume` and +`write` methods may only be called once (and return failure thereafter). +The `headers` and `trailers` passed into and out of responses are shared +with the response, with all mutations visible to all uses. Components MUST +avoid updating `headers` and `trailers` after passing a response that +points to them to the outside world. +

    type outgoing-response

    +

    u32

    +

    +#### `type future-incoming-response` +`u32` +

    The following block defines a special resource type used by the +`wasi:http/outgoing-handler` interface to emulate +`future>` in advance of Preview3. Given a +`future-incoming-response`, the client can call the non-blocking `get` +method to get the result if it is available. If the result is not available, +the client can call `listen` to get a `pollable` that can be passed to +`io.poll.poll-oneoff`.

    Functions

    drop-fields: func

    @@ -987,6 +1064,11 @@ be used.

  • pollable

    • Import interface wasi:http/outgoing-handler

    +

    The wasi:http/outgoing-handler interface is meant to be imported by +components and implemented by the host.

    +

    NOTE: in Preview3, this interface will be merged with +wasi:http/outgoing-handler into a single wasi:http/handler interface +that takes a request parameter and returns a response result.

    Types

    type outgoing-request

    @@ -1001,6 +1083,9 @@ be used.

    ----

    Functions

    handle: func

    +

    The parameter and result types of the handle function allow the caller +to concurrently stream the bodies of the outgoing request and the incoming +response.

    Params