plugin

package
v1.0.6 Latest Latest
Warning

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

 Go to latest Published: Mar 15, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultCertsDir = "~/.orchestra/certs"

DefaultCertsDir is the default directory for mTLS certificates.

View Source 
const MaxMessageSize = 16 * 1024 * 1024

MaxMessageSize is the maximum allowed size for a single framed protobuf message (16 MB).

Variables

This section is empty.

Functions

func ClientTLSConfig 

func ClientTLSConfig(certsDir string, name string) (*tls.Config, error)

ClientTLSConfig returns a TLS configuration for a QUIC client that uses mTLS. It loads or generates the named certificate and trusts the CA.

func EnsureCA 

func EnsureCA(certsDir string) (*x509.Certificate, crypto.PrivateKey, error)

EnsureCA loads or generates a CA certificate and private key at the given certs directory. The CA cert is stored at certsDir/ca.crt and the key at certsDir/ca.key. Uses ed25519 for fast, compact keys.

func GenerateCert 

func GenerateCert(certsDir string, name string, caCert *x509.Certificate, caKey crypto.PrivateKey) (tls.Certificate, error)

GenerateCert creates a new certificate signed by the given CA for the named entity. Certificates are stored at certsDir/{name}.crt and certsDir/{name}.key.

func ReadMessage 

func ReadMessage(r io.Reader, msg proto.Message) error

ReadMessage reads a length-delimited protobuf message from r and unmarshals it into msg. The framing format must match WriteMessage.

func ResolveCertsDir 

func ResolveCertsDir(certsDir string) string

ResolveCertsDir expands ~ in the certs directory path.

func ServerTLSConfig 

func ServerTLSConfig(certsDir string, name string) (*tls.Config, error)

ServerTLSConfig returns a TLS configuration for a QUIC server that uses mTLS. It loads or generates the named certificate and requires client certificates signed by the same CA.

func WriteMessage 

func WriteMessage(w io.Writer, msg proto.Message) error

WriteMessage marshals a protobuf message and writes it to w using length-delimited framing: [4 bytes big-endian uint32 length][N bytes payload].

Types

type EventHandler added in v0.1.3 

type EventHandler func(ctx context.Context, event *pluginv1.EventDelivery)

EventHandler is called when an event is delivered to a subscriber.

type ExportedPlugin added in v0.1.3 

type ExportedPlugin struct {
	ID             string
	Manifest       *pluginv1.PluginManifest
	Tools          []ExportedTool
	StreamTools    []ExportedStreamTool
	Prompts        []ExportedPrompt
	StorageHandler StorageHandler
	Lifecycle      LifecycleHooks
}

ExportedPlugin contains all tools, prompts, and storage handler collected from a PluginBuilder, without any QUIC or network infrastructure. Used by the in-process serve mode to embed plugins directly.

type ExportedPrompt added in v0.1.3 

type ExportedPrompt struct {
	Name        string
	Description string
	Arguments   []*pluginv1.PromptArgument
	Handler     PromptHandler
}

ExportedPrompt holds a prompt's definition and handler.

type ExportedStreamTool added in v0.1.3 

type ExportedStreamTool struct {
	Name        string
	Description string
	Schema      *structpb.Struct
	Handler     StreamingToolHandler
}

ExportedStreamTool holds a streaming tool's definition and handler.

type ExportedTool added in v0.1.3 

type ExportedTool struct {
	Name        string
	Description string
	Schema      *structpb.Struct
	Handler     ToolHandler
}

ExportedTool holds a tool's definition and handler for in-process use.

type LifecycleHooks 

type LifecycleHooks interface {
	// OnBoot is called when the orchestrator sends a Boot request with
	// configuration parameters. The plugin should initialize any resources
	// it needs and return an error if boot fails.
	OnBoot(config map[string]string) error

	// OnShutdown is called when the orchestrator requests a graceful shutdown.
	// The plugin should release resources and return an error if cleanup fails.
	OnShutdown() error
}

LifecycleHooks defines optional callbacks that a plugin can implement to respond to lifecycle events from the orchestrator.

type ManifestBuilder 

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

ManifestBuilder provides a fluent API for constructing a PluginManifest.

func NewManifest 

func NewManifest(id string) *ManifestBuilder

NewManifest creates a new ManifestBuilder with the given plugin ID.

func (*ManifestBuilder) Author 

func (b *ManifestBuilder) Author(a string) *ManifestBuilder

Author sets the plugin author.

func (*ManifestBuilder) Binary 

func (b *ManifestBuilder) Binary(bin string) *ManifestBuilder

Binary sets the path to the plugin binary.

func (*ManifestBuilder) Build 

func (b *ManifestBuilder) Build() *pluginv1.PluginManifest

Build returns the constructed PluginManifest.

func (*ManifestBuilder) Description 

func (b *ManifestBuilder) Description(d string) *ManifestBuilder

Description sets the human-readable description.

func (*ManifestBuilder) NeedsAI 

func (b *ManifestBuilder) NeedsAI(providers ...string) *ManifestBuilder

NeedsAI declares the AI providers this plugin requires.

func (*ManifestBuilder) NeedsEvents 

func (b *ManifestBuilder) NeedsEvents(events ...string) *ManifestBuilder

NeedsEvents declares the event types this plugin subscribes to.

func (*ManifestBuilder) NeedsStorage 

func (b *ManifestBuilder) NeedsStorage(types ...string) *ManifestBuilder

NeedsStorage declares the storage types this plugin requires from others.

func (*ManifestBuilder) NeedsTools 

func (b *ManifestBuilder) NeedsTools(tools ...string) *ManifestBuilder

NeedsTools declares the tools this plugin requires from other plugins.

func (*ManifestBuilder) ProvidesAI added in v0.1.3 

func (b *ManifestBuilder) ProvidesAI(providers ...string) *ManifestBuilder

ProvidesAI declares the AI providers this plugin serves (e.g. "claude", "openai", "ollama"). The orchestrator uses this to build the AI routing table so that tool calls with a matching provider field are dispatched to the correct bridge plugin.

func (*ManifestBuilder) ProvidesPrompts added in v0.1.1 

func (b *ManifestBuilder) ProvidesPrompts(names ...string) *ManifestBuilder

ProvidesPrompts declares the prompt names this plugin provides.

func (*ManifestBuilder) ProvidesStorage 

func (b *ManifestBuilder) ProvidesStorage(types ...string) *ManifestBuilder

ProvidesStorage declares the storage types this plugin provides.

func (*ManifestBuilder) ProvidesTools 

func (b *ManifestBuilder) ProvidesTools(names ...string) *ManifestBuilder

ProvidesTools declares the tool names this plugin provides.

func (*ManifestBuilder) ProvidesTransport 

func (b *ManifestBuilder) ProvidesTransport(types ...string) *ManifestBuilder

ProvidesTransport declares the transport types this plugin provides.

func (*ManifestBuilder) Version 

func (b *ManifestBuilder) Version(v string) *ManifestBuilder

Version sets the semantic version of the plugin.

type OrchestratorClient 

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

OrchestratorClient is a QUIC client for communicating with the orchestrator or another plugin server. Each Send call opens a new bidirectional QUIC stream, writes the request, reads the response, and closes the stream.

func NewOrchestratorClient 

func NewOrchestratorClient(ctx context.Context, addr string, tlsConfig *tls.Config) (*OrchestratorClient, error)

NewOrchestratorClient dials a QUIC connection to the given address using the provided TLS configuration.

func (*OrchestratorClient) Close 

func (c *OrchestratorClient) Close() error

Close terminates the underlying QUIC connection.

func (*OrchestratorClient) Send 

func (c *OrchestratorClient) Send(ctx context.Context, req *pluginv1.PluginRequest) (*pluginv1.PluginResponse, error)

Send opens a new bidirectional QUIC stream, writes the PluginRequest, reads the PluginResponse, and returns it. Each call is one complete RPC exchange.

func (*OrchestratorClient) SendStream added in v0.1.3 

func (c *OrchestratorClient) SendStream(ctx context.Context, req *pluginv1.PluginRequest) (<-chan *pluginv1.PluginResponse, error)

SendStream opens a QUIC stream, writes the request, and returns a channel that receives multiple PluginResponse messages (StreamChunk + StreamEnd). The channel is closed after StreamEnd is received or on error. The caller can cancel the context to abort the stream.

type Plugin 

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

Plugin is the top-level runtime for a Go-based Orchestra plugin. It manages a QUIC server (to receive requests), a QUIC client (to connect to the orchestrator), the tool registry, and lifecycle hooks.

func (*Plugin) Manifest 

func (p *Plugin) Manifest() *pluginv1.PluginManifest

Manifest returns the plugin manifest.

func (*Plugin) OrchestratorClient 

func (p *Plugin) OrchestratorClient() *OrchestratorClient

OrchestratorClient returns the orchestrator QUIC client. This is nil until Run has connected to the orchestrator. Tool handlers that need storage access should call this lazily (e.g., via a closure) rather than at registration time.

func (*Plugin) ParseFlags 

func (p *Plugin) ParseFlags()

ParseFlags parses standard CLI flags and overrides builder values. Flags: --orchestrator-addr, --listen-addr, --certs-dir, --manifest

If --manifest is passed, the plugin prints its manifest as JSON to stdout and exits immediately. This is used by `orchestra install` to query plugin metadata without starting the full QUIC stack.

func (*Plugin) Run 

func (p *Plugin) Run(ctx context.Context) error

Run starts the plugin:

  1. Ensures mTLS certificates exist (auto-generates if needed).
  2. Starts the QUIC server on the listen address.
  3. Prints "READY <addr>" to stderr.
  4. If an orchestrator address is configured, connects and sends Register.
  5. Serves requests until the context is cancelled.
  6. On shutdown, calls lifecycle OnShutdown and closes connections.

func (*Plugin) Server 

func (p *Plugin) Server() *Server

Server returns the underlying QUIC server, useful for registering additional tools after Build.

type PluginBuilder 

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

PluginBuilder provides a fluent API for constructing a Plugin.

func New 

func New(id string) *PluginBuilder

New creates a new PluginBuilder with the given plugin ID.

func (*PluginBuilder) Author 

func (b *PluginBuilder) Author(a string) *PluginBuilder

Author sets the plugin author.

func (*PluginBuilder) Binary 

func (b *PluginBuilder) Binary(bin string) *PluginBuilder

Binary sets the plugin binary path.

func (*PluginBuilder) Build 

func (b *PluginBuilder) Build() *Plugin

Build constructs the Plugin. Call Run to start it.

func (*PluginBuilder) BuildWithTools 

func (b *PluginBuilder) BuildWithTools() *Plugin

BuildWithTools constructs the Plugin and registers all pending tools and handlers on its server. This is the recommended way to build a plugin.

func (*PluginBuilder) CertsDir 

func (b *PluginBuilder) CertsDir(dir string) *PluginBuilder

CertsDir sets the directory for mTLS certificates.

func (*PluginBuilder) Description 

func (b *PluginBuilder) Description(d string) *PluginBuilder

Description sets the plugin description.

func (*PluginBuilder) Export added in v0.1.3 

func (b *PluginBuilder) Export() *ExportedPlugin

Export extracts all registered tools, prompts, and storage handler from the builder without creating a QUIC server or Plugin runtime. This is used by `orchestra serve` to embed plugins in a single process.

func (*PluginBuilder) Lifecycle 

func (b *PluginBuilder) Lifecycle(hooks LifecycleHooks) *PluginBuilder

Lifecycle sets the lifecycle hooks implementation.

func (*PluginBuilder) ListenAddr 

func (b *PluginBuilder) ListenAddr(addr string) *PluginBuilder

ListenAddr sets the address the plugin server listens on.

func (*PluginBuilder) NeedsAI 

func (b *PluginBuilder) NeedsAI(providers ...string) *PluginBuilder

NeedsAI declares AI provider dependencies in the manifest.

func (*PluginBuilder) NeedsEvents 

func (b *PluginBuilder) NeedsEvents(events ...string) *PluginBuilder

NeedsEvents declares event dependencies in the manifest.

func (*PluginBuilder) NeedsStorage 

func (b *PluginBuilder) NeedsStorage(types ...string) *PluginBuilder

NeedsStorage declares storage dependencies in the manifest.

func (*PluginBuilder) NeedsTools 

func (b *PluginBuilder) NeedsTools(tools ...string) *PluginBuilder

NeedsTools declares tool dependencies in the manifest.

func (*PluginBuilder) OrchestratorAddr 

func (b *PluginBuilder) OrchestratorAddr(addr string) *PluginBuilder

OrchestratorAddr sets the address of the orchestrator to connect to.

func (*PluginBuilder) ProvidesAI added in v0.1.3 

func (b *PluginBuilder) ProvidesAI(providers ...string) *PluginBuilder

ProvidesAI declares the AI providers this plugin serves (e.g. "claude", "openai", "ollama"). The orchestrator uses this to route tool calls with a matching provider field to this plugin.

func (*PluginBuilder) ProvidesStorage 

func (b *PluginBuilder) ProvidesStorage(types ...string) *PluginBuilder

ProvidesStorage declares storage types in the manifest.

func (*PluginBuilder) ProvidesTools 

func (b *PluginBuilder) ProvidesTools(names ...string) *PluginBuilder

ProvidesTools declares tools in the manifest.

func (*PluginBuilder) ProvidesTransport 

func (b *PluginBuilder) ProvidesTransport(types ...string) *PluginBuilder

ProvidesTransport declares transport types in the manifest.

func (*PluginBuilder) RegisterPrompt added in v0.1.1 

func (b *PluginBuilder) RegisterPrompt(name string, description string, args []*pluginv1.PromptArgument, handler PromptHandler) *PluginBuilder

RegisterPrompt adds a prompt to the plugin. The prompt name is also added to the manifest's ProvidesPrompts list.

func (*PluginBuilder) RegisterStreamingTool added in v0.1.3 

func (b *PluginBuilder) RegisterStreamingTool(name string, description string, schema *structpb.Struct, handler StreamingToolHandler) *PluginBuilder

RegisterStreamingTool adds a streaming tool to the plugin. The tool name is also added to the manifest's ProvidesTools list. Streaming tools keep the QUIC stream open and send multiple StreamChunk responses before a final StreamEnd.

func (*PluginBuilder) RegisterTool 

func (b *PluginBuilder) RegisterTool(name string, description string, schema *structpb.Struct, handler ToolHandler) *PluginBuilder

RegisterTool adds a tool to the plugin. The tool name is also added to the manifest's ProvidesTools list.

func (*PluginBuilder) SetStorageHandler 

func (b *PluginBuilder) SetStorageHandler(h StorageHandler) *PluginBuilder

SetStorageHandler sets the storage handler for the plugin. This is used by storage plugins that handle StorageRead/Write/Delete/List requests.

func (*PluginBuilder) Version 

func (b *PluginBuilder) Version(v string) *PluginBuilder

Version sets the plugin version.

type PromptHandler added in v0.1.1 

type PromptHandler func(ctx context.Context, req *pluginv1.PromptGetRequest) (*pluginv1.PromptGetResponse, error)

PromptHandler is the function signature for handling prompt get requests.

type Server 

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

Server is a QUIC server that accepts plugin protocol requests (tool calls, list_tools, health, boot, shutdown, storage) from an orchestrator or other clients.

func NewServer 

func NewServer(addr string, tlsConfig *tls.Config) *Server

NewServer creates a new QUIC server bound to the given address.

func (*Server) ActualAddr 

func (s *Server) ActualAddr() string

ActualAddr returns the address the server is listening on. This blocks until the server has started listening. Returns empty string if the server hasn't started.

func (*Server) ListenAndServe 

func (s *Server) ListenAndServe(ctx context.Context) error

ListenAndServe starts the QUIC listener and accepts connections until the context is cancelled. Each connection is handled in its own goroutine.

func (*Server) ListenAndServeTCP added in v0.1.3 

func (s *Server) ListenAndServeTCP(ctx context.Context, addr string) error

ListenAndServeTCP starts a plain TCP listener on the given address and serves the same length-delimited Protobuf protocol as ListenAndServe (QUIC). This is used by clients (e.g. Swift/macOS) that cannot open raw QUIC streams via Network.framework. Each TCP connection handles one request/response.

func (*Server) RegisterPrompt added in v0.1.1 

func (s *Server) RegisterPrompt(name string, description string, args []*pluginv1.PromptArgument, handler PromptHandler)

RegisterPrompt adds a prompt to the server's registry.

func (*Server) RegisterStreamingTool added in v0.1.3 

func (s *Server) RegisterStreamingTool(name string, description string, schema *structpb.Struct, handler StreamingToolHandler)

RegisterStreamingTool adds a streaming tool to the server's registry.

func (*Server) RegisterTool 

func (s *Server) RegisterTool(name string, description string, schema *structpb.Struct, handler ToolHandler)

RegisterTool adds a tool to the server's registry.

func (*Server) SetLifecycleHooks 

func (s *Server) SetLifecycleHooks(hooks LifecycleHooks)

SetLifecycleHooks sets the lifecycle hook implementation for boot/shutdown.

func (*Server) SetStorageHandler 

func (s *Server) SetStorageHandler(h StorageHandler)

SetStorageHandler sets the storage handler for dispatching storage requests.

func (*Server) Subscribe added in v0.1.3 

func (s *Server) Subscribe(topic string, filters map[string]string, handler EventHandler) string

Subscribe registers a local event handler for a topic. Returns subscription ID.

func (*Server) Unsubscribe added in v0.1.3 

func (s *Server) Unsubscribe(subscriptionID string)

Unsubscribe removes a local event subscription.

type StorageHandler 

type StorageHandler interface {
	Read(ctx context.Context, req *pluginv1.StorageReadRequest) (*pluginv1.StorageReadResponse, error)
	Write(ctx context.Context, req *pluginv1.StorageWriteRequest) (*pluginv1.StorageWriteResponse, error)
	Delete(ctx context.Context, req *pluginv1.StorageDeleteRequest) (*pluginv1.StorageDeleteResponse, error)
	List(ctx context.Context, req *pluginv1.StorageListRequest) (*pluginv1.StorageListResponse, error)
}

StorageHandler defines the interface that storage plugins must implement to handle storage requests dispatched by the orchestrator.

type StreamingToolHandler added in v0.1.3 

type StreamingToolHandler func(ctx context.Context, req *pluginv1.StreamStart, chunks chan<- []byte) error

StreamingToolHandler is the function signature for streaming tool invocations. The handler sends chunks via the provided channel and returns when done. Each []byte chunk is sent as a StreamChunk to the client. The content_type parameter in StreamStart determines how chunks are interpreted.

type ToolHandler 

type ToolHandler func(ctx context.Context, req *pluginv1.ToolRequest) (*pluginv1.ToolResponse, error)

ToolHandler is the function signature for handling tool invocations.

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.