diff --git a/wit-0.3.0-draft/types.wit b/wit-0.3.0-draft/types.wit index deec70b..f0ba605 100644 --- a/wit-0.3.0-draft/types.wit +++ b/wit-0.3.0-draft/types.wit @@ -230,77 +230,36 @@ interface types { /// Trailers is an alias for Fields. type trailers = fields; - /// Represents an HTTP Request or Response's Body. - /// - /// A body has both its contents - a stream of bytes - and a (possibly empty) - /// set of trailers, indicating that the full contents of the body have been - /// received. This resource represents the contents as a `stream` and the - /// delivery of trailers as a `trailers`, and ensures that the user of this - /// interface may only be consuming either the body contents or waiting on - /// trailers at any given time. - resource body { - - /// Construct a new `body` with the specified stream. - /// - /// This function returns a future, which will resolve - /// to an error code if transmitting stream data fails. - /// - /// The returned future resolves to success once body stream - /// is fully transmitted. - new: static func( - %stream: stream, - ) -> tuple>>; - - /// Construct a new `body` with the specified stream and trailers. - /// - /// This function returns a future, which will resolve - /// to an error code if transmitting stream data or trailers fails. - /// - /// The returned future resolves to success once body stream and trailers - /// are fully transmitted. - new-with-trailers: static func( - %stream: stream, - trailers: future - ) -> tuple>>; - - /// Returns the contents of the body, as a stream of bytes. - /// - /// This function may be called multiple times as long as any `stream`s - /// returned by previous calls have been dropped first. - /// - /// On success, this function returns a stream and a future, which will resolve - /// to an error code if receiving data from stream fails. - /// The returned future resolves to success if body is closed. - %stream: func() -> result, future>>>; - - /// Takes ownership of `body`, and returns an unresolved optional `trailers` result. - /// - /// This function will trap if a `stream` child is still alive. - finish: static func(this: body) -> future, error-code>>; - } - /// Represents an HTTP Request. resource request { /// Construct a new `request` with a default `method` of `GET`, and /// `none` values for `path-with-query`, `scheme`, and `authority`. /// - /// * `headers` is the HTTP Headers for the Response. - /// * `body` is the optional contents of the body, possibly including - /// trailers. - /// * `options` is optional `request-options` to be used if the request is - /// sent over a network connection. + /// `headers` is the HTTP Headers for the Request. + /// + /// `contents` is the optional body content stream with `none` + /// representing a zero-length content stream. + /// Once it is closed, `trailers` future must resolve to a result. + /// If `trailers` resolves to an error, underlying connection + /// will be closed immediately. + /// + /// `options` is optional `request-options` resource to be used + /// if the request is sent over a network connection. /// /// It is possible to construct, or manipulate with the accessor functions - /// below, an `request` with an invalid combination of `scheme` + /// below, a `request` with an invalid combination of `scheme` /// and `authority`, or `headers` which are not permitted to be sent. /// It is the obligation of the `handler.handle` implementation /// to reject invalid constructions of `request`. - constructor( + /// + /// The returned future resolves to result of transmission of this request. + new: static func( headers: headers, - body: option, + contents: option>, + trailers: future, error-code>>, options: option - ); + ) -> tuple>>; /// Get the Method for the Request. method: func() -> method; @@ -348,22 +307,28 @@ interface types { /// /// The returned `headers` resource is immutable: `set`, `append`, and /// `delete` operations will fail with `header-error.immutable`. - /// - /// This headers resource is a child: it must be dropped before the parent - /// `request` is dropped, or its ownership is transferred to another - /// component by e.g. `handler.handle`. headers: func() -> headers; - /// Get the body associated with the Request, if any. + /// Get body of the Request. /// - /// This body resource is a child: it must be dropped before the parent - /// `request` is dropped, or its ownership is transferred to another - /// component by e.g. `handler.handle`. - body: func() -> option; - - /// Takes ownership of the `request` and returns the `headers`, `body` - /// and `request-options`, if any. - into-parts: static func(this: request) -> tuple, option>; + /// Stream returned by this method represents the contents of the body. + /// Once the stream is reported as closed, callers should await the returned future + /// to determine whether the body was received successfully. + /// The future will only resolve after the stream is reported as closed. + /// + /// The stream and future returned by this method are children: + /// they should be closed or consumed before the parent `response` + /// is dropped, or its ownership is transferred to another component + /// by e.g. `handler.handle`. + /// + /// This method may be called multiple times. + /// + /// This method will return an error if it is called while either: + /// - a stream or future returned by a previous call to this method is still open + /// - a stream returned by a previous call to this method has reported itself as closed + /// Thus there will always be at most one readable stream open for a given body. + /// Each subsequent stream picks up where the last stream left off, up until it is finished. + body: func() -> result, future, error-code>>>>; } /// Parameters for making an HTTP Request. Each of these parameters is @@ -400,6 +365,10 @@ interface types { /// body stream. An error return value indicates that this timeout is not /// supported or that this handle is immutable. set-between-bytes-timeout: func(duration: option) -> result<_, request-options-error>; + + /// Make a deep copy of the `request-options`. + /// The resulting `request-options` is mutable. + clone: func() -> request-options; } /// This type corresponds to the HTTP standard Status Code. @@ -408,17 +377,24 @@ interface types { /// Represents an HTTP Response. resource response { - /// Construct an `response`, with a default `status-code` of `200`. If a - /// different `status-code` is needed, it must be set via the + /// Construct a new `response`, with a default `status-code` of `200`. + /// If a different `status-code` is needed, it must be set via the /// `set-status-code` method. /// - /// * `headers` is the HTTP Headers for the Response. - /// * `body` is the optional contents of the body, possibly including - /// trailers. - constructor( + /// `headers` is the HTTP Headers for the Response. + /// + /// `contents` is the optional body content stream with `none` + /// representing a zero-length content stream. + /// Once it is closed, `trailers` future must resolve to a result. + /// If `trailers` resolves to an error, underlying connection + /// will be closed immediately. + /// + /// The returned future resolves to result of transmission of this response. + new: static func( headers: headers, - body: option, - ); + contents: option>, + trailers: future, error-code>>, + ) -> tuple>>; /// Get the HTTP Status Code for the Response. status-code: func() -> status-code; @@ -427,25 +403,31 @@ interface types { /// given is not a valid http status code. set-status-code: func(status-code: status-code) -> result; - /// Get the headers associated with the Request. + /// Get the headers associated with the Response. /// /// The returned `headers` resource is immutable: `set`, `append`, and /// `delete` operations will fail with `header-error.immutable`. - /// - /// This headers resource is a child: it must be dropped before the parent - /// `response` is dropped, or its ownership is transferred to another - /// component by e.g. `handler.handle`. headers: func() -> headers; - /// Get the body associated with the Response, if any. + /// Get body of the Response. /// - /// This body resource is a child: it must be dropped before the parent - /// `response` is dropped, or its ownership is transferred to another - /// component by e.g. `handler.handle`. - body: func() -> option; - - /// Takes ownership of the `response` and returns the `headers` and `body`, - /// if any. - into-parts: static func(this: response) -> tuple>; + /// Stream returned by this method represents the contents of the body. + /// Once the stream is reported as closed, callers should await the returned future + /// to determine whether the body was received successfully. + /// The future will only resolve after the stream is reported as closed. + /// + /// The stream and future returned by this method are children: + /// they should be closed or consumed before the parent `response` + /// is dropped, or its ownership is transferred to another component + /// by e.g. `handler.handle`. + /// + /// This method may be called multiple times. + /// + /// This method will return an error if it is called while either: + /// - a stream or future returned by a previous call to this method is still open + /// - a stream returned by a previous call to this method has reported itself as closed + /// Thus there will always be at most one readable stream open for a given body. + /// Each subsequent stream picks up where the last stream left off, up until it is finished. + body: func() -> result, future, error-code>>>>; } }