🥮 mooncakes.io
README
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, Show)

Defines the case payload type for DNS-error above:

#
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, Show)

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

#
FieldSizePayload

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

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

#
Fields

source
pub(all) type Fields Int derive(Eq, Show)

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::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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn Fields::inner(self : Fields) -> Int
Convert newtype to its underlying type, automatically derived.

#
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.

#
FutureIncomingResponse

source
pub(all) type FutureIncomingResponse Int derive(Eq, Show)

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::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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn FutureIncomingResponse::inner(self : FutureIncomingResponse) -> Int
Convert newtype to its underlying type, automatically derived.

#
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.

#
FutureTrailers

source
pub(all) type FutureTrailers Int derive(Eq, Show)

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::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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn FutureTrailers::inner(self : FutureTrailers) -> Int
Convert newtype to its underlying type, automatically derived.

#
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.

#
HeaderError

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

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

#
IncomingBody

source
pub(all) type IncomingBody Int derive(Eq, Show)

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::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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn IncomingBody::inner(self : IncomingBody) -> Int
Convert newtype to its underlying type, automatically derived.

#
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.

#
IncomingRequest

source
pub(all) type IncomingRequest Int derive(Eq, Show)

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::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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn IncomingRequest::inner(self : IncomingRequest) -> Int
Convert newtype to its underlying type, automatically derived.

#
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.

#
IncomingResponse

source
pub(all) type IncomingResponse Int derive(Eq, Show)

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::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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn IncomingResponse::inner(self : IncomingResponse) -> Int
Convert newtype to its underlying type, automatically derived.

#
IncomingResponse::status

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

Returns the status code from the incoming response.

#
Method

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

This type corresponds to HTTP standard Methods.

#
OutgoingBody

source
pub(all) type OutgoingBody Int derive(Eq, Show)

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::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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn OutgoingBody::inner(self : OutgoingBody) -> Int
Convert newtype to its underlying type, automatically derived.

#
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) type OutgoingRequest Int derive(Eq, Show)

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::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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn OutgoingRequest::inner(self : OutgoingRequest) -> Int
Convert newtype to its underlying type, automatically derived.

#
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.

#
OutgoingResponse

source
pub(all) type OutgoingResponse Int derive(Eq, Show)

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::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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn OutgoingResponse::inner(self : OutgoingResponse) -> Int
Convert newtype to its underlying type, automatically derived.

#
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.

#
RequestOptions

source
pub(all) type RequestOptions Int derive(Eq, Show)

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::first_byte_timeout

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

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

#
RequestOptions::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn RequestOptions::inner(self : RequestOptions) -> Int
Convert newtype to its underlying type, automatically derived.

#
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.

#
ResponseOutparam

source
pub(all) type ResponseOutparam Int derive(Eq, Show)

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::inner

source
#deprecated("Use `struct T(A)` to declare a newtype and use `.0` access the underlying type instead.")
fn ResponseOutparam::inner(self : ResponseOutparam) -> Int
Convert newtype to its underlying type, automatically derived.

#
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.

#
Scheme

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

This type corresponds to HTTP standard Related Schemes.

#
TlsAlertReceivedPayload

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

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

#
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