Registration Protocol

Function blocks are registered with the engine by workers at startup. The registration protocol ensures that schemas are compatible across versions and that function blocks are available for workflow execution.

Registration Flow

sequenceDiagram
    participant Worker
    participant Engine

    Worker->>Engine: POST /workers/register
    Engine->>Worker: worker UUID

    Worker->>Engine: POST /function-blocks/register<br/>{package, name, version, schemas, workerId}
    Engine->>Engine: Validate schema compatibility
    alt New FB or compatible version
        Engine->>Worker: 201 Created
    else Incompatible schema
        Engine->>Worker: 400 Bad Request
    end

Registration Payload

Workers send function block metadata via POST /function-blocks/register:

Field	Required	Description
package	Yes	Namespace
name	Yes	Function block name
majorVersion / minorVersion / patchVersion	Yes	Semantic version
parameterJsonSchema	Yes	JSON Schema for input parameters
resultDataJsonSchema	Yes	JSON Schema for output data
runOn	Yes	Entity type (device, group, interface)
fbType	Yes	Category (facts, configure, check, execute, none)
isPure	Yes	Read-only flag
isIdempotent	Yes	Safe-to-retry flag
workerId	No	Associate this FB with a specific worker
description	No	Human-readable description
markdownHelpText	No	Extended documentation

Schema Compatibility Rules

When registering a new version of an existing function block, the engine enforces compatibility:

Parameter schema (input) -- backward compatible: : New versions must ensure that the set of required parameters in the new version is a subset of (or equal to) the required parameters in the existing version. Adding new optional parameters is always safe. The engine validates compatibility against the exact version (if re-registering), the latest patch version, and the latest minor version of the same major.

Result schema (output) -- forward compatible: : New versions can add fields to results but must not remove existing fields. This ensures that workflows that reference step results still find the expected data.

Immutable properties: : runOn and fbType cannot change across versions of the same function block. These are part of the function block's contract.

Worker Association

Function blocks can be associated with specific workers during registration. This enables:

• Tracking which workers can execute which function blocks
• Job routing -- the blackboard only returns jobs to workers that have registered the matching function block
• Health monitoring -- if a worker goes offline, the engine knows which function blocks are affected

Multiple workers can register the same function block (for horizontal scaling).

Deregistration

When a worker gracefully shuts down (POST /workers/:uuid/unregister), its function block registrations are preserved but unlinked from the worker. The function block definitions remain available for workflow resolution -- only the worker's ability to execute them is removed.

When a function block is deprecated, existing workflows can still reference it, but new workflows should use the latest version.