Skip to content

Latest commit

 

History

History
301 lines (198 loc) · 7.04 KB

http-wasm.md

File metadata and controls

301 lines (198 loc) · 7.04 KB
title
HttpWasm

Grain API for http-wasm ABI

Implements WASM foreign binding from ./http-wasm-abi.gr. Traefik plugin logic code can include HttpWasm to use native http-wasm functions, and register functions that will be called when http-wasm's handle_request or handle_response are called.

Types

Type declarations included in the HttpWasm module.

HttpWasm.Request

record Request {
  method: String,
  path: String,
  headers: List<String>,
  sourceAddr: String,
  protocolVersion: String,
}

Reguest is provided as argument to any functions provided to registerRequestHandler

HttpWasm.Response

record Response {
  headers: List<String>,
}

Response is provided as argument to any functions provided to registerResponseHandler

HttpWasm.RequestHandler

type RequestHandler = Request => Bool

HttpWasm.ResponseHandler

type ResponseHandler = Response => Void

HttpWasm.LogLevel

enum LogLevel {
  Debug,
  Info,
  Warn,
  Err,
}

See http-wasm ABI spec for log_level

HttpWasm.Features

enum Features {
  BufferRequest,
  BufferResponse,
  Trailers,
}

See http-wasm ABI spec for features

HttpWasm.HeaderKind

enum HeaderKind {
  RequestHeader,
  ResponseHeader,
}

See http-wasm ABI spec for header_kind

Values

Functions and constants included in the HttpWasm module.

HttpWasm.enableFeatures

enableFeatures : (features: List<Features>) => Void

See http-wasm ABI spec for HttpWasmAbi._log

"whether the next handler on the host flushes the response prior to returning is implementation-specific..."

HttpWasm.log

log : (level: LogLevel, msg: String) => Void

See http-wasm ABI spec for HttpWasmAbi._log

HttpWasm.getConfig

getConfig : () => String

Get middleware dynamic configuration exposed from Traefik as string containing unparsed JSON string

See http-wasm ABI spec for HttpWasmAbi._getConfig

HttpWasm.hostJson

hostJson : Result<Json.Json, Json.JsonParseError>

Grain helper function to parse JSON from Traefik, so not part of http-wasm ABI.

Middleware configuration exposed from Traefik via get_config, as "raw" Grain Json.Json types.

HttpWasm.configMap

configMap : Map.Map<String, String>

Grain helper function to parse JSON from Traefik, so not part of http-wasm ABI

Middleware configuration exposed from Traefik via get_config, as Grain Map type. This can be used like: Map.get("Headers.Foo", configMap)

HttpWasm.getConfigItem

getConfigItem : (name: String) => Option<String>

Grain helper function to parse JSON from Traefik, so not part of http-wasm ABI

Quick access to config data from plugin.gr code. For example:

let fooHeaderValue = getConfigItem("Headers.Foo")

HttpWasm.getMethod

getMethod : () => String

See http-wasm ABI spec for HttpWasmAbi._getMethod

HttpWasm.getUri

getUri : () => String

See http-wasm ABI spec for HttpWasmAbi._getUri

HttpWasm.getProtocolVersion

getProtocolVersion : () => String

See http-wasm ABI spec for HttpWasmAbi._getProtocolVersion

HttpWasm.getSourceAddr

getSourceAddr : () => String

See http-wasm ABI spec for HttpWasmAbi._getSourceAddr

HttpWasm.getHeaderNames

getHeaderNames : (headerKind: HeaderKind) => List<String>

See http-wasm ABI spec for HttpWasmAbi._getHeaderNames

HttpWasm.getHeaderValues

getHeaderValues : (headerKind: HeaderKind, name: String) => String

See http-wasm ABI spec for HttpWasmAbi._getHeaderValues

HttpWasm.addHeaderValue

addHeaderValue :
  (headerKind: HeaderKind, name: String, value: String) => Void

NOTE** plugin will panic if addHeaderValue() is called on existing header. Check getHeaderName() if header already exists before call addHeaderValue().

See http-wasm ABI spec for HttpWasmAbi._addHeaderValue

HttpWasm.setHeaderValue

setHeaderValue :
  (headerKind: HeaderKind, name: String, value: String) => Void

NOTE** plugin will panic if setHeaderValue() is called on non-existing header. Check getHeaderName() to make sure header exists before call setHeaderValue().

See http-wasm ABI spec for HttpWasmAbi._setHeaderValue

HttpWasm.removeHeader

removeHeader : (headerKind: HeaderKind, name: String) => Void

See http-wasm ABI spec for HttpWasmAbi._removeHeader

HttpWasm.getStatusCode

getStatusCode : () => Int32

Response Only

NOTE** will panic if status code has not be previously set.

See http-wasm ABI spec for HttpWasmAbi._getStatusCode

HttpWasm.registerRequestHandler

registerRequestHandler : (fn: RequestHandler) => Void

This is critical to how plugin.gr works.** The interface between handle_request and Grain Traefik Plugin code is one or more calls to registerRequestHandler. This module will use list of "registered handlers" when a call from host (Traefik) to handle_request is invoked.

All registered functions must return true or false to indicate whether HTTP processing should continue.

HttpWasm.registerResponseHandler

registerResponseHandler : (fn: ResponseHandler) => Void

HttpWasm.handle_request

handle_request : () => WasmI64

See http-wasm ABI spec for handle_request

HttpWasm.handle_response

handle_response : (high: WasmI32, low: WasmI32) => Void

See http-wasm ABI spec for handle_response

HttpWasm.stripNulls

stripNulls : (str: String) => String

Helper to remove C-like null-terminated strings that http-wasm returns.

Returns** String to the null-terminator

Traefik logging seems to ignore them. However Grain Number.parse() treats null-terminated string as invalid char.

HttpWasm.dumpCodePoints

dumpCodePoints : (str: String) => String

For debugging, dump strings as codepoints to see tailing non-printables