PluginService

When to use this pageCopy Anchor Link

Read it when you implement a plugin from scratch against the wire contract, when you write a test host, or when you need the exact rejection rules the host applies to what a plugin returns. If you only want to build a plugin with the Go packages, start with Build a custom plugin in Go and return here for the details.

The other half of the plugin boundary is HostService: the plugin calls it, from inside an Invoke, to log, emit evidence and obtain credential handles.

The serviceCopy Anchor Link

PluginService has six RPCs. These lines are copied from plugin.proto; the annotation bodies are shown in the annotation table.

service PluginService {
  rpc Handshake(HandshakeRequest) returns (HandshakeResponse) { ... }
  rpc GetManifest(GetManifestRequest) returns (GetManifestResponse) { ... }
  rpc GetDescriptors(GetDescriptorsRequest) returns (GetDescriptorsResponse) { ... }
  rpc Invoke(InvokeRequest) returns (stream InvokeResponse) { ... }
  rpc Health(HealthRequest) returns (HealthResponse) { ... }
  rpc Shutdown(ShutdownRequest) returns (ShutdownResponse) { ... }
}

Only Invoke is server-streaming. Every element of the service is since: "1.0.0".

Rules that hold for every RPCCopy Anchor Link

• Every RPC except Invoke is host-only lifecycle. Invoke carries an action whose target is a method in a numinance.ports.* package; the target's annotations in the host's descriptor copy govern it, never Invoke's own.
• No PluginService RPC declares evidence. The host records each lifecycle call in its own lifecycle evidence and each Invoke under the target's declared evidence.
• Every string is at most 1024 bytes and every repeated field at most 256 entries unless a field states otherwise. Over-limit input is rejected, never truncated. Duplicate entries in any repeated field are rejected.
• The host reads every response through a size-limited reader with a per-call timeout.
• A rejection names an index-based field path and the violated bound, never the offending value.

Annotations of each RPCCopy Anchor Link

Invoke is RISK_CLASS_PRIVILEGED because it carries one policy-approved action to code that may touch customer systems. Its exec is OPERATION because the stream carries OPERATION targets, not because Invoke has the start, get and cancel shape. The meaning of each annotation is in Governance annotations.

HandshakeCopy Anchor Link

Handshake negotiates the protocol version, the spec version and the capabilities between host and plugin.

message HandshakeRequest {
  string spec_version = 1;
  repeated uint32 protocol_versions = 2;
  repeated string ports = 3;
  repeated string capabilities = 4;
}

message HandshakeResponse {
  uint32 protocol_version = 1;
  string spec_version = 2;
  repeated string capabilities = 3;
}

(Per-field [(numinance.annotations.v1.field).since = "1.0.0"] options omitted.)

HandshakeRequest fieldsCopy Anchor Link

HandshakeResponse fieldsCopy Anchor Link

The response is at most 64 KiB serialized.

Semantics worth knowingCopy Anchor Link

• The host records the negotiated versions in its own lifecycle evidence; the plugin declares none.
• The host writes the negotiated protocol version into the lockfile at install and offers only that version at run time. A plugin cannot select a lower protocol later.
• Negotiation is an intersection, never a union: a plugin cannot claim a capability the manifest does not declare, and the host will not enable one it did not offer.

GetManifestCopy Anchor Link

message GetManifestRequest {}

message GetManifestResponse {
  Manifest manifest = 1;
}

GetManifestRequest has no fields; the plugin has one manifest. The returned manifest is at most 1 MiB serialized and must equal (proto.Equal) the manifest decoded from the installed package's manifest.yaml, whose digest the lockfile pins. If it does not, the host refuses to start the plugin. The manifest returned here is never a source of intents or capabilities: those come from the installed, digest-pinned package. See Manifest and capabilities.

GetDescriptorsCopy Anchor Link

message GetDescriptorsRequest {}

message GetDescriptorsResponse {
  google.protobuf.FileDescriptorSet descriptor_set = 1;
}

The plugin returns every port it implements as a serialized FileDescriptorSet, at most 2 MiB and at most 64 files. The host validates it against the spec version it supports, and its own compiled copy of each port file is authoritative:

• A shared port file that differs from the host copy in any option fails install.
• An RPC that is not in a port file the host serves is not dispatchable.
• A file whose name or package collides with a host-compiled file (annotations, types, the google.protobuf well-known types, any numinance.ports.*) must equal the host copy (proto.Equal on FileDescriptorProto with source_code_info cleared) or install fails; the host copy is used either way.
• Plugin-private files must not use the numinance. or google. package prefixes and must not extend any google.protobuf options message.
• Options are always read through the host's own registry. source_code_info of every plugin-supplied file is discarded after validation and never rendered.

The consequence is the invariant that matters: a plugin cannot change the risk, execution mode or evidence declarations of a port verb by shipping its own copy of the descriptor. Governance annotations come from the host's descriptors.

InvokeCopy Anchor Link

Invoke dispatches one action after the policy decision and the grant check.

message InvokeRequest {
  Envelope envelope = 1;
}

message InvokeResponse {
  ActionResult result = 1;
}

InvokeRequest.envelope is the action, built by the host. Its structure is on Envelope, ActionContext and ActionResult. Each InvokeResponse.result is one reported result of the stream; status is INVOKE_STATUS_RUNNING on every message but the last.

Stream boundsCopy Anchor Link

Server-streaming targetsCopy Anchor Link

A target whose method is itself server-streaming (a port verb such as authorexecutor Execute) is always an OPERATION target and rides the same stream.

• Each message of the target's stream is one RUNNING message whose ActionResult.result holds it. The type URL is the method's output type, and the 64 KiB RUNNING bound covers it.
• The terminal message carries no result. Its status follows the last stream message as the port defines it. For authorexecutor Execute, SUCCEEDED follows EXECUTION_COMPLETED and FAILED follows EXECUTION_FAILED.
• A terminal status that disagrees with the last stream message is rejected.
• A stream whose last stream message is not one the port names terminal is rejected.
• A stream that ends without any stream message may only end FAILED (a provider rejection).
• A RUNNING message with a result on a target that is not server-streaming is rejected.

Error semanticsCopy Anchor Link

The host reads each message through a size-limited reader, never buffers the stream, and decodes strictly, rejecting unknown fields. A stream that breaks any rule above is rejected and recorded as failed. The host decides the recorded outcome itself: the plugin's status is a claim, not the record (see InvokeStatus).

There is no dry run of Invoke itself. The host sets ActionContext.dry_run only for a target whose supports_dry_run is true.

HealthCopy Anchor Link

message HealthRequest {}

message HealthResponse {
  HealthStatus status = 1;
}

enum HealthStatus {
  HEALTH_STATUS_UNSPECIFIED = 0;
  HEALTH_STATUS_SERVING = 1;
  HEALTH_STATUS_NOT_SERVING = 2;
}

Health is reported for the whole plugin. The host rejects HEALTH_STATUS_UNSPECIFIED. HEALTH_STATUS_SERVING accepts calls; HEALTH_STATUS_NOT_SERVING accepts none.

ShutdownCopy Anchor Link

message ShutdownRequest {}

message ShutdownResponse {}

Shutdown asks the plugin to stop. Before calling it the host cancels in-flight operations and revokes the plugin's credential handles and egress grants. The plugin starts no new work after it, and the host kills the process after a bounded grace period. It has no dry run: stopping its own process is the whole effect, and the host may always kill the process.

Failure modes and safeguardsCopy Anchor Link

TroubleshootingCopy Anchor Link

• Install fails after a descriptor change: you shipped a port file that differs from the host's copy. Regenerate from the pinned spec revision instead of editing options.
• A streaming verb is recorded as failed although the work finished: check that the last stream message is the one the port names terminal and that the terminal status agrees with it.
• The host rejects a Diagnostic: its field_path or subject did not resolve in the host's registry. Details are on the envelope page.

Next stepsCopy Anchor Link