sdk

package module

v0.4.0 Latest Latest Go to latest Published: May 14, 2025 License: MPL-2.0 Imports: 14 Imported by: 1

README ¶

Phobos Plugin SDK

This repository is a Go library that enables users to write custom Phobos plugins.

Plugins in Phobos are separate binaries which communicate with the Phobos application; the plugin communicates using gRPC.

Simple Plugin Overview

To initialize the plugin SDK you use the Main function in the sdk package and register a plugin which provides callbacks for Phobos during the various parts of the lifecycle.

package main

import (
  sdk "gitlab.com/infor-cloud/martian-cloud/phobos/phobos-plugin-sdk"
)

func main() {

  sdk.Main(
    sdk.WithPluginDescription("This is an example plugin"),
    sdk.WithPipelinePlugin(
      &internal.Plugin{},
    ),
  )

}

The pipeline plugin struct must implement the following interface:

type Plugin interface {
  Metadata() *Metadata
  Config() (any, error)
  ValidateConfig(config any) error
  PluginData(logger hclog.Logger) (any, error)
  GetActions() []func() Action
}

Installing Dependencies

To automate installing the required Golang packages needed to build Phobos locally, run make tools.

Regenerating protobufs

Install docker and run make gen

Security

If you've discovered a security vulnerability in the Phobos API, please let us know by creating a confidential issue in this project.

Statement of support

Please submit any bugs or feature requests for Phobos. Of course, MR's are even better. :)

License

Phobos API is distributed under Mozilla Public License v2.0.

Documentation ¶

Overview ¶

Package sdk provides the entrypoint to execute a plugin

Index ¶

func Debug(ctx context.Context, pluginAddr string, opts ...Option) error
func Main(opts ...Option)
type Option
- func WithPipelinePlugin(plugin pipeline.Plugin) Option
- func WithPluginDescription(description string) Option
type ReattachConfig
- func DebugServe(ctx context.Context, opts ...Option) (ReattachConfig, <-chan struct{}, error)
type ReattachConfigAddr

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

func Debug ¶

func Debug(ctx context.Context, pluginAddr string, opts ...Option) error

Debug starts a debug server and controls its lifecycle, printing the information needed for Phobos to connect to the plugin to stdout. os.Interrupt will be captured and used to stop the server.

func Main ¶

func Main(opts ...Option)

Main is the primary entrypoint for plugins serving components. This function never returns; it blocks until the program is exited. This should be called immediately in main() in your plugin binaries, no prior setup should be done.

Types ¶

type Option ¶

type Option func(*config)

Option modifies config. Zero or more can be passed to Main.

func WithPipelinePlugin ¶

func WithPipelinePlugin(plugin pipeline.Plugin) Option

WithPipelinePlugin adds the specified pipeline plugin

func WithPluginDescription ¶

func WithPluginDescription(description string) Option

WithPluginDescription sets the description of the plugin

type ReattachConfig ¶

type ReattachConfig struct {
	Addr            ReattachConfigAddr
	Protocol        string
	ProtocolVersion int
	Pid             int
	Test            bool
}

ReattachConfig holds the information Phobos needs to be able to attach itself to a plugin process, so it can drive the process.

func DebugServe ¶

func DebugServe(ctx context.Context, opts ...Option) (ReattachConfig, <-chan struct{}, error)

DebugServe starts a plugin server in debug mode; this should only be used when the plugin will manage its own lifecycle. It is not recommended for normal usage; Serve is the correct function for that.

type ReattachConfigAddr ¶

type ReattachConfigAddr struct {
	Network string
	String  string
}

ReattachConfigAddr is a JSON-encoding friendly version of net.Addr.

Source Files ¶

View all Source files

main.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd Package main provides the entrypoint for the CLI tool.	Package main provides the entrypoint for the CLI tool.
framework
pipeline Package pipeline is intended to be used by plugin developers to create new pipeline plugins	Package pipeline is intended to be used by plugin developers to create new pipeline plugins
pipeline/mocks
internal
cmd Package cmd provides the internal implementation for the CLI tool.	Package cmd provides the internal implementation for the CLI tool.
funcspec Package funcspec contains functions for building function specs	Package funcspec contains functions for building function specs
plugin Package plugin contains core GRPC plugin functionality	Package plugin contains core GRPC plugin functionality
plugin/terminal Package terminal provides the GRPC terminal implementations	Package terminal provides the GRPC terminal implementations
pluginargs Package pluginargs contains base args that can be passed to plugin functions	Package pluginargs contains base args that can be passed to plugin functions
stdio Package stdio provides concurrency controls around creating the plugin stdio	Package stdio provides concurrency controls around creating the plugin stdio
testproto Package testproto contains some protobuf defintions that are used in internal tests.	Package testproto contains some protobuf defintions that are used in internal tests.
internal-shared
component Package component exposes the component interfaces	Package component exposes the component interfaces
component/mocks
pluginclient Package pluginclient is used to initialize a new plugin instance	Package pluginclient is used to initialize a new plugin instance
protomappers Package protomappers contains mappers for converting to/from proto types	Package protomappers contains mappers for converting to/from proto types
schema Package schema defines the schema format for plugins	Package schema defines the schema format for plugins
proto
gen
terminal Package terminal is used by plugins to read and write to a terminal UI.	Package terminal is used by plugins to read and write to a terminal UI.