PluginRPC is an Protobuf RPC framework for plugins. It enables writing plugins defined by Protobuf services while only relying on CLI primitives such as args, stdin, and stdout. PluginRPC has no reliance on network calls. Individual RPCs are invoked via arguments passed to the CLI plugin, requests are sent on stdin, and responses are sent on stdout. It's everything you need to use Protobuf services to represent your plugin API without any of the cruft.
PluginRPC has the following goals:
- Make it possible to evolve both the PluginRPC protocol and the APIs for individual plugins in backward-compatible ways over time.
- Make it possible to invoke multiple methods as part of a plugin. Many plugin frameworks only provide for a single entrypoint. In contrast, PluginRPC provides the full power of Protobuf services: multiple services, and multiple RPCs per service, can be exposed.
- Expose the plugin interface in CLI-idiomatic ways. PluginRPC exposes individual RPCs as sub-commands with flags for control, optionally allowing the specific sub-commands to be customizable. PluginRPC attempts to consume and produce requests and responses in a manner that will be readable by humans invoking the sub-commands.
- Make it easy to call plugins even in the absence of an official language-specific library.
PluginRPC currently has one official language library:
Go is a natural language to write plugins in, and we have a direct use case for an RPC library in Go for our custom lint and breaking change plugins in buf. However, PluginRPC is purposefully designed to be simple to implement in any language. If there is sufficient demand, we may provide official implementations for other languages in the future.
If using Protobuf to write plugins, there's traditionally been two mechanisms:
- Have a single request message type sent over stdin, and return a single response message type
over stdout. This is how
protoc
operates, for example, taking in aCodeGeneratorRequest
and sending back aCodeGeneratorRequest
over stdout. This is very simple, however it makes doing anything else extremely difficult. All plugin API evolution needs to remain within these single messages for all time, and providing functionality for multiple methods is awkward at best (for example, via use ofoneofs
). Multiple content types cannot be supported. - Bring a full-powered network RPC framework into the mix. This is how go-plugin operates, for example, making a plugin expose a gRPC service, and then doing an exec/kill dance to bring the plugin up temporarily and expose it on a port, call the required method, and then kill the plugin entirely. While effective in allowing lots of flexibility, it's bringing in a very complicated framework to solve a simple engineering problem, adding brittleness, requiring network calls, and not allowing plugins to remain idiomatic CLI tools
PluginRPC provides the best of both worlds: simple CLI constructs with all the power you require. If you want to use Protobuf services across the network, use ConnectRPC. If you want to use Protobuf services to write plugins, use PluginRPC.
A plugin is implemented as an executable binary. Plugins may be implemented on sub-commands of the
binary. For example, given the binary acme
, a plugin author may choose to implement the plugin
under the sub-command acme plug
. PluginRPC frameworks will provide clients the ability to specify
this sub-command (in pluginrpc-go, this is done via
ExecRunnerWithArgs
).
We'll refer to the executable and subsequent base args as $PLUGIN
below. In our example here,
acme plug
is what we refer to as $PLUGIN
. We'll also assume that the plugin wants to implement
the following Protobuf service:
package acme.foo.v1;
service FooService {
rpc Bar(BarRequest) returns (BarResponse);
rpc Baz(BazRequest) returns (BazResponse);
}
message BarRequest {
string id = 1;
}
message BarResponse {
string bar = 1;
}
message BazRequest {}
message BazResponse {
string baz = 1;
}
All plugins must respond to three flags:
$PLUGIN --protocol
. This must print the PluginRPC protocol version to stdout with any number of subsequent newlines and exit with code0
. The only protocol version right now is1
, so plugins must print1
to stdout (or1\n
,1\n\n
, etc).
Plugin callers can use --protocol
to understand which PluginRPC protocol version the plugin
supports. In the future, if there are newer backwards-incompatible versions of the PluginRPC
protocol, these will be exposed as versions 2
, 3
, etc.
-
$PLUGIN --spec
. This must print a serializedpluginrpc.v1.Spec
to stdout and exit with code0
. -
$PLUGIN --format
. This controls the serialization format of requests, responses, errors, and the result of the--spec
flag. The current valid values are--format binary
and--format json
. All plugins must respond to--format binary
and--format json
.
Here's an example response to --spec --format json
on stdout:
{
"procedures": [
{
"path": "/acme.foo.v1.FooService/Bar",
"args": ["bar"]
},
{
"path": "/acme.foo.v1.FooService/Baz",
"args": ["baz"]
}
]
}
This specifies that:
- The
Bar
RPC is invoked by calling$PLUGIN bar
. - The
Baz
RPC is invoked by calling$PLUGIN baz
.
The procedure.args
field is optional. If args
are not specified, a procedure can be invoked with
$PLUGIN <path>
. For example, if args
were not specified for Baz
, then
$PLUGIN /acme.foo.v1.FooService/Baz
would invoke the Baz
RPC.
An RPC is invoked by sending a serialized
pluginrpc.v1.Request
to stdin.
Plugins must support nothing being written to stdin, which will be interpreted as a request with an empty value.
An RPC will respond on stdout a serialized
pluginrpc.v1.Response
.
The plugin will exit with code 0
unless there is a system error.
A response value may be present even if there is a
pluginrpc.v1.Error
on the Response
.
If a plugin exits with any code other than 0
, this is considered a system error, and stdout is
undefined and will not be processed.
A plugin may always write to stderr as it wishes.
This framework is in active development, and should not be considered stable.
Offered under the Apache 2 license