Documentation
¶
Overview ¶
Package client provides a standard PlugKit host implementation. It allows launching and communicating with external plugin processes using CBOR-encoded messages over standard input and output.
Package client provides a low-level PlugKit host implementation. The RawClient allows for direct handling of plugin communication by exposing decoded CBOR messages and letting the user define custom message logic
`Copyright (c) 2025 Michał Hodur SPDX-License-Identifier: MIT
Index ¶
- func HandleMessage[In any, Out any](c WrappedMessageHandler, name string, handler func(In) (Out, error))
- type RawClient
- type RawClientImpl
- type RawStreamClient
- type RawStreamClientImpl
- type SmartPlugClient
- func (c *SmartPlugClient) HandleMessageType(name string, handler func(any) (any, error))
- func (c *SmartPlugClient) RespondRaw(t string, v any) error
- func (c *SmartPlugClient) RunCommand(name codes.MessageCode, v any) (codes.PluginExitReason, any, error)
- func (c *SmartPlugClient) SetCommand(command string)
- func (c *SmartPlugClient) StartLocal() error
- type WrappedMessageHandler
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func HandleMessage ¶ added in v0.1.0
func HandleMessage[In any, Out any](c WrappedMessageHandler, name string, handler func(In) (Out, error))
HandleMessage is a generic convenience wrapper for HandleMessageType. It allows registering a strongly-typed handler function without manual wrapping.
The handler should have the form: func(In) (Out, error), where In is the expected input type (after CBOR decoding), and Out is the return type. Internally, the handler is wrapped using WrapHandler to conform to the PlugKit internal interface.
Types ¶
type RawClient ¶ added in v0.2.0
type RawClient struct {
Impl RawClientImpl
// contains filtered or unexported fields
}
RawClient provides a minimalistic PlugKit host implementation. Unlike SmartPlugClient, it does not automatically decode or route messages by type.
Instead, it allows the user to implement their own message handler via RawClientImpl. This enables advanced use cases or full control over the plugin protocol.
Communication occurs over CBOR-encoded envelopes using stdin and stdout pipes.
func NewRawClient ¶ added in v0.2.0
func NewRawClient(name string, impl RawClientImpl) *RawClient
NewRawClient returns plugin with impl implementation
func (*RawClient) RunCommand ¶ added in v0.2.0
func (c *RawClient) RunCommand(name codes.MessageCode, v any) (codes.PluginExitReason, any, error)
RunCommand sends a command (message) to the plugin and waits for its response.
The message is wrapped in an Envelope with the given message code and payload. Based on the plugin's response, this method returns an appropriate PluginExitReason, a handler result (if any), and an error.
The second return value (of type any) represents the value returned by a matching message handler registered via HandleMessageType. If the plugin responds with a recognized message type and the corresponding handler executes successfully, its return value is passed back to the caller.
If no matching handler is found or the handler fails, the returned result will be nil. In general, it's recommended that plugins return a single, well-defined response type, or exit with an appropriate error code when things go wrong. Supporting multiple possible response types is possible, but may require custom decoding logic on the client side.
func (*RawClient) SetCommand ¶ added in v0.2.0
SetCommand sets the executable path or name of the plugin binary. This must be set before calling StartLocal().
func (*RawClient) StartLocal ¶ added in v0.2.0
StartLocal starts the plugin process using the configured command.
It establishes CBOR-based communication over stdin/stdout pipes. The method must be called before sending any commands to the plugin.
type RawClientImpl ¶ added in v0.2.0
RawClientImpl defines the interface that must be implemented by users of RawClient. It is responsible for handling incoming messages manually.
type RawStreamClient ¶ added in v0.2.0
type RawStreamClient struct {
Impl RawStreamClientImpl
// contains filtered or unexported fields
}
RawStreamClient provides a streaming PlugKit host implementation.
It launches the plugin process and maintains an open communication loop, continuously decoding incoming CBOR messages and dispatching them to the provided handler.
This structure is well-suited for long-running plugins with complex protocols or event-based logic.
func NewRawStreamClient ¶ added in v0.2.0
func NewRawStreamClient(impl RawStreamClientImpl, command string) *RawStreamClient
NewRawStreamClient constructs a new RawStreamClient with the given handler implementation.
The plugin process is not started automatically — use Start() and then Run() to begin communication.
func (*RawStreamClient) Run ¶ added in v0.2.0
func (c *RawStreamClient) Run()
Run begins the main communication loop with the plugin.
This method blocks until Stop() is called or the stream ends. It spawns a background loop to decode messages and invokes the handler logic for each received message.
func (*RawStreamClient) Send ¶ added in v0.2.0
func (c *RawStreamClient) Send(messageCode string, payload cbor.RawMessage)
Send sends a response message back to the plugin.
The message type and CBOR payload must be specified explicitly.
func (*RawStreamClient) Start ¶ added in v0.2.0
func (c *RawStreamClient) Start() error
Start initializes and starts the plugin process using the configured command.
It sets up CBOR encoders and decoders for stdin/stdout communication. Must be called before Run().
func (*RawStreamClient) Stop ¶ added in v0.2.0
func (c *RawStreamClient) Stop()
Stop signals the RawStreamClient to stop receiving messages.
It cancels the internal context and allows the loop to exit gracefully.
func (*RawStreamClient) Wrapper ¶ added in v0.2.0
func (c *RawStreamClient) Wrapper(msg messages.Envelope)
Wrapper wraps a single message and processes it via the implementation's Handle method.
It constructs a response and sends it back to the plugin. This function is run as a goroutine for each message.
type RawStreamClientImpl ¶ added in v0.2.0
type RawStreamClientImpl interface {
Handle(kind string, payload *cbor.RawMessage)
Mount(c *RawStreamClient)
CloseSignal()
}
RawStreamClientImpl must be implemented by consumers of RawStreamClient. It defines the logic for handling incoming messages and sending responses.
- Handle is invoked for each incoming message and must return the message type and CBOR payload of the response. - Mount is called before the communication loop starts. - CloseSignal is triggered when the stream is closing.
type SmartPlugClient ¶ added in v0.1.0
type SmartPlugClient struct {
Handlers map[string]func(any) (any, error)
// contains filtered or unexported fields
}
SmartPlugClient represents a PlugKit host instance. It manages the lifecycle and communication of a plugin process.
Communication is handled via stdin/stdout pipes using CBOR encoding. Messages are exchanged as Envelope structures with a defined message type and payload.
func NewSmartClient ¶ added in v0.1.0
func NewSmartClient(name string) *SmartPlugClient
NewSmartClient creates a new SmartPlugClient instance with the given plugin command. The plugin is not started automatically — use StartLocal() to launch it.
func (*SmartPlugClient) HandleMessageType ¶ added in v0.1.0
func (c *SmartPlugClient) HandleMessageType(name string, handler func(any) (any, error))
HandleMessageType registers a handler for a specific incoming message type.
Handlers are called when a message of the given type is received from the plugin.
func (*SmartPlugClient) RespondRaw ¶ added in v0.1.0
func (c *SmartPlugClient) RespondRaw(t string, v any) error
RespondRaw sends a raw response to the plugin with a specified type and payload.
This method bypasses the MessageCode abstraction and can be used for ad-hoc messages.
func (*SmartPlugClient) RunCommand ¶ added in v0.1.0
func (c *SmartPlugClient) RunCommand(name codes.MessageCode, v any) (codes.PluginExitReason, any, error)
RunCommand sends a command (message) to the plugin and waits for its response.
The message is wrapped in an Envelope with the given message code and payload. Based on the plugin's response, this method returns an appropriate PluginExitReason, a handler result (if any), and an error.
The second return value (of type any) represents the value returned by a matching message handler registered via HandleMessageType. If the plugin responds with a recognized message type and the corresponding handler executes successfully, its return value is passed back to the caller.
If no matching handler is found or the handler fails, the returned result will be nil. In general, it's recommended that plugins return a single, well-defined response type, or exit with an appropriate error code when things go wrong. Supporting multiple possible response types is possible, but may require custom decoding logic on the client side.
func (*SmartPlugClient) SetCommand ¶ added in v0.1.0
func (c *SmartPlugClient) SetCommand(command string)
SetCommand sets the executable path or name of the plugin binary. This must be set before calling StartLocal().
func (*SmartPlugClient) StartLocal ¶ added in v0.1.0
func (c *SmartPlugClient) StartLocal() error
StartLocal starts the plugin process using the provided command.
It sets up CBOR encoding/decoding over stdin/stdout pipes. Returns an error if the plugin cannot be started or the communication setup fails.
Source Files