Documentation

Plugin Development

Ze plugins receive events, add configuration and commands, validate or apply configuration changes, implement address families and capabilities, and call the shared command dispatcher. External and in-process plugins use the same five-stage registration model.

Start here

The public Go SDK is pkg/plugin/sdk. An external plugin normally:

Creates an SDK client from the environment supplied by Ze.
Registers callbacks.
Declares subscriptions, commands, schemas, families, or capabilities.
Runs the five-stage startup protocol.
Processes runtime events and commands until shutdown.

package main

import (
    "context"
    "log"

    "github.com/ze-software/ze/pkg/plugin/sdk"
)

func main() {
    plugin, err := sdk.NewFromEnv("example")
    if err != nil {
        log.Fatal(err)
    }
    defer plugin.Close()

    plugin.OnEvent(func(event string) error {
        log.Print(event)
        return nil
    })
    plugin.SetStartupSubscriptions([]string{"update", "state"}, nil, "")

    if err := plugin.Run(context.Background(), sdk.Registration{}); err != nil {
        log.Fatal(err)
    }
}

Ze starts an external plugin with a per-plugin token and TLS certificate fingerprint in ZE_PLUGIN_HUB_* environment variables. sdk.NewFromEnv consumes these values and connects to the engine.

Guide set

Guide	Purpose
Protocol	Five-stage registration, runtime framing, requests, responses, and shutdown
Schemas	Register YANG configuration and constraints
Handlers	Configure, verify, apply, event, and codec callbacks
Commands	Declare commands and return structured results
Testing	SDK harness, functional scenarios, and failure cases
Metrics	Register and expose plugin metrics without a second telemetry path

The plugin operator guide covers loading, dependencies, process bindings, subscriptions, filters, and the built-in catalogue.

Security model

Each external process receives a token bound to its configured plugin name.
The SDK pins the engine certificate when the fingerprint is supplied.
Configuration verification must fail closed on invalid candidate state.
Commands remain subject to the shared dispatcher and authorisation path.
Plugin output must be structured and bounded because it crosses process and operator boundaries.

Development workflow

Implement one registration or callback surface.
Test the callback with the SDK harness.
Add a functional scenario through the normal plugin process manager.
Verify malformed requests and unavailable dependencies.
Run the plugin against a minimal Ze configuration.
Check command discovery, YANG registration, events, shutdown, and reload.

Do not invent a private configuration parser, command transport, or metrics server. Register with the shared engine so the same surface remains available through CLI, web, REST, gRPC, and MCP.