1.7. Extending the Mesh Node

1.7.1. Extending a node: dialects and plugins

Two seams, one rule each. A dialect is a wire protocol someone else minted under their own origin and a node may speak alongside ours. A plugin is a compartment the operator declares in the config that is not in the tree. Both exist so that extending fleetmesh never means forking schema/ or fleetmesh_node/app/core.py, and so that what a node runs is stated in one file an operator reads.

Neither is a sandbox. See “trust” at the end before reaching for a plugin.

1.7.1.1. Dialects: the origin is the namespace

A descriptor (kind 11801) says what a node speaks with c tags holding protocol identifiers of the shape <origin>/<name>/<major>.<minor>:

["c", "https://fleetmesh.org/peering/1.0"]
["c", "https://example.org/echo/1.0"]

The second is a dialect. The rules that make this safe:

  • https://fleetmesh.org/... is ours. Every identifier under it is declared in schema/messages.json, governed by the schema digest, and only those take part in peering admission (fleetmesh_core/identity/identity.py protocols_of, compatible). Code cannot mint a fleetmesh protocol: fleetmesh_core/wire/validate.py register_protocol refuses that origin.

  • Any other https:// origin is a dialect. fleetmesh_core/identity/identity.py foreign_protocols_of reads them off a descriptor; they take no part in admission, need no registry entry here and no digest bump. The origin is the namespace, as in DIDComm: whoever controls example.org decides what echo/1.0 means, and a node that does not speak it ignores the tag.

  • Short names are one namespace at the door. register_protocol refuses a foreign protocol whose <name> collides with a fleetmesh protocol or one already registered, so split_type can keep returning (name, kind) for every message it knows and (None, None) for everything else.

  • A message whose type belongs to no known protocol passes the door unjudged, exactly as before. Register a protocol and its kinds and the door checks shape and refuses unknown kinds; add body checks per kind with register_check. A plugin may add checks; it can never loosen or replace one of ours (register_check raises on an existing key).

fleetmesh_core/wire/validate.py:

name = validate.register_protocol('https://example.org/echo/1.0', ['ping', 'pong'],
                                  checks={'ping': lambda body: None if 'n' in body else 'no n'})
validate.unregister_protocol('https://example.org/echo/1.0')   # tests, or a plugin's stop()

Named profiles (“this node speaks the archive profile”) were considered and set aside: they are a documentation device over a set of c tags and should stay one. Negotiated per-message ext fields were rejected: every pair of versions would need a compatibility matrix the tags already are.

1.7.1.2. Plugins: an out-of-tree compartment, declared in the config

"plugins": [
  {"ref": "fleetmesh_echo.node:EchoPlugin", "after": "budget"},
  "fleetmesh_stats.node:Stats"
],
"extensions": {"echo": {"greeting": "hello"}}

A plugin is a class in an importable module that subclasses fleetmesh_node/compartment/base.py Compartment and makes the same subsystem/1 declaration a core compartment makes (docs/compartments.md): name, requires, optional, reads, from_context, tick, state. At startup fleetmesh_node/app/core.py load_plugins imports each ref, checks it, and splices the class into a copy of MANIFEST right after the compartment after names (default: the end, before updates, which reports on everything before it). Then the assembler builds every compartment, core and plugin alike, from one NodeContext in that order.

The node refuses to start, naming the ref, when a plugin cannot be imported, is not a Compartment, has no name, reuses a compartment’s name, or anchors on a compartment that does not exist. A node would rather not start than start with a plugin it could not load.

What a plugin may do beyond ticking:

  • Read its own block under extensions.<name> through ctx.cfg_of('extensions'). The block is carried as-is and belongs to the plugin; the node’s own config checker never looks inside it.

  • Speak a dialect. Declare piuris = ('https://example.org/echo/1.0',) and a handle(inbound) method and the node registers that prefix on the message router at start. A plugin claiming a fleetmesh.org PIURI is refused.

  • Advertise it. Implement capability_protocols() (returning the PIURIs to put in c tags) and/or descriptor_tags() (extra tags) and the next descriptor the node builds carries them. Sidecars and paid fetch use the same two methods; there is no plugin-specific path.

  • Expose a command. Declare COMMANDS = (Command('show', run='state'), ...) as for any compartment (docs/compartments.md); the base answers it, refuses arguments it does not declare, and lists it in every_command. Do not also write command() or a commands dict - the class is refused.

  • Front a sidecar. Declare sidecars = ({...manifest...}, '@/etc/x.json') and the manifests join the node’s sidecar registry at start, before the first self-test, exactly as a shipped one (docs/sidecars.md): the operator gives sidecars.<name>.endpoint, the node tests it and declares the capability only while the tests pass. A manifest that will not lint, or claims the fleetmesh.org origin, stops the node naming the plugin.

  • Bring CLI verbs. Declare cli = (('verb', register_fn),); meshnode reads the plugins block of the node directory on its command line (or FLEETMESH_PLUGINS, comma-separated refs, when there is no directory yet), imports those plugins and calls register_fn(subparsers) for each verb, after the core commands. A verb that names a core command is refused. fleetmesh_node/commands/__init__.py register_plugin_cli is the hook.

A plugin is a compartment someone else shipped - the rules are the same ones MANIFEST is held to (docs/compartments.md, “One model, four words”). Before an operator lists it, meshnode plugin-check package.module:Class imports the class with no node and holds it to the same rules the node applies at startup - the same functions, so the check cannot drift: the subsystem/1 declaration (name, no collision, requires/uses name real compartments, from_context), dialects and sidecar manifests on their own origin, CLI verbs that collide with nothing. Exit 0 conformant, 1 with each finding on its own line, 2 if the ref will not import. --json for CI.

Step by step, for someone doing it: docs/agents/PLUGIN.md.

fleetmesh_node/tests/test_extensions.py is a complete example: EchoPlugin is loaded through a real import into a real node, reads its block, ticks, is routed and is advertised. The strfry relay bridge (fleetmesh-strfry, fleetmesh_strfry.plugin:StrfryBridgePlugin) is a plugin that lives in its own repo and uses every one of these, the CLI hook included.

1.7.1.3. Trust

A plugin is operator-trusted code imported into the node’s process. It sees everything a core compartment sees, keys included, and a bug in it is a bug in the node. Installing one is the same act of trust as editing fleetmesh_node/app/core.py; the plugins block exists so that act is declared in the config, not hidden in site-packages.

That is the whole model. There is no permission system, no capability list, no sandbox, and a plugin block should never be filled from something a stranger sent. Code you do not trust belongs out of process:

  • a sidecar fronted by the node (docs/sidecars.md): its own process, its own user, reachable over HTTP, gated per-blob by paid fetch, and advertised with a capability tag. GRASP, ncontainer and magpie are all this;

  • a separate node peered with yours, admitted or refused by the ordinary rules.

1.7.1.4. Out-of-process plugins: the contract

An out-of-process plugin is any program on the box that talks to the node’s control socket. That is the whole contract, and it is deliberately nothing new:

  1. It follows the node with subscribe (fleetmesh_node/README.md, “The control socket”): one JSON line per bus event, filtered by topic, resumable with since from the ring the node keeps in memory. A slow reader is told how many envelopes it missed; one that needs every event replays the relays, because the node promises nothing across a restart.

  2. It acts through the same verbs an operator has - pull, terminate, withdraw, <compartment>.<command> - and nothing else. There is no privileged plugin path; whatever the socket refuses to an operator it refuses to a plugin.

  3. It speaks on its own origin. If it carries a protocol of its own it is a dialect (above); the operator advertises it the way a sidecar is advertised, with a capability tag, and the node routes nothing to it - it has its own listener, as magpie and GRASP do.

  4. It is supervised by the host, not the node. systemd (the Ansible role already templates units for sidecars) starts, restarts and journals it. The node spawning children was considered and set aside: it would put the node back in charge of code the whole point of the boundary is to keep it out of.

What the boundary buys: the plugin runs as its own user with no keys, can crash without taking the node down, can be written in any language that can read a line of JSON from a unix socket, and is removed by stopping it. What it costs: it sees only what the wire functions put on the bus - and adding a topic or a field is a change to fleetmesh_node/channels/bus.py WIRE, made in the tree, reviewed like any other.

fleetmesh_node/examples/follower.py is the reference: forty lines that subscribe, print, and ask the node a question when a grant is issued. fleetmesh_node/tests/test_follower.py runs it against a live node.

A WASM ABI for in-process untrusted code was considered and set aside: the compute compartment already runs WASM for workloads, and extending that to node behaviour would recreate the sandbox question the socket boundary already answers.