api

package

v1.0.5 Latest Latest Go to latest Published: Jun 27, 2023 License: Apache-2.0 Imports: 0 Imported by: 12

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/banzaicloud/proxy-wasm-go-host

Links

Open Source Insights

Documentation ¶

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type ABIContext ¶

type ABIContext interface {
	Name() string
	GetExports() Exports
	GetImports() ImportsHandler
	SetImports(imports ImportsHandler)
	GetInstance() WasmInstance
	SetInstance(instance WasmInstance)
}

type Action ¶

type Action int32

const (
	ActionContinue Action = iota
	ActionPause
)

type BufferType ¶

type BufferType int32

const (
	BufferTypeHttpRequestBody BufferType = iota
	BufferTypeHttpResponseBody
	BufferTypeDownstreamData
	BufferTypeUpstreamData
	BufferTypeHttpCallResponseBody
	BufferTypeGrpcReceiveBuffer
	BufferTypeVmConfiguration
	BufferTypePluginConfiguration
	BufferTypeCallData
	BufferTypeMax BufferType = 8
)

type ContextHandler ¶

type ContextHandler interface {
	Name() string

	GetImports() ImportsHandler
	SetImports(imports ImportsHandler)

	GetExports() Exports

	GetInstance() WasmInstance
	SetInstance(instance WasmInstance)
}

type ContextType ¶

type ContextType int32

const (
	ContextTypeHttpContext ContextType = iota
	ContextTypeStreamContext
)

type Exports ¶

type Exports interface {
	// Configuration
	ProxyOnVmStart(rootContextID int32, vmConfigurationSize int32) (bool, error)
	ProxyOnConfigure(rootContextID int32, pluginConfigurationSize int32) (bool, error)

	// Misc
	ProxyOnLog(contextID int32) error
	ProxyOnTick(rootContextID int32) error
	ProxyOnHttpCallResponse(contextID int32, tokenID int32, headerCount int32, bodySize int32, trailerCount int32) error
	ProxyOnQueueReady(rootContextID int32, queueID int32) error

	// Context
	ProxyOnContextCreate(contextID int32, rootContextID int32) error
	ProxyOnDone(contextID int32) (bool, error)
	ProxyOnDelete(contextID int32) error

	// L4
	ProxyOnNewConnection(contextID int32) (Action, error)
	ProxyOnDownstreamData(contextID int32, dataSize int32, endOfStream int32) (Action, error)
	ProxyOnDownstreamConnectionClose(contextID int32, peerType int32) error
	ProxyOnUpstreamData(contextID int32, dataSize int32, endOfStream int32) (Action, error)
	ProxyOnUpstreamConnectionClose(contextID int32, peerType int32) error

	// gRPC
	ProxyOnGrpcClose(contextID int32, tokenID int32, statusCode int32) error
	ProxyOnGrpcReceiveInitialMetadata(contextID int32, tokenID int32, headerCount int32) error
	ProxyOnGrpcReceiveTrailingMetadata(contextID int32, tokenID int32, trailerCount int32) error
	ProxyOnGrpcReceive(contextID int32, tokenID int32, responseSize int32) error

	// HTTP request
	ProxyOnRequestBody(contextID int32, bodySize int32, endOfStream int32) (Action, error)
	ProxyOnRequestHeaders(contextID int32, headerCount int32, endOfStream int32) (Action, error)
	ProxyOnRequestTrailers(contextID int32, trailerCount int32) (Action, error)

	// HTTP response
	ProxyOnResponseBody(contextID int32, bodySize int32, endOfStream int32) (Action, error)
	ProxyOnResponseHeaders(contextID int32, headerCount int32, endOfStream int32) (Action, error)
	ProxyOnResponseTrailers(contextID int32, trailerCount int32) (Action, error)
}

type HeaderMap ¶

type HeaderMap interface {
	// Get value of key
	// If multiple values associated with this key, first one will be returned.
	Get(key string) (string, bool)

	// Set key-value pair in header map, the previous pair will be replaced if exists
	Set(key, value string)

	// Add value for given key.
	// Multiple headers with the same key may be added with this function.
	// Use Set for setting a single header for the given key.
	Add(key, value string)

	// Del delete pair of specified key
	Del(key string)

	// Range calls f sequentially for each key and value present in the map.
	// If f returns false, range stops the iteration.
	Range(f func(key, value string) bool)

	// Clone used to deep copy header's map
	Clone() HeaderMap

	// ByteSize return size of HeaderMap
	ByteSize() uint64
}

HeaderMap is a interface to provide operation facade with user-value headers.

type Imports ¶

type Imports interface {
	// Logging
	ProxyLog(logLevel int32, messagePtr int32, messageSize int32) int32
	ProxyGetLogLevel(logLevelPtr int32) int32

	// Timer (will be set for the root context, e.g. onStart, onTick).
	ProxySetTickPeriodMilliseconds(tickPeriodMillisecondsPtr int32) int32
	// Time
	ProxyGetCurrentTimeNanoseconds(resultUint64Ptr int32) int32

	// Results status details for any previous ABI call and onGrpcClose.
	ProxyGetStatus(statusCodePtr int32, returnStatusDetailPtr int32, returnStatusDetailSize int32) int32

	// System
	ProxySetEffectiveContext(contextID int32) int32
	ProxyDone() int32
	ProxyCallForeignFunction(funcNamePtr int32, funcNameSize int32, paramPtr int32, paramSize int32, returnDataPtr int32, returnSize int32) int32

	// State accessors
	ProxyGetProperty(keyPtr int32, keySize int32, returnValuePtr int32, returnValueSize int32) int32
	ProxySetProperty(keyPtr int32, keySize int32, valuePtr int32, valueSize int32) int32

	// Continue/Close/Reply
	ProxyContinueStream(streamType int32) int32
	ProxyCloseStream(streamType int32) int32
	ProxySendLocalResponse(statusCode int32, statusCodeDetailsPtr int32, statusCodeDetailsSize int32, bodyPtr int32, bodySize int32, headersPtr int32, headersSize int32, grpcStatus int32) int32

	// Headers/Trailers/Metadata Maps
	ProxyAddHeaderMapValue(mapType int32, keyPtr int32, keySize int32, valuePtr int32, valueSize int32) int32
	ProxyGetHeaderMapValue(mapType MapType, keyPtr int32, keySize int32, returnValuePtr int32, returnValueSize int32) int32
	ProxyGetHeaderMapPairs(mapType MapType, returnDataPtr int32, returnDataSize int32) int32
	ProxySetHeaderMapPairs(mapType MapType, dataPtr int32, dataSize int32) int32
	ProxyReplaceHeaderMapValue(mapType int32, keyPtr int32, keySize int32, valuePtr int32, valueSize int32) int32
	ProxyRemoveHeaderMapValue(mapType int32, keyPtr int32, keySize int32) int32
	ProxyGetHeaderMapSize(mapType int32, sizePtr int32) int32

	// Shared data
	// Returns: Ok, NotFound
	ProxyGetSharedData(keyPtr int32, keySize int32, returnValuePtr int32, returnValueSize int32, returnCasPtr int32) int32
	// If cas != 0 and cas != the current cas for 'key' return false, otherwise set
	// the value and return true.
	// Returns: Ok, CasMismatch
	ProxySetSharedData(keyPtr int32, keySize int32, valuePtr int32, valueSize int32, cas int32) int32

	// Shared queue
	// Note: Registering the same queue_name will overwrite the old registration
	// while preseving any pending data. Consequently it should typically be
	// followed by a call to proxy_dequeue_shared_queue. Returns: Ok
	ProxyRegisterSharedQueue(queueNamePtr int32, queueNameSize int32, tokenIDPtr int32) int32
	// Returns: Ok, NotFound
	ProxyResolveSharedQueue(vmIDPtr int32, vmIDSize int32, queueNamePtr int32, queueNameSize int32, tokenIDPtr int32) int32
	// Returns false if the queue was not found and the data was not enqueued.
	ProxyEnqueueSharedQueue(tokenID int32, dataPtr int32, dataSize int32) int32
	// Returns Ok, Empty, NotFound (token not registered).
	ProxyDequeueSharedQueue(tokenID int32, returnValuePtr int32, returnValueSize int32) int32

	// Buffer
	ProxyGetBufferBytes(bufferType int32, start int32, length int32, returnDataPtr int32, returnDataSize int32) int32
	ProxyGetBufferStatus(bufferType int32, lengthPtr int32, flagsPtr int32) int32
	ProxySetBufferBytes(bufferType int32, start int32, length int32, dataPtr int32, dataSize int32) int32

	// Metrics
	ProxyDefineMetric(metricType int32, namePtr int32, nameSize int32, returnMetricId int32) int32
	ProxyIncrementMetric(metricId int32, offset int64) int32
	ProxyRecordMetric(metricId int32, value int64) int32
	ProxyGetMetric(metricId int32, resultUint64Ptr int32) int32

	// HTTP
	ProxyHttpCall(uriPtr int32, uriSize int32, headerPairsPtr int32, headerPairsSize int32, bodyPtr int32, bodySize int32, trailerPairsPtr int32, trailerPairsSize int32, timeoutMilliseconds int32, calloutIDPtr int32) int32

	// gRPC
	ProxyGrpcCall(grpcServiceData int32, grpcServiceSize int32, serviceNameData int32, serviceNameSize int32, methodName int32, methodSize int32, initialMetadataPtr int32, initialMetadataSize int32, grpcMessage int32, grpcMessageSize int32, timeoutMilliseconds int32, returnCalloutID int32) int32
	ProxyGrpcStream(grpcServiceData int32, grpcServiceSize int32, serviceNameData int32, serviceNameSize int32, methodName int32, methodSize int32, initialMetadataPtr int32, initialMetadataSize int32, returnStreamID int32) int32
	ProxyGrpcSend(streamID int32, messagePtr int32, messageSize int32, endOfStream int32) int32
	ProxyGrpcCancel(calloutID int32) int32
	ProxyGrpcClose(calloutID int32) int32
}

type ImportsHandler ¶

type ImportsHandler interface {
	// Logging
	Log(level LogLevel, msg string) WasmResult
	GetLogLevel() LogLevel

	// System
	GetRootContextID() int32
	SetEffectiveContextID(contextID int32) WasmResult
	Done() WasmResult

	// Time
	SetTickPeriodMilliseconds(tickPeriodMilliseconds int32) WasmResult
	GetCurrentTimeNanoseconds() (int32, WasmResult)

	GetStatus() (int32, string, WasmResult)

	// Configuration
	GetVmConfig() IoBuffer
	GetPluginConfig() IoBuffer

	// Metric
	DefineMetric(metricType MetricType, name string) (int32, WasmResult)
	IncrementMetric(metricID int32, offset int64) WasmResult
	RecordMetric(metricID int32, value int64) WasmResult
	GetMetric(metricID int32) (int64, WasmResult)

	// State accessors
	GetProperty(key string) (string, WasmResult)
	SetProperty(key string, value string) WasmResult

	// L4
	GetDownStreamData() IoBuffer
	GetUpstreamData() IoBuffer
	ResumeDownstream() WasmResult
	ResumeUpstream() WasmResult
	CloseDownstream() WasmResult
	CloseUpstream() WasmResult

	// HTTP request
	GetHttpRequestHeader() HeaderMap
	GetHttpRequestBody() IoBuffer
	GetHttpRequestTrailer() HeaderMap
	ResumeHttpRequest() WasmResult
	CloseHttpRequest() WasmResult

	// HTTP response
	GetHttpResponseHeader() HeaderMap
	GetHttpResponseBody() IoBuffer
	GetHttpResponseTrailer() HeaderMap
	ResumeHttpResponse() WasmResult
	CloseHttpResponse() WasmResult
	SendHttpResp(respCode int32, respCodeDetail IoBuffer, respBody IoBuffer, additionalHeaderMap HeaderMap, grpcCode int32) WasmResult

	// HTTP call out
	HttpCall(url string, headers HeaderMap, body IoBuffer, trailer HeaderMap, timeoutMilliseconds int32) (int32, WasmResult)
	GetHttpCallResponseHeaders() HeaderMap
	GetHttpCallResponseBody() IoBuffer
	GetHttpCallResponseTrailer() HeaderMap

	// gRPC
	OpenGrpcStream(grpcService string, serviceName string, method string) (int32, WasmResult)
	SendGrpcCallMsg(token int32, data IoBuffer, endOfStream int32) WasmResult
	CancelGrpcCall(token int32) WasmResult
	CloseGrpcCall(token int32) WasmResult

	GrpcCall(grpcService string, serviceName string, method string, data IoBuffer, timeoutMilliseconds int32) (int32, WasmResult)
	GetGrpcReceiveInitialMetaData() HeaderMap
	GetGrpcReceiveBuffer() IoBuffer
	GetGrpcReceiveTrailerMetaData() HeaderMap

	// foreign
	CallForeignFunction(funcName string, param []byte) ([]byte, WasmResult)
	GetFuncCallData() IoBuffer

	// Shared data
	GetSharedData(key string) (string, uint32, WasmResult)
	SetSharedData(key string, value string, cas uint32) WasmResult

	// Shared queue
	RegisterSharedQueue(queueName string) (uint32, WasmResult)
	ResolveSharedQueue(queueName string) (uint32, WasmResult)
	EnqueueSharedQueue(queueID uint32, data string) WasmResult
	DequeueSharedQueue(queueID uint32) (string, WasmResult)

	// for golang host environment
	// Wait until async call return, eg. sync http call in golang
	Wait() Action
}

type IoBuffer ¶

type IoBuffer interface {
	// Len returns the number of bytes of the unread portion of the buffer;
	// b.Len() == len(b.Bytes()).
	Len() int

	// Bytes returns all bytes from buffer, without draining any buffered data.
	// It can be used to get fixed-length content, such as headers, body.
	// Note: do not change content in return bytes, use write instead
	Bytes() []byte

	// Read reads the next len(p) bytes from the buffer or until the buffer
	// is drained. The return value n is the number of bytes read. If the
	// buffer has no data to return, err is io.EOF (unless len(p) is zero);
	// otherwise it is nil.
	Read(p []byte) (n int, err error)

	// Write appends the contents of p to the buffer, growing the buffer as
	// needed. The return value n is the length of p; err is always nil. If the
	// buffer becomes too large, Write will panic with ErrTooLarge.
	Write(p []byte) (n int, err error)

	// Truncate discards all but the first n unread bytes from the buffer
	// but continues to use the same allocated storage.
	// It panics if n is negative or greater than the length of the buffer.
	Truncate(n int)

	// Reset resets the buffer to be empty,
	// but it retains the underlying storage for use by future writes.
	// Reset is the same as Truncate(0).
	Reset()
}

type KVStore ¶

type KVStore interface {
	HeaderMap
	SetCAS(key, value string, cas bool) bool
	DelCAS(key string, cas bool) bool
}

type LogLevel ¶

type LogLevel int32

const (
	LogLevelTrace LogLevel = iota
	LogLevelDebug
	LogLevelInfo
	LogLevelWarning
	LogLevelError
	LogLevelCritical
)

type MapType ¶

type MapType = int32

const (
	MapTypeHttpRequestHeaders MapType = iota
	MapTypeHttpRequestTrailers
	MapTypeHttpResponseHeaders
	MapTypeHttpResponseTrailers
	MapTypeGrpcReceiveInitialMetadata
	MapTypeGrpcReceiveTrailingMetadata
	MapTypeHttpCallResponseHeaders
	MapTypeHttpCallResponseTrailers
	MapTypeMax MapType = 7
)

type MetricType ¶

type MetricType int32

const (
	MetricTypeCounter MetricType = iota
	MetricTypeGauge
	MetricTypeHistogram
	MetricTypeMax MetricType = 2
)

type PeerType ¶

type PeerType int32

const (
	PeerTypeUnknown PeerType = iota
	PeerTypeLocal            // Close initiated by the proxy.
	PeerTypeRemote           // Close initiated by the peer.
)

type Result ¶

type Result int32

const (
	ResultOk Result = iota
	ResultEmpty
	ResultNotFound
	ResultNotAllowed
	ResultBadArgument
	ResultInvalidMemoryAccess
	ResultInvalidOperation
	ResultCompareAndSwapMismatch
	ResultUnimplemented Result = 12
)

type StreamType ¶

type StreamType int32

const (
	StreamTypeHttpRequest StreamType = iota
	StreamTypeHttpResponse
	StreamTypeDownstream
	StreamTypeUpstream
)

type WasmFunction ¶

type WasmFunction interface {
	// Call invokes the wasm func
	Call(args ...interface{}) (interface{}, error)
}

WasmFunction is the func exported by wasm module

type WasmInstance ¶

type WasmInstance interface {
	// Start starts the wasm instance
	Start() error

	// Stop stops the wasm instance
	Stop()

	// GetExportsFunc returns the exported func of the wasm instance
	GetExportsFunc(funcName string) (WasmFunction, error)

	// GetExportsMem returns the exported mem of the wasm instance
	GetExportsMem(memName string) ([]byte, error)

	// GetMemory returns wasm mem bytes from specified addr and size
	GetMemory(addr uint64, size uint64) ([]byte, error)

	// PutMemory sets wasm mem bytes to specified addr and size
	PutMemory(addr uint64, size uint64, content []byte) error

	// GetByte returns one wasm byte from specified addr
	GetByte(addr uint64) (byte, error)

	// PutByte sets one wasms bytes to specified addr
	PutByte(addr uint64, b byte) error

	// GetUint32 returns uint32 from specified addr
	GetUint32(addr uint64) (uint32, error)

	// PutUint32 set uint32 to specified addr
	PutUint32(addr uint64, value uint32) error

	// Malloc allocates size of mem from wasm default memory
	Malloc(size int32) (uint64, error)

	// GetData returns user-defined data
	GetData() interface{}

	// SetData sets user-defined data into the wasm instance
	SetData(data interface{})

	// Acquire increases the ref count of the wasm instance
	Acquire() bool

	// Release decreases the ref count of the wasm instance
	Release()

	// Lock gets the exclusive ownership of the wasm instance
	// and sets the user-defined data
	Lock(data interface{})

	// Unlock releases the exclusive ownership of the wasm instance
	// and sets the users-defined data to nil
	Unlock()

	// GetModule returns the wasm module of current instance
	GetModule() WasmModule

	// HandlerError processes the encountered err
	HandleError(err error)
}

WasmInstance represents the wasm instance

type WasmModule ¶

type WasmModule interface {
	// Init got called when creating a new wasm module
	Init()

	// NewInstance instantiates and returns a new wasm instance
	NewInstance() (WasmInstance, error)

	// GetABINameList returns the abi name list exported by wasm module
	//
	// Note: These are the only valid choices for WasmInstance.RegisterImports.
	GetABINameList() []string
}

WasmModule represents the wasm module

type WasmResult ¶

type WasmResult int32

const (
	WasmResultOk                   WasmResult = iota
	WasmResultNotFound                        // The result could not be found, e.g. a provided key did not appear in a table.
	WasmResultBadArgument                     // An argument was bad, e.g. did not conform to the required range.
	WasmResultSerializationFailure            // A protobuf could not be serialized.
	WasmResultParseFailure                    // A protobuf could not be parsed.
	WasmResultBadExpression                   // A provided expression (e.g. "foo.bar") was illegal or unrecognized.
	WasmResultInvalidMemoryAccess             // A provided memory range was not legal.
	WasmResultEmpty                           // Data was requested from an empty container.
	WasmResultCasMismatch                     // The provided CAS did not match that of the stored data.
	WasmResultResultMismatch                  // Returned result was unexpected, e.g. of the incorrect size.
	WasmResultInternalFailure                 // Internal failure: trying check logs of the surrounding system.
	WasmResultBrokenConnection                // The connection/stream/pipe was broken/closed unexpectedly.
	WasmResultUnimplemented                   // Feature not implemented.
)

func (WasmResult) Int32 ¶

func (wasmResult WasmResult) Int32() int32

type WasmVM ¶

type WasmVM interface {
	// Name returns the name of wasm vm(engine)
	Name() string

	// Init got called when creating a new wasm vm(engine)
	Init()

	// NewModule compiles the 'guest' into a wasm module
	NewModule(guest []byte) (WasmModule, error)

	// Close avoids leaking resources such as memory-mapped files.
	Close() error
}

WasmVM represents the wasm vm(engine)

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Documentation ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

type ABIContext ¶

type Action ¶

type BufferType ¶

type ContextHandler ¶

type ContextType ¶

type Exports ¶

type HeaderMap ¶

type Imports ¶

type ImportsHandler ¶

type IoBuffer ¶

type KVStore ¶

type LogLevel ¶

type MapType ¶

type MetricType ¶

type PeerType ¶

type Result ¶

type StreamType ¶

type WasmFunction ¶

type WasmInstance ¶

type WasmModule ¶

type WasmResult ¶

func (WasmResult) Int32 ¶

type WasmVM ¶

Source Files ¶