Module plugin_protocol 

JSON-RPC over stdio wire protocol for SecretSource plugins per ADR-021 §10 (subprocess plugin extension).

The host (devboy-tools) and the plugin exchange one request and one response per line — the same newline-delimited framing the secrets-agent daemon uses. Methods correspond 1:1 to the crate::source::SecretSource trait so an out-of-tree plugin can implement any backend the framework doesn’t ship natively (Doppler, AWS Secrets Manager, custom HSMs, …) without touching the core.

Method names

RPC method	Trait method
secret_source.init	(no equivalent — capability handshake)
secret_source.is_available	SecretSource::is_available
secret_source.get	SecretSource::get
secret_source.list	SecretSource::list
secret_source.validate	SecretSource::validate

init is the first call — the host sends config and gets back the plugin’s name + capability bitset. Subsequent calls happen against an initialised session.

Wire format

Each line is a complete JSON-RPC 2.0 frame (id + method or id + result/error). The params and result payloads are typed via the enums below.

What this module does not do

Spawn the subprocess, manage its lifetime, or implement retry / restart semantics. Those concerns live in the plugin client (P15.2) which builds on top of these wire types.

Structs

GetParams

GetResult

InitParams

InitResult

IsAvailableResult

JsonRpcVersion

Newtype around the literal "2.0" so a malformed frame fails fast at parse time instead of at the dispatcher.

ListResult

PluginRpcRequest

Wrapper for a single request line. Always includes jsonrpc = "2.0", an integer id, and a method name with typed params.

PluginRpcResponse

Wrapper for a single response line. Carries either result or error.

RemoteRefDto

ValidateParams

ValidateResult

Enums

IsAvailableStatus

Ground states the plugin can report. Mirrors crate::source::SourceStatus but kept independent so the wire protocol can evolve separately from the in-process trait.

PluginError

Error variants the plugin can return. The codes mirror JSON-RPC 2.0 reserved ranges; payload is structured so the host can map back to crate::source::SourceError without regex-parsing strings.

PluginRequest

One request the host sends. Tagged by method for clean JSON-RPC 2.0 framing and so a future method addition can be added as a new variant without touching dispatch.

PluginResponse

Successful reply payload. Variants mirror the request set (minus IsAvailable/Validate/List which have their own shapes).

RpcOutcome

result xor error — one of, never both. Tagged internally so a malformed response that includes both fields fails to deserialise.

Constants

PROTOCOL_VERSION

Pinned protocol version. Bumped on a breaking change so host + plugin can refuse to talk if the major versions don’t match.