grpc

package
v0.8.0 Latest Latest
Warning

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

 Go to latest Published: Mar 28, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package grpc provides gRPC-based plugin runtime using HashiCorp go-plugin.

This enables native Go plugins to run as separate processes, communicating with the host via gRPC. Useful for I/O-heavy plugins that benefit from native performance and direct system access.

Shared types (handshake, RPC structs, ServePlugin) live in pkg/plugin/grpcutil so external plugins can import them. This package adds the host-side loading, HostAPI bridging, and bidirectional calls.

Index

Constants

This section is empty.

Variables

View Source 
var Handshake = grpcutil.Handshake

Handshake re-exports the shared handshake config.

View Source 
var PluginMap = map[string]goplugin.Plugin{
	"gkplugin": &GKPluginPluginHost{},
}

PluginMap is the map of plugin types we support.

View Source 
var ServePlugin = grpcutil.ServePlugin

ServePlugin re-exports the public ServePlugin for internal use.

Functions

func GeneratePodManifest added in v0.8.0 

func GeneratePodManifest(spec K8sPodSpec) string

GeneratePodManifest returns a Kubernetes pod YAML for a plugin.

Types

type CallRequest 

type CallRequest = grpcutil.CallRequest

type CallResponse 

type CallResponse = grpcutil.CallResponse

type GKPluginInterface 

type GKPluginInterface = grpcutil.GKPluginInterface

Re-export shared types so existing internal callers don't break.

type GKPluginPlugin 

type GKPluginPlugin = grpcutil.GKPluginPlugin

type GKPluginPluginHost added in v0.7.0 

type GKPluginPluginHost struct {
	goplugin.Plugin
	Impl       GKPluginInterface
	Host       plugin.HostAPI // For bidirectional calls
	PluginName string         // Plugin name for caller authentication
}

GKPluginPluginHost is the host-side go-plugin.Plugin implementation. It extends the base plugin with HostAPI bidirectional call support.

func (*GKPluginPluginHost) Client added in v0.7.0 

func (p *GKPluginPluginHost) Client(b *goplugin.MuxBroker, c *rpc.Client) (interface{}, error)

Client returns the RPC client for the plugin (host side).

func (*GKPluginPluginHost) Server added in v0.7.0 

func (p *GKPluginPluginHost) Server(b *goplugin.MuxBroker) (interface{}, error)

Server returns the RPC server for the plugin (plugin side).

type GKPluginRPCClient 

type GKPluginRPCClient = grpcutil.GKPluginRPCClient

type GKPluginRPCClientHost added in v0.7.0 

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

GKPluginRPCClientHost is the host-side RPC client with HostAPI bridging.

func (*GKPluginRPCClientHost) Call added in v0.7.0 

func (c *GKPluginRPCClientHost) Call(fn string, args json.RawMessage) (json.RawMessage, error)

func (*GKPluginRPCClientHost) GKRegister added in v0.7.0 

func (c *GKPluginRPCClientHost) GKRegister() (*plugin.GKRegistration, error)

func (*GKPluginRPCClientHost) Init added in v0.7.0 

func (c *GKPluginRPCClientHost) Init(config map[string]string) error

func (*GKPluginRPCClientHost) Shutdown added in v0.7.0 

func (c *GKPluginRPCClientHost) Shutdown() error

type GKPluginRPCServer 

type GKPluginRPCServer = grpcutil.GKPluginRPCServer

type GKPluginRPCServerHost added in v0.7.0 

type GKPluginRPCServerHost struct {
	Impl GKPluginInterface
	// contains filtered or unexported fields
}

GKPluginRPCServerHost is the host-side RPC server with HostAPI bridging.

func (*GKPluginRPCServerHost) Call added in v0.7.0 

func (s *GKPluginRPCServerHost) Call(req CallRequest, resp *CallResponse) error

func (*GKPluginRPCServerHost) GKRegister added in v0.7.0 

func (s *GKPluginRPCServerHost) GKRegister(args interface{}, resp *[]byte) error

func (*GKPluginRPCServerHost) Init added in v0.7.0 

func (s *GKPluginRPCServerHost) Init(req InitRequest, resp *interface{}) error

func (*GKPluginRPCServerHost) Shutdown added in v0.7.0 

func (s *GKPluginRPCServerHost) Shutdown(args interface{}, resp *interface{}) error

type GRPCPlugin 

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

GRPCPlugin wraps a go-plugin client to implement plugin.Plugin.

func LoadGRPCPlugin 

func LoadGRPCPlugin(execPath, pluginName string, host plugin.HostAPI, policy plugin.ResourcePolicy) (*GRPCPlugin, error)

LoadGRPCPlugin loads a gRPC plugin from an executable path with OS-level sandboxing.

func (*GRPCPlugin) Call 

func (p *GRPCPlugin) Call(ctx context.Context, fn string, args json.RawMessage) (json.RawMessage, error)

Call implements plugin.Plugin.

func (*GRPCPlugin) GKRegister 

func (p *GRPCPlugin) GKRegister() plugin.GKRegistration

GKRegister implements plugin.Plugin.

func (*GRPCPlugin) Init 

func (p *GRPCPlugin) Init(ctx context.Context, host plugin.HostAPI) error

Init implements plugin.Plugin.

func (*GRPCPlugin) SetCallTimeout added in v0.7.0 

func (p *GRPCPlugin) SetCallTimeout(d time.Duration)

SetCallTimeout sets the per-call timeout for this plugin.

func (*GRPCPlugin) Shutdown 

func (p *GRPCPlugin) Shutdown(ctx context.Context) error

Shutdown implements plugin.Plugin.

type HostAPIRPCClient 

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

HostAPIRPCClient is the client plugins use to call the host. This runs on the plugin side.

func NewHostAPIRPCClient 

func NewHostAPIRPCClient(client *rpc.Client) *HostAPIRPCClient

NewHostAPIRPCClient creates a new host API client.

func (*HostAPIRPCClient) Call 

func (c *HostAPIRPCClient) Call(method string, args any) (json.RawMessage, error)

Call makes a host API call.

func (*HostAPIRPCClient) CallPlugin 

func (c *HostAPIRPCClient) CallPlugin(pluginName, fn string, args json.RawMessage) (json.RawMessage, error)

func (*HostAPIRPCClient) DBExec 

func (c *HostAPIRPCClient) DBExec(query string, args ...any) (int64, error)

func (*HostAPIRPCClient) DBQuery 

func (c *HostAPIRPCClient) DBQuery(query string, args ...any) ([]map[string]any, error)

type HostAPIRPCServer 

type HostAPIRPCServer struct {
	Host       plugin.HostAPI
	CallerName string // Authenticated plugin name (set by host, not trusted from plugin)
}

HostAPIRPCServer exposes HostAPI to plugins via RPC. This runs on the host side and handles plugin callbacks.

func (*HostAPIRPCServer) Call 

func (s *HostAPIRPCServer) Call(req HostAPIRequest, resp *HostAPIResponse) error

Call handles all host API calls from plugins.

type HostAPIRequest 

type HostAPIRequest struct {
	Method       string          // Method name (e.g., "db_query", "cache_get")
	Args         json.RawMessage // JSON-encoded arguments
	CallerPlugin string          // Name of the calling plugin (for error context)
}

HostAPIRequest is a generic host API request.

type HostAPIResponse 

type HostAPIResponse struct {
	Result json.RawMessage
	Error  string
}

HostAPIResponse is a generic host API response.

type HostError 

type HostError struct {
	Message string
}

HostError represents an error from the host.

func (*HostError) Error 

func (e *HostError) Error() string

type InitRequest 

type InitRequest = grpcutil.InitRequest

type IsolationMode added in v0.8.0 

type IsolationMode string

IsolationMode determines how gRPC plugins are sandboxed. 

const (
	// IsolationLocal runs plugins as local processes with Linux namespace isolation.
	IsolationLocal IsolationMode = "local"
	// IsolationK8s runs plugins as Kubernetes pods.
	IsolationK8s IsolationMode = "k8s"
)

func GetIsolationMode added in v0.8.0 

func GetIsolationMode() IsolationMode

GetIsolationMode returns the configured plugin isolation mode.

type K8sPodSpec added in v0.8.0 

type K8sPodSpec struct {
	PluginName string
	Image      string // Container image for the plugin
	Port       int    // gRPC port
	MemoryMB   int    // Memory limit from ResourcePolicy
	CPUMillis  int    // CPU limit (millicores)
	Namespace  string // K8s namespace (default: goatflow-plugins)
}

K8sPodSpec generates a Kubernetes pod spec for a gRPC plugin. This is used by the plugin loader when isolation mode is "k8s".

type UnknownMethodError 

type UnknownMethodError struct {
	Method string
}

UnknownMethodError is returned when a plugin calls an unknown host method.

func (*UnknownMethodError) Error 

func (e *UnknownMethodError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
Example gRPC plugin for GoatKit.
 Example gRPC plugin for GoatKit.

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.