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 inschema/messages.json, governed by the schema digest, and only those take part in peering admission (fleetmesh_core/identity/identity.pyprotocols_of,compatible). Code cannot mint a fleetmesh protocol:fleetmesh_core/wire/validate.pyregister_protocolrefuses that origin.Any other
https://origin is a dialect.fleetmesh_core/identity/identity.pyforeign_protocols_ofreads 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 controlsexample.orgdecides whatecho/1.0means, and a node that does not speak it ignores the tag.Short names are one namespace at the door.
register_protocolrefuses a foreign protocol whose<name>collides with a fleetmesh protocol or one already registered, sosplit_typecan 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_checkraises 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>throughctx.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 ahandle(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 inctags) and/ordescriptor_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 inevery_command. Do not also writecommand()or acommandsdict - 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 givessidecars.<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),);meshnodereads thepluginsblock of the node directory on its command line (orFLEETMESH_PLUGINS, comma-separated refs, when there is no directory yet), imports those plugins and callsregister_fn(subparsers)for each verb, after the core commands. A verb that names a core command is refused.fleetmesh_node/commands/__init__.pyregister_plugin_cliis 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:
It follows the node with
subscribe(fleetmesh_node/README.md, “The control socket”): one JSON line per bus event, filtered by topic, resumable withsincefrom 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.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.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.
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.