plugin

package
v0.12.0 Latest Latest
Warning

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

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

Documentation

Index

Constants

View Source 
const (
	// ProtocolVersion is the JSON-RPC plugin protocol version supported by this host.
	ProtocolVersion = "1.0"
	// NamespacePrefix is the host-owned namespace for discovered plugin libraries.
	NamespacePrefix = "plugin."
)
View Source 
const ControlLibraryName = "scriptling.plugin"
View Source 
const DefaultReleaseTimeout = 2 * time.Second

DefaultReleaseTimeout is used by Release and GC finalizers when no caller context is available. Use ReleaseWithContext for request-scoped cleanup.

Variables

This section is empty.

Functions

func Logger added in v0.11.0 

func Logger(ctx context.Context) logger.Logger

Logger returns a call-scoped proxy to the manager's host logger. It uses ctx to find the active plugin call runtime, so plugin code should request it from functions, constructors, methods, or property accessors and should not store it globally. If ctx is not attached to an active plugin call, Logger returns a no-op logger.

func NewControlLibrary 

func NewControlLibrary(manager *Manager) *object.Library

func NormalizeLibraryName 

func NormalizeLibraryName(name string) string

NormalizeLibraryName returns name in the host-owned plugin namespace.

func RegisterLibraries 

func RegisterLibraries(registrar Registrar, manager *Manager)

func Release 

func Release(obj object.Object) error

func ReleaseWithContext 

func ReleaseWithContext(ctx context.Context, obj object.Object) error

ReleaseWithContext explicitly releases a remote plugin object using ctx.

Types

type Callback 

type Callback interface {
	Call(ctx context.Context, args ...any) (Value, error)
}

Callback is a host callback passed into a plugin call. It is valid only until the outer plugin function, constructor, or method returns.

type CallbackRef 

type CallbackRef struct {
	ID string `json:"id"`
}

CallbackRef identifies a callback valid during one outer plugin call.

type ClassSchema 

type ClassSchema struct {
	Name        string           `json:"name"`
	Description string           `json:"description,omitempty"`
	Constructor FunctionSchema   `json:"constructor,omitempty"`
	Methods     []FunctionSchema `json:"methods,omitempty"`
	Properties  []PropertySchema `json:"properties,omitempty"`
	Source      string           `json:"source,omitempty"`
}

ClassSchema describes a plugin class and its methods.

type Client 

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

func (*Client) CallFunction 

func (c *Client) CallFunction(ctx context.Context, name string, args []Value, kwargs map[string]Value) (Value, error)

func (*Client) CallFunctionWithCallbacks 

func (c *Client) CallFunctionWithCallbacks(ctx context.Context, name string, args []Value, kwargs map[string]Value, callbacks *callbackSet) (Value, error)

func (*Client) CallMethod 

func (c *Client) CallMethod(ctx context.Context, objectID, method string, args []Value, kwargs map[string]Value) (Value, error)

func (*Client) CallMethodWithCallbacks 

func (c *Client) CallMethodWithCallbacks(ctx context.Context, objectID, method string, args []Value, kwargs map[string]Value, callbacks *callbackSet) (Value, error)

func (*Client) Close 

func (c *Client) Close() error

Close shuts down this plugin process.

func (*Client) DestroyObject 

func (c *Client) DestroyObject(ctx context.Context, objectID string) error

func (*Client) Health 

func (c *Client) Health() error

Health reports whether this plugin process and stdio transport are healthy.

func (*Client) Metadata 

func (c *Client) Metadata() Metadata

func (*Client) NewObject 

func (c *Client) NewObject(ctx context.Context, class string, args []Value, kwargs map[string]Value) (*RemoteRef, error)

func (*Client) NewObjectWithCallbacks 

func (c *Client) NewObjectWithCallbacks(ctx context.Context, class string, args []Value, kwargs map[string]Value, callbacks *callbackSet) (*RemoteRef, error)

type ConstantSchema 

type ConstantSchema struct {
	Name  string `json:"name"`
	Value Value  `json:"value"`
}

ConstantSchema describes a plugin constant.

type FunctionSchema 

type FunctionSchema struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Source      string `json:"source,omitempty"`
}

FunctionSchema describes a plugin function or supplied wrapper source.

type Manager 

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

func NewManager 

func NewManager(log logger.Logger, crashHandler ...func(name string, err error)) *Manager

NewManager creates an empty plugin manager. If log is not nil, plugin log records emitted through Logger(ctx) are forwarded to it. If crashHandler is provided, it is called when a loaded plugin process exits unexpectedly.

func (*Manager) AddDir 

func (m *Manager) AddDir(dir string)

AddDir adds a directory whose executable files should be loaded as plugins.

func (*Manager) Close 

func (m *Manager) Close() error

Close shuts down all loaded plugin processes.

func (*Manager) Get 

func (m *Manager) Get(name string) (*Client, bool)

Get returns a loaded plugin client by short or fully-qualified library name.

func (*Manager) Health 

func (m *Manager) Health() map[string]error

Health returns loaded plugins whose process or stdio transport is unhealthy.

func (*Manager) List 

func (m *Manager) List() []Metadata

List returns metadata for all loaded plugins sorted by library name.

func (*Manager) Load 

func (m *Manager) Load(ctx context.Context) error

Load eagerly starts all executable plugins in configured plugin directories.

func (*Manager) SetCrashHandler 

func (m *Manager) SetCrashHandler(handler func(name string, err error))

SetCrashHandler installs a callback for loaded plugin processes that exit unexpectedly. The handler is not called for normal manager shutdown.

func (*Manager) SetLogger added in v0.11.0 

func (m *Manager) SetLogger(log logger.Logger)

SetLogger installs the host logger used for log records emitted by plugins.

func (*Manager) Warnings 

func (m *Manager) Warnings() []string

Warnings returns non-fatal plugin load warnings collected by the manager.

type Metadata 

type Metadata struct {
	Name         string   `json:"name"`
	Version      string   `json:"version"`
	Description  string   `json:"description"`
	Transport    string   `json:"transport,omitempty"`
	Capabilities []string `json:"capabilities,omitempty"`
	Schema       Schema   `json:"schema"`
}

Metadata describes a loaded plugin library.

type PropertySchema added in v0.11.0 

type PropertySchema struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
	Settable    bool   `json:"settable,omitempty"`
}

PropertySchema describes a plugin class property.

type RPCError 

type RPCError struct {
	Code    int    `json:"code"`
	Message string `json:"message"`
}

func (*RPCError) Error 

func (e *RPCError) Error() string

type Registrar 

type Registrar interface {
	RegisterLibrary(*object.Library)
}

type RemoteRef 

type RemoteRef struct {
	Library string `json:"library"`
	Class   string `json:"class"`
	ID      string `json:"id"`
}

RemoteRef identifies an object stored in a plugin process.

type Schema 

type Schema struct {
	Functions []FunctionSchema `json:"functions"`
	Classes   []ClassSchema    `json:"classes"`
	Constants []ConstantSchema `json:"constants"`
}

Schema describes functions, classes, and constants exposed by a plugin.

type ScriptLibraryRegistrar 

type ScriptLibraryRegistrar interface {
	RegisterScriptLibrary(name string, script string) error
}

type Server 

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

func NewServer 

func NewServer(name, version, description string) *Server

func (*Server) Constant 

func (s *Server) Constant(name string, value any) *Server

func (*Server) RegisterClass 

func (s *Server) RegisterClass(builder *object.ClassBuilder) *Server

func (*Server) RegisterFunc 

func (s *Server) RegisterFunc(name string, builder *object.FunctionBuilder) *Server

func (*Server) RegisterScriptClass 

func (s *Server) RegisterScriptClass(name string, source string) *Server

func (*Server) RegisterScriptFunc 

func (s *Server) RegisterScriptFunc(name string, source string) *Server

func (*Server) Run 

func (s *Server) Run() error

func (*Server) RunIO 

func (s *Server) RunIO(input io.Reader, output io.Writer) error

func (*Server) Wrapper 

func (s *Server) Wrapper(name string, source string) *Server

type Value 

type Value struct {
	Type     string           `json:"type"`
	Value    any              `json:"value,omitempty"`
	Items    []Value          `json:"items,omitempty"`
	Entries  map[string]Value `json:"entries,omitempty"`
	Remote   *RemoteRef       `json:"remote,omitempty"`
	Callback *CallbackRef     `json:"callback,omitempty"`
}

Value is the JSON-RPC transport representation of Scriptling values.

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.