Documentation
¶
Overview ¶
Package plug provides the default runtime for a PlugKit-compatible plugin.
A SmartPlug is a minimal, one-shot command handler that receives a CBOR-encoded Envelope from the host via stdin, processes it using a registered handler, sends a response back to stdout, and terminates with a specific exit code.
This simple model allows for sandboxed, transactional plugin operations using structured messaging.
Index ¶
- func HandleSmartPlugMessage[In any](s *SmartPlug, messageType string, ...)
- func WrapSmartPlugTypedHandler[In any](fn func(In) (*messages.Result, codes.PluginExitReason, error)) func([]byte) (*messages.Result, codes.PluginExitReason, error)
- type RawPlug
- type RawPlugImpl
- type RawStreamPlug
- type RawStreamPlugImpl
- type SmartPlug
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HandleSmartPlugMessage ¶ added in v0.1.0
func WrapSmartPlugTypedHandler ¶ added in v0.1.0
func WrapSmartPlugTypedHandler[In any]( fn func(In) (*messages.Result, codes.PluginExitReason, error), ) func([]byte) (*messages.Result, codes.PluginExitReason, error)
WrapSmartPlugTypedHandler adapts a strongly-typed plugin handler to the func([]byte) (*messages.Result, codes.PluginExitReason, error) form expected by SmartPlug.
It performs CBOR decoding of the input and passes the resulting value to the user-defined handler.
Types ¶
type RawPlug ¶ added in v0.2.0
type RawPlug struct {
PlugImpl RawPlugImpl
// contains filtered or unexported fields
}
RawPlug provides a low-level plugin host that communicates over stdin and stdout using CBOR encoding. It reads and writes Envelope messages, and delegates the handling of payloads to the user-defined RawPlugImpl. RawPlug is the most minimal building block for creating plugins with custom protocols or structure.
func NewRawPlug ¶ added in v0.2.0
func NewRawPlug(impl RawPlugImpl) *RawPlug
NewRawPlug creates a new RawPlug with the given user-defined implementation.
type RawPlugImpl ¶ added in v0.2.0
type RawPlugImpl interface {
Handle(kind string, payload cbor.RawMessage) (messageCode string, response cbor.RawMessage, err error)
Mount(c *RawPlug)
}
RawPlugImpl is the interface that every raw plug implementation must satisfy.
Handle receives the raw CBOR payload extracted from the envelope and returns: - a message code indicating the result (e.g., "ok", "unsupported", custom-defined, etc.), - a CBOR-encoded response payload to be sent back to the host, - or an error, which will cause the RawPlug to send a operation failure response to the host.
If an error is returned from Handle, the plug is considered to have failed the request. In all other cases, the message is treated as successfully handled, even if the operation type was unknown or invalid — it's up to the plugin to decide how to respond. This is intentional, as RawPlug provides no automatic validation or dispatching — full control is left to the implementer.
Mount is called once at startup and provides the plugin with access to its host context, which can be used to configure or initialize internal state.
type RawStreamPlug ¶ added in v0.2.0
type RawStreamPlug struct {
PlugImpl RawStreamPlugImpl
// contains filtered or unexported fields
}
RawStreamPlug is a low-level CBOR-based plugin communication framework.
It provides raw input/output streams without automatic validation or message dispatching. The plugin implementation (RawStreamPlugImpl) is fully responsible for interpreting incoming messages and producing appropriate responses.
RawStreamPlug handles system signals (e.g., SIGINT, SIGTERM) and supports graceful shutdown via internal signals. Each incoming message is processed asynchronously in its own goroutine. Ordering of responses is not guaranteed and must be handled by the plugin if needed.
Usage:
- Initialize RawStreamPlug with a RawStreamPlugImpl implementation.
- Call Main() to start the event loop.
- Call Shutdown() to terminate the plug from the implementation.
func NewRawStreamPlug ¶ added in v0.2.0
func NewRawStreamPlug(impl RawStreamPlugImpl) *RawStreamPlug
func (*RawStreamPlug) Loop ¶ added in v0.2.0
func (p *RawStreamPlug) Loop()
Loop contains the main logic of the RawStreamPlug. It takes care of decoding the incoming CBOR payload and sends it to handler asynchronously. Handler must decode the type of the message and respond accordingly. This plug type does not guarantee the order of incoming and outgoing messages. It is up to implementer to handle logic.
func (*RawStreamPlug) Main ¶ added in v0.2.0
func (p *RawStreamPlug) Main()
Main starts the main loop of the RawStreamPlug.
func (*RawStreamPlug) Send ¶ added in v0.2.0
func (p *RawStreamPlug) Send(messageCode string, payload cbor.RawMessage)
Send sends an Envelope with the message code and CBOR payload to stdout.
func (*RawStreamPlug) Shutdown ¶ added in v0.2.0
func (p *RawStreamPlug) Shutdown()
Shutdown sends signal to shut down the plug. As the plug can be long living, it has to have a control mechanism to shut down the plug from the implementation.
type RawStreamPlugImpl ¶ added in v0.2.0
type RawStreamPlugImpl interface {
Handle(kind string, payload cbor.RawMessage)
Mount(c *RawStreamPlug)
CloseSignal()
}
RawStreamPlugImpl is the interface that every raw plug implementation must satisfy.
Handle receives the raw CBOR payload extracted from the envelope and returns: - a message code indicating the result (e.g., "ok", "unsupported", custom-defined, etc.), - a CBOR-encoded response payload to be sent back to the host, - or an error, which will cause the RawPlug to send a operation failure response to the host.
If an error is returned from Handle, the plug is considered to have failed the request. In all other cases, the message is treated as successfully handled, even if the operation type was unknown or invalid — it's up to the plugin to decide how to respond. This is intentional, as RawStreamPlug provides no automatic validation or dispatching — full control is left to the implementer.
Mount is called once at startup and provides the plugin with access to its host context, which can be used to configure or initialize internal state. CloseSignal is called when the plug receives external shutdown signal (i.e. OS, plug host etc).
type SmartPlug ¶ added in v0.1.0
type SmartPlug struct {
Handlers map[string]func([]byte) (result *messages.Result, exitReason codes.PluginExitReason, e error)
// contains filtered or unexported fields
}
SmartPlug is a most standard type of plug. It supports one-off comand. SmartPlug is the one of the runtime structures for a PlugKit plugin.
It supports registering handlers for specific message types and handles a single Envelope message per execution.
func New ¶
func New() *SmartPlug
New creates a new SmartPlug instance wired to stdin and stdout.
A default "exit" message handler is registered, which allows the host to gracefully terminate the plugin if needed.
func (*SmartPlug) Finish ¶ added in v0.1.0
func (h *SmartPlug) Finish(message string, code codes.PluginExitReason)
Finish sends a PluginFinish message and terminates the plugin process.
The plugin will exit with the given PluginExitReason code.
func (*SmartPlug) HandleMessageType ¶ added in v0.1.0
func (h *SmartPlug) HandleMessageType(name string, handler func([]byte) (*messages.Result, codes.PluginExitReason, error))
HandleMessageType registers a function to handle a given message type.
The handler receives raw CBOR-encoded data from the Envelope and is responsible for decoding and processing it.
The handler must return a messages.Result (or nil), a PluginExitReason, and an error (or nil). message.Result must contain status code, and value of the response.
func (*SmartPlug) Main ¶ added in v0.1.0
Main runs the main routine of the plugin.
It waits for a single incoming message, dispatches it to the appropriate handler, sends back any response, and terminates with the declared PluginExitReason.
This function is designed for one-shot plugin invocations. It should be called from the plugin's main() function.
Source Files