proxytest

README

Test framework for proxy-wasm-go-sdk

Using proxytest, you can test your extension with the official command:

go test ./...

This framework emulates the expected behavior of Envoyproxy, and you can test your extensions without running Envoy. For detail, see examples/*/main_test.go.

Note that we have not covered all the functionality, and the API is very likely to change in the future.

Documentation

Index

• Constants
• type EmulatorOption
  • func NewEmulatorOption() *EmulatorOption
  • func (o *EmulatorOption) WithPluginConfiguration(data []byte) *EmulatorOption
  • func (o *EmulatorOption) WithProperty(path []string, value []byte) *EmulatorOption
  • func (o *EmulatorOption) WithVMConfiguration(data []byte) *EmulatorOption
  • func (o *EmulatorOption) WithVMContext(context types.VMContext) *EmulatorOption
• type HostEmulator
  • func NewHostEmulator(opt *EmulatorOption) (host HostEmulator, reset func())
• type HttpCalloutAttribute
• type LocalHttpResponse
• type WasmVMContext
  • func NewWasmVMContext(wasm []byte) (WasmVMContext, error)

Constants

const (
	PluginContextID uint32 = 1 // TODO: support multiple pluginContext
)

Types

type EmulatorOption

type EmulatorOption struct {
	// contains filtered or unexported fields
}

EmulatorOption is an option that can be passed to NewHostEmulator.

func NewEmulatorOption

func NewEmulatorOption() *EmulatorOption

NewEmulatorOption creates a new EmulatorOption.

func (*EmulatorOption) WithPluginConfiguration

func (o *EmulatorOption) WithPluginConfiguration(data []byte) *EmulatorOption

WithPluginConfiguration sets the plugin configuration.

func (*EmulatorOption) WithProperty

func (o *EmulatorOption) WithProperty(path []string, value []byte) *EmulatorOption

WithProperty sets a property. If the property already exists, it will be overwritten.

func (*EmulatorOption) WithVMConfiguration

func (o *EmulatorOption) WithVMConfiguration(data []byte) *EmulatorOption

WithVMConfiguration sets the VM configuration.

func (*EmulatorOption) WithVMContext

func (o *EmulatorOption) WithVMContext(context types.VMContext) *EmulatorOption

WithVMContext sets the VMContext.

type HostEmulator

type HostEmulator interface {
	// StartVM executes types.VMContext.OnVMStart in the plugin.
	StartVM() types.OnVMStartStatus
	// StartPlugin executes types.PluginContext.OnPluginStart in the plugin.
	StartPlugin() types.OnPluginStartStatus
	// FinishVM executes types.PluginContext.OnPluginDone in the plugin.
	FinishVM() bool
	// GetCalloutAttributesFromContext returns the current HTTP callout attributes for the given HTTP context in the
	// host.
	GetCalloutAttributesFromContext(contextID uint32) []HttpCalloutAttribute
	// CallOnHttpCallResponse executes the callback for the HTTP call with ID calloutID in the plugin.
	CallOnHttpCallResponse(calloutID uint32, headers [][2]string, trailers [][2]string, body []byte)
	// GetCounterMetric returns the value for the counter in the host.
	GetCounterMetric(name string) (uint64, error)
	// GetGaugeMetric returns the value for the gauge in the host.
	GetGaugeMetric(name string) (uint64, error)
	// GetHistogramMetric returns the value for the histogram in the host.
	GetHistogramMetric(name string) (uint64, error)
	// GetTraceLogs returns the trace logs that have been collected in the host.
	GetTraceLogs() []string
	// GetDebugLogs returns the debug logs that have been collected in the host.
	GetDebugLogs() []string
	// GetInfoLogs returns the info logs that have been collected in the host.
	GetInfoLogs() []string
	// GetWarnLogs returns the warn logs that have been collected in the host.
	GetWarnLogs() []string
	// GetErrorLogs returns the error logs that have been collected in the host.
	GetErrorLogs() []string
	// GetCriticalLogs returns the critical logs that have been collected in the host.
	GetCriticalLogs() []string
	// GetTickPeriod returns the current tick period in the host.
	GetTickPeriod() uint32
	// Tick executes types.PluginContext.OnTick in the plugin.
	Tick()
	// GetQueueSize gets the current size of the queue in the host.
	GetQueueSize(queueID uint32) int
	// RegisterForeignFunction registers the foreign function in the host.
	RegisterForeignFunction(name string, f func([]byte) []byte)

	// InitializeConnection executes types.TcpContext.OnNewConnection in the plugin.
	InitializeConnection() (contextID uint32, action types.Action)
	// CallOnUpstreamData executes types.TcpContext.OnUpstreamData in the plugin.
	CallOnUpstreamData(contextID uint32, data []byte) types.Action
	// CallOnDownstreamData executes types.TcpContext.OnDownstreamData in the plugin.
	CallOnDownstreamData(contextID uint32, data []byte) types.Action
	// CloseUpstreamConnection executes types.TcpContext.OnUpstreamClose in the plugin.
	CloseUpstreamConnection(contextID uint32)
	// CloseDownstreamConnection executes types.TcpContext.OnDownstreamClose in the plugin.
	CloseDownstreamConnection(contextID uint32)
	// CompleteConnection executes types.TcpContext.OnStreamDone in the plugin.
	CompleteConnection(contextID uint32)

	// InitializeHttpContext executes types.PluginContext.NewHttpContext in the plugin.
	InitializeHttpContext() (contextID uint32)
	// CallOnResponseHeaders executes types.HttpContext.OnHttpResponseHeaders in the plugin.
	// The number of headers and endOfStream are passed to the plugin and the content of headers are visible in
	// the plugin for methods like proxywasm.GetHttpResponseHeaders.
	CallOnResponseHeaders(contextID uint32, headers [][2]string, endOfStream bool) types.Action
	// CallOnResponseBody executes types.HttpContext.OnHttpResponseBody in the plugin.
	// The number of bytes and endOfStream are passed to the plugin and the content of bytes are visible in the plugin
	// for methods like proxywasm.GetHttpResponseBody.
	CallOnResponseBody(contextID uint32, body []byte, endOfStream bool) types.Action
	// CallOnResponseTrailers executes types.HttpContext.OnHttpResponseTrailers in the plugin.
	// The number of trailers and endOfStream are passed to the plugin and the content of trailers are visible in the
	// plugin for methods like proxywasm.GetHttpResponseTrailers.
	CallOnResponseTrailers(contextID uint32, trailers [][2]string) types.Action
	// CallOnRequestHeaders executes types.HttpContext.OnHttpRequestHeaders in the plugin.
	// The number of headers and endOfStream are passed to the plugin and the content of headers are visible in the
	// plugin for methods like proxywasm.GetHttpRequestHeaders.
	CallOnRequestHeaders(contextID uint32, headers [][2]string, endOfStream bool) types.Action
	// CallOnRequestTrailers executes types.HttpContext.OnHttpRequestTrailers in the plugin.
	// The number of trailers and endOfStream are passed to the plugin and the content of trailers are visible in the
	// plugin for methods like proxywasm.GetHttpRequestTrailers.
	CallOnRequestTrailers(contextID uint32, trailers [][2]string) types.Action
	// CallOnRequestBody executes types.HttpContext.OnHttpRequestBody in the plugin.
	// The number of bytes and endOfStream are passed to the plugin and the content of bytes are visible in the plugin
	// for methods like proxywasm.GetHttpRequestBody.
	CallOnRequestBody(contextID uint32, body []byte, endOfStream bool) types.Action
	// CompleteHttpContext executes types.HttpContext.OnHttpStreamDone in the plugin.
	CompleteHttpContext(contextID uint32)
	// GetCurrentHttpStreamAction returns the current action for the HTTP stream with ID contextID in the host.
	// This is the return value of a previous lifecycle call in the plugin.
	GetCurrentHttpStreamAction(contextID uint32) types.Action
	// GetCurrentRequestHeaders returns the current request headers for the HTTP stream with ID contextID in the host.
	// This will reflect any mutations made by the plugin such as with proxywasm.AddHttpRequestHeader.
	GetCurrentRequestHeaders(contextID uint32) [][2]string
	// GetCurrentResponseHeaders returns the current response headers for the HTTP stream with ID contextID in the host.
	// This will reflect any mutations made by the plugin such as with proxywasm.AddHttpResponseHeader.
	GetCurrentResponseHeaders(contextID uint32) [][2]string
	// GetCurrentRequestBody returns the current request body for the HTTP stream with ID contextID in the host.
	// This will reflect any mutations made by th eplugin such as with proxywasm.AppendHttpRequestBody.
	GetCurrentRequestBody(contextID uint32) []byte
	// GetCurrentResponseBody returns the current response body for the HTTP stream with ID contextID in the host.
	// This will reflect any mutations made by the plugin such as with proxywasm.AppendHttpResponseBody.
	GetCurrentResponseBody(contextID uint32) []byte
	// GetSentLocalResponse returns the local response that has been sent for the HTTP stream with ID contextID in the
	// host. This contains the arguments passed to proxywasm.SendHttpResponse in the plugin. If
	// proxywasm.SendHttpResponse hasn't been invoked by the plugin, this will return nil.
	GetSentLocalResponse(contextID uint32) *LocalHttpResponse
	// GetProperty returns property data from the host, for a given path.
	GetProperty(path []string) ([]byte, error)
	// SetProperty sets property data on the host, for a given path.
	SetProperty(path []string, data []byte) error
}

HostEmulator implements the host side of proxy-wasm. Methods on HostEmulator will either invoke methods in the plugin or return state about the host itself, reflecting any changes from previous plugin invocations.

func NewHostEmulator

func NewHostEmulator(opt *EmulatorOption) (host HostEmulator, reset func())

NewHostEmulator returns a new HostEmulator that can be used to test a plugin. Plugin tests will often involve calling methods on HostEmulator to invoke methods in the plugin while checking the state within the host after plugin execution.

type HttpCalloutAttribute

type HttpCalloutAttribute struct {
	CalloutID uint32
	Upstream  string
	Headers   [][2]string
	Trailers  [][2]string
	Body      []byte
}

type LocalHttpResponse

type LocalHttpResponse struct {
	StatusCode       uint32
	StatusCodeDetail string
	Data             []byte
	Headers          [][2]string
	GRPCStatus       int32
}

type WasmVMContext

type WasmVMContext interface {
	types.VMContext
	io.Closer
}

WasmVMContext is a VMContext that delegates execution to a compiled wasm binary.

func NewWasmVMContext

func NewWasmVMContext(wasm []byte) (WasmVMContext, error)

NewWasmVMContext returns a types.VMContext that delegates plugin invocations to the provided compiled wasm binary. proxytest can be run with a compiled wasm binary by passing this to proxytest.WithVMContext.

Running proxytest with the compiled wasm binary helps to ensure that the plugin will run when actually compiled with TinyGo, however stack traces and other debug features will be much worse. It is recommended to run unit tests both with Go and with wasm. Tests will run much faster under Go for quicker development cycles, and the wasm runner can confirm the behavior matches when actually compiled.

For example, this snippet allows determining the types.VMContext based on a test case flag.

var vm types.VMContext
switch runner {
case "go":
	vm = &vmContext{}
case "wasm":
	wasm, err := os.ReadFile("plugin.wasm")
	if err != nil {
		t.Skip("wasm not found")
	}
	v, err := proxytest.NewWasmVMContext(wasm)
	require.NoError(t, err)
	vm = v
}

Note: Currently only HTTP plugins are supported.