handler

const (
	// HostModule is the WebAssembly module name of the ABI this middleware
	// implements.
	//
	// Note: This is lower-hyphen case while functions are lower_underscore to
	// follow conventions of wit-bindgen, which retains the case format of the
	// interface filename as the module name, but converts function and
	// parameter names to lower_underscore format.
	//
	// See https://github.com/http-wasm/http-wasm-abi/blob/main/http_handler/http_handler.wit.md
	HostModule = "http_handler"

	// FuncEnableFeatures tries to enable the given features and returns the
	// Features bitflag supported by the host. To have any affect, this must be
	// called prior to returning from FuncHandleRequest.
	//
	// This may be called prior to FuncHandleRequest, for example inside a
	// start function. Doing so reduces overhead per-call and also allows the
	// guest to fail early on unsupported.
	//
	// If called during FuncHandleRequest, any new features are enabled for the
	// scope of the current request. This allows fine-grained access to
	// expensive features such as FeatureBufferResponse.
	//
	// TODO: document on http-wasm-abi
	FuncEnableFeatures = "enable_features"

	// FuncGetConfig writes configuration from the host to memory if it exists
	// and isn't larger than BufLimit. The result is its length in bytes.
	//
	// Note: Configuration is determined by the guest and is not necessarily
	// UTF-8 encoded.
	//
	// TODO: document on http-wasm-abi
	FuncGetConfig = "get_config"

	// FuncLogEnabled returns 1 if the api.LogLevel is enabled. This value may
	// be cached at request granularity.
	//
	// This function is used to avoid unnecessary overhead generating log
	// messages that the host would discard due to its level being below this.
	//
	// TODO: document on http-wasm-abi
	FuncLogEnabled = "log_enabled"

	// FuncLog logs a message to the host's logs at the given api.LogLevel.
	//
	// See https://github.com/http-wasm/http-wasm-abi/blob/main/http_handler/http_handler.wit.md#log
	FuncLog = "log"

	// FuncHandleRequest is the entrypoint guest export called by the host when
	// processing a request.
	//
	// To proceed to the next handler, the guest returns CtxNext `next=1`. The
	// simplest result is uint64(1). Guests who need request correlation can
	// also set the CtxNext "ctx" field. This will be propagated by the host as
	// the `reqCtx` parameter of FuncHandleResponse.
	//
	// To skip any next handler, the guest returns CtxNext `next=0`, or simply
	// uint64(0). In this case, FuncHandleResponse will not be called.
	FuncHandleRequest = "handle_request"

	// FuncHandleResponse is called by the host after processing the next
	// handler when the guest returns CtxNext `next=1` from FuncHandleRequest.
	//
	// The `reqCtx` parameter is a possibly zero CtxNext "ctx" field the host
	// the host propagated from FuncHandleRequest. This allows request
	// correlation for guests who need it.
	//
	// The `isError` parameter is one if there was a host error producing a
	// response. This allows guests to clean up any resources.
	//
	// By default, whether the next handler flushes the response prior to
	// returning is implementation-specific. If your handler needs to inspect
	// or manipulate the downstream response, enable FeatureBufferResponse via
	// FuncEnableFeatures prior to returning from FuncHandleRequest.
	// TODO: update
	FuncHandleResponse = "handle_response"

	// FuncGetMethod writes the method to memory if it isn't larger than
	// BufLimit. The result is its length in bytes. Ex. "GET"
	//
	// TODO: document on http-wasm-abi
	FuncGetMethod = "get_method"

	// FuncSetMethod overwrites the method with one read from memory.
	//
	// TODO: document on http-wasm-abi
	FuncSetMethod = "set_method"

	// FuncGetURI writes the URI to memory if it isn't larger than BufLimit.
	// The result is its length in bytes. Ex. "/v1.0/hi?name=panda"
	//
	// Note: The URI may include query parameters.
	//
	// TODO: update document on http-wasm-abi
	// See https://github.com/http-wasm/http-wasm-abi/blob/main/http_handler/http_handler.wit.md#get_uri
	FuncGetURI = "get_uri"

	// FuncSetURI overwrites the URI with one read from memory.
	//
	// Note: The URI may include query parameters.
	//
	// TODO: update document on http-wasm-abi
	// See https://github.com/http-wasm/http-wasm-abi/blob/main/http_handler/http_handler.wit.md#set_uri
	FuncSetURI = "set_uri"

	// FuncGetProtocolVersion writes the HTTP protocol version to memory if it
	// isn't larger than BufLimit. The result is its length in bytes.
	// Ex. "HTTP/1.1"
	//
	// See https://www.rfc-editor.org/rfc/rfc9110#name-protocol-version
	// TODO: document on http-wasm-abi
	FuncGetProtocolVersion = "get_protocol_version"

	// FuncGetHeaderNames writes all names for the given HeaderKind,
	// NUL-terminated, to memory if the encoded length isn't larger than
	// BufLimit. CountLen is returned regardless of whether memory was written.
	//
	// TODO: document on http-wasm-abi
	FuncGetHeaderNames = "get_header_names"

	// FuncGetHeaderValues writes all values of the given HeaderKind and name,
	// NUL-terminated, to memory if the encoded length isn't larger than
	// BufLimit. CountLen is returned regardless of whether memory was written.
	//
	// TODO: document on http-wasm-abi
	FuncGetHeaderValues = "get_header_values"

	// FuncSetHeaderValue overwrites all values of the given HeaderKind and name
	// with the input.
	//
	// TODO: document on http-wasm-abi
	FuncSetHeaderValue = "set_header_value"

	// FuncAddHeaderValue adds a single value for the given HeaderKind and
	// name.
	//
	// TODO: document on http-wasm-abi
	FuncAddHeaderValue = "add_header_value"

	// FuncRemoveHeader removes any values for the given HeaderKind and name.
	//
	// TODO: document on http-wasm-abi
	FuncRemoveHeader = "remove_header"

	// FuncReadBody reads up to BufLimit bytes remaining in the BodyKind body
	// into memory at offset `buf`. A zero BufLimit will panic.
	//
	// The result is EOFLen, indicating the count of bytes read and whether
	// there may be more available.
	//
	// Unlike `get_XXX` functions, this function is stateful, so repeated calls
	// reads what's remaining in the stream, as opposed to starting from zero.
	// Callers do not have to exhaust the stream until `EOF`.
	//
	// TODO: document on http-wasm-abi
	FuncReadBody = "read_body"

	// FuncWriteBody reads `buf_len` bytes at memory offset `buf` and writes
	// them to the pending BodyKind body.
	//
	// Unlike `set_XXX` functions, this function is stateful, so repeated calls
	// write to the current stream.
	//
	// TODO: document on http-wasm-abi
	FuncWriteBody = "write_body"

	// FuncGetStatusCode returns the status code produced by FuncNext. This
	// requires FeatureBufferResponse.
	//
	// To enable FeatureBufferResponse, FuncEnableFeatures prior to FuncNext.
	// Doing otherwise, or calling before FuncNext will panic.
	//
	// TODO: document on http-wasm-abi
	FuncGetStatusCode = "get_status_code"

	// FuncSetStatusCode overrides the status code. The default is 200.
	//
	// To use this function after FuncNext, set FeatureBufferResponse via
	// FuncEnableFeatures. Otherwise, this can be called when FuncNext wasn't.
	//
	// TODO: document on http-wasm-abi
	FuncSetStatusCode = "set_status_code"

	// FuncGetSourceAddr writes the SourceAddr to memory if it isn't larger than BufLimit.
	// The result is its length in bytes. Ex. "1.1.1.1:12345" or "[fe80::101e:2bdf:8bfb:b97e]:12345"
	//
	// TODO: document on http-wasm-abi
	FuncGetSourceAddr = "get_source_addr"
)