Documentation

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 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 {"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-registration message 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 main does BEFORE the call runs under a query too. The SDK cannot reach it. Put every side effect inside the start function.
  • Plugin.Run derives wants-validate-open from the callbacks you registered. A query has no Plugin, 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 plugin route 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 OnEvent and 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-policy without 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's on-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's on-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's on-error; the other routes of the batch keep their verdicts. A nonempty error takes 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: answerFilterBatch calls the evaluator OnFilter installed 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 verdict error fails 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 fields member, and raw is sent only to a filter that declared raw.
  • A field Ze cannot read, such as a malformed attribute, is never sent empty: the filter's on-error decides 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-id and cluster-list need bgp-rr, and aigp needs bgp-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. raw is still the received body. A filter that declared no reads fails the route under its on-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 attribute when 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 prefix remove needs only that the filter declares it reads prefix, and a family remove that it reads family. 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 set prefix or family.
  • The as-path, prefix and family entries 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 for ipv4/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 reads is 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 as on-error reject whatever the filter declared. Declare at least one field the filter reads, or raw.
  • The route fails the same way when the answer carries sets beside accept, reject or withdraw.
  • A filter that declares raw among its reads may answer "action":"modify" with a whole-body raw rewrite and no sets. 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's on-error: reject drops the route; accept discards 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 declare raw, 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 answers raw on a pass over a body that differs from the chain's input ("Filter Run Occasions").
  • teardown on 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 raw to see the route before the chain changed it.
  • A set that adds to the route applies again. A prepend of 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.