external

package
v0.0.0-...-54d7c77 Latest Latest
Warning

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

 Go to latest Published: Feb 20, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package external provides gRPC-based external plugin support for the workflow engine. External plugins run as separate processes communicating over gRPC via hashicorp/go-plugin.

Index

Constants

View Source 
const (
	// ProtocolVersion is the plugin protocol version.
	// Increment this when making breaking changes to the gRPC interface.
	ProtocolVersion = 1

	// MagicCookieKey is the environment variable used for the handshake.
	MagicCookieKey = "WORKFLOW_PLUGIN"

	// MagicCookieValue is the expected value for the handshake cookie.
	MagicCookieValue = "workflow-external-plugin-v1"
)

Variables

View Source 
var Handshake = goplugin.HandshakeConfig{
	ProtocolVersion:  ProtocolVersion,
	MagicCookieKey:   MagicCookieKey,
	MagicCookieValue: MagicCookieValue,
}

Handshake is the shared handshake configuration between host and plugins. Both the host (client) and plugin (server) must use identical values.

Functions

This section is empty.

Types

type CallbackServer 

type CallbackServer struct {
	pb.UnimplementedEngineCallbackServiceServer
	// contains filtered or unexported fields
}

CallbackServer implements the EngineCallbackService gRPC server. It runs on the host and is called by plugin processes.

func NewCallbackServer 

func NewCallbackServer(onTrigger TriggerFunc, lookup ServiceLookupFunc, logger *log.Logger) *CallbackServer

NewCallbackServer creates a new callback server.

func (*CallbackServer) GetService 

func (s *CallbackServer) GetService(_ context.Context, req *pb.GetServiceRequest) (*pb.GetServiceResponse, error)

func (*CallbackServer) Log 

func (s *CallbackServer) Log(_ context.Context, req *pb.LogRequest) (*emptypb.Empty, error)

func (*CallbackServer) TriggerWorkflow 

func (s *CallbackServer) TriggerWorkflow(_ context.Context, req *pb.TriggerWorkflowRequest) (*pb.ErrorResponse, error)

type ExternalPluginAdapter 

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

ExternalPluginAdapter wraps a gRPC plugin client to implement plugin.EnginePlugin. The engine sees this as a regular plugin — no changes to engine.go needed.

func NewExternalPluginAdapter 

func NewExternalPluginAdapter(name string, client *PluginClient) (*ExternalPluginAdapter, error)

NewExternalPluginAdapter creates an adapter from a connected plugin client.

func (*ExternalPluginAdapter) Capabilities 

func (a *ExternalPluginAdapter) Capabilities() []capability.Contract

func (*ExternalPluginAdapter) Dependencies 

func (a *ExternalPluginAdapter) Dependencies() []plugin.PluginDependency

func (*ExternalPluginAdapter) Description 

func (a *ExternalPluginAdapter) Description() string

func (*ExternalPluginAdapter) EngineManifest 

func (a *ExternalPluginAdapter) EngineManifest() *plugin.PluginManifest

func (*ExternalPluginAdapter) ModuleFactories 

func (a *ExternalPluginAdapter) ModuleFactories() map[string]plugin.ModuleFactory

func (*ExternalPluginAdapter) ModuleSchemas 

func (a *ExternalPluginAdapter) ModuleSchemas() []*schema.ModuleSchema

func (*ExternalPluginAdapter) Name 

func (a *ExternalPluginAdapter) Name() string

func (*ExternalPluginAdapter) OnDisable 

func (a *ExternalPluginAdapter) OnDisable(_ plugin.PluginContext) error

func (*ExternalPluginAdapter) OnEnable 

func (a *ExternalPluginAdapter) OnEnable(_ plugin.PluginContext) error

func (*ExternalPluginAdapter) RegisterRoutes 

func (a *ExternalPluginAdapter) RegisterRoutes(_ *http.ServeMux)

func (*ExternalPluginAdapter) StepFactories 

func (a *ExternalPluginAdapter) StepFactories() map[string]plugin.StepFactory

func (*ExternalPluginAdapter) TriggerFactories 

func (a *ExternalPluginAdapter) TriggerFactories() map[string]plugin.TriggerFactory

func (*ExternalPluginAdapter) UIPages 

func (a *ExternalPluginAdapter) UIPages() []plugin.UIPageDef

func (*ExternalPluginAdapter) Version 

func (a *ExternalPluginAdapter) Version() string

func (*ExternalPluginAdapter) WiringHooks 

func (a *ExternalPluginAdapter) WiringHooks() []plugin.WiringHook

func (*ExternalPluginAdapter) WorkflowHandlers 

func (a *ExternalPluginAdapter) WorkflowHandlers() map[string]plugin.WorkflowHandlerFactory

type ExternalPluginManager 

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

ExternalPluginManager discovers, loads, and manages external plugin subprocesses. Each plugin lives in its own subdirectory under the plugins directory and communicates with the host via gRPC through the go-plugin framework.

func NewExternalPluginManager 

func NewExternalPluginManager(pluginsDir string, logger *log.Logger) *ExternalPluginManager

NewExternalPluginManager creates a new manager that scans the given directory for plugins.

func (*ExternalPluginManager) DiscoverPlugins 

func (m *ExternalPluginManager) DiscoverPlugins() ([]string, error)

DiscoverPlugins scans the plugins directory for subdirectories that contain a plugin.json manifest and an executable binary matching the directory name. It returns the list of discovered plugin names.

func (*ExternalPluginManager) IsLoaded 

func (m *ExternalPluginManager) IsLoaded(name string) bool

IsLoaded returns true if the named plugin is currently loaded.

func (*ExternalPluginManager) LoadPlugin 

func (m *ExternalPluginManager) LoadPlugin(name string) (*ExternalPluginAdapter, error)

LoadPlugin starts the named plugin subprocess, performs the handshake, and creates an ExternalPluginAdapter. The plugin must have been previously discovered via DiscoverPlugins.

func (*ExternalPluginManager) LoadedPlugins 

func (m *ExternalPluginManager) LoadedPlugins() []string

LoadedPlugins returns the names of all currently loaded plugins.

func (*ExternalPluginManager) ReloadPlugin 

func (m *ExternalPluginManager) ReloadPlugin(name string) (*ExternalPluginAdapter, error)

ReloadPlugin unloads and then loads the named plugin.

func (*ExternalPluginManager) Shutdown 

func (m *ExternalPluginManager) Shutdown()

Shutdown kills all loaded plugin subprocesses.

func (*ExternalPluginManager) UnloadPlugin 

func (m *ExternalPluginManager) UnloadPlugin(name string) error

UnloadPlugin stops the named plugin subprocess and removes it from the internal map.

type GRPCPlugin 

type GRPCPlugin struct {
	goplugin.Plugin
	// CallbackServer is the host-side callback implementation.
	// When non-nil, it will be registered on the broker for plugin access.
	CallbackServer *CallbackServer
}

GRPCPlugin implements go-plugin's Plugin and GRPCPlugin interfaces. It bridges between go-plugin's plugin system and our gRPC services.

func (*GRPCPlugin) GRPCClient 

func (p *GRPCPlugin) GRPCClient(_ context.Context, broker *goplugin.GRPCBroker, c *grpc.ClientConn) (any, error)

GRPCClient returns the client wrapper (host side). This is called by the host process to get a client that talks to the plugin.

func (*GRPCPlugin) GRPCServer 

func (p *GRPCPlugin) GRPCServer(broker *goplugin.GRPCBroker, s *grpc.Server) error

GRPCServer registers the plugin service on the gRPC server (plugin side). This is called by the plugin process.

type PluginClient 

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

PluginClient wraps the gRPC client for the plugin service.

type PluginHandler 

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

PluginHandler provides HTTP API endpoints for managing external plugins.

func NewPluginHandler 

func NewPluginHandler(manager *ExternalPluginManager) *PluginHandler

NewPluginHandler creates a new handler backed by the given external plugin manager.

func (*PluginHandler) RegisterRoutes 

func (h *PluginHandler) RegisterRoutes(mux *http.ServeMux)

RegisterRoutes registers the external plugin management HTTP routes on the given mux.

type RemoteModule 

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

RemoteModule implements modular.Module by delegating to a gRPC plugin.

func NewRemoteModule 

func NewRemoteModule(name, handleID string, client pb.PluginServiceClient) *RemoteModule

NewRemoteModule creates a remote module proxy.

func (*RemoteModule) Dependencies 

func (m *RemoteModule) Dependencies() []string

func (*RemoteModule) Destroy 

func (m *RemoteModule) Destroy() error

Destroy releases the remote module resources.

func (*RemoteModule) Init 

func (m *RemoteModule) Init(app modular.Application) error

func (*RemoteModule) InvokeService 

func (m *RemoteModule) InvokeService(method string, args map[string]any) (map[string]any, error)

InvokeService calls a named method on the remote module's service interface.

func (*RemoteModule) Name 

func (m *RemoteModule) Name() string

func (*RemoteModule) ProvidesServices 

func (m *RemoteModule) ProvidesServices() []string

func (*RemoteModule) RegisterConfig 

func (m *RemoteModule) RegisterConfig(app modular.Application) error

func (*RemoteModule) RequiresServices 

func (m *RemoteModule) RequiresServices() []string

func (*RemoteModule) Start 

func (m *RemoteModule) Start(ctx context.Context) error

func (*RemoteModule) Stop 

func (m *RemoteModule) Stop(ctx context.Context) error

type RemoteStep 

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

RemoteStep implements module.PipelineStep by delegating to a gRPC plugin.

func NewRemoteStep 

func NewRemoteStep(name, handleID string, client pb.PluginServiceClient) *RemoteStep

NewRemoteStep creates a remote step proxy.

func (*RemoteStep) Destroy 

func (s *RemoteStep) Destroy() error

Destroy releases the remote step resources.

func (*RemoteStep) Execute 

func (s *RemoteStep) Execute(ctx context.Context, pc *module.PipelineContext) (*module.StepResult, error)

func (*RemoteStep) Name 

func (s *RemoteStep) Name() string

type ServiceLookupFunc 

type ServiceLookupFunc func(name string) bool

ServiceLookupFunc checks if a named service exists in the host.

type TriggerFunc 

type TriggerFunc func(triggerType, action string, data map[string]any) error

TriggerFunc is called when a plugin fires a workflow trigger.

Source Files

View all Source files

Directories

Path Synopsis
Package sdk provides the public API for building external workflow plugins.
 Package sdk provides the public API for building external workflow plugins.

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.