Plugin Protocol
Ze plugins communicate with the engine via newline-framed YANG RPCs over a single
bidirectional connection. Internal plugins use net.Pipe() for startup; external
plugins connect back via TLS.
All messages use newline-delimited framing with the wire format #<id> <verb> [<json>]\n.
Wire Format
Every message is a single newline-terminated line:
| Message type | Format |
|---|---|
| Request | #<id> <method> [<json-params>]\n |
| Success response | #<id> ok [<json-result>]\n |
| Error response | #<id> error [<json-error>]\n |
| Record answer | #<id> <kind> <positional fields>\n: a head, one line for each record, and a terminator |
The record answer applies to three methods. It replaces the single success line with a head, zero or more records, and a terminator. Every other method keeps the three forms above.
An answer line carries no verb and no key name. The field after the id is a three-byte word saying what the line IS:
| Word | The line is |
|---|---|
top |
the head, which opens the answer |
row |
one record the command produced |
bad |
one record it rejected. The walk goes on |
end |
the terminator, which ends the answer |
wrn |
the terminator of a command that completed and states a warning |
nay |
the whole answer to a command text naming no command |
The head carries a second three-byte word saying how the records read:
| Word | The records are |
|---|---|
doc |
one document. The whole answer is that one value |
map |
one map of names to values for each record |
tab |
one positional row for each record, read against the column names |
Every field after those is positional and takes one of two shapes. A NUMBER is
decimal digits closed by a space or by the end of the line. A TEXT is decimal
digits, a colon, then that many BYTES. The count is a BYTE count, never a count
of characters. A text of zero bytes is written 0:, so a line's field count
never varies:
#43 top doc 0: 0:
| | | | |
| | | | +----- column names, 0 BYTES, so the records are not positional
| | | +-------- envelope name, 0 BYTES, so the document carries its own
| | +------------ item type doc: the whole answer is one document
| +---------------- kind top: the head, always the first line
+-------------------- correlation id 43, echoed from the request
#43 row 26:{"running":true,"peers":1}
| | | |
| | | +----- those 26 bytes, the handler's value byte for byte
| | +-------- 26, the payload's BYTE count, then its colon
| +------------ kind row: one record the command produced
+---------------- correlation id 43
#43 end 1 0 0:
| | | | |
| | | | +----- message, 0 BYTES, so the command stated none
| | | +------- 0 rows rejected
| | +--------- 1 record produced
| +------------- kind end: the terminator, always the last line
+----------------- correlation id 43
Neither the head nor the terminator states an outcome. The verdict is DERIVED from what the terminator carries:
| The terminator | Verdict |
|---|---|
| ✕ | done |
wrn, no rejected row and no message |
warning |
| records and rejected rows, no message | ∿ |
| a message over no record | error |
| a message over records | aborted |
| ✕ | truncated |
When the engine cannot build the answer to a dispatch-command, for example
because the command's payload is not a JSON object or array, it still writes a
head and a terminator whose message names the reason. Your plugin reads
error with that message rather than waiting for its timeout.
ipc_protocol.md, "Answer Protocol", carries the same grammar with the buffering threshold and the failure cases beside it.
| Method | The plugin | The engine |
|---|---|---|
dispatch-command |
reads the answer | writes it |
dispatch-command-args |
reads the answer | writes it |
execute-command |
writes the answer | reads it |
One encoding covers both columns, on every connection. Nothing is declared and nothing is negotiated, so a plugin author sets no field and reaches no option.
A plugin READS an engine answer in one of two ways, and both read the same
frame. Plugin.DispatchCommandAnswer yields each row as it arrives, which is
what bounds the memory of a walk over a large table. Plugin.DispatchCommand
and Plugin.DispatchCommandArgs collapse the same answer into the one document
a caller that wants the whole payload reads.
A plugin WRITES its own answer to execute-command, and the frame is the same
whatever the payload is. A handler that returns a plugin.Records writes one
line for each row of the walk. A handler that returns a built value writes that
value as the one record of a doc answer, byte for byte.
<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
okorerroras 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 {"protocol-version":1,"families":[{"name":"ipv4/flow","mode":"both","afi":1,"safi":133}]}
# Engine answers the protocol version both sides speak
#1 ok {"protocol-version":1,"plugin-name":"flow-export"}
# 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:
| Field | Type | Description |
|---|---|---|
protocol-version |
int |
REQUIRED. The highest plugin protocol version the plugin speaks (this engine speaks 1) |
families |
[]FamilyDecl |
Address families the plugin handles (name, mode, AFI, and SAFI) |
commands |
[]CommandDecl |
Commands the plugin provides |
dependencies |
[]string |
Plugin names that must also be loaded |
wants-config |
[]string |
Config roots the plugin wants to receive |
config-operations |
[]ConfigOperationDecl |
Config operation callbacks the plugin supports, and the operation labels it emits for each root. The labels are the plugin's own: the engine keeps no list of them |
verify-budget |
int |
Estimated verify time in seconds (0 means trivial) |
apply-budget |
int |
Estimated apply time in seconds (0 means trivial) |
schema |
*SchemaDecl |
YANG schema (module, namespace, yang-text, handlers) |
wants-validate-open |
bool |
Whether plugin wants OPEN validation callbacks |
cache-consumer |
bool |
Whether plugin consumes cached events |
cache-consumer-unordered |
bool |
Whether unordered cache delivery is acceptable |
filters |
[]FilterDecl |
Named route filters the plugin provides: each a name or a name-pattern, and the route fields it reads (raw for the UPDATE body) and sets, and whether an export filter also runs on two extra occasions, readvertise and judges-final ("Filter Run Occasions"); Stage 1 and config load judge them ("Filter Declaration"). docs/architecture/api/process-protocol.md |
doctor-checks |
[]DoctorCheckDecl |
Doctor checks the plugin provides, each with a phase: pre-config, missing-config, parsed-config, post-config, or runtime. Declare runtime (sdk.DoctorPhaseRuntime) for a check that reads your plugin's live state: only show doctor on the running daemon runs it, never a local ze doctor process, which holds no live state. A runtime check only reads; it changes nothing |
resolver-caches |
[]string |
Resolver caches the plugin holds clients for: peeringdb, irr, cymru. Set by OnResolverCacheClear; any other name is refused |
enrichers |
[]EnricherDecl |
Show enrichers the plugin provides |
pipes |
[]PipeDecl |
CLI pipe aliases the plugin names for its own commands |
claims |
[]string |
Exclusive runtime roles the plugin takes over |
failure-policy |
string |
What ze does when this plugin fails: restart, ignore or fatal. Omitting it means ignore |
signals-session-ready |
bool |
Your routes belong to a peer's initial routing update, and you report plugin session ready once they are out ("The session-ready report") |
The failure policy is what your plugin asks ze to do when your plugin fails. It is voluntary, and a plugin that omits it is carried on without. A value that is none of the three fails the whole registration, so ze never guesses.
| You declare | ze does | May ze start your plugin again? |
|---|---|---|
restart |
starts the plugin again, bounded at 5 in 60 seconds and 20 in the life of the daemon | ✓ |
ignore |
logs it and carries on without the plugin | ✕ |
fatal |
stops ze | ✕ |
fatal is open to any plugin, whether ze ships it or you wrote it (owner
directive, 2026-09-06). An operator who configures your plugin accepts its
terms.
Declaring anything other than restart also says your plugin must NOT be
started again. An operator whose plugin { external <name> } block writes
respawn true for such a plugin gets a daemon that refuses to start, with an
error naming your plugin and the policy it declared. Declare restart when
your plugin can come back from a crash, which usually means its state lives
outside the process.
The session-ready report says your share of a peer's initial routing update
is out. It is voluntary. Declare signals-session-ready only when your
plugin pushes routes into a peer from that peer's peer-up event. A plugin that
pushes on its own schedule leaves it false and owes no report.
A peer counts your plugin only when three facts hold: its attach process
block grants you send [ update ] or send [ raw ], you declared
signals-session-ready, and it grants you receive [ state ], so you see the
peer-up event. Once your routes for that session are sent, dispatch:
request peer <address> plugin session ready session <initial-replay>
<initial-replay> is the token from that peer-up event's initial-replay
field (docs/architecture/api/json-format.md). Send one report per peer-up,
even when you had nothing to send.
What the report does:
| Situation | What ze does |
|---|---|
| You report | ze credits the report to your process for that session, once. A second report is not credited again |
| You report with a token from an older session, or for a session that is going down | ze refuses it with an error naming the problem |
| You report for a peer ze does not have | ze credits it to nothing and logs a WARN naming the peer |
| You never report | Nothing waits for you. ze never holds its End-of-RIB for a report: it sends the marker once its own table is out |
The report's effect inside ze is to lower the replay fence, which holds a peer's live forwarded changes while a route server or RIB plugin compiled into ze replays that peer's table. Only a plugin compiled into ze can own that fence, so today a report from an external plugin is credited and changes nothing on the wire. Declaring it still tells ze that your routes belong to the initial update.
Each CommandDecl has these fields:
| Field | Type | Description |
|---|---|---|
name |
string |
Command path the plugin serves |
description |
string |
The one-line SUMMARY. Every surface that shows the command on one line reads it. One line, at most 256 bytes, no control character |
description |
string |
The LONG explanation the command's own help page prints. At most 4096 bytes, newlines kept, every other control character refused |
args |
[]string |
Expected argument names, for help and completion |
completable |
bool |
Whether the command supports tab completion |
hidden |
bool |
Whether the command is left out of help and completion |
deprecated-names |
[]string |
Older spellings that still reach this command |
shape |
string |
What the answer holds: doc, map, tab or blob |
columns |
[]string |
The answer's keys, in the order a person reads them. Needs a shape that has rows. Maximum 64 |
address-fields |
[]string |
The keys whose value holds an IP address or a prefix. Needs a shape. Maximum 16 |
The last three are optional and additive. A plugin that sends none keeps the behavior it had before they existed. A plugin that sends one the engine refuses fails Stage 1 and does not start.
short-help and description are two texts and neither is derived from the
other. The key is description and not help, because help already names the
SUMMARY in a completion row on this same protocol. A plugin that sends
description and no description renders with its summary and an empty
explanation. That is what every plugin written before description existed
sends. An empty description NEVER renders as an empty summary.
validateHelpDecls reads both texts before any conversion. It refuses a text
past its bound, and a control character the text's shape does not allow. The
summary reaches the tab-separated shell-completion format and the one-line
terminal candidate. A newline, a tab or an ESC in it breaks the format for
every row that follows. The alias description below is held to the same
one-line rule.
Each PipeDecl has these fields:
| Field | Type | Description |
|---|---|---|
command |
string |
Command path the alias sits on. MUST be one of this plugin's own declared commands |
name |
string |
The word an operator types after the pipe character (kebab-case, 1-64 chars) |
description |
string |
The one-line summary completion and command help show beside the name. At most 256 bytes, no control character |
expansion |
string |
The operator chain the name stands for, as an operator would type it |
A pipe alias SELECTS and re-sequences the answer the command already returned.
It renames no key, sums no numbers and counts no rows, so the command MUST emit
the aggregate fields beside the detail rows. One bad entry refuses the whole
list and fails the plugin's startup. Read
docs/architecture/api/commands.md for the collision rules and the payload
obligation.
Each FamilyDecl has these fields:
| Field | Type | Description |
|---|---|---|
name |
string |
Canonical afi/safi name |
mode |
string |
encode, decode, or both |
afi |
uint16 |
RFC 4760 Address Family Identifier |
safi |
uint8 |
RFC 4760 Subsequent Address Family Identifier |
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 {"protocol-version":1,"families":[{"name":"ipv4/flow","mode":"both","afi":1,"safi":133}],"commands":[{"name":"flowspec status","short-help":"Show FlowSpec status"}],"wants-config":["bgp"]}
#1 ok {"protocol-version":1,"plugin-name":"flow-export"}
The protocol version. The engine answers Stage 1 with the version both
sides speak from then on: the lower of the plugin's protocol-version and its
own. A plugin declaring a version above the engine's speaks the answered
version. A declaration with no protocol-version is from the text era, before
filters declared the route fields they read, and the engine refuses it with
one error that names the plugin and the version to declare; the startup tier
then stops, as for any plugin failure. Version 1 is the first versioned
contract. The Go SDK declares it and refuses an engine that answers any other.
The answer also includes plugin-name, the configured instance name of the
authenticated process. It can differ from the implementation's name. The Go
SDK exposes this through Plugin.InstanceName() before OnConfigure runs;
before the Stage 1 answer it is empty. Use that configured identity in recovery
commands that restart the plugin.
Stage 2: Config (Engine to Plugin)
Engine sends ze-plugin-callback:configure with a ConfigureInput:
| Field | Type | Description |
|---|---|---|
sections |
[]ConfigSection |
Config sections (root name + JSON data) |
Each ConfigSection has:
| Field | Type | Description |
|---|---|---|
root |
string |
Config root name (e.g., "bgp") |
data |
string |
JSON-encoded config data |
Wire example:
#1 ze-plugin-callback:configure {"sections":[{"root":"bgp","data":"{\"bgp\":{\"peer\":{...}}}"}]}
#1 ok
Refusing the configuration. Answer with #1 error and the reason when you
cannot take what you were sent. That answer is a refusal: ze stops your plugin,
and ze itself stops when your registration carries FatalOnConfigError, so an
operator who mistyped a value is told rather than left with a router silently
missing your feature. Return an error from your OnConfigure handler and the
Go SDK writes that response for you.
#1 ze-plugin-callback:configure {"sections":[...]}
#1 error {"code":"error","message":"address family \"ipv6-unicat\" is not a family"}
Never answer ok for a configuration you rejected, and never just close the
connection: a lost connection is a transport failure, which says nothing about
the configuration and so never stops ze.
Stage 3: Capabilities (Plugin to Engine)
Plugin sends ze-plugin-engine:declare-capabilities with a DeclareCapabilitiesInput:
| Field | Type | Description |
|---|---|---|
capabilities |
[]CapabilityDecl |
BGP capabilities for OPEN injection |
Each CapabilityDecl has:
| Field | Type | Description |
|---|---|---|
code |
uint8 |
Capability code (e.g., 64 for Graceful Restart) |
encoding |
string |
"hex", "b64", or "text" |
payload |
string |
Encoded capability value |
peers |
[]string |
Peer addresses to inject into (empty = all peers) |
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:
| Field | Type | Description |
|---|---|---|
commands |
[]RegistryCommand |
Registered commands from all plugins |
Each RegistryCommand has:
| Field | Type | Description |
|---|---|---|
name |
string |
Command name |
plugin |
string |
Plugin that registered it |
encoding |
string |
Encoding format |
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:
| Field | Type | Description |
|---|---|---|
subscribe |
SubscribeEventsInput |
Optional startup event subscription |
transport |
string |
"bridge" for internal plugins; pipe closed after ack |
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.
Query Mode: Answering Without Starting
Ze can start your plugin to ask what it declares, with no daemon running and no
hub to connect to. It sets ZE_PLUGIN_MODE=declare in your process's
environment. Your plugin writes its Stage 1 declaration to stdout, exits 0, and
does none of a live start's work: no data initialization, no connection, no
bind, no listener, no timer.
What you call
sdk.RunOrDeclare takes your declaration and your start function as two
arguments and returns the exit code:
// declaration is what this plugin provides. It is a pure value: no file, no
// socket, no goroutine.
func declaration() *sdk.Registration {
return &sdk.Registration{
Commands: []sdk.CommandDecl{{Name: "acme-monitor status", ShortHelp: "Show monitor status"}},
}
}
func main() {
os.Exit(sdk.RunOrDeclare(declaration(), start))
}
// start does everything a live start does, and query mode never calls it.
func start() int {
p, err := sdk.NewFromEnv("acme-monitor")
if err != nil {
return 1
}
defer p.Close()
// ... register callbacks, open files, dial, start timers ...
if err := p.Run(context.Background(), declaration()); err != nil {
return 1
}
return 0
}
The declaration is the same *sdk.Registration you pass to Plugin.Run,
so query mode reads nothing new and adds no second list to keep in step.
What the SDK guarantees
- Your start function is NOT called under the mode. Side-effecting code inside it is unreachable during a query, not merely discouraged.
- The line written is the Stage 1
declare-registrationmessage in the protocol's own framing, so the reader parses one format. - A declaration naming no command and no pipe still writes the line. "Declared nothing" and "sent nothing" are different answers.
What it does not guarantee
- Work your
maindoes BEFORE the call runs under a query too. The SDK cannot reach it. Put every side effect inside the start function. Plugin.Runderiveswants-validate-openfrom the callbacks you registered. A query has noPlugin, so state that field in the declaration you pass here when you want it in the answer.- A plugin that adopts neither this entry point nor the
ze pluginroute is reported as having sent nothing. Ze cannot make a binary it does not compile inert, so for third-party code this is enforcement for adopters and convention for everyone else. QueryModeRequested()reports the mode for a plugin that has its own reason to branch. It is a reader, not a guarantee: the branch is yours to place, and anything above it has already run.
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.
| Method | SDK handler | Input | Output | Purpose |
|---|---|---|---|---|
ze-plugin-callback:deliver-event |
OnEvent |
DeliverEventInput |
None | Deliver one event |
ze-plugin-callback:deliver-batch |
OnEvent |
{"events":[]} |
None | Deliver an event batch |
ze-plugin-callback:execute-command |
OnExecuteCommand |
ExecuteCommandInput |
a record answer | Run a command |
ze-plugin-callback:encode-nlri |
OnEncodeNLRI |
EncodeNLRIInput |
EncodeNLRIOutput |
Encode NLRI |
ze-plugin-callback:decode-nlri |
OnDecodeNLRI |
DecodeNLRIInput |
DecodeNLRIOutput |
Decode NLRI |
ze-plugin-callback:decode-capability |
OnDecodeCapability |
DecodeCapabilityInput |
{"json":...} |
Decode a capability |
ze-plugin-callback:config-verify |
OnConfigVerify |
ConfigVerifyInput |
ConfigVerifyOutput |
Verify candidate config |
ze-plugin-callback:config-apply |
OnConfigApply |
ConfigApplyInput |
ConfigApplyOutput |
Apply a config diff |
ze-plugin-callback:config-rollback |
OnConfigRollback |
{"transaction-id":"..."} |
None | Roll back a config transaction. Reaches the handler only while an apply this plugin accepted is neither committed nor rolled back |
ze-plugin-callback:config-committed |
OnConfigCommitted |
{"transaction-id":"..."} |
None | The transaction committed; the SDK stops owing a rollback for its apply. Reaches the handler only while an apply this plugin accepted is neither committed nor rolled back |
ze-plugin-callback:config-operation-decompose |
OnConfigOperationDecompose |
ConfigOperationDecomposeInput |
ConfigOperationDecomposeOutput |
Decompose a config transaction |
ze-plugin-callback:config-operation-verify |
OnConfigOperationVerify |
ConfigOperationVerifyInput |
ConfigOperationVerifyOutput |
Verify a config operation |
ze-plugin-callback:config-operation-apply |
OnConfigOperationApply |
ConfigOperationApplyInput |
ConfigOperationApplyOutput |
Apply a config operation |
ze-plugin-callback:config-operation-rollback |
OnConfigOperationRollback |
ConfigOperationRollbackInput |
ConfigOperationRollbackOutput |
Roll back config operations |
ze-plugin-callback:config-operation-commit |
OnConfigOperationCommit |
ConfigOperationCommitInput |
ConfigOperationCommitOutput |
Commit reversible operation state; retain undo through whole-reload acceptance |
ze-plugin-callback:config-complete |
OnConfigComplete |
ConfigCompleteInput |
ConfigCompleteOutput |
Acknowledge cleanup for the named original transaction after acceptance or completed abort |
ze-plugin-callback:source-policy |
OnSourcePolicy |
rpc.SourcePolicyInput |
rpc.SourcePolicyOutput |
Settle prepare/apply/abort/finalize for a captured retained source |
ze-plugin-callback:validate-open |
OnValidateOpen |
ValidateOpenInput |
ValidateOpenOutput |
Validate an OPEN message |
ze-plugin-callback:filter-update |
OnFilter |
FilterUpdateBatchInput (routes, each a FilterUpdateInput) |
FilterUpdateBatchOutput (verdicts, each a FilterUpdateOutput) |
Filter a batch of routes, one verdict per route in request order ("The filter-update batch"). The engine waits rpc.FilterUpdateTimeout (5 s) for the whole batch, then applies the filter's on-error policy to each of its routes, so a handler MUST NOT wait on its own data: it answers from what it holds, and a route it could not judge yet is re-judged later (for an import filter, by asking the peer with request peer <peer> refresh <family>, as bgp-filter-irr does) |
ze-plugin-callback:doctor-check |
OnDoctorCheck |
DoctorCheckInput |
DoctorCheckOutput |
Run a doctor check. Each answered diagnostic carries code, severity, message, and fix: the command or config statement that clears the problem, alone and with no label (show rpki cache, not fix: show rpki cache). Set fix on every finding a command can clear; ze draws it on a line of its own under the message on every surface, and omits the key when you leave it empty |
ze-plugin-callback:resolver-cache-clear |
OnResolverCacheClear |
ResolverCacheClearInput |
ResolverCacheClearOutput |
Clear a declared resolver cache of the plugin's current clients, answering the entries removed |
ze-plugin-callback:enrich-show |
OnEnrichShow |
EnrichShowInput |
EnrichShowOutput |
Add data to show output |
ze-plugin-callback:post-startup |
OnAllPluginsReady |
None | None | Signal that all plugins are ready |
| ✕ | OnStructuredEvent |
[]any of *rpc.StructuredEvent |
None | Deliver structured events without JSON |
ze-plugin-callback:bye |
OnBye |
ByeInput |
None | Notify the plugin of its live removal or a subsystem stop. A daemon stop sends none: it closes the connection |
An OnConfigComplete handler automatically declares config-completion in
Stage 1. Its context carries the absolute deadline-ms work bound. Complete
cleanup before returning: callback queue admission is not a receipt. Keep
operation journals through OnConfigOperationCommit; discard only the matching
transaction on accepted completion. Rejected completion follows original undo,
after section-owned configuration and filters have been restored. A completion
error after acceptance reports an active candidate, not a rollback.
Requests and receipts MUST carry an explicit JSON boolean accepted, including
false for rejection. Missing or null decisions never invoke SDK cleanup and
never acknowledge completion to the engine; they are malformed messages.
Plugins retaining source state MUST declare source-policy-owner in Stage 1,
even if they do not implement the lifecycle yet. That unsupported declaration
refuses policy changes before publication; pure observers are not owners.
In Go, a plugin with no handler sets SourcePolicyOwner: true in the
sdk.Registration it passes to Run; the engine then refuses the change and
tells the operator to take the peer down around it.
OnSourcePolicy(func(context.Context, rpc.SourcePolicyInput) error) automatically
declares both ownership and source-policy handler support. All four operations
use one registered callback on both transports, not the shutdown OnDrain path.
Requests carry a transaction, operation, captured source identity, target epoch and absolute deadline. The engine sends the earlier of its caller's budget and the request deadline, so the handler's context never outlives the caller. The source identity comprises peer, peer incarnation, session generation, original policy epoch, receive frontier and template generation. Every field MUST be present and non-null; the last two may be zero. Prepare/finalize require explicit target zero. Apply requires a fresh target newer than the captured epoch. Abort carries target zero when the transaction was prepared and never applied: release your prepare pins and change nothing else (no restamp, no eligibility change, no downstream write). After apply, abort carries a fresh target newer than the captured epoch, and you restamp restored state to it. Refuse a zero abort after apply. The coordinator enforces monotonicity between calls. The SDK rejects malformed, unknown and expired requests before calling the owner.
The engine strictly drains event application before prepare, but the handler MUST additionally fence its own workers and downstream writes. It MUST honor the context deadline and return only after the requested work settles. Keep prepare pins through apply; abort restores them (a zero-target abort only releases them), while finalize releases accepted pins. The SDK returns an exact identity/target receipt only after the handler returns. The engine checks the captured process and connection again after acknowledgement. Neither this callback transport nor copied epoch fields alone invalidate routes.
The handler does not run on the callback loop. The Go SDK starts one source-policy worker for the plugin's connection and stops it with the plugin, on both transports, so a handler may wait for events delivered after its request, or call the engine during prepare or apply, without blocking the loop that delivers them. What that means for your handler:
- It runs concurrently with
OnEventand the other callbacks. Protect the state they share. Every event delivered before the request has already been applied when it starts. - Calls never overlap and arrive in the order the engine sent them, so one source's prepare, apply, abort and finalize reach you in order.
- Its context ends at the request deadline or when the plugin stops. A request that expired while queued fails without calling you.
- At most 16 requests wait behind the running one. A request beyond that is answered at once with an error receipt saying the queue is full, and your handler never sees it.
- A panic fails the request, and nothing runs after it: every request already
queued gets a failed receipt, then the plugin's connection ends with that
error.
A plugin written in another language owes the same: answer
source-policywithout stopping its event delivery.
Retained/replayed received routes MUST preserve their original
StoredRoute.SourcePolicyEpoch (source-policy-epoch), never stamp the current
epoch onto old work. Zero is unrecorded, independently of session generation.
A peer's AS is not always known when an event is written. A dynamic peer's AS
comes from its OPEN, so the OPEN Ze sends, a NOTIFICATION Ze sends in
OpenSent and the FSM changes before OpenConfirm carry none. The JSON peer
object then omits remote.as, a text line says remote as unknown, and
StructuredEvent.PeerAS is the zero rpc.RemoteAS, which means "not yet
known" and never AS 0. Read it with PeerAS.ASN(), which answers
(uint32, bool), and branch on the bool. An UPDATE always names the AS.
Rendered without a branch, it writes the number or unknown through %v, %s
and log/slog, and the number or null through encoding/json, where a field
tagged omitzero is omitted while the AS is unknown.
A session-down event names the session it ended: session-generation in the
JSON and text forms, StructuredEvent.SessionGeneration in the structured
one, a nonzero number captured when that session closed. An up carries none.
A forwarding plugin that asks the engine to withdraw or replace a departed
peer's routes (recovery-source meta on its update command) MUST name that
session as recovery-generation meta, a decimal string: the engine refuses a
departure without it, and with it owes only routes that session or an older
one wrote, so a down handled after the peer reconnected never takes the newer
session's routes (docs/architecture/plugin/rib-storage-design.md,
"Source-DOWN replacement and sent ordering").
The filter-update batch
One filter-update exchange carries a batch of routes. The request is
{"routes":[...]}, each entry one route as FilterUpdateInput describes it
(filter, direction, peer, peer-as, fields, raw). The
answer is {"verdicts":[...]}, one FilterUpdateOutput per route, at the
position of its route.
#7 ze-plugin-callback:filter-update {"routes":[{"filter":"lp","direction":"import","peer":"192.0.2.1","peer-as":65001,"fields":{"prefix":{"ipv4/unicast":["10.0.0.0/24"]}}},{"filter":"lp","direction":"import","peer":"192.0.2.1","peer-as":65001,"fields":{"prefix":{"ipv4/unicast":["10.0.1.0/24"]}}}]}
#7 ok {"verdicts":[{"action":"reject"},{"action":"modify","sets":[{"field":"med","action":"set","value":50}]}]}
- What a batch holds. Ze sends the routes queued for the plugin when the
exchange starts, at most
rpc.FilterUpdateBatchMax(64), and splits that FIFO group into contiguous exchanges that each fit the 16 MiB RPC request frame, including its JSON envelope, method and request ID. A lone route goes at once in a batch of one; routes that queue while an exchange is in flight go in the next group. Routes from one source stay in order within and across exchanges, and each verdict stays paired with its original route. A route whose serialized input cannot fit a frame even alone fails only itself under its filter'son-error, not its queued neighbors. - One timeout per batch.
rpc.FilterUpdateTimeout(5 s) bounds the whole exchange. When it expires, or the plugin answers an error, each route of the batch takes its filter'son-error, one outcome per route. - Queue admission and the typed slot. Only the encoded transport creates a
per-route
rpc.FilterUpdateTimeout(5 s) deadline, before encoding the route and waiting for room in the bounded batch queue. An earlier caller deadline or cancellation still wins. Once admitted, the route waits behind the bounded queue's predecessors and any exchange in flight, then its own exchange, each bounded separately by the batch timeout. An activated typed slot calls the evaluator synchronously under the fast-path contract, with no unused route context or timer. A closed slot fails the route; it never falls back to the queue. - One verdict per route. A reply with more or fewer verdicts than the
request held routes is malformed: no verdict of it is applied, and each
route of the batch takes its filter's
on-error. The next batch is judged normally. - A route the filter cannot judge. A verdict carrying
error(a string) fails that route alone under its filter'son-error; the other routes of the batch keep their verdicts. A nonemptyerrortakes precedence over every other verdict field: no action, sets, raw rewrite or teardown is applied. The Go SDK answers this way when the evaluator fails:answerFilterBatchcalls the evaluatorOnFilterinstalled once per route, in request order, and an error it returns or a nil verdict fails that route alone, so a Go filter is written for one route. The same evaluator run internal, through the typed slot, gets the same answer: a returned error, nil verdict or nonempty verdicterrorfails that route alone, before raw ownership processing, and counts no completed typed judgment. The conformance harness compares these consumer-visible failures rather than the ignored fields of a failed verdict.
The Route Fields of filter-update
FilterUpdateInput.Fields (fields on the wire) is one JSON object holding the
route fields the filter declared in reads, and no other. Each key is the
vocabulary field name, never the UPDATE event's attr key: community, not
communities. Each value takes the shape the event's attr map gives that
attribute (docs/architecture/api/json-format.md, "Attributes"), written by
the same formatter. The fields the attr table has no row for take these
shapes:
| Field | Shape | Example |
|---|---|---|
prefix |
object: family to the list of announced NLRI, in the event's NLRI shapes (ADD-PATH adds path-id) |
{"ipv4/unicast":["10.0.0.0/24"]} |
withdrawn |
object: family to the list of withdrawn NLRI (the body Withdrawn Routes, then MP_UNREACH_NLRI), in the event's withdrawal shapes (ADD-PATH adds path-id); the sections as received, whatever an earlier filter dropped. Read-only: no attachment lets a filter set it |
{"ipv4/unicast":["10.9.0.0/24"]} |
family |
list of the announced families | ["ipv4/unicast","ipv6/unicast"] |
next-hop |
object: family to the next hop of its announced routes | {"ipv4/unicast":"192.0.2.1"} |
protocol |
"ebgp" or "ibgp": the session the route came from (import) or goes to (export) |
"ebgp" |
origin-as |
the origin AS number, or "none" for RFC 6811's NONE |
65002 |
A filter may also declare the facts of the session the route is judged on.
The plain names describe the session's peer: the peer the route came from on
import, the peer it goes to on export. The source- names describe, on
export, the peer a forwarded route came from; a route Ze originated has none.
A fact the session does not hold is left out, never sent as a zero or an
empty string.
| Field | Shape | Left out when | Example |
|---|---|---|---|
peer-name, source-peer-name |
string: the peer's config name | never, once the peer is known | "edge" |
peer-group, source-peer-group |
string: the peer's group | the peer is in no group | "clients" |
peer-address, source-peer-address |
string: the peer's address | never, once the peer is known | "192.0.2.1" |
local-as |
the local AS number on this session | the session has none yet | 65000 |
peer-as, source-peer-as |
the peer's AS number | a dynamic peer still resolving its AS | 65001 |
route-server-as |
the AS the route server acts on for a route-server client | the peer is not a route-server client | 64999 |
ibgp, source-ibgp |
boolean: an internal session, an RFC 7705 migration session included | never, once the peer is known | false |
rs-client, source-rs-client |
boolean: the peer is a configured route-server client | never, once the peer is known | true |
llgr-advertised |
boolean: the OPEN Ze sent this session carried the Long-Lived Graceful Restart Capability (RFC 9494 Section 3) | on export: only the received path knows it | true |
source-llgr-advertised |
boolean: the OPEN Ze sent the session an exported route came from carried the Long-Lived Graceful Restart Capability (RFC 9494 Section 3) | on import, and on export unless the route was rebuilt from storage (rebuilt is true): the live export rails carry the stale level in stale instead |
true |
src-role, src-peer-role |
string: route metadata bgp-role registers, Ze's role toward the route's source peer and that peer's role toward Ze. docs/architecture/meta/README.md |
✕ | "customer" |
stale |
the route's stale level, route metadata bgp-gr registers (0 to 255; 2 marks an LLGR-stale route) |
✕ | 2 |
rebuilt |
boolean: route metadata the engine registers, set on a route rebuilt from storage | a live route | true |
otc |
the route's Only to Customer attribute (RFC 9234 Section 5), an AS number, registered by bgp-role; a value that is not 4 octets fails the filter that reads it |
the UPDATE carries no OTC | 65001 |
A route metadata field is also a set: a filter at bgp import that declared
it answers {"field":"stale","action":"set","value":2}, with the value in the
field's type (a string, an integer from 0 to 255, or true or false).
The engine writes it into the route's metadata map, so a later member of the
chain reads it and the received event carries it in route-meta. A filter at
bgp export reads the received route's map and may not set it: every
destination shares that map.
otc is a set only for a filter of bgp-role, the plugin that owns it: it
answers {"field":"otc","action":"set","value":65001} at either attachment.
A set of otc from any other plugin's filter fails the route.
For example, a filter that declared community, as-path and
local-preference reads
"fields":{"community":["65001:100"],"as-path":[65001,65002],"local-preference":100}.
- A declared field the route does not carry is left out of the object.
- A filter that declared no route field (a raw-only filter) is sent no
fieldsmember, andrawis sent only to a filter that declaredraw. - A field Ze cannot read, such as a malformed attribute, is never sent empty:
the filter's
on-errordecides the route instead of the filter. - Stage 1 refuses a declared BGP field this binary cannot write: the
community fields need
bgp-filter-community,originator-idandcluster-listneedbgp-rr, andaigpneedsbgp-aigp. - The values are the route as the earlier members of the chain left it: a
local-preference, med or community an earlier member set, in process or in
a plugin, is what this filter reads.
rawis still the received body. A filter that declared noreadsfails the route under itson-error.
The Sets of a filter-update answer
A filter answers its changes in FilterUpdateOutput.Sets (sets on the wire), with "action":"modify".
Each entry names one field the filter declared in sets, how it changes, and
the value in the field's shape:
| Field | Actions | Value | Example |
|---|---|---|---|
local-preference |
set, increment, decrement |
a number from 0 to 4294967295 | {"field":"local-preference","action":"set","value":200} |
med |
set, increment, decrement |
a number from 0 to 4294967295 | {"field":"med","action":"increment","value":10} |
community |
add, remove |
one community string | {"field":"community","action":"add","value":"65000:100"} |
med |
remove |
null; honored on an import chain only (RFC 4271 Section 5.1.4), so on an export chain the route fails |
{"field":"med","action":"remove","value":null} |
aigp |
set, increment, decrement |
a number from 0 to 4294967295; an increment or decrement of a route with no AIGP changes nothing | {"field":"aigp","action":"increment","value":10} |
origin |
set |
"igp", "egp" or "incomplete" |
{"field":"origin","action":"set","value":"egp"} |
next-hop |
set |
one IPv4 address | {"field":"next-hop","action":"set","value":"192.0.2.1"} |
large-community |
add, remove |
one large community string | {"field":"large-community","action":"add","value":"65000:1:2"} |
extended-community |
add, remove |
one extended community string, in the form the UPDATE event writes | {"field":"extended-community","action":"add","value":"target:65000:100"} |
as-path |
prepend |
a count of local AS copies, 1 to 32 | {"field":"as-path","action":"prepend","value":2} |
as-path |
remove |
"private" removes the private-use AS numbers; "private-peer-as" replaces each with the peer AS |
{"field":"as-path","action":"remove","value":"private"} |
prefix |
remove |
one announced unicast, multicast or labeled-unicast NLRI, in the shape the prefix field is sent: the prefix string, under ADD-PATH {"prefix":...,"path-id":...}, and for labeled unicast {"labels":[[label,entry],...],"prefix":...}, with "path-id" between them under ADD-PATH |
{"field":"prefix","action":"remove","value":"10.0.9.0/24"} |
family |
remove |
one family name | {"field":"family","action":"remove","value":"ipv6/unicast"} |
- A later filter of the chain is sent the value an earlier filter's sets left, not the received one.
- An increment or decrement starts from the route's value, or from
bgp defaults attributewhen the route carries none, and stays within 0 and 4294967295. The changes fold in chain order and produce the same UPDATE bytes. - The route fails under the filter's
on-error, logged and counted, with none of its sets applied, when an entry names a field the filter did not declare, a field the chain's attachment does not let a filter set, or a field no BGP chain sets; when the action is not one the field takes; or when the value has the wrong shape. The other routes are judged on their own. - A
prefixremove needs only that the filter declares it readsprefix, and afamilyremove that it readsfamily. Each drops only what the filter was shown, so neither is a set the filter declares, and both work at a BGP attachment, which lets no filter setprefixorfamily. - The
as-path,prefixandfamilyentries are intents Ze resolves with state the plugin does not hold: a prepend uses the local AS and the session's AS number width,"private-peer-as"the peer AS, a prefix remove drops the entry from the body NLRI and from MP_REACH_NLRI (an MP_REACH_NLRI left empty leaves the UPDATE), and a family remove drops that family's MP_REACH_NLRI and MP_UNREACH_NLRI (the body NLRI and withdrawn routes foripv4/unicast). Prepends add up across the chain to at most 32. A labeled remove drops the entry whose prefix and whole label stack match, label field included (RFC 8277 Section 2.3). A prefix the route does not announce, one with host bits set, or a value whose shape names another kind of NLRI (a label stack for a unicast entry, a plain prefix for a labeled one) fails the route. "action":"withdraw"removes the route rather than only stopping it: on import the engine treats the route's announcements as withdrawn by the peer that sent them, so a version accepted earlier leaves the RIB; on export the route is withdrawn toward that destination. Every route of the UPDATE is withdrawn: one whose MP_REACH_NLRI and MP_UNREACH_NLRI name two families is withdrawn as two UPDATEs, one per family, because one UPDATE carries one MP_UNREACH_NLRI. Both generated withdrawals carry the original policy decision: import does not run the filter again on the attribute-free follow-up. The later filters of the chain are not called.- A filter that declares no
readsis never called: Ze has no field to send it, so every route the chain asks it to judge fails, and the chain treats the failure ason-errorrejectwhatever the filter declared. Declare at least one field the filter reads, orraw. - The route fails the same way when the answer carries
setsbesideaccept,rejectorwithdraw. - A filter that declares
rawamong its reads may answer"action":"modify"with a whole-bodyrawrewrite and nosets. A valid rewrite is terminal: the later filters of the chain are not called, the chain's final still decides the route, and the rewrite is sent in place of the received body. Before it can end the chain, Ze checks the UPDATE section framing and applies the receive path's mandatory RFC 9012 Section 13 tunnel checks and normalization. A malformed rewrite is a named member failure, logged and counted on a live run, under that filter'son-error:rejectdrops the route;acceptdiscards the failed rewrite and continues to later members with the route unchanged. A dry run follows the same decisions and records the member failure without logging or counting it. The same failure rule applies when the filter did not declareraw, when the body is shorter than its two 2-octet length fields or a section extends beyond it, and when an earlier member already set a field: a rewrite made from the received body would discard that change. It also applies when a filter answersrawon a pass over a body that differs from the chain's input ("Filter Run Occasions"). teardownon an import route closes the session; on export it is ignored and the action stands.
Filter Run Occasions
An export chain calls a filter once for each route. Two fields of the filter's
declaration add occasions, and both default to false. Stage 1 refuses each one
on an import-only filter. The request does not name the occasion: the same
filter-update message arrives each time.
| Field | When the filter also runs | Which members run | What decides the route |
|---|---|---|---|
readvertise |
A graceful-restart retention re-advertises its stale routes (the stale readvertise rail) | Only the external members that declare it. The route's stale metadata is set |
A route that reaches the end of those members is sent: the chain's final is not read. A raw answer ends the run and the final decides it, so a chain whose final is reject withholds a raw answer where it would send a set answer |
judges-final |
The export chain rewrote the body, by a set or by a raw answer |
Only the external members that declare it, in chain order | The answer of the pass replaces the answer of the chain. A route that reaches the end of the pass is accepted, because the chain's final already decided it. A raw answer, allowed only when the rewritten body equals the chain's input, ends the pass and the final decides it |
A member whose declaration Ze cannot read, because its plugin has gone or no
longer declares the filter, runs on both occasions and fails under
on-error. Whether it opted in is unknown, and it may be the filter that
withholds the route.
The stale readvertise rail. The rail takes its body from what Ze already
sent, so the route has passed the chain once. If the destination's export policy
changed after the route was sent, the policy of that first run no longer
applies. Ze then runs every member that does not declare readvertise, then the
chain's final, then the members that declare it over that result, with raw
holding the body the rail started from.
The pass over a rewritten body. The pass reads raw as the route the chain
received, and every other field from the rewritten body. A filter that declares
raw compares the two to see what the chain took off. The pass may reject,
withdraw or set. A raw answer is refused when the pass runs over a body that
differs from the chain's input, because it would discard the rewrite. The refusal
is a member failure under that filter's on-error. show policy test shows the
pass.
The pass protects a member's answer from a member that does not declare
judges-final. It does not protect that answer from a member that does: the
last one in chain order has the last word.
On the stale rail, a member must declare both fields to run in the pass, unless
the policy changed, in which case every member that declares judges-final
runs. The rail skips the pass when it has one member and that member is the
chain's only judges-final member, because it already ran last.
What repeats. A judges-final filter that ran in the chain runs again on
every rewritten route. A readvertise filter answers again on bytes it already judged when the route was
first sent. A filter that declares both can run more times than that on one
route.
What a filter author makes safe to repeat. The filter MUST answer correctly on a route it already changed:
- A verdict MUST hold on the rewritten body, not only on the body the filter
first saw. Read
rawto see the route before the chain changed it. - A set that adds to the route applies again. A
prependof the AS path in the pass doubles the copies. Compare first, or set a value that the second run leaves as it is. - A side effect in the filter (a counter, a log line, a lookup) happens on each run, so it cannot count routes.
Runtime RPCs (Plugin to Engine)
Plugins call the engine during runtime through these SDK methods:
| Method | SDK method | Input | Output | Purpose |
|---|---|---|---|---|
ze-plugin-engine:update-route |
UpdateRoute, UpdateRouteWithMeta, UpdateRouteSel, UpdateRouteSelWithMeta |
UpdateRouteInput |
UpdateRouteOutput |
Send a route update |
ze-plugin-engine:forward-cached |
ForwardCached |
ForwardCachedInput |
None | Forward cached UPDATEs |
ze-plugin-engine:release-cached |
ReleaseCached |
ReleaseCachedInput |
None | Release cached UPDATEs |
ze-plugin-engine:relay-stored-route |
RelayStoredRoute |
RelayStoredRouteInput |
None | Relay stored routes |
ze-plugin-engine:route-install |
RouteInstall |
RouteInstallInput |
RouteInstallOutput |
Install routes in the Loc-RIB |
ze-plugin-engine:route-remove |
RouteRemove |
RouteRemoveInput |
RouteRemoveOutput |
Remove routes from the Loc-RIB |
ze-plugin-engine:inject-wire-route |
InjectWireRoute |
InjectWireRouteInput |
None | Inject a raw BGP UPDATE |
ze-plugin-engine:batch-validate |
BatchValidate |
BatchValidateInput |
BatchValidateResult |
Submit route validation decisions |
ze-plugin-engine:metrics-publish |
MetricsRegistry, SetMetricsInterval, FlushMetrics |
MetricsPublishInput |
MetricsPublishOutput |
Declare metrics and publish their changes, at the plugin's interval. docs/plugin-development/metrics.md |
ze-plugin-engine:report-issue |
RaiseIssue, ClearIssue |
ReportIssueInput |
None | Raise or clear a problem on the daemon's report bus, where show doctor reads it ("Plugin problems"). docs/architecture/api/process-protocol.md |
ze-plugin-engine:dispatch-command |
DispatchCommand |
DispatchCommandInput |
DispatchCommandOutput |
Dispatch a command string |
ze-plugin-engine:dispatch-command-args |
DispatchCommandArgs |
DispatchCommandArgsInput |
DispatchCommandOutput |
Dispatch a command and pre-tokenized arguments |
ze-plugin-engine:emit-event |
EmitEvent |
EmitEventInput |
EmitEventOutput |
Emit an event |
ze-plugin-engine:subscribe-events |
SubscribeEvents |
SubscribeEventsInput |
None | Subscribe to events |
ze-plugin-engine:unsubscribe-events |
UnsubscribeEvents |
None | None | Unsubscribe from events |
ze-plugin-engine:decode-nlri |
DecodeNLRI |
DecodeNLRIInput |
DecodeNLRIOutput |
Decode NLRI through the registry |
ze-plugin-engine:encode-nlri |
EncodeNLRI |
EncodeNLRIInput |
EncodeNLRIOutput |
Encode NLRI through the registry |
ze-plugin-engine:decode-mp-reach |
DecodeMPReach |
DecodeMPReachInput |
DecodeMPReachOutput |
Decode MP_REACH_NLRI |
ze-plugin-engine:decode-mp-unreach |
DecodeMPUnreach |
DecodeMPUnreachInput |
DecodeMPUnreachOutput |
Decode MP_UNREACH_NLRI |
ze-plugin-engine:decode-update |
DecodeUpdate |
DecodeUpdateInput |
DecodeUpdateOutput |
Decode a BGP UPDATE |
System routing views
Each selected path's ecmp list retains the owning source of every member.
The optional member protocol is a registered name for an owner different from
the primary. Omission means the primary's protocol owns that member. Consumers
resolve supplied names from existing registrations and reject an unknown name.
The authority keeps same-target members with different owners until the
consumer applies each owner's FIB permission, then renders the target group.
Member ownership never changes the primary protocol credited with the prefix.
The system RIB owns the ze-sysrib namespace. Its routing view transfers the
daemon's selected routes as values to either an internal or an external
consumer. The daemon remains the authority for route admission, import policy,
administrative distance and selection.
| Method | SDK method | Input/output types | Available |
|---|---|---|---|
ze-sysrib:route-view-open |
RouteViewOpen |
RouteViewOpenInput / RouteViewOpenOutput |
Stage 2 and runtime |
ze-sysrib:route-view-read |
RouteViewRead |
RouteViewReadInput / RouteViewReadOutput |
Runtime |
ze-sysrib:route-view-candidates |
RouteViewCandidates |
RouteViewCandidatesInput / RouteViewCandidatesOutput |
Runtime |
ze-sysrib:route-view-distances |
RouteViewDistances |
RouteViewDistancesInput / RouteViewDistancesOutput |
Stage 2 and runtime |
ze-sysrib:route-view-publish |
RouteViewPublish |
RouteViewPublishInput / RouteViewPublishOutput |
Runtime |
ze-sysrib:route-view-close |
RouteViewClose |
RouteViewCloseInput / RouteViewCloseOutput |
Runtime |
open accepts an optional reader: selected-feed or local-authority.
An empty input selects selected-feed. The authenticated process generation owns
the returned session token. Subsequent requests carry that token and cannot choose
another plugin's identity. A selected page carries the server epoch, cursor, explicit
snapshot, delta or reset phase, and completion flag. The consumer MUST finish
the initial snapshot before forwarding and MUST discard its projection on reset.
An empty delta preserves the current projection.
An explicit reset can advance the cursor to a newer fenced marker. It clears
readiness and authorizes no forwarding. Older reset cursors remain invalid.
A refused publication does not by itself authorize reopening. For a benign
selected-feed retention reset, a subsequent read on the exact refused session
may return rejected-publication, a positive operation identity. The consumer
MUST require its exact refused operation and validate the complete Reset page
before rebuilding. The proof cannot carry entries, a snapshot or completion.
Omission grants no proof; explicit zero and null are invalid. The daemon
retains one fully validated refused batch, and only its exact operation,
cursor and values can repeat that proof. Malformed attempts, output delivery
errors and foreign or replaced leases cannot acquire it. Internal local readers
do not use selected-feed publication recovery.
local-authority requires an authenticated internal system RIB with direct access
to the daemon's Loc-RIB. It retains no selected snapshot or delta journal.
Its direct reader is ready at logical cursor zero. Distance acknowledgment follows
authoritative reselection and returns zero. Selected reads require reopening with
selected-feed. Both transports provide the same reader choices and refusals.
External system RIBs use selected-feed.
Requests require every mandatory field even when its value is zero. read
requires explicit cursor and wait-ms fields. Candidate reads and publications
also require an explicit cursor. Unknown request fields and null mandatory
fields fail before the session changes. An omitted distance list remains empty.
The complete request must fit rpc.MaxMessageSize, including its method and
correlation ID. rpc.RouteViewRequestBudget reserves the widest ID and the
method header. Direct calls enforce the same bound.
read accepts a record limit from 1 through 4096 and a wait from 0 through
1000 milliseconds. The producer MUST also keep the complete encoded reply within
rpc.MaxMessageSize; rpc.RouteViewResultBudget() reserves framing for the
widest correlation ID. The same bounds apply to Direct calls. A selected path
includes its protocol name and instance, resolved distance, recursive metric and
BGP/AIGP metadata, primary and equal-cost targets, labels, SID and repair target.
Presence flags preserve zero tags and zero AIGP. Protocol IDs local to a process
never cross this boundary.
The selected path requires non-null protocol, instance, distance and
metric fields. Explicit zero ranking values remain valid. A distance row
requires non-null protocol and distance, including an explicit zero distance.
Malformed values leave the current decoded value unchanged.
Candidate scans use their own snapshot and cursor. Their entries preserve the
existing show rib candidates JSON, including hidden paths and a present zero
tag. A candidate scan does not feed selection. distances carries a complete
protocol distance declaration and an ordered operation ID. Its acknowledgment
follows authoritative application and reselection.
publish wraps the unchanged system best-change JSON with the consumed cursor
and operation ID. The consumer MUST retain this operation until acknowledgment.
The owner MUST fence stale generations before emission and return an identical
retry's acknowledgment without emitting twice. A newer completed read preserves
that original acknowledgment. A new operation requires the latest consumed cursor.
Each publication accepts at most 4096 changes. The JSON adapter refuses an excess row before decoding the remaining rows. Device and gateway-zone names must contain valid UTF-8 through both transports.
Publication withdrawals retain an explicit empty protocol field. Device-only
ecmp-paths and backup members retain an explicit empty next-hop and name
their interface. The publication schema accepts these existing event values.
Add and update still require a registered protocol, and each member requires a
gateway or interface. Selected-view addresses keep their nonempty address type.
close fences the session and releases its readers and pinned values before
acknowledgment. Its cleanup withdraws only owned prefixes, in separate family
batches of at most 4096 entries. Every emitted batch retains independent storage.
A failed withdrawal keeps its ledger entries and blocks replacement until retry
succeeds. Fencing releases the retained publication, and successful cleanup
releases the empty ledger.
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 top doc 0: 0: ---------------------------->| head: doc, no envelope,
| | no column names
|-- #43 row 26:{"running":true,"peers":1} -------->| 26 BYTES of payload
|-- #43 end 1 0 0: ------------------------------->| 1 produced, 0 rejected,
| | no message
| |
| REMOVAL: bye |
|<- #99 ze-plugin-callback:bye {"reason":"..."} ---|
|-- #99 ok ---------------------------------------->|
| (plugin exits) |
A daemon stop sends no bye: the engine closes the connection, and the
plugin's Run returns nil (docs/architecture/api/process-protocol.md,
"Shutdown").
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":"..."}. A plugin with no
OnConfigVerify handler accepts at config-verify. A plugin that registered neither
OnConfigApply nor DeclareAppliesNothing answers both with an error naming the
plugin and the roots, so the reload is refused rather than accepted and ignored
(handlers.md, "A plugin with no apply handler").
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.