Plugin Protocol

All messages use newline-delimited framing with the wire format #<id> <verb> [<json>]\n.

Wire Format

Every message is a single newline-terminated line:

• <id> is a monotonically increasing uint64 correlation ID
• <method> uses YANG-style <module>:<rpc-name> naming (e.g., ze-plugin-engine:declare-registration)
• JSON payloads are optional (omitted when empty or null)
• Responses use ok or error as the verb; requests use the method name

Routing: MuxConn multiplexes a single connection for concurrent RPCs. A background reader goroutine routes incoming lines by verb: ok/error responses go to the waiting CallRPC caller by #<id>, while method-name requests go to the Requests() channel.

Examples:

# Plugin sends declare-registration (Stage 1)
#1 ze-plugin-engine:declare-registration {"families":[{"name":"ipv4/flow","mode":"both","afi":1,"safi":133}]}

# Engine responds OK
#1 ok

# Engine sends configure to plugin (Stage 2)
#1 ze-plugin-callback:configure {"sections":[{"root":"bgp","data":"{...}"}]}

# Plugin responds OK
#1 ok

# Engine sends event at runtime
#42 ze-plugin-callback:deliver-event {"event":"{\"type\":\"state\",...}"}

# Plugin responds OK
#42 ok

# Error response with payload
#5 error {"code":"error","message":"unknown family: ipv4/unknown"}

Protocol Stages

The SDK handles the 5-stage startup protocol automatically via Plugin.Run().

Stage 1: Registration (Plugin to Engine)

Plugin sends ze-plugin-engine:declare-registration with a DeclareRegistrationInput:

Each FamilyDecl has these fields:

Set afi and safi for a custom family. A built-in family can omit both numeric fields.

Wire example:

#1 ze-plugin-engine:declare-registration {"families":[{"name":"ipv4/flow","mode":"both","afi":1,"safi":133}],"commands":[{"name":"flowspec status","description":"Show FlowSpec status"}],"wants-config":["bgp"]}
#1 ok

Stage 2: Config (Engine to Plugin)

Engine sends ze-plugin-callback:configure with a ConfigureInput:

Each ConfigSection has:

Wire example:

#1 ze-plugin-callback:configure {"sections":[{"root":"bgp","data":"{\"bgp\":{\"peer\":{...}}}"}]}
#1 ok

Stage 3: Capabilities (Plugin to Engine)

Plugin sends ze-plugin-engine:declare-capabilities with a DeclareCapabilitiesInput:

Each CapabilityDecl has:

Wire example:

#2 ze-plugin-engine:declare-capabilities {"capabilities":[{"code":64,"encoding":"hex","payload":"0078","peers":["192.168.1.1"]}]}
#2 ok

Stage 4: Registry (Engine to Plugin)

Engine sends ze-plugin-callback:share-registry with a ShareRegistryInput:

Each RegistryCommand has:

Wire example:

#2 ze-plugin-callback:share-registry {"commands":[{"name":"rib adjacent status","plugin":"bgp-adj-rib-in"},{"name":"peer","plugin":"bgp"}]}
#2 ok

Stage 5: Ready (Plugin to Engine)

Plugin sends ze-plugin-engine:ready with an optional ReadyInput:

The subscribe field allows plugins to register event subscriptions atomically with startup completion. This avoids a race where SignalAPIReady triggers route sends before a separate subscribe-events RPC could be processed.

When transport is "bridge", the engine activates bridge callbacks on the PluginConn and the SDK closes the pipe after receiving the OK response. All subsequent engine-to-plugin callbacks flow through bridge.CallbackCh() instead of the MuxConn.

Wire example:

#3 ze-plugin-engine:ready {"subscribe":{"events":["update","state"],"peers":["*"],"format":"json"},"transport":"bridge"}
#3 ok

After Stage 5, the SDK activates the DirectBridge (for internal plugins) and enters the event loop.

Runtime Callbacks (Engine to Plugin)

After startup, the engine sends runtime RPCs to the plugin. The SDK dispatches each wire method to its registered handler.

Runtime RPCs (Plugin to Engine)

Plugins call the engine during runtime through these SDK methods:

Message Flow Example

Plugin                                             Engine
   |                                                  |
   |  STAGE 1: declare-registration                   |
   |-- #1 ze-plugin-engine:declare-registration {...}->|
   |<- #1 ok ---------------------------------------- |
   |                                                  |
   |  STAGE 2: configure                              |
   |<- #1 ze-plugin-callback:configure {...} ---------|
   |-- #1 ok ---------------------------------------->|
   |                                                  |
   |  STAGE 3: declare-capabilities                   |
   |-- #2 ze-plugin-engine:declare-capabilities {...}->|
   |<- #2 ok ---------------------------------------- |
   |                                                  |
   |  STAGE 4: share-registry                         |
   |<- #2 ze-plugin-callback:share-registry {...} ----|
   |-- #2 ok ---------------------------------------->|
   |                                                  |
   |  STAGE 5: ready                                  |
   |-- #3 ze-plugin-engine:ready {...} -------------->|
   |<- #3 ok ---------------------------------------- |
   |                                                  |
   |  RUNTIME: event delivery                         |
   |<- #42 ze-plugin-callback:deliver-batch {...} ----|
   |-- #42 ok ---------------------------------------->|
   |                                                  |
   |  RUNTIME: plugin sends route update              |
   |-- #4 ze-plugin-engine:update-route {...} -------->|
   |<- #4 ok {"peers-affected":2,"routes-sent":2} --- |
   |                                                  |
   |  RUNTIME: command execution                      |
   |<- #43 ze-plugin-callback:execute-command {...} ---|
   |-- #43 ok {"status":"done","data":"..."} -------->|
   |                                                  |
   |  SHUTDOWN: bye                                   |
   |<- #99 ze-plugin-callback:bye {"reason":"..."} ---|
   |-- #99 ok ---------------------------------------->|
   |  (plugin exits)                                  |

Error Handling

Stage errors: If any stage RPC fails (error response or timeout), the SDK returns an error from Run() with context like "stage 1 (declare-registration): ...".

Runtime errors: Callback handlers return errors via #<id> error {"code":"...","message":"..."}. Unknown methods are rejected with "unknown method: <method>".

Connection errors: EOF or closed connection during the event loop is treated as clean shutdown (engine closes socket to signal exit).

Config reload errors: config-verify and config-apply return structured results with {"status":"ok"} or {"status":"error","error":"..."}. If no handler is registered, the response is {"status":"ok"} (graceful no-op).

Batched Event Delivery

Events are batched for efficiency. The engine collects pending events from a per-process channel, JSON-quotes each one, and sends them in a single deliver-batch RPC.

#42 ze-plugin-callback:deliver-batch {"events":["<json-event-1>","<json-event-2>",...]}
#42 ok

The SDK unpacks the batch and dispatches each event to the OnEvent handler individually. Both deliver-event and deliver-batch handlers are registered in the callback map when OnEvent is called.

For internal plugins with an active DirectBridge, event delivery bypasses the callback channel entirely: bridge.DeliverEvents(events) calls the onEvent handler directly (hot path). The callback channel is only used for non-event callbacks (execute-command, config-verify, etc.) and bye.