contract

Documentation

Overview

Package contract contains host/plugin shared types that must stay free of workflow host runtime dependencies.

Index

• Constants
• Variables
• type UIManifest
• type UINavItem

Constants

const (
	// ProtocolVersion is the plugin protocol version.
	// Increment this when making breaking changes to the gRPC interface.
	ProtocolVersion = 1

	// MagicCookieKey is the environment variable used for the handshake.
	MagicCookieKey = "WORKFLOW_PLUGIN"

	// MagicCookieValue is the expected value for the handshake cookie.
	MagicCookieValue = "workflow-external-plugin-v1"
)

Variables

var Handshake = goplugin.HandshakeConfig{
	ProtocolVersion:  ProtocolVersion,
	MagicCookieKey:   MagicCookieKey,
	MagicCookieValue: MagicCookieValue,
}

Handshake is the shared handshake configuration between host and plugins. Both the host client and plugin server must use identical values.

Types

type UIManifest

type UIManifest struct {
	// Name is the plugin identifier. Must match the plugin directory name.
	Name string `json:"name"`
	// Version is the plugin version string (e.g. "1.0.0").
	Version string `json:"version"`
	// Description is a short human-readable description of the plugin.
	Description string `json:"description,omitempty"`
	// NavItems declares navigation entries contributed to the admin UI.
	NavItems []UINavItem `json:"navItems,omitempty"`
	// AssetDir is the subdirectory within the plugin directory that holds
	// static assets. Defaults to "assets" when empty.
	AssetDir string `json:"assetDir,omitempty"`
}

UIManifest describes the UI contribution of a go-plugin UI plugin. Place this as "ui.json" in the plugin directory alongside "plugin.json".

Directory Layout

plugins/
  my-ui-plugin/
    my-ui-plugin  (binary, required for API handlers; optional for asset-only plugins)
    plugin.json   (gRPC plugin manifest; required when binary is present)
    ui.json       (UI manifest: nav items and asset location)
    assets/       (static files: HTML, CSS, JS, images, etc.)
      index.html
      main.js

Asset Versioning

Include a version hash in asset filenames (e.g. main.abc123.js) and reference them from index.html so browsers pick up new files after hot-deploy.

Hot-Reload

After updating assets or ui.json, call:

POST /api/v1/plugins/ui/{name}/reload

This re-reads the manifest and serves the new files without restarting the workflow engine.

Hot-Deploy

Replace the plugin binary and/or assets directory with the new version, then call the reload endpoint above.

type UINavItem

type UINavItem struct {
	// ID is the unique page identifier (e.g. "my-plugin-dashboard").
	ID string `json:"id"`
	// Label is the human-readable navigation label shown in the sidebar.
	Label string `json:"label"`
	// Icon is an emoji or icon token rendered alongside the label.
	Icon string `json:"icon,omitempty"`
	// Category groups navigation entries:
	//   "global"   - always visible top-level entries
	//   "workflow" - shown only when a workflow is open
	//   "plugin"   - plugin-contributed entries (default)
	//   "tools"    - administrative tooling entries
	Category string `json:"category,omitempty"`
	// Order controls the sort position within the category (lower = higher up).
	Order int `json:"order,omitempty"`
	// RequiredRole is the minimum role needed to see this page
	// (e.g. "viewer", "editor", "admin", "operator").
	RequiredRole string `json:"requiredRole,omitempty"`
	// RequiredPermission is a specific permission key required to see this page
	// (e.g. "plugins.manage").
	RequiredPermission string `json:"requiredPermission,omitempty"`
}

UINavItem describes a single entry in the admin UI navigation sidebar.