sdk

Documentation

Overview

Package sdk provides the plugin authoring API for prox.

Plugins are external executables that extend prox with custom logic. The SDK handles all transport details — plugin authors just register callbacks and call Run().

Index

• type ConfigureHandler
• type ConnRequest
• type ConnResponse
  • func AcceptConn() *ConnResponse
  • func RejectConn() *ConnResponse
• type ConnectHandler
• type Envelope
• type HookType
• type Option
  • func WithHeader(key, value string) Option
• type Plugin
  • func New() *Plugin
  • func (p *Plugin) OnConfigure(h ConfigureHandler)
  • func (p *Plugin) OnConnect(h ConnectHandler)
  • func (p *Plugin) OnRequest(h RequestHandler)
  • func (p *Plugin) OnResponse(h ResponseHandler)
  • func (p *Plugin) Run()
  • func (p *Plugin) SetActionGroupedTargets(action string, groups map[string][]string)
  • func (p *Plugin) SetActionTargets(action string, targets []string)
  • func (p *Plugin) SetGroupedTargets(routeID string, groups map[string][]string)
  • func (p *Plugin) SetTargets(routeID string, targets []string)
• type Request
  • func (r *Request) Header(key string) string
  • func (r *Request) QueryParam(key string) string
• type RequestHandler
• type Response
  • func Allow(opts ...Option) *Response
  • func Deny(status int, body string, opts ...Option) *Response
  • func Drop() *Response
• type ResponseHandler
• type ResponseMod
  • func ModifyResponse(opts ...ResponseOption) *ResponseMod
  • func NoResponseMod() *ResponseMod
• type ResponseOption
  • func RemoveResponseHeader(key string) ResponseOption
  • func WithResponseHeader(key, value string) ResponseOption
  • func WithResponseStatus(status int) ResponseOption
• type Route
• type UpstreamResponse

Types

type ConfigureHandler

type ConfigureHandler func(route Route)

ConfigureHandler is called when the plugin receives route configuration.

type ConnRequest

type ConnRequest struct {
	RouteID     string `msgpack:"r" json:"route_id"`
	Domain      string `msgpack:"d" json:"domain"`
	RemoteAddr  string `msgpack:"a" json:"remote_addr"`
	MatchDomain string `msgpack:"md,omitempty" json:"match_domain,omitempty"`
	MatchGlob   string `msgpack:"mg,omitempty" json:"match_glob,omitempty"`
}

ConnRequest carries L4 connection context for on_connect hooks.

type ConnResponse

type ConnResponse struct {
	Allow bool `msgpack:"ok" json:"allow"`
}

ConnResponse is the plugin's verdict for an on_connect hook.

func AcceptConn

func AcceptConn() *ConnResponse

AcceptConn creates an L4 connection approval.

func RejectConn

func RejectConn() *ConnResponse

RejectConn creates an L4 connection denial.

type ConnectHandler

type ConnectHandler func(conn *ConnRequest) *ConnResponse

ConnectHandler processes an L4 connection and returns a verdict.

type Envelope

type Envelope struct {
	Hook HookType `msgpack:"t"`
	Data []byte   `msgpack:"d"`
}

Envelope wraps all socket messages with a type discriminator.

type HookType

type HookType byte

HookType identifies the hook being invoked over the socket.

const (
	HookRequest  HookType = 1
	HookResponse HookType = 2
	HookConnect  HookType = 3
)

type Option

type Option func(*Response)

Option configures a Response.

func WithHeader

func WithHeader(key, value string) Option

WithHeader adds a header to the response (injected into the proxied request on allow, or into the HTTP response on deny).

type Plugin

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

Plugin is the main entry point for writing prox plugins.

func New

func New() *Plugin

New creates a new plugin instance.

func (*Plugin) OnConfigure

func (p *Plugin) OnConfigure(h ConfigureHandler)

OnConfigure registers a handler for route configuration events.

func (*Plugin) OnConnect

func (p *Plugin) OnConnect(h ConnectHandler)

OnConnect registers a handler for L4 connection authorization. When registered, the plugin advertises the "on_connect" capability.

func (*Plugin) OnRequest

func (p *Plugin) OnRequest(h RequestHandler)

OnRequest registers a handler for L7 HTTP request authorization. When registered, the plugin advertises the "on_request" capability.

func (*Plugin) OnResponse

func (p *Plugin) OnResponse(h ResponseHandler)

OnResponse registers a handler for upstream response modification. When registered, the plugin advertises the "on_response" capability.

func (*Plugin) Run

func (p *Plugin) Run()

Run starts the plugin event loop. It blocks until stdin is closed. Call this after registering all handlers.

func (*Plugin) SetActionGroupedTargets

func (p *Plugin) SetActionGroupedTargets(action string, groups map[string][]string)

SetActionGroupedTargets pushes grouped targets for all routes using the given action.

func (*Plugin) SetActionTargets

func (p *Plugin) SetActionTargets(action string, targets []string)

SetActionTargets pushes a flat target list for all routes using the given action.

func (*Plugin) SetGroupedTargets

func (p *Plugin) SetGroupedTargets(routeID string, groups map[string][]string)

SetGroupedTargets pushes grouped targets for the given route. Use "*" as routeID to target all routes with balancers.

func (*Plugin) SetTargets

func (p *Plugin) SetTargets(routeID string, targets []string)

SetTargets pushes a flat target list for the given route. Use "*" as routeID to target all routes with balancers.

type Request

type Request struct {
	RouteID       string            `msgpack:"r" json:"route_id"`
	Method        string            `msgpack:"m" json:"method"`
	Path          string            `msgpack:"p" json:"path"`
	Query         string            `msgpack:"q,omitempty" json:"query,omitempty"`
	Domain        string            `msgpack:"d" json:"domain"`
	Host          string            `msgpack:"ho,omitempty" json:"host,omitempty"`
	Proto         string            `msgpack:"pr,omitempty" json:"proto,omitempty"`
	RemoteAddr    string            `msgpack:"a" json:"remote_addr"`
	ContentLength int64             `msgpack:"cl,omitempty" json:"content_length,omitempty"`
	Headers       map[string]string `msgpack:"h" json:"headers"`
	Body          []byte            `msgpack:"bd,omitempty" json:"body,omitempty"`
	MatchDomain   string            `msgpack:"md,omitempty" json:"match_domain,omitempty"`
	MatchGlob     string            `msgpack:"mg,omitempty" json:"match_glob,omitempty"`
	MatchPath     string            `msgpack:"mp,omitempty" json:"match_path,omitempty"`
	Vars          map[string]string `msgpack:"v,omitempty" json:"vars,omitempty"`
}

Request carries the HTTP request context for on_request hooks.

func (*Request) Header

func (r *Request) Header(key string) string

Header returns the value of a request header (case-sensitive key).

func (*Request) QueryParam

func (r *Request) QueryParam(key string) string

QueryParam returns the first value of a query parameter. For raw access to the full query string, use r.Query.

type RequestHandler

type RequestHandler func(req *Request) *Response

RequestHandler processes an incoming HTTP request and returns a verdict.

type Response

type Response struct {
	Allow   bool              `msgpack:"ok" json:"allow"`
	Drop    bool              `msgpack:"dr,omitempty" json:"drop,omitempty"`
	Status  int               `msgpack:"s,omitempty" json:"status,omitempty"`
	Body    string            `msgpack:"b,omitempty" json:"body,omitempty"`
	Headers map[string]string `msgpack:"h,omitempty" json:"headers,omitempty"`
}

Response is the plugin's verdict for an on_request hook.

func Allow

func Allow(opts ...Option) *Response

Allow creates an approval response, optionally injecting headers.

func Deny

func Deny(status int, body string, opts ...Option) *Response

Deny creates a denial response with the given HTTP status and body.

func Drop

func Drop() *Response

Drop silently closes the connection without sending any HTTP response.

type ResponseHandler

type ResponseHandler func(req *Request, resp *UpstreamResponse) *ResponseMod

ResponseHandler processes an upstream response and returns modifications.

type ResponseMod

type ResponseMod struct {
	Status  int               `msgpack:"s,omitempty" json:"status,omitempty"`
	Headers map[string]string `msgpack:"h,omitempty" json:"headers,omitempty"`
	Remove  []string          `msgpack:"rm,omitempty" json:"remove,omitempty"`
}

ResponseMod describes modifications to apply to the upstream response.

func ModifyResponse

func ModifyResponse(opts ...ResponseOption) *ResponseMod

ModifyResponse creates upstream response modifications.

func NoResponseMod

func NoResponseMod() *ResponseMod

NoResponseMod returns an empty modification (no changes).

type ResponseOption

type ResponseOption func(*ResponseMod)

ResponseOption configures a ResponseMod.

func RemoveResponseHeader

func RemoveResponseHeader(key string) ResponseOption

RemoveResponseHeader removes a header from the upstream response.

func WithResponseHeader

func WithResponseHeader(key, value string) ResponseOption

WithResponseHeader adds or overrides a header in the upstream response.

func WithResponseStatus

func WithResponseStatus(status int) ResponseOption

WithResponseStatus overrides the upstream response status code.

type Route

type Route struct {
	ID     string `msgpack:"id" json:"route_id"`
	Domain string `msgpack:"domain,omitempty" json:"domain,omitempty"`
	Path   string `msgpack:"path,omitempty" json:"path,omitempty"`
}

Route describes a configured route, sent during plugin initialization.

type UpstreamResponse

type UpstreamResponse struct {
	Status  int               `msgpack:"s" json:"status"`
	Headers map[string]string `msgpack:"h" json:"headers"`
}

UpstreamResponse carries upstream response context for on_response hooks.