sdk

package module
v0.0.0-...-a2ee51c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 7, 2026 License: MIT Imports: 10 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

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 DisconnectEvent 

type DisconnectEvent struct {
	RouteID    string `msgpack:"r" json:"route_id"`
	Target     string `msgpack:"tg,omitempty" json:"target,omitempty"`
	RemoteAddr string `msgpack:"a" json:"remote_addr"`
	BytesRx    int64  `msgpack:"rx" json:"bytes_rx"`
	BytesTx    int64  `msgpack:"tx" json:"bytes_tx"`
	DurationMs int64  `msgpack:"ms" json:"duration_ms"`
}

DisconnectEvent carries connection statistics for on_disconnect hooks.

type DisconnectHandler 

type DisconnectHandler func(event *DisconnectEvent)

DisconnectHandler receives connection statistics after a connection ends.

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
	HookDisconnect HookType = 4
)

type Option 

type Option func(*Response)

Option configures a Response.

func WithCleanQuery 

func WithCleanQuery() Option

WithCleanQuery removes the query string from the proxied request URL.

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).

func WithRewritePath 

func WithRewritePath(path string) Option

WithRewritePath changes the upstream request path (e.g. for removing identifiers).

func WithSpeedLimit 

func WithSpeedLimit(downloadMbps, uploadMbps float64, groupKey ...string) Option

WithSpeedLimit sets bandwidth caps in Mbps. Zero values mean unlimited for that direction. An optional groupKey aggregates bandwidth across all connections sharing the same key (e.g. a user ID) instead of limiting each connection independently.

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) Debug 

func (p *Plugin) Debug(msg string, args ...any)

Debug logs a message at debug level.

func (*Plugin) Error 

func (p *Plugin) Error(msg string, args ...any)

Error logs a message at error level.

func (*Plugin) Info 

func (p *Plugin) Info(msg string, args ...any)

Info logs a message at info level.

func (*Plugin) Log 

func (p *Plugin) Log(level, msg string, args ...any)

Log sends a log message at the given level through the proxy's logger. Level must be one of: "debug", "info", "warn", "error". Args are slog-style key-value pairs (e.g. "key", value, "key2", value2).

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) OnDisconnect 

func (p *Plugin) OnDisconnect(h DisconnectHandler)

OnDisconnect registers a handler for connection statistics events. This is a fire-and-forget notification — no response is expected.

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) SetActionSpeedLimit 

func (p *Plugin) SetActionSpeedLimit(action string, limit SpeedLimit)

SetActionSpeedLimit pushes a speed limit 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) SetSpeedLimit 

func (p *Plugin) SetSpeedLimit(routeID string, limit SpeedLimit)

SetSpeedLimit pushes a speed limit for the given route. Use "*" as routeID to target all routes.

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.

func (*Plugin) Warn 

func (p *Plugin) Warn(msg string, args ...any)

Warn logs a message at warn level.

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"`
	Target        string            `msgpack:"tg,omitempty" json:"target,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"`
	Fallback    bool              `msgpack:"fb,omitempty" json:"fallback,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"`
	SpeedLimit  *SpeedLimit       `msgpack:"sp,omitempty" json:"speed_limit,omitempty"`
	CleanQuery  bool              `msgpack:"cq,omitempty" json:"clean_query,omitempty"`
	RewritePath string            `msgpack:"rp,omitempty" json:"rewrite_path,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.

func Fallback 

func Fallback(opts ...Option) *Response

Fallback creates a response that tells the proxy to route the request to the configured fallback action.

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 SpeedLimit 

type SpeedLimit struct {
	DownloadMbps float64 `msgpack:"dl,omitempty" json:"download_mbps,omitempty"`
	UploadMbps   float64 `msgpack:"ul,omitempty" json:"upload_mbps,omitempty"`
	GroupKey     string  `msgpack:"gk,omitempty" json:"group_key,omitempty"`
}

SpeedLimit defines bandwidth caps in Mbps. When GroupKey is set, all connections sharing the same key share a single bandwidth budget instead of each getting independent per-connection limits.

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.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.