🥮 mooncakes.io
    Sign in
    This interface defines all of the types and methods for implementing HTTP Requests and Responses, both incoming and outgoing, as well as their headers, trailers, and bodies.

    DnsErrorPayload

    source
    pub(all) struct DnsErrorPayload {
      rcode : String?
      info_code : UInt?
    } derive(Eq, 
    Debug    )

    Defines the case payload type for DNS-error above:

    DnsErrorPayload::equal

    source

    DnsErrorPayload::to_repr

    source

    ErrorCode

    source
    pub(all) enum ErrorCode {
      DnsTimeout
      DnsError(DnsErrorPayload)
      DestinationNotFound
      DestinationUnavailable
      DestinationIpProhibited
      DestinationIpUnroutable
      ConnectionRefused
      ConnectionTerminated
      ConnectionTimeout
      ConnectionReadTimeout
      ConnectionWriteTimeout
      ConnectionLimitReached
      TlsProtocolError
      TlsCertificateError
      TlsAlertReceived(TlsAlertReceivedPayload)
      HttpRequestDenied
      HttpRequestLengthRequired
      HttpRequestBodySize(UInt64?)
      HttpRequestMethodInvalid
      HttpRequestUriInvalid
      HttpRequestUriTooLong
      HttpRequestHeaderSectionSize(UInt?)
      HttpRequestHeaderSize(FieldSizePayload?)
      HttpRequestTrailerSectionSize(UInt?)
      HttpRequestTrailerSize(FieldSizePayload)
      HttpResponseIncomplete
      HttpResponseHeaderSectionSize(UInt?)
      HttpResponseHeaderSize(FieldSizePayload)
      HttpResponseBodySize(UInt64?)
      HttpResponseTrailerSectionSize(UInt?)
      HttpResponseTrailerSize(FieldSizePayload)
      HttpResponseTransferCoding(String?)
      HttpResponseContentCoding(String?)
      HttpResponseTimeout
      HttpUpgradeFailed
      HttpProtocolError
      LoopDetected
      ConfigurationError
      InternalError(String?)
    } derive(Eq, 
    Debug    )

    These cases are inspired by the IANA HTTP Proxy Error Types: https://www.iana.org/assignments/http-proxy-status/http-proxy-status.xhtml#table-http-proxy-error-types

    ErrorCode::equal

    source
    fn ErrorCode::equal(ErrorCode, ErrorCode) -> Bool

    ErrorCode::to_repr

    source

    FieldSizePayload

    source
    pub(all) struct FieldSizePayload {
      field_name : String?
      field_size : UInt?
    } derive(Eq, 
    Debug    )

    Defines the case payload type for HTTP-response-{header,trailer}-size above:

    FieldSizePayload::equal

    source

    FieldSizePayload::to_repr

    source

    Fields

    source
    pub(all) struct Fields(Int) derive(Eq, 
    Debug    )

    This following block defines the fields resource which corresponds to HTTP standard Fields. Fields are a common representation used for both Headers and Trailers.

    A fields may be mutable or immutable. A fields created using the constructor, from-list, or clone will be mutable, but a fields resource given by other means (including, but not limited to, incoming-request.headers, outgoing-request.headers) might be be immutable. In an immutable fields, the set, append, and delete operations will fail with header-error.immutable.

    Fields::append

    source
    fn Fields::append(self : Fields, name : String, value : FixedArray[Byte]) -> Result[Unit, HeaderError]

    Append a value for a key. Does not change or delete any existing values for that key.

    Fails with header-error.immutable if the fields are immutable.

    Fields::clone

    source
    fn Fields::clone(self : Fields) -> Fields

    Make a deep copy of the Fields. Equivelant in behavior to calling the fields constructor on the return value of entries. The resulting fields is mutable.

    Fields::delete

    source
    fn Fields::delete(self : Fields, name : String) -> Result[Unit, HeaderError]

    Delete all values for a key. Does nothing if no values for the key exist.

    Fails with header-error.immutable if the fields are immutable.

    Fields::drop

    source
    fn Fields::drop(self : Fields) -> Unit

    Drops a resource handle.

    Fields::entries

    source
    fn Fields::entries(self : Fields) -> Array[(String, FixedArray[Byte])]

    Retrieve the full set of keys and values in the Fields. Like the constructor, the list represents each key-value pair.

    The outer list represents each key-value pair in the Fields. Keys which have multiple values are represented by multiple entries in this list with the same key.

    Fields::equal

    source
    fn Fields::equal(Fields, Fields) -> Bool

    Fields::fields

    source
    fn Fields::fields() -> Fields

    Construct an empty HTTP Fields.

    The resulting fields is mutable.

    Fields::from_list

    source
    fn Fields::from_list(entries : Array[(String, FixedArray[Byte])]) -> Result[Fields, HeaderError]

    Construct an HTTP Fields.

    The resulting fields is mutable.

    The list represents each key-value pair in the Fields. Keys which have multiple values are represented by multiple entries in this list with the same key.

    The tuple is a pair of the field key, represented as a string, and Value, represented as a list of bytes. In a valid Fields, all keys and values are valid UTF-8 strings. However, values are not always well-formed, so they are represented as a raw list of bytes.

    An error result will be returned if any header or value was syntactically invalid, or if a header was forbidden.

    Fields::get

    source
    fn Fields::get(self : Fields, name : String) -> Array[FixedArray[Byte]]

    Get all of the values corresponding to a key. If the key is not present in this fields, an empty list is returned. However, if the key is present but empty, this is represented by a list with one or more empty field-values present.

    Fields::has

    source
    fn Fields::has(self : Fields, name : String) -> Bool

    Returns true when the key is present in this fields. If the key is syntactically invalid, false is returned.

    Fields::set

    source
    fn Fields::set(self : Fields, name : String, value : Array[FixedArray[Byte]]) -> Result[Unit, HeaderError]

    Set all of the values for a key. Clears any existing values for that key, if they have been set.

    Fails with header-error.immutable if the fields are immutable.

    Fields::to_repr

    source

    FutureIncomingResponse

    source
    pub(all) struct FutureIncomingResponse(Int) derive(Eq, 
    Debug    )

    Represents a future which may eventaully return an incoming HTTP Response, or an error.

    This resource is returned by the wasi:http/outgoing-handler interface to provide the HTTP Response corresponding to the sent Request.

    FutureIncomingResponse::drop

    source

    Drops a resource handle.

    FutureIncomingResponse::equal

    source

    FutureIncomingResponse::get

    source
    fn FutureIncomingResponse::get(self : FutureIncomingResponse) -> Result[Result[IncomingResponse, ErrorCode], Unit]?

    Returns the incoming HTTP Response, or an error, once one is ready.

    The outer option represents future readiness. Users can wait on this option to become some using the subscribe method.

    The outer result is used to retrieve the response or error at most once. It will be success on the first call in which the outer option is some, and error on subsequent calls.

    The inner result represents that either the incoming HTTP Response status and headers have recieved successfully, or that an error occured. Errors may also occur while consuming the response body, but those will be reported by the incoming-body and its output-stream child.

    FutureIncomingResponse::subscribe

    source

    Returns a pollable which becomes ready when either the Response has been received, or an error has occured. When this pollable is ready, the get method will return some.

    FutureIncomingResponse::to_repr

    source

    FutureTrailers

    source
    pub(all) struct FutureTrailers(Int) derive(Eq, 
    Debug    )

    Represents a future which may eventaully return trailers, or an error.

    In the case that the incoming HTTP Request or Response did not have any trailers, this future will resolve to the empty set of trailers once the complete Request or Response body has been received.

    FutureTrailers::drop

    source
    fn FutureTrailers::drop(self : FutureTrailers) -> Unit

    Drops a resource handle.

    FutureTrailers::equal

    source

    FutureTrailers::get

    source
    fn FutureTrailers::get(self : FutureTrailers) -> Result[Result[Fields?, ErrorCode], Unit]?

    Returns the contents of the trailers, or an error which occured, once the future is ready.

    The outer option represents future readiness. Users can wait on this option to become some using the subscribe method.

    The outer result is used to retrieve the trailers or error at most once. It will be success on the first call in which the outer option is some, and error on subsequent calls.

    The inner result represents that either the HTTP Request or Response body, as well as any trailers, were received successfully, or that an error occured receiving them. The optional trailers indicates whether or not trailers were present in the body.

    When some trailers are returned by this method, the trailers resource is immutable, and a child. Use of the set, append, or delete methods will return an error, and the resource must be dropped before the parent future-trailers is dropped.

    FutureTrailers::subscribe

    source

    Returns a pollable which becomes ready when either the trailers have been received, or an error has occured. When this pollable is ready, the get method will return some.

    FutureTrailers::to_repr

    source

    HeaderError

    source
    pub(all) enum HeaderError {
      InvalidSyntax
      Forbidden
      Immutable
    } derive(Eq, 
    Debug    )

    This type enumerates the different kinds of errors that may occur when setting or appending to a fields resource.

    HeaderError::equal

    source
    fn HeaderError::equal(HeaderError, HeaderError) -> Bool

    HeaderError::to_repr

    source

    IncomingBody

    source
    pub(all) struct IncomingBody(Int) derive(Eq, 
    Debug    )

    Represents an incoming 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 an input-stream and the delivery of trailers as a future-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.

    IncomingBody::drop

    source
    fn IncomingBody::drop(self : IncomingBody) -> Unit

    Drops a resource handle.

    IncomingBody::equal

    source

    IncomingBody::finish

    source

    Takes ownership of incoming-body, and returns a future-trailers. This function will trap if the input-stream child is still alive.

    IncomingBody::stream

    source

    Returns the contents of the body, as a stream of bytes.

    Returns success on first call: the stream representing the contents can be retrieved at most once. Subsequent calls will return error.

    The returned input-stream resource is a child: it must be dropped before the parent incoming-body is dropped, or consumed by incoming-body.finish.

    This invariant ensures that the implementation can determine whether the user is consuming the contents of the body, waiting on the future-trailers to be ready, or neither. This allows for network backpressure is to be applied when the user is consuming the body, and for that backpressure to not inhibit delivery of the trailers if the user does not read the entire body.

    IncomingBody::to_repr

    source

    IncomingRequest

    source
    pub(all) struct IncomingRequest(Int) derive(Eq, 
    Debug    )

    Represents an incoming HTTP Request.

    IncomingRequest::authority

    source
    fn IncomingRequest::authority(self : IncomingRequest) -> String?

    Returns the authority from the request, if it was present.

    IncomingRequest::consume

    source
    fn IncomingRequest::consume(self : IncomingRequest) -> Result[IncomingBody, Unit]

    Gives the incoming-body associated with this request. Will only return success at most once, and subsequent calls will return error.

    IncomingRequest::drop

    source
    fn IncomingRequest::drop(self : IncomingRequest) -> Unit

    Drops a resource handle.

    IncomingRequest::equal

    source

    IncomingRequest::headers

    source
    fn IncomingRequest::headers(self : IncomingRequest) -> Fields

    Get the headers associated with the request.

    The returned headers resource is immutable: set, append, and delete operations will fail with header-error.immutable.

    The headers returned are a child resource: it must be dropped before the parent incoming-request is dropped. Dropping this incoming-request before all children are dropped will trap.

    IncomingRequest::method_

    source
    fn IncomingRequest::method_(self : IncomingRequest) -> Method

    Returns the method of the incoming request.

    IncomingRequest::path_with_query

    source
    fn IncomingRequest::path_with_query(self : IncomingRequest) -> String?

    Returns the path with query parameters from the request, as a string.

    IncomingRequest::scheme

    source
    fn IncomingRequest::scheme(self : IncomingRequest) -> Scheme?

    Returns the protocol scheme from the request.

    IncomingRequest::to_repr

    source

    IncomingResponse

    source
    pub(all) struct IncomingResponse(Int) derive(Eq, 
    Debug    )

    Represents an incoming HTTP Response.

    IncomingResponse::consume

    source
    fn IncomingResponse::consume(self : IncomingResponse) -> Result[IncomingBody, Unit]

    Returns the incoming body. May be called at most once. Returns error if called additional times.

    IncomingResponse::drop

    source
    fn IncomingResponse::drop(self : IncomingResponse) -> Unit

    Drops a resource handle.

    IncomingResponse::equal

    source

    IncomingResponse::headers

    source

    Returns the headers from the incoming 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 incoming-response is dropped.

    IncomingResponse::status

    source
    fn IncomingResponse::status(self : IncomingResponse) -> UInt

    Returns the status code from the incoming response.

    IncomingResponse::to_repr

    source

    Method

    source
    pub(all) enum Method {
      Get
      Head
      Post
      Put
      Delete
      Connect
      Options
      Trace
      Patch
      Other(String)
    } derive(Eq, 
    Debug    )

    This type corresponds to HTTP standard Methods.

    Method::equal

    source
    fn Method::equal(Method, Method) -> Bool

    Method::to_repr

    source

    OutgoingBody

    source
    pub(all) struct OutgoingBody(Int) derive(Eq, 
    Debug    )

    Represents an outgoing HTTP Request or Response's Body.

    A body has both its contents - a stream of bytes - and a (possibly empty) set of trailers, inducating the full contents of the body have been sent. This resource represents the contents as an output-stream child resource, and the completion of the body (with optional trailers) with a static function that consumes the outgoing-body resource, and ensures that the user of this interface may not write to the body contents after the body has been finished.

    If the user code drops this resource, as opposed to calling the static method finish, the implementation should treat the body as incomplete, and that an error has occured. The implementation should propogate this error to the HTTP protocol by whatever means it has available, including: corrupting the body on the wire, aborting the associated Request, or sending a late status code for the Response.

    OutgoingBody::drop

    source
    fn OutgoingBody::drop(self : OutgoingBody) -> Unit

    Drops a resource handle.

    OutgoingBody::equal

    source

    OutgoingBody::finish

    source
    fn OutgoingBody::finish(this : OutgoingBody, trailers : Fields?) -> Result[Unit, ErrorCode]

    Finalize an outgoing body, optionally providing trailers. This must be called to signal that the response is complete. If the outgoing-body is dropped without calling outgoing-body.finalize, the implementation should treat the body as corrupted.

    Fails if the body's outgoing-request or outgoing-response was constructed with a Content-Length header, and the contents written to the body (via write) does not match the value given in the Content-Length.

    OutgoingBody::to_repr

    source

    OutgoingBody::write

    source

    Returns a stream for writing the body contents.

    The returned output-stream is a child resource: it must be dropped before the parent outgoing-body resource is dropped (or finished), otherwise the outgoing-body drop or finish will trap.

    Returns success on the first call: the output-stream resource for this outgoing-body may be retrieved at most once. Subsequent calls will return error.

    OutgoingRequest

    source
    pub(all) struct OutgoingRequest(Int) derive(Eq, 
    Debug    )

    Represents an outgoing HTTP Request.

    OutgoingRequest::authority

    source
    fn OutgoingRequest::authority(self : OutgoingRequest) -> String?

    Get the HTTP Authority for the Request. A value of none may be used with Related Schemes which do not require an Authority. The HTTP and HTTPS schemes always require an authority.

    OutgoingRequest::body

    source
    fn OutgoingRequest::body(self : OutgoingRequest) -> Result[OutgoingBody, Unit]

    Returns the resource corresponding to the outgoing Body for this Request.

    Returns success on the first call: the outgoing-body resource for this outgoing-request can be retrieved at most once. Subsequent calls will return error.

    OutgoingRequest::drop

    source
    fn OutgoingRequest::drop(self : OutgoingRequest) -> Unit

    Drops a resource handle.

    OutgoingRequest::equal

    source

    OutgoingRequest::headers

    source
    fn OutgoingRequest::headers(self : OutgoingRequest) -> Fields

    Get the headers associated with the Request.

    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 outgoing-request is dropped, or its ownership is transfered to another component by e.g. outgoing-handler.handle.

    OutgoingRequest::method_

    source
    fn OutgoingRequest::method_(self : OutgoingRequest) -> Method

    Get the Method for the Request.

    OutgoingRequest::outgoing_request

    source
    fn OutgoingRequest::outgoing_request(headers : Fields) -> OutgoingRequest

    Construct a new outgoing-request with a default method of GET, and none values for path-with-query, scheme, and authority.

    • headers is the HTTP Headers for the Request.

    It is possible to construct, or manipulate with the accessor functions below, an outgoing-request with an invalid combination of scheme and authority, or headers which are not permitted to be sent. It is the obligation of the outgoing-handler.handle implementation to reject invalid constructions of outgoing-request.

    OutgoingRequest::path_with_query

    source
    fn OutgoingRequest::path_with_query(self : OutgoingRequest) -> String?

    Get the combination of the HTTP Path and Query for the Request. When none, this represents an empty Path and empty Query.

    OutgoingRequest::scheme

    source
    fn OutgoingRequest::scheme(self : OutgoingRequest) -> Scheme?

    Get the HTTP Related Scheme for the Request. When none, the implementation may choose an appropriate default scheme.

    OutgoingRequest::set_authority

    source
    fn OutgoingRequest::set_authority(self : OutgoingRequest, authority : String?) -> Result[Unit, Unit]

    Set the HTTP Authority for the Request. A value of none may be used with Related Schemes which do not require an Authority. The HTTP and HTTPS schemes always require an authority. Fails if the string given is not a syntactically valid uri authority.

    OutgoingRequest::set_method

    source
    fn OutgoingRequest::set_method(self : OutgoingRequest, method_ : Method) -> Result[Unit, Unit]

    Set the Method for the Request. Fails if the string present in a method.other argument is not a syntactically valid method.

    OutgoingRequest::set_path_with_query

    source
    fn OutgoingRequest::set_path_with_query(self : OutgoingRequest, path_with_query : String?) -> Result[Unit, Unit]

    Set the combination of the HTTP Path and Query for the Request. When none, this represents an empty Path and empty Query. Fails is the string given is not a syntactically valid path and query uri component.

    OutgoingRequest::set_scheme

    source
    fn OutgoingRequest::set_scheme(self : OutgoingRequest, scheme : Scheme?) -> Result[Unit, Unit]

    Set the HTTP Related Scheme for the Request. When none, the implementation may choose an appropriate default scheme. Fails if the string given is not a syntactically valid uri scheme.

    OutgoingRequest::to_repr

    source

    OutgoingResponse

    source
    pub(all) struct OutgoingResponse(Int) derive(Eq, 
    Debug    )

    Represents an outgoing HTTP Response.

    OutgoingResponse::body

    source
    fn OutgoingResponse::body(self : OutgoingResponse) -> Result[OutgoingBody, Unit]

    Returns the resource corresponding to the outgoing Body for this Response.

    Returns success on the first call: the outgoing-body resource for this outgoing-response can be retrieved at most once. Subsequent calls will return error.

    OutgoingResponse::drop

    source
    fn OutgoingResponse::drop(self : OutgoingResponse) -> Unit

    Drops a resource handle.

    OutgoingResponse::equal

    source

    OutgoingResponse::headers

    source

    Get the headers associated with the Request.

    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 outgoing-request is dropped, or its ownership is transfered to another component by e.g. outgoing-handler.handle.

    OutgoingResponse::outgoing_response

    source
    fn OutgoingResponse::outgoing_response(headers : Fields) -> OutgoingResponse

    Construct an outgoing-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.

    OutgoingResponse::set_status_code

    source
    fn OutgoingResponse::set_status_code(self : OutgoingResponse, status_code : UInt) -> Result[Unit, Unit]

    Set the HTTP Status Code for the Response. Fails if the status-code given is not a valid http status code.

    OutgoingResponse::status_code

    source
    fn OutgoingResponse::status_code(self : OutgoingResponse) -> UInt

    Get the HTTP Status Code for the Response.

    OutgoingResponse::to_repr

    source

    RequestOptions

    source
    pub(all) struct RequestOptions(Int) derive(Eq, 
    Debug    )

    Parameters for making an HTTP Request. Each of these parameters is currently an optional timeout applicable to the transport layer of the HTTP protocol.

    These timeouts are separate from any the user may use to bound a blocking call to wasi:io/poll.poll.

    RequestOptions::between_bytes_timeout

    source
    fn RequestOptions::between_bytes_timeout(self : RequestOptions) -> UInt64?

    The timeout for receiving subsequent chunks of bytes in the Response body stream.

    RequestOptions::connect_timeout

    source
    fn RequestOptions::connect_timeout(self : RequestOptions) -> UInt64?

    The timeout for the initial connect to the HTTP Server.

    RequestOptions::drop

    source
    fn RequestOptions::drop(self : RequestOptions) -> Unit

    Drops a resource handle.

    RequestOptions::equal

    source

    RequestOptions::first_byte_timeout

    source
    fn RequestOptions::first_byte_timeout(self : RequestOptions) -> UInt64?

    The timeout for receiving the first byte of the Response body.

    RequestOptions::request_options

    source
    fn RequestOptions::request_options() -> RequestOptions

    Construct a default request-options value.

    RequestOptions::set_between_bytes_timeout

    source
    fn RequestOptions::set_between_bytes_timeout(self : RequestOptions, duration : UInt64?) -> Result[Unit, Unit]

    Set the timeout for receiving subsequent chunks of bytes in the Response body stream. An error return value indicates that this timeout is not supported.

    RequestOptions::set_connect_timeout

    source
    fn RequestOptions::set_connect_timeout(self : RequestOptions, duration : UInt64?) -> Result[Unit, Unit]

    Set the timeout for the initial connect to the HTTP Server. An error return value indicates that this timeout is not supported.

    RequestOptions::set_first_byte_timeout

    source
    fn RequestOptions::set_first_byte_timeout(self : RequestOptions, duration : UInt64?) -> Result[Unit, Unit]

    Set the timeout for receiving the first byte of the Response body. An error return value indicates that this timeout is not supported.

    RequestOptions::to_repr

    source

    ResponseOutparam

    source
    pub(all) struct ResponseOutparam(Int) derive(Eq, 
    Debug    )

    Represents the ability to send an HTTP Response.

    This resource is used by the wasi:http/incoming-handler interface to allow a Response to be sent corresponding to the Request provided as the other argument to incoming-handler.handle.

    ResponseOutparam::drop

    source
    fn ResponseOutparam::drop(self : ResponseOutparam) -> Unit

    Drops a resource handle.

    ResponseOutparam::equal

    source

    ResponseOutparam::set

    source
    fn ResponseOutparam::set(param : ResponseOutparam, response : Result[OutgoingResponse, ErrorCode]) -> Unit

    Set the value of the response-outparam to either send a response, or indicate an error.

    This method consumes the response-outparam to ensure that it is called at most once. If it is never called, the implementation will respond with an error.

    The user may provide an error to response to allow the implementation determine how to respond with an HTTP error response.

    ResponseOutparam::to_repr

    source

    Scheme

    source
    pub(all) enum Scheme {
      Http
      Https
      Other(String)
    } derive(Eq, 
    Debug    )

    This type corresponds to HTTP standard Related Schemes.

    Scheme::equal

    source
    fn Scheme::equal(Scheme, Scheme) -> Bool

    Scheme::to_repr

    source

    TlsAlertReceivedPayload

    source
    pub(all) struct TlsAlertReceivedPayload {
      alert_id : Byte?
      alert_message : String?
    } derive(Eq, 
    Debug    )

    Defines the case payload type for TLS-alert-received above:

    TlsAlertReceivedPayload::equal

    source

    TlsAlertReceivedPayload::to_repr

    source

    http_error_code

    source

    Attempts to extract a http-related error from the wasi:io error provided.

    Stream operations which return wasi:io/stream/stream-error::last-operation-failed have a payload of type wasi:io/error/error with more information about the operation that failed. This payload can be passed through to this function to see if there's http-related information about the error to return.

    Note that this function is fallible because not all io-errors are http-related errors.

    Source Files

    Powered by MoonBit

    Site sourceReport issuePackagesBuild queueSkillsStatistics

    © 2026 mooncakes.io