sdk

type AssetProvider ¶ added in v0.3.3

type AssetProvider interface {
	GetAsset(path string) (content []byte, contentType string, err error)
}

AssetProvider allows plugins to serve embedded static assets (e.g., UI files).

type CLIProvider ¶ added in v0.18.0

type CLIProvider interface {
	// RunCLI handles the command. args contains the command and all subsequent
	// arguments (the plugin binary path and the --wfctl-cli flag are stripped).
	// The return value becomes the process exit code.
	RunCLI(args []string) int
}

CLIProvider is implemented by plugins that expose top-level wfctl subcommands. When wfctl detects a matching command it invokes the plugin binary with --wfctl-cli <command> [args...], and the plugin must exit with the returned code.

type ConfigField ¶ added in v0.1.5

type ConfigField struct {
	Name         string
	Type         string
	Description  string
	DefaultValue string
	Required     bool
	Options      []string
}

ConfigField describes a configuration field.

type ConfigProvider ¶ added in v0.1.7

type ConfigProvider interface {
	// ConfigFragment returns YAML config to merge into the host config.
	ConfigFragment() ([]byte, error)
}

ConfigProvider is optionally implemented by plugins that need to inject config (modules, workflows, triggers) into the host config before module registration.

type ContractProvider ¶ added in v0.19.0

type ContractProvider interface {
	ContractRegistry() *pb.ContractRegistry
}

ContractProvider is optionally implemented to expose typed contract descriptors.

type HookHandler ¶ added in v0.18.0

type HookHandler interface {
	// HandleBuildHook handles the given hook event.
	// payload is the raw JSON payload from wfctl.
	// result is the raw JSON response written back to wfctl.
	// A non-nil error causes wfctl to apply the plugin's on_hook_failure policy.
	HandleBuildHook(event string, payload []byte) (result []byte, err error)
}

HookHandler is implemented by plugins that register build-pipeline hook handlers. When wfctl dispatches a hook event it invokes the plugin binary with --wfctl-hook <event>, writes the JSON payload to stdin, and reads the JSON result from stdout.

type MessageAwareModule ¶ added in v0.1.5

type MessageAwareModule interface {
	SetMessagePublisher(pub MessagePublisher)
	SetMessageSubscriber(sub MessageSubscriber)
}

MessageAwareModule is optionally implemented by ModuleInstance to receive message capabilities.

type MessagePublisher ¶ added in v0.1.5

type MessagePublisher interface {
	Publish(topic string, payload []byte, metadata map[string]string) (messageID string, err error)
}

MessagePublisher is provided to modules that need to send messages to the host.

type MessageSubscriber ¶ added in v0.1.5

type MessageSubscriber interface {
	Subscribe(topic string, handler func(payload []byte, metadata map[string]string) error) error
	Unsubscribe(topic string) error
}

MessageSubscriber is provided to modules that need to receive messages from the host.

type ModuleInstance ¶

type ModuleInstance interface {
	Init() error
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

ModuleInstance is a remote module's lifecycle.

type ModuleProvider ¶

type ModuleProvider interface {
	// ModuleTypes returns the module type names this plugin provides.
	ModuleTypes() []string
	// CreateModule creates a module instance of the given type.
	CreateModule(typeName, name string, config map[string]any) (ModuleInstance, error)
}

ModuleProvider is optionally implemented to provide module types.

type ModuleSchemaData ¶ added in v0.1.5

type ModuleSchemaData struct {
	Type         string
	Label        string
	Category     string
	Description  string
	Inputs       []ServiceIO
	Outputs      []ServiceIO
	ConfigFields []ConfigField
}

ModuleSchemaData describes a module type for the UI.

type PluginManifest ¶

type PluginManifest struct {
	Name           string
	Version        string
	Author         string
	Description    string
	ConfigMutable  bool   // whether tenants can override the config fragment
	SampleCategory string // non-empty means this is a sample/app plugin
}

PluginManifest describes the plugin.

type PluginProvider ¶

type PluginProvider interface {
	// Manifest returns the plugin's metadata.
	Manifest() PluginManifest
}

PluginProvider is the main interface plugin authors implement.

type SchemaProvider ¶ added in v0.1.5

type SchemaProvider interface {
	ModuleSchemas() []ModuleSchemaData
}

SchemaProvider is optionally implemented to provide UI schemas.

type ServiceContextInvoker ¶ added in v0.19.0

type ServiceContextInvoker interface {
	InvokeMethodContext(ctx context.Context, method string, args map[string]any) (map[string]any, error)
}

ServiceContextInvoker is optionally implemented by ModuleInstance to receive the gRPC request context for long-running service invocations.

type ServiceIO ¶ added in v0.1.5

type ServiceIO struct {
	Name        string
	Type        string
	Description string
}

ServiceIO describes a service input or output.

type ServiceInvoker ¶ added in v0.2.19

type ServiceInvoker interface {
	InvokeMethod(method string, args map[string]any) (map[string]any, error)
}

ServiceInvoker is optionally implemented by ModuleInstance to handle service method invocations from the host. The host calls InvokeService with a method name and a map of arguments; the implementation dispatches to the appropriate logic and returns a result map.

type StepInstance ¶

type StepInstance interface {
	Execute(ctx context.Context, triggerData map[string]any, stepOutputs map[string]map[string]any, current map[string]any, metadata map[string]any, config map[string]any) (*StepResult, error)
}

StepInstance is a remote pipeline step.

type StepProvider ¶

type StepProvider interface {
	// StepTypes returns the step type names this plugin provides.
	StepTypes() []string
	// CreateStep creates a step instance of the given type.
	CreateStep(typeName, name string, config map[string]any) (StepInstance, error)
}

StepProvider is optionally implemented to provide step types.

type StepResult ¶

type StepResult struct {
	Output       map[string]any
	StopPipeline bool
}

StepResult is the output of a step execution.

type TriggerCallback ¶ added in v0.1.5

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

TriggerCallback allows a trigger to fire workflow actions on the host.

type TriggerInstance ¶ added in v0.1.5

type TriggerInstance interface {
	Start(ctx context.Context) error
	Stop(ctx context.Context) error
}

TriggerInstance is a remote trigger's lifecycle.

type TriggerProvider ¶ added in v0.1.5

type TriggerProvider interface {
	TriggerTypes() []string
	CreateTrigger(typeName string, config map[string]any, cb TriggerCallback) (TriggerInstance, error)
}

TriggerProvider is optionally implemented by plugins that provide trigger types.

type TypedModuleCreator ¶ added in v0.19.0

type TypedModuleCreator[C proto.Message] func(name string, config C) (ModuleInstance, error)

TypedModuleCreator constructs a module after its typed config has been unpacked and validated.

type TypedModuleFactory ¶ added in v0.19.0

type TypedModuleFactory[C proto.Message] struct {
	// contains filtered or unexported fields
}

TypedModuleFactory is a single-module TypedModuleProvider implementation.

func NewTypedModuleFactory[C proto.Message](
	typeName string,
	configPrototype C,
	create TypedModuleCreator[C],
) *TypedModuleFactory[C]

func (f *TypedModuleFactory[C]) CreateTypedModule(typeName, name string, config *anypb.Any) (ModuleInstance, error)

func (f *TypedModuleFactory[C]) TypedModuleTypes() []string

type TypedModuleInstance ¶ added in v0.19.0

type TypedModuleInstance[C proto.Message] struct {
	ModuleInstance
	// contains filtered or unexported fields
}

TypedModuleInstance adapts protobuf-typed module config while preserving the normal ModuleInstance lifecycle interface.

func NewTypedModuleInstance[C proto.Message](configPrototype C, module ModuleInstance) *TypedModuleInstance[C]

func (m *TypedModuleInstance[C]) Init() error

func (m *TypedModuleInstance[C]) InvokeMethod(method string, args map[string]any) (map[string]any, error)

func (m *TypedModuleInstance[C]) InvokeTypedMethod(method string, input *anypb.Any) (*anypb.Any, error)

func (m *TypedModuleInstance[C]) SetMessagePublisher(pub MessagePublisher)

func (m *TypedModuleInstance[C]) SetMessageSubscriber(sub MessageSubscriber)

func (m *TypedModuleInstance[C]) Start(ctx context.Context) error

func (m *TypedModuleInstance[C]) Stop(ctx context.Context) error

func (m *TypedModuleInstance[C]) TypedConfig() C

type TypedModuleProvider ¶ added in v0.19.0

type TypedModuleProvider interface {
	TypedModuleTypes() []string
	CreateTypedModule(typeName, name string, config *anypb.Any) (ModuleInstance, error)
}

TypedModuleProvider creates protobuf-typed module instances after validating typed_config. Implement this instead of ModuleProvider for strict typed modules.

type TypedServiceInvoker ¶ added in v0.19.0

type TypedServiceInvoker interface {
	InvokeTypedMethod(method string, input *anypb.Any) (*anypb.Any, error)
}

TypedServiceInvoker is optionally implemented by ModuleInstance to handle strict protobuf service method invocations from the host.

type TypedStepFactory ¶ added in v0.19.0

type TypedStepFactory[C proto.Message, I proto.Message, O proto.Message] struct {
	// contains filtered or unexported fields
}

TypedStepFactory is a single-step TypedStepProvider implementation.

func NewTypedStepFactory[C proto.Message, I proto.Message, O proto.Message](
	typeName string,
	configPrototype C,
	inputPrototype I,
	handler TypedStepHandler[C, I, O],
) *TypedStepFactory[C, I, O]

func (f *TypedStepFactory[C, I, O]) CreateTypedStep(typeName, _ string, config *anypb.Any) (StepInstance, error)

func (f *TypedStepFactory[C, I, O]) TypedStepTypes() []string

type TypedStepHandler ¶ added in v0.19.0

type TypedStepHandler[C proto.Message, I proto.Message, O proto.Message] func(context.Context, TypedStepRequest[C, I]) (*TypedStepResult[O], error)

TypedStepHandler executes a typed step with protobuf config and input.

type TypedStepInstance ¶ added in v0.19.0

type TypedStepInstance[C proto.Message, I proto.Message, O proto.Message] struct {
	// contains filtered or unexported fields
}

TypedStepInstance adapts a protobuf-typed step implementation to the legacy StepInstance interface and the typed gRPC execution path.

func NewTypedStepInstance[C proto.Message, I proto.Message, O proto.Message](
	configPrototype C,
	inputPrototype I,
	handler TypedStepHandler[C, I, O],
) *TypedStepInstance[C, I, O]

func (s *TypedStepInstance[C, I, O]) Execute(context.Context, map[string]any, map[string]map[string]any, map[string]any, map[string]any, map[string]any) (*StepResult, error)

type TypedStepProvider ¶ added in v0.19.0

type TypedStepProvider interface {
	TypedStepTypes() []string
	CreateTypedStep(typeName, name string, config *anypb.Any) (StepInstance, error)
}

TypedStepProvider creates protobuf-typed step instances after validating typed_config. Implement this instead of StepProvider for strict typed steps.

type TypedStepRequest ¶ added in v0.19.0

type TypedStepRequest[C proto.Message, I proto.Message] struct {
	Config C
	Input  I

	TriggerData map[string]any
	StepOutputs map[string]map[string]any
	Current     map[string]any
	Metadata    map[string]any
}

TypedStepRequest is passed to typed step handlers after protobuf Any payloads have been validated and unpacked.

type TypedStepResult ¶ added in v0.19.0

type TypedStepResult[O proto.Message] struct {
	Output       O
	StopPipeline bool
}

TypedStepResult is returned from typed step handlers and packed into Any.

type UIProvider ¶ added in v0.1.1

type UIProvider interface {
	// UIManifest returns the UI manifest for this plugin.
	UIManifest() ext.UIManifest
}

UIProvider is an optional interface that PluginProvider implementations can satisfy to declare UI assets and navigation contributions.

If a PluginProvider implements UIProvider, the SDK Serve() function will write a "ui.json" file to the plugin's working directory on first start (if one does not already exist). Alternatively, authors can maintain "ui.json" manually without implementing this interface.

Type aliases ¶

The UI manifest types (UIManifest, UINavItem) are defined in the github.com/GoCodeAlone/workflow/plugin/external package so that both the host engine and plugin processes share the same type definitions without introducing an import cycle.