Documentation
¶
Overview ¶
Package extensions provides a sandboxed Lua scripting environment for extending the functionality of the proxy. It allows for the interception and modification of HTTP/S traffic.
Index ¶
- func ExtensionWithLogHandler(handler func(log ExtensionLog) error) func(*Runtime) error
- func FunctionIndex(functions map[string]lua.Function) func(l *lua.State) int
- func GetExtensionID(l *lua.State) uuid.UUID
- func GoValue(l *lua.State, index int) any
- func ParseTable(l *lua.State, index int, converter func(*lua.State, int) any) any
- func PrintValue(l *lua.State, index int) any
- func RegisterCookieType(extension *Runtime)
- func RegisterCustomPrint(extension *Runtime)
- func RegisterHeaderType(extension *Runtime)
- func RegisterRegexType(extension *Runtime)
- func RegisterRequestBuilderType(extension *Runtime)
- func RegisterRequestType(extension *Runtime)
- func RegisterResponseType(extension *Runtime)
- func RegisterScopeType(extension *Runtime)
- func RegisterType(l *lua.State, name string, functions map[string]lua.Function, ...)
- func RegisterURLType(extension *Runtime)
- type ExtensionLog
- type ProxyService
- type RequestBuilder
- type Runtime
- func (extension *Runtime) CallFunction(name string, args ...any) error
- func (extension *Runtime) CallRequestHandler(req *http.Request) error
- func (extension *Runtime) CallResponseHandler(res *http.Response) error
- func (extension *Runtime) CheckGlobalFlag(name string) bool
- func (extension *Runtime) CheckGlobalFunction(functionName string) bool
- func (extension *Runtime) ExecuteLua(code string) error
- func (extension *Runtime) GetGlobal(name string) any
- func (extension *Runtime) GetGlobalString(name string) (string, error)
- func (extension *Runtime) PrepareState(proxy ProxyService, options []func(*Runtime) error) error
- func (extension *Runtime) ShouldInterceptRequest(req *http.Request) (bool, error)
- func (extension *Runtime) ShouldInterceptResponse(res *http.Response) (bool, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ExtensionWithLogHandler ¶
func ExtensionWithLogHandler(handler func(log ExtensionLog) error) func(*Runtime) error
ExtensionWithLogHandler returns an option function to set a log handler on a LuaExtension. This handler is called whenever the extension's custom `print` function is used.
func FunctionIndex ¶
FunctionIndex returns a Lua function that acts as an `__index` metamethod. It looks up a field name in the provided functions map and pushes the corresponding function onto the stack if found.
func GetExtensionID ¶
GetExtensionID retrieves and parses the "extension_id" global variable from the Lua state. It returns the parsed UUID if the global exists and is a valid UUID string. Returns uuid.Nil if the global is missing, not a string, or an invalid UUID.
func GoValue ¶
GoValue converts a value at a specific stack index in the Lua state to its Go equivalent. It handles primitives (nil, boolean, number, string), tables (recursively via ParseTable), and UserData. For unsupported types (like functions or threads), it returns nil.
func ParseTable ¶
ParseTable converts a Lua table at the given index into a Go slice or map. If the table is a sequence (integer keys 1..N), it returns []any. Otherwise, it returns map[string]any, converting all keys to strings. The converter function allows custom value transformation; if nil, GoValue is used.
func RegisterCookieType ¶
func RegisterCookieType(extension *Runtime)
RegisterCookieType registers the `http.Cookie` type and its methods with the Lua state. This allows Lua scripts to read and modify HTTP cookies.
func RegisterCustomPrint ¶
func RegisterCustomPrint(extension *Runtime)
RegisterCustomPrint overrides the default Lua `print` function. The new function captures the output and sends it to the extension's log, making it visible in the Marasi UI.
func RegisterHeaderType ¶
func RegisterHeaderType(extension *Runtime)
RegisterHeaderType registers the `http.Header` type and its methods with the Lua state. This allows Lua scripts to read and modify HTTP headers.
func RegisterRegexType ¶
func RegisterRegexType(extension *Runtime)
RegisterRegexType registers the `regexp.Regexp` type and its methods with the Lua state. This allows Lua scripts to perform regular expression matching, searching, and replacement.
func RegisterRequestBuilderType ¶
func RegisterRequestBuilderType(extension *Runtime)
RegisterRequestBuilderType registers the `RequestBuilder` type and its methods with the Lua state. This allows Lua scripts to construct and send new HTTP requests from within an extension.
func RegisterRequestType ¶
func RegisterRequestType(extension *Runtime)
RegisterRequestType registers the `http.Request` type and its methods with the Lua state. This allows Lua scripts to read and modify incoming HTTP requests.
func RegisterResponseType ¶
func RegisterResponseType(extension *Runtime)
RegisterResponseType registers the `http.Response` type and its methods with the Lua state. This allows Lua scripts to read and modify outgoing HTTP responses.
func RegisterScopeType ¶
func RegisterScopeType(extension *Runtime)
RegisterScopeType registers the `compass.Scope` type and its methods with the Lua state. This allows Lua scripts to interact with the proxy's scope, adding, removing, and checking rules.
func RegisterType ¶
func RegisterType(l *lua.State, name string, functions map[string]lua.Function, toString func(l *lua.State) int)
RegisterType creates a new metatable in the Lua state and associates it with a name. It registers a set of functions as methods for the type and a `__tostring` metamethod. This is a generic helper for exposing Go types to Lua.
func RegisterURLType ¶
func RegisterURLType(extension *Runtime)
RegisterURLType registers the `url.URL` type and its methods with the Lua state. This allows direct modification of the request URL without needing to re-set it.
Types ¶
type ExtensionLog ¶
type ExtensionLog struct {
// Time is the timestamp when the log entry was created.
Time time.Time
// Text is the content of the log message.
Text string
}
ExtensionLog represents a single log entry generated by a Lua extension.
type ProxyService ¶
type ProxyService interface {
// GetConfigDir returns the path to the proxy's configuration directory.
GetConfigDir() (string, error)
// GetScope returns the proxy's current scope.
GetScope() (*compass.Scope, error)
// GetClient returns an HTTP client that can be used to make requests.
GetClient() (*http.Client, error)
// WriteLog writes a message to the proxy's log.
WriteLog(level string, message string, options ...func(log *domain.Log) error) error
// GetExtensionRepo returns the extension repository.
GetExtensionRepo() (domain.ExtensionRepository, error)
// GetTrafficRepo returns the traffic repository
GetTrafficRepo() (domain.TrafficRepository, error)
}
ProxyService defines the interface that extensions use to interact with the core proxy. It provides a limited set of methods to ensure extensions cannot access or modify the proxy's internal state in unintended ways.
type RequestBuilder ¶
type RequestBuilder struct {
// contains filtered or unexported fields
}
RequestBuilder provides a fluent interface for constructing and sending HTTP requests from within a Lua environment. It allows for method, URL, body, headers, and cookies to be set before sending the request.
func NewRequestBuilder ¶
func NewRequestBuilder(client *http.Client) *RequestBuilder
NewRequestBuilder creates and returns a new RequestBuilder instance. It is initialized with an HTTP client that will be used to send the request.
type Runtime ¶
type Runtime struct {
// Data is the database model for the extension.
Data *domain.Extension
// LuaState is the isolated Lua execution environment.
LuaState *lua.State
// Mu is a mutex to ensure thread-safe access to the Lua state.
Mu sync.Mutex
// Logs is a slice of log entries generated by the extension.
Logs []ExtensionLog
// OnLog is a callback function to handle new log entries.
OnLog func(ExtensionLog) error `json:"-"`
}
Runtime represents a self-contained Lua extension environment. It holds the extension's data, its Lua state, logs, and provides thread-safe methods for interacting with the Lua runtime.
func (*Runtime) CallFunction ¶
CallFunction executes a global Lua function by name with optional arguments. It is used for lifecycle events or simple triggers. If the function does not exist, it returns nil. If the function execution fails, it returns a formatted error.
func (*Runtime) CallRequestHandler ¶
CallRequestHandler calls the `processRequest` function in the Lua script, passing the HTTP request to be processed by the extension.
func (*Runtime) CallResponseHandler ¶
CallResponseHandler calls the `processResponse` function in the Lua script, passing the HTTP response to be processed by the extension.
func (*Runtime) CheckGlobalFlag ¶
CheckGlobalFlag checks for the existence and value of a boolean global variable in the Lua state. It returns true if the global exists and is set to true, otherwise false.
func (*Runtime) CheckGlobalFunction ¶
CheckGlobalFunction checks if a global variable of a given name exists and is a function.
func (*Runtime) ExecuteLua ¶
ExecuteLua executes an arbitrary string of Lua code within the extension's sandboxed state. Access is mutex-locked to ensure thread safety.
func (*Runtime) GetGlobalString ¶
GetGlobalString returns the string value of a global variable from the Lua state.
func (*Runtime) PrepareState ¶
func (extension *Runtime) PrepareState(proxy ProxyService, options []func(*Runtime) error) error
PrepareState initializes the Lua execution environment for the extension. It creates a new Lua state, opens a safe subset of standard libraries, registers all custom Go types and functions, and executes the extension's script. It also disables potentially dangerous Lua functions like `dofile` and `loadfile` to sandbox the extension.
func (*Runtime) ShouldInterceptRequest ¶
ShouldInterceptRequest calls the `interceptRequest` function in the Lua script to determine if the given HTTP request should be intercepted.
Source Files